build-runner

Active contributors: andrewrk, mlugg, alexrp

Purpose

lib/compiler/build_runner.zig (~78 KB) is the program that zig build actually runs. The zig binary compiles the user's build.zig together with this runner and then executes the result. The runner parses the CLI, constructs a std.Build, calls the user's build(b), walks the resulting step graph, and invokes zig recursively to do the work.

How zig build invokes it

1. src/main.zig sees argv[1] == "build".
2. The compiler builds an executable by:
   • Treating lib/compiler/build_runner.zig as the root.
   • Treating the project's build.zig as a module imported by the runner.
   • Resolving build.zig.zon dependencies via src/Package/Fetch.zig.
3. The runner is launched with the user's CLI arguments (everything after zig build).

Responsibilities

• Parse CLI flags: target options, optimize mode, install prefix, --watch, --listen, --summary, -D... user options.
• Construct std.Build: with the resolved host, target, cache directory, and prefix.
• Call build(b) in the user's build.zig. This registers Steps.
• Resolve the requested step. zig build foo runs the step named foo (or install, the default).
• Run the step graph. Walk dependencies, hash inputs through std.Build.Cache, and execute cache misses in parallel via std.Thread.Pool.
• Stream progress via std.Progress and std.Build.WebServer when --listen is set.
• Watch mode delegates to std.Build.Watch and re-runs affected steps on file events.

Integration points

• std.Build (lib/std/Build.zig) — the API the runner exposes to build.zig.
• std.Build.Cache (lib/std/Build/Cache.zig) — content-addressed caching.
• std.Build.Watch (lib/std/Build/Watch.zig) — --watch plumbing.
• std.Build.WebServer (lib/std/Build/WebServer.zig) — --listen HTTP UI.
• std.Build.Fuzz (lib/std/Build/Fuzz.zig) — fuzz-step plumbing.
• src/Package/ — dependency fetching.

Companion: lib/compiler/test_runner.zig

The same pattern applies to zig test: lib/compiler/test_runner.zig (~16 KB) is the program embedded in test executables. Step.Compile for a test artifact links the user's code together with the test runner; running the resulting binary discovers and executes test "..." blocks and reports results.

Key source files

File	Purpose
lib/compiler/build_runner.zig	The runner itself.
lib/compiler/test_runner.zig	The test runner.
lib/compiler/util.zig	Shared utilities for compiler-bundled tools.
lib/compiler/std-docs.zig	Used by zig std (similar pattern).
lib/std/Build.zig and lib/std/Build/*	What the runner orchestrates.

See Build system for the user-facing API and Package manager for how dependencies feed the runner.