Zig Cinterop

Zig C interop

Contract

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

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.