Kache hashes the inputs that can change compiler output and normalizes machine-local paths that should not. Missing a real input risks a wrong hit; retaining harmless machine identity causes avoidable misses.

Rust key inputs

The exact set depends on the invocation. It can include:

• rustc identity and target
• linker identity for outputs that invoke linking
• crate name, crate types, edition, cfg values, and features
• source and included file contents discovered through dep-info
• code-generation flags, rustflags, and requested emit kinds
• the contents of --extern dependencies
• compile-time environment values rustc reports
• native libc identity for host-loaded Linux outputs
• configured salt, extra inputs, and declared environment inputs

Incremental directory names and harmless local path spellings are excluded or normalized.

The live implementation is the authority. Use kache why-miss and trace logging to see the components for a particular build.

Path normalization

Kache maps known roots to stable sentinels before hashing and asks the compiler to emit matching remapped paths. This allows equivalent worktrees and runners to share entries.

Common mappings include the workspace, Cargo home, Rustup home, temporary directory, target directory, and configured base directories. Add a missing root with KACHE_BASE_DIR or paths.base_dirs.

Do not choose an overly broad base directory. Normalization deliberately merges path identities; two genuinely different inputs must not map to the same sentinel.

Disable Rust path normalization for a local profiling or debugging session:

KACHE_RUSTC_PATH_NORMALIZE=0 cargo build

That puts real paths in debug information and makes the key local to those path identities. C/C++ has the corresponding KACHE_CC_PATH_NORMALIZE=0 control.

Coverage-instrumented Rust builds use real paths and a separate, path-local key namespace so coverage tools can find source files.

Debugger source maps

On macOS and Windows, map the stable workspace prefix back to your checkout:

set substitute-path /kache/workspace /absolute/path/to/checkout

settings set target.source-map /kache/workspace /absolute/path/to/checkout

Linux workspace paths use /proc/self/cwd when possible, so running the debugger from the workspace root usually resolves them directly.

Inputs the compiler does not report

Use these controls only for a real hidden input:

• cache.key_salt or KACHE_KEY_SALT for an opaque toolchain boundary
• crate kache.toml for files read during compilation but absent from dep-info
• workspace.extra_inputs for workspace-root provider inputs
• cache.key_env_vars for environment read by proc macros through std::env
• cache.path_only_env_vars for locator variables proven not to affect emitted bytes

See Configuration for syntax and safety limits.

Explain a miss

kache why-miss my_crate

The command compares recent key material for that crate and prints changed groups. For individual components, run the trace command it suggests, typically:

KACHE_LOG=trace cargo build -p my_crate 2>&1 | grep '\[key:my_crate\]'

Warnings also identify residual absolute paths that survive normalization.