graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs
0212. Build time is analysis-bound: keep the default backend, filter test builds
Status: accepted 2026-09-28
Context
A cold zig build of graff takes about 16 s and a cold zig build test-bin
about 44 s (Zig 0.17.0-dev.813, Debug, Apple silicon). The question was
whether redundant files were inflating that, and what could make it faster.
An audit of the import graph from every root in build.zig:
- 825
.zigfiles. 649 (8.6 MB) are reachable from the shipped binaries; 175 (2.0 MB) only fromtestblocks; none from nothing.src/shell_identity_probe.ziglooks unreferenced from Zig but is built on its own byscripts/eval-tier1.sh. - No two files have identical content. No single file is outsized.
- The spec JSON under
spec/kernels/(1.1 MB) is embedded only into the unit test binary.libgraffand the wasm core are opt-in steps, not part of the default install. - Six
*_test.zig/*_tests.zigfiles are imported at the top level of normal code. Zig analyzes only what is referenced andtestblocks only in test builds, so the binary pays for parsing them and nothing else.
Measurements, each cold (fresh local cache) and run one at a time:
| Build | Time |
|---|---|
graff, default backend |
16 s |
graff, analysis only (-fno-emit-bin) |
17 s |
graff, -fllvm |
36 s |
| No-op rebuild | 0.2 s |
test-bin, all tests |
44 s |
test-bin, one -Dtest-filter |
13 s |
Analysis-only takes as long as the full build: semantic analysis of the code actually used is the whole cost, and it runs on one core. Code generation and linking with the default backend are nearly free.
Tried and rejected:
-fllvm: twice as slow in Debug.-fincremental: its state does not persist across separatezig buildinvocations, so each edit still re-analyzes everything. Underzig build --watch -fincremental, a comment edit took 15 s to rebuild and a one-function change 70 s: slower than a cold build.-fno-llvm -fno-lld(self-hosted backend without lld): did not converge; see the second decision below.
Decision
- Keep the default backend for Debug builds. Do not add
-fllvm,-fincremental, or-fno-llvm -fno-lldtobuild.zigor scripts. - No file removal: there is no dead weight to cut. Size is not the lever; analyzed code is.
- While iterating, build unit tests with
-Dtest-filter=<name>(about 3x faster).test-binonly compiles; run the resulting test binary to execute the filtered tests. Leave the full suite to the pre-push hook and CI. - Run build-time experiments one at a time, never in parallel, and watch memory.
The self-hosted backend without lld is not a supported build path
While measuring cold-build variants, a Debug build of graff with
-fno-llvm -fno-lld did not converge: its memory grew without bound past
100 GB until the host stopped responding. The default and -fllvm builds of
the same tree peak around 1.7 GB.
- Build graff only with the default backend (or
-fllvmwhere a release step needs it). Do not pass-fno-llvm/-fno-lldinbuild.zig, scripts, CI, or build-time measurements. - Run cold-build measurements one at a time, never in parallel. A variant that dies or is killed is recorded as a failure, not retried.
Consequences
A cold build stays around 16 s and each edit re-analyzes the whole binary.
Faster iteration comes from filtered test builds, not from build flags.
Build-time comparisons cover only the backends graff actually builds with.
Revisit when a Zig upgrade makes -fincremental persist across invocations,
or makes --watch rebuilds faster than cold ones. Revisit the self-hosted
backend when upstream Zig can build graff within normal memory limits, and
re-test it in isolation, under an external memory limit, before it goes back
into any measurement.