Nim C Wrappers

Rules

Architecture

• Use a two-layer design: raw FFI layer (ABI-faithful) + ergonomic Nim layer (safe, idiomatic). Keep the raw layer thin and stable.
• Split modules by library domain. Mirror the C header structure for large libraries.
• Centralize shared types in a lib_raw_types module to avoid cyclic imports.
• Export raw symbols only for advanced users; re-export selected symbols from ergonomic modules.

Raw FFI Layer

• Use importc with cdecl (or stdcall if the library requires it). Prefer {.push callconv: cdecl, importc.} blocks for shared conventions.
• header declares linker-resolved imports; dynlib loads symbols at runtime. Do not combine them on one proc. Guard library names with when defined(windows): etc.
• Never reorder struct fields. Use object in C field order. Add packed only if C headers specify packing.
• Use incompleteStruct and list only needed fields to reduce ABI risk.
• For C enums, use distinct integer types + const values. Do not use Nim enum in raw bindings. Find actual enum values in C headers—do not guess.
• For bitflags, use distinct integer types with bitwise helpers. Do not use set[Enum].
• Map C macros: numeric → const; function-like → template; use inline proc when arguments should evaluate once.
• Keep pointer types as C intends — do not convert them in the raw layer.

Type Mapping

Struct types: object in C order. Fixed arrays: array[N, T]. Pointer+length: ptr T + csize_t. Raw buffers: ptr UncheckedArray[T]. Opaque handles: pointer or ptr OpaqueObj (empty object).

Ergonomic Layer

• In =destroy, explicitly call =destroy on owned nested GC-managed fields (string, seq) after releasing C resources.
• Define ownership hooks in the same module as the type. Cross-module hook definitions are a compile error.
• Raise exceptions (IOError, ValueError, etc.) for C errors — do not return result wrappers that only carry ok/kind/message.
• Do not create custom exception types unless callers handle them differently.
• Catch errors only at translation boundaries (C return code → Nim exception, or exception → domain result). Let exceptions propagate otherwise.

Naming

• In raw bindings, match C identifier names directly.
• importc without an explicit string resolves the C symbol from the Nim name.
• Strip redundant C prefixes (LIB_, foo_) in the ergonomic layer.
• Keep raw constant names in C style (e.g., CURLE_OK).
• When a C identifier collides with a Nim keyword, rename the Nim identifier and use importc: to map to the original C name.

Callbacks

• Declare callbacks as plain C-callable procs such as proc onEvent(code: cint; userData: pointer) {.cdecl.}.
• Pass closure state through userdata via rawProc/rawEnv. See references/callback_pattern.md.

Verification

• Add static: doAssert sizeof(T) == N and offsetOf checks in tests to verify struct layouts.
• Test ABI with compile + link + smoke test + runtime checks.

Workflow

1. Read the C API. Identify structs, enums, functions, callbacks, and ownership semantics.
2. Map types. Use the type table. Verify sizes with static: doAssert sizeof.
3. Write raw bindings. One module per C header or subsystem. Centralize shared raw types to avoid cycles. Use importc, correct calling convention, packed only when C specifies it. Use typed integer aliases for enums.
4. Write ergonomic wrappers. Add destructors for owned resources (move-only or RC). Raise exceptions for C errors. Re-export only the intended public surface. Strip prefixes.
5. Test. Compile check → link check → smoke test → ABI sizeof/offset asserts → runtime ownership tests.
6. Iterate. Add missing APIs as needed. Keep raw layer stable.

Common Mistakes

References

• references/move_only_resource.md — A move-only wrapper for one owner of a C handle.
• references/rc_resource.md — A reference-counted wrapper for shared C resource ownership.
• references/callback_pattern.md — C callbacks with userdata, captured Nim state, and lifetime management.
• references/enum_and_bitflags.md — Distinct-integer wrappers for non-contiguous enums and bitwise flags.
• references/module_layout.md — Separating raw FFI from an ergonomic API in two modules.