zig-cinterop
/zig-cinterop
Pomaga przy współpracy Zig z C: @cImport, translate-c, mapowanie typów, struktury extern i packed, export fn, nieprzezroczyste uchwyty oraz mieszane buildy.
- Autor
- OutlineDriven ↗
- Repozytorium
- outline-driven-development ↗
- Licencja
- Apache-2.0
- Ostatnia zmiana repozytorium
- 28.09.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 2
- Skrypty
- 0
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 0
Brak sygnałów. Repozytorium zmienione 28.09.2026, bez odwołań do wycofanych modeli i API.
Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.
Co robi i kiedy
Pomaga przy współpracy Zig z C: @cImport, translate-c, mapowanie typów, struktury extern i packed, export fn, nieprzezroczyste uchwyty oraz mieszane buildy.
Oryginalny opis (EN)
Use when Zig code calls C or C code calls Zig: @cImport, translate-c, C type mapping, extern and packed structs, export fn, opaque handles, or a mixed C and Zig build. Not for Rust FFI: use rust-ffi.
Jak działa
- Contract
- Inputs
- Procedure
- Failure and recovery
- Output
Podgląd SKILL.md
---
name: zig-cinterop
description: 'Use when Zig code calls C or C code calls Zig: @cImport, translate-c, C type mapping, extern and packed structs, export fn, opaque handles, or a mixed C and Zig build. Not for Rust FFI: use rust-ffi.'
---
# Zig C interop
## Contract
| Field | Bound contract |
|---|---|
| Trigger | The user calls a C function from Zig, exposes a Zig function to C, needs a struct that matches a C layout, wants to see how a C header translates, or builds a project that mixes C and Zig sources. |
| Authority | Read-only. The skill emits Zig declarations, `build.zig` lines, and `translate-c` commands to chat; the user writes them. Rollback is not needed. No remote mutation. |
| Side effect | Chat output; `translate-c` output goes where the user redirects it. |
| Done | The declarations and build lines for the request are reported, they compile against libc on the installed Zig in a scratch file, and every C type in the request has its Zig mapping. |
## Inputs
- Zig version from `zig version`: required. The samples ran on Zig 0.14.1.
- The C header or function signatures involved: required.
- Direction: required. C called from Zig, Zig called from C, or both.
- Whether the C code lives in the project or in a system library: required; decides `addCSourceFile` versus `linkSystemLibrary`.
## Procedure
1. Call C from Zig with `@cImport`: `const c = @cImport({ @cInclude("stdio.h"); @cDefine("MY_FEATURE", "1"); @cUndef("SOME_MACRO"); });` then `_ = c.printf("value: %d\n", @as(c_int, 42));`. Variadic C functions such as `printf` work through the import. Single-file builds need `-lc`; in `build.zig` call `exe.linkLibC()` and `exe.addIncludePath(b.path("include"))`. Done when: the call compiles and links against libc.
2. Inspect the translation when a declaration looks wrong: `zig translate-c -lc -I include -DFEATURE=1 mylib.h > mylib.zig`, or with `-target aarch64-linux-gnu` to see another platform's layout. Read the output to learn the generated names and types, then keep using `@cImport` in code; the translated file is a reference, not a source to commit. Done when: the generated declaration for the symbol in question is read.
3. Map C types from the table; `translate-c` output is the authority for anything not listed. Done when: every parameter and return type in the request is mapped.
| C | Zig |
|---|---|
| `int`, `unsigned`, `long`, `unsigned long`, `long long` | `c_int`, `c_uint`, `c_long`, `c_ulong`, `c_longlong` |
| `size_t`, `ssize_t` | `usize`, `isize` |
| `char *` (null-terminated) | `[*:0]u8`; `const char *` is `[*:0]const u8`; generated code shows `[*c]u8` |
| `void *` | `*anyopaque`; nullable `?*anyopaque` |
| `NULL` | `null` |
| `bool` (C99) | `bool` |
| `float`, `double` | `f32`, `f64` |
| `T *` returned from C | `?*T` when it may be null; `[*c]T` in generated code |
Zig string literals are already `[*:0]const u8`. Build a dynamic C string with `std.fmt.bufPrintZ(&buf, "hello {d}", .{42})` on a `[N:0]u8` buffer and pass `.ptr`. Done when: no string crosses the boundary without a terminator.
4. Match C layouts with `extern struct`, which uses the C ABI layout: `const Point = extern struct { x: c_int, y: c_int };`. Match bitfields and wire formats with a backed packed struct: `const Flags = packed struct(u8) { mode: u4, kind: u4 };` and convert with `@bitCast`. Model a forward-declared C type as `const FILE = opaque {};` and declare its functions with `extern fn fopen(path: [*:0]const u8, mode: [*:0]const u8) ?*FILE;`. Done when: each C struct has one Zig counterpart with the same layout rule.
5. Export Zig to C: `export fn zig_add(a: c_int, b: c_int) c_int { return a + b; }` exports the symbol with the C calling convention; a non-exported C-callable function is `pub fn f(x: u32) callconv(.c) u32`; data is `export const VERSION: c_int = 42;`. Write the matching C header by hand with the C types from the table (`int zig_add(int, int); extern int VERSION;`). Done when: the header's prototypes match the exported signatures.
6. Build the mixed project. Zig library consumed by C: build with `b.addLibrary(.{ .linkage = .static, ... })`, then a C executable with `c_exe.addCSourceFile(.{ .file = b.path("src/main.c"), .flags = &.{"-std=c11"} })`, `c_exe.linkLibrary(lib)`, `c_exe.linkLibC()`. C consumed by Zig: `exe.addCSourceFiles`, `exe.addIncludePath`, `exe.linkLibC()`, or `exe.linkSystemLibrary("name")` for an installed library. Details of the build graph: use zig-build-system. Done when: the artifact links.
7. Handle memory across the boundary: memory from C `malloc` is freed with `c.free`; `std.heap.c_allocator` gives Zig code an allocator backed by libc so buffers can cross either way. Model a C pointer that may be `NULL` as an optional and handle it with `orelse`. Done when: every allocation has one owner and every nullable pointer is checked.
8. Confirm with a scratch file compiled by `zig build-exe scratch.zig -lc` and, for exports, inspect the symbol table (use elf-inspection). Done when: the scratch build runs.
## Failure and recovery
| Failure class | Behavior |
|---|---|
| `@cImport` struct has no member `name` | The header that declares it is not included or the macro guard hid it; add the `@cInclude` or `@cDefine`. |
| `translate-c` fails on `size_t` or similar | The header relies on an include it does not pull in; pass `-lc` and add the missing `@cInclude` or `-I`. |
| Calling convention mismatch | Non-exported callbacks passed to C need `callconv(.c)`; the 0.14.1 spelling is lowercase `.c`. |
| Bitfield layout differs from C | Zig packed structs pack from the least significant bit; confirm against the C compiler's layout on the target before relying on it. |
| Build graph question | `build.zig` structure: use zig-build-system. |
## Output
A chat report with the `@cImport` block or `extern` declarations, the type mapping for every signature in the request, the `build.zig` lines that link the pieces, and the scratch-build line confirming they compile on the installed Zig.
Pliki w paczce (2)
- SKILL.md 6 KB
- agents/openai.yaml 1 KB
Wersje
| Repozytorium | Wynik | Licencja |
|---|---|---|
| Ta strona · OutlineDriven/outline-driven-development | 90 | Apache-2.0 |
| mohitmishra786/low-level-dev-skills | 100 | MIT |
Migawka bazy z 13.11.2026 · wersja paczki 10e0d5a75421 (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 100zig-017
Pomaga przenosić kod do Zig 0.17, wraz z migracją z wersji 0.16, oraz tworzyć nowe typy na bazie prymitywów. - 96zig-best-practices
Wspiera czytanie i pisanie plików Zig: .zig, build.zig i build.zig.zon. - 95zig
Implementuje, debuguje, przegląda, migruje i optymalizuje kod w Zig oraz systemy budowania. - 100zig
Prowadzi przez język Zig: pisanie kodu, zakładanie projektów, migracje między wersjami i przegląd przepływów pracy. - 100zig
Wspiera pisanie, budowanie, testowanie i kompilację krzyżową kodu Zig, portowanie projektów C i naprawę kodu po zmianach w nowych wydaniach, z zig init, zig build, comptime i serwerem HTTP na Zig 0.17. - 100hashiiiii-zig
Pomaga pisać, edytować i przeglądać implementację w Zig, testy, pliki budowania i konfigurację CI.