A caching problem with 0.17

A Zig 0.17 caching bug causes stale executables when a C project's header changes after a library-only relink, according to a forum report from a developer building a JUCE C++ project on an M2 Mac running Tahoe 26.6.2. The report states that when Zig relinks without compiling sources it rewrites the build step's cache note with source files only and no headers, so a later header change is reported as "cached" and the old binary persists until .zig-cache is deleted. The developer published a minimal reproduction in /tmp/zig-header-bug and could not file a bug report due to Zig's no-AI bug report policy.

Hi, I use zig to build a c++ JUCE project on a Mac M2 Silicon running Tahoe 26.6.2 and recently updated to Zig 0.17. Today I had the following problem: I build the project but the executable didn’t get updated. After some research, Claude claimed that the problem lies in Zig. I am not so proficient in Zig to judge for myself if the problem was indeed in Zig and I cannot send a bug report due to the no AI bug report policy, which is fine. Because I benefit greatly from using Zig daily, I still wanted to provide some feedback, so I chose this forum. I asked for a minimal project that can recreate the problem, it is here. The problem was real, I am unsure about the cause. Kind regards. Zig keeps two kinds of cache notes for a C program: main.c and value.h . This note is correct. cached and does no work. It never opens the per-file notes. The bug is in the second note. Sometimes zig must redo a step without compiling any of its sources, for example when a library it links has changed, so it only re-links. Zig then rewrites the step’s note with the source files only, and no headers. The header list comes from compiling, and nothing was compiled. After that, the step’s note no longer mentions value.h . When value.h changes, zig checks the note, sees no listed file changed, reports cached , and keeps the old binary. The binary stays stale on every later build until .zig-cache is deleted. | File | What it does | |---|---| | value.h | Defines VALUE | | main.c | Includes value.h and prints VALUE | | other.c | A static library with one function that returns a number. main.c prints its result too. | | build.zig | Builds the library and an executable that links it | It creates the project in /tmp/zig-header-bug and runs two cases. It touches nothing outside /tmp . d=/tmp/zig-header-bug rm -rf "$d" mkdir -p "$d" cd "$d" || exit 1 cat build.zig <<'EOF' const std = @import "std" ; pub fn build b: std.Build void { const target = b.standardTargetOptions .{} ; const optimize = b.standardOptimizeOption .{} ; const lib mod = b.createModule .{ .target = target, .optimize = optimize, .link libc = true } ; lib mod.addCSourceFile .{ .file = b.path "other.c" } ; const lib = b.addLibrary .{ .name = "other", .root module = lib mod, .linkage = .static } ; const exe mod = b.createModule .{ .target = target, .optimize = optimize, .link libc = true } ; exe mod.addCSourceFile .{ .file = b.path "main.c" } ; exe mod.linkLibrary lib ; const exe = b.addExecutable .{ .name = "repro", .root module = exe mod } ; b.installArtifact exe ; } EOF cat main.c <<'EOF' include <stdio.h include "value.h" int other void ; int main void { printf "header=%d library=%d\n", VALUE, other ; return 0; } EOF setHeader { printf ' define VALUE %s\n' "$1" value.h; } setLib { printf 'int other void { return %s; }\n' "$1" other.c; } run { sleep 1 zig build --summary all 2 &1 | grep -E 'compile exe repro|error' printf ' output: ' ./zig-out/bin/repro } echo "zig $ zig version " echo '=== CONTROL: header change only ===' rm -rf .zig-cache zig-out setHeader 1; setLib 1 echo '-- first build expect header=1 library=1 '; run setHeader 2 echo '-- header 1 - 2 expect header=2 library=1 '; run echo '=== BUG: library change, then header change ===' rm -rf .zig-cache zig-out setHeader 1; setLib 1 echo '-- first build expect header=1 library=1 '; run setLib 2 echo '-- library 1 - 2, program only re-linked expect header=1 library=2 '; run setHeader 2 echo '-- header 1 - 2 expect header=2 library=2 '; run echo '-- the same build again, nothing changed expect header=2 library=2 '; run 2 &1 | tee /tmp/zig-header-bug.txt to the last line, and press Return. /tmp/zig-header-bug.txt . The sleep 1 before each build keeps file times clearly apart, so the result cannot be a timing effect. The same steps by hand, in the project folder: zig build , then ./zig-out/bin/repro . It prints header=1 library=1 . other.c to return 2, and build again. Zig re-links only, and the program prints header=1 library=2 . define VALUE 2 , and build again. Zig reports header=1 . | Step | Expected | Actual | |---|---|---| | Control: change the header only | Recompile, header=2 | Recompile, header=2 correct | | Bug: change the library | Re-link, header=1 library=2 | Re-link, header=1 library=2 correct | | Bug: then change the header | Recompile, header=2 library=2 | cached , header=1 library=2 | | Bug: build again, no change | header=2 library=2 | cached , header=1 library=2 | zig 0.17.0 === CONTROL: header change only === -- first build expect header=1 library=1 +- compile exe repro debug native success 125ms MaxRSS:54M output: header=1 library=1 -- header 1 - 2 expect header=2 library=1 +- compile exe repro debug native success 133ms MaxRSS:54M output: header=2 library=1 === BUG: library change, then header change === -- first build expect header=1 library=1 +- compile exe repro debug native success 118ms MaxRSS:54M output: header=1 library=1 -- library 1 - 2, program only re-linked expect header=1 library=2 +- compile exe repro debug native success 81ms MaxRSS:49M output: header=1 library=2 -- header 1 - 2 expect header=2 library=2 +- compile exe repro debug native cached 62ms MaxRSS:30M output: header=1 library=2 -- the same build again, nothing changed expect header=2 library=2 +- compile exe repro debug native cached 62ms MaxRSS:30M output: header=1 library=2 The build reports success and the output looks fine, but it is built from old headers. In a real project, the common trigger is a change in a linked library while the program’s own sources stay the same. A later header change then ships silently as old code. .zig-cache before a build that must be correct.