A caching problem with 0.17

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.

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.

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.