liveBook · Manning

Build script

As explained in Systems Programming with Zig

A build script is a program or declarative specification that defines how source code and dependencies are configured and compiled.

A build script automates how source code and dependencies are configured and compiled. In Zig, it is itself a Zig program: it defines modules and connects build steps into a build graph. A step can produce an executable or depend on files generated by earlier steps. section 3.5.1

For a small project, put build.zig at the project root and the entry point at src/main.zig. The script uses a build function rather than main. Its std.Build argument represents the graph and provides functions to create and connect steps. section 3.5.2

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

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

    const mod = b.createModule(.{ #2
        .root_source_file = b.path("src/main.zig"),
        .target = target,
        .optimize = optimize,
    });

    const exe = b.addExecutable(.{ #3
        .name = "cat",
        .root_module = mod,
    });
    b.installArtifact(exe); #4
}

This minimal script creates a module and a cat executable, then attaches the executable to the install step. Run zig build from the project directory to build the default install step. section 3.5.2

The target and optimize options make the same script useful across environments and deployment needs. A target combines operating-system and CPU details. Debug favors iteration and runtime safety; ReleaseFast favors speed, ReleaseSmall binary size, and ReleaseSafe retains runtime safety with limited optimization. section 3.5.2

Compile-time buffer configuration

A cat-style utility can offer configurable reader and writer buffer sizes at compile time: small buffers suit tight space constraints, while large buffers suit throughput-focused workflows. The build script is the place to add the compilation argument. section 3.5 section 3.5.2

As a project grows, the build graph can enforce separation of concerns. A CHIP-8 interpreter can keep its virtual machine, interactive runtime, and tests in separate modules. Linking the runtime’s heavier dependency to its own module keeps it out of the VM and can make tests compile slightly faster. section 6.3.1

Listing 6.3 Making new steps
pub fn build(b: *std.Build) void {
    // ... module code ...

    const tests = b.addTest(.{ #1
        .root_module = test_mod,
    });
    const run_tests = b.addRunArtifact(tests); #2

    const test_cmd = b.step("test", "Run the vm tests"); #3
    test_cmd.dependOn(&run_tests.step); #4
}

A named test step depends on running the test artifact, which in turn requires compiling it. Invoke the chain with zig build test. section 6.3.1

Build scripts can also handle integration work. For GLFW, a translate-c dependency translates a C header into a module, links the glfw3 system library, and makes the result importable by Zig code. section 7.2.1

Listing 7.2 Translating our header
const std = @import("std");
const Translator = @import("translate_c").Translator; #1

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

    const translate_c = b.dependency("translate_c", .{});

    const translator: Translator = .init(translate_c, .{ #2
        .c_source_file = b.path("src/c.h"),
        .target = target,
        .optimize = optimize,
        .link_system_libs = &.{
            .{ .name = "glfw3" }, #3
        },
    });

    const c = translator.mod; #4

    const mod = b.createModule(.{
        .root_source_file = b.path("src/main.zig"),
        .target = target,
        .optimize = optimize,
        .imports = &.{
            .{ .name = "c", .module = c }, #5
        },
    });

    // ... other build stuff ...
}

The translation setup passes the header, target, optimization mode, and system library to the translator, then adds its module to the application’s imports. section 7.2.1

How Systems Programming with Zig covers it

How deep it goes
Builds from a minimal executable script to module dependencies, named test steps, and C header translation.
Examples
Uses a configurable cat utility, a CHIP-8 interpreter with tests, and GLFW header translation.
What you can do after
Apply it via Zig’s build system to create an executable, configure targets, connect modules, and run tests.
How it connects
Connects build graphs with modules, cross-compilation, optimization modes, testing, and C interoperability.

Also explained in

Compare how 3 books explain build script →

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Systems Programming with Zig. The section links point to the parts of the book it draws on.