Nim C Wrappers

Nim C Wrappers

This skill covers the two-layer pattern for wrapping C libraries in Nim: a raw FFI layer for ABI correctness and an ergonomic Nim layer for safety and usability. Larger examples live in references/.

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, header: "foo.h".} blocks for shared conventions.
• Use {.header.} for static linking, {.dynlib.} for dynamic linking. 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 → inline proc or template; sizeof/​side-effect → template.
• 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

• For move-only resources: implement =destroy, =wasMoved, =sink; mark =copy and =dup with {.error.}. Use ensureMove() for ownership transfer.
• For reference-counted resources: use a ptr int counter. =copy/=dup increment, =destroy decrements and frees at zero. Use field-by-field assignment in =dup, not result = src.
• 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

• Strip redundant C prefixes (LIB_, foo_); keep names that disambiguate or match docs.
• Keep raw constant names in C style (e.g., CURLE_OK).
• Rename Nim keywords: type → typ, addr → address, or use importc: to preserve the C name.

Callbacks

• Declare callbacks as plain C-callable procs such as proc onEvent(code: cint; userData: pointer) {.cdecl.}. Do not pass Nim closures to C.
• For callback state, use a global table keyed by userdata. Ensure Nim data is globally rooted or manually managed.

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 — Complete move-only resource wrapper with destructor hooks
• references/​rc_resource.md — Reference-counted (shared ownership) resource wrapper
• references/​callback_pattern.md — C callback pattern using direct pointer casting
• references/​enum_and_bitflags.md — Typed aliases for enums and distinct types for bitflags
• references/​module_layout.md — Shared-types module plus selective ergonomic re-exports

Changelog

• 2026-04-09: Initial verified skill. Added dynlib loading, nested destruction, callback registries, multi-module layout.