ccache: Usage, Options & Common CI Errors

ccache caches compiler outputs so unchanged files are not recompiled.

ccache can cut C/C++ CI build times by an order of magnitude - but only if the cache directory is persisted between runs and the compiler is actually routed through it. A misconfigured ccache silently shows a 0% hit rate.

What it does

ccache is a compiler cache. It hashes the preprocessed source, compiler, and flags, and on a match returns the cached object instead of recompiling. It wraps gcc/clang either as a symlink (cc → ccache) or via the launcher integration of CMake/Meson.

Common usage

Terminal

export CCACHE_DIR="$PWD/.ccache"        # persist this in CI cache
ccache --max-size=2G
cmake -S . -B build -DCMAKE_CXX_COMPILER_LAUNCHER=ccache
export CC="ccache gcc" CXX="ccache g++"
ccache -s                              # show stats / hit rate
ccache -z                              # zero the stats counters

Options

Item	What it does
CCACHE_DIR	Where the cache lives (persist in CI)
--max-size / -M	Cap the cache size (e.g. 2G)
-s / --show-stats	Print hit/miss statistics
-z	Zero the statistics
-C / --clear	Empty the entire cache
CMAKE_<LANG>_COMPILER_LAUNCHER	CMake way to route compiles through it

Common errors in CI

The number-one CI symptom is a 0% hit rate. Causes: CCACHE_DIR not restored between runs (cache it explicitly); absolute paths in compile commands differ per run (set CCACHE_BASEDIR or hash_dir=false / CCACHE_NOHASHDIR); a build timestamp in the source (__DATE__/__TIME__ defeat caching); or the compiler not actually routed through ccache (verify with ccache -s showing nonzero "cacheable" calls). A too-small --max-size evicts before reuse - size it to the build.