Zig's Build System Is Becoming a Two-Process Pipeline

Zig’s build system has always been one of the language’s more interesting bets. Instead of making a separate DSL, it lets projects describe builds in Zig itself. That gives build logic the same language, types, imports, and control flow as the rest of the program.

The cost is that zig build has to run user Zig code before it can do anything useful.

Andrew Kelley just landed a large rework that changes how that cost is paid. The short version: zig build is no longer one bloated debug process that both configures and executes the build graph. It is becoming a two-process pipeline.

One process configures. One process makes.

That sounds like an implementation detail, but it changes the shape of the build system in ways that should matter to real Zig projects, especially as --watch, --fuzz, --webui, and third-party tooling keep leaning harder on the build graph.

The Old Shape

Before this change, a project’s build.zig file and the build system implementation were compiled together into a single debug-mode build runner.

That one process did two jobs:

  1. Execute the user’s build.zig logic.
  2. Execute the build graph that the script constructed.

This is simple to understand, but it has a scaling problem. Every time the user’s build logic changes, the build runner drags the build system implementation along with it. As the build system grows more features, the cost of compiling and running that combined process grows too.

That matters more now than it did a few releases ago. zig build is no longer just a convenient command for compiling a binary. It is the front door for tests, fuzzing, watch mode, generated files, package integration, tooling metadata, and increasingly rich developer workflows.

If every small interaction pays for too much build-system machinery in debug mode, the build command becomes the thing that feels slow.

The New Shape

The rework splits the job into two roles.

The first role is the configurer. This is the small process that runs the user’s build.zig file in debug mode. Its job is to construct the build graph.

But instead of directly executing that graph, the configurer serializes it into a binary configuration file. The parent zig build process knows about that file and can cache it.

The second role is the maker. This process consumes the serialized configuration file and executes the build graph. Unlike the old all-in-one debug runner, the maker is compiled with optimizations enabled. It also only needs to be compiled once per Zig version because it can live in the global cache.

So the new model looks like this:

  1. build.zig runs in a small debug-mode configurer.
  2. The configurer writes a serialized build graph.
  3. The parent zig build process caches that graph.
  4. An optimized maker process reads the graph.
  5. The maker executes the steps.

The important part is not just that this is faster once. It creates a better boundary between “figure out what the project wants” and “do the work.”

Why This Is Faster

The Zig devlog gives three motivations.

First, only the user’s build.zig logic needs to be recompiled when that logic changes. The build system implementation does not need to be repeatedly bundled into the same debug runner.

Second, Zig can sometimes avoid rerunning build.zig entirely. If a command-line flag affects the make phase but not the configure phase, the cached serialized configuration can be reused.

The example from the devlog is -freference-trace. Adding that flag should not require the build script to be executed again if the build graph itself has not changed. Under the new architecture, Zig can reuse the previous configuration and send the changed behavior to the make phase.

Third, the process that executes the build graph is optimized. That is a simple but important change. Build execution is ordinary software. If it is doing more work over time, running it as optimized code instead of debug code matters.

The benchmark in the devlog shows why people paid attention. zig build -h dropped from about 150 ms to about 14.3 ms on Andrew’s test, with large reductions in CPU cycles and instructions as well. That particular command benefits dramatically because it can reuse cached configuration instead of rerunning user build logic.

Not every project action will see a 90 percent wall-time improvement. The number to take seriously is not “all builds are now 10x faster.” The useful reading is narrower: the architecture now gives Zig places to skip redundant configure work and places to run repeated make work with optimized code.

That is the kind of improvement that compounds.

The Build Graph Becomes an Artifact

The serialized configuration file may be the most strategically important part of the change.

Once the build graph exists as a concrete artifact, it becomes easier for other tools to understand a project without reimplementing the build runner.

The devlog specifically calls out ZLS, the Zig language server. Today, language tooling often has to approximate a build system’s behavior, ask the build system for fragments of state, or carry its own partial model of the project. That gets fragile when build scripts are programmable.

A serialized build graph gives tools a cleaner target. Instead of guessing what build.zig will do or maintaining a forked understanding of build-runner internals, tooling can consume the same configured graph that the maker sees.

That does not magically solve every editor and package-management problem. Build scripts can still be dynamic. Projects can still depend on host state, environment variables, generated files, discovered programs, and user-selected options.

