table of contents
- RUN MODES
- COMMAND LINE OPTIONS
- CACHE SIZE MANAGEMENT
- CACHE COMPRESSION
- CACHE STATISTICS
- HOW CCACHE WORKS
- HANDLING OF NEWLY CREATED HEADER FILES
- CACHE DEBUGGING
- COMPILING IN DIFFERENT DIRECTORIES
- PRECOMPILED HEADERS
- C++ MODULES
- SHARING A CACHE
- SHARING A CACHE ON NFS
- USING CCACHE WITH OTHER COMPILER WRAPPERS
- MORE INFORMATION
ccache - a fast C/C++ compiler cache
ccache [options] ccache compiler [compiler options] compiler [compiler options] (via symbolic link)
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.
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.
The technique of letting ccache masquerade as the compiler works well, but currently doesn’t interact well with other tools that do the same thing. See Using ccache with other compiler wrappers.
Use a symbolic links for masquerading, not hard links.
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.
-d, --directory PATH
-F NUM, --max-files NUM
-M SIZE, --max-size SIZE
-X LEVEL, --recompress LEVEL
-o KEY=VALUE, --set-config KEY=VALUE
Options for scripting or debugging¶
-k KEY, --get-config KEY
When run as a compiler, ccache usually just takes the same command line options as the compiler you are using. The only exception to this is the option --ccache-skip. That option can be used to tell ccache to avoid interpreting the next option in any way and to pass it along to the compiler as-is.
--ccache-skip currently only tells ccache not to interpret the next option as a special compiler option — the option will still be included in the direct mode hash.
The reason this can be important is that ccache does need to parse the command line and determine what is an input filename and what is a compiler option, as it needs the input filename to determine the name of the resulting object file (among other things). The heuristic ccache uses when parsing the command line is that any argument that exists as a file is treated as an input file name. By using --ccache-skip you can force an option to not be treated as an input file name and instead be passed along to the compiler as a command line option.
Another case where --ccache-skip can be useful is if ccache interprets an option specially but shouldn’t, since the option has another meaning for your compiler than what ccache thinks.
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.
Location of the primary configuration file¶
The location of the primary (cache-specific) configuration is determined like this:
Configuration file syntax¶
Configuration files are in a simple “key = value” format, one option per line. Lines starting with a hash sign are comments. Blank lines are ignored, as is whitespace surrounding keys and values. Example:
# Set maximum cache size to 10 GB: max_size = 10G
Some configuration options are boolean values (i.e. truth values). In a configuration file, such values must be set to the string true or false. For the corresponding environment variables, the semantics are a bit different:
Each boolean environment variable also has a negated form starting with CCACHE_NO. For example, CCACHE_COMPRESS can be set to force compression and CCACHE_NOCOMPRESS can be set to force no compression.
Below is a list of available configuration options. The corresponding environment variable name is indicated in parentheses after each configuration option key.
A typical path to use as base_dir is your home directory or another directory that is a parent of your project directories. Don’t use / as the base directory since that will make ccache also rewrite paths to system header files, which typically is contraproductive.
For example, say that Alice’s current working directory is /home/alice/project1/build and that she compiles like this:
ccache gcc -I/usr/include/example -I/home/alice/project2/include -c /home/alice/project1/src/example.c
Here is what ccache will actually execute for different base_dir values:
# 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
If Bob has put project1 and project2 in /home/bob/stuff and both users have set base_dir to /home or /home/$USER, then Bob will get a cache hit (if they share ccache directory) since the actual command line will be identical to that of Alice:
# 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
Without base_dir there will be a cache miss since the absolute paths will differ. With base_dir set to / there will be a cache miss since the relative path to /usr/include/example will be different. With base_dir set to /home/bob/stuff/project1 there will a cache miss since the path to project2 will be a different absolute path.
See also Location of the primary configuration file.
If you want to use another CCACHE_DIR value temporarily for one ccache invocation you can use the -d/--directory command line option instead.
compiler (CCACHE_COMPILER or (deprecated) CCACHE_CC)
a command string
%compiler% -dumpmachine; %compiler% -dumpversion
You should make sure that the specified command is as fast as possible since it will be run once for each ccache invocation.
Identifying the compiler using a command is useful if you want to avoid cache misses when the compiler has been rebuilt but not changed.
Another case is when the compiler (as seen by ccache) actually isn’t the real compiler but another compiler wrapper — in that case, the default mtime method will hash the mtime and size of the other compiler wrapper, which means that ccache won’t be able to detect a compiler upgrade. Using a suitable command to identify the compiler is thus safer, but it’s also slower, so you should consider continue using the mtime method in combination with the prefix_command option if possible. See Using ccache with other compiler wrappers.
compression (CCACHE_COMPRESS or CCACHE_NOCOMPRESS, see Boolean values above)
Compression is done using the Zstandard algorithm. 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.
Compression will be disabled if file cloning (the file_clone option) or hard linking (the hard_link option) is enabled.
Semantics of compression_level:
See the Zstandard documentation for more information.
debug (CCACHE_DEBUG or CCACHE_NODEBUG, see Boolean values above)
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>>_.
depend_mode (CCACHE_DEPEND or CCACHE_NODEPEND, see Boolean values above)
direct_mode (CCACHE_DIRECT or CCACHE_NODIRECT, see Boolean values above)
disable (CCACHE_DISABLE or CCACHE_NODISABLE, see Boolean values above)
file_clone (CCACHE_FILECLONE or CCACHE_NOFILECLONE, see Boolean values above)
Files stored by cloning cannot be compressed, so the cache size will likely be significantly larger if this option is enabled. However, performance may be improved depending on the use case.
Unlike the hard_link option, file_clone is completely safe to use, but not all file systems support the feature. For such file systems, ccache will fall back to use plain copying (or hard links if hard_link is enabled).
hard_link (CCACHE_HARDLINK or CCACHE_NOHARDLINK, see Boolean values above)
Files stored via hard links cannot be compressed, so the cache size will likely be significantly larger if this option is enabled. However, performance may be improved depending on the use case.
Do not enable this option unless you are aware of these caveats:
hash_dir (CCACHE_HASHDIR or CCACHE_NOHASHDIR, see Boolean values above)
The reason for including the CWD in the hash by default is to prevent a problem with the storage of the current working directory in the debug info of an object file, which can lead ccache to return a cached object file that has the working directory in the debug info set incorrectly.
You can disable this option to get cache hits when compiling the same source code in different directories if you don’t mind that CWD in the debug info might be incorrect.
inode_cache (CCACHE_INODECACHE or CCACHE_NOINODECACHE, see Boolean values above)
The feature is still experimental and thus off by default. It is currently not available on Windows.
The feature requires temporary_dir to be located on a local filesystem.
keep_comments_cpp (CCACHE_COMMENTS or CCACHE_NOCOMMENTS, see Boolean values above)
If set to syslog, ccache will log using syslog() instead of to a file. If you use rsyslogd, you can add something like this to /etc/rsyslog.conf or a file in /etc/rsyslog.d:
# log ccache to file :programname, isequal, "ccache" /var/log/ccache # remove from syslog & ~
pch_external_checksum (CCACHE_PCH_EXTSUM or CCACHE_NOPCH_EXTSUM, see Boolean values above)
read_only (CCACHE_READONLY or CCACHE_NOREADONLY, see Boolean values above)
If you are using this because your ccache directory is read-only, you need to set temporary_dir since ccache will fail to create temporary files otherwise. You may also want to set stats to false make ccache not even try to update stats files.
read_only_direct (CCACHE_READONLY_DIRECT or CCACHE_NOREADONLY_DIRECT, see Boolean values above)
recache (CCACHE_RECACHE or CCACHE_NORECACHE, see Boolean values above)
run_second_cpp (CCACHE_CPP2 or CCACHE_NOCPP2, see Boolean values above)
If false, ccache will first run preprocessor to preprocess the source code and then on a cache miss run the compiler on the preprocessed source code instead of the original source code. This makes cache misses slightly faster since the source code only has to be preprocessed once. The downside is that some compilers won’t produce the same result (for instance diagnostics warnings) when compiling preprocessed source code.
A solution to the above mentioned downside is to set run_second_cpp to false and pass -fdirectives-only (for GCC) or -frewrite-includes (for Clang) to the compiler. This will cause the compiler to leave the macros and other preprocessor information, and only process the #include directives. When run in this way, the preprocessor arguments will be passed to the compiler since it still has to do some preprocessing (like macros).
See the discussion under Troubleshooting for more information.
stats (CCACHE_STATS or CCACHE_NOSTATS, see Boolean values above)
In previous versions of ccache, CCACHE_TEMPDIR had to be on the same filesystem as the CCACHE_DIR path, but this requirement has been relaxed.)
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.
Ccache maintains counters for various statistics about the cache, including the size and number of all cached files. In order to improve performance and reduce issues with concurrent ccache invocations, there is one statistics file for each of the sixteen subdirectories in the cache.
After a new compilation result has been written to the cache, ccache will update the size and file number statistics for the subdirectory (one of sixteen) to which the result was written. Then, if the size counter for said subdirectory is greater than max_size / 16 or the file number counter is greater than max_files / 16, automatic cleanup is triggered.
When automatic cleanup is triggered for a subdirectory in the cache, ccache will:
The reason for removing more files than just those needed to not exceed the max limits is that a cleanup is a fairly slow operation, so it would not be a good idea to trigger it often, like after each cache miss.
You can run ccache -c/--cleanup to force cleanup of the whole cache, i.e. all of the sixteen subdirectories. This will recalculate the statistics counters and make sure that the configuration options max_size and max_files are not exceeded. Note that limit_multiple is not taken into account for manual cleanup.
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
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.
ccache -s/--show-stats can show the following statistics:
|autoconf compile/link||Uncachable compilation or linking by an autoconf test.|
|bad compiler arguments||Malformed compiler argument, e.g. missing a value for a compiler option that requires an argument or failure to read a file specified by a compiler option argument.|
|cache file missing||A file was unexpectedly missing from the cache. This only happens in rare situations, e.g. if one ccache instance is about to get a file from the cache while another instance removed the file as part of cache cleanup.|
|cache hit (direct)||A result was successfully found using the direct mode.|
|cache hit (preprocessed)||A result was successfully found using the preprocessor mode.|
|cache miss||No result was found.|
|cache size||Current size of the cache.|
|called for link||The compiler was called for linking, not compiling. Ccache only supports compilation of a single file, i.e. calling the compiler with the -c option to produce a single object file from a single source file.|
|called for preprocessing||The compiler was called for preprocessing, not compiling.|
|can’t use precompiled header||Preconditions for using precompiled headers were not fulfilled.|
|can’t use modules||Preconditions for using C++ modules were not fulfilled.|
|ccache internal error||Unexpected failure, e.g. due to problems reading/writing the cache.|
|cleanups performed||Number of cleanups performed, either implicitly due to the cache size limit being reached or due to explicit ccache -c/--cleanup calls.|
|compile failed||The compilation failed. No result stored in the cache.|
|compiler check failed||A compiler check program specified by compiler_check (CCACHE_COMPILERCHECK) failed.|
|compiler produced empty output||The compiler’s output file (typically an object file) was empty after compilation.|
|compiler produced no output||The compiler’s output file (typically an object file) was missing after compilation.|
|compiler produced stdout||The compiler wrote data to standard output. This is something that compilers normally never do, so ccache is not designed to store such output in the cache.|
|couldn’t find the compiler||The compiler to execute could not be found.|
|error hashing extra file||Failure reading a file specified by extra_files_to_hash (CCACHE_EXTRAFILES).|
|files in cache||Current number of files in the cache.|
|multiple source files||The compiler was called to compile multiple source files in one go. This is not supported by ccache.|
|no input file||No input file was specified to the compiler.|
|output to a non-regular file||The output path specified with -o is not a file (e.g. a directory or a device node).|
|output to stdout||The compiler was instructed to write its output to standard output using -o -. This is not supported by ccache.|
|preprocessor error||Preprocessing the source code using the compiler’s -E option failed.|
|stats updated||When statistics were updated the last time.|
|stats zeroed||When ccache -z was called the last time.|
|unsupported code directive||Code like the assembler .incbin directive was found. This is not supported by ccache.|
|unsupported compiler option||A compiler option not supported by ccache was found.|
|unsupported source language||A source language e.g. specified with -x was unsupported by ccache.|
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.
Common hashed information¶
The following information is always included in the hash:
The preprocessor mode¶
In the preprocessor mode, the hash is formed of the common information and:
Based on the hash, the cached compilation result can be looked up directly in the cache.
The direct mode¶
In the direct mode, the hash is formed of the common information and:
Based on the hash, a data structure called “manifest” is looked up in the cache. The manifest contains:
The current contents of the include files are then hashed and compared to the information in the manifest. If there is a match, ccache knows the result of the compilation. If there is no match, ccache falls back to running the preprocessor. The output from the preprocessor is parsed to find the include files that were read. The paths and hash sums of those include files are then stored in the manifest along with information about the produced compilation result.
There is a catch with the direct mode: header files that were used by the compiler are recorded, but header files that were not used, but would have been used if they existed, are not. So, when ccache checks if a result can be taken from the cache, it currently can’t check if the existence of a new header file should invalidate the result. In practice, the direct mode is safe to use in the absolute majority of cases.
The direct mode will be disabled if any of the following holds:
The depend mode¶
If the depend mode is enabled, ccache will not use the preprocessor at all. The hash used to identify results in the cache will be based on the direct mode hash described above plus information about include files read from the dependency file generated by the compiler with -MD or -MMD.
The depend mode will be disabled if any of the following holds:
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:
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:
|<objectfile>.ccache-input-c||Binary input hashed by both the direct mode and the preprocessor mode.|
|<objectfile>.ccache-input-d||Binary input only hashed by the direct mode.|
|<objectfile>.ccache-input-p||Binary input only hashed by the preprocessor mode.|
|<objectfile>.ccache-input-text||Human-readable combined diffable text version of the three files above.|
|<objectfile>.ccache-log||Log for this 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:
Ccache has support for GCC’s precompiled headers. However, you have to do some things to make it work properly:
If you don’t do this, either the non-precompiled version of the header file will be used (if available) or ccache will fall back to running the real compiler and increase the statistics counter “preprocessor error” (if the non-precompiled header file is not available).
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).
A general tip for getting information about what ccache is doing is to enable debug logging by setting the configuration option debug (or the environment variable CCACHE_DEBUG); see Cache debugging for more information. Another way of keeping track of what is happening is to check the output of ccache -s.
Ccache has been written to perform well out of the box, but sometimes you may have to do some adjustments of how you use the compiler and ccache in order to improve performance.
Since ccache works best when I/O is fast, put the cache directory on a fast storage device if possible. Having lots of free memory so that files in the cache directory stay in the disk cache is also preferable.
A good way of monitoring how well ccache works is to run ccache -s before and after your build and then compare the statistics counters. Here are some common problems and what may be done to increase the hit rate:
Corrupt object files¶
It should be noted that ccache is susceptible to general storage problems. If a bad object file sneaks into the cache for some reason, it will of course stay bad. Some possible reasons for erroneous object files are bad hardware (disk drive, disk controller, memory, etc), buggy drivers or file systems, a bad prefix_command or compiler wrapper. If this happens, the easiest way of fixing it is this:
An alternative is to clear the whole cache with ccache -C if you don’t mind losing other cached results.
There are no reported issues about ccache producing broken object files reproducibly. That doesn’t mean it can’t happen, so if you find a repeatable case, please report it.
Credits, mailing list information, bug reporting instructions, source code, etc, can be found on ccache’s web site: https://ccache.dev.
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.