Version: next

Build graph — `build.zig`

This file is the single source of truth for how libjzx is built, tested, and packaged via Zig’s build system.

It creates:

A libjzx runtime module that compiles Zig + C together:
- Zig: src/jzx_xev.zig (libxev integration + C ABI wrappers)
- C: src/jzx_runtime.c (runtime core)
- Headers: include/
A static library (libjzx.a) and a shared library (libjzx.dylib/libjzx.so/libjzx.dll).
A Zig module import named jzx (zig/jzx/lib.zig).
Test and example executables.
A stress tool executable.
A formatting step (zig build fmt).

This page explains the build graph in “textbook” style: small snippets with the explanation immediately around them.

Cross-links

Start here: Source index
Previous: Dependency manifest — build.zig.zon
Runtime referenced here:
- Runtime core — src/jzx_runtime.c
- libxev integration — src/jzx_xev.zig
Practical: Installation, Quickstart

Importing Zig’s build API

Source: build.zig#L1

Zig build API entry
const std = @import("std");

std provides std.Build (the build graph builder) and other build-time utilities.

The runtime module factory: `makeRuntimeModule`

The runtime is compiled as a Zig module that includes:

src/jzx_xev.zig as the root Zig source file
src/jzx_runtime.c as an additional C translation unit
include/ on the include path
a dependency import named xev

Source: build.zig#L3-L20

makeRuntimeModule(): create a mixed Zig+C module
fn makeRuntimeModule(
    b: *std.Build,
    target: std.Build.ResolvedTarget,
    optimize: std.builtin.OptimizeMode,
    xev_module: *std.Build.Module,
) *std.Build.Module {
    const module = b.createModule(.{
        .root_source_file = b.path("src/jzx_xev.zig"),
        .target = target,
        .optimize = optimize,
        .link_libc = true,
    });
    module.addImport("xev", xev_module);
    module.addIncludePath(b.path("include"));
    module.addCSourceFile(.{ .file = b.path("src/jzx_runtime.c") });
    module.linkSystemLibrary("pthread", .{});
    return module;
}

Line-by-line intent:

b.createModule(...) creates a build module (roughly: “a compilation unit configuration”).
- .root_source_file: sets the Zig entry point for the module.
- .target: makes the module respect -Dtarget=... (cross compilation).
- .optimize: makes the module respect -Doptimize=... (Debug/ReleaseFast/etc).
- .link_libc = true: enables linking against libc because:
  - src/jzx_runtime.c uses libc (malloc, free, memset, etc).
  - src/jzx_xev.zig uses OS/libc facilities via std/POSIX.
module.addImport("xev", xev_module) makes @import("xev") available inside the runtime module.
- Why it exists: src/jzx_xev.zig needs libxev’s Zig module.
module.addIncludePath(b.path("include")) allows C sources to include headers like #include "jzx/jzx.h".
module.addCSourceFile(...) compiles the C runtime implementation and links it into the module.
module.linkSystemLibrary("pthread", ...) explicitly links pthreads on platforms that require it.
- Why it exists: libxev and/or async primitives may rely on threading primitives.

The build entrypoint: `pub fn build`

Zig calls build(b) as the root of the build graph. Everything else hangs off of this.

Target and optimization options

Source: build.zig#L22-L27

