NAME

ccache - a fast C/C++ compiler cache

SYNOPSIS

ccache [options]
ccache compiler [compiler options]
compiler [compiler options]                   (via symbolic link)

DESCRIPTION

Ccache is a compiler cache. It speeds up recompilation by caching the result of previous compilations and detecting when the same compilation is being done again.

Ccache has been carefully written to always produce exactly the same compiler output that you would get without the cache. The only way you should be able to tell that you are using ccache is the speed. Currently known exceptions to this goal are listed under CAVEATS. If you discover an undocumented case where ccache changes the output of your compiler, please let us know.

RUN MODES

There are two ways to use ccache. You can either prefix your compilation commands with ccache or you can let ccache masquerade as the compiler by creating a symbolic link (named as the compiler) to ccache. The first method is most convenient if you just want to try out ccache or wish to use it for some specific projects. The second method is most useful for when you wish to use ccache for all your compilations.

To use the second method on a Debian system, it’s easiest to just prepend /usr/lib/ccache to your PATH. /usr/lib/ccache contains symlinks for all compilers currently installed as Debian packages.

Alternatively, you can create any symlinks you like yourself like this:

ln -s /usr/bin/ccache /usr/local/bin/gcc
ln -s /usr/bin/ccache /usr/local/bin/g++
ln -s /usr/bin/ccache /usr/local/bin/cc
ln -s /usr/bin/ccache /usr/local/bin/c++

And so forth. This will work as long as the directory with symlinks comes before the path to the compiler (which is usually in /usr/bin). After installing you may wish to run “which gcc” to make sure that the correct link is being used.

COMMAND LINE OPTIONS

These command line options only apply when you invoke ccache as “ccache”. When invoked as a compiler (via a symlink as described in the previous section), the normal compiler options apply and you should refer to the compiler’s documentation.

CONFIGURATION

ccache’s default behavior can be overridden by options in configuration files, which in turn can be overridden by environment variables with names starting with CCACHE_. Ccache normally reads configuration from two files: first a system-level configuration file and secondly a cache-specific configuration file. The priorities of configuration options are as follows (where 1 is highest):

As a special case, if the the environment variable CCACHE_CONFIGPATH is set it specifies the primary configuration file and the secondary (system-wide) configuration file won’t be read.

# Set maximum cache size to 10 GB:
max_size = 10G

ccache gcc -I/usr/include/example -I/home/alice/project2/include -c /home/alice/project1/src/example.c

# Current working directory: /home/alice/project1/build
# With base_dir = /:
gcc -I../../../../usr/include/example -I../../project2/include -c ../src/example.c
# With base_dir = /home or /home/alice:
gcc -I/usr/include/example -I../../project2/include -c ../src/example.c
# With base_dir = /home/alice/project1 or /home/alice/project1/src:
gcc -I/usr/include/example -I/home/alice/project2/include -c ../src/example.c

# Current working directory: /home/bob/stuff/project1/build
# With base_dir = /home or /home/bob:
gcc -I/usr/include/example -I../../project2/include -c ../src/example.c

%compiler% -v

%compiler% -dumpmachine; %compiler% -dumpversion

For example, if *debug_dir* is set to `/example`, the current working
directory is `/home/user` and the object file is `build/output.o` then the
debug log will be written to `/example/home/user/build/output.o.ccache-log`.
See also _<<_cache_debugging,Cache debugging>>_.

# log ccache to file
:programname, isequal, "ccache"         /var/log/ccache
# remove from syslog
& ~

CACHE SIZE MANAGEMENT

By default, ccache has a 5 GB limit on the total size of files in the cache and no limit on the number of files. You can set different limits using the command line options -M/--max-size and -F/--max-files. Use ccache -s/--show-stats to see the cache size and the currently configured limits (in addition to other various statistics).

Cleanup can be triggered in two different ways: automatic and manual.

CACHE COMPRESSION

Ccache will by default compress all data it puts into the cache using the compression algorithm Zstandard (zstd) using compression level 1. The algorithm is fast enough that there should be little reason to turn off compression to gain performance. One exception is if the cache is located on a compressed file system, in which case the compression performed by ccache of course is redundant. See the documentation for the configuration options compression and compression_level for more information.

You can use the command line option -x/--show-compression to print information related to compression. Example:

Total data:              14.8 GB (16.0 GB disk blocks)
Compressed data:         11.3 GB (30.6% of original size)


  - Original data:       36.9 GB


  - Compression ratio:  3.267 x  (69.4% space savings)
Incompressible data:      3.5 GB

Notes:

The cache data can also be recompressed to another compression level (or made uncompressed) with the command line option -X/--recompress. If you choose to disable compression by default or to use a low compression level, you can (re)compress newly cached data with a higher compression level after the build or at another time when there are more CPU cycles available, for instance every night. Full recompression potentially takes a lot of time, but only files that are currently compressed with a different level than the target level will be recompressed.

CACHE STATISTICS

ccache -s/--show-stats can show the following statistics:

HOW CCACHE WORKS

The basic idea is to detect when you are compiling exactly the same code a second time and reuse the previously produced output. The detection is done by hashing different kinds of information that should be unique for the compilation and then using the hash sum to identify the cached output. Ccache uses BLAKE3, a very fast cryptographic hash algorithm, for the hashing. On a cache hit, ccache is able to supply all of the correct compiler outputs (including all warnings, dependency file, etc) from the cache. Data stored in the cache is checksummed with XXH3, an extremely fast non-cryptographic algorithm, to detect corruption.