But it moves Zig toward a healthier interface: configure once, inspect the result, execute from the result.

The Tradeoff: Configure-Time Observation Gets Tighter

The main migration issue most users are likely to hit is passthrough arguments.

Previously, build scripts could inspect b.args and manually forward them into a run step:

if (b.args) |args| {
    run_cmd.addArgs(args);
}

The new pattern is:

run_cmd.addPassthruArgs();

This is not just a rename. It removes a capability. Build scripts can no longer observe those passthrough arguments during the configure phase.

That restriction is the point.

If the configure phase can observe those arguments, then changing the arguments may change the build graph. Zig has to rerun the build script to be correct. If passthrough arguments are handled later as make-phase data, changing them does not necessarily invalidate the configured graph.

This is the core theme of the rework: anything that belongs to graph construction should stay in configure. Anything that only affects execution should move to make.

Some projects will need small build script updates because of that cleaner boundary. The PR also lists other API adjustments, including FmtStep path options moving toward LazyPath lists and several std.Build API changes such as b.build_root becoming b.root.

The devlog frames the change as mostly non-breaking from an API perspective, but “mostly” is doing real work. If your project has clever build logic, this is the moment to test against Zig master before 0.17.0 lands.

Why This Fits Zig’s Direction

This rework also fits a larger pattern in Zig’s recent development.

Zig has been pushing on developer-loop speed from several angles: incremental compilation, watch mode, faster linker paths, richer build output, and better toolchain integration. The May devlog entry about the ELF linker showed incremental rebuilds around the tens-of-milliseconds range in a demo, and the 0.16.0 release notes shipped a large set of build-system and compiler workflow improvements.

The build-system split is another piece of that same story.

Fast rebuilds are not just about compiler internals. They depend on the full path from command invocation to graph construction to dependency checking to compilation to linking to running tests. If the build command itself repeatedly does avoidable work, it can erase wins elsewhere.

A two-process build pipeline helps keep those layers separate.

The configurer can stay friendly to edit-debug cycles because it only compiles user build logic. The maker can stay fast because it is optimized and cached. The serialized graph can become a stable handoff point for tools.

That is a cleaner architecture than making one debug-mode runner carry every responsibility forever.

What Project Maintainers Should Do

If you maintain a Zig project, the practical checklist is simple.

First, try your build on a current development build of Zig if you have time. The Zig team is asking for feedback before the 0.17.0 release window closes.

Second, search your build.zig for b.args. If you are only forwarding command-line arguments into a run step, move to addPassthruArgs(). If you are using those arguments to decide the graph shape, you may need to redesign that boundary.

Third, look for build APIs that depend on values only known during the make phase. The removal of things like LazyPath.basename points in the same direction: configure-time code should not pretend it knows execution-time results.

Fourth, pay attention to tooling. If ZLS and other tools start consuming serialized build configuration, projects with cleaner build graphs should become easier to index and reason about.

Finally, keep the benchmark in perspective. A faster zig build -h is a strong signal that the architecture removed waste. It is not a promise that every compile-heavy build becomes 10x faster. The biggest wins will come where configure work was being repeated unnecessarily or where build execution overhead mattered.

The Bigger Lesson

The interesting part of this change is not that Zig found a micro-optimization. It is that Zig separated two responsibilities that had become too entangled.

Build systems start simple, then they become platforms. They accumulate package discovery, code generation, test orchestration, watch loops, editor integration, fuzzing, cross-compilation, and deployment hooks. If the architecture does not introduce sharper boundaries, every new feature makes every invocation heavier.

Zig’s answer is to make the build graph a first-class handoff:

  • configure the graph with project logic,
  • cache the result,
  • execute it with an optimized maker,
  • let tools inspect the configured state.

That is a good direction for a language that wants its build system to remain programmable without becoming sluggish.

The immediate headline is faster zig build. The deeper story is that Zig is making its build system easier to cache, easier to optimize, and easier for tools to consume.

That is the kind of internal rework users may barely notice when it succeeds. Commands get faster. Watch mode feels lighter. Tooling has less guesswork. Build scripts get a stricter boundary around what belongs to configuration.

For a pre-1.0 language, that is exactly the right time to make the cut.

Sources