3933 lines
98 KiB
Groff
3933 lines
98 KiB
Groff
'\" t
|
|
.\" Title: ccache
|
|
.\" Author: [see the "AUTHOR(S)" section]
|
|
.\" Generator: Asciidoctor 2.0.18
|
|
.\" Date: 2023-03-12
|
|
.\" Manual: \ \&
|
|
.\" Source: Ccache 4.8
|
|
.\" Language: English
|
|
.\"
|
|
.TH "CCACHE" "1" "2023-03-12" "Ccache 4.8" "\ \&"
|
|
.ie \n(.g .ds Aq \(aq
|
|
.el .ds Aq '
|
|
.ss \n[.ss] 0
|
|
.nh
|
|
.ad l
|
|
.de URL
|
|
\fI\\$2\fP <\\$1>\\$3
|
|
..
|
|
.als MTO URL
|
|
.if \n[.g] \{\
|
|
. mso www.tmac
|
|
. am URL
|
|
. ad l
|
|
. .
|
|
. am MTO
|
|
. ad l
|
|
. .
|
|
. LINKSTYLE blue R < >
|
|
.\}
|
|
.SH "NAME"
|
|
ccache \- a fast C/C++ compiler cache
|
|
.SH "SYNOPSIS"
|
|
.sp
|
|
.nf
|
|
\fBccache\fP [\fIccache options\fP]
|
|
\fBccache\fP [\fIKEY\fP=\fIVALUE\fP ...] \fIcompiler\fP [\fIcompiler options\fP]
|
|
\fIcompiler\fP [\fIcompiler options\fP]
|
|
.fi
|
|
.br
|
|
.sp
|
|
The first form takes options described in COMMAND LINE OPTIONS below. The
|
|
second form invokes the compiler, optionally using configuration
|
|
options as \fIKEY\fP=\fIVALUE\fP arguments. In the third form, ccache is masquerading
|
|
as the compiler as described in RUN MODES.
|
|
.SH "DESCRIPTION"
|
|
.sp
|
|
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.
|
|
.sp
|
|
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 \fICAVEATS\fP. If you discover an undocumented case where
|
|
ccache changes the output of your compiler, please let us know.
|
|
.SH "RUN MODES"
|
|
.sp
|
|
There are two different ways to use ccache to cache a compilation:
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04' 1.\h'+01'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP " 1." 4.2
|
|
.\}
|
|
Prefix your compilation command with \fBccache\fP. This method is most convenient
|
|
if you just want to try out ccache or wish to use it for some specific
|
|
projects. Example:
|
|
.sp
|
|
.if n .RS 4
|
|
.nf
|
|
.fam C
|
|
ccache gcc \-c example.c
|
|
.fam
|
|
.fi
|
|
.if n .RE
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04' 2.\h'+01'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP " 2." 4.2
|
|
.\}
|
|
Let ccache masquerade as the compiler. This method is most useful when you
|
|
wish to use ccache for all your compilations. To do this, create a symbolic
|
|
link to ccache named as the compiler. For example, here is set up ccache to
|
|
masquerade as \fBgcc\fP and \fBg++\fP:
|
|
.sp
|
|
.if n .RS 4
|
|
.nf
|
|
.fam C
|
|
cp ccache /usr/local/bin/
|
|
ln \-s ccache /usr/local/bin/gcc
|
|
ln \-s ccache /usr/local/bin/g++
|
|
.fam
|
|
.fi
|
|
.if n .RE
|
|
.sp
|
|
On platforms that don\(cqt support symbolic links you can simply copy ccache to the
|
|
compiler name instead for a similar effect:
|
|
.sp
|
|
.if n .RS 4
|
|
.nf
|
|
.fam C
|
|
cp ccache /usr/local/bin/gcc
|
|
cp ccache /usr/local/bin/g++
|
|
.fam
|
|
.fi
|
|
.if n .RE
|
|
.sp
|
|
And so forth. This will work as long as the directory with symbolic links or
|
|
ccache copies comes before the directory with the compiler (typically
|
|
\fB/usr/bin\fP) in \fBPATH\fP.
|
|
.if n .sp
|
|
.RS 4
|
|
.it 1 an-trap
|
|
.nr an-no-space-flag 1
|
|
.nr an-break-flag 1
|
|
.br
|
|
.ps +1
|
|
.B Warning
|
|
.ps -1
|
|
.br
|
|
.sp
|
|
The technique of letting ccache masquerade as the compiler works well,
|
|
but currently doesn\(cqt interact well with other tools that do the same thing. See
|
|
\fIUSING CCACHE WITH OTHER COMPILER WRAPPERS\fP.
|
|
.sp .5v
|
|
.RE
|
|
.RE
|
|
.SH "COMMAND LINE OPTIONS"
|
|
.sp
|
|
These command line options only apply when you invoke ccache as \(lqccache\(rq. When
|
|
ccache masquerades as a compiler (as described in the previous section), the
|
|
normal compiler options apply and you should refer to the compiler\(cqs
|
|
documentation.
|
|
.SS "Common options"
|
|
.sp
|
|
\fB\-c\fP, \fB\-\-cleanup\fP
|
|
.RS 4
|
|
Clean up the cache by removing old cached files until the specified file
|
|
number and cache size limits are not exceeded. This also recalculates the
|
|
cache file count and size totals. Normally, there is no need to initiate
|
|
cleanup manually as ccache keeps the cache below the specified limits at
|
|
runtime and keeps statistics up to date on each compilation. Forcing a
|
|
cleanup is mostly useful if you have modified the cache contents manually or
|
|
believe that the cache size statistics may be inaccurate.
|
|
.RE
|
|
.sp
|
|
\fB\-C\fP, \fB\-\-clear\fP
|
|
.RS 4
|
|
Clear the entire cache, removing all cached files, but keeping the
|
|
configuration file.
|
|
.RE
|
|
.sp
|
|
\fB\-\-config\-path\fP \fIPATH\fP
|
|
.RS 4
|
|
Let the command line options operate on configuration file \fIPATH\fP instead of
|
|
the default. Using this option has the same effect as setting (overriding)
|
|
the environment variable \fBCCACHE_CONFIGPATH\fP temporarily.
|
|
.RE
|
|
.sp
|
|
\fB\-d\fP, \fB\-\-dir\fP \fIPATH\fP
|
|
.RS 4
|
|
Let the command line options operate on cache directory \fIPATH\fP instead of
|
|
the default. For example, to show statistics for a cache directory at
|
|
\fB/shared/ccache\fP you can run \fBccache \-d /shared/ccache \-s\fP. Using this option
|
|
has the same effect as setting the environment variable \fBCCACHE_DIR\fP
|
|
temporarily.
|
|
.RE
|
|
.sp
|
|
\fB\-\-evict\-namespace\fP \fINAMESPACE\fP
|
|
.RS 4
|
|
Remove files created in the given \fBnamespace\fP from the
|
|
cache.
|
|
.RE
|
|
.sp
|
|
\fB\-\-evict\-older\-than\fP \fIAGE\fP
|
|
.RS 4
|
|
Remove files older than \fIAGE\fP from the cache. \fIAGE\fP should be an unsigned
|
|
integer with a \fBd\fP (days) or \fBs\fP (seconds) suffix. If combined with
|
|
\fB\-\-evict\-namespace\fP, only remove old files within that namespace.
|
|
.RE
|
|
.sp
|
|
\fB\-h\fP, \fB\-\-help\fP
|
|
.RS 4
|
|
Print a summary of command line options.
|
|
.RE
|
|
.sp
|
|
\fB\-F\fP \fINUM\fP, \fB\-\-max\-files\fP \fINUM\fP
|
|
.RS 4
|
|
Set the maximum number of files allowed in the cache to \fINUM\fP. Use 0 for no
|
|
limit. The value is stored in a configuration file in the cache directory
|
|
and applies to all future compilations.
|
|
.RE
|
|
.sp
|
|
\fB\-M\fP \fISIZE\fP, \fB\-\-max\-size\fP \fISIZE\fP
|
|
.RS 4
|
|
Set the maximum size of the files stored in the cache. \fISIZE\fP should be a
|
|
number followed by an optional suffix: kB, MB, GB, TB (decimal), KiB, MiB,
|
|
GiB or TiB (binary). The default suffix is GiB. Use 0 for no limit. The
|
|
value is stored in a configuration file in the cache directory and applies
|
|
to all future compilations.
|
|
.RE
|
|
.sp
|
|
\fB\-X\fP \fILEVEL\fP, \fB\-\-recompress\fP \fILEVEL\fP
|
|
.RS 4
|
|
Recompress the cache to level \fILEVEL\fP using the Zstandard algorithm. The
|
|
level can be an integer, with the same semantics as the
|
|
\fBcompression_level\fP configuration option, or
|
|
the special value \fBuncompressed\fP for no compression. See \fI[Cache
|
|
compression]\fP for more information. This can potentially take a long time
|
|
since all files in the cache need to be visited. Only files that are
|
|
currently compressed with a different level than \fILEVEL\fP will be
|
|
recompressed.
|
|
.RE
|
|
.sp
|
|
\fB\-\-recompress\-threads\fP \fITHREADS\fP
|
|
.RS 4
|
|
Use up to \fITHREADS\fP threads when recompressing the cache. The default is to
|
|
use one thread per CPU.
|
|
.RE
|
|
.sp
|
|
\fB\-o\fP \fIKEY=VALUE\fP, \fB\-\-set\-config\fP \fIKEY\fP=\fIVALUE\fP
|
|
.RS 4
|
|
Set configuration option \fIKEY\fP to \fIVALUE\fP. See \fICONFIGURATION\fP for more
|
|
information.
|
|
.RE
|
|
.sp
|
|
\fB\-x\fP, \fB\-\-show\-compression\fP
|
|
.RS 4
|
|
Print cache compression statistics. See \fICACHE COMPRESSION\fP for more
|
|
information. This can potentially take a long time since all files in the
|
|
cache need to be visited.
|
|
.RE
|
|
.sp
|
|
\fB\-p\fP, \fB\-\-show\-config\fP
|
|
.RS 4
|
|
Print current configuration options and from where they originate
|
|
(environment variable, configuration file or compile\-time default) in
|
|
human\-readable format.
|
|
.RE
|
|
.sp
|
|
\fB\-\-show\-log\-stats\fP
|
|
.RS 4
|
|
Print statistics counters from the stats log in human\-readable format. See
|
|
\fBstats_log\fP. Use \fB\-v\fP/\fB\-\-verbose\fP once or twice for
|
|
more details.
|
|
.RE
|
|
.sp
|
|
\fB\-s\fP, \fB\-\-show\-stats\fP
|
|
.RS 4
|
|
Print a summary of configuration and statistics counters in human\-readable
|
|
format. Use \fB\-v\fP/\fB\-\-verbose\fP once or twice for more details.
|
|
.RE
|
|
.sp
|
|
\fB\-v\fP, \fB\-\-verbose\fP
|
|
.RS 4
|
|
Increase verbosity. The option can be given multiple times.
|
|
.RE
|
|
.sp
|
|
\fB\-V\fP, \fB\-\-version\fP
|
|
.RS 4
|
|
Print version and copyright information.
|
|
.RE
|
|
.sp
|
|
\fB\-z\fP, \fB\-\-zero\-stats\fP
|
|
.RS 4
|
|
Zero the cache statistics (but not the configuration options).
|
|
.RE
|
|
.SS "Options for remote file\-based storage"
|
|
.sp
|
|
\fB\-\-trim\-dir\fP \fIPATH\fP
|
|
.RS 4
|
|
Remove old files from directory \fIPATH\fP until it is at most the size
|
|
specified by \fB\-\-trim\-max\-size\fP.
|
|
.if n .sp
|
|
.RS 4
|
|
.it 1 an-trap
|
|
.nr an-no-space-flag 1
|
|
.nr an-break-flag 1
|
|
.br
|
|
.ps +1
|
|
.B Warning
|
|
.ps -1
|
|
.br
|
|
.sp
|
|
Don\(cqt use this option to trim the local cache. To trim the local cache
|
|
directory to a certain size, use \fBCCACHE_MAXSIZE=\fISIZE\fP ccache \-c\fP.
|
|
.sp .5v
|
|
.RE
|
|
.RE
|
|
.sp
|
|
\fB\-\-trim\-max\-size\fP \fISIZE\fP
|
|
.RS 4
|
|
Specify the maximum size for \fB\-\-trim\-dir\fP. \fISIZE\fP should be a number
|
|
followed by an optional suffix: kB, MB, GB, TB (decimal), KiB, MiB, GiB or
|
|
TiB (binary). The default suffix is GiB.
|
|
.RE
|
|
.sp
|
|
\fB\-\-trim\-method\fP \fIMETHOD\fP
|
|
.RS 4
|
|
Specify the method to trim a directory with \fB\-\-trim\-dir\fP. Possible values
|
|
are:
|
|
.sp
|
|
\fBatime\fP
|
|
.RS 4
|
|
LRU (least recently used) using the file access timestamp. This is the
|
|
default.
|
|
.RE
|
|
.sp
|
|
\fBmtime\fP
|
|
.RS 4
|
|
LRU (least recently used) using the file modification timestamp.
|
|
.RE
|
|
.RE
|
|
.sp
|
|
\fB\-\-trim\-recompress\fP \fILEVEL\fP
|
|
.RS 4
|
|
Recompress to level \fILEVEL\fP using the Zstandard algorithm when using
|
|
\fB\-\-trim\-dir\fP. The level can be an integer, with the same semantics as the
|
|
\fBcompression_level\fP configuration option, or
|
|
the special value \fBuncompressed\fP for no compression. See \fI[Cache
|
|
compression]\fP for more information. This can potentially take a long time
|
|
since all files in the cache need to be visited. Only files that are
|
|
currently compressed with a different level than \fILEVEL\fP will be
|
|
recompressed.
|
|
.RE
|
|
.sp
|
|
\fB\-\-trim\-recompress\-threads\fP \fITHREADS\fP
|
|
.RS 4
|
|
Recompress using up to \fITHREADS\fP threads with \fB\-\-trim\-recompress\fP. The
|
|
default is to use one thread per CPU.
|
|
.RE
|
|
.SS "Options for scripting or debugging"
|
|
.sp
|
|
\fB\-\-checksum\-file\fP \fIPATH\fP
|
|
.RS 4
|
|
Print the checksum (128 bit XXH3) of the file at \fIPATH\fP (\fB\-\fP for standard
|
|
input).
|
|
.RE
|
|
.sp
|
|
\fB\-\-extract\-result\fP \fIPATH\fP
|
|
.RS 4
|
|
Extract data stored in the result file at \fIPATH\fP (\fB\-\fP for standard input).
|
|
The data will be written to \fBccache\-result.*\fP files in to the current
|
|
working directory. This option is only useful when debugging ccache and its
|
|
behavior.
|
|
.RE
|
|
.sp
|
|
\fB\-k\fP \fIKEY\fP, \fB\-\-get\-config\fP \fIKEY\fP
|
|
.RS 4
|
|
Print the value of configuration option \fIKEY\fP. See \fICONFIGURATION\fP for
|
|
more information.
|
|
.RE
|
|
.sp
|
|
\fB\-\-hash\-file\fP \fIPATH\fP
|
|
.RS 4
|
|
Print the hash (160 bit BLAKE3) of the file at \fIPATH\fP (\fB\-\fP for standard
|
|
input). This is only useful when debugging ccache and its behavior.
|
|
.RE
|
|
.sp
|
|
\fB\-\-inspect\fP \fIPATH\fP
|
|
.RS 4
|
|
Print the content of a result or manifest file at \fIPATH\fP (\fB\-\fP for standard
|
|
input) to standard output in human\-readable format. File content embedded in
|
|
a result file will however not be printed; use \fB\-\-extract\-result\fP to extract
|
|
the file content. This option is only useful when debugging ccache and its
|
|
behavior.
|
|
.RE
|
|
.sp
|
|
\fB\-\-print\-stats\fP
|
|
.RS 4
|
|
Print statistics counter IDs and corresponding values in machine\-parsable
|
|
(tab\-separated) format.
|
|
.RE
|
|
.SS "Extra options"
|
|
.sp
|
|
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
|
|
\fB\-\-ccache\-skip\fP. 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.
|
|
.if n .sp
|
|
.RS 4
|
|
.it 1 an-trap
|
|
.nr an-no-space-flag 1
|
|
.nr an-break-flag 1
|
|
.br
|
|
.ps +1
|
|
.B Note
|
|
.ps -1
|
|
.br
|
|
.sp
|
|
\fB\-\-ccache\-skip\fP currently only tells ccache not to interpret the next
|
|
option as a special compiler option \(em the option will still be included in the
|
|
direct mode hash.
|
|
.sp .5v
|
|
.RE
|
|
.sp
|
|
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 \fB\-\-ccache\-skip\fP 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.
|
|
.sp
|
|
Another case where \fB\-\-ccache\-skip\fP can be useful is if ccache interprets an
|
|
option specially but shouldn\(cqt, since the option has another meaning for your
|
|
compiler than what ccache thinks.
|
|
.SH "CONFIGURATION"
|
|
.sp
|
|
Ccache\(cqs default behavior can be overridden by options in configuration files,
|
|
which in turn can be overridden by environment variables with names starting
|
|
with \fBCCACHE_\fP. 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):
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04' 1.\h'+01'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP " 1." 4.2
|
|
.\}
|
|
Command line settings in \fIKEY\fP=\fIVALUE\fP form. Example:
|
|
.sp
|
|
.if n .RS 4
|
|
.nf
|
|
.fam C
|
|
ccache debug=true compiler_check="%compiler% \-\-version" gcc \-c example.c
|
|
.fam
|
|
.fi
|
|
.if n .RE
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04' 2.\h'+01'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP " 2." 4.2
|
|
.\}
|
|
Environment variables.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04' 3.\h'+01'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP " 3." 4.2
|
|
.\}
|
|
The cache\-specific configuration file (see below).
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04' 4.\h'+01'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP " 4." 4.2
|
|
.\}
|
|
The system (read\-only) configuration file \fB<sysconfdir>/ccache.conf\fP
|
|
(typically \fB/etc/ccache.conf\fP or \fB/usr/local/etc/ccache.conf\fP).
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04' 5.\h'+01'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP " 5." 4.2
|
|
.\}
|
|
Compile\-time defaults.
|
|
.RE
|
|
.sp
|
|
As a special case, if the environment variable \fBCCACHE_CONFIGPATH\fP is set it
|
|
specifies the configuration file, and the system configuration file won\(cqt be
|
|
read.
|
|
.SS "Location of the configuration file"
|
|
.sp
|
|
The location of the cache\-specific configuration file is determined like this on
|
|
non\-Windows systems:
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04' 1.\h'+01'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP " 1." 4.2
|
|
.\}
|
|
If \fBCCACHE_CONFIGPATH\fP is set, use that path.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04' 2.\h'+01'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP " 2." 4.2
|
|
.\}
|
|
Otherwise, if the environment variable \fBCCACHE_DIR\fP is set then use
|
|
\fB$CCACHE_DIR/ccache.conf\fP.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04' 3.\h'+01'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP " 3." 4.2
|
|
.\}
|
|
Otherwise, if \fBcache_dir\fP is set in the system
|
|
configuration file then use \fB<cache_dir>/ccache.conf\fP.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04' 4.\h'+01'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP " 4." 4.2
|
|
.\}
|
|
Otherwise, if there is a legacy \fB$HOME/.ccache\fP directory then use
|
|
\fB$HOME/.ccache/ccache.conf\fP.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04' 5.\h'+01'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP " 5." 4.2
|
|
.\}
|
|
Otherwise, if \fBXDG_CONFIG_HOME\fP is set then use
|
|
\fB$XDG_CONFIG_HOME/ccache/ccache.conf\fP.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04' 6.\h'+01'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP " 6." 4.2
|
|
.\}
|
|
Otherwise, use
|
|
\fB$HOME/Library/Preferences/ccache/ccache.conf\fP (macOS) or
|
|
\fB$HOME/.config/ccache/ccache.conf\fP (other systems).
|
|
.RE
|
|
.sp
|
|
On Windows, this is the method used to find the configuration file:
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04' 1.\h'+01'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP " 1." 4.2
|
|
.\}
|
|
If \fBCCACHE_CONFIGPATH\fP is set, use that path.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04' 2.\h'+01'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP " 2." 4.2
|
|
.\}
|
|
Otherwise, if the environment variable \fBCCACHE_DIR\fP is set then use
|
|
\fB%CCACHE_DIR%/ccache.conf\fP.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04' 3.\h'+01'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP " 3." 4.2
|
|
.\}
|
|
Otherwise, if \fBcache_dir\fP is set in the system
|
|
configuration file then use \fB<cache_dir>\(rsccache.conf\fP. The
|
|
system\-wide configuration on Windows is
|
|
\fB%ALLUSERSPROFILE%\(rsccache\(rsccache.conf\fP by default. The \fBALLUSERSPROFILE\fP
|
|
environment variable is usually \fBC:\(rsProgramData\fP.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04' 4.\h'+01'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP " 4." 4.2
|
|
.\}
|
|
Otherwise, if there is a legacy \fB%USERPROFILE%\(rs.ccache\fP directory then use
|
|
\fB%USERPROFILE%\(rs.ccache\(rsccache.conf\fP.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04' 5.\h'+01'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP " 5." 4.2
|
|
.\}
|
|
Otherwise, use \fB%LOCALAPPDATA%\(rsccache\(rsccache.conf\fP if it exists.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04' 6.\h'+01'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP " 6." 4.2
|
|
.\}
|
|
Otherwise, use \fB%APPDATA%\(rsccache\(rsccache.conf\fP.
|
|
.RE
|
|
.sp
|
|
See also the \fBcache_dir\fP configuration option for how the
|
|
cache directory location is determined.
|
|
.SS "Configuration file syntax"
|
|
.sp
|
|
Configuration files are in a simple \(lqkey = value\(rq 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:
|
|
.sp
|
|
.if n .RS 4
|
|
.nf
|
|
.fam C
|
|
# Set maximum cache size to 10 GB:
|
|
max_size = 10G
|
|
.fam
|
|
.fi
|
|
.if n .RE
|
|
.SS "Boolean values"
|
|
.sp
|
|
Some configuration options are boolean values (i.e. truth values). In a
|
|
configuration file, such values must be set to the string \fBtrue\fP or \fBfalse\fP.
|
|
For the corresponding environment variables, the semantics are a bit different:
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
A set environment variable means \(lqtrue\(rq (even if set to the empty string).
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
The following case\-insensitive negative values are considered an error
|
|
(instead of surprising the user): \fB0\fP, \fBfalse\fP, \fBdisable\fP and \fBno\fP.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
An unset environment variable means \(lqfalse\(rq.
|
|
.RE
|
|
.sp
|
|
Each boolean environment variable also has a negated form starting with
|
|
\fBCCACHE_NO\fP. For example, \fBCCACHE_COMPRESS\fP can be set to force compression and
|
|
\fBCCACHE_NOCOMPRESS\fP can be set to force no compression.
|
|
.SS "Configuration options"
|
|
.sp
|
|
Below is a list of available configuration options. The corresponding
|
|
environment variable name is indicated in parentheses after each configuration
|
|
option key.
|
|
.sp
|
|
\fBabsolute_paths_in_stderr\fP (\fBCCACHE_ABSSTDERR\fP)
|
|
.RS 4
|
|
This option specifies whether ccache should rewrite relative paths in the
|
|
compiler\(cqs standard error output to absolute paths. This can be useful if
|
|
you use \fBbase_dir\fP with a build system (e.g. CMake with
|
|
the "Unix Makefiles" generator) that executes the compiler in a different
|
|
working directory, which makes relative paths in compiler errors or
|
|
warnings incorrect. The default is false.
|
|
.RE
|
|
.sp
|
|
\fBbase_dir\fP (\fBCCACHE_BASEDIR\fP)
|
|
.RS 4
|
|
This option should be an absolute path to a directory. If set, ccache will
|
|
rewrite absolute paths into paths relative to the current working directory,
|
|
but only absolute paths that begin with \fBbase_dir\fP. Cache results can then
|
|
be shared for compilations in different directories even if the project uses
|
|
absolute paths in the compiler command line. See also the discussion under
|
|
\fICOMPILING IN DIFFERENT DIRECTORIES\fP. If set to the empty string (which
|
|
is the default), no rewriting is done.
|
|
.sp
|
|
A typical path to use as \fBbase_dir\fP is your home directory or another directory
|
|
that is a parent of your project directories. Don\(cqt use \fB/\fP as the base
|
|
directory since that will make ccache also rewrite paths to system header
|
|
files, which typically is contraproductive.
|
|
.sp
|
|
For example, say that Alice\(cqs current working directory is
|
|
\fB/home/alice/project1/build\fP and that she compiles like this:
|
|
.sp
|
|
.if n .RS 4
|
|
.nf
|
|
.fam C
|
|
ccache gcc \-I/usr/include/example \-I/home/alice/project2/include \-c /home/alice/project1/src/example.c
|
|
.fam
|
|
.fi
|
|
.if n .RE
|
|
.sp
|
|
Here is what ccache will actually execute for different \fBbase_dir\fP values:
|
|
.sp
|
|
.if n .RS 4
|
|
.nf
|
|
.fam C
|
|
# 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
|
|
.fam
|
|
.fi
|
|
.if n .RE
|
|
.sp
|
|
If Bob has put \fBproject1\fP and \fBproject2\fP in \fB/home/bob/stuff\fP and both users
|
|
have set \fBbase_dir\fP to \fB/home\fP or \fB/home/$USER\fP, then Bob will get a cache hit
|
|
(if they share ccache directory) since the actual command line will be
|
|
identical to that of Alice:
|
|
.sp
|
|
.if n .RS 4
|
|
.nf
|
|
.fam C
|
|
# 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
|
|
.fam
|
|
.fi
|
|
.if n .RE
|
|
.sp
|
|
Without \fBbase_dir\fP there will be a cache miss since the absolute paths will
|
|
differ. With \fBbase_dir\fP set to \fB/\fP there will be a cache miss since the
|
|
relative path to \fB/usr/include/example\fP will be different. With \fBbase_dir\fP set
|
|
to \fB/home/bob/stuff/project1\fP there will a cache miss since the path to
|
|
project2 will be a different absolute path.
|
|
.if n .sp
|
|
.RS 4
|
|
.it 1 an-trap
|
|
.nr an-no-space-flag 1
|
|
.nr an-break-flag 1
|
|
.br
|
|
.ps +1
|
|
.B Warning
|
|
.ps -1
|
|
.br
|
|
.sp
|
|
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 \fBbase_dir\fP.
|
|
.sp .5v
|
|
.RE
|
|
.RE
|
|
.sp
|
|
\fBcache_dir\fP (\fBCCACHE_DIR\fP)
|
|
.RS 4
|
|
This option specifies where ccache will keep its cached compiler outputs.
|
|
.sp
|
|
On non\-Windows systems, the default is \fB$HOME/.ccache\fP if such a directory
|
|
exists, otherwise \fB$XDG_CACHE_HOME/ccache\fP if \fBXDG_CACHE_HOME\fP is set, otherwise
|
|
\fB$HOME/Library/Caches/ccache\fP (macOS) or \fB$HOME/.config/ccache\fP (other systems).
|
|
.sp
|
|
On Windows, the default is \fB%USERPROFILE%\(rs.ccache\fP if such a directory exists,
|
|
otherwise \fB%LOCALAPPDATA%\(rsccache\fP.
|
|
.if n .sp
|
|
.RS 4
|
|
.it 1 an-trap
|
|
.nr an-no-space-flag 1
|
|
.nr an-break-flag 1
|
|
.br
|
|
.ps +1
|
|
.B Warning
|
|
.ps -1
|
|
.br
|
|
.sp
|
|
Previous ccache versions defaulted to storing the cache in
|
|
\fB%APPDATA%\(rsccache\fP on Windows. This can result in large network file transfers
|
|
of the cache in domain environments and similar problems. Please check this
|
|
directory for cache directories and either delete them or the whole directory,
|
|
or move them to the \fB%LOCALAPPDATA%\(rsccache\fP directory.
|
|
.sp .5v
|
|
.RE
|
|
.sp
|
|
See also \fILocation of the configuration file\fP.
|
|
.RE
|
|
.sp
|
|
\fBcompiler\fP (\fBCCACHE_COMPILER\fP or (deprecated) \fBCCACHE_CC\fP)
|
|
.RS 4
|
|
This option can be used to force the name of the compiler to use. If set to
|
|
the empty string (which is the default), ccache works it out from the
|
|
command line.
|
|
.RE
|
|
.sp
|
|
\fBcompiler_check\fP (\fBCCACHE_COMPILERCHECK\fP)
|
|
.RS 4
|
|
By default, ccache includes the modification time (\(lqmtime\(rq) and size of
|
|
the compiler in the hash to ensure that results retrieved from the cache
|
|
are accurate. If compiler plugins are used, these plugins will also be
|
|
added to the hash. This option can be used to select another strategy.
|
|
Possible values are:
|
|
.sp
|
|
\fBcontent\fP
|
|
.RS 4
|
|
Hash the content of the compiler binary. This makes ccache very slightly
|
|
slower compared to \fBmtime\fP, but makes it cope better with compiler upgrades
|
|
during a build bootstrapping process.
|
|
.RE
|
|
.sp
|
|
\fBmtime\fP
|
|
.RS 4
|
|
Hash the compiler\(cqs mtime and size, which is fast. This is the default.
|
|
.RE
|
|
.sp
|
|
\fBnone\fP
|
|
.RS 4
|
|
Don\(cqt hash anything. This may be good for situations where you can safely
|
|
use the cached results even though the compiler\(cqs mtime or size has changed
|
|
(e.g. if the compiler is built as part of your build system and the
|
|
compiler\(cqs source has not changed, or if the compiler only has changes that
|
|
don\(cqt affect code generation). You should only use \fBnone\fP if you know what
|
|
you are doing.
|
|
.RE
|
|
.sp
|
|
\fBstring:value\fP
|
|
.RS 4
|
|
Hash \fBvalue\fP. This can for instance be a compiler revision number or
|
|
another string that the build system generates to identify the compiler.
|
|
.RE
|
|
.sp
|
|
\fIa command string\fP
|
|
.RS 4
|
|
Hash the standard output and standard error output of the specified
|
|
command. The string will be split on whitespace to find out the command and
|
|
arguments to run. No other interpretation of the command string will be
|
|
done, except that the special word \fB%compiler%\fP will be replaced with the
|
|
path to the compiler. Several commands can be specified with semicolon as
|
|
separator. Examples:
|
|
.sp
|
|
.if n .RS 4
|
|
.nf
|
|
.fam C
|
|
%compiler% \-v
|
|
.fam
|
|
.fi
|
|
.if n .RE
|
|
.sp
|
|
.if n .RS 4
|
|
.nf
|
|
.fam C
|
|
%compiler% \-dumpmachine; %compiler% \-dumpversion
|
|
.fam
|
|
.fi
|
|
.if n .RE
|
|
.sp
|
|
You should make sure that the specified command is as fast as possible since it
|
|
will be run once for each ccache invocation.
|
|
.sp
|
|
Identifying the compiler using a command is useful if you want to avoid cache
|
|
misses when the compiler has been rebuilt but not changed.
|
|
.sp
|
|
Another case is when the compiler (as seen by ccache) actually isn\(cqt the real
|
|
compiler but another compiler wrapper \(em in that case, the default \fBmtime\fP
|
|
method will hash the mtime and size of the other compiler wrapper, which means
|
|
that ccache won\(cqt be able to detect a compiler upgrade. Using a suitable command
|
|
to identify the compiler is thus safer, but it\(cqs also slower, so you should
|
|
consider continue using the \fBmtime\fP method in combination with the
|
|
\fBprefix_command\fP option if possible. See
|
|
\fIUSING CCACHE WITH OTHER COMPILER WRAPPERS\fP.
|
|
.RE
|
|
.RE
|
|
.sp
|
|
\fBcompiler_type\fP (\fBCCACHE_COMPILERTYPE\fP)
|
|
.RS 4
|
|
Ccache normally guesses the compiler type based on the compiler name. The
|
|
\fBcompiler_type\fP option lets you force a compiler type. This can be useful
|
|
if the compiler has a non\-standard name but is actually one of the known
|
|
compiler types. Possible values are:
|
|
.sp
|
|
\fBauto\fP
|
|
.RS 4
|
|
Guess one of the types below based on the compiler name (following
|
|
symlinks). This is the default.
|
|
.RE
|
|
.sp
|
|
\fBclang\fP
|
|
.RS 4
|
|
Clang\-based compiler.
|
|
.RE
|
|
.sp
|
|
\fBclang\-cl\fP
|
|
.RS 4
|
|
clang\-cl.
|
|
.RE
|
|
.sp
|
|
\fBgcc\fP
|
|
.RS 4
|
|
GCC\-based compiler.
|
|
.RE
|
|
.sp
|
|
\fBicl\fP
|
|
.RS 4
|
|
Intel compiler on Windows.
|
|
.RE
|
|
.sp
|
|
\fBmsvc\fP
|
|
.RS 4
|
|
Microsoft Visual C++ (MSVC).
|
|
.RE
|
|
.sp
|
|
\fBnvcc\fP
|
|
.RS 4
|
|
NVCC (CUDA) compiler.
|
|
.RE
|
|
.sp
|
|
\fBother\fP
|
|
.RS 4
|
|
Any compiler other than the known types.
|
|
.RE
|
|
.RE
|
|
.sp
|
|
\fBcompression\fP (\fBCCACHE_COMPRESS\fP or \fBCCACHE_NOCOMPRESS\fP, see \fIBoolean values\fP above)
|
|
.RS 4
|
|
If true, ccache will compress data it puts in the cache. However, this
|
|
option has no effect on how files are retrieved from the cache; compressed
|
|
and uncompressed results will still be usable regardless of this option.
|
|
The default is true.
|
|
.sp
|
|
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.
|
|
.sp
|
|
Compression will be disabled if file cloning (the
|
|
\fBfile_clone\fP option) or hard linking (the
|
|
\fBhard_link\fP option) is enabled.
|
|
.RE
|
|
.sp
|
|
\fBcompression_level\fP (\fBCCACHE_COMPRESSLEVEL\fP)
|
|
.RS 4
|
|
This option determines the level at which ccache will compress object files
|
|
using the real\-time compression algorithm Zstandard. It only has effect if
|
|
\fBcompression\fP is enabled (which it is by default).
|
|
Zstandard is extremely fast for decompression and very fast for compression
|
|
for lower compression levels. The default is 0.
|
|
.sp
|
|
Semantics of \fBcompression_level\fP:
|
|
.sp
|
|
\fB> 0\fP
|
|
.RS 4
|
|
A positive value corresponds to normal Zstandard compression levels. Lower
|
|
levels (e.g. \fB1\fP) mean faster compression but worse compression ratio.
|
|
Higher levels (e.g. \fB19\fP) mean slower compression but better compression
|
|
ratio. The maximum possible value depends on the libzstd version, but at
|
|
least up to 19 is available for all versions. Decompression speed is
|
|
essentially the same for all levels. As a rule of thumb, use level 5 or
|
|
lower since higher levels may slow down compilations noticeably. Higher
|
|
levels are however useful when recompressing the cache with command line
|
|
option \fB\-X\fP/\fB\-\-recompress\fP.
|
|
.RE
|
|
.sp
|
|
\fB< 0\fP
|
|
.RS 4
|
|
A negative value corresponds to Zstandard\(cqs \(lqultra\-fast\(rq compression
|
|
levels, which are even faster than level 1 but with less good compression
|
|
ratios. For instance, level \fB\-3\fP corresponds to \fB\-\-fast=3\fP for the \fBzstd\fP
|
|
command line tool. In practice, there is little use for levels lower than
|
|
\fB\-5\fP or so.
|
|
.RE
|
|
.sp
|
|
\fB0\fP (default)
|
|
.RS 4
|
|
The value \fB0\fP means that ccache will choose a suitable level, currently
|
|
\fB1\fP.
|
|
.RE
|
|
.sp
|
|
See the \c
|
|
.URL "http://zstd.net" "Zstandard documentation" ""
|
|
for more information.
|
|
.RE
|
|
.sp
|
|
\fBcpp_extension\fP (\fBCCACHE_EXTENSION\fP)
|
|
.RS 4
|
|
This option can be used to force a certain extension for the intermediate
|
|
preprocessed file. The default is to automatically determine the extension
|
|
to use for intermediate preprocessor files based on the type of file being
|
|
compiled, but that sometimes doesn\(cqt work. For example, when using the
|
|
\(lqaCC\(rq compiler on HP\-UX, set the cpp extension to \fBi\fP.
|
|
.RE
|
|
.sp
|
|
\fBdebug\fP (\fBCCACHE_DEBUG\fP or \fBCCACHE_NODEBUG\fP, see \fIBoolean values\fP above)
|
|
.RS 4
|
|
If true, enable the debug mode. The debug mode creates per\-object debug
|
|
files that are helpful when debugging unexpected cache misses. Note however
|
|
that ccache performance will be reduced slightly. See \fICACHE DEBUGGING\fP
|
|
for more information. The default is false.
|
|
.RE
|
|
.sp
|
|
\fBdebug_dir\fP (\fBCCACHE_DEBUGDIR\fP)
|
|
.RS 4
|
|
Specifies where to write per\-object debug files if the debug
|
|
mode is enabled. If set to the empty string, the files will be written
|
|
next to the object file. If set to a directory, the debug files will be
|
|
written with full absolute paths in that directory, creating it if needed.
|
|
The default is the empty string.
|
|
.sp
|
|
For example, if \fBdebug_dir\fP is set to \fB/example\fP, the current working directory
|
|
is \fB/home/user\fP and the object file is \fBbuild/output.o\fP then the debug log will
|
|
be written to \fB/example/home/user/build/output.o.ccache\-log\fP. See also
|
|
\fICACHE DEBUGGING\fP.
|
|
.RE
|
|
.sp
|
|
\fBdepend_mode\fP (\fBCCACHE_DEPEND\fP or \fBCCACHE_NODEPEND\fP, see \fIBoolean values\fP above)
|
|
.RS 4
|
|
If true, the depend mode will be used. The default is false. See
|
|
\fIThe depend mode\fP.
|
|
.RE
|
|
.sp
|
|
\fBdirect_mode\fP (\fBCCACHE_DIRECT\fP or \fBCCACHE_NODIRECT\fP, see \fIBoolean values\fP above)
|
|
.RS 4
|
|
If true, the direct mode will be used. The default is true. See
|
|
\fIThe direct mode\fP.
|
|
.RE
|
|
.sp
|
|
\fBdisable\fP (\fBCCACHE_DISABLE\fP or \fBCCACHE_NODISABLE\fP, see \fIBoolean values\fP above)
|
|
.RS 4
|
|
When true, ccache will just call the real compiler, bypassing the cache
|
|
completely. The default is false.
|
|
.sp
|
|
It is also possible to disable ccache for a specific source code file by adding
|
|
the string \fBccache:disable\fP in a comment in the first 4096 bytes of the file.
|
|
.RE
|
|
.sp
|
|
\fBextra_files_to_hash\fP (\fBCCACHE_EXTRAFILES\fP)
|
|
.RS 4
|
|
This option is a list of paths to files that ccache will include in the the
|
|
hash sum that identifies the build. The list separator is semicolon on
|
|
Windows systems and colon on other systems.
|
|
.RE
|
|
.sp
|
|
\fBfile_clone\fP (\fBCCACHE_FILECLONE\fP or \fBCCACHE_NOFILECLONE\fP, see \fIBoolean values\fP above)
|
|
.RS 4
|
|
If true, ccache will attempt to use file cloning (also known as \(lqcopy on
|
|
write\(rq, \(lqCoW\(rq or \(lqreflinks\(rq) to store and fetch cached compiler
|
|
results. \fBfile_clone\fP has priority over \fBhard_link\fP.
|
|
The default is false.
|
|
.sp
|
|
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.
|
|
.sp
|
|
Unlike the \fBhard_link\fP option, \fBfile_clone\fP 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
|
|
\fBhard_link\fP is enabled).
|
|
.RE
|
|
.sp
|
|
\fBhard_link\fP (\fBCCACHE_HARDLINK\fP or \fBCCACHE_NOHARDLINK\fP, see \fIBoolean values\fP above)
|
|
.RS 4
|
|
If true, ccache will attempt to use hard links to store and fetch cached
|
|
object files. The default is false.
|
|
.sp
|
|
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.
|
|
.if n .sp
|
|
.RS 4
|
|
.it 1 an-trap
|
|
.nr an-no-space-flag 1
|
|
.nr an-break-flag 1
|
|
.br
|
|
.ps +1
|
|
.B Warning
|
|
.ps -1
|
|
.br
|
|
.sp
|
|
Do not enable this option unless you are aware of these caveats:
|
|
.sp .5v
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
If the resulting file is modified, the file in the cache will also be
|
|
modified since they share content, which corrupts the cache entry. As of
|
|
version 4.0, ccache makes stored and fetched object files read\-only as a
|
|
safety measure. Furthermore, a simple integrity check is made for cached
|
|
object files by verifying that their sizes are correct. This means that
|
|
mistakes like \fBstrip file.o\fP or \fBecho >file.o\fP will be detected even if the
|
|
object file is made writable, but a modification that doesn\(cqt change the file
|
|
size will not.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
Programs that don\(cqt expect that files from two different identical
|
|
compilations are hard links to each other can fail.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
Programs that rely on modification times (like \fBmake\fP) can be confused if
|
|
several users (or one user with several build trees) use the same cache
|
|
directory. The reason for this is that the object files share i\-nodes and
|
|
therefore modification times. If \fBfile.o\fP is in build tree \fBA\fP (hard\-linked
|
|
from the cache) and \fBfile.o\fP then is produced by ccache in build tree \fBB\fP by
|
|
hard\-linking from the cache, the modification timestamp will be updated for
|
|
\fBfile.o\fP in build tree \fBA\fP as well. This can retrigger relinking in build tree
|
|
\fBA\fP even though nothing really has changed.
|
|
.RE
|
|
.RE
|
|
.sp
|
|
\fBhash_dir\fP (\fBCCACHE_HASHDIR\fP or \fBCCACHE_NOHASHDIR\fP, see \fIBoolean values\fP above)
|
|
.RS 4
|
|
If true (which is the default), ccache will include the current working
|
|
directory (CWD) in the hash that is used to distinguish two compilations
|
|
when generating debug info (compiler option \fB\-g\fP with variations).
|
|
Exception: The CWD will not be included in the hash if
|
|
\fBbase_dir\fP is set (and matches the CWD) and the
|
|
compiler option \fB\-fdebug\-prefix\-map\fP is used. See also the discussion under
|
|
\fICOMPILING IN DIFFERENT DIRECTORIES\fP.
|
|
.sp
|
|
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.
|
|
.sp
|
|
You can disable this option to get cache hits when compiling the same source
|
|
code in different directories if you don\(cqt mind that CWD in the debug info
|
|
might be incorrect.
|
|
.RE
|
|
.sp
|
|
\fBignore_headers_in_manifest\fP (\fBCCACHE_IGNOREHEADERS\fP)
|
|
.RS 4
|
|
This option is a list of paths to files (or directories with headers) that
|
|
ccache will \fBnot\fP include in the manifest list that makes up the direct
|
|
mode. Note that this can cause stale cache hits if those headers do indeed
|
|
change. The list separator is semicolon on Windows systems and colon on
|
|
other systems.
|
|
.RE
|
|
.sp
|
|
\fBignore_options\fP (\fBCCACHE_IGNOREOPTIONS\fP)
|
|
.RS 4
|
|
This option is a space\-delimited list of compiler options that ccache will
|
|
exclude from the hash. Excluding a compiler option from the hash can be
|
|
useful when you know it doesn\(cqt affect the result (but ccache doesn\(cqt know
|
|
that), or when it does and you don\(cqt care. If a compiler option in the list
|
|
is suffixed with an asterisk (\fB*\fP) it will be matched as a prefix. For
|
|
example, \fB\-fmessage\-length=*\fP will match both \fB\-fmessage\-length=20\fP and
|
|
\fB\-fmessage\-length=70\fP.
|
|
.RE
|
|
.sp
|
|
\fBinode_cache\fP (\fBCCACHE_INODECACHE\fP or \fBCCACHE_NOINODECACHE\fP, see \fIBoolean values\fP above)
|
|
.RS 4
|
|
If true, ccache will cache source file hashes based on device, inode and
|
|
timestamps. This reduces the time spent on hashing include files since the
|
|
result can be reused between compilations. The default is true. The feature
|
|
requires \fBtemporary_dir\fP to be located on a local
|
|
filesystem of a supported type.
|
|
.if n .sp
|
|
.RS 4
|
|
.it 1 an-trap
|
|
.nr an-no-space-flag 1
|
|
.nr an-break-flag 1
|
|
.br
|
|
.ps +1
|
|
.B Note
|
|
.ps -1
|
|
.br
|
|
.sp
|
|
The inode cache feature is currently not available on Windows.
|
|
.sp .5v
|
|
.RE
|
|
.RE
|
|
.sp
|
|
\fBkeep_comments_cpp\fP (\fBCCACHE_COMMENTS\fP or \fBCCACHE_NOCOMMENTS\fP, see \fIBoolean values\fP above)
|
|
.RS 4
|
|
If true, ccache will not discard the comments before hashing preprocessor
|
|
output. The default is false. This can be used to check documentation with
|
|
\fB\-Wdocumentation\fP.
|
|
.RE
|
|
.sp
|
|
\fBlog_file\fP (\fBCCACHE_LOGFILE\fP)
|
|
.RS 4
|
|
If set to a file path, ccache will write information on what it is doing to
|
|
the specified file. This is useful for tracking down problems.
|
|
.sp
|
|
If set to \fBsyslog\fP, ccache will log using \fBsyslog()\fP instead of to a file. If
|
|
you use rsyslogd, you can add something like this to \fB/etc/rsyslog.conf\fP or a
|
|
file in \fB/etc/rsyslog.d\fP:
|
|
.sp
|
|
.if n .RS 4
|
|
.nf
|
|
.fam C
|
|
# log ccache to file
|
|
:programname, isequal, "ccache" /var/log/ccache
|
|
# remove from syslog
|
|
& ~
|
|
.fam
|
|
.fi
|
|
.if n .RE
|
|
.RE
|
|
.sp
|
|
\fBmax_files\fP (\fBCCACHE_MAXFILES\fP)
|
|
.RS 4
|
|
This option specifies the maximum number of files to keep in the cache. Use
|
|
0 for no limit (which is the default). See also \fICACHE SIZE MANAGEMENT\fP.
|
|
.RE
|
|
.sp
|
|
\fBmax_size\fP (\fBCCACHE_MAXSIZE\fP)
|
|
.RS 4
|
|
This option specifies the maximum size of the cache. Use 0 for no limit. The
|
|
default value is 5G. Available suffixes: k, M, G, T (decimal) and Ki, Mi,
|
|
Gi, Ti (binary). The default suffix is G. See also
|
|
\fICACHE SIZE MANAGEMENT\fP.
|
|
.RE
|
|
.sp
|
|
\fBmsvc_dep_prefix\fP (\fBCCACHE_MSVC_DEP_PREFIX\fP)
|
|
.RS 4
|
|
This option specifies the prefix of included files output for MSVC compiler.
|
|
The default prefix is \(lqNote: including file:\(rq. If you use a localized
|
|
compiler, this should be set accordingly.
|
|
.RE
|
|
.sp
|
|
\fBnamespace\fP (\fBCCACHE_NAMESPACE\fP)
|
|
.RS 4
|
|
If set, the namespace string will be added to the hashed data for each
|
|
compilation. This will make the associated cache entries logically separate
|
|
from cache entries with other namespaces, but they will still share the same
|
|
storage space. Cache entries can also be selectively removed from the local
|
|
cache with the command line option \fB\-\-evict\-namespace\fP, potentially in
|
|
combination with \fB\-\-evict\-older\-than\fP.
|
|
.sp
|
|
For instance, if you use the same local 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.
|
|
.RE
|
|
.sp
|
|
\fBpath\fP (\fBCCACHE_PATH\fP)
|
|
.RS 4
|
|
If set, ccache will search directories in this list when looking for the
|
|
real compiler. The list separator is semicolon on Windows systems and colon
|
|
on other systems. If not set, ccache will look for the first executable
|
|
matching the compiler name in the normal \fBPATH\fP that isn\(cqt a symbolic link
|
|
to ccache itself.
|
|
.RE
|
|
.sp
|
|
\fBpch_external_checksum\fP (\fBCCACHE_PCH_EXTSUM\fP or \fBCCACHE_NOPCH_EXTSUM\fP, see \fIBoolean values\fP above)
|
|
.RS 4
|
|
When this option is set, and ccache finds a precompiled header file,
|
|
ccache will look for a file with the extension \(lq.sum\(rq added
|
|
(e.g. \(lqpre.h.gch.sum\(rq), and if found, it will hash this file instead
|
|
of the precompiled header itself to work around the performance
|
|
penalty of hashing very large files.
|
|
.RE
|
|
.sp
|
|
\fBprefix_command\fP (\fBCCACHE_PREFIX\fP)
|
|
.RS 4
|
|
This option adds a list of prefixes (separated by space) to the command line
|
|
that ccache uses when invoking the compiler. See also
|
|
\fIUSING CCACHE WITH OTHER COMPILER WRAPPERS\fP.
|
|
.RE
|
|
.sp
|
|
\fBprefix_command_cpp\fP (\fBCCACHE_PREFIX_CPP\fP)
|
|
.RS 4
|
|
This option adds a list of prefixes (separated by space) to the command
|
|
line that ccache uses when invoking the preprocessor.
|
|
.RE
|
|
.sp
|
|
\fBread_only\fP (\fBCCACHE_READONLY\fP or \fBCCACHE_NOREADONLY\fP, see \fIBoolean values\fP above)
|
|
.RS 4
|
|
If true, ccache will attempt to use existing cached results, but it will not
|
|
add new results to any cache backend. Statistics counters will still be
|
|
updated, though, unless the \fBstats\fP option is set to
|
|
\fBfalse\fP.
|
|
.sp
|
|
If you are using this because your ccache directory is read\-only, you need to
|
|
set \fBtemporary_dir\fP since ccache will fail to create
|
|
temporary files otherwise. You may also want to set \fBstats\fP to
|
|
\fBfalse\fP make ccache not even try to update stats files.
|
|
.RE
|
|
.sp
|
|
\fBread_only_direct\fP (\fBCCACHE_READONLY_DIRECT\fP or \fBCCACHE_NOREADONLY_DIRECT\fP, see \fIBoolean values\fP above)
|
|
.RS 4
|
|
Just like \fBread_only\fP except that ccache will only try
|
|
to retrieve results from the cache using the direct mode, not the
|
|
preprocessor mode. See documentation for \fBread_only\fP
|
|
regarding using a read\-only ccache directory.
|
|
.RE
|
|
.sp
|
|
\fBrecache\fP (\fBCCACHE_RECACHE\fP or \fBCCACHE_NORECACHE\fP, see \fIBoolean values\fP above)
|
|
.RS 4
|
|
If true, ccache will not use any previously stored result. New results will
|
|
still be cached, possibly overwriting any pre\-existing results.
|
|
.RE
|
|
.sp
|
|
\fBremote_only\fP (\fBCCACHE_REMOTE_ONLY\fP or \fBCCACHE_NOREMOTE_ONLY\fP, see \fIBoolean values\fP above)
|
|
.RS 4
|
|
If true, ccache will only use remote storage. The
|
|
default is false. Note that cache statistics counters will still be kept in
|
|
the local cache directory unless \fBstats\fP is false. See also
|
|
\fIStorage interaction\fP.
|
|
.RE
|
|
.sp
|
|
\fBremote_storage\fP (\fBCCACHE_REMOTE_STORAGE\fP)
|
|
.RS 4
|
|
This option specifies one or several storage backends (separated by space)
|
|
to query after checking the local cache (unless
|
|
\fBremote_only\fP is true). See
|
|
\fIREMOTE STORAGE BACKENDS\fP for documentation of syntax and available
|
|
backends.
|
|
.sp
|
|
Examples:
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
\fBfile:/shared/nfs/directory\fP
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
\fBfile:///shared/nfs/one|read\-only file:///shared/nfs/two\fP
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
\fBhttp://example.com/cache\fP
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
\fBredis://example.com\fP
|
|
.if n .sp
|
|
.RS 4
|
|
.it 1 an-trap
|
|
.nr an-no-space-flag 1
|
|
.nr an-break-flag 1
|
|
.br
|
|
.ps +1
|
|
.B Note
|
|
.ps -1
|
|
.br
|
|
.sp
|
|
In previous ccache versions this option was called \fBsecondary_storage\fP
|
|
(\fBCCACHE_SECONDARY_STORAGE\fP), which can still be used as an alias.
|
|
.sp .5v
|
|
.RE
|
|
.RE
|
|
.RE
|
|
.sp
|
|
\fBreshare\fP (\fBCCACHE_RESHARE\fP or \fBCCACHE_NORESHARE\fP, see \fIBoolean values\fP above)
|
|
.RS 4
|
|
If true, ccache will write results to remote storage even for local storage
|
|
cache hits. The default is false.
|
|
.RE
|
|
.sp
|
|
\fBrun_second_cpp\fP (\fBCCACHE_CPP2\fP or \fBCCACHE_NOCPP2\fP, see \fIBoolean values\fP above)
|
|
.RS 4
|
|
If true, ccache will first run the preprocessor to preprocess the source
|
|
code (see \fIThe preprocessor mode\fP) and then on a cache miss run the
|
|
compiler on the source code to get hold of the object file. This is the
|
|
default.
|
|
.sp
|
|
If false, ccache will first run preprocessor to preprocess the source code and
|
|
then on a cache miss run the compiler on the \fIpreprocessed source code\fP 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\(cqt produce the same result (for instance diagnostics warnings)
|
|
when compiling preprocessed source code.
|
|
.sp
|
|
A solution to the above mentioned downside is to set \fBrun_second_cpp\fP to false
|
|
and pass \fB\-fdirectives\-only\fP (for GCC) or \fB\-frewrite\-includes\fP (for Clang) to
|
|
the compiler. This will cause the compiler to leave the macros and other
|
|
preprocessor information, and only process the \fB#include\fP directives. When run
|
|
in this way, the preprocessor arguments will be passed to the compiler since it
|
|
still has to do \fIsome\fP preprocessing (like macros).
|
|
.sp
|
|
This option is ignored with MSVC, as there is no way to make it compile without
|
|
preprocessing first.
|
|
.RE
|
|
.sp
|
|
\fBsloppiness\fP (\fBCCACHE_SLOPPINESS\fP)
|
|
.RS 4
|
|
By default, ccache tries to give as few false cache hits as possible.
|
|
However, in certain situations it\(cqs possible that you know things that
|
|
ccache can\(cqt take for granted. This option makes it possible to tell
|
|
ccache to relax some checks in order to increase the hit rate. The value
|
|
should be a comma\-separated string with one or several of the following
|
|
values:
|
|
.sp
|
|
\fBclang_index_store\fP
|
|
.RS 4
|
|
Ignore the Clang compiler option \fB\-index\-store\-path\fP and its argument when
|
|
computing the manifest hash. This is useful if you use Xcode, which uses an
|
|
index store path derived from the local project path. Note that the index
|
|
store won\(cqt be updated correctly on cache hits if you enable this
|
|
sloppiness.
|
|
.RE
|
|
.sp
|
|
\fBfile_stat_matches\fP
|
|
.RS 4
|
|
Ccache normally examines a file\(cqs contents to determine whether it matches
|
|
the cached version. With this sloppiness set, ccache will consider a file
|
|
as matching its cached version if the mtimes and ctimes match.
|
|
.RE
|
|
.sp
|
|
\fBfile_stat_matches_ctime\fP
|
|
.RS 4
|
|
Ignore ctimes when \fBfile_stat_matches\fP is enabled. This can be useful when
|
|
backdating files\*(Aq mtimes in a controlled way.
|
|
.RE
|
|
.sp
|
|
\fBgcno_cwd\fP
|
|
.RS 4
|
|
By default, ccache will include the current working directory in the hash
|
|
when producing a \fB.gcno\fP file (when compiling with \fB\-ftest\-coverage\fP or
|
|
\fB\-\-coverage\fP). This is because GCC 9+ includes the current working directory
|
|
in the \fB.gcno\fP file. The \fBgcno_cwd\fP sloppiness makes ccache not hash the
|
|
current working directory so that you can get cache hits when compiling in
|
|
different directories, with the tradeoff of potentially getting an incorrect
|
|
directory in the \fB.gcno\fP file. \fBgcno_cwd\fP also disables hashing of the
|
|
current working directory if \fB\-fprofile\-abs\-path\fP is used.
|
|
.RE
|
|
.sp
|
|
\fBinclude_file_ctime\fP
|
|
.RS 4
|
|
By default, ccache will disable the direct mode if an include file has too
|
|
new ctime. This sloppiness disables that check. See also \fI[Handling of
|
|
newly created header files]\fP.
|
|
.RE
|
|
.sp
|
|
\fBinclude_file_mtime\fP
|
|
.RS 4
|
|
By default, ccache will disable the direct mode if an include file has too
|
|
new mtime. This sloppiness disables that check. See also \fI[Handling of
|
|
newly created header files]\fP.
|
|
.RE
|
|
.sp
|
|
\fBivfsoverlay\fP
|
|
.RS 4
|
|
Ignore the Clang compiler option \fB\-ivfsoverlay\fP and its argument. This is
|
|
useful if you use Xcode, which uses a virtual file system (VFS) for things
|
|
like combining Objective\-C and Swift code.
|
|
.RE
|
|
.sp
|
|
\fBlocale\fP
|
|
.RS 4
|
|
Ccache includes the environment variables \fBLANG\fP, \fBLC_ALL\fP, \fBLC_CTYPE\fP and
|
|
\fBLC_MESSAGES\fP in the hash by default since they may affect localization of
|
|
compiler warning messages. Set this sloppiness to tell ccache not to do
|
|
that.
|
|
.RE
|
|
.sp
|
|
\fBmodules\fP
|
|
.RS 4
|
|
By default, ccache will not cache compilations if \fB\-fmodules\fP is used since
|
|
it cannot hash the state of compiler\(cqs internal representation of relevant
|
|
modules. This sloppiness allows caching in such a case. See
|
|
\fIC++ MODULES\fP for more information.
|
|
.RE
|
|
.sp
|
|
\fBpch_defines\fP
|
|
.RS 4
|
|
Be sloppy about \fB#define\fP directives when precompiling a header file. See
|
|
\fIPRECOMPILED HEADERS\fP for more information.
|
|
.RE
|
|
.sp
|
|
\fBrandom_seed\fP
|
|
.RS 4
|
|
Ignore the \fB\-frandom\-seed\fP option and its arguments when computing the input
|
|
hash. This is useful if your build system generates different seeds between
|
|
builds and you are OK with reusing cached results.
|
|
.RE
|
|
.sp
|
|
\fBsystem_headers\fP
|
|
.RS 4
|
|
By default, ccache will also include all system headers in the manifest.
|
|
With this sloppiness set, ccache will only include system headers in the
|
|
hash but not add the system header files to the list of include files.
|
|
.RE
|
|
.sp
|
|
\fBtime_macros\fP
|
|
.RS 4
|
|
Ignore \fB__DATE__\fP, \fB__TIME__\fP and \fB__TIMESTAMP__\fP being present in the
|
|
source code.
|
|
.RE
|
|
.sp
|
|
See the discussion under \fITROUBLESHOOTING\fP for more information.
|
|
.RE
|
|
.sp
|
|
\fBstats\fP (\fBCCACHE_STATS\fP or \fBCCACHE_NOSTATS\fP, see \fIBoolean values\fP above)
|
|
.RS 4
|
|
If true, ccache will update the statistics counters on each compilation. The
|
|
default is true. If false, \fI[automatic cleanup]\fP will be disabled as well.
|
|
.RE
|
|
.sp
|
|
\fBstats_log\fP (\fBCCACHE_STATSLOG\fP)
|
|
.RS 4
|
|
If set to a file path, ccache will write statistics counter updates to the
|
|
specified file. This is useful for getting statistics for individual builds.
|
|
To show a summary of the current stats log, use \fBccache \-\-show\-log\-stats\fP.
|
|
.if n .sp
|
|
.RS 4
|
|
.it 1 an-trap
|
|
.nr an-no-space-flag 1
|
|
.nr an-break-flag 1
|
|
.br
|
|
.ps +1
|
|
.B Note
|
|
.ps -1
|
|
.br
|
|
.sp
|
|
Lines in the stats log starting with a hash sign (\fB#\fP) are comments.
|
|
.sp .5v
|
|
.RE
|
|
.RE
|
|
.sp
|
|
\fBtemporary_dir\fP (\fBCCACHE_TEMPDIR\fP)
|
|
.RS 4
|
|
This option specifies where ccache will put temporary files. The default is
|
|
\fB$XDG_RUNTIME_DIR/ccache\-tmp\fP (typically \fB/run/user/<UID>/ccache\-tmp\fP) if
|
|
\fBXDG_RUNTIME_DIR\fP is set and the directory exists, otherwise
|
|
\fB<cache_dir>/tmp\fP.
|
|
.if n .sp
|
|
.RS 4
|
|
.it 1 an-trap
|
|
.nr an-no-space-flag 1
|
|
.nr an-break-flag 1
|
|
.br
|
|
.ps +1
|
|
.B Note
|
|
.ps -1
|
|
.br
|
|
.sp
|
|
In previous versions of ccache, \fBCCACHE_TEMPDIR\fP had to be on the same
|
|
filesystem as the \fBCCACHE_DIR\fP path, but this requirement has been relaxed.
|
|
.sp .5v
|
|
.RE
|
|
.RE
|
|
.sp
|
|
\fBumask\fP (\fBCCACHE_UMASK\fP)
|
|
.RS 4
|
|
This option (an octal integer) specifies the umask for files and directories
|
|
in the cache directory. This is mostly useful when you wish to share your
|
|
cache with other users.
|
|
.RE
|
|
.SS "Disabling ccache"
|
|
.sp
|
|
To disable ccache completely for all invocations, set \fBdisable
|
|
= true\fP (\fBCCACHE_DISABLE=1\fP). You can also disable ccache for a certain source
|
|
code file by adding the string \fBccache:disable\fP in a comment in the first 4096
|
|
bytes of the file. In the latter case the \fBCcache disabled\fP statistics counter
|
|
will be increased.
|
|
.SH "REMOTE STORAGE BACKENDS"
|
|
.sp
|
|
The \fBremote_storage\fP option lets you configure ccache
|
|
to use one or several remote storage backends. By default, the local cache
|
|
directory located in \fBcache_dir\fP will be queried first and
|
|
remote storage second, but \fBremote_only\fP can be set to
|
|
true to disable local storage. Note that cache statistics counters will still be
|
|
kept in the local cache directory \(em remote storage backends only store
|
|
compilation results and manifests.
|
|
.sp
|
|
A remote storage backend is specified with a URL, optionally followed by a pipe
|
|
(\fB|\fP) and a pipe\-separated list of attributes. An attribute is \fIkey\fP=\fIvalue\fP or
|
|
just \fIkey\fP as a short form of \fIkey\fP=\fBtrue\fP. Attribute values must be
|
|
.URL "https://en.wikipedia.org/wiki/Percent\-encoding" "percent\-encoded" ""
|
|
if they contain
|
|
percent, pipe or space characters.
|
|
.SS "Attributes for all backends"
|
|
.sp
|
|
These optional attributes are available for all remote storage backends:
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
\fBread\-only\fP: If \fBtrue\fP, only read from this backend, don\(cqt write. The default
|
|
is \fBfalse\fP.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
\fBshards\fP: A comma\-separated list of names for sharding (partitioning) the
|
|
cache entries using
|
|
.URL "https://en.wikipedia.org/wiki/Rendezvous_hashing" "Rendezvous hashing" ","
|
|
typically to spread the cache over a server cluster. When set, the storage URL
|
|
must contain an asterisk (\fB*\fP), which will be replaced by one of the shard
|
|
names to form a real URL. A shard name can optionally have an appended weight
|
|
within parentheses to indicate how much of the key space should be associated
|
|
with that shard. A shard with weight \fBw\fP will contain \fBw\fP/\fBS\fP of the cache,
|
|
where \fBS\fP is the sum of all shard weights. A weight could for instance be set
|
|
to represent the available memory for a memory cache on a specific server. The
|
|
default weight is \fB1\fP.
|
|
.sp
|
|
Examples:
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
\fBredis://cache\-*.example.com|shards=a(3),b(1),c(1.5)\fP will put 55% (3/5.5)
|
|
of the cache on \fBredis://cache\-a.example.com\fP, 18% (1/5.5) on
|
|
\fBredis://cache\-b.example.com\fP and 27% (1.5/5.5) on
|
|
\fBredis://cache\-c.example.com\fP.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
\fBhttp://example.com/*|shards=alpha,beta\fP will put 50% of the cache on
|
|
\fBhttp://example.com/alpha\fP and 50% on \fBhttp://example.com/beta\fP.
|
|
.RE
|
|
.RE
|
|
.SS "Storage interaction"
|
|
.sp
|
|
The table below describes the interaction between local and remote storage on
|
|
cache hits and misses if \fBremote_only\fP is false (which is
|
|
the default):
|
|
.TS
|
|
allbox tab(:);
|
|
lt lt lt.
|
|
T{
|
|
.sp
|
|
\fBLocal storage\fP
|
|
T}:T{
|
|
.sp
|
|
\fBRemote storage\fP
|
|
T}:T{
|
|
.sp
|
|
\fBWhat happens\fP
|
|
T}
|
|
T{
|
|
.sp
|
|
miss
|
|
T}:T{
|
|
.sp
|
|
miss
|
|
T}:T{
|
|
.sp
|
|
Compile, write to local, write to remote[1]
|
|
T}
|
|
T{
|
|
.sp
|
|
miss
|
|
T}:T{
|
|
.sp
|
|
hit
|
|
T}:T{
|
|
.sp
|
|
Read from remote, write to local
|
|
T}
|
|
T{
|
|
.sp
|
|
hit
|
|
T}:T{
|
|
.sp
|
|
\-
|
|
T}:T{
|
|
.sp
|
|
Read from local, don\(cqt write to remote[2]
|
|
T}
|
|
.TE
|
|
.sp
|
|
.sp
|
|
[1] Unless remote storage has attribute \fBread\-only=true\fP.
|
|
.br
|
|
[2] Unless local storage is set to share its cache hits with the
|
|
\fBreshare\fP option.
|
|
.sp
|
|
If \fBremote_only\fP is true:
|
|
.TS
|
|
allbox tab(:);
|
|
lt lt lt.
|
|
T{
|
|
.sp
|
|
\fBLocal storage\fP
|
|
T}:T{
|
|
.sp
|
|
\fBRemote storage\fP
|
|
T}:T{
|
|
.sp
|
|
\fBWhat happens\fP
|
|
T}
|
|
T{
|
|
.sp
|
|
\-
|
|
T}:T{
|
|
.sp
|
|
miss
|
|
T}:T{
|
|
.sp
|
|
Compile, write to remote, don\(cqt write to local
|
|
T}
|
|
T{
|
|
.sp
|
|
\-
|
|
T}:T{
|
|
.sp
|
|
hit
|
|
T}:T{
|
|
.sp
|
|
Read from remote, don\(cqt write to local
|
|
T}
|
|
.TE
|
|
.sp
|
|
.SS "File storage backend"
|
|
.sp
|
|
URL format: \fBfile:DIRECTORY\fP or \fBfile://[HOST]DIRECTORY\fP
|
|
.sp
|
|
This backend stores data as separate files in a directory structure below
|
|
\fBDIRECTORY\fP, similar (but not identical) to the local cache storage. A typical
|
|
use case for this backend would be sharing a cache on an NFS directory.
|
|
\fBDIRECTORY\fP must start with a slash. \fBHOST\fP can be the empty string or
|
|
localhost. On Windows, \fBHOST\fP can also be the name of a server hosting a shared
|
|
folder.
|
|
.if n .sp
|
|
.RS 4
|
|
.it 1 an-trap
|
|
.nr an-no-space-flag 1
|
|
.nr an-break-flag 1
|
|
.br
|
|
.ps +1
|
|
.B Important
|
|
.ps -1
|
|
.br
|
|
.sp
|
|
ccache will not perform any cleanup of the storage \(em that has to be
|
|
done by other means, for instance by running \fBccache \-\-trim\-dir\fP periodically.
|
|
.sp .5v
|
|
.RE
|
|
.sp
|
|
Examples:
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
\fBfile:/shared/nfs/directory\fP
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
\fBfile:///shared/nfs/directory|umask=002|update\-mtime=true\fP
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
\fBfile://example.com/shared/folder\fP
|
|
.RE
|
|
.sp
|
|
Optional attributes:
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
\fBlayout\fP: How to store file under the cache directory. Available values:
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
\fBflat\fP: Store all files directly under the cache directory.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
\fBsubdirs\fP: Store files in 256 subdirectories of the cache directory.
|
|
.RE
|
|
.sp
|
|
The default is \fBsubdirs\fP.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
\fBumask\fP: This attribute (an octal integer) overrides the umask to use for
|
|
files and directories in the cache directory.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
\fBupdate\-mtime\fP: If \fBtrue\fP, update the modification time (mtime) of cache
|
|
entries that are read. The default is \fBfalse\fP.
|
|
.RE
|
|
.SS "HTTP storage backend"
|
|
.sp
|
|
URL format: \fBhttp://HOST[:PORT][/PATH]\fP
|
|
.sp
|
|
This backend stores data in an HTTP\-compatible server. The required HTTP methods
|
|
are \fBGET\fP, \fBPUT\fP and \fBDELETE\fP.
|
|
.if n .sp
|
|
.RS 4
|
|
.it 1 an-trap
|
|
.nr an-no-space-flag 1
|
|
.nr an-break-flag 1
|
|
.br
|
|
.ps +1
|
|
.B Important
|
|
.ps -1
|
|
.br
|
|
.sp
|
|
ccache will not perform any cleanup of the storage \(em that has to be
|
|
done by other means, for instance by running \fBccache \-\-trim\-dir\fP periodically.
|
|
.sp .5v
|
|
.RE
|
|
.if n .sp
|
|
.RS 4
|
|
.it 1 an-trap
|
|
.nr an-no-space-flag 1
|
|
.nr an-break-flag 1
|
|
.br
|
|
.ps +1
|
|
.B Note
|
|
.ps -1
|
|
.br
|
|
.sp
|
|
HTTPS is not supported.
|
|
.sp .5v
|
|
.RE
|
|
.if n .sp
|
|
.RS 4
|
|
.it 1 an-trap
|
|
.nr an-no-space-flag 1
|
|
.nr an-break-flag 1
|
|
.br
|
|
.ps +1
|
|
.B Tip
|
|
.ps -1
|
|
.br
|
|
.sp
|
|
See \c
|
|
.URL "https://ccache.dev/howto/http\-storage.html" "How to set up HTTP storage"
|
|
for hints on how to set up an HTTP server for use with ccache.
|
|
.sp .5v
|
|
.RE
|
|
.sp
|
|
Examples:
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
\fBhttp://localhost\fP
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
\fBhttp://someusername:p4ssw0rd@example.com/cache/\fP
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
\fBhttp://localhost:8080|layout=bazel|connect\-timeout=50\fP
|
|
.RE
|
|
.sp
|
|
Optional attributes:
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
\fBbearer\-token\fP: Bearer token used to authorize the HTTP requests.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
\fBconnect\-timeout\fP: Timeout (in ms) for network connection. The default is 100.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
\fBkeep\-alive\fP: If \fBtrue\fP, keep the HTTP connection to the storage server open
|
|
to avoid reconnects. The default is \fBtrue\fP.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
\fBlayout\fP: How to map key names to the path part of the URL. Available values:
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
\fBbazel\fP: Store values in a format compatible with the Bazel HTTP caching
|
|
protocol. More specifically, the entries will be stored as 64 hex digits
|
|
under the \fB/ac/\fP part of the cache.
|
|
.if n .sp
|
|
.RS 4
|
|
.it 1 an-trap
|
|
.nr an-no-space-flag 1
|
|
.nr an-break-flag 1
|
|
.br
|
|
.ps +1
|
|
.B Note
|
|
.ps -1
|
|
.br
|
|
.sp
|
|
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.
|
|
.sp .5v
|
|
.RE
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
\fBflat\fP: Append the key directly to the path part of the URL (with a leading
|
|
slash if needed).
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
\fBsubdirs\fP: Append the first two characters of the key to the URL (with a
|
|
leading slash if needed), followed by a slash and the rest of the key. This
|
|
divides the entries into 256 buckets.
|
|
.RE
|
|
.sp
|
|
The default is \fBsubdirs\fP.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
\fBoperation\-timeout\fP: Timeout (in ms) for HTTP requests. The default is 10000.
|
|
.RE
|
|
.SS "Redis storage backend"
|
|
.sp
|
|
URL formats:
|
|
.sp
|
|
\fBredis://[[USERNAME:]PASSWORD@]HOST[:PORT][/DBNUMBER]\fP
|
|
.br
|
|
\fBredis+unix:SOCKET_PATH[?db=DBNUMBER]\fP
|
|
.br
|
|
\fBredis+unix://[[USERNAME:]PASSWORD@localhost]SOCKET_PATH[?db=DBNUMBER]\fP
|
|
.sp
|
|
This backend stores data in a \c
|
|
.URL "https://redis.io" "Redis" ""
|
|
(or Redis\-compatible)
|
|
server. There are implementations for both memory\-based and disk\-based storage.
|
|
\fBPORT\fP defaults to \fB6379\fP and \fBDBNUMBER\fP defaults to \fB0\fP.
|
|
.if n .sp
|
|
.RS 4
|
|
.it 1 an-trap
|
|
.nr an-no-space-flag 1
|
|
.nr an-break-flag 1
|
|
.br
|
|
.ps +1
|
|
.B Note
|
|
.ps -1
|
|
.br
|
|
.sp
|
|
ccache will not perform any cleanup of the Redis storage, but you can
|
|
.URL "https://redis.io/topics/lru\-cache" "configure LRU eviction" "."
|
|
.sp .5v
|
|
.RE
|
|
.if n .sp
|
|
.RS 4
|
|
.it 1 an-trap
|
|
.nr an-no-space-flag 1
|
|
.nr an-break-flag 1
|
|
.br
|
|
.ps +1
|
|
.B Tip
|
|
.ps -1
|
|
.br
|
|
.sp
|
|
See \c
|
|
.URL "https://ccache.dev/howto/redis\-storage.html" "How to set up Redis
|
|
storage" for hints on setting up a Redis server for use with ccache.
|
|
.sp .5v
|
|
.RE
|
|
.if n .sp
|
|
.RS 4
|
|
.it 1 an-trap
|
|
.nr an-no-space-flag 1
|
|
.nr an-break-flag 1
|
|
.br
|
|
.ps +1
|
|
.B Tip
|
|
.ps -1
|
|
.br
|
|
.sp
|
|
You can set up a cluster of Redis servers using the \fBshards\fP attribute
|
|
described in \fIREMOTE STORAGE BACKENDS\fP.
|
|
.sp .5v
|
|
.RE
|
|
.sp
|
|
Examples:
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
\fBredis://localhost\fP
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
\fBredis://p4ssw0rd@cache.example.com:6379/0|connect\-timeout=50\fP
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
\fBredis+unix:/run/redis.sock\fP
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
\fBredis+unix:///run/redis.sock\fP
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
\fBredis+unix://p4ssw0rd@localhost/run/redis.sock?db=0\fP
|
|
.RE
|
|
.sp
|
|
Optional attributes:
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
\fBconnect\-timeout\fP: Timeout (in ms) for network connection. The default is 100.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
\fBoperation\-timeout\fP: Timeout (in ms) for Redis commands. The default is 10000.
|
|
.RE
|
|
.SH "CACHE SIZE MANAGEMENT"
|
|
.sp
|
|
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 \fB\-M\fP/\fB\-\-max\-size\fP and \fB\-F\fP/\fB\-\-max\-files\fP. Use the
|
|
\fB\-s\fP/\fB\-\-show\-stats\fP option to see the cache size and the currently configured
|
|
limits (in addition to other various statistics).
|
|
.sp
|
|
Cleanup can be triggered in two different ways: automatic and manual.
|
|
.SS "Automatic cleanup"
|
|
.sp
|
|
After a new compilation result has been written to the local cache, ccache will
|
|
trigger an automatic cleanup if \fBmax_size\fP or
|
|
\fBmax_files\fP is exceeded. The cleanup removes cache entries
|
|
in LRU (least recently used) order based on the modification time (mtime) of
|
|
files in the cache. For this reason, ccache updates mtime of the cache files
|
|
read on a cache hit to mark them as recently used.
|
|
.SS "Manual cleanup"
|
|
.sp
|
|
You can run \fBccache \-c/\-\-cleanup\fP to force cleanup of the whole cache. This will
|
|
recalculate the cache size information and also make sure that the cache size
|
|
does not exceed \fBmax_size\fP and
|
|
\fBmax_files\fP.
|
|
.SH "CACHE COMPRESSION"
|
|
.sp
|
|
Ccache will by default compress all data it puts into the cache using the
|
|
compression algorithm \c
|
|
.URL "http://zstd.net" "Zstandard" ""
|
|
(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
|
|
\fBcompression\fP and
|
|
\fBcompression_level\fP for more information.
|
|
.sp
|
|
You can use the command line option \fB\-x\fP/\fB\-\-show\-compression\fP to print
|
|
information related to compression. Example:
|
|
.sp
|
|
.if n .RS 4
|
|
.nf
|
|
.fam C
|
|
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
|
|
.fam
|
|
.fi
|
|
.if n .RE
|
|
.sp
|
|
Notes:
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
The \(lqdisk blocks\(rq size is the cache size when taking disk block size into
|
|
account. This value should match the \(lqCache size\(rq value from \(lqccache
|
|
\-\-show\-stats\(rq. The other size numbers refer to actual content sizes.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
\(lqCompressed data\(rq refers to result and manifest files stored in the cache.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
\(lqIncompressible data\(rq refers to files that are always stored uncompressed
|
|
(triggered by enabling \fBfile_clone\fP or
|
|
\fBhard_link\fP) or unknown files (for instance files
|
|
created by older ccache versions).
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
The compression ratio is affected by
|
|
\fBcompression_level\fP.
|
|
.RE
|
|
.sp
|
|
The cache data can also be recompressed to another compression level (or made
|
|
uncompressed) with the command line option \fB\-X\fP/\fB\-\-recompress\fP. 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.
|
|
.SH "CACHE STATISTICS"
|
|
.sp
|
|
\fBccache \-\-show\-stats\fP 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 \fBccache \-c\fP calls), overall hit rate, hit
|
|
rate for direct/preprocessed modes
|
|
and hit rate for local and remote storage.
|
|
.sp
|
|
The summary also includes counters called \(lqErrors\(rq and \(lqUncacheable\(rq, which
|
|
are sums of more detailed counters. To see those detailed counters, use the
|
|
\fB\-v\fP/\fB\-\-verbose\fP flag. The verbose mode can show the following counters:
|
|
.TS
|
|
allbox tab(:);
|
|
lt lt.
|
|
T{
|
|
.sp
|
|
\fBCounter\fP
|
|
T}:T{
|
|
.sp
|
|
\fBDescription\fP
|
|
T}
|
|
T{
|
|
.sp
|
|
Autoconf compile/link
|
|
T}:T{
|
|
.sp
|
|
Uncacheable compilation or linking by an Autoconf test.
|
|
T}
|
|
T{
|
|
.sp
|
|
Bad compiler arguments
|
|
T}:T{
|
|
.sp
|
|
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.
|
|
T}
|
|
T{
|
|
.sp
|
|
Called for linking
|
|
T}:T{
|
|
.sp
|
|
The compiler was called for linking, not compiling. Ccache only supports
|
|
compilation of a single file, i.e. calling the compiler with the \fB\-c\fP option to
|
|
produce a single object file from a single source file.
|
|
T}
|
|
T{
|
|
.sp
|
|
Called for preprocessing
|
|
T}:T{
|
|
.sp
|
|
The compiler was called for preprocessing, not compiling.
|
|
T}
|
|
T{
|
|
.sp
|
|
Ccache disabled
|
|
T}:T{
|
|
.sp
|
|
Ccache was disabled by a \fBccache:disable\fP string in the source code file.
|
|
T}
|
|
T{
|
|
.sp
|
|
Could not use modules
|
|
T}:T{
|
|
.sp
|
|
Preconditions for using C++ MODULES were not fulfilled.
|
|
T}
|
|
T{
|
|
.sp
|
|
Could not use precompiled header
|
|
T}:T{
|
|
.sp
|
|
Preconditions for using precompiled headers were not
|
|
fulfilled.
|
|
T}
|
|
T{
|
|
.sp
|
|
Could not write to output file
|
|
T}:T{
|
|
.sp
|
|
The output path specified with \fB\-o\fP could not be written to.
|
|
T}
|
|
T{
|
|
.sp
|
|
Compilation failed
|
|
T}:T{
|
|
.sp
|
|
The compilation failed. No result stored in the cache.
|
|
T}
|
|
T{
|
|
.sp
|
|
Compiler check failed
|
|
T}:T{
|
|
.sp
|
|
A compiler check program specified by
|
|
\fBcompiler_check\fP (\fBCCACHE_COMPILERCHECK\fP) failed.
|
|
T}
|
|
T{
|
|
.sp
|
|
Compiler output file missing
|
|
T}:T{
|
|
.sp
|
|
One of the files expected to be produced by the compiler was missing after
|
|
compilation.
|
|
T}
|
|
T{
|
|
.sp
|
|
Compiler produced empty output
|
|
T}:T{
|
|
.sp
|
|
The compiler\(cqs output file (typically an object file) was empty after
|
|
compilation.
|
|
T}
|
|
T{
|
|
.sp
|
|
Could not find the compiler
|
|
T}:T{
|
|
.sp
|
|
The compiler to execute could not be found.
|
|
T}
|
|
T{
|
|
.sp
|
|
Error hashing extra file
|
|
T}:T{
|
|
.sp
|
|
Failure reading a file specified by
|
|
\fBextra_files_to_hash\fP (\fBCCACHE_EXTRAFILES\fP).
|
|
T}
|
|
T{
|
|
.sp
|
|
Forced recache
|
|
T}:T{
|
|
.sp
|
|
\fBCCACHE_RECACHE\fP was used to overwrite an existing result.
|
|
T}
|
|
T{
|
|
.sp
|
|
Internal error
|
|
T}:T{
|
|
.sp
|
|
Unexpected failure, e.g. due to problems reading/writing the cache.
|
|
T}
|
|
T{
|
|
.sp
|
|
Missing cache file
|
|
T}:T{
|
|
.sp
|
|
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.
|
|
T}
|
|
T{
|
|
.sp
|
|
Multiple source files
|
|
T}:T{
|
|
.sp
|
|
The compiler was called to compile multiple source files in one go. This is not
|
|
supported by ccache.
|
|
T}
|
|
T{
|
|
.sp
|
|
No input file
|
|
T}:T{
|
|
.sp
|
|
No input file was specified to the compiler.
|
|
T}
|
|
T{
|
|
.sp
|
|
Output to stdout
|
|
T}:T{
|
|
.sp
|
|
The compiler was instructed to write its output to standard output using \fB\-o \-\fP.
|
|
This is not supported by ccache.
|
|
T}
|
|
T{
|
|
.sp
|
|
Preprocessing failed
|
|
T}:T{
|
|
.sp
|
|
Preprocessing the source code using the compiler\(cqs \fB\-E\fP option failed.
|
|
T}
|
|
T{
|
|
.sp
|
|
Unsupported code directive
|
|
T}:T{
|
|
.sp
|
|
Code like the assembler \fB.incbin\fP directive was found. This is not supported
|
|
by ccache.
|
|
T}
|
|
T{
|
|
.sp
|
|
Unsupported compiler option
|
|
T}:T{
|
|
.sp
|
|
A compiler option not supported by ccache was found.
|
|
T}
|
|
T{
|
|
.sp
|
|
Unsupported environment variable
|
|
T}:T{
|
|
.sp
|
|
An environment variable not supported by ccache was set.
|
|
T}
|
|
T{
|
|
.sp
|
|
Unsupported source language
|
|
T}:T{
|
|
.sp
|
|
A source language e.g. specified with \fB\-x\fP was unsupported by ccache.
|
|
T}
|
|
.TE
|
|
.sp
|
|
.SH "HOW CCACHE WORKS"
|
|
.sp
|
|
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.
|
|
.sp
|
|
Ccache has two ways of gathering information used to look up results in the
|
|
cache:
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
the \fBpreprocessor mode\fP, where ccache runs the preprocessor on the source
|
|
code and hashes the result
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
the \fBdirect mode\fP, where ccache hashes the source code and include files
|
|
directly
|
|
.RE
|
|
.sp
|
|
The direct mode is generally faster since running the preprocessor has some
|
|
overhead.
|
|
.sp
|
|
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 \fBdepend mode\fP is
|
|
enabled. In the depend mode, ccache never runs the preprocessor, not even on
|
|
cache misses. Read more in \fIThe depend mode\fP below.
|
|
.SS "Common hashed information"
|
|
.sp
|
|
The following information is always included in the hash:
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
the extension used by the compiler for a file with preprocessor output
|
|
(normally \fB.i\fP for C code and \fB.ii\fP for C++ code)
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
the compiler\(cqs size and modification time (or other compiler\-specific
|
|
information specified by \fBcompiler_check\fP)
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
the name of the compiler
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
the current directory (if \fBhash_dir\fP is enabled)
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
contents of files specified by
|
|
\fBextra_files_to_hash\fP (if any)
|
|
.RE
|
|
.SS "The preprocessor mode"
|
|
.sp
|
|
In the preprocessor mode, the hash is formed of the common information and:
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
the preprocessor output from running the compiler with \fB\-E\fP
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
the command line options except those that affect include files (\fB\-I\fP,
|
|
\fB\-include\fP, \fB\-D\fP, etc; the theory is that these command line options will
|
|
change the preprocessor output if they have any effect at all)
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
any standard error output generated by the preprocessor
|
|
.RE
|
|
.sp
|
|
Based on the hash, the cached compilation result can be looked up directly in
|
|
the cache.
|
|
.SS "The direct mode"
|
|
.sp
|
|
In the direct mode, the hash is formed of the common information and:
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
the input source file
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
the compiler options
|
|
.RE
|
|
.sp
|
|
Based on the hash, a data structure called \(lqmanifest\(rq is looked up in the
|
|
cache. The manifest contains:
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
references to cached compilation results (object file, dependency file, etc)
|
|
that were produced by previous compilations that matched the hash
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
paths to the include files that were read at the time the compilation results
|
|
were stored in the cache
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
hash sums of the include files at the time the compilation results were
|
|
stored in the cache
|
|
.RE
|
|
.sp
|
|
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.
|
|
.sp
|
|
There is a catch with the direct mode: header files that were used by the
|
|
compiler are recorded, but header files that were \fBnot\fP 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\(cqt 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.
|
|
.sp
|
|
The direct mode will be disabled if any of the following holds:
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
\fBdirect_mode\fP is false
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
a modification time of one of the include files is too new (needed to avoid a
|
|
race condition)
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
a compiler option not supported by the direct mode is used:
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
a \fB\-Wp,*\fP compiler option other than \fB\-Wp,\-MD,<path>\fP, \fB\-Wp,\-MMD,<path>\fP,
|
|
\fB\-Wp,\-D<macro[=defn]>\fP or \fB\-Wp,\-U<macro>\fP
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
\fB\-Xpreprocessor\fP
|
|
.RE
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
the string \fB__TIME__\fP is present in the source code
|
|
.RE
|
|
.SS "The depend mode"
|
|
.sp
|
|
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 list generated by MSVC with \fB/showIncludes\fP, or the dependency file
|
|
generated by other compilers with \fB\-MD\fP or \fB\-MMD\fP.
|
|
.sp
|
|
Advantages:
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
The ccache overhead of a cache miss will be much smaller.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
Not running the preprocessor at all can be good if compilation is performed
|
|
remotely, for instance when using distcc or similar; ccache then won\(cqt make
|
|
potentially costly preprocessor calls on the local machine.
|
|
.RE
|
|
.sp
|
|
Disadvantages:
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
The cache hit rate will likely be lower since any change to compiler options
|
|
or source code will make the hash different. Compare this with the default
|
|
setup where ccache will fall back to the preprocessor mode, which is tolerant
|
|
to some types of changes of compiler options and source code changes.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
If \fB\-MD\fP is used, the manifest entries will include system header files as
|
|
well, thus slowing down cache hits slightly, just as using \fB\-MD\fP slows down
|
|
make. This is also the case for MSVC with \fB/showIncludes\fP.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
If \fB\-MMD\fP is used, the manifest entries will not include system header files,
|
|
which means ccache will ignore changes in them.
|
|
.RE
|
|
.sp
|
|
The depend mode will be disabled if any of the following holds:
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
\fBdepend_mode\fP is false.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
\fBrun_second_cpp\fP is false.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
The compiler is not generating dependencies using \fB\-MD\fP or \fB\-MMD\fP (for MSVC,
|
|
\fB/showIncludes\fP is added automatically if not specified by the user).
|
|
.RE
|
|
.SH "HANDLING OF NEWLY CREATED HEADER FILES"
|
|
.sp
|
|
If modification time (mtime) or status change time (ctime) of one of the include
|
|
files is equal to (or newer than) 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).
|
|
.sp
|
|
To be able to use a newly created header files in direct mode (or use a newly
|
|
precompiled header), either:
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
create the include file earlier in the build process, or
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
set \fBsloppiness\fP to
|
|
\fBinclude_file_ctime,include_file_mtime\fP if you are willing to take the risk,
|
|
for instance if you know that your build system is robust enough not to
|
|
trigger the race condition.
|
|
.RE
|
|
.sp
|
|
For reference, the race condition mentioned above consists of these events:
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04' 1.\h'+01'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP " 1." 4.2
|
|
.\}
|
|
The preprocessor is run.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04' 2.\h'+01'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP " 2." 4.2
|
|
.\}
|
|
An include file is modified by someone.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04' 3.\h'+01'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP " 3." 4.2
|
|
.\}
|
|
The new include file is hashed by ccache.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04' 4.\h'+01'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP " 4." 4.2
|
|
.\}
|
|
The real compiler is run on the preprocessor\(cqs output, which contains data
|
|
from the old header file.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04' 5.\h'+01'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP " 5." 4.2
|
|
.\}
|
|
The wrong object file is stored in the cache.
|
|
.RE
|
|
.SH "CACHE DEBUGGING"
|
|
.sp
|
|
To find out what information ccache actually is hashing, you can enable the
|
|
debug mode via the configuration option \fBdebug\fP or by setting
|
|
\fBCCACHE_DEBUG\fP in the environment. This can be useful if you are investigating
|
|
why you don\(cqt get cache hits. Note that performance will be reduced slightly.
|
|
.sp
|
|
When the debug mode is enabled, ccache will create up to five additional files
|
|
next to the object file:
|
|
.TS
|
|
allbox tab(:);
|
|
lt lt.
|
|
T{
|
|
.sp
|
|
\fBFilename\fP
|
|
T}:T{
|
|
.sp
|
|
\fBDescription\fP
|
|
T}
|
|
T{
|
|
.sp
|
|
\fB<objectfile>.<timestamp>.ccache\-input\-c\fP
|
|
T}:T{
|
|
.sp
|
|
Binary input hashed by both the direct mode and the preprocessor mode.
|
|
T}
|
|
T{
|
|
.sp
|
|
\fB<objectfile>.<timestamp>.ccache\-input\-d\fP
|
|
T}:T{
|
|
.sp
|
|
Binary input only hashed by the direct mode.
|
|
T}
|
|
T{
|
|
.sp
|
|
\fB<objectfile>.<timestamp>.ccache\-input\-p\fP
|
|
T}:T{
|
|
.sp
|
|
Binary input only hashed by the preprocessor mode.
|
|
T}
|
|
T{
|
|
.sp
|
|
\fB<objectfile>.<timestamp>.ccache\-input\-text\fP
|
|
T}:T{
|
|
.sp
|
|
Human\-readable combined diffable text version of the three files above.
|
|
T}
|
|
T{
|
|
.sp
|
|
\fB<objectfile>.<timestamp>.ccache\-log\fP
|
|
T}:T{
|
|
.sp
|
|
Log for this object file.
|
|
T}
|
|
.TE
|
|
.sp
|
|
.sp
|
|
.if n .RS 4
|
|
.nf
|
|
.fam C
|
|
The timestamp format is
|
|
`<year><month><day>_<hour><minute><second>_<microsecond>`.
|
|
.fam
|
|
.fi
|
|
.if n .RE
|
|
.sp
|
|
If \fBdebug_dir\fP (environment variable \fBCCACHE_DEBUGDIR\fP) is
|
|
set, the files above will be written to that directory with full absolute paths
|
|
instead of next to the object file.
|
|
.sp
|
|
In the direct mode, ccache uses the 160 bit BLAKE3 hash of the
|
|
\(lqccache\-input\-c\(rq + \(lqccache\-input\-d\(rq data (where \fB+\fP means concatenation),
|
|
while the \(lqccache\-input\-c\(rq + \(lqccache\-input\-p\(rq data is used in the
|
|
preprocessor mode.
|
|
.sp
|
|
The \(lqccache\-input\-text\(rq file is a combined text version of the three binary
|
|
input files. It has three sections (\(lqCOMMON\(rq, \(lqDIRECT MODE\(rq and
|
|
\(lqPREPROCESSOR MODE\(rq), which is turn contain annotations that say what kind of
|
|
data comes next.
|
|
.sp
|
|
To debug why you don\(cqt get an expected cache hit for an object file, you can do
|
|
something like this:
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04' 1.\h'+01'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP " 1." 4.2
|
|
.\}
|
|
Enable \fBdebug\fP (\fBCCACHE_DEBUG\fP).
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04' 2.\h'+01'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP " 2." 4.2
|
|
.\}
|
|
Build.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04' 3.\h'+01'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP " 3." 4.2
|
|
.\}
|
|
Clean and build again.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04' 4.\h'+01'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP " 4." 4.2
|
|
.\}
|
|
Compare the \fB<objectfile>.<timestamp>.ccache\-input\-text\fP files for the two
|
|
builds. This together with the \fB<objectfile>.<timestamp>.ccache\-log\fP files
|
|
should give you some clues about what is happening.
|
|
.RE
|
|
.SH "COMPILING IN DIFFERENT DIRECTORIES"
|
|
.sp
|
|
Some information included in the hash that identifies a unique compilation can
|
|
contain absolute paths:
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
The preprocessed source code may contain absolute paths to include files if
|
|
the compiler option \fB\-g\fP is used or if absolute paths are given to \fB\-I\fP and
|
|
similar compiler options.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
Paths specified by compiler options (such as \fB\-I\fP, \fB\-MF\fP, etc) on the command
|
|
line may be absolute.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
The source code file path may be absolute, and that path may substituted for
|
|
\fB__FILE__\fP macros in the source code or included in warnings emitted to
|
|
standard error by the preprocessor.
|
|
.RE
|
|
.sp
|
|
This means that if you compile the same code in different locations, you can\(cqt
|
|
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.
|
|
.sp
|
|
Here\(cqs what can be done to enable cache hits between different build
|
|
directories:
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
If you build with \fB\-g\fP (or similar) to add debug information to the object
|
|
file, you must either:
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
use the compiler option \fB\-fdebug\-prefix\-map=<old>=<new>\fP for relocating
|
|
debug info to a common prefix (e.g. \fB\-fdebug\-prefix\-map=$PWD=.\fP); or
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
set \fBhash_dir = false\fP.
|
|
.RE
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
If you use absolute paths anywhere on the command line (e.g. the source code
|
|
file path or an argument to compiler options like \fB\-I\fP and \fB\-MF\fP), you must
|
|
set \fBbase_dir\fP to an absolute path to a \(lqbase
|
|
directory\(rq. Ccache will then rewrite absolute paths under that directory to
|
|
relative before computing the hash.
|
|
.RE
|
|
.SH "PRECOMPILED HEADERS"
|
|
.sp
|
|
Ccache has support for precompiled headers with GCC and Clang. However, you have
|
|
to do some things to make it work properly:
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
You must set \fBsloppiness\fP to \fBpch_defines,time_macros\fP.
|
|
The reason is that ccache can\(cqt tell whether \fB__TIME__\fP, \fB__DATE__\fP or
|
|
\fB__TIMESTAMP__\fP is used when using a precompiled header. Further, it can\(cqt
|
|
detect changes in \fB#define\fPs in the source code because of how preprocessing
|
|
works in combination with precompiled headers.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
You may also want to include \fBinclude_file_mtime,include_file_ctime\fP in
|
|
\fBsloppiness\fP. See
|
|
\fIHANDLING OF NEWLY CREATED HEADER FILES\fP.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
You must either:
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
use the compiler option \fB\-include\fP to include the precompiled header (i.e.,
|
|
don\(cqt use \fB#include\fP in the source code to include the header; the filename
|
|
itself must be sufficient to find the header, i.e. \fB\-I\fP paths are not
|
|
searched); or
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
(for the Clang compiler) use the compiler option \fB\-include\-pch\fP to include
|
|
the PCH file generated from the precompiled header; or
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
(for the GCC compiler) add the compiler option \fB\-fpch\-preprocess\fP when
|
|
compiling.
|
|
.RE
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
If you use Clang, you must compile with \fB\-fno\-pch\-timestamp\fP.
|
|
.RE
|
|
.sp
|
|
If you don\(cqt 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 \(lqPreprocessing failed\(rq (if the non\-precompiled
|
|
header file is not available).
|
|
.SH "C++ MODULES"
|
|
.sp
|
|
Ccache has support for Clang\(cqs \fB\-fmodules\fP option. In practice ccache only
|
|
additionally hashes \fBmodule.modulemap\fP 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 \fBmodule.modulemap\fP
|
|
files) is the same the cached result should work. Still, you must set
|
|
\fBsloppiness\fP to \fBmodules\fP to allow caching.
|
|
.sp
|
|
You must use both \fBdirect mode\fP and
|
|
\fBdepend mode\fP. When using
|
|
the preprocessor mode Clang does not provide enough
|
|
information to allow hashing of \fBmodule.modulemap\fP files.
|
|
.SH "SHARING A LOCAL CACHE"
|
|
.sp
|
|
A group of developers can increase the cache hit rate by sharing a local cache
|
|
directory. To share a local cache without unpleasant side effects, the following
|
|
conditions should to be met:
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
Use the same cache directory.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
Make sure that the configuration option \fBhard_link\fP is
|
|
false (which is the default).
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
Make sure that all users are in the same group.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
Set the configuration option \fBumask\fP to \fB002\fP. This ensures
|
|
that cached files are accessible to everyone in the group.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
Make sure that all users have write permission in the entire cache directory
|
|
(and that you trust all users of the shared cache).
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
Make sure that the setgid bit is set on all directories in the cache. This
|
|
tells the filesystem to inherit group ownership for new directories. The
|
|
following command might be useful for this:
|
|
.sp
|
|
.if n .RS 4
|
|
.nf
|
|
.fam C
|
|
find $CCACHE_DIR \-type d | xargs chmod g+s
|
|
.fam
|
|
.fi
|
|
.if n .RE
|
|
.RE
|
|
.sp
|
|
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\(cqs 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.
|
|
.sp
|
|
You may also want to make sure that a base directory is set appropriately, as
|
|
discussed in a previous section.
|
|
.SH "SHARING A CACHE ON NFS"
|
|
.sp
|
|
It is possible to put the cache directory on an NFS filesystem (or similar
|
|
filesystems), but keep in mind that:
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
Having the cache on NFS may slow down compilation. Make sure to do some
|
|
benchmarking to see if it\(cqs worth it.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
Ccache hasn\(cqt been tested very thoroughly on NFS.
|
|
.RE
|
|
.sp
|
|
A tip is to set \fBtemporary_dir\fP to a directory on the
|
|
local host to avoid NFS traffic for temporary files.
|
|
.sp
|
|
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
|
|
\fBsloppiness\fP to \fBsystem_headers\fP to ignore system
|
|
headers.
|
|
.sp
|
|
An alternative to putting the main cache directory on NFS is to set up a
|
|
remote storage file cache.
|
|
.SH "USING CCACHE WITH OTHER COMPILER WRAPPERS"
|
|
.sp
|
|
The recommended way of combining ccache with another compiler wrapper (such as
|
|
\(lqdistcc\(rq) is by letting ccache execute the compiler wrapper. This is
|
|
accomplished by defining \fBprefix_command\fP, for
|
|
example by setting the environment variable \fBCCACHE_PREFIX\fP to the name of the
|
|
wrapper (e.g. \fBdistcc\fP). Ccache will then prefix the command line with the
|
|
specified command when running the compiler. To specify several prefix
|
|
commands, set \fBprefix_command\fP to a colon\-separated
|
|
list of commands.
|
|
.sp
|
|
Unless you set \fBcompiler_check\fP to a suitable command
|
|
(see the description of that configuration option), it is not recommended to use
|
|
the form \fBccache anotherwrapper compiler args\fP as the compilation command. It\(cqs
|
|
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:
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
Compiler upgrades will not be detected properly.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
The cached results will not be shared between compilations with and without
|
|
the other wrapper.
|
|
.RE
|
|
.sp
|
|
Another minor thing is that if \fBprefix_command\fP is
|
|
used, ccache will not invoke the other wrapper when running the preprocessor,
|
|
which increases performance. You can use
|
|
\fBprefix_command_cpp\fP if you also want to invoke
|
|
the other wrapper when doing preprocessing (normally by adding \fB\-E\fP).
|
|
.SH "CAVEATS"
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
The direct mode fails to pick up new header files in some rare scenarios. See
|
|
\fIThe direct mode\fP above.
|
|
.RE
|
|
.SH "TROUBLESHOOTING"
|
|
.SS "General"
|
|
.sp
|
|
A general tip for getting information about what ccache is doing is to enable
|
|
debug logging by setting the configuration option \fBdebug\fP (or
|
|
the environment variable \fBCCACHE_DEBUG\fP); see \fICACHE DEBUGGING\fP
|
|
for more information. Another way of keeping track of what is
|
|
happening is to check the output of \fBccache \-s\fP.
|
|
.SS "Performance"
|
|
.sp
|
|
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.
|
|
.sp
|
|
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.
|
|
.sp
|
|
A good way of monitoring how well ccache works is to run \fBccache \-s\fP 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:
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
If the counter for preprocessed cache hits has been incremented instead of the
|
|
one for direct cache hits, ccache has fallen back to preprocessor mode, which
|
|
is generally slower. Some possible reasons are:
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
The source code has been modified in such a way that the preprocessor output
|
|
is not affected.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
Compiler arguments that are hashed in the direct mode but not in the
|
|
preprocessor mode have changed (\fB\-I\fP, \fB\-include\fP, \fB\-D\fP, etc) and they didn\(cqt
|
|
affect the preprocessor output.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
The compiler option \fB\-Xpreprocessor\fP or \fB\-Wp,*\fP (except \fB\-Wp,\-MD,<path>\fP,
|
|
\fB\-Wp,\-MMD,<path>\fP, and \fB\-Wp,\-D<define>\fP) is used.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
This was the first compilation with a new value of the
|
|
base directory.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
A modification or status change time of one of the include files is too new
|
|
(created the same second as the compilation is being done). See
|
|
\fIHANDLING OF NEWLY CREATED HEADER FILES\fP.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
The \fB__TIME__\fP preprocessor macro is (potentially) being used. Ccache turns
|
|
off direct mode if \fB__TIME__\fP is present in the source code. This is done
|
|
as a safety measure since the string indicates that a \fB__TIME__\fP macro
|
|
\fImay\fP affect the output. (To be sure, ccache would have to run the
|
|
preprocessor, but the sole point of the direct mode is to avoid that.) If you
|
|
know that \fB__TIME__\fP isn\(cqt used in practise, or don\(cqt care if ccache
|
|
produces objects where \fB__TIME__\fP is expanded to something in the past, you
|
|
can set \fBsloppiness\fP to \fBtime_macros\fP.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
The \fB__DATE__\fP preprocessor macro is (potentially) being used and the date
|
|
has changed. This is similar to how \fB__TIME__\fP is handled. If \fB__DATE__\fP
|
|
is present in the source code, ccache hashes the current date in order to be
|
|
able to produce the correct object file if the \fB__DATE__\fP macro affects the
|
|
output. If you know that \fB__DATE__\fP isn\(cqt used in practise, or don\(cqt care
|
|
if ccache produces objects where \fB__DATE__\fP is expanded to something in the
|
|
past, you can set \fBsloppiness\fP to \fBtime_macros\fP.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
The \fB__TIMESTAMP__\fP preprocessor macro is (potentially) being used and the
|
|
source file\(cqs modification time has changed. This is similar to how
|
|
\fB__TIME__\fP is handled. If \fB__TIMESTAMP__\fP is present in the source code,
|
|
ccache hashes the string representation of the source file\(cqs modification
|
|
time in order to be able to produce the correct object file if the
|
|
\fB__TIMESTAMP__\fP macro affects the output. If you know that
|
|
\fB__TIMESTAMP__\fP isn\(cqt used in practise, or don\(cqt care if ccache produces
|
|
objects where \fB__TIMESTAMP__\fP is expanded to something in the past, you can
|
|
set \fBsloppiness\fP to \fBtime_macros\fP.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
The input file path has changed. Ccache includes the input file path in the
|
|
direct mode hash to be able to take relative include files into account and
|
|
to produce a correct object file if the source code includes a \fB__FILE__\fP
|
|
macro.
|
|
.RE
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
If a cache hit counter was not incremented even though the same code has been
|
|
compiled and cached before, ccache has either detected that something has
|
|
changed anyway or a cleanup has been performed (either explicitly or
|
|
implicitly when a cache limit has been reached). Some perhaps unobvious things
|
|
that may result in a cache miss are usage of \fB__TIME__\fP, \fB__DATE__\fP or
|
|
\fB__TIMESTAMP__\fP macros, or use of automatically generated code that contains
|
|
a timestamp, build counter or other volatile information.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
If \(lqMultiple source files\(rq has been incremented, it\(cqs an indication that the
|
|
compiler has been invoked on several source code files at once. Ccache doesn\(cqt
|
|
support that. Compile the source code files separately if possible.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
If \(lqUnsupported compiler option\(rq has been incremented, enable debug logging
|
|
and check which compiler option was rejected.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
If \(lqPreprocessing failed\(rq has been incremented, one possible reason is that
|
|
precompiled headers are being used. See \fIPRECOMPILED HEADERS\fP for how to
|
|
remedy this.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
If \(lqCould not use precompiled header\(rq has been incremented, see
|
|
\fIPRECOMPILED HEADERS\fP.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP \(bu 2.3
|
|
.\}
|
|
If \(lqCould not use modules\(rq has been incremented, see \fIC++ MODULES\fP.
|
|
.RE
|
|
.SS "Corrupt object files"
|
|
.sp
|
|
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
|
|
\fBprefix_command\fP or compiler wrapper. If this
|
|
happens, the easiest way of fixing it is this:
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04' 1.\h'+01'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP " 1." 4.2
|
|
.\}
|
|
Build so that the bad object file ends up in the build tree.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04' 2.\h'+01'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP " 2." 4.2
|
|
.\}
|
|
Remove the bad object file from the build tree.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04' 3.\h'+01'\c
|
|
.\}
|
|
.el \{\
|
|
. sp -1
|
|
. IP " 3." 4.2
|
|
.\}
|
|
Rebuild with \fBCCACHE_RECACHE\fP set.
|
|
.RE
|
|
.sp
|
|
An alternative is to clear the whole cache with \fBccache \-C\fP if you don\(cqt mind
|
|
losing other cached results.
|
|
.sp
|
|
There are no reported issues about ccache producing broken object files
|
|
reproducibly. That doesn\(cqt mean it can\(cqt happen, so if you find a repeatable
|
|
case, please report it.
|
|
.SH "MORE INFORMATION"
|
|
.sp
|
|
Credits, mailing list information, bug reporting instructions, source code,
|
|
etc, can be found on ccache\(cqs web site: \c
|
|
.URL "https://ccache.dev" "" "."
|
|
.SH "AUTHOR"
|
|
.sp
|
|
Ccache was originally written by Andrew Tridgell and is currently developed and
|
|
maintained by Joel Rosdahl. See AUTHORS.txt or AUTHORS.html and
|
|
.URL "https://ccache.dev/credits.html" "" ""
|
|
for a list of contributors. |