[crux-commits] ports/opt (3.7): ccache: 4.8.2 -> 4.8.3

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