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


