C Bindgen

Automatic C header → Nyra extern fn bindings via libclang — call SQLite, zlib, OpenSSL, and the rest of the C ecosystem without hand-written FFI.

Quick start

# Easiest — known system libraries (raylib, zlib, sqlite3, sdl2)
nyra pkg c add raylib
nyra pkg c remove raylib
nyra pkg c list

# Advanced — any header path
nyra bind c /path/to/header.h --lib foo --update-mod
nyra pkg bind c vendor/api.h --lib mylib --update-mod

Default output: vendor/bindings/{header-stem}.ny with every bindable function from the header. Use --export SYM only if you want a smaller file; delete unused lines manually anytime.

nyra pkg c — one command per library

The recommended way to add system C libraries to a NyraPkg project. No manual -I paths, no Homebrew keg paths, no hand-editing nyra.mod.

nyrapkg init && cd myapp

nyra pkg c add raylib     # brew install + full bind + nyra.mod
nyra pkg c add zlib
nyra pkg c add sqlite3
nyra pkg c add sdl2

nyra pkg c list           # what's installed in this project
nyra pkg c remove raylib  # delete bindings + unlink nyra.mod

import "vendor/bindings/raylib.ny"

What add does automatically

Built-in catalog

Flags

Manifest (vendor/bindings/c-libs.toml)

# Managed by nyra pkg c add|remove

[raylib]
bindings = "vendor/bindings/raylib.ny"
link = "raylib"
header = "/opt/homebrew/opt/raylib/include/raylib.h"
link_search = ["/opt/homebrew/opt/raylib/lib"]

Re-running nyra pkg c add raylib refreshes bindings. Unknown libraries still work via manual nyra pkg bind c.

Prerequisites

brew install llvm    # libclang for bindgen
nyra toolchain install   # alternative

import "vendor/bindings/zlib.ny"

import "vendor/bindings/zlib.ny"

Why Nyra + C libraries

Nyra targets the same niche as Rust or Go calling native code: your app logic stays in Nyra, mature C libraries do the heavy lifting (compression, crypto, databases, OS APIs). C Bindgen removes hand-written extern fn boilerplate — one command turns a .h file into typed Nyra bindings plus nyra.mod link lines.

Tutorial: zlib

Recommended:

nyrapkg init && cd myapp
nyra pkg c add zlib
nyra run .

import "vendor/bindings/zlib.ny"

fn main() {
    print(zlibVersion())
}

import "vendor/bindings/zlib.ny"

fn main() -> void {
    print(zlibVersion())
}

brew install zlib llvm
nyrapkg init
cd myapp

SDK=$(xcrun --show-sdk-path)

nyra pkg bind c /opt/homebrew/opt/zlib/include/zlib.h --lib z \
  -I /opt/homebrew/opt/zlib/include \
  -I "$SDK/usr/include" \
  -I "$(brew --prefix llvm)/lib/clang/$(ls $(brew --prefix llvm)/lib/clang | tail -1)/include" \
  -o vendor/bindings/zlib.ny

nyra pkg bind c /opt/homebrew/opt/zlib/include/zlib.h --lib z \
  -I /opt/homebrew/opt/zlib/include -I "$SDK/usr/include" \
  --export zlibVersion --stdout

module example.local

link z
link -L /opt/homebrew/opt/zlib/lib

import "vendor/bindings/zlib.ny"

fn main() {
    print("Hello, World!")
    print(zlibVersion())   // e.g. "1.3.2"
}

import "vendor/bindings/zlib.ny"

fn main() -> void {
    print("Hello, World!")
    print(zlibVersion())   // e.g. "1.3.2"
}

nyra run .

Hello, World!
1.3.2

myapp/
  main.ny
  nyra.mod              # link z + link -L …/lib
  vendor/
    bindings/
      zlib.ny           # auto-generated extern fn + repr(C) structs

myapp/
  main.ny
  nyra.mod              # link z + link -L …/lib
  vendor/
    bindings/
      zlib.ny           # auto-generated extern fn + repr(C) structs

Tutorial: SQLite

nyra pkg c add sqlite3

import "vendor/bindings/sqlite3.ny"

fn main() {
    print(sqlite3_libversion())
}

Alternatively: nyrapkg install ny-sqlite@^0.1.0 — see nyrapkg.

Tutorial: Raylib graphics & games 🎮

Raylib — 2D/3D games in C. One command gives you the full API (~556 functions):

nyra pkg c add raylib
import "vendor/bindings/raylib.ny"

Homebrew path pitfalls (/opt/homebrew/include/raylib.h vs keg-only) are handled automatically.

Game loop example

