Kache caches conservative, single-source C and C++ object compilations. If it cannot prove that an invocation is safe to cache, it runs the real compiler unchanged.

Set up the wrapper

For build systems that honor CC and CXX:

export CC="kache cc"
export CXX="kache c++"

The Rust cc crate also needs to know that kache is a wrapper:

export CC_KNOWN_WRAPPER_CUSTOM=kache

For build systems that call compiler names directly, install shims on Unix:

kache install-shims ~/.local/lib/kache/shims
export PATH="$HOME/.local/lib/kache/shims:$PATH"

Kache creates cc, c++, gcc, g++, clang, and clang++ symlinks. Keep the real compilers later in PATH; Kache skips paths that resolve back to itself.

For clang-cl driver mode:

$env:CC = "kache clang-cl"

Cached invocations

Supported shapes compile one source into one object:

cc -c src/foo.c -o build/foo.o
c++ -c src/foo.cpp -o build/foo.o
clang-cl /c foo.c /Fofoo.obj

The key includes preprocessor output, compiler identity, modeled code-generation options, and normalized paths. Header changes therefore invalidate the entry.

Kache recognizes GCC, Clang, Apple Clang, clang-cl, versioned names such as gcc-13, and target-prefixed compiler names. It can probe other wrapper names to identify the underlying compiler family.

Portability

GCC and Clang entries can be reused across worktrees when source and build paths normalize cleanly. Set KACHE_BASE_DIR when the automatic roots do not cover a container mount or out-of-tree layout:

KACHE_BASE_DIR="$PWD" cmake --build build

clang-cl debug objects remain machine-local because CodeView records paths that clang-cl does not remap.

Passthroughs

Kache currently passes through:

• link and whole-program steps
• multi-source or multi-architecture invocations
• response files
• precompiled headers and modules
• coverage and split-DWARF builds
• flags it has not classified

C/C++ entries are local-only. Remote sync currently handles Rust entries.

Inspect passthrough reasons in the monitor or logs:

kache monitor
KACHE_LOG=kache=debug make

You can opt a known-safe flag into the local model:

[cc]
extra_allowlist_flags = ["-ffunction-sections"]

Kache folds the spelling into the key. Do not allow flags whose meaning depends on the host, such as -march=native.