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. 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 BUGS. If you ever discover an undocumented case where ccache changes the output of your compiler, please let us know.

Features¶

Limitations¶

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: 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.

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. -c, --cleanup -C, --clear -F, --max-files=N -h, --help -M, --max-size=SIZE -s, --show-stats -V, --version -z, --zero-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. 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.

ENVIRONMENT VARIABLES¶

ccache uses a number of environment variables to control operation. In most cases you won’t need any of these as the defaults will be fine. CCACHE_BASEDIR CCACHE_CC CCACHE_COMPILERCHECK CCACHE_COMPRESS CCACHE_CPP2 CCACHE_DETECT_SHEBANG CCACHE_DIR CCACHE_DISABLE CCACHE_EXTENSION CCACHE_EXTRAFILES CCACHE_HARDLINK CCACHE_HASHDIR CCACHE_LOGFILE CCACHE_NLEVELS CCACHE_NODIRECT CCACHE_NOSTATS CCACHE_PATH CCACHE_PREFIX CCACHE_READONLY CCACHE_RECACHE CCACHE_SLOPPINESS CCACHE_TEMPDIR CCACHE_UMASK CCACHE_UNIFY

CACHE SIZE MANAGEMENT¶

By default ccache has a one gigabyte limit on the total size of files in the cache and no maximum 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).

CACHE COMPRESSION¶

ccache can optionally compress all files it puts into the cache using the compression library zlib. While this involves a negligible performance slowdown, it significantly increases the number of files that fit in the cache. You can turn on compression by setting the CCACHE_COMPRESS environment variable.

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 doing the detection: The direct mode is generally faster since running the preprocessor has some overhead.

Common hashed information¶

For both modes, the following information is 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. 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.

COMPILING IN DIFFERENT DIRECTORIES¶

Some information included in the hash that identifies a unique compilation may 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. To mitigate this problem, you can specify a “base directory” by setting the CCACHE_BASEDIR variable to an absolute path to the directory. ccache will then rewrite absolute paths that are under the base directory (i.e., paths that have the base directory as a prefix) to relative paths when constructing the hash. A typical path to use as the base directory is your home directory or another directory that is a parent of your build directories. (Don’t use / as the base directory since that will make ccache also rewrite paths to system header files, which doesn’t gain anything.) The drawbacks of using CCACHE_BASEDIR are:

PRECOMPILED HEADERS¶

ccache has support for GCC’s precompiled headers. However, you have to do some things to make it work properly:

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: 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 the developers have CCACHE_BASEDIR set appropriately, as discussed in the 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 CCACHE_TEMPDIR 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 using the CCACHE_PREFIX option. You just need to set the environment variable CCACHE_PREFIX to the name of the wrapper (e.g. distcc) and ccache will prefix the command line with the specified command when running the compiler. Unless you set CCACHE_COMPILERCHECK 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 CCACHE_PREFIX is not used, ccache will needlessly invoke the other wrapper when running the preprocessor.

BUGS¶

TROUBLESHOOTING¶

General¶

A general tip for getting information about what ccache is doing is to enable debug logging by setting CCACHE_LOGFILE. The log contains executed commands, important decisions that ccache makes, read and written files, etc. 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 preferrable. 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:

Errors when compiling with ccache¶

If compilation doesn’t work with ccache, but it works without it, one possible reason is that the compiler can’t compile preprocessed output correctly. A workaround that may work is to set CCACHE_CPP2. This will make cache misses slower, though, so it is better to find and fix the root cause.

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 CCACHE_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: http://ccache.samba.org.

AUTHOR¶

ccache was originally written by Andrew Tridgell and is currently developed and maintained by Joel Rosdahl. See AUTHORS.txt or AUTHORS.html and http://ccache.samba.org/credits.html for a list of contributors.