nim-c-wrappers

Files (6)

• SKILL.md
• callback_pattern.md · references/
• enum_and_bitflags.md · references/
• module_layout.md · references/
• move_only_resource.md · references/
• rc_resource.md · references/

SKILL.md (first lines)

# 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.

From Vyrnexis/nim-agent-template, MIT.

More from Vyrnexis/nim-agent-template