Ccache has two ways of gathering information used to look up results in the cache:

The direct mode is generally faster since running the preprocessor has some overhead.

If no previous result is detected (i.e., there is a cache miss) using the direct mode, ccache will fall back to the preprocessor mode unless the depend mode is enabled. In the depend mode, ccache never runs the preprocessor, not even on cache misses. Read more in The depend mode below.

HANDLING OF NEWLY CREATED HEADER FILES

If modification time (mtime) or status change time (ctime) of one of the include files is the same second as the time compilation is being done, ccache disables the direct mode (or, in the case of a precompiled header, disables caching completely). This done as a safety measure to avoid a race condition (see below).

To be able to use a newly created header files in direct mode (or use a newly precompiled header), either:

For reference, the race condition mentioned above consists of these events:

CACHE DEBUGGING

To find out what information ccache actually is hashing, you can enable the debug mode via the configuration option debug or by setting CCACHE_DEBUG in the environment. This can be useful if you are investigating why you don’t get cache hits. Note that performance will be reduced slightly.

When the debug mode is enabled, ccache will create up to five additional files next to the object file:

If config_dir (environment variable CCACHE_DEBUGDIR) is set, the files above will be written to that directory with full absolute paths instead of next to the object file.

In the direct mode, ccache uses the 160 bit BLAKE3 hash of the ccache-input-c + ccache-input-d data (where + means concatenation), while the ccache-input-c + ccache-input-p data is used in the preprocessor mode.

The ccache-input-text file is a combined text version of the three binary input files. It has three sections (“COMMON”, “DIRECT MODE” and “PREPROCESSOR MODE”), which is turn contain annotations that say what kind of data comes next.

To debug why you don’t get an expected cache hit for an object file, you can do something like this:

COMPILING IN DIFFERENT DIRECTORIES

Some information included in the hash that identifies a unique compilation can contain absolute paths:

This means that if you compile the same code in different locations, you can’t share compilation results between the different build directories since you get cache misses because of the absolute build directory paths that are part of the hash.

Here’s what can be done to enable cache hits between different build directories:

PRECOMPILED HEADERS

Ccache has support for GCC’s precompiled headers. However, you have to do some things to make it work properly:

C++ MODULES

Ccache has support for Clang’s -fmodules option. In practice ccache only additionally hashes module.modulemap files; it does not know how Clang handles its cached binary form of modules so those are ignored. This should not matter in practice: as long as everything else (including module.modulemap files) is the same the cached result should work. Still, you must set sloppiness to modules to allow caching.

You must use both direct mode and depend mode. When using the preprocessor mode Clang does not provide enough information to allow hashing of module.modulemap files.

SHARING A CACHE

A group of developers can increase the cache hit rate by sharing a cache directory. To share a cache without unpleasant side effects, the following conditions should to be met:

find $CCACHE_DIR -type d | xargs chmod g+s

The reason to avoid the hard link mode is that the hard links cause unwanted side effects, as all links to a cached file share the file’s modification timestamp. This results in false dependencies to be triggered by timestamp-based build systems whenever another user links to an existing file. Typically, users will see that their libraries and binaries are relinked without reason.

You may also want to make sure that a base directory is set appropriately, as discussed in a previous section.

SHARING A CACHE ON NFS

It is possible to put the cache directory on an NFS filesystem (or similar filesystems), but keep in mind that:

A tip is to set temporary_dir to a directory on the local host to avoid NFS traffic for temporary files.

It is recommended to use the same operating system version when using a shared cache. If operating system versions are different then system include files will likely be different and there will be few or no cache hits between the systems. One way of improving cache hit rate in that case is to set sloppiness to system_headers to ignore system headers.

USING CCACHE WITH OTHER COMPILER WRAPPERS

The recommended way of combining ccache with another compiler wrapper (such as “distcc”) is by letting ccache execute the compiler wrapper. This is accomplished by defining prefix_command, for example by setting the environment variable CCACHE_PREFIX to the name of the wrapper (e.g. distcc). Ccache will then prefix the command line with the specified command when running the compiler. To specify several prefix commands, set prefix_command to a colon-separated list of commands.

Unless you set compiler_check to a suitable command (see the description of that configuration option), it is not recommended to use the form ccache anotherwrapper compiler args as the compilation command. It’s also not recommended to use the masquerading technique for the other compiler wrapper. The reason is that by default, ccache will in both cases hash the mtime and size of the other wrapper instead of the real compiler, which means that:

Another minor thing is that if prefix_command is used, ccache will not invoke the other wrapper when running the preprocessor, which increases performance. You can use prefix_command_cpp if you also want to invoke the other wrapper when doing preprocessing (normally by adding -E).

CAVEATS

TROUBLESHOOTING

MORE INFORMATION

Credits, mailing list information, bug reporting instructions, source code, etc, can be found on ccache’s web site: https://ccache.dev.

AUTHOR

Ccache was originally written by Andrew Tridgell and is currently developed and maintained by Joel Rosdahl. See AUTHORS.txt or AUTHORS.html and https://ccache.dev/credits.html for a list of contributors.