FFI & ABI

Stable C ABI since v0.4.0 — manifest, header, and heap string ownership at the boundary.

Stable since v0.4.0

• export fn — unmangled C names; boundary typecheck
• repr(C) on structs at FFI
• Boundary types: i8–i128, u8–u128, isize, usize, f64, bool, string, ptr, void, fn callbacks
• C Bindgen — auto extern fn from .h files
• Stable, versioned C ABI you can link against

arm64-apple repr(C)

On Apple Silicon, small structs (≤8 bytes, e.g. Color) pass as integer registers; larger structs use platform rules: returns >16 bytes use sret (e.g. Image, Texture from raylib), parameters >16 bytes pass as indirect ptr. Required for graphics apps under Apps/Graphics/ and examples/c_raylib/.

Five-step cookbook (inbound FFI)

1. Add a system library: nyra pkg c add raylib — or manual C Bindgen: nyra pkg bind c header.h --lib foo --update-mod
2. Link native libs: automatic via nyra pkg c, or link … in nyra.mod
3. import "vendor/bindings/raylib.ny"
4. Build: nyra run .
5. See examples/c_raylib/, C Bindgen

Outbound (Nyra cdylib)

nyra build lib.ny -o mylib --cdylib — hosts call export fn; free returned string with free. CI: scripts/abi-roundtrip.sh. Examples: examples/ffi/export_greet/, examples/ffi/hello_from_rust/.

Allocator

Strings from export fn, read_file, or strcat are heap-owned. Nyra code: auto-drop at scope end. FFI callers outside Nyra must call free.

Experimental symbols

Volatile MMIO: volatile_* — via import "stdlib/core/mem.ny".

OS / syscalls: os_*, os_syscall6 / asm_* — via import "stdlib/os.ny". macOS battery links IOKit automatically.

Not part of the frozen v0.4.0 boundary contract.

SemVer

0.4.x may add symbols; 1.x may break signatures after RFC. See docs/abi-policy.md.