Target/optimize + dependency import
pub fn build(b: *std.Build) void {
    const target = b.standardTargetOptions(.{});
    const optimize = b.standardOptimizeOption(.{});

    const libxev = b.dependency("libxev", .{ .target = target, .optimize = optimize });
    const xev_module = libxev.module("xev");

What’s happening:

standardTargetOptions and standardOptimizeOption wire the common CLI flags into the build:
- zig build -Dtarget=...
- zig build -Doptimize=ReleaseFast (etc)
b.dependency("libxev", ...) requests the dependency declared in build.zig.zon.
- Why it exists: the repo doesn’t assume a system-installed libxev; Zig will fetch/cache it.
libxev.module("xev") retrieves the Zig module exported by libxev so we can import it into our own module.

Building the C/Zig runtime as libraries

This repo builds both:

a static library for embedding
a shared library for dynamic linking / FFI experimentation

Source: build.zig#L29-L44

Static + shared libraries
    const static_module = makeRuntimeModule(b, target, optimize, xev_module);
    const static_lib = b.addLibrary(.{
        .name = "jzx",
        .root_module = static_module,
        .linkage = .static,
    });
    b.installArtifact(static_lib);

    const shared_module = makeRuntimeModule(b, target, optimize, xev_module);
    const shared_lib = b.addLibrary(.{
        .name = "jzx",
        .root_module = shared_module,
        .linkage = .dynamic,
        .version = .{ .major = 0, .minor = 1, .patch = 0 },
    });
    b.installArtifact(shared_lib);

Notes:

Both libraries share the same source set (the runtime module factory).
installArtifact(...) attaches the library to the default install step (so zig build produces it under zig-out/).
The shared library has an explicit version.
- Why it exists: it’s useful metadata for dynamic linking workflows.

Installing public headers

Source: build.zig#L46-L51

Install include/ as headers
    const install_headers = b.addInstallDirectory(.{
        .source_dir = b.path("include"),
        .install_dir = .header,
        .install_subdir = "jzx",
    });
    b.getInstallStep().dependOn(&install_headers.step);

What this does:

Copies include/ into the install prefix under the “header” directory.
The install_subdir = "jzx" means downstream include paths can look like .../include/jzx/....

Why the explicit dependOn:

installArtifact hooks artifacts into the install step automatically.
addInstallDirectory creates a separate step, so we must depend on it to ensure headers are installed too.

Exporting a Zig wrapper module (`@import("jzx")`)

The Zig wrapper (zig/jzx/lib.zig) is exposed as a build module named "jzx".

Source: build.zig#L53-L60

Expose zig/jzx/lib.zig as module 'jzx'
    const jzx_module = b.addModule("jzx", .{
        .root_source_file = b.path("zig/jzx/lib.zig"),
        .target = target,
        .optimize = optimize,
    });
    jzx_module.addIncludePath(b.path("include"));
    jzx_module.linkLibrary(static_lib);
    jzx_module.linkSystemLibrary("pthread", .{});

Why it’s wired this way:

jzx_module.addIncludePath("include") allows the wrapper to import C headers via @cImport.
linkLibrary(static_lib) ensures Zig code that imports jzx automatically links against the runtime.

Tests (`zig build test`)

The test suite is a Zig test artifact built from zig/tests/basic.zig.

Source: build.zig#L62-L72

Test step wiring
    const tests_module = b.createModule(.{
        .root_source_file = b.path("zig/tests/basic.zig"),
        .target = target,
        .optimize = optimize,
        .imports = &.{.{ .name = "jzx", .module = jzx_module }},
    });
    const tests = b.addTest(.{ .root_module = tests_module });

    const test_step = b.step("test", "Run Zig bindings tests");
    const run_tests = b.addRunArtifact(tests);
    test_step.dependOn(&run_tests.step);

The “shape” here is:

create a module with imports = { jzx }
build a test artifact from it
create a named step ("test")
attach a run step so zig build test actually executes the tests

Examples (`zig build examples`)

The examples are installed as executables under zig-out/bin/.

Source: build.zig#L74-L126

Examples step wiring
    const example_module = b.createModule(.{
        .root_source_file = b.path("examples/zig/ping.zig"),
        .target = target,
        .optimize = optimize,
        .imports = &.{.{ .name = "jzx", .module = jzx_module }},
    });
    const zig_example = b.addExecutable(.{
        .name = "zig-example",
        .root_module = example_module,
    });
    b.installArtifact(zig_example);

    const example_step = b.step("examples", "Build example binaries");
    example_step.dependOn(&zig_example.step);

    const sup_module = b.createModule(.{
        .root_source_file = b.path("examples/zig/supervisor.zig"),
        .target = target,
        .optimize = optimize,
        .imports = &.{.{ .name = "jzx", .module = jzx_module }},
    });
    const zig_sup = b.addExecutable(.{
        .name = "zig-supervisor",
        .root_module = sup_module,
    });
    b.installArtifact(zig_sup);
    example_step.dependOn(&zig_sup.step);

    const echo_module = b.createModule(.{
        .root_source_file = b.path("examples/zig/echo_server.zig"),
        .target = target,
        .optimize = optimize,
        .imports = &.{.{ .name = "jzx", .module = jzx_module }},
    });
    const zig_echo = b.addExecutable(.{
        .name = "zig-echo-server",
        .root_module = echo_module,
    });
    b.installArtifact(zig_echo);
    example_step.dependOn(&zig_echo.step);

    const typed_module = b.createModule(.{
        .root_source_file = b.path("examples/zig/typed_actor.zig"),
        .target = target,
        .optimize = optimize,
        .imports = &.{.{ .name = "jzx", .module = jzx_module }},
    });
    const zig_typed = b.addExecutable(.{
        .name = "zig-typed-actor",
        .root_module = typed_module,
    });
    b.installArtifact(zig_typed);
    example_step.dependOn(&zig_typed.step);

Why there’s an explicit examples step:

It provides a discoverable entry point: zig build examples
It acts as a grouping mechanism (build all examples with one command)

Important subtlety:

Each example imports the jzx module, which already links the runtime.
The example_step.dependOn(&exe.step) pattern ensures the build step builds these artifacts even if the default install step isn’t run.

Stress tool (`zig build stress`)

The stress tool is a normal executable wired into a named step.

Source: build.zig#L128-L143

Stress tool step wiring
    const stress_module = b.createModule(.{
        .root_source_file = b.path("tools/stress.zig"),
        .target = target,
        .optimize = optimize,
        .imports = &.{.{ .name = "jzx", .module = jzx_module }},
    });
    const stress_exe = b.addExecutable(.{
        .name = "jzx-stress",
        .root_module = stress_module,
    });
    b.installArtifact(stress_exe);

    const stress_step = b.step("stress", "Run stress tools (smoke)");
    const run_stress = b.addRunArtifact(stress_exe);
    run_stress.addArgs(&.{"--smoke"});
    stress_step.dependOn(&run_stress.step);

The important UX detail is addArgs(&.{"--smoke"}):

zig build stress runs a shorter smoke variant by default to keep CI times reasonable.

Formatting (`zig build fmt`)

The fmt step is a curated list of Zig source files to run zig fmt on.

Source: build.zig#L145-L158

zig fmt step
    const fmt = b.addFmt(.{ .paths = &.{
        "build.zig",
        "src/jzx_xev.zig",
        "zig/jzx/lib.zig",
        "zig/tests/basic.zig",
        "examples/zig/echo_server.zig",
        "examples/zig/ping.zig",
        "examples/zig/supervisor.zig",
        "examples/zig/typed_actor.zig",
        "tools/stress.zig",
    } });
    const fmt_step = b.step("fmt", "Run zig fmt on Zig sources");
    fmt_step.dependOn(&fmt.step);
}

