A Zig library can manage recipe data while a PHP frontend handles the interface, but the two need a common way to communicate. The C ABI supplies that boundary: rules for exposing functions and data so code built with different languages and compilers can work together. section 5.0 section 5.2 section 5.7
There is no single C ABI for every machine. The relevant rules depend on the operating system and CPU and are designed around C’s simple, stable data representation. Compilers do most of the work of following them; you do not need to be a C expert to use the interface. section 5.2.1
In Zig, make the boundary explicit:
- Declare a C-compatible structure as `extern struct`. Ordinary Zig structs do not have a guaranteed memory layout, while the C ABI requires one. section 5.2.2
- Use `export` for functions that must be available from a library. For C integer parameters and fields, use types such as `c_int` or `c_long`, whose widths can vary by environment. section 5.2.2
- Pass pointers to internal data when the data itself is not ABI-compatible. Use regular functions in place of method syntax; the C ABI does not provide namespaces or methods. section 5.2.2 section 5.3.1
- For a C-compatible callback that need not be exported, specify `callconv(.c)` between the parameters and return type. section 7.3.2
Zig conveniences such as errors and slices do not have a good general translation to the C ABI. At the boundary, choose a simpler representation and document its meaning. For example, a nullable pointer can signal that creation failed. If a type’s compatibility is unclear, try compiling and let the compiler report the problem. section 5.2.2 section 5.4
Listing 5.3 An object without methods
const std = @import("std");
var gpa: std.heap.SafeAllocator(.{}) = .init; #1
var threaded: std.Io.Threaded = .init_single_threaded;
export fn recipes_quit() void {
_ = gpa.deinit(); #2
threaded.deinit();
gpa = .init; #3
threaded = .init_single_threaded;
}
const RecipeBook = struct {}; #4
export fn recipe_book_create() ?*RecipeBook { #5
const ally = gpa.allocator();
const book = ally.create(RecipeBook) catch {
return null; #6
};
book.* = .{}; #7
return book;
}
export fn recipe_book_close(book: *RecipeBook) void { #8
const ally = gpa.allocator();
book.deinit(ally); #9
ally.destroy(book);
}
The recipe library exports create and close functions around a pointer to its internal object. Creation returns null on allocation failure; closing destroys the object. A separate quit function releases library-wide resources. section 5.3.1 section 5.4
Listing 7.5 Error callback
fn glfwErrorCallback(code: c_int, desc: [*c]const u8)
callconv(.c) void { #1
std.debug.print("glfw error {d}: {s}\n", .{ code, desc }); #2
}
pub fn main() !void {
// ... call glfwInit ...
_ = c.glfwSetErrorCallback(&glfwErrorCallback); #3
// ... the rest of the code ...
}
This GLFW error callback uses `callconv(.c)` to match the expected calling convention without exporting the function as a library entry point. section 7.3.2
