[Yaraslaut]

A second checkout of this repository on the same machine recompiled 359 of its 1017 units, and a second machine whose user has a different home directory recompiled 1145 of 1155. Every one of those misses was silent: the build succeeded, it simply was not shared. This branch makes both share, and makes any project that maps __FILE__ itself (Catch2 does) share across checkouts at all.

Measured on this repository (clang-release on the host, gcc-release in two Docker containers with different users, homes and checkout paths, all against one fastcached):

Second build	Before	After
Same machine, another folder	658 / 1017 hits	996 / 1017 hits (514 s → 23 s)
Another machine, CPM cache in its own home	10 / 1155 hits	1128 / 1155 hits (584 s → 36 s)

A further rebuild on the first machine with FASTCACHE_VERIFY=1 (every hit recompiled and compared) found no differing object among 1134 hits. On Catch2 v3.6.0 alone, a second folder went from 0 / 107 to 107 / 107 hits, each served object byte-identical to that folder's uncached compile.

Changes

• The test targets' checkout paths leave the command line. FastCacheTest and fastcache-compile-node-tests passed FASTCACHED_SOURCE_DIR/FASTCACHED_TESTDATA_DIR as target-wide definitions, which put an absolute path into the key of all 382 of their units. They now come from a generated <tests/CheckoutPaths.hpp>, included by the 20 cases that read a file out of the checkout.
• -ffile-prefix-map and -fmacro-prefix-map are keyed portably (PathValueRole::SourcePrefixMap). They reached the key verbatim, absolute root included. The head is relativized and the replacement kept literal, as for -fdebug-prefix-map. The flag stays on the preprocess line, because it rewrites the __FILE__ the key hashes. Where the build tree sits under the source root is folded into the key whenever such a map is present.
• A dependency cache outside the checkout is a root of its own: <DEPROOT>, PathCanon::Layout::dependencyRoot, FASTCACHE_DEPS_DIR, which the CMake module fills from CPM_SOURCE_CACHE.
  • The key tokenizes it, and its headers count as content in the dependency set and the manifest.
  • An object naming it is bound to the machine (CheckoutPart::DependencyRoot).
  • The launcher tokenizes it in a value's text regions before the STORE, and a hit localizes it against its own root. Servers canonicalize with the two roots their frame carries, so their behaviour and CompileValueVersion do not move.
  • objkey-v8 / manifest-v9 keep the generations apart.
• This repository maps __FILE__ for the checkout and the dependency cache, under fastcache-cc only (_fc_source_prefix_map_rules, checked by debug-prefix-map-rules). Before this, every Catch2 test object named its checkout and was stored per checkout.
• -fmacro-prefix-map travels to a worker verbatim. It is a RemoteLine::Forwarded column, asked ahead of the role's refusal. The worker's allowlist gains an ArgValue::PrefixMapRule kind for a rule whose halves are paths it never opens. -ffile-prefix-map, which also rewrites debug records, still keeps the compile local.
• Rules (compile-cache.md, AGENT.md tripwires) and the launcher, node and distributed-compilation docs describe all of the above.

Not covered

• The 20 checkout-reading test units compile the checkout path in on purpose and stay bound to it.
• Sources that sit outside the CMake source directory (lz4 here, zstd's build/cmake layout) still miss across machines. CMake embeds their absolute path in the object path, -MT and -MF, and the replayed depfile's target has to match.
• Debug records of objects built from dependency sources still name the producing machine's cache. A dispatched compile carries one debug mapping pair, so a third rule would make local and dispatched objects differ in their debug records.
• A failed STORE is still logged as MISS. Found while measuring; not touched here.

🤖 Generated with Claude Code

https://claude.ai/code/session_01CnCkwgtUsaSM5HcgB3APNU

[christianparpart]

approved while it's hot. Mind, I gonna cut a new release by tomorrow night, such that we hae a new one by Monday morning!