Why the list is explicit (instead of formatting “everything”):

It ensures formatting applies to exactly the sources that should be Zig-formatted.
It avoids formatting vendored dependencies or generated files.

Full listing (for reference)

Source: build.zig#L1-L158

build.zig
const std = @import("std");

fn makeRuntimeModule(
    b: *std.Build,
    target: std.Build.ResolvedTarget,
    optimize: std.builtin.OptimizeMode,
    xev_module: *std.Build.Module,
) *std.Build.Module {
    const module = b.createModule(.{
        .root_source_file = b.path("src/jzx_xev.zig"),
        .target = target,
        .optimize = optimize,
        .link_libc = true,
    });
    module.addImport("xev", xev_module);
    module.addIncludePath(b.path("include"));
    module.addCSourceFile(.{ .file = b.path("src/jzx_runtime.c") });
    module.linkSystemLibrary("pthread", .{});
    return module;
}

pub fn build(b: *std.Build) void {
    const target = b.standardTargetOptions(.{});
    const optimize = b.standardOptimizeOption(.{});

    const libxev = b.dependency("libxev", .{ .target = target, .optimize = optimize });
    const xev_module = libxev.module("xev");

    const static_module = makeRuntimeModule(b, target, optimize, xev_module);
    const static_lib = b.addLibrary(.{
        .name = "jzx",
        .root_module = static_module,
        .linkage = .static,
    });
    b.installArtifact(static_lib);

    const shared_module = makeRuntimeModule(b, target, optimize, xev_module);
    const shared_lib = b.addLibrary(.{
        .name = "jzx",
        .root_module = shared_module,
        .linkage = .dynamic,
        .version = .{ .major = 0, .minor = 1, .patch = 0 },
    });
    b.installArtifact(shared_lib);

    const install_headers = b.addInstallDirectory(.{
        .source_dir = b.path("include"),
        .install_dir = .header,
        .install_subdir = "jzx",
    });
    b.getInstallStep().dependOn(&install_headers.step);

    const jzx_module = b.addModule("jzx", .{
        .root_source_file = b.path("zig/jzx/lib.zig"),
        .target = target,
        .optimize = optimize,
    });
    jzx_module.addIncludePath(b.path("include"));
    jzx_module.linkLibrary(static_lib);
    jzx_module.linkSystemLibrary("pthread", .{});

    const tests_module = b.createModule(.{
        .root_source_file = b.path("zig/tests/basic.zig"),
        .target = target,
        .optimize = optimize,
        .imports = &.{.{ .name = "jzx", .module = jzx_module }},
    });
    const tests = b.addTest(.{ .root_module = tests_module });

    const test_step = b.step("test", "Run Zig bindings tests");
    const run_tests = b.addRunArtifact(tests);
    test_step.dependOn(&run_tests.step);

    const example_module = b.createModule(.{
        .root_source_file = b.path("examples/zig/ping.zig"),
        .target = target,
        .optimize = optimize,
        .imports = &.{.{ .name = "jzx", .module = jzx_module }},
    });
    const zig_example = b.addExecutable(.{
        .name = "zig-example",
        .root_module = example_module,
    });
    b.installArtifact(zig_example);

    const example_step = b.step("examples", "Build example binaries");
    example_step.dependOn(&zig_example.step);

    const sup_module = b.createModule(.{
        .root_source_file = b.path("examples/zig/supervisor.zig"),
        .target = target,
        .optimize = optimize,
        .imports = &.{.{ .name = "jzx", .module = jzx_module }},
    });
    const zig_sup = b.addExecutable(.{
        .name = "zig-supervisor",
        .root_module = sup_module,
    });
    b.installArtifact(zig_sup);
    example_step.dependOn(&zig_sup.step);

    const echo_module = b.createModule(.{
        .root_source_file = b.path("examples/zig/echo_server.zig"),
        .target = target,
        .optimize = optimize,
        .imports = &.{.{ .name = "jzx", .module = jzx_module }},
    });
    const zig_echo = b.addExecutable(.{
        .name = "zig-echo-server",
        .root_module = echo_module,
    });
    b.installArtifact(zig_echo);
    example_step.dependOn(&zig_echo.step);

    const typed_module = b.createModule(.{
        .root_source_file = b.path("examples/zig/typed_actor.zig"),
        .target = target,
        .optimize = optimize,
        .imports = &.{.{ .name = "jzx", .module = jzx_module }},
    });
    const zig_typed = b.addExecutable(.{
        .name = "zig-typed-actor",
        .root_module = typed_module,
    });
    b.installArtifact(zig_typed);
    example_step.dependOn(&zig_typed.step);

    const stress_module = b.createModule(.{
        .root_source_file = b.path("tools/stress.zig"),
        .target = target,
        .optimize = optimize,
        .imports = &.{.{ .name = "jzx", .module = jzx_module }},
    });
    const stress_exe = b.addExecutable(.{
        .name = "jzx-stress",
        .root_module = stress_module,
    });
    b.installArtifact(stress_exe);

    const stress_step = b.step("stress", "Run stress tools (smoke)");
    const run_stress = b.addRunArtifact(stress_exe);
    run_stress.addArgs(&.{"--smoke"});
    stress_step.dependOn(&run_stress.step);

    const fmt = b.addFmt(.{ .paths = &.{
        "build.zig",
        "src/jzx_xev.zig",
        "zig/jzx/lib.zig",
        "zig/tests/basic.zig",
        "examples/zig/echo_server.zig",
        "examples/zig/ping.zig",
        "examples/zig/supervisor.zig",
        "examples/zig/typed_actor.zig",
        "tools/stress.zig",
    } });
    const fmt_step = b.step("fmt", "Run zig fmt on Zig sources");
    fmt_step.dependOn(&fmt.step);
}

Cross-links​

Importing Zig’s build API​

The runtime module factory: makeRuntimeModule​

The build entrypoint: pub fn build​

Target and optimization options​

Building the C/Zig runtime as libraries​

Installing public headers​

Exporting a Zig wrapper module (@import("jzx"))​

Tests (zig build test)​

Examples (zig build examples)​

Stress tool (zig build stress)​

Formatting (zig build fmt)​

Full listing (for reference)​