CheatPress

ccache Compiler cache

Version 4.11.2 · source

ccache, Postcard, light preview Light · Postcard 102 × 152 mm · PDF ccache, Postcard, dark preview Dark · Postcard 102 × 152 mm · PDF ccache, Postcard, ink saver preview Ink saver · Postcard 102 × 152 mm · PDF
ccache, A5, light preview Light · A5 148 × 210 mm · PDF ccache, A5, dark preview Dark · A5 148 × 210 mm · PDF ccache, A5, ink saver preview Ink saver · A5 148 × 210 mm · PDF
ccache, A4, light preview Light · A4 210 × 297 mm · PDF ccache, A4, dark preview Dark · A4 210 × 297 mm · PDF ccache, A4, ink saver preview Ink saver · A4 210 × 297 mm · PDF
ccache, A4 landscape, light preview Light · A4 landscape 297 × 210 mm · PDF ccache, A4 landscape, dark preview Dark · A4 landscape 297 × 210 mm · PDF ccache, A4 landscape, ink saver preview Ink saver · A4 landscape 297 × 210 mm · PDF
ccache, A3, light preview Light · A3 297 × 420 mm · PDF ccache, A3, dark preview Dark · A3 297 × 420 mm · PDF ccache, A3, ink saver preview Ink saver · A3 297 × 420 mm · PDF
ccache, A3 landscape, light preview Light · A3 landscape 420 × 297 mm · PDF ccache, A3 landscape, dark preview Dark · A3 landscape 420 × 297 mm · PDF ccache, A3 landscape, ink saver preview Ink saver · A3 landscape 420 × 297 mm · PDF
ccache, Letter, light preview Light · Letter 8.5 × 11 in · PDF ccache, Letter, dark preview Dark · Letter 8.5 × 11 in · PDF ccache, Letter, ink saver preview Ink saver · Letter 8.5 × 11 in · PDF
ccache, Tabloid, light preview Light · Tabloid 11 × 17 in · PDF ccache, Tabloid, dark preview Dark · Tabloid 11 × 17 in · PDF ccache, Tabloid, ink saver preview Ink saver · Tabloid 11 × 17 in · PDF

Start here

ccache gcc -c <file.c>
Compile through the cache
ccache -s
Show hit and miss statistics
ccache -z
Zero the statistics
ccache -M <size>
Set the cache size limit
ccache -C
Clear the whole cache
ccache -p
Show effective config and origins
CCACHE_DISABLE=1 make
Bypass the cache for one run
CMAKE_C_COMPILER_LAUNCHER
CMake: set to ccache

Concepts

  1. ccache gcc ... hash inputs
  2. Cache hit: copy object
  3. Real compiler store result
Each compile is a lookup keyed by source, flags and compiler
Config precedence (highest first)
Source Example
Command line ccache max_size=1G gcc ...
Environment CCACHE_MAXSIZE=1G
Directory config ccache.conf up the tree
Cache config $CCACHE_DIR/ccache.conf
System config /etc/ccache.conf

Running it

ccache <compiler> <args>
Prefix a compiler command
ln -s $(which ccache) ~/bin/gcc
Masquerade as the compiler
The link directory must come before the real compiler in PATH. Repeat for g++, cc, c++, clang.
make CC='ccache gcc'
Pass the prefix to make
CC="ccache gcc" ./configure
Use it with autotools
CMAKE_C_COMPILER_LAUNCHER
Set to ccache via -D (also CXX)
ccache -V
Print the version
ccache --help
List all options
ccache <KEY>=<value> gcc ...
Set one config option for this call

Statistics

ccache -s
Show summary of hits and misses
ccache -s -v
Show more detailed statistics
ccache -s -vv
Show even more detail
ccache -z
Zero the statistics counters
ccache -x
Show compression statistics
ccache --print-stats
Machine-readable counters
ccache --print-stats --format json
Counters as JSON
ccache --show-log-stats
Counters from the stats log

Cache management

