table of contents
- NAME
- SYNOPSIS
- DESCRIPTION
- RUN MODES
- COMMAND LINE OPTIONS
- CONFIGURATION
- SECONDARY STORAGE BACKENDS
- 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
- CAVEATS
- TROUBLESHOOTING
- MORE INFORMATION
- AUTHOR
CCACHE(1) | CCACHE(1) |
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 first method, just make sure that ccache is in your PATH.
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.
Warning
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.
Warning
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.
Common options¶
-c, --cleanup
-C, --clear
--config-path PATH
-d, --dir PATH
--evict-namespace NAMESPACE
--evict-older-than AGE
-h, --help
-F NUM, --max-files NUM
-M SIZE, --max-size SIZE
-X LEVEL, --recompress LEVEL
-o KEY=VALUE, --set-config KEY=VALUE
-x, --show-compression
-p, --show-config
--show-log-stats
-s, --show-stats
-v, --verbose
-V, --version
-z, --zero-stats
Options for secondary storage¶
--trim-dir PATH
Warning
Don’t use this option to trim the primary cache. To trim
the primary
cache directory to a certain size, use CCACHE_MAXSIZE=SIZE
ccache -c.
--trim-max-size SIZE
--trim-method METHOD
atime
mtime
Options for scripting or debugging¶
--checksum-file PATH
--extract-result PATH
-k KEY, --get-config KEY
--hash-file PATH
--inspect PATH
--print-stats
Extra options¶
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.
Note
--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.
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.
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
Boolean values¶
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.
Configuration options¶
Below is a list of available configuration options. The corresponding environment variable name is indicated in parentheses after each configuration option key.
absolute_paths_in_stderr (CCACHE_ABSSTDERR)
base_dir (CCACHE_BASEDIR)
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.
Warning
Rewriting absolute paths to relative is kind of a brittle hack. It
works OK in many cases, but there might be cases where things break. One known
issue is that absolute paths are not reproduced in dependency files, which
can mess up dependency detection in tools like Make and Ninja. If possible,
use relative paths in the first place instead instead of using
base_dir.
cache_dir (CCACHE_DIR)
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/--dir command line option instead.
compiler (CCACHE_COMPILER or (deprecated) CCACHE_CC)
compiler_check (CCACHE_COMPILERCHECK)
content
mtime
none
string:value
a command string
%compiler% -v
%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.
compiler_type (CCACHE_COMPILERTYPE)
auto
clang
clang-cl
gcc
msvc
nvcc
other
pump
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.
compression_level (CCACHE_COMPRESSLEVEL)
Semantics of compression_level:
> 0
< 0
0 (default)
See the Zstandard documentation <http://zstd.net> for more information.
cpp_extension (CCACHE_EXTENSION)
debug (CCACHE_DEBUG or CCACHE_NODEBUG, see Boolean values above)
debug_dir (CCACHE_DEBUGDIR)
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.
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)
extra_files_to_hash (CCACHE_EXTRAFILES)
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.
Warning
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.
ignore_headers_in_manifest (CCACHE_IGNOREHEADERS)
ignore_options (CCACHE_IGNOREOPTIONS)
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)
limit_multiple (CCACHE_LIMIT_MULTIPLE)
log_file (CCACHE_LOGFILE)
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 & ~
max_files (CCACHE_MAXFILES)
max_size (CCACHE_MAXSIZE)
namespace (CCACHE_NAMESPACE)
For instance, if you use the same primary cache for several disparate projects, you can use a unique namespace string for each one. This allows you to remove cache entries that belong to a certain project if you stop working with that project.
path (CCACHE_PATH)
pch_external_checksum (CCACHE_PCH_EXTSUM or CCACHE_NOPCH_EXTSUM, see Boolean values above)
prefix_command (CCACHE_PREFIX)
prefix_command_cpp (CCACHE_PREFIX_CPP)
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)
reshare (CCACHE_RESHARE or CCACHE_NORESHARE, 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).
This option is ignored with MSVC, as there is no way to make it compile without preprocessing first.
secondary_storage (CCACHE_SECONDARY_STORAGE)
Examples:
sloppiness (CCACHE_SLOPPINESS)
clang_index_store
file_stat_matches
file_stat_matches_ctime
gcno_cwd
include_file_ctime
include_file_mtime
ivfsoverlay
locale
pch_defines
modules
system_headers
time_macros
See the discussion under TROUBLESHOOTING for more information.
stats (CCACHE_STATS or CCACHE_NOSTATS, see Boolean values above)
stats_log (CCACHE_STATSLOG)
Note
Lines in the stats log starting with a hash sign (#) are comments.
temporary_dir (CCACHE_TEMPDIR)
Note
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.
umask (CCACHE_UMASK)
SECONDARY STORAGE BACKENDS¶
The secondary_storage option lets you configure ccache to use one or several other storage backends in addition to the primary cache storage located in cache_dir. Note that cache statistics counters will still be kept in the primary cache directory — secondary storage backends only store cache results and manifests.
A secondary storage backend is specified with a URL, optionally followed by a pipe (|) and a pipe-separated list of attributes. An attribute is key=value or just key as a short form of key=true. Attribute values must be percent-encoded <https://en.wikipedia.org/wiki/Percent-encoding> if they contain percent, pipe or space characters.
Attributes for all backends¶
These optional attributes are available for all secondary storage backends:
Examples:
Storage interaction¶
The table below describes the interaction between primary and secondary storage on cache hits and misses:
Primary storage | Secondary storage | What happens |
miss | miss | Compile, write to primary, write to secondary[1] |
miss | hit | Read from secondary, write to primary[2] |
hit | - | Read from primary, don’t write to secondary[3] |
[1] Unless secondary storage has attribute read-only=true.
[2] Unless secondary storage has attribute share-hits=false.
[3] Unless primary storage is set to share its cache hits with the
reshare option.
File storage backend¶
URL format: file:DIRECTORY or file://DIRECTORY
This backend stores data as separate files in a directory structure below DIRECTORY (an absolute path), similar (but not identical) to the primary cache storage. A typical use case for this backend would be sharing a cache on an NFS directory.
Important
ccache will not perform any cleanup of the storage — that
has to be
done by other means, for instance by running ccache --trim-dir
periodically.
Examples:
Optional attributes:
The default is subdirs.
HTTP storage backend¶
URL format: http://HOST[:PORT][/PATH]
This backend stores data in an HTTP-compatible server. The required HTTP methods are GET, PUT and DELETE.
Important
ccache will not perform any cleanup of the storage — that
has to be
done by other means, for instance by running ccache --trim-dir
periodically.
Note
HTTPS is not supported.
Tip
See
How to set up HTTP storage
<https://ccache.dev/howto/http-storage.html> for hints on how to set
up an HTTP server for use with ccache.
Examples:
Optional attributes:
Note
You may have to disable verification of action cache values in the
server
for this to work since ccache entries are not valid action result metadata
values.
The default is subdirs.
Redis storage backend¶
URL format: redis://[[USERNAME:]PASSWORD@]HOST[:PORT][/DBNUMBER]
This backend stores data in a Redis <https://redis.io> (or Redis-compatible) server. There are implementations for both memory-based and disk-based storage. PORT defaults to 6379 and DBNUMBER defaults to 0.
Note
ccache will not perform any cleanup of the Redis storage, but you
can
configure LRU eviction <https://redis.io/topics/lru-cache>.
Tip
See
How to set up Redis <https://ccache.dev/howto/redis-storage.html>
storage" for hints on setting up a Redis server for use with
ccache.
Tip
You can set up a cluster of Redis servers using the shards
attribute
described in SECONDARY STORAGE BACKENDS.
Examples:
Optional attributes:
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 the -s/--show-stats option 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.
Automatic cleanup¶
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.
The LRU cleanup makes use of the file modification time (mtime) of cache entries; ccache updates mtime of the cache entries read on a cache hit to mark them as "recently used".
Manual cleanup¶
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.
CACHE COMPRESSION¶
Ccache will by default compress all data it puts into the cache using the compression algorithm Zstandard <http://zstd.net> (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 size: 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 --show-stats shows a summary of statistics, including cache size, cleanups (number of performed cleanups, either implicitly due to a cache size limit being reached or due to explicit ccache -c calls), overall hit rate, hit rate for direct/preprocessed modes and hit rate for primary and secondary storage.
The summary also includes counters called “Errors” and “Uncacheable”, which are sums of more detailed counters. To see those detailed counters, use the -v/--verbose flag. The verbose mode can show the following counters:
Counter | Description |
Autoconf compile/link | Uncacheable 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. |
Called for linking | 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. |
Could not use modules | Preconditions for using C++ MODULES were not fulfilled. |
Could not use precompiled header | Preconditions for using precompiled headers were not fulfilled. |
Could not write to output file | The output path specified with -o could not be written to. |
Compilation 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. |
Could not 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). |
Forced recache | CCACHE_RECACHE was used to overwrite an existing result. |
Internal error | Unexpected failure, e.g. due to problems reading/writing the cache. |
Missing cache file | 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. |
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 stdout | The compiler was instructed to write its output to standard output using -o -. This is not supported by ccache. |
Preprocessing failed | Preprocessing the source code using the compiler’s -E option failed. |
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 environment variable | An environment variable not supported by ccache was set. |
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.
Advantages:
Disadvantages:
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:
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:
Filename | Description |
<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 debug_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:
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 “Preprocessing failed” (if the non-precompiled header file is not available).
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.
An alternative to putting the main cache directory on NFS is to set up a secondary storage file cache.
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¶
General¶
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.
Performance¶
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.
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.
2022-09-05 | Ccache 4.6.3 |