AGENT SKILL

nim-c-wrappers

Turn low-level C FFI bindings into an idiomatic Nim API, with safer types, cleaner module boundaries, resource management, callbacks, enums, bitflags, and exception-based error handling. Use when building a high-level Nim wrapper around a C library or improving the usability of existing raw bindings.

License 许可
MIT
最近更新
2026-10-27
Stars
★ 5
Forks
2

01 前言 Front Matter

name
nim-c-wrappers
description
Turn low-level C FFI bindings into an idiomatic Nim API, with safer types, cleaner module boundaries, resource management, callbacks, enums, bitflags, and exception-based error handling. Use when building a high-level Nim wrapper around a C library or improving the usability of existing raw bindings.

02 资源文件 5

03 SKILL.md 正文

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

C Type Nim Type Notes
char cchar Platform-dependent signedness
signed char cschar Always int8
unsigned char uint8 Safer default spelling; avoid relying on cuchar status across Nim versions
short cshort Always int16
unsigned short cushort Always uint16
int cint Always int32
unsigned int cuint Always uint32
long clong ABI-sized (4 on Win64, 8 on LP64)
unsigned long culong ABI-sized
long long clonglong Always int64
unsigned long long culonglong Always uint64
size_t csize_t Alias for uint
intptr_t int Pointer-sized signed
uintptr_t uint Pointer-sized unsigned
float cfloat Always float32
double cdouble Always float64
long double clongdouble Limited codegen support
void* pointer Untyped
T* ptr T Nullable
T** ptr ptr T
char* / const char* cstring NUL-terminated
char** cstringArray ptr UncheckedArray[cstring]

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

Mistake Why it's wrong
Passing Nim string directly to char* parameter Type mismatch; use .cstring
Using seq where C expects stable pointer add() can reallocate, invalidating the pointer
Reordering struct fields Breaks ABI layout, causes garbage values
Using Nim enum for C enum values ABI incompatibility; use typed integer aliases
Adding enum or constant values without inspecting headers Find actual enum values in C headers, do not guess
Passing closures as C callbacks C expects plain function pointers, not GC closures
Storing cstring beyond the call cstring from string.cstring dangles after the source is freed
=dup body using result = src in RC pattern May trigger implicit =copy instead of =dup; use field-by-field assignment
Wrong calling convention Causes crashes at call sites

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.

04 同仓库更多 Skills

Vyrnexis
Vyrnexis/nim-agent-template

run-tests

Runs the project unit tests and validation suites.

★ 5
Vyrnexis
Vyrnexis/nim-agent-template

nimonyplugins

Build and debug Nimony compile-time plugins for code generation and DSL rewrites. Use when replacing Nim macros with Nimony plugins, writing or reviewing template, for-loop, module, type, or import plugins, or diagnosing NIF traversal and generated output.

★ 5
Vyrnexis
Vyrnexis/nim-agent-template

nim-testing

Write and run deterministic Nim tests, including isolated test files, expected-exception checks, multi-configuration builds, and sanitizer integration. Use when setting up a Nim test suite, testing failure behavior, running tests across debug/release/danger modes, or adding AddressSanitizer support.

★ 5
Vyrnexis
Vyrnexis/nim-agent-template

nim-style-guide

Write clear, consistent Nim code in a simple stdlib-aligned style, covering imports, naming, proc vs func vs template choices, local variables, constructors, formatting, and control flow. Use when writing new Nim code or reviewing a Nim module for readability, consistency, and low-noise style decisions.

★ 5
Vyrnexis
Vyrnexis/nim-agent-template

nim-ownership-hooks

Implement and review Nim ARC/ORC ownership hooks for types that manually manage resources, including move-only, deep-copy, refcounted, and copy-on-write patterns. Use when a Nim type owns pointers, buffers, file descriptors, or custom heap memory and you need correct `=destroy`, `=copy`, `=dup`, `=sink`, or move semantics.

★ 5
Vyrnexis
Vyrnexis/nim-agent-template

nim-mcp-tools

Use for Nim symbol navigation, diagnostics, and type resolution. MANDATORY: Use specialized MCP tools (nimFindSymbols, nimFindReferences, nimListSymbols, nimCheckFile, nimCheckProject, nimFindTypeDefinition) first; fall back to grep only on error or user confirmation.

★ 5