import "vendor/bindings/raylib.ny"

fn main() {
    InitWindow(800, 450, "Nyra + Raylib")
    SetTargetFPS(60)

    let r = 255
    let g = 255
    let b = 255
    let a = 255
    let white = Color { r: r, g: g, b: b, a: a }
    let r2 = 255
    let g2 = 0
    let b2 = 0
    let a2 = 255
    let red = Color { r: r2, g: g2, b: b2, a: a2 }

    while !WindowShouldClose() {
        BeginDrawing()
        ClearBackground(white)
        DrawText("Nyra is Drawing Graphics!", 190, 200, 20, red)
        DrawCircle(400, 300, 50.0, red)
        EndDrawing()
    }

    CloseWindow()
}

import "vendor/bindings/raylib.ny"

fn main() -> void {
    InitWindow(800, 450, "Nyra + Raylib")
    SetTargetFPS(60)

    let r: i32 = 255
    let g: i32 = 255
    let b: i32 = 255
    let a: i32 = 255
    let white = Color { r: r, g: g, b: b, a: a }
    let r2: i32 = 255
    let g2: i32 = 0
    let b2: i32 = 0
    let a2: i32 = 255
    let red = Color { r: r2, g: g2, b: b2, a: a2 }

    while !WindowShouldClose() {
        BeginDrawing()
        ClearBackground(white)
        DrawText("Nyra is Drawing Graphics!", 190, 200, 20, red)
        DrawCircle(400, 300, 50.0, red)
        EndDrawing()
    }

    CloseWindow()
}

Colors: Raylib’s Color uses u8 fields — use let r: u8 = 255 or build via GetColor(hex as u32). Nyra does not parse 0xFF0000FF integer literals yet; use decimal + as u32 or struct fields.

5 — Run

nyra run .

Opens an 800×450 window with text and a red circle at 60 FPS. Runnable example: examples/c_raylib/.

Other simple graphics C libraries

• SDL2 — 2D pixels and input; bind SDL.h with --lib SDL2
• stb_image — single-header PNG load/save; use link-source vendor/stb_image_impl.c

Linux quick reference

# Debian / Ubuntu — install dev packages first
sudo apt install libraylib-dev zlib1g-dev libsqlite3-dev llvm-dev

nyra pkg c add raylib
nyra pkg c add zlib

# Or manual bind
nyra pkg bind c /usr/include/zlib.h --lib z -o vendor/bindings/zlib.ny

Troubleshooting

Your own C code (link-source)

When you write C alongside Nyra (not only a prebuilt system lib):

vendor/
  api.h              # C header
  api_impl.c         # your C implementation
  bindings/api.ny    # from bindgen or hand-written extern fn

# nyra.mod
link-source vendor/api_impl.c

nyra build compiles link-source files to cached .o objects automatically. See examples/c_bindgen/.

What gets generated

• repr(C) structs for C structs with ABI-safe fields (i32, ptr, …)
• extern fn declarations for each bindable C function
• link … lines for nyra.mod (with --update-mod)
• vendor/bindings/shim.c + link-source when a signature needs a simplified wrapper (opaque struct returns, etc.)

Example output

struct Point repr(C) {
    x: i32
    y: i32
}

extern fn make_point(x, y) -> Point
extern fn geom_add(a, b) -> i32

struct Point repr(C) {
    x: i32
    y: i32
}

extern fn make_point(x, y) -> Point
extern fn geom_add(a, b) -> i32

CLI reference

Type mapping (C → Nyra)

Integer mappings use Nyra’s full i8–i128 / u8–u128 families (optional annotations in your code). See Data types.

Performance

• Nyra compiler — unchanged; bindings are just extern fn declarations.
• At run time — each call is a direct native FFI jump; overhead is negligible vs the C library work (e.g. SQLite, zlib).
• Shims — when bindgen emits vendor/bindings/shim.c, one extra C wrapper call for complex signatures only.

C library speed is the library’s own speed — Nyra does not interpret or sandbox it.

Ownership, escape analysis & safety

Nyra’s safety rules apply to your Nyra code at the FFI boundary, not inside third-party C:

See FFI & ABI · Escape analysis · Memory & ownership.

Workflow

1. Vendor or point at the C header (vendor/foo.h).
2. Run nyra pkg bind c vendor/foo.h --lib foo --update-mod.
3. import "vendor/bindings/foo.ny" and call C APIs from Nyra.
4. Re-run bindgen when the upstream header changes.

Example projects

See also

• FFI & ABI — boundary types and repr(C)
• nyrapkg — link and link-source
• Toolchain — nyra cc, nyra toolchain install
• docs/c-bindgen.md in the repository