ccache -M <size>
Set maximum cache size (default GiB)
ccache -M 0
Remove the size limit
ccache -F <num>
Set maximum number of files
ccache -c
Clean up to the configured limits
ccache -C
Clear all cached files, keep config
ccache -X <level>
Recompress the cache at a Zstandard level
ccache -X uncompressed
Store the cache uncompressed
ccache --evict-older-than <age>d
Drop entries unused for N days
ccache --evict-namespace <ns>
Drop entries of one namespace
ccache -d <dir> -s
Operate on another cache directory

Configuration

ccache -p
Show effective config and its origin
ccache -k <key>
Print one config value
ccache -o <key>=<value>
Write a config option to the file
ccache --config-path <file>
Use another config file
CCACHE_DIR=<dir>
Cache location
CCACHE_MAXSIZE=<size>
Cache size limit (default 5GiB)
CCACHE_DISABLE=1
Bypass ccache entirely
Any set value counts as true, even an empty one. Use CCACHE_NODISABLE or unset the variable to re-enable.
CCACHE_CONFIGPATH=<file>
Only read this config file
CCACHE_COMPRESS=1
Compress cached files (on by default)
CCACHE_COMPRESSLEVEL=<n>
Zstandard level for new entries
CCACHE_NAMESPACE=<name>
Partition the cache logically
CCACHE_UMASK=<octal>
Permissions for shared caches
CCACHE_STATS=0
Stop counting statistics

Hit rate and correctness

CCACHE_BASEDIR=<dir>
Rewrite absolute paths under dir
Needed when the same source is built from different checkout paths.
CCACHE_SLOPPINESS=<list>
Relax checks to get more hits
CCACHE_SLOPPINESS=time_macros
Ignore __DATE__ and __TIME__
CCACHE_SLOPPINESS=pch_defines
Allow precompiled headers
CCACHE_COMPILERCHECK=content
Hash compiler binary contents
CCACHE_COMPILERCHECK=<command>
Hash the output of a command
CCACHE_NODIRECT=1
Disable direct mode
CCACHE_DEPEND=1
Use depend mode (compiler writes deps)
CCACHE_IGNOREOPTIONS=<opts>
Ignore options when hashing
CCACHE_EXTRAFILES=<files>
Hash extra files into the key
CCACHE_RECACHE=1
Ignore existing results and overwrite
CCACHE_READONLY=1
Read from the cache, do not add
CCACHE_COMMENTS=1
Keep comments when hashing
CCACHE_PATH=<dirs>
Where to find the real compiler

Debugging and sharing

CCACHE_LOGFILE=<file>
Log every decision to a file
CCACHE_DEBUG=1
Write per-object debug files
CCACHE_DEBUGDIR=<dir>
Directory for the debug files
CCACHE_STATSLOG=<file>
Collect per-build statistics
ccache --inspect <file>
Show a result or manifest file
ccache --extract-result <file>
Unpack stored files from a result
ccache --hash-file <file>
Print a BLAKE3 hash of a file
CCACHE_REMOTE_STORAGE=<url>
Add a remote cache backend
CCACHE_REMOTE_ONLY=1
Use only the remote storage
CCACHE_RESHARE=1
Push local hits to remote storage
CCACHE_FILECLONE=1
Use reflinks instead of copies
CCACHE_HARDLINK=1
Hard-link objects from the cache
Shared inodes: editing or touching an object also changes the cached copy.

Recipes

Trial: measure the speedup
ccache -zmake clean && make -j8make clean && make -j8ccache -s   # second build should be mostly hits
Transparent via symlinks
mkdir -p ~/ccbinfor c in gcc g++ cc c++; do ln -sf $(which ccache) ~/ccbin/$c; doneexport PATH=$HOME/ccbin:$PATHgcc --version   # now routed through ccache
CMake project with ccache
L=CMAKE_C_COMPILER_LAUNCHER=ccacheX=CMAKE_CXX_COMPILER_LAUNCHER=ccachecmake -B build -G Ninja -D$L -D$Xcmake --build build && ccache -s
Why is it missing?
export CCACHE_LOGFILE=/tmp/ccache.logmake clean && makegrep -iE 'miss|result' /tmp/ccache.log | headccache -p | grep -E 'sloppiness|base_dir'