table of contents
- RUN MODES
- EXTRA OPTIONS
- CACHE SIZE MANAGEMENT
- CACHE COMPRESSION
- CACHE STATISTICS
- HOW CCACHE WORKS
- CACHE DEBUGGING
- COMPILING IN DIFFERENT DIRECTORIES
- PRECOMPILED HEADERS
- SHARING A CACHE
- SHARING A CACHE ON NFS
- USING CCACHE WITH OTHER COMPILER WRAPPERS
- MORE INFORMATION
NAME¶ccache - a fast C/C++ compiler cache
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. Supported languages are C, C++, Objective-C and Objective-C++.
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 ever 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.
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.
Do not use a hard link, use a symbolic link. A hard link will cause “interesting” problems.
OPTIONS¶These 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.
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.
--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 configuration file settings, 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 priority of configuration settings is as follows (where 1 is highest):
As a special case, if the environment variable CCACHE_CONFIGPATH is set, ccache reads configuration from the specified path instead of the default paths.
Configuration file syntax¶Configuration files are in a simple “key = value” format, one setting 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 settings 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: a set environment variable means “true” (even if set to the empty string), the following case-insensitive negative values are considered an error (rather than surprising the user): 0, false, disable and no, and an unset environment variable means “false”. 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 settings¶Below is a list of available configuration settings. The corresponding environment variable name is indicated in parentheses after each configuration setting key.
See also the discussion under COMPILING IN DIFFERENT DIRECTORIES.
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 setting if possible. See USING CCACHE WITH OTHER COMPILER WRAPPERS.
compression (CCACHE_COMPRESS or CCACHE_NOCOMPRESS, see Boolean values above)
debug (CCACHE_DEBUG or CCACHE_NODEBUG, see Boolean values above)
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)
hard_link (CCACHE_HARDLINK or CCACHE_NOHARDLINK, see Boolean values above)
Do not enable this option unless you are aware of the consequences. Using hard links may be slightly faster in some situations, but there are several pitfalls since the resulting object file will share i-node with the cached object file:
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 setting 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.
keep_comments_cpp (CCACHE_COMMENTS or CCACHE_NOCOMMENTS, see Boolean values above)
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)
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.)
unify (CCACHE_UNIFY or CCACHE_NOUNIFY, see Boolean values above)
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 -M/--max-size and -F/--max-files options. 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.
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.
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 max_size and max_files settings are not exceeded. Note that limit_multiple is not taken into account for manual cleanup.
CACHE COMPRESSION¶ccache can optionally compress all files it puts into the cache using the compression library zlib. While this may involve a tiny performance slowdown, it increases the number of files that fit in the cache. You can turn on compression with the compression configuration setting and you can also tweak the compression level with compression_level.
CACHE STATISTICS¶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 an option that requires an argument or failure to read a file specified by an 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.|
|called for preprocessing||The compiler was called for preprocessing, not compiling.|
|can’t use precompiled header||Preconditions for using precompiled headers 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 MD4, a very fast cryptographic hash algorithm, for the hashing. (MD4 is nowadays too weak to be useful in cryptographic contexts, but it should be safe enough to be used to identify recompilations.) On a cache hit, ccache is able to supply all of the correct compiler outputs (including all warnings, dependency file, etc) from the cache.
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 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 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 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:
CACHE DEBUGGING¶To find out what information ccache actually is hashing, you can enable the debug mode via the configuration setting 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.|
In the direct mode, ccache uses the MD4 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 “preprocessor error” (if the non-precompiled header file is not available).
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.
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 the configuration setting 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 the prefix_command_cpp configuration setting if you also want to invoke the other wrapper when doing preprocessing (normally by adding -E).
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 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.