Zig: Build System Reworked to Split Configuration from Execution

The Zig project has landed a large change to its build system, separating the process that configures a build from the process that executes it. Andrew Kelley, the language's creator, describes the branch in the project's devlog as a preview of the upcoming release notes and an early notice for people who want to test the change before Zig 0.17.0 ships.

Configurer and maker

Previously, build.zig files and the build system implementation were compiled into a single, bloated process in Debug mode; once the script had constructed a build graph in memory, the build runner executed it. Now the script is compiled into a small process, the configurer, which still runs in Debug mode. When the graph is ready, it is serialized to a binary configuration file that the parent zig build process caches. While that happens, Zig asynchronously compiles the process that runs the graph — the maker — with optimizations enabled. The maker then executes the serialized graph.

Because of the global cache, the maker only has to be compiled once per Zig version. Three goals motivated the split: only the user's build.zig logic is recompiled on each change instead of the whole build system, which matters more now that --watch, --fuzz and --webui exist; the build system can skip rerunning the script entirely when it knows nothing will change; and the graph execution process is built in release mode.

Benchmarks: 150 ms to 14 ms

The measured effect is large. Running zig build -h took a mean of 150 ms before the change and 14.3 ms after — a reduction of about 90.4% in wall time, with CPU cycles down 95.9%, instructions down 95.6% and peak memory down 7.4%. The gain comes from reusing the cached, serialized configuration instead of executing the build script on every invocation.

What breaks and what comes next

Beyond performance, the author expects third-party tooling such as ZLS to benefit from reading the serialized configuration instead of maintaining a fork of the build runner. The change heavily reworks the internals but is mostly non-breaking at the API level, with exceptions listed in the pull request. The most visible one: build scripts can no longer inspect command-line arguments through b.args and instead forward them with run_cmd.addPassthruArgs(), which removes a capability but means such arguments no longer force a rebuild of the script.

Zig 0.17.0 is expected within a couple of weeks, and the author notes there will be room for fixes in 0.17.1 as well.