Skip to content
Skills Library
Programming · Building & coding

zig-cinterop

/zig-cinterop

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.

Licence
Apache-2.0
Last repository change
28.09.2026

Assessment and security

90/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content25 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 28.09.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

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.

Original author 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.

How it works

  1. Contract
  2. Inputs
  3. Procedure
  4. Failure and recovery
  5. Output
Original SKILL.md headings · 57 lines, 935 words
SKILL.md preview
---
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.
Files in this package (2)
  • SKILL.md 6 KB
  • agents/openai.yaml 1 KB

Versions

RepositoryScoreLicence
This page · OutlineDriven/outline-driven-development90Apache-2.0
mohitmishra786/low-level-dev-skills100MIT

Database snapshot: 13.11.2026 · package version 10e0d5a75421 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100zig-017
    Write and port Zig 0.17, including the 0.16 to 0.17 migration and the primitive behind a hand-written type. Use when a Zig 0.16 tree fails to build on 0.17, when porting code across @cImport, array multiplication, or b.args, or when writing new Zig 0.17 code and choosing between std and a new type.
  • 96zig-best-practices
    Use when reading or writing Zig files (.zig, build.zig, build.zig.zon).
  • 95zig
    Implement, debug, review, migrate, and optimize Zig code and build systems. Use when the task requires Zig-specific language or toolchain expertise.
  • 100zig
    Guide for Zig programming language. Use when writing Zig code, setting up Zig projects, migrating between Zig versions, or needing an overview of Zig development workflows.
  • 100zig
    Zig is a systems programming language with compile-time evaluation, seamless C interop, no hidden control flow and no garbage collector. Use when writing, building, testing or cross-compiling Zig code, porting C projects, or fixing code that broke on a new Zig release (std.Io,…
  • 100hashiiiii-zig
    Use when writing, editing, or reviewing Zig implementation, tests, build files, or CI.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.