ccache [options] ccache compiler [compiler options] compiler [compiler options] (via symbolic link)
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.
To use the first method, just make sure that ccache is in your PATH.
To use the symlinks method, do something like this:
cp ccache /usr/local/bin/ ln -s ccache /usr/local/bin/gcc ln -s ccache /usr/local/bin/g++ ln -s ccache /usr/local/bin/cc ln -s 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.
-d, --directory PATH
-F NUM, --max-files NUM
-M SIZE, --max-size SIZE
-X LEVEL, --recompress LEVEL
-o KEY=VALUE, --set-config KEY=VALUE
-k KEY, --get-config KEY
--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.
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
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.
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.)
Cleanup can be triggered in two different ways: automatic and manual.
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 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.
|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.|
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.
Based on the hash, the cached compilation result can be looked up directly in the cache.
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 will be disabled if any of the following holds:
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:
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:
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:
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).
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.
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.
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.
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).
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:
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.