-CCACHE(1)
-=========
+= CCACHE(1)
:man source: ccache
:man version: {revnumber}
:man manual: ccache Manual
-Name
-----
+== Name
ccache - a fast C/C++ compiler cache
-Synopsis
---------
+== Synopsis
[verse]
*ccache* [_options_]
_compiler_ [_compiler options_] (via symbolic link)
-Description
------------
+== 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
where ccache changes the output of your compiler, please let us know.
-Run modes
----------
+== 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
WARNING: Use a symbolic links for masquerading, not hard links.
-Command line options
---------------------
+== 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
compiler's documentation.
-Common options
-~~~~~~~~~~~~~~
+=== Common options
*`-c`*, *`--cleanup`*::
Zero the cache statistics (but not the configuration options).
-Options for scripting or debugging
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+=== Options for scripting or debugging
*`--checksum-file`* _PATH_::
-Extra options
-~~~~~~~~~~~~~
+=== 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
compiler than what ccache thinks.
-Configuration
--------------
+== 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
configuration file won't be read.
-Location of the primary configuration file
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+=== Location of the primary configuration file
The location of the primary (cache-specific) configuration is determined like
this:
*$HOME/.config/ccache/ccache.conf* (other systems).
-Configuration file syntax
-~~~~~~~~~~~~~~~~~~~~~~~~~
+=== 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
max_size = 10G
-------------------------------------------------------------------------------
-Boolean values
-~~~~~~~~~~~~~~
+=== 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*.
*CCACHE_NOCOMPRESS* can be set to force no compression.
-Configuration options
-~~~~~~~~~~~~~~~~~~~~~~
+=== Configuration options
Below is a list of available configuration options. The corresponding
environment variable name is indicated in parentheses after each configuration
other users.
-Cache size management
----------------------
+== 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
Cleanup can be triggered in two different ways: automatic and manual.
-Automatic cleanup
-~~~~~~~~~~~~~~~~~
+=== 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
idea to trigger it often, like after each cache miss.
-Manual cleanup
-~~~~~~~~~~~~~~
+=== 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
cleanup.
-Cache compression
------------------
+== Cache compression
Ccache will by default compress all data it puts into the cache using the
compression algorithm http://zstd.net[Zstandard] (zstd) using compression level
recompressed.
-Cache statistics
-----------------
+== Cache statistics
*ccache -s/--show-stats* can show the following statistics:
|==============================================================================
-How ccache works
-----------------
+== 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
below.
-Common hashed information
-~~~~~~~~~~~~~~~~~~~~~~~~~
+=== Common hashed information
The following information is always included in the hash:
<<config_extra_files_to_hash,*extra_files_to_hash*>> (if any)
-The preprocessor mode
-~~~~~~~~~~~~~~~~~~~~~
+=== The preprocessor mode
In the preprocessor mode, the hash is formed of the common information and:
the cache.
-The direct mode
-~~~~~~~~~~~~~~~
+=== The direct mode
In the direct mode, the hash is formed of the common information and:
* the string `__TIME__` is present in the source code
-The depend mode
-~~~~~~~~~~~~~~~
+=== 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
* The compiler is not generating dependencies using *-MD* or *-MMD*.
-Handling of newly created header files
---------------------------------------
+== 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
5. The wrong object file is stored in the cache.
-Cache debugging
----------------
+== Cache debugging
To find out what information ccache actually is hashing, you can enable the
debug mode via the configuration option <<config_debug,*debug*>> or by setting
what is happening.
-Compiling in different directories
-----------------------------------
+== Compiling in different directories
Some information included in the hash that identifies a unique compilation can
contain absolute paths:
relative before computing the hash.
-Precompiled headers
--------------------
+== Precompiled headers
Ccache has support for GCC's precompiled headers. However, you have to do some
things to make it work properly:
--
-C++ modules
------------
+== 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
of *module.modulemap* files.
-Sharing a cache
----------------
+== 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
discussed in a previous section.
-Sharing a cache on NFS
-----------------------
+== 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:
headers.
-Using ccache with other compiler wrappers
------------------------------------------
+== 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
the other wrapper when doing preprocessing (normally by adding *-E*).
-Caveats
--------
+== Caveats
* The direct mode fails to pick up new header files in some rare scenarios. See
_<<_the_direct_mode,The direct mode>>_ above.
-Troubleshooting
----------------
+== Troubleshooting
-General
-~~~~~~~
+=== General
A general tip for getting information about what ccache is doing is to enable
debug logging by setting the configuration option <<config_debug,*debug*>> (or
happening is to check the output of *ccache -s*.
-Performance
-~~~~~~~~~~~
+=== 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
modules>>_.
-Corrupt object files
-~~~~~~~~~~~~~~~~~~~~
+=== 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
case, please report it.
-More information
-----------------
+== More information
Credits, mailing list information, bug reporting instructions, source code,
etc, can be found on ccache's web site: <https://ccache.dev>.
-Author
-------
+== Author
Ccache was originally written by Andrew Tridgell and is currently developed and
maintained by Joel Rosdahl. See AUTHORS.txt or AUTHORS.html and
projects / thirdparty / ccache.git / commitdiff
