From fcd6b928018241527e8db4c2f802ec88b981c1d9 Mon Sep 17 00:00:00 2001 From: q66 Date: Thu, 6 Jan 2022 17:51:38 +0100 Subject: [PATCH] ccache: ship a pregenerated manpage for now Apparently asciidoc does not generate an entirely correct one. --- srcpkgs/ccache/files/ccache.1 | 3626 +++++++++++++++++++++++++ srcpkgs/ccache/patches/asciidoc.patch | 79 - srcpkgs/ccache/template | 4 +- 3 files changed, 3629 insertions(+), 80 deletions(-) create mode 100644 srcpkgs/ccache/files/ccache.1 delete mode 100644 srcpkgs/ccache/patches/asciidoc.patch diff --git a/srcpkgs/ccache/files/ccache.1 b/srcpkgs/ccache/files/ccache.1 new file mode 100644 index 0000000000..0fe62140c4 --- /dev/null +++ b/srcpkgs/ccache/files/ccache.1 @@ -0,0 +1,3626 @@ +'\" t +.\" Title: ccache +.\" Author: [see the "AUTHOR(S)" section] +.\" Generator: Asciidoctor 2.0.15 +.\" Date: 2022-01-05 +.\" Manual: \ \& +.\" Source: Ccache 4.5.1 +.\" Language: English +.\" +.TH "CCACHE" "1" "2022-01-05" "Ccache 4.5.1" "\ \&" +.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 [\fIoptions\fP] +\fBccache\fP \fIcompiler\fP [\fIcompiler options\fP] +\fIcompiler\fP [\fIcompiler options\fP] (via symbolic link) +.fi +.br +.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 ways to use ccache. You can either prefix your compilation +commands with \fBccache\fP or you can let ccache masquerade as the compiler by +creating a symbolic link (named as the compiler) to ccache. The first method is +most convenient if you just want to try out ccache or wish to use it for some +specific projects. The second method is most useful for when you wish to use +ccache for all your compilations. +.sp +To use the first method, just make sure that \fBccache\fP is in your \fBPATH\fP. +.sp +To use the symlinks method, do something like this: +.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++ +ln \-s ccache /usr/local/bin/cc +ln \-s ccache /usr/local/bin/c++ +.fam +.fi +.if n .RE +.sp +And so forth. This will work as long as the directory with symlinks comes +before the path to the compiler (which is usually in \fB/usr/bin\fP). After +installing you may wish to run \(lqwhich gcc\(rq to make sure that the correct link +is being used. +.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 +\fI[_using_ccache_with_other_compiler_wrappers]\fP. +.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 Warning +.ps -1 +.br +.sp +Use a symbolic links for masquerading, not hard links. +.sp .5v +.RE +.SH "COMMAND LINE OPTIONS" +.sp +These command line options only apply when you invoke ccache as \(lqccache\(rq. +When invoked as a compiler (via a symlink as described in the previous +section), the normal compiler options apply and you should refer to the +compiler\(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 manually modify the cache contents 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 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: k, M, G, T (decimal), Ki, Mi, Gi or +Ti (binary). The default suffix is G. 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 potentionally 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\-o\fP \fIKEY=VALUE\fP, \fB\-\-set\-config\fP \fIKEY\fP=\fIVALUE\fP +.RS 4 +Set configuration option \fIKEY\fP to \fIVALUE\fP. See \fI[_configuration]\fP for more +information. +.RE +.sp +\fB\-x\fP, \fB\-\-show\-compression\fP +.RS 4 +Print cache compression statistics. See \fI[_cache_compression]\fP for more +information. This can potentionally 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 secondary 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 primary cache. To trim the primary +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: k, M, G, T (decimal), Ki, Mi, Gi or Ti (binary). The +default suffix is G. +.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 +.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\-\-dump\-manifest\fP \fIPATH\fP +.RS 4 +Dump manifest file at \fIPATH\fP (\fB\-\fP for standard input) in text format to +standard output. This is only useful when debugging ccache and its behavior. +.RE +.sp +\fB\-\-dump\-result\fP \fIPATH\fP +.RS 4 +Dump result file at \fIPATH\fP (\fB\-\fP for standard input) in text format to +standard output. This is only useful when debugging ccache and its behavior. +.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 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 \fI[_configuration]\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\-\-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 +.\} +Environment variables. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 2.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 2." 4.2 +.\} +The primary (cache\-specific) configuration file (see below). +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 3.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 3." 4.2 +.\} +The secondary (system\-wide read\-only) configuration file +\fB/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' 4.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 4." 4.2 +.\} +Compile\-time defaults. +.RE +.sp +As a special case, if the the environment variable \fBCCACHE_CONFIGPATH\fP is set +it specifies the primary configuration file and the secondary (system\-wide) +configuration file won\(cqt be read. +.SS "Location of the primary configuration file" +.sp +The location of the primary (cache\-specific) configuration is determined like +this: +.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 secondary +(system\-wide) configuration file then use \fB/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%APPDATA%/ccache/ccache.conf\fP (Windows), +\fB$HOME/Library/Preferences/ccache/ccache.conf\fP (macOS) or +\fB$HOME/.config/ccache/ccache.conf\fP (other systems). +.RE +.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 +\fI[_compiling_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. +.RE +.sp +\fBcache_dir\fP (\fBCCACHE_DIR\fP) +.RS 4 +This option specifies where ccache will keep its cached compiler outputs. +The default is \fB$XDG_CACHE_HOME/ccache\fP if \fBXDG_CACHE_HOME\fP is set, +otherwise \fB$HOME/.cache/ccache\fP. Exception: If the legacy directory +\fB$HOME/.ccache\fP exists then that directory is the default. +.sp +See also \fI[_location_of_the_primary_configuration_file]\fP. +.sp +If you want to use another \fBCCACHE_DIR\fP value temporarily for one ccache +invocation you can use the \fB\-d\fP/\fB\-\-dir\fP command line option instead. +.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. 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 +\fI[_using_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 +\fBgcc\fP +.RS 4 +GCC\-based compiler. +.RE +.sp +\fBnvcc\fP +.RS 4 +NVCC (CUDA) compiler. +.RE +.sp +\fBother\fP +.RS 4 +Any compiler other than the known types. +.RE +.sp +\fBpump\fP +.RS 4 +distcc\(cqs \(lqpump\(rq script. +.RE +.RE +.sp +\fBcompression\fP (\fBCCACHE_COMPRESS\fP or \fBCCACHE_NOCOMPRESS\fP, see \fI[_boolean_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 \fI[_boolean_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 \fI[_cache_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 +\fI[_cache_debugging]\fP. +.RE +.sp +\fBdepend_mode\fP (\fBCCACHE_DEPEND\fP or \fBCCACHE_NODEPEND\fP, see \fI[_boolean_values]\fP above) +.RS 4 +If true, the depend mode will be used. The default is false. See +\fI[_the_depend_mode]\fP. +.RE +.sp +\fBdirect_mode\fP (\fBCCACHE_DIRECT\fP or \fBCCACHE_NODIRECT\fP, see \fI[_boolean_values]\fP above) +.RS 4 +If true, the direct mode will be used. The default is true. See +\fI[_the_direct_mode]\fP. +.RE +.sp +\fBdisable\fP (\fBCCACHE_DISABLE\fP or \fBCCACHE_NODISABLE\fP, see \fI[_boolean_values]\fP above) +.RS 4 +When true, ccache will just call the real compiler, bypassing the cache +completely. The default is false. +.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 \fI[_boolean_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 \fI[_boolean_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 guard. 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 writeable, 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 \fI[_boolean_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 +\fI[_compiling_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 \fI[_boolean_values]\fP above) +.RS 4 +If true, enables caching of source file hashes based on device, inode and +timestamps. This will reduce the time spent on hashing included files as +the result can be resused between compilations. +.sp +The feature is still experimental and thus off by default. It is currently not +available on Windows. +.sp +The feature requires \fBtemporary_dir\fP to be located on a local filesystem. +.RE +.sp +\fBkeep_comments_cpp\fP (\fBCCACHE_COMMENTS\fP or \fBCCACHE_NOCOMMENTS\fP, see \fI[_boolean_values]\fP above) +.RS 4 +If true, ccache will not discard the comments before hashing preprocessor +output. This can be used to check documentation with \fB\-Wdocumentation\fP. +.RE +.sp +\fBlimit_multiple\fP (\fBCCACHE_LIMIT_MULTIPLE\fP) +.RS 4 +Sets the limit when cleaning up. Files are deleted (in LRU order) until the +levels are below the limit. The default is 0.8 (= 80%). See +\fI[_automatic_cleanup]\fP for more information. +.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 \fI[_cache_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 +\fI[_cache_size_management]\fP. +.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 +primary cache with the command line option \fB\-\-evict\-namespace\fP, potentially +in combination with \fB\-\-evict\-older\-than\fP. +\&. +For instance, if you use the same primary 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 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 \fI[_boolean_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 +\fI[_using_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 \fI[_boolean_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 \fI[_boolean_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 \fI[_boolean_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 +\fBreshare\fP (\fBCCACHE_RESHARE\fP or \fBCCACHE_NORESHARE\fP, see \fI[_boolean_values]\fP above) +.RS 4 +If true, ccache will write results to secondary storage even for primary +storage cache hits. The default is false. +.RE +.sp +\fBrun_second_cpp\fP (\fBCCACHE_CPP2\fP or \fBCCACHE_NOCPP2\fP, see \fI[_boolean_values]\fP above) +.RS 4 +If true, ccache will first run the preprocessor to preprocess the source +code (see \fI[_the_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). +.RE +.sp +\fBsecondary_storage\fP (\fBCCACHE_SECONDARY_STORAGE\fP) +.RS 4 +This option specifies one or several storage backends (separated by space) +to query after the primary cache storage. See +\fI[_secondary_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 +.RE +.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 +\fBinclude_file_ctime\fP +.RS 4 +By default, ccache will not cache a file if it includes a header whose ctime +is too new. 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 not cache a file if it includes a header whose mtime +is too new. 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 +\fBpch_defines\fP +.RS 4 +Be sloppy about \fB#define\fP directives when precompiling a header file. See +\fI[_precompiled_headers]\fP for more information. +.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 +\fI[_c_modules]\fP for more information. +.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 \fI[_troubleshooting]\fP for more information. +.RE +.sp +\fBstats\fP (\fBCCACHE_STATS\fP or \fBCCACHE_NOSTATS\fP, see \fI[_boolean_values]\fP above) +.RS 4 +If true, ccache will update the statistics counters on each compilation. +The default is true. +.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/run/user//ccache\-tmp\fP if \fB/run/user/\fP exists, otherwise +\fB/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 +.SH "SECONDARY STORAGE BACKENDS" +.sp +The \fBsecondary_storage\fP option lets you configure +ccache to use one or several other storage backends in addition to the primary +cache storage located in \fBcache_dir\fP. Note that cache +statistics counters will still be kept in the primary cache directory \(em secondary storage backends only store cache results and manifests. +.sp +A secondary 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 \c +.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 secondary 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 +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBshare\-hits\fP: If \fBtrue\fP, write hits for this backend to primary storage. The +default is \fBtrue\fP. +.RE +.SS "Storage interaction" +.sp +The table below describes the interaction between primary and secondary storage +on cache hits and misses: +.TS +allbox tab(:); +lt lt lt. +T{ +.sp +\fBPrimary storage\fP +T}:T{ +.sp +\fBSecondary storage\fP +T}:T{ +.sp +\fBWhat happens\fP +T} +T{ +.sp +miss +T}:T{ +.sp +miss +T}:T{ +.sp +Compile, write to primary, write to secondary[1] +T} +T{ +.sp +miss +T}:T{ +.sp +hit +T}:T{ +.sp +Read from secondary, write to primary[2] +T} +T{ +.sp +hit +T}:T{ +.sp +\- +T}:T{ +.sp +Read from primary, don\(cqt write to secondary[3] +T} +.TE +.sp +.sp +[1] Unless secondary storage has attribute \fBread\-only=true\fP. +.br +[2] Unless secondary storage has attribute \fBshare\-hits=false\fP. +.br +[3] Unless primary storage is set to share its cache hits with the +\fBreshare\fP option. +.SS "File storage backend" +.sp +URL format: \fBfile:DIRECTORY\fP or \fBfile://DIRECTORY\fP +.sp +This backend stores data as separate files in a directory structure below +\fBDIRECTORY\fP (an absolute path), similar (but not identical) to the primary cache +storage. A typical use case for this backend would be sharing a cache on an NFS +directory. +.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 +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 +.\} +\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 \fBfalse\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 +Connection keep\-alive is disabled by default because with the current +HTTP implementation uploads to the remote end might fail in case the server +closes the connection due to a keep\-alive timeout. If the general case with +short compilation times should be accelerated or the server is configured with +a long\-enough timeout, then connection keep\-alive could be enabled. +.sp .5v +.RE +.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 format: \fBredis://[[USERNAME:]PASSWORD@]HOST[:PORT][/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 \fI[_secondary_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 +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 +Ccache maintains counters for various statistics about the cache, including the +size and number of all cached files. In order to improve performance and reduce +issues with concurrent ccache invocations, there is one statistics file for +each of the sixteen subdirectories in the cache. +.sp +After a new compilation result has been written to the cache, ccache will +update the size and file number statistics for the subdirectory (one of +sixteen) to which the result was written. Then, if the size counter for said +subdirectory is greater than \fBmax_size / 16\fP or the file number counter is +greater than \fBmax_files / 16\fP, automatic cleanup is triggered. +.sp +When automatic cleanup is triggered for a subdirectory in the cache, ccache +will: +.sp +.RS 4 +.ie n \{\ +\h'-04' 1.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 1." 4.2 +.\} +Count all files in the subdirectory and compute their aggregated size. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 2.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 2." 4.2 +.\} +Remove files in LRU (least recently used) order until the size is at most +\fBlimit_multiple * max_size / 16\fP and the number of files is at most +\fBlimit_multiple * max_files / 16\fP, where +\fBlimit_multiple\fP, \fBmax_size\fP +and \fBmax_files\fP are configuration options. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 3.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 3." 4.2 +.\} +Set the size and file number counters to match the files that were kept. +.RE +.sp +The reason for removing more files than just those needed to not exceed the max +limits is that a cleanup is a fairly slow operation, so it would not be a good +idea to trigger it often, like after each cache miss. +.SS "Manual cleanup" +.sp +You can run \fBccache \-c/\-\-cleanup\fP to force cleanup of the whole cache, i.e. all +of the sixteen subdirectories. This will recalculate the statistics counters +and make sure that the configuration options \fBmax_size\fP and +\fBmax_files\fP are not exceeded. Note that +\fBlimit_multiple\fP is not taken into account for manual +cleanup. +.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 primary and secondary 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 +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 is not a file (e.g. a directory or a device +node). +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 produced empty output +T}:T{ +.sp +The compiler\(cqs output file (typically an object file) was empty after +compilation. +T} +T{ +.sp +Compiler produced no output +T}:T{ +.sp +The compiler\(cqs output file (typically an object file) was missing after +compilation. +T} +T{ +.sp +Compiler produced stdout +T}:T{ +.sp +The compiler wrote data to standard output. This is something that compilers +normally never do, so ccache is not designed to store such output in the cache. +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 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 \fI[_the_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,\fP, \fB\-Wp,\-MMD,\fP +and \fB\-Wp,\-D\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 file generated by the compiler 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 \-MD is used, the manifest entries will include system header files as +well, thus slowing down cache hits slightly, just as using \-MD slows down +make. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +If \-MMD 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. +.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 the same second as 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.ccache\-input\-c\fP +T}:T{ +.sp +Binary input hashed by both the direct mode and the preprocessor mode. +T} +T{ +.sp +\fB.ccache\-input\-d\fP +T}:T{ +.sp +Binary input only hashed by the direct mode. +T} +T{ +.sp +\fB.ccache\-input\-p\fP +T}:T{ +.sp +Binary input only hashed by the preprocessor mode. +T} +T{ +.sp +\fB.ccache\-input\-text\fP +T}:T{ +.sp +Human\-readable combined diffable text version of the three files above. +T} +T{ +.sp +\fB.ccache\-log\fP +T}:T{ +.sp +Log for this object file. +T} +.TE +.sp +.sp +If \fBconfig_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 +.\} +Build with debug mode enabled. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 2.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 2." 4.2 +.\} +Save the \fB.ccache\-*\fP files. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 3.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 3." 4.2 +.\} +Build again with debug mode enabled. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 4.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 4." 4.2 +.\} +Compare \fB.ccache\-input\-text\fP for the two builds. This together +with the \fB.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==\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 GCC\(cqs precompiled headers. 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 +\fI[_handling_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 +.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). +.RE +.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 CACHE" +.sp +A group of developers can increase the cache hit rate by sharing a cache +directory. To share a cache without unpleasant side effects, the following +conditions should to be met: +.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 +secondary 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 +\fI[_the_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 \fI[_cache_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,\fP, +\fB\-Wp,\-MMD,\fP, and \fB\-Wp,\-D\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 +\fI[_handling_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 \fI[_precompiled_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 +\fI[_precompiled_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 \fI[_c_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. \ No newline at end of file diff --git a/srcpkgs/ccache/patches/asciidoc.patch b/srcpkgs/ccache/patches/asciidoc.patch deleted file mode 100644 index 76a7fd2c4f..0000000000 --- a/srcpkgs/ccache/patches/asciidoc.patch +++ /dev/null @@ -1,79 +0,0 @@ ---- a/doc/CMakeLists.txt -+++ b/doc/CMakeLists.txt -@@ -1,54 +1,37 @@ --find_program(ASCIIDOCTOR_EXE asciidoctor) --mark_as_advanced(ASCIIDOCTOR_EXE) # Don't show in CMake UIs -+find_program(ASCIIDOC_EXE asciidoc) -+mark_as_advanced(ASCIIDOC_EXE) # Don't show in CMake UIs - --if(NOT ASCIIDOCTOR_EXE) -+if(NOT ASCIIDOC_EXE) - message(WARNING "Could not find asciidoctor; documentation will not be generated") - else() -- function(generate_doc backend adoc_file output_file) -- get_filename_component(base_name "${adoc_file}" NAME_WE) -- add_custom_command( -- OUTPUT "${output_file}" -- COMMAND -- ${ASCIIDOCTOR_EXE} -- -o "${output_file}" -- -a revnumber="${CCACHE_VERSION}" -- -a icons=font -- -a toc=left -- -a sectanchors -- -a stylesheet="${CMAKE_CURRENT_SOURCE_DIR}/ccache-doc.css" -- -b "${backend}" -- "${CMAKE_SOURCE_DIR}/${adoc_file}" -- MAIN_DEPENDENCY "${CMAKE_SOURCE_DIR}/${adoc_file}" -- DEPENDS "${CMAKE_CURRENT_SOURCE_DIR}/ccache-doc.css" -- ) -- set(doc_files "${doc_files}" "${output_file}" PARENT_SCOPE) -- endfunction() -- -- # -- # HTML documentation -- # -- generate_doc(html LICENSE.adoc LICENSE.html) -- generate_doc(html doc/AUTHORS.adoc AUTHORS.html) -- generate_doc(html doc/MANUAL.adoc MANUAL.html) -- generate_doc(html doc/NEWS.adoc NEWS.html) -- add_custom_target(doc-html DEPENDS "${doc_files}") -- - # - # Man page - # -- generate_doc(manpage doc/MANUAL.adoc ccache.1.tmp) -+ find_program(A2X_EXE a2x) -+ mark_as_advanced(A2X_EXE) # Don't show in CMake UIs -+ # MANUAL.adoc -> MANUAL.xml -> man page -+ add_custom_command( -+ OUTPUT MANUAL.xml -+ COMMAND -+ ${ASCIIDOC_EXE} -+ -o - -+ -a revnumber=${CCACHE_VERSION} -+ -d manpage -+ -b docbook "${CMAKE_SOURCE_DIR}/doc/MANUAL.adoc" -+ | perl -pe 's!\(.*?\)!\\1!g' -+ >MANUAL.xml -+ MAIN_DEPENDENCY "${CMAKE_SOURCE_DIR}/doc/MANUAL.adoc" -+ ) - add_custom_command( - OUTPUT ccache.1 -- # Convert monospace to bold since that's typically rendered better when -- # viewing the man page. -- COMMAND perl -pe "'s!\\\\f\\(CR(.*?)\\\\fP!\\\\fB\\1\\\\fP!g'" ccache.1.tmp >ccache.1 -- MAIN_DEPENDENCY ccache.1.tmp -+ COMMAND ${A2X_EXE} --doctype manpage --format manpage MANUAL.xml -+ MAIN_DEPENDENCY MANUAL.xml - ) -+ add_custom_target(doc-man-page DEPENDS ccache.1) - install( - FILES "${CMAKE_CURRENT_BINARY_DIR}/ccache.1" - DESTINATION "${CMAKE_INSTALL_MANDIR}/man1" - ) -- add_custom_target(doc-man-page DEPENDS ccache.1) - -- add_custom_target(doc ALL DEPENDS doc-html doc-man-page) -+ add_custom_target(doc ALL DEPENDS ccache.1) - endif() diff --git a/srcpkgs/ccache/template b/srcpkgs/ccache/template index 64d3e9f48e..033cfe9a2f 100644 --- a/srcpkgs/ccache/template +++ b/srcpkgs/ccache/template @@ -4,7 +4,7 @@ version=4.5.1 revision=2 build_style=cmake configure_args="-DENABLE_TESTING=OFF -DREDIS_STORAGE_BACKEND=OFF" -hostmakedepends="asciidoc perl" +hostmakedepends="perl" makedepends="libzstd-devel zlib-devel" short_desc="Fast C/C++ Compiler Cache" maintainer="Enno Boland " @@ -42,4 +42,6 @@ post_install() { ln -sfr ${DESTDIR}/usr/bin/ccache ${DESTDIR}/usr/lib/ccache/bin/${x}-${f} done done + # pregenerated manpage to avoid bringing ruby into the build + vman ${FILESDIR}/ccache.1 }