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 ever 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.
Do not use a hard link, use a symbolic link. A hard link will cause “interesting” problems.
--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 environment variable CCACHE_CONFIGPATH is set, ccache reads configuration from the specified path instead of the default paths.
# Set maximum cache size to 10 GB: max_size = 10G
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)
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 = false to 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.
|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.|
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, 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:
Based on the hash, the cached compilation result can be looked up directly in the cache.
The depend mode will be disabled if any of the following holds:
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:
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).
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.
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).
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.