* [PR PATCH] ccache: update to 4.7.4.
@ 2022-12-18 17:10 r-ricci
2022-12-19 5:36 ` [PR REVIEW] " classabbyamp
` (5 more replies)
0 siblings, 6 replies; 7+ messages in thread
From: r-ricci @ 2022-12-18 17:10 UTC (permalink / raw)
To: ml
[-- Attachment #1: Type: text/plain, Size: 1443 bytes --]
There is a new pull request by r-ricci against master on the void-packages repository
https://github.com/r-ricci/void-packages ccache
https://github.com/void-linux/void-packages/pull/41168
ccache: update to 4.7.4.
<!-- Uncomment relevant sections and delete options which are not applicable -->
It doesn't link to zlib since [version 4.0](https://ccache.dev/releasenotes.html#_ccache_4_0).
I don't know why perl was in hostmakedepends but the build log is identical with and without it.
@Gottox
#### Testing the changes
- I tested the changes in this PR: **YES**
<!--
#### New package
- This new package conforms to the [package requirements](https://github.com/void-linux/void-packages/blob/master/CONTRIBUTING.md#package-requirements): **YES**|**NO**
-->
<!-- Note: If the build is likely to take more than 2 hours, please add ci skip tag as described in
https://github.com/void-linux/void-packages/blob/master/CONTRIBUTING.md#continuous-integration
and test at least one native build and, if supported, at least one cross build.
Ignore this section if this PR is not skipping CI.
-->
<!--
#### Local build testing
- I built this PR locally for my native architecture, (ARCH-LIBC)
- I built this PR locally for these architectures (if supported. mark crossbuilds):
- aarch64-musl
- armv7l
- armv6l-musl
-->
A patch file from https://github.com/void-linux/void-packages/pull/41168.patch is attached
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: github-pr-ccache-41168.patch --]
[-- Type: text/x-diff, Size: 45587 bytes --]
From cef4afbb682071f0b8955cca128b18bc6e77eb6e Mon Sep 17 00:00:00 2001
From: Roberto Ricci <ricci@disroot.org>
Date: Sat, 17 Dec 2022 23:34:19 +0100
Subject: [PATCH] ccache: update to 4.7.4.
---
srcpkgs/ccache/files/ccache.1 | 796 +++++++++++++++++++++++-----------
srcpkgs/ccache/template | 9 +-
2 files changed, 553 insertions(+), 252 deletions(-)
diff --git a/srcpkgs/ccache/files/ccache.1 b/srcpkgs/ccache/files/ccache.1
index 0fe62140c43f..366e4a2b68e2 100644
--- a/srcpkgs/ccache/files/ccache.1
+++ b/srcpkgs/ccache/files/ccache.1
@@ -2,12 +2,12 @@
.\" Title: ccache
.\" Author: [see the "AUTHOR(S)" section]
.\" Generator: Asciidoctor 2.0.15
-.\" Date: 2022-01-05
+.\" Date: 2022-12-18
.\" Manual: \ \&
-.\" Source: Ccache 4.5.1
+.\" Source: Ccache 4.7.4
.\" Language: English
.\"
-.TH "CCACHE" "1" "2022-01-05" "Ccache 4.5.1" "\ \&"
+.TH "CCACHE" "1" "2022-12-18" "Ccache 4.7.4" "\ \&"
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.ss \n[.ss] 0
@@ -34,7 +34,7 @@ ccache \- a fast C/C++ compiler cache
.nf
\fBccache\fP [\fIoptions\fP]
\fBccache\fP \fIcompiler\fP [\fIcompiler options\fP]
-\fIcompiler\fP [\fIcompiler options\fP] (via symbolic link)
+\fIcompiler\fP [\fIcompiler options\fP] (ccache masquerading as the compiler)
.fi
.br
.SH "DESCRIPTION"
@@ -50,16 +50,41 @@ goal are listed under \fICaveats\fP. If you discover an undocumented case where
ccache changes the output of your compiler, please let us know.
.SH "RUN MODES"
.sp
-There are two ways to use ccache. You can either prefix your compilation
-commands with \fBccache\fP or you can let ccache masquerade as the compiler by
-creating a symbolic link (named as the compiler) to ccache. The first method is
-most convenient if you just want to try out ccache or wish to use it for some
-specific projects. The second method is most useful for when you wish to use
-ccache for all your compilations.
+There are two different ways to use ccache to cache a compilation:
.sp
-To use the first method, just make sure that \fBccache\fP is in your \fBPATH\fP.
+.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
-To use the symlinks method, do something like this:
+.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
@@ -67,16 +92,25 @@ To use the symlinks method, do something like this:
cp ccache /usr/local/bin/
ln \-s ccache /usr/local/bin/gcc
ln \-s ccache /usr/local/bin/g++
-ln \-s ccache /usr/local/bin/cc
-ln \-s ccache /usr/local/bin/c++
.fam
.fi
.if n .RE
.sp
-And so forth. This will work as long as the directory with symlinks comes
-before the path to the compiler (which is usually in \fB/usr/bin\fP). After
-installing you may wish to run \(lqwhich gcc\(rq to make sure that the correct link
-is being used.
+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
@@ -93,26 +127,13 @@ but currently doesn\(cqt interact well with other tools that do the same thing.
\fI[_using_ccache_with_other_compiler_wrappers]\fP.
.sp .5v
.RE
-.if n .sp
-.RS 4
-.it 1 an-trap
-.nr an-no-space-flag 1
-.nr an-break-flag 1
-.br
-.ps +1
-.B Warning
-.ps -1
-.br
-.sp
-Use a symbolic links for masquerading, not hard links.
-.sp .5v
.RE
.SH "COMMAND LINE OPTIONS"
.sp
-These command line options only apply when you invoke ccache as \(lqccache\(rq.
-When invoked as a compiler (via a symlink as described in the previous
-section), the normal compiler options apply and you should refer to the
-compiler\(cqs documentation.
+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
@@ -135,8 +156,8 @@ configuration file.
\fB\-\-config\-path\fP \fIPATH\fP
.RS 4
Let the command line options operate on configuration file \fIPATH\fP instead of
-the default. Using this option has the same effect as setting the
-environment variable \fBCCACHE_CONFIGPATH\fP temporarily.
+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
@@ -186,7 +207,7 @@ future compilations.
.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
+\fBcompression_level\fP configuration option, or
the special value \fBuncompressed\fP for no compression. See
\fI[_cache_compression]\fP for more information. This can potentionally take a
long time since all files in the cache need to be visited. Only files that
@@ -241,12 +262,12 @@ Print version and copyright information.
.RS 4
Zero the cache statistics (but not the configuration options).
.RE
-.SS "Options for secondary storage"
+.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.
+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
@@ -258,17 +279,17 @@ by \fB\-\-trim\-max\-size\fP.
.ps -1
.br
.sp
-Don\(cqt use this option to trim the primary cache. To trim the primary
-cache directory to a certain size, use \fBCCACHE_MAXSIZE=\fISIZE\fP ccache \-c\fP.
+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: k, M, G, T (decimal), Ki, Mi, Gi or Ti (binary). The
-default suffix is G.
+Specify the maximum size for \fB\-\-trim\-dir\fP. \fISIZE\fP should be a number
+followed by an optional suffix: k, M, G, T (decimal), Ki, Mi, Gi or Ti
+(binary). The default suffix is G.
.RE
.sp
\fB\-\-trim\-method\fP \fIMETHOD\fP
@@ -295,23 +316,11 @@ Print the checksum (128 bit XXH3) of the file at \fIPATH\fP (\fB\-\fP for standa
input).
.RE
.sp
-\fB\-\-dump\-manifest\fP \fIPATH\fP
-.RS 4
-Dump manifest file at \fIPATH\fP (\fB\-\fP for standard input) in text format to
-standard output. This is only useful when debugging ccache and its behavior.
-.RE
-.sp
-\fB\-\-dump\-result\fP \fIPATH\fP
-.RS 4
-Dump result file at \fIPATH\fP (\fB\-\fP for standard input) in text format to
-standard output. This is only useful when debugging ccache and its behavior.
-.RE
-.sp
\fB\-\-extract\-result\fP \fIPATH\fP
.RS 4
Extract data stored in the result file at \fIPATH\fP (\fB\-\fP for standard input).
The data will be written to \fBccache\-result.*\fP files in to the current
-working directory. This is only useful when debugging ccache and its
+working directory. This option is only useful when debugging ccache and its
behavior.
.RE
.sp
@@ -327,6 +336,15 @@ 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
@@ -394,7 +412,7 @@ Environment variables.
. sp -1
. IP " 2." 4.2
.\}
-The primary (cache\-specific) configuration file (see below).
+The cache\-specific configuration file (see below).
.RE
.sp
.RS 4
@@ -405,9 +423,8 @@ The primary (cache\-specific) configuration file (see below).
. sp -1
. IP " 3." 4.2
.\}
-The secondary (system\-wide read\-only) configuration file
-\fB<sysconfdir>/ccache.conf\fP (typically \fB/etc/ccache.conf\fP or
-\fB/usr/local/etc/ccache.conf\fP).
+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
@@ -421,13 +438,13 @@ The secondary (system\-wide read\-only) configuration file
Compile\-time defaults.
.RE
.sp
-As a special case, if the the environment variable \fBCCACHE_CONFIGPATH\fP is set
-it specifies the primary configuration file and the secondary (system\-wide)
-configuration file won\(cqt be read.
-.SS "Location of the primary configuration file"
+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 primary (cache\-specific) configuration is determined like
-this:
+The location of the cache\-specific configuration file is determined like this on
+non\-Windows systems:
.sp
.RS 4
.ie n \{\
@@ -460,8 +477,8 @@ Otherwise, if the environment variable \fBCCACHE_DIR\fP is set then use
. sp -1
. IP " 3." 4.2
.\}
-Otherwise, if \fBcache_dir\fP is set in the secondary
-(system\-wide) configuration file then use \fB<cache_dir>/ccache.conf\fP.
+Otherwise, if \fBcache_dir\fP is set in the system
+configuration file then use \fB<cache_dir>/ccache.conf\fP.
.RE
.sp
.RS 4
@@ -496,10 +513,87 @@ Otherwise, if \fBXDG_CONFIG_HOME\fP is set then use
. sp -1
. IP " 6." 4.2
.\}
-Otherwise, use \fB%APPDATA%/ccache/ccache.conf\fP (Windows),
+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
@@ -639,19 +733,56 @@ 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.
-The default is \fB$XDG_CACHE_HOME/ccache\fP if \fBXDG_CACHE_HOME\fP is set,
-otherwise \fB$HOME/.cache/ccache\fP. Exception: If the legacy directory
-\fB$HOME/.ccache\fP exists then that directory is the default.
.sp
-See also \fI[_location_of_the_primary_configuration_file]\fP.
+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
-If you want to use another \fBCCACHE_DIR\fP value temporarily for one ccache
-invocation you can use the \fB\-d\fP/\fB\-\-dir\fP command line option instead.
+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 \fI[_location_of_the_configuration_file]\fP.
.RE
.sp
\fBcompiler\fP (\fBCCACHE_COMPILER\fP or (deprecated) \fBCCACHE_CC\fP)
@@ -665,8 +796,9 @@ command line.
.RS 4
By default, ccache includes the modification time (\(lqmtime\(rq) and size of
the compiler in the hash to ensure that results retrieved from the cache
-are accurate. This option can be used to select another strategy. Possible
-values are:
+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
@@ -756,11 +888,26 @@ symlinks). This is the default.
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.
@@ -770,11 +917,6 @@ NVCC (CUDA) compiler.
.RS 4
Any compiler other than the known types.
.RE
-.sp
-\fBpump\fP
-.RS 4
-distcc\(cqs \(lqpump\(rq script.
-.RE
.RE
.sp
\fBcompression\fP (\fBCCACHE_COMPRESS\fP or \fBCCACHE_NOCOMPRESS\fP, see \fI[_boolean_values]\fP above)
@@ -944,11 +1086,11 @@ Do not enable this option unless you are aware of these caveats:
If the resulting file is modified, the file in the cache will also be
modified since they share content, which corrupts the cache entry. As of
version 4.0, ccache makes stored and fetched object files read\-only as a
-safety measure guard. Furthermore, a simple integrity check is made for
-cached object files by verifying that their sizes are correct. This means
-that mistakes like \fBstrip file.o\fP or \fBecho >file.o\fP will be detected even if
-the object file is made writeable, but a modification that doesn\(cqt change the
-file size will not.
+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 writeable, but a modification that doesn\(cqt change the file
+size will not.
.RE
.sp
.RS 4
@@ -1024,20 +1166,32 @@ example, \fB\-fmessage\-length=*\fP will match both \fB\-fmessage\-length=20\fP
.sp
\fBinode_cache\fP (\fBCCACHE_INODECACHE\fP or \fBCCACHE_NOINODECACHE\fP, see \fI[_boolean_values]\fP above)
.RS 4
-If true, enables caching of source file hashes based on device, inode and
-timestamps. This will reduce the time spent on hashing included files as
-the result can be resused between compilations.
-.sp
-The feature is still experimental and thus off by default. It is currently not
-available on Windows.
+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 resused 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 feature requires \fBtemporary_dir\fP to be located on a local filesystem.
+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 \fI[_boolean_values]\fP above)
.RS 4
If true, ccache will not discard the comments before hashing preprocessor
-output. This can be used to check documentation with \fB\-Wdocumentation\fP.
+output. The default is false. This can be used to check documentation with
+\fB\-Wdocumentation\fP.
.RE
.sp
\fBlimit_multiple\fP (\fBCCACHE_LIMIT_MULTIPLE\fP)
@@ -1082,18 +1236,25 @@ Gi, Ti (binary). The default suffix is G. See also
\fI[_cache_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
+If set, the namespace string will be added to the hashed data for each
compilation. This will make the associated cache entries logically separate
from cache entries with other namespaces, but they will still share the same
-storage space. Cache entries can also be selectively removed from the
-primary cache with the command line option \fB\-\-evict\-namespace\fP, potentially
-in combination with \fB\-\-evict\-older\-than\fP.
-\&.
-For instance, if you use the same primary cache for several disparate projects,
+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 stop working with that
+cache entries that belong to a certain project if you stop working with that
project.
.RE
.sp
@@ -1155,40 +1316,20 @@ If true, ccache will not use any previously stored result. New results will
still be cached, possibly overwriting any pre\-existing results.
.RE
.sp
-\fBreshare\fP (\fBCCACHE_RESHARE\fP or \fBCCACHE_NORESHARE\fP, see \fI[_boolean_values]\fP above)
+\fBremote_only\fP (\fBCCACHE_REMOTE_ONLY\fP or \fBCCACHE_NOREMOTE_ONLY\fP, see \fI[_boolean_values]\fP above)
.RS 4
-If true, ccache will write results to secondary storage even for primary
-storage cache hits. The default is false.
+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
+\fI[_storage_interaction]\fP.
.RE
.sp
-\fBrun_second_cpp\fP (\fBCCACHE_CPP2\fP or \fBCCACHE_NOCPP2\fP, see \fI[_boolean_values]\fP above)
-.RS 4
-If true, ccache will first run the preprocessor to preprocess the source
-code (see \fI[_the_preprocessor_mode]\fP) and then on a cache miss run the
-compiler on the source code to get hold of the object file. This is the
-default.
-.sp
-If false, ccache will first run preprocessor to preprocess the source code and
-then on a cache miss run the compiler on the \fIpreprocessed source code\fP instead
-of the original source code. This makes cache misses slightly faster since the
-source code only has to be preprocessed once. The downside is that some
-compilers won\(cqt produce the same result (for instance diagnostics warnings)
-when compiling preprocessed source code.
-.sp
-A solution to the above mentioned downside is to set \fBrun_second_cpp\fP to false
-and pass \fB\-fdirectives\-only\fP (for GCC) or \fB\-frewrite\-includes\fP (for Clang) to
-the compiler. This will cause the compiler to leave the macros and other
-preprocessor information, and only process the \fB#include\fP directives. When run
-in this way, the preprocessor arguments will be passed to the compiler since it
-still has to do \fIsome\fP preprocessing (like macros).
-.RE
-.sp
-\fBsecondary_storage\fP (\fBCCACHE_SECONDARY_STORAGE\fP)
+\fBremote_storage\fP (\fBCCACHE_REMOTE_STORAGE\fP)
.RS 4
This option specifies one or several storage backends (separated by space)
-to query after the primary cache storage. See
-\fI[_secondary_storage_backends]\fP for documentation of syntax and available
-backends.
+to query after checking the local cache (unless
+\fBremote_only\fP is true). See \fI[Remote storage
+backends]\fP for documentation of syntax and available backends.
.sp
Examples:
.sp
@@ -1234,8 +1375,54 @@ Examples:
. 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 \fI[_boolean_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 \fI[_boolean_values]\fP above)
+.RS 4
+If true, ccache will first run the preprocessor to preprocess the source
+code (see \fI[_the_preprocessor_mode]\fP) and then on a cache miss run the
+compiler on the source code to get hold of the object file. This is the
+default.
+.sp
+If false, ccache will first run preprocessor to preprocess the source code and
+then on a cache miss run the compiler on the \fIpreprocessed source code\fP instead
+of the original source code. This makes cache misses slightly faster since the
+source code only has to be preprocessed once. The downside is that some
+compilers won\(cqt produce the same result (for instance diagnostics warnings)
+when compiling preprocessed source code.
+.sp
+A solution to the above mentioned downside is to set \fBrun_second_cpp\fP to false
+and pass \fB\-fdirectives\-only\fP (for GCC) or \fB\-frewrite\-includes\fP (for Clang) to
+the compiler. This will cause the compiler to leave the macros and other
+preprocessor information, and only process the \fB#include\fP directives. When run
+in this way, the preprocessor arguments will be passed to the compiler since it
+still has to do \fIsome\fP preprocessing (like macros).
+.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
@@ -1268,18 +1455,30 @@ 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 not cache a file if it includes a header whose ctime
-is too new. This sloppiness disables that check. See also
-\fI[_handling_of_newly_created_header_files]\fP.
+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 not cache a file if it includes a header whose mtime
-is too new. This sloppiness disables that check. See also
-\fI[_handling_of_newly_created_header_files]\fP.
+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
@@ -1297,18 +1496,25 @@ 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
+\fI[_c_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
\fI[_precompiled_headers]\fP for more information.
.RE
.sp
-\fBmodules\fP
+\fBrandom_seed\fP
.RS 4
-By default, ccache will not cache compilations if \fB\-fmodules\fP is used since
-it cannot hash the state of compiler\(cqs internal representation of relevant
-modules. This sloppiness allows caching in such a case. See
-\fI[_c_modules]\fP for more information.
+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
@@ -1357,7 +1563,8 @@ Lines in the stats log starting with a hash sign (\fB#\fP) are comments.
\fBtemporary_dir\fP (\fBCCACHE_TEMPDIR\fP)
.RS 4
This option specifies where ccache will put temporary files. The default is
-\fB/run/user/<UID>/ccache\-tmp\fP if \fB/run/user/<UID>\fP exists, otherwise
+\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
@@ -1382,23 +1589,25 @@ This option (an octal integer) specifies the umask for files and directories
in the cache directory. This is mostly useful when you wish to share your
cache with other users.
.RE
-.SH "SECONDARY STORAGE BACKENDS"
+.SH "REMOTE STORAGE BACKENDS"
.sp
-The \fBsecondary_storage\fP option lets you configure
-ccache to use one or several other storage backends in addition to the primary
-cache storage located in \fBcache_dir\fP. Note that cache
-statistics counters will still be kept in the primary cache directory \(em secondary storage backends only store cache results and manifests.
+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 secondary storage backend is specified with a URL, optionally followed by a
-pipe (\fB|\fP) and a pipe\-separated list of attributes. An attribute is
-\fIkey\fP=\fIvalue\fP or just \fIkey\fP as a short form of \fIkey\fP=\fBtrue\fP. Attribute values
-must be \c
+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.
+if they contain
+percent, pipe or space characters.
.SS "Attributes for all backends"
.sp
-These optional attributes are available for all secondary storage backends:
+These optional attributes are available for all remote storage backends:
.sp
.RS 4
.ie n \{\
@@ -1460,31 +1669,20 @@ of the cache on \fBredis://cache\-a.example.com\fP, 18% (1/5.5) on
\fBhttp://example.com/alpha\fP and 50% on \fBhttp://example.com/beta\fP.
.RE
.RE
-.sp
-.RS 4
-.ie n \{\
-\h'-04'\(bu\h'+03'\c
-.\}
-.el \{\
-. sp -1
-. IP \(bu 2.3
-.\}
-\fBshare\-hits\fP: If \fBtrue\fP, write hits for this backend to primary storage. The
-default is \fBtrue\fP.
-.RE
.SS "Storage interaction"
.sp
-The table below describes the interaction between primary and secondary storage
-on cache hits and misses:
+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
-\fBPrimary storage\fP
+\fBLocal storage\fP
T}:T{
.sp
-\fBSecondary storage\fP
+\fBRemote storage\fP
T}:T{
.sp
\fBWhat happens\fP
@@ -1497,7 +1695,7 @@ T}:T{
miss
T}:T{
.sp
-Compile, write to primary, write to secondary[1]
+Compile, write to local, write to remote[1]
T}
T{
.sp
@@ -1507,7 +1705,7 @@ T}:T{
hit
T}:T{
.sp
-Read from secondary, write to primary[2]
+Read from remote, write to local
T}
T{
.sp
@@ -1517,25 +1715,62 @@ T}:T{
\-
T}:T{
.sp
-Read from primary, don\(cqt write to secondary[3]
+Read from local, don\(cqt write to remote[2]
T}
.TE
.sp
.sp
-[1] Unless secondary storage has attribute \fBread\-only=true\fP.
+[1] Unless remote storage has attribute \fBread\-only=true\fP.
.br
-[2] Unless secondary storage has attribute \fBshare\-hits=false\fP.
-.br
-[3] Unless primary storage is set to share its cache hits with the
+[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://DIRECTORY\fP
+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 (an absolute path), similar (but not identical) to the primary cache
-storage. A typical use case for this backend would be sharing a cache on an NFS
-directory.
+\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
@@ -1576,6 +1811,17 @@ Examples:
\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
@@ -1733,6 +1979,17 @@ Optional attributes:
. 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
@@ -1745,25 +2002,7 @@ Optional attributes:
. IP \(bu 2.3
.\}
\fBkeep\-alive\fP: If \fBtrue\fP, keep the HTTP connection to the storage server open
-to avoid reconnects. The default is \fBfalse\fP.
-.if n .sp
-.RS 4
-.it 1 an-trap
-.nr an-no-space-flag 1
-.nr an-break-flag 1
-.br
-.ps +1
-.B Note
-.ps -1
-.br
-.sp
-Connection keep\-alive is disabled by default because with the current
-HTTP implementation uploads to the remote end might fail in case the server
-closes the connection due to a keep\-alive timeout. If the general case with
-short compilation times should be accelerated or the server is configured with
-a long\-enough timeout, then connection keep\-alive could be enabled.
-.sp .5v
-.RE
+to avoid reconnects. The default is \fBtrue\fP.
.RE
.sp
.RS 4
@@ -1845,7 +2084,13 @@ The default is \fBsubdirs\fP.
.RE
.SS "Redis storage backend"
.sp
-URL format: \fBredis://[[USERNAME:]PASSWORD@]HOST[:PORT][/DBNUMBER]\fP
+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" ""
@@ -1895,7 +2140,7 @@ storage" for hints on setting up a Redis server for use with ccache.
.br
.sp
You can set up a cluster of Redis servers using the \fBshards\fP attribute
-described in \fI[_secondary_storage_backends]\fP.
+described in \fI[_remote_storage_backends]\fP.
.sp .5v
.RE
.sp
@@ -1923,6 +2168,39 @@ Examples:
\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
@@ -2011,6 +2289,10 @@ Set the size and file number counters to match the files that were kept.
The reason for removing more files than just those needed to not exceed the max
limits is that a cleanup is a fairly slow operation, so it would not be a good
idea to trigger it often, like after each cache miss.
+.sp
+The LRU cleanup makes use of the file modification time (mtime) of cache
+entries; ccache updates mtime of the cache entries 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, i.e. all
@@ -2113,7 +2395,7 @@ recompressed.
cleanups (number of performed cleanups, either implicitly due to a cache size
limit being reached or due to explicit \fBccache \-c\fP calls), overall hit rate, hit
rate for direct/preprocessed modes
-and hit rate for primary and secondary storage.
+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
@@ -2180,8 +2462,7 @@ T{
Could not write to output file
T}:T{
.sp
-The output path specified with \fB\-o\fP is not a file (e.g. a directory or a device
-node).
+The output path specified with \fB\-o\fP could not be written to.
T}
T{
.sp
@@ -2200,30 +2481,22 @@ A compiler check program specified by
T}
T{
.sp
-Compiler produced empty output
+Compiler output file missing
T}:T{
.sp
-The compiler\(cqs output file (typically an object file) was empty after
+One of the files expected to be produced by the compiler was missing after
compilation.
T}
T{
.sp
-Compiler produced no output
+Compiler produced empty output
T}:T{
.sp
-The compiler\(cqs output file (typically an object file) was missing after
+The compiler\(cqs output file (typically an object file) was empty after
compilation.
T}
T{
.sp
-Compiler produced stdout
-T}:T{
-.sp
-The compiler wrote data to standard output. This is something that compilers
-normally never do, so ccache is not designed to store such output in the cache.
-T}
-T{
-.sp
Could not find the compiler
T}:T{
.sp
@@ -2307,6 +2580,13 @@ 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
@@ -2616,7 +2896,8 @@ the string \fB__TIME__\fP is present in the source code
If the depend mode is enabled, ccache will not use the preprocessor at all. The
hash used to identify results in the cache will be based on the direct mode
hash described above plus information about include files read from the
-dependency file generated by the compiler with \fB\-MD\fP or \fB\-MMD\fP.
+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
@@ -2669,8 +2950,8 @@ to some types of changes of compiler options and source code changes.
. IP \(bu 2.3
.\}
If \-MD is used, the manifest entries will include system header files as
-well, thus slowing down cache hits slightly, just as using \-MD slows down
-make.
+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
@@ -2681,7 +2962,7 @@ make.
. sp -1
. IP \(bu 2.3
.\}
-If \-MMD is used, the manifest entries will not include system header files,
+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
@@ -2717,13 +2998,14 @@ The depend mode will be disabled if any of the following holds:
. sp -1
. IP \(bu 2.3
.\}
-The compiler is not generating dependencies using \fB\-MD\fP or \fB\-MMD\fP.
+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 the same second as the time compilation is being done, ccache disables
-the direct mode (or, in the case of a precompiled
+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
@@ -2833,35 +3115,35 @@ T}:T{
T}
T{
.sp
-\fB<objectfile>.ccache\-input\-c\fP
+\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>.ccache\-input\-d\fP
+\fB<objectfile>.<timestamp>.ccache\-input\-d\fP
T}:T{
.sp
Binary input only hashed by the direct mode.
T}
T{
.sp
-\fB<objectfile>.ccache\-input\-p\fP
+\fB<objectfile>.<timestamp>.ccache\-input\-p\fP
T}:T{
.sp
Binary input only hashed by the preprocessor mode.
T}
T{
.sp
-\fB<objectfile>.ccache\-input\-text\fP
+\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>.ccache\-log\fP
+\fB<objectfile>.<timestamp>.ccache\-log\fP
T}:T{
.sp
Log for this object file.
@@ -2869,7 +3151,16 @@ T}
.TE
.sp
.sp
-If \fBconfig_dir\fP (environment variable \fBCCACHE_DEBUGDIR\fP) is
+.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
@@ -2894,7 +3185,7 @@ something like this:
. sp -1
. IP " 1." 4.2
.\}
-Build with debug mode enabled.
+Enable \fBdebug\fP (\fBCCACHE_DEBUG\fP).
.RE
.sp
.RS 4
@@ -2905,7 +3196,7 @@ Build with debug mode enabled.
. sp -1
. IP " 2." 4.2
.\}
-Save the \fB<objectfile>.ccache\-*\fP files.
+Build.
.RE
.sp
.RS 4
@@ -2916,7 +3207,7 @@ Save the \fB<objectfile>.ccache\-*\fP files.
. sp -1
. IP " 3." 4.2
.\}
-Build again with debug mode enabled.
+Clean and build again.
.RE
.sp
.RS 4
@@ -2927,9 +3218,9 @@ Build again with debug mode enabled.
. sp -1
. IP " 4." 4.2
.\}
-Compare \fB<objectfile>.ccache\-input\-text\fP for the two builds. This together
-with the \fB<objectfile>.ccache\-log\fP files should give you some clues about
-what is happening.
+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
@@ -3033,8 +3324,8 @@ relative before computing the hash.
.RE
.SH "PRECOMPILED HEADERS"
.sp
-Ccache has support for GCC\(cqs precompiled headers. However, you have to do some
-things to make it work properly:
+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 \{\
@@ -3111,12 +3402,23 @@ the PCH file generated from the precompiled header; or
(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).
-.RE
.SH "C++ MODULES"
.sp
Ccache has support for Clang\(cqs \fB\-fmodules\fP option. In practice ccache only
@@ -3130,10 +3432,10 @@ You must use both \fBdirect mode\fP and
\fBdepend mode\fP. When using
the preprocessor mode Clang does not provide enough
information to allow hashing of \fBmodule.modulemap\fP files.
-.SH "SHARING A CACHE"
+.SH "SHARING A LOCAL CACHE"
.sp
-A group of developers can increase the cache hit rate by sharing a cache
-directory. To share a cache without unpleasant side effects, the following
+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
@@ -3263,7 +3565,7 @@ systems. One way of improving cache hit rate in that case is to set
headers.
.sp
An alternative to putting the main cache directory on NFS is to set up a
-secondary storage file cache.
+remote storage file cache.
.SH "USING CCACHE WITH OTHER COMPILER WRAPPERS"
.sp
The recommended way of combining ccache with another compiler wrapper (such as
diff --git a/srcpkgs/ccache/template b/srcpkgs/ccache/template
index 5c1dc8914258..13268fb11414 100644
--- a/srcpkgs/ccache/template
+++ b/srcpkgs/ccache/template
@@ -1,18 +1,17 @@
# Template file for 'ccache'
pkgname=ccache
-version=4.6.3
+version=4.7.4
revision=1
build_style=cmake
configure_args="-DENABLE_TESTING=OFF -DREDIS_STORAGE_BACKEND=OFF"
-hostmakedepends="perl"
-makedepends="libzstd-devel zlib-devel"
+makedepends="libzstd-devel"
short_desc="Fast C/C++ Compiler Cache"
maintainer="Enno Boland <gottox@voidlinux.org>"
license="GPL-3.0-or-later"
-homepage="https://ccache.samba.org/"
+homepage="https://ccache.dev"
changelog="https://ccache.dev/releasenotes.html"
distfiles="https://github.com/ccache/ccache/releases/download/v${version}/${pkgname}-${version}.tar.xz"
-checksum=1e3a251bb112632553b8255a78661fe526c3a16598496d51128c32b218fd8b22
+checksum=df0c64d15d3efaf0b4f6837dd6b1467e40eeaaa807db25ce79c3a08a46a84e36
if [ -n "$XBPS_CHECK_PKGS" ]; then
configure_args+=" -DENABLE_TESTING=ON"
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: [PR REVIEW] ccache: update to 4.7.4.
2022-12-18 17:10 [PR PATCH] ccache: update to 4.7.4 r-ricci
@ 2022-12-19 5:36 ` classabbyamp
2022-12-19 7:42 ` icp1994
` (4 subsequent siblings)
5 siblings, 0 replies; 7+ messages in thread
From: classabbyamp @ 2022-12-19 5:36 UTC (permalink / raw)
To: ml
[-- Attachment #1: Type: text/plain, Size: 272 bytes --]
New review comment by classabbyamp on void-packages repository
https://github.com/void-linux/void-packages/pull/41168#discussion_r1051826889
Comment:
```suggestion
distfiles="https://github.com/ccache/ccache/releases/download/v${version}/ccache-${version}.tar.xz"
```
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: ccache: update to 4.7.4.
2022-12-18 17:10 [PR PATCH] ccache: update to 4.7.4 r-ricci
2022-12-19 5:36 ` [PR REVIEW] " classabbyamp
@ 2022-12-19 7:42 ` icp1994
2022-12-19 20:25 ` [PR PATCH] [Updated] " r-ricci
` (3 subsequent siblings)
5 siblings, 0 replies; 7+ messages in thread
From: icp1994 @ 2022-12-19 7:42 UTC (permalink / raw)
To: ml
[-- Attachment #1: Type: text/plain, Size: 389 bytes --]
New comment by icp1994 on void-packages repository
https://github.com/void-linux/void-packages/pull/41168#issuecomment-1357220973
Comment:
`perl` was there to help generate [the docs](https://github.com/ccache/ccache/blob/v4.7.4/doc/CMakeLists.txt#L40-L46). But apparently there were issues with asciidoctor (from commit history of ccache) so a pre-generated manpage is shipped instead.
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: [PR PATCH] [Updated] ccache: update to 4.7.4.
2022-12-18 17:10 [PR PATCH] ccache: update to 4.7.4 r-ricci
2022-12-19 5:36 ` [PR REVIEW] " classabbyamp
2022-12-19 7:42 ` icp1994
@ 2022-12-19 20:25 ` r-ricci
2022-12-22 22:07 ` r-ricci
` (2 subsequent siblings)
5 siblings, 0 replies; 7+ messages in thread
From: r-ricci @ 2022-12-19 20:25 UTC (permalink / raw)
To: ml
[-- Attachment #1: Type: text/plain, Size: 1448 bytes --]
There is an updated pull request by r-ricci against master on the void-packages repository
https://github.com/r-ricci/void-packages ccache
https://github.com/void-linux/void-packages/pull/41168
ccache: update to 4.7.4.
<!-- Uncomment relevant sections and delete options which are not applicable -->
It doesn't link to zlib since [version 4.0](https://ccache.dev/releasenotes.html#_ccache_4_0).
I don't know why perl was in hostmakedepends but the build log is identical with and without it.
@Gottox
#### Testing the changes
- I tested the changes in this PR: **YES**
<!--
#### New package
- This new package conforms to the [package requirements](https://github.com/void-linux/void-packages/blob/master/CONTRIBUTING.md#package-requirements): **YES**|**NO**
-->
<!-- Note: If the build is likely to take more than 2 hours, please add ci skip tag as described in
https://github.com/void-linux/void-packages/blob/master/CONTRIBUTING.md#continuous-integration
and test at least one native build and, if supported, at least one cross build.
Ignore this section if this PR is not skipping CI.
-->
<!--
#### Local build testing
- I built this PR locally for my native architecture, (ARCH-LIBC)
- I built this PR locally for these architectures (if supported. mark crossbuilds):
- aarch64-musl
- armv7l
- armv6l-musl
-->
A patch file from https://github.com/void-linux/void-packages/pull/41168.patch is attached
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: github-pr-ccache-41168.patch --]
[-- Type: text/x-diff, Size: 45688 bytes --]
From 5ddd0bef2c173a42ac967f1fa05932f4bfb53278 Mon Sep 17 00:00:00 2001
From: Roberto Ricci <ricci@disroot.org>
Date: Sat, 17 Dec 2022 23:34:19 +0100
Subject: [PATCH] ccache: update to 4.7.4.
---
srcpkgs/ccache/files/ccache.1 | 796 +++++++++++++++++++++++-----------
srcpkgs/ccache/template | 11 +-
2 files changed, 554 insertions(+), 253 deletions(-)
diff --git a/srcpkgs/ccache/files/ccache.1 b/srcpkgs/ccache/files/ccache.1
index 0fe62140c43f..366e4a2b68e2 100644
--- a/srcpkgs/ccache/files/ccache.1
+++ b/srcpkgs/ccache/files/ccache.1
@@ -2,12 +2,12 @@
.\" Title: ccache
.\" Author: [see the "AUTHOR(S)" section]
.\" Generator: Asciidoctor 2.0.15
-.\" Date: 2022-01-05
+.\" Date: 2022-12-18
.\" Manual: \ \&
-.\" Source: Ccache 4.5.1
+.\" Source: Ccache 4.7.4
.\" Language: English
.\"
-.TH "CCACHE" "1" "2022-01-05" "Ccache 4.5.1" "\ \&"
+.TH "CCACHE" "1" "2022-12-18" "Ccache 4.7.4" "\ \&"
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.ss \n[.ss] 0
@@ -34,7 +34,7 @@ ccache \- a fast C/C++ compiler cache
.nf
\fBccache\fP [\fIoptions\fP]
\fBccache\fP \fIcompiler\fP [\fIcompiler options\fP]
-\fIcompiler\fP [\fIcompiler options\fP] (via symbolic link)
+\fIcompiler\fP [\fIcompiler options\fP] (ccache masquerading as the compiler)
.fi
.br
.SH "DESCRIPTION"
@@ -50,16 +50,41 @@ goal are listed under \fICaveats\fP. If you discover an undocumented case where
ccache changes the output of your compiler, please let us know.
.SH "RUN MODES"
.sp
-There are two ways to use ccache. You can either prefix your compilation
-commands with \fBccache\fP or you can let ccache masquerade as the compiler by
-creating a symbolic link (named as the compiler) to ccache. The first method is
-most convenient if you just want to try out ccache or wish to use it for some
-specific projects. The second method is most useful for when you wish to use
-ccache for all your compilations.
+There are two different ways to use ccache to cache a compilation:
.sp
-To use the first method, just make sure that \fBccache\fP is in your \fBPATH\fP.
+.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
-To use the symlinks method, do something like this:
+.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
@@ -67,16 +92,25 @@ To use the symlinks method, do something like this:
cp ccache /usr/local/bin/
ln \-s ccache /usr/local/bin/gcc
ln \-s ccache /usr/local/bin/g++
-ln \-s ccache /usr/local/bin/cc
-ln \-s ccache /usr/local/bin/c++
.fam
.fi
.if n .RE
.sp
-And so forth. This will work as long as the directory with symlinks comes
-before the path to the compiler (which is usually in \fB/usr/bin\fP). After
-installing you may wish to run \(lqwhich gcc\(rq to make sure that the correct link
-is being used.
+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
@@ -93,26 +127,13 @@ but currently doesn\(cqt interact well with other tools that do the same thing.
\fI[_using_ccache_with_other_compiler_wrappers]\fP.
.sp .5v
.RE
-.if n .sp
-.RS 4
-.it 1 an-trap
-.nr an-no-space-flag 1
-.nr an-break-flag 1
-.br
-.ps +1
-.B Warning
-.ps -1
-.br
-.sp
-Use a symbolic links for masquerading, not hard links.
-.sp .5v
.RE
.SH "COMMAND LINE OPTIONS"
.sp
-These command line options only apply when you invoke ccache as \(lqccache\(rq.
-When invoked as a compiler (via a symlink as described in the previous
-section), the normal compiler options apply and you should refer to the
-compiler\(cqs documentation.
+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
@@ -135,8 +156,8 @@ configuration file.
\fB\-\-config\-path\fP \fIPATH\fP
.RS 4
Let the command line options operate on configuration file \fIPATH\fP instead of
-the default. Using this option has the same effect as setting the
-environment variable \fBCCACHE_CONFIGPATH\fP temporarily.
+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
@@ -186,7 +207,7 @@ future compilations.
.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
+\fBcompression_level\fP configuration option, or
the special value \fBuncompressed\fP for no compression. See
\fI[_cache_compression]\fP for more information. This can potentionally take a
long time since all files in the cache need to be visited. Only files that
@@ -241,12 +262,12 @@ Print version and copyright information.
.RS 4
Zero the cache statistics (but not the configuration options).
.RE
-.SS "Options for secondary storage"
+.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.
+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
@@ -258,17 +279,17 @@ by \fB\-\-trim\-max\-size\fP.
.ps -1
.br
.sp
-Don\(cqt use this option to trim the primary cache. To trim the primary
-cache directory to a certain size, use \fBCCACHE_MAXSIZE=\fISIZE\fP ccache \-c\fP.
+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: k, M, G, T (decimal), Ki, Mi, Gi or Ti (binary). The
-default suffix is G.
+Specify the maximum size for \fB\-\-trim\-dir\fP. \fISIZE\fP should be a number
+followed by an optional suffix: k, M, G, T (decimal), Ki, Mi, Gi or Ti
+(binary). The default suffix is G.
.RE
.sp
\fB\-\-trim\-method\fP \fIMETHOD\fP
@@ -295,23 +316,11 @@ Print the checksum (128 bit XXH3) of the file at \fIPATH\fP (\fB\-\fP for standa
input).
.RE
.sp
-\fB\-\-dump\-manifest\fP \fIPATH\fP
-.RS 4
-Dump manifest file at \fIPATH\fP (\fB\-\fP for standard input) in text format to
-standard output. This is only useful when debugging ccache and its behavior.
-.RE
-.sp
-\fB\-\-dump\-result\fP \fIPATH\fP
-.RS 4
-Dump result file at \fIPATH\fP (\fB\-\fP for standard input) in text format to
-standard output. This is only useful when debugging ccache and its behavior.
-.RE
-.sp
\fB\-\-extract\-result\fP \fIPATH\fP
.RS 4
Extract data stored in the result file at \fIPATH\fP (\fB\-\fP for standard input).
The data will be written to \fBccache\-result.*\fP files in to the current
-working directory. This is only useful when debugging ccache and its
+working directory. This option is only useful when debugging ccache and its
behavior.
.RE
.sp
@@ -327,6 +336,15 @@ 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
@@ -394,7 +412,7 @@ Environment variables.
. sp -1
. IP " 2." 4.2
.\}
-The primary (cache\-specific) configuration file (see below).
+The cache\-specific configuration file (see below).
.RE
.sp
.RS 4
@@ -405,9 +423,8 @@ The primary (cache\-specific) configuration file (see below).
. sp -1
. IP " 3." 4.2
.\}
-The secondary (system\-wide read\-only) configuration file
-\fB<sysconfdir>/ccache.conf\fP (typically \fB/etc/ccache.conf\fP or
-\fB/usr/local/etc/ccache.conf\fP).
+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
@@ -421,13 +438,13 @@ The secondary (system\-wide read\-only) configuration file
Compile\-time defaults.
.RE
.sp
-As a special case, if the the environment variable \fBCCACHE_CONFIGPATH\fP is set
-it specifies the primary configuration file and the secondary (system\-wide)
-configuration file won\(cqt be read.
-.SS "Location of the primary configuration file"
+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 primary (cache\-specific) configuration is determined like
-this:
+The location of the cache\-specific configuration file is determined like this on
+non\-Windows systems:
.sp
.RS 4
.ie n \{\
@@ -460,8 +477,8 @@ Otherwise, if the environment variable \fBCCACHE_DIR\fP is set then use
. sp -1
. IP " 3." 4.2
.\}
-Otherwise, if \fBcache_dir\fP is set in the secondary
-(system\-wide) configuration file then use \fB<cache_dir>/ccache.conf\fP.
+Otherwise, if \fBcache_dir\fP is set in the system
+configuration file then use \fB<cache_dir>/ccache.conf\fP.
.RE
.sp
.RS 4
@@ -496,10 +513,87 @@ Otherwise, if \fBXDG_CONFIG_HOME\fP is set then use
. sp -1
. IP " 6." 4.2
.\}
-Otherwise, use \fB%APPDATA%/ccache/ccache.conf\fP (Windows),
+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
@@ -639,19 +733,56 @@ 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.
-The default is \fB$XDG_CACHE_HOME/ccache\fP if \fBXDG_CACHE_HOME\fP is set,
-otherwise \fB$HOME/.cache/ccache\fP. Exception: If the legacy directory
-\fB$HOME/.ccache\fP exists then that directory is the default.
.sp
-See also \fI[_location_of_the_primary_configuration_file]\fP.
+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
-If you want to use another \fBCCACHE_DIR\fP value temporarily for one ccache
-invocation you can use the \fB\-d\fP/\fB\-\-dir\fP command line option instead.
+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 \fI[_location_of_the_configuration_file]\fP.
.RE
.sp
\fBcompiler\fP (\fBCCACHE_COMPILER\fP or (deprecated) \fBCCACHE_CC\fP)
@@ -665,8 +796,9 @@ command line.
.RS 4
By default, ccache includes the modification time (\(lqmtime\(rq) and size of
the compiler in the hash to ensure that results retrieved from the cache
-are accurate. This option can be used to select another strategy. Possible
-values are:
+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
@@ -756,11 +888,26 @@ symlinks). This is the default.
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.
@@ -770,11 +917,6 @@ NVCC (CUDA) compiler.
.RS 4
Any compiler other than the known types.
.RE
-.sp
-\fBpump\fP
-.RS 4
-distcc\(cqs \(lqpump\(rq script.
-.RE
.RE
.sp
\fBcompression\fP (\fBCCACHE_COMPRESS\fP or \fBCCACHE_NOCOMPRESS\fP, see \fI[_boolean_values]\fP above)
@@ -944,11 +1086,11 @@ Do not enable this option unless you are aware of these caveats:
If the resulting file is modified, the file in the cache will also be
modified since they share content, which corrupts the cache entry. As of
version 4.0, ccache makes stored and fetched object files read\-only as a
-safety measure guard. Furthermore, a simple integrity check is made for
-cached object files by verifying that their sizes are correct. This means
-that mistakes like \fBstrip file.o\fP or \fBecho >file.o\fP will be detected even if
-the object file is made writeable, but a modification that doesn\(cqt change the
-file size will not.
+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 writeable, but a modification that doesn\(cqt change the file
+size will not.
.RE
.sp
.RS 4
@@ -1024,20 +1166,32 @@ example, \fB\-fmessage\-length=*\fP will match both \fB\-fmessage\-length=20\fP
.sp
\fBinode_cache\fP (\fBCCACHE_INODECACHE\fP or \fBCCACHE_NOINODECACHE\fP, see \fI[_boolean_values]\fP above)
.RS 4
-If true, enables caching of source file hashes based on device, inode and
-timestamps. This will reduce the time spent on hashing included files as
-the result can be resused between compilations.
-.sp
-The feature is still experimental and thus off by default. It is currently not
-available on Windows.
+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 resused 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 feature requires \fBtemporary_dir\fP to be located on a local filesystem.
+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 \fI[_boolean_values]\fP above)
.RS 4
If true, ccache will not discard the comments before hashing preprocessor
-output. This can be used to check documentation with \fB\-Wdocumentation\fP.
+output. The default is false. This can be used to check documentation with
+\fB\-Wdocumentation\fP.
.RE
.sp
\fBlimit_multiple\fP (\fBCCACHE_LIMIT_MULTIPLE\fP)
@@ -1082,18 +1236,25 @@ Gi, Ti (binary). The default suffix is G. See also
\fI[_cache_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
+If set, the namespace string will be added to the hashed data for each
compilation. This will make the associated cache entries logically separate
from cache entries with other namespaces, but they will still share the same
-storage space. Cache entries can also be selectively removed from the
-primary cache with the command line option \fB\-\-evict\-namespace\fP, potentially
-in combination with \fB\-\-evict\-older\-than\fP.
-\&.
-For instance, if you use the same primary cache for several disparate projects,
+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 stop working with that
+cache entries that belong to a certain project if you stop working with that
project.
.RE
.sp
@@ -1155,40 +1316,20 @@ If true, ccache will not use any previously stored result. New results will
still be cached, possibly overwriting any pre\-existing results.
.RE
.sp
-\fBreshare\fP (\fBCCACHE_RESHARE\fP or \fBCCACHE_NORESHARE\fP, see \fI[_boolean_values]\fP above)
+\fBremote_only\fP (\fBCCACHE_REMOTE_ONLY\fP or \fBCCACHE_NOREMOTE_ONLY\fP, see \fI[_boolean_values]\fP above)
.RS 4
-If true, ccache will write results to secondary storage even for primary
-storage cache hits. The default is false.
+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
+\fI[_storage_interaction]\fP.
.RE
.sp
-\fBrun_second_cpp\fP (\fBCCACHE_CPP2\fP or \fBCCACHE_NOCPP2\fP, see \fI[_boolean_values]\fP above)
-.RS 4
-If true, ccache will first run the preprocessor to preprocess the source
-code (see \fI[_the_preprocessor_mode]\fP) and then on a cache miss run the
-compiler on the source code to get hold of the object file. This is the
-default.
-.sp
-If false, ccache will first run preprocessor to preprocess the source code and
-then on a cache miss run the compiler on the \fIpreprocessed source code\fP instead
-of the original source code. This makes cache misses slightly faster since the
-source code only has to be preprocessed once. The downside is that some
-compilers won\(cqt produce the same result (for instance diagnostics warnings)
-when compiling preprocessed source code.
-.sp
-A solution to the above mentioned downside is to set \fBrun_second_cpp\fP to false
-and pass \fB\-fdirectives\-only\fP (for GCC) or \fB\-frewrite\-includes\fP (for Clang) to
-the compiler. This will cause the compiler to leave the macros and other
-preprocessor information, and only process the \fB#include\fP directives. When run
-in this way, the preprocessor arguments will be passed to the compiler since it
-still has to do \fIsome\fP preprocessing (like macros).
-.RE
-.sp
-\fBsecondary_storage\fP (\fBCCACHE_SECONDARY_STORAGE\fP)
+\fBremote_storage\fP (\fBCCACHE_REMOTE_STORAGE\fP)
.RS 4
This option specifies one or several storage backends (separated by space)
-to query after the primary cache storage. See
-\fI[_secondary_storage_backends]\fP for documentation of syntax and available
-backends.
+to query after checking the local cache (unless
+\fBremote_only\fP is true). See \fI[Remote storage
+backends]\fP for documentation of syntax and available backends.
.sp
Examples:
.sp
@@ -1234,8 +1375,54 @@ Examples:
. 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 \fI[_boolean_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 \fI[_boolean_values]\fP above)
+.RS 4
+If true, ccache will first run the preprocessor to preprocess the source
+code (see \fI[_the_preprocessor_mode]\fP) and then on a cache miss run the
+compiler on the source code to get hold of the object file. This is the
+default.
+.sp
+If false, ccache will first run preprocessor to preprocess the source code and
+then on a cache miss run the compiler on the \fIpreprocessed source code\fP instead
+of the original source code. This makes cache misses slightly faster since the
+source code only has to be preprocessed once. The downside is that some
+compilers won\(cqt produce the same result (for instance diagnostics warnings)
+when compiling preprocessed source code.
+.sp
+A solution to the above mentioned downside is to set \fBrun_second_cpp\fP to false
+and pass \fB\-fdirectives\-only\fP (for GCC) or \fB\-frewrite\-includes\fP (for Clang) to
+the compiler. This will cause the compiler to leave the macros and other
+preprocessor information, and only process the \fB#include\fP directives. When run
+in this way, the preprocessor arguments will be passed to the compiler since it
+still has to do \fIsome\fP preprocessing (like macros).
+.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
@@ -1268,18 +1455,30 @@ 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 not cache a file if it includes a header whose ctime
-is too new. This sloppiness disables that check. See also
-\fI[_handling_of_newly_created_header_files]\fP.
+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 not cache a file if it includes a header whose mtime
-is too new. This sloppiness disables that check. See also
-\fI[_handling_of_newly_created_header_files]\fP.
+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
@@ -1297,18 +1496,25 @@ 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
+\fI[_c_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
\fI[_precompiled_headers]\fP for more information.
.RE
.sp
-\fBmodules\fP
+\fBrandom_seed\fP
.RS 4
-By default, ccache will not cache compilations if \fB\-fmodules\fP is used since
-it cannot hash the state of compiler\(cqs internal representation of relevant
-modules. This sloppiness allows caching in such a case. See
-\fI[_c_modules]\fP for more information.
+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
@@ -1357,7 +1563,8 @@ Lines in the stats log starting with a hash sign (\fB#\fP) are comments.
\fBtemporary_dir\fP (\fBCCACHE_TEMPDIR\fP)
.RS 4
This option specifies where ccache will put temporary files. The default is
-\fB/run/user/<UID>/ccache\-tmp\fP if \fB/run/user/<UID>\fP exists, otherwise
+\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
@@ -1382,23 +1589,25 @@ This option (an octal integer) specifies the umask for files and directories
in the cache directory. This is mostly useful when you wish to share your
cache with other users.
.RE
-.SH "SECONDARY STORAGE BACKENDS"
+.SH "REMOTE STORAGE BACKENDS"
.sp
-The \fBsecondary_storage\fP option lets you configure
-ccache to use one or several other storage backends in addition to the primary
-cache storage located in \fBcache_dir\fP. Note that cache
-statistics counters will still be kept in the primary cache directory \(em secondary storage backends only store cache results and manifests.
+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 secondary storage backend is specified with a URL, optionally followed by a
-pipe (\fB|\fP) and a pipe\-separated list of attributes. An attribute is
-\fIkey\fP=\fIvalue\fP or just \fIkey\fP as a short form of \fIkey\fP=\fBtrue\fP. Attribute values
-must be \c
+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.
+if they contain
+percent, pipe or space characters.
.SS "Attributes for all backends"
.sp
-These optional attributes are available for all secondary storage backends:
+These optional attributes are available for all remote storage backends:
.sp
.RS 4
.ie n \{\
@@ -1460,31 +1669,20 @@ of the cache on \fBredis://cache\-a.example.com\fP, 18% (1/5.5) on
\fBhttp://example.com/alpha\fP and 50% on \fBhttp://example.com/beta\fP.
.RE
.RE
-.sp
-.RS 4
-.ie n \{\
-\h'-04'\(bu\h'+03'\c
-.\}
-.el \{\
-. sp -1
-. IP \(bu 2.3
-.\}
-\fBshare\-hits\fP: If \fBtrue\fP, write hits for this backend to primary storage. The
-default is \fBtrue\fP.
-.RE
.SS "Storage interaction"
.sp
-The table below describes the interaction between primary and secondary storage
-on cache hits and misses:
+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
-\fBPrimary storage\fP
+\fBLocal storage\fP
T}:T{
.sp
-\fBSecondary storage\fP
+\fBRemote storage\fP
T}:T{
.sp
\fBWhat happens\fP
@@ -1497,7 +1695,7 @@ T}:T{
miss
T}:T{
.sp
-Compile, write to primary, write to secondary[1]
+Compile, write to local, write to remote[1]
T}
T{
.sp
@@ -1507,7 +1705,7 @@ T}:T{
hit
T}:T{
.sp
-Read from secondary, write to primary[2]
+Read from remote, write to local
T}
T{
.sp
@@ -1517,25 +1715,62 @@ T}:T{
\-
T}:T{
.sp
-Read from primary, don\(cqt write to secondary[3]
+Read from local, don\(cqt write to remote[2]
T}
.TE
.sp
.sp
-[1] Unless secondary storage has attribute \fBread\-only=true\fP.
+[1] Unless remote storage has attribute \fBread\-only=true\fP.
.br
-[2] Unless secondary storage has attribute \fBshare\-hits=false\fP.
-.br
-[3] Unless primary storage is set to share its cache hits with the
+[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://DIRECTORY\fP
+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 (an absolute path), similar (but not identical) to the primary cache
-storage. A typical use case for this backend would be sharing a cache on an NFS
-directory.
+\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
@@ -1576,6 +1811,17 @@ Examples:
\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
@@ -1733,6 +1979,17 @@ Optional attributes:
. 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
@@ -1745,25 +2002,7 @@ Optional attributes:
. IP \(bu 2.3
.\}
\fBkeep\-alive\fP: If \fBtrue\fP, keep the HTTP connection to the storage server open
-to avoid reconnects. The default is \fBfalse\fP.
-.if n .sp
-.RS 4
-.it 1 an-trap
-.nr an-no-space-flag 1
-.nr an-break-flag 1
-.br
-.ps +1
-.B Note
-.ps -1
-.br
-.sp
-Connection keep\-alive is disabled by default because with the current
-HTTP implementation uploads to the remote end might fail in case the server
-closes the connection due to a keep\-alive timeout. If the general case with
-short compilation times should be accelerated or the server is configured with
-a long\-enough timeout, then connection keep\-alive could be enabled.
-.sp .5v
-.RE
+to avoid reconnects. The default is \fBtrue\fP.
.RE
.sp
.RS 4
@@ -1845,7 +2084,13 @@ The default is \fBsubdirs\fP.
.RE
.SS "Redis storage backend"
.sp
-URL format: \fBredis://[[USERNAME:]PASSWORD@]HOST[:PORT][/DBNUMBER]\fP
+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" ""
@@ -1895,7 +2140,7 @@ storage" for hints on setting up a Redis server for use with ccache.
.br
.sp
You can set up a cluster of Redis servers using the \fBshards\fP attribute
-described in \fI[_secondary_storage_backends]\fP.
+described in \fI[_remote_storage_backends]\fP.
.sp .5v
.RE
.sp
@@ -1923,6 +2168,39 @@ Examples:
\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
@@ -2011,6 +2289,10 @@ Set the size and file number counters to match the files that were kept.
The reason for removing more files than just those needed to not exceed the max
limits is that a cleanup is a fairly slow operation, so it would not be a good
idea to trigger it often, like after each cache miss.
+.sp
+The LRU cleanup makes use of the file modification time (mtime) of cache
+entries; ccache updates mtime of the cache entries 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, i.e. all
@@ -2113,7 +2395,7 @@ recompressed.
cleanups (number of performed cleanups, either implicitly due to a cache size
limit being reached or due to explicit \fBccache \-c\fP calls), overall hit rate, hit
rate for direct/preprocessed modes
-and hit rate for primary and secondary storage.
+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
@@ -2180,8 +2462,7 @@ T{
Could not write to output file
T}:T{
.sp
-The output path specified with \fB\-o\fP is not a file (e.g. a directory or a device
-node).
+The output path specified with \fB\-o\fP could not be written to.
T}
T{
.sp
@@ -2200,30 +2481,22 @@ A compiler check program specified by
T}
T{
.sp
-Compiler produced empty output
+Compiler output file missing
T}:T{
.sp
-The compiler\(cqs output file (typically an object file) was empty after
+One of the files expected to be produced by the compiler was missing after
compilation.
T}
T{
.sp
-Compiler produced no output
+Compiler produced empty output
T}:T{
.sp
-The compiler\(cqs output file (typically an object file) was missing after
+The compiler\(cqs output file (typically an object file) was empty after
compilation.
T}
T{
.sp
-Compiler produced stdout
-T}:T{
-.sp
-The compiler wrote data to standard output. This is something that compilers
-normally never do, so ccache is not designed to store such output in the cache.
-T}
-T{
-.sp
Could not find the compiler
T}:T{
.sp
@@ -2307,6 +2580,13 @@ 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
@@ -2616,7 +2896,8 @@ the string \fB__TIME__\fP is present in the source code
If the depend mode is enabled, ccache will not use the preprocessor at all. The
hash used to identify results in the cache will be based on the direct mode
hash described above plus information about include files read from the
-dependency file generated by the compiler with \fB\-MD\fP or \fB\-MMD\fP.
+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
@@ -2669,8 +2950,8 @@ to some types of changes of compiler options and source code changes.
. IP \(bu 2.3
.\}
If \-MD is used, the manifest entries will include system header files as
-well, thus slowing down cache hits slightly, just as using \-MD slows down
-make.
+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
@@ -2681,7 +2962,7 @@ make.
. sp -1
. IP \(bu 2.3
.\}
-If \-MMD is used, the manifest entries will not include system header files,
+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
@@ -2717,13 +2998,14 @@ The depend mode will be disabled if any of the following holds:
. sp -1
. IP \(bu 2.3
.\}
-The compiler is not generating dependencies using \fB\-MD\fP or \fB\-MMD\fP.
+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 the same second as the time compilation is being done, ccache disables
-the direct mode (or, in the case of a precompiled
+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
@@ -2833,35 +3115,35 @@ T}:T{
T}
T{
.sp
-\fB<objectfile>.ccache\-input\-c\fP
+\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>.ccache\-input\-d\fP
+\fB<objectfile>.<timestamp>.ccache\-input\-d\fP
T}:T{
.sp
Binary input only hashed by the direct mode.
T}
T{
.sp
-\fB<objectfile>.ccache\-input\-p\fP
+\fB<objectfile>.<timestamp>.ccache\-input\-p\fP
T}:T{
.sp
Binary input only hashed by the preprocessor mode.
T}
T{
.sp
-\fB<objectfile>.ccache\-input\-text\fP
+\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>.ccache\-log\fP
+\fB<objectfile>.<timestamp>.ccache\-log\fP
T}:T{
.sp
Log for this object file.
@@ -2869,7 +3151,16 @@ T}
.TE
.sp
.sp
-If \fBconfig_dir\fP (environment variable \fBCCACHE_DEBUGDIR\fP) is
+.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
@@ -2894,7 +3185,7 @@ something like this:
. sp -1
. IP " 1." 4.2
.\}
-Build with debug mode enabled.
+Enable \fBdebug\fP (\fBCCACHE_DEBUG\fP).
.RE
.sp
.RS 4
@@ -2905,7 +3196,7 @@ Build with debug mode enabled.
. sp -1
. IP " 2." 4.2
.\}
-Save the \fB<objectfile>.ccache\-*\fP files.
+Build.
.RE
.sp
.RS 4
@@ -2916,7 +3207,7 @@ Save the \fB<objectfile>.ccache\-*\fP files.
. sp -1
. IP " 3." 4.2
.\}
-Build again with debug mode enabled.
+Clean and build again.
.RE
.sp
.RS 4
@@ -2927,9 +3218,9 @@ Build again with debug mode enabled.
. sp -1
. IP " 4." 4.2
.\}
-Compare \fB<objectfile>.ccache\-input\-text\fP for the two builds. This together
-with the \fB<objectfile>.ccache\-log\fP files should give you some clues about
-what is happening.
+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
@@ -3033,8 +3324,8 @@ relative before computing the hash.
.RE
.SH "PRECOMPILED HEADERS"
.sp
-Ccache has support for GCC\(cqs precompiled headers. However, you have to do some
-things to make it work properly:
+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 \{\
@@ -3111,12 +3402,23 @@ the PCH file generated from the precompiled header; or
(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).
-.RE
.SH "C++ MODULES"
.sp
Ccache has support for Clang\(cqs \fB\-fmodules\fP option. In practice ccache only
@@ -3130,10 +3432,10 @@ You must use both \fBdirect mode\fP and
\fBdepend mode\fP. When using
the preprocessor mode Clang does not provide enough
information to allow hashing of \fBmodule.modulemap\fP files.
-.SH "SHARING A CACHE"
+.SH "SHARING A LOCAL CACHE"
.sp
-A group of developers can increase the cache hit rate by sharing a cache
-directory. To share a cache without unpleasant side effects, the following
+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
@@ -3263,7 +3565,7 @@ systems. One way of improving cache hit rate in that case is to set
headers.
.sp
An alternative to putting the main cache directory on NFS is to set up a
-secondary storage file cache.
+remote storage file cache.
.SH "USING CCACHE WITH OTHER COMPILER WRAPPERS"
.sp
The recommended way of combining ccache with another compiler wrapper (such as
diff --git a/srcpkgs/ccache/template b/srcpkgs/ccache/template
index 5c1dc8914258..4e15bf4207bb 100644
--- a/srcpkgs/ccache/template
+++ b/srcpkgs/ccache/template
@@ -1,18 +1,17 @@
# Template file for 'ccache'
pkgname=ccache
-version=4.6.3
+version=4.7.4
revision=1
build_style=cmake
configure_args="-DENABLE_TESTING=OFF -DREDIS_STORAGE_BACKEND=OFF"
-hostmakedepends="perl"
-makedepends="libzstd-devel zlib-devel"
+makedepends="libzstd-devel"
short_desc="Fast C/C++ Compiler Cache"
maintainer="Enno Boland <gottox@voidlinux.org>"
license="GPL-3.0-or-later"
-homepage="https://ccache.samba.org/"
+homepage="https://ccache.dev"
changelog="https://ccache.dev/releasenotes.html"
-distfiles="https://github.com/ccache/ccache/releases/download/v${version}/${pkgname}-${version}.tar.xz"
-checksum=1e3a251bb112632553b8255a78661fe526c3a16598496d51128c32b218fd8b22
+distfiles="https://github.com/ccache/ccache/releases/download/v${version}/ccache-${version}.tar.xz"
+checksum=df0c64d15d3efaf0b4f6837dd6b1467e40eeaaa807db25ce79c3a08a46a84e36
if [ -n "$XBPS_CHECK_PKGS" ]; then
configure_args+=" -DENABLE_TESTING=ON"
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: [PR PATCH] [Updated] ccache: update to 4.7.4.
2022-12-18 17:10 [PR PATCH] ccache: update to 4.7.4 r-ricci
` (2 preceding siblings ...)
2022-12-19 20:25 ` [PR PATCH] [Updated] " r-ricci
@ 2022-12-22 22:07 ` r-ricci
2022-12-27 16:37 ` r-ricci
2022-12-27 17:45 ` [PR PATCH] [Merged]: " paper42
5 siblings, 0 replies; 7+ messages in thread
From: r-ricci @ 2022-12-22 22:07 UTC (permalink / raw)
To: ml
[-- Attachment #1: Type: text/plain, Size: 1448 bytes --]
There is an updated pull request by r-ricci against master on the void-packages repository
https://github.com/r-ricci/void-packages ccache
https://github.com/void-linux/void-packages/pull/41168
ccache: update to 4.7.4.
<!-- Uncomment relevant sections and delete options which are not applicable -->
It doesn't link to zlib since [version 4.0](https://ccache.dev/releasenotes.html#_ccache_4_0).
I don't know why perl was in hostmakedepends but the build log is identical with and without it.
@Gottox
#### Testing the changes
- I tested the changes in this PR: **YES**
<!--
#### New package
- This new package conforms to the [package requirements](https://github.com/void-linux/void-packages/blob/master/CONTRIBUTING.md#package-requirements): **YES**|**NO**
-->
<!-- Note: If the build is likely to take more than 2 hours, please add ci skip tag as described in
https://github.com/void-linux/void-packages/blob/master/CONTRIBUTING.md#continuous-integration
and test at least one native build and, if supported, at least one cross build.
Ignore this section if this PR is not skipping CI.
-->
<!--
#### Local build testing
- I built this PR locally for my native architecture, (ARCH-LIBC)
- I built this PR locally for these architectures (if supported. mark crossbuilds):
- aarch64-musl
- armv7l
- armv6l-musl
-->
A patch file from https://github.com/void-linux/void-packages/pull/41168.patch is attached
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: github-pr-ccache-41168.patch --]
[-- Type: text/x-diff, Size: 45688 bytes --]
From 0c3e289eb74c31d0c50f281ecf04e428a35a9656 Mon Sep 17 00:00:00 2001
From: Roberto Ricci <ricci@disroot.org>
Date: Sat, 17 Dec 2022 23:34:19 +0100
Subject: [PATCH] ccache: update to 4.7.4.
---
srcpkgs/ccache/files/ccache.1 | 796 +++++++++++++++++++++++-----------
srcpkgs/ccache/template | 11 +-
2 files changed, 554 insertions(+), 253 deletions(-)
diff --git a/srcpkgs/ccache/files/ccache.1 b/srcpkgs/ccache/files/ccache.1
index 0fe62140c43f..366e4a2b68e2 100644
--- a/srcpkgs/ccache/files/ccache.1
+++ b/srcpkgs/ccache/files/ccache.1
@@ -2,12 +2,12 @@
.\" Title: ccache
.\" Author: [see the "AUTHOR(S)" section]
.\" Generator: Asciidoctor 2.0.15
-.\" Date: 2022-01-05
+.\" Date: 2022-12-18
.\" Manual: \ \&
-.\" Source: Ccache 4.5.1
+.\" Source: Ccache 4.7.4
.\" Language: English
.\"
-.TH "CCACHE" "1" "2022-01-05" "Ccache 4.5.1" "\ \&"
+.TH "CCACHE" "1" "2022-12-18" "Ccache 4.7.4" "\ \&"
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.ss \n[.ss] 0
@@ -34,7 +34,7 @@ ccache \- a fast C/C++ compiler cache
.nf
\fBccache\fP [\fIoptions\fP]
\fBccache\fP \fIcompiler\fP [\fIcompiler options\fP]
-\fIcompiler\fP [\fIcompiler options\fP] (via symbolic link)
+\fIcompiler\fP [\fIcompiler options\fP] (ccache masquerading as the compiler)
.fi
.br
.SH "DESCRIPTION"
@@ -50,16 +50,41 @@ goal are listed under \fICaveats\fP. If you discover an undocumented case where
ccache changes the output of your compiler, please let us know.
.SH "RUN MODES"
.sp
-There are two ways to use ccache. You can either prefix your compilation
-commands with \fBccache\fP or you can let ccache masquerade as the compiler by
-creating a symbolic link (named as the compiler) to ccache. The first method is
-most convenient if you just want to try out ccache or wish to use it for some
-specific projects. The second method is most useful for when you wish to use
-ccache for all your compilations.
+There are two different ways to use ccache to cache a compilation:
.sp
-To use the first method, just make sure that \fBccache\fP is in your \fBPATH\fP.
+.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
-To use the symlinks method, do something like this:
+.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
@@ -67,16 +92,25 @@ To use the symlinks method, do something like this:
cp ccache /usr/local/bin/
ln \-s ccache /usr/local/bin/gcc
ln \-s ccache /usr/local/bin/g++
-ln \-s ccache /usr/local/bin/cc
-ln \-s ccache /usr/local/bin/c++
.fam
.fi
.if n .RE
.sp
-And so forth. This will work as long as the directory with symlinks comes
-before the path to the compiler (which is usually in \fB/usr/bin\fP). After
-installing you may wish to run \(lqwhich gcc\(rq to make sure that the correct link
-is being used.
+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
@@ -93,26 +127,13 @@ but currently doesn\(cqt interact well with other tools that do the same thing.
\fI[_using_ccache_with_other_compiler_wrappers]\fP.
.sp .5v
.RE
-.if n .sp
-.RS 4
-.it 1 an-trap
-.nr an-no-space-flag 1
-.nr an-break-flag 1
-.br
-.ps +1
-.B Warning
-.ps -1
-.br
-.sp
-Use a symbolic links for masquerading, not hard links.
-.sp .5v
.RE
.SH "COMMAND LINE OPTIONS"
.sp
-These command line options only apply when you invoke ccache as \(lqccache\(rq.
-When invoked as a compiler (via a symlink as described in the previous
-section), the normal compiler options apply and you should refer to the
-compiler\(cqs documentation.
+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
@@ -135,8 +156,8 @@ configuration file.
\fB\-\-config\-path\fP \fIPATH\fP
.RS 4
Let the command line options operate on configuration file \fIPATH\fP instead of
-the default. Using this option has the same effect as setting the
-environment variable \fBCCACHE_CONFIGPATH\fP temporarily.
+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
@@ -186,7 +207,7 @@ future compilations.
.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
+\fBcompression_level\fP configuration option, or
the special value \fBuncompressed\fP for no compression. See
\fI[_cache_compression]\fP for more information. This can potentionally take a
long time since all files in the cache need to be visited. Only files that
@@ -241,12 +262,12 @@ Print version and copyright information.
.RS 4
Zero the cache statistics (but not the configuration options).
.RE
-.SS "Options for secondary storage"
+.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.
+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
@@ -258,17 +279,17 @@ by \fB\-\-trim\-max\-size\fP.
.ps -1
.br
.sp
-Don\(cqt use this option to trim the primary cache. To trim the primary
-cache directory to a certain size, use \fBCCACHE_MAXSIZE=\fISIZE\fP ccache \-c\fP.
+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: k, M, G, T (decimal), Ki, Mi, Gi or Ti (binary). The
-default suffix is G.
+Specify the maximum size for \fB\-\-trim\-dir\fP. \fISIZE\fP should be a number
+followed by an optional suffix: k, M, G, T (decimal), Ki, Mi, Gi or Ti
+(binary). The default suffix is G.
.RE
.sp
\fB\-\-trim\-method\fP \fIMETHOD\fP
@@ -295,23 +316,11 @@ Print the checksum (128 bit XXH3) of the file at \fIPATH\fP (\fB\-\fP for standa
input).
.RE
.sp
-\fB\-\-dump\-manifest\fP \fIPATH\fP
-.RS 4
-Dump manifest file at \fIPATH\fP (\fB\-\fP for standard input) in text format to
-standard output. This is only useful when debugging ccache and its behavior.
-.RE
-.sp
-\fB\-\-dump\-result\fP \fIPATH\fP
-.RS 4
-Dump result file at \fIPATH\fP (\fB\-\fP for standard input) in text format to
-standard output. This is only useful when debugging ccache and its behavior.
-.RE
-.sp
\fB\-\-extract\-result\fP \fIPATH\fP
.RS 4
Extract data stored in the result file at \fIPATH\fP (\fB\-\fP for standard input).
The data will be written to \fBccache\-result.*\fP files in to the current
-working directory. This is only useful when debugging ccache and its
+working directory. This option is only useful when debugging ccache and its
behavior.
.RE
.sp
@@ -327,6 +336,15 @@ 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
@@ -394,7 +412,7 @@ Environment variables.
. sp -1
. IP " 2." 4.2
.\}
-The primary (cache\-specific) configuration file (see below).
+The cache\-specific configuration file (see below).
.RE
.sp
.RS 4
@@ -405,9 +423,8 @@ The primary (cache\-specific) configuration file (see below).
. sp -1
. IP " 3." 4.2
.\}
-The secondary (system\-wide read\-only) configuration file
-\fB<sysconfdir>/ccache.conf\fP (typically \fB/etc/ccache.conf\fP or
-\fB/usr/local/etc/ccache.conf\fP).
+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
@@ -421,13 +438,13 @@ The secondary (system\-wide read\-only) configuration file
Compile\-time defaults.
.RE
.sp
-As a special case, if the the environment variable \fBCCACHE_CONFIGPATH\fP is set
-it specifies the primary configuration file and the secondary (system\-wide)
-configuration file won\(cqt be read.
-.SS "Location of the primary configuration file"
+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 primary (cache\-specific) configuration is determined like
-this:
+The location of the cache\-specific configuration file is determined like this on
+non\-Windows systems:
.sp
.RS 4
.ie n \{\
@@ -460,8 +477,8 @@ Otherwise, if the environment variable \fBCCACHE_DIR\fP is set then use
. sp -1
. IP " 3." 4.2
.\}
-Otherwise, if \fBcache_dir\fP is set in the secondary
-(system\-wide) configuration file then use \fB<cache_dir>/ccache.conf\fP.
+Otherwise, if \fBcache_dir\fP is set in the system
+configuration file then use \fB<cache_dir>/ccache.conf\fP.
.RE
.sp
.RS 4
@@ -496,10 +513,87 @@ Otherwise, if \fBXDG_CONFIG_HOME\fP is set then use
. sp -1
. IP " 6." 4.2
.\}
-Otherwise, use \fB%APPDATA%/ccache/ccache.conf\fP (Windows),
+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
@@ -639,19 +733,56 @@ 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.
-The default is \fB$XDG_CACHE_HOME/ccache\fP if \fBXDG_CACHE_HOME\fP is set,
-otherwise \fB$HOME/.cache/ccache\fP. Exception: If the legacy directory
-\fB$HOME/.ccache\fP exists then that directory is the default.
.sp
-See also \fI[_location_of_the_primary_configuration_file]\fP.
+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
-If you want to use another \fBCCACHE_DIR\fP value temporarily for one ccache
-invocation you can use the \fB\-d\fP/\fB\-\-dir\fP command line option instead.
+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 \fI[_location_of_the_configuration_file]\fP.
.RE
.sp
\fBcompiler\fP (\fBCCACHE_COMPILER\fP or (deprecated) \fBCCACHE_CC\fP)
@@ -665,8 +796,9 @@ command line.
.RS 4
By default, ccache includes the modification time (\(lqmtime\(rq) and size of
the compiler in the hash to ensure that results retrieved from the cache
-are accurate. This option can be used to select another strategy. Possible
-values are:
+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
@@ -756,11 +888,26 @@ symlinks). This is the default.
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.
@@ -770,11 +917,6 @@ NVCC (CUDA) compiler.
.RS 4
Any compiler other than the known types.
.RE
-.sp
-\fBpump\fP
-.RS 4
-distcc\(cqs \(lqpump\(rq script.
-.RE
.RE
.sp
\fBcompression\fP (\fBCCACHE_COMPRESS\fP or \fBCCACHE_NOCOMPRESS\fP, see \fI[_boolean_values]\fP above)
@@ -944,11 +1086,11 @@ Do not enable this option unless you are aware of these caveats:
If the resulting file is modified, the file in the cache will also be
modified since they share content, which corrupts the cache entry. As of
version 4.0, ccache makes stored and fetched object files read\-only as a
-safety measure guard. Furthermore, a simple integrity check is made for
-cached object files by verifying that their sizes are correct. This means
-that mistakes like \fBstrip file.o\fP or \fBecho >file.o\fP will be detected even if
-the object file is made writeable, but a modification that doesn\(cqt change the
-file size will not.
+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 writeable, but a modification that doesn\(cqt change the file
+size will not.
.RE
.sp
.RS 4
@@ -1024,20 +1166,32 @@ example, \fB\-fmessage\-length=*\fP will match both \fB\-fmessage\-length=20\fP
.sp
\fBinode_cache\fP (\fBCCACHE_INODECACHE\fP or \fBCCACHE_NOINODECACHE\fP, see \fI[_boolean_values]\fP above)
.RS 4
-If true, enables caching of source file hashes based on device, inode and
-timestamps. This will reduce the time spent on hashing included files as
-the result can be resused between compilations.
-.sp
-The feature is still experimental and thus off by default. It is currently not
-available on Windows.
+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 resused 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 feature requires \fBtemporary_dir\fP to be located on a local filesystem.
+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 \fI[_boolean_values]\fP above)
.RS 4
If true, ccache will not discard the comments before hashing preprocessor
-output. This can be used to check documentation with \fB\-Wdocumentation\fP.
+output. The default is false. This can be used to check documentation with
+\fB\-Wdocumentation\fP.
.RE
.sp
\fBlimit_multiple\fP (\fBCCACHE_LIMIT_MULTIPLE\fP)
@@ -1082,18 +1236,25 @@ Gi, Ti (binary). The default suffix is G. See also
\fI[_cache_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
+If set, the namespace string will be added to the hashed data for each
compilation. This will make the associated cache entries logically separate
from cache entries with other namespaces, but they will still share the same
-storage space. Cache entries can also be selectively removed from the
-primary cache with the command line option \fB\-\-evict\-namespace\fP, potentially
-in combination with \fB\-\-evict\-older\-than\fP.
-\&.
-For instance, if you use the same primary cache for several disparate projects,
+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 stop working with that
+cache entries that belong to a certain project if you stop working with that
project.
.RE
.sp
@@ -1155,40 +1316,20 @@ If true, ccache will not use any previously stored result. New results will
still be cached, possibly overwriting any pre\-existing results.
.RE
.sp
-\fBreshare\fP (\fBCCACHE_RESHARE\fP or \fBCCACHE_NORESHARE\fP, see \fI[_boolean_values]\fP above)
+\fBremote_only\fP (\fBCCACHE_REMOTE_ONLY\fP or \fBCCACHE_NOREMOTE_ONLY\fP, see \fI[_boolean_values]\fP above)
.RS 4
-If true, ccache will write results to secondary storage even for primary
-storage cache hits. The default is false.
+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
+\fI[_storage_interaction]\fP.
.RE
.sp
-\fBrun_second_cpp\fP (\fBCCACHE_CPP2\fP or \fBCCACHE_NOCPP2\fP, see \fI[_boolean_values]\fP above)
-.RS 4
-If true, ccache will first run the preprocessor to preprocess the source
-code (see \fI[_the_preprocessor_mode]\fP) and then on a cache miss run the
-compiler on the source code to get hold of the object file. This is the
-default.
-.sp
-If false, ccache will first run preprocessor to preprocess the source code and
-then on a cache miss run the compiler on the \fIpreprocessed source code\fP instead
-of the original source code. This makes cache misses slightly faster since the
-source code only has to be preprocessed once. The downside is that some
-compilers won\(cqt produce the same result (for instance diagnostics warnings)
-when compiling preprocessed source code.
-.sp
-A solution to the above mentioned downside is to set \fBrun_second_cpp\fP to false
-and pass \fB\-fdirectives\-only\fP (for GCC) or \fB\-frewrite\-includes\fP (for Clang) to
-the compiler. This will cause the compiler to leave the macros and other
-preprocessor information, and only process the \fB#include\fP directives. When run
-in this way, the preprocessor arguments will be passed to the compiler since it
-still has to do \fIsome\fP preprocessing (like macros).
-.RE
-.sp
-\fBsecondary_storage\fP (\fBCCACHE_SECONDARY_STORAGE\fP)
+\fBremote_storage\fP (\fBCCACHE_REMOTE_STORAGE\fP)
.RS 4
This option specifies one or several storage backends (separated by space)
-to query after the primary cache storage. See
-\fI[_secondary_storage_backends]\fP for documentation of syntax and available
-backends.
+to query after checking the local cache (unless
+\fBremote_only\fP is true). See \fI[Remote storage
+backends]\fP for documentation of syntax and available backends.
.sp
Examples:
.sp
@@ -1234,8 +1375,54 @@ Examples:
. 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 \fI[_boolean_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 \fI[_boolean_values]\fP above)
+.RS 4
+If true, ccache will first run the preprocessor to preprocess the source
+code (see \fI[_the_preprocessor_mode]\fP) and then on a cache miss run the
+compiler on the source code to get hold of the object file. This is the
+default.
+.sp
+If false, ccache will first run preprocessor to preprocess the source code and
+then on a cache miss run the compiler on the \fIpreprocessed source code\fP instead
+of the original source code. This makes cache misses slightly faster since the
+source code only has to be preprocessed once. The downside is that some
+compilers won\(cqt produce the same result (for instance diagnostics warnings)
+when compiling preprocessed source code.
+.sp
+A solution to the above mentioned downside is to set \fBrun_second_cpp\fP to false
+and pass \fB\-fdirectives\-only\fP (for GCC) or \fB\-frewrite\-includes\fP (for Clang) to
+the compiler. This will cause the compiler to leave the macros and other
+preprocessor information, and only process the \fB#include\fP directives. When run
+in this way, the preprocessor arguments will be passed to the compiler since it
+still has to do \fIsome\fP preprocessing (like macros).
+.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
@@ -1268,18 +1455,30 @@ 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 not cache a file if it includes a header whose ctime
-is too new. This sloppiness disables that check. See also
-\fI[_handling_of_newly_created_header_files]\fP.
+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 not cache a file if it includes a header whose mtime
-is too new. This sloppiness disables that check. See also
-\fI[_handling_of_newly_created_header_files]\fP.
+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
@@ -1297,18 +1496,25 @@ 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
+\fI[_c_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
\fI[_precompiled_headers]\fP for more information.
.RE
.sp
-\fBmodules\fP
+\fBrandom_seed\fP
.RS 4
-By default, ccache will not cache compilations if \fB\-fmodules\fP is used since
-it cannot hash the state of compiler\(cqs internal representation of relevant
-modules. This sloppiness allows caching in such a case. See
-\fI[_c_modules]\fP for more information.
+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
@@ -1357,7 +1563,8 @@ Lines in the stats log starting with a hash sign (\fB#\fP) are comments.
\fBtemporary_dir\fP (\fBCCACHE_TEMPDIR\fP)
.RS 4
This option specifies where ccache will put temporary files. The default is
-\fB/run/user/<UID>/ccache\-tmp\fP if \fB/run/user/<UID>\fP exists, otherwise
+\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
@@ -1382,23 +1589,25 @@ This option (an octal integer) specifies the umask for files and directories
in the cache directory. This is mostly useful when you wish to share your
cache with other users.
.RE
-.SH "SECONDARY STORAGE BACKENDS"
+.SH "REMOTE STORAGE BACKENDS"
.sp
-The \fBsecondary_storage\fP option lets you configure
-ccache to use one or several other storage backends in addition to the primary
-cache storage located in \fBcache_dir\fP. Note that cache
-statistics counters will still be kept in the primary cache directory \(em secondary storage backends only store cache results and manifests.
+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 secondary storage backend is specified with a URL, optionally followed by a
-pipe (\fB|\fP) and a pipe\-separated list of attributes. An attribute is
-\fIkey\fP=\fIvalue\fP or just \fIkey\fP as a short form of \fIkey\fP=\fBtrue\fP. Attribute values
-must be \c
+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.
+if they contain
+percent, pipe or space characters.
.SS "Attributes for all backends"
.sp
-These optional attributes are available for all secondary storage backends:
+These optional attributes are available for all remote storage backends:
.sp
.RS 4
.ie n \{\
@@ -1460,31 +1669,20 @@ of the cache on \fBredis://cache\-a.example.com\fP, 18% (1/5.5) on
\fBhttp://example.com/alpha\fP and 50% on \fBhttp://example.com/beta\fP.
.RE
.RE
-.sp
-.RS 4
-.ie n \{\
-\h'-04'\(bu\h'+03'\c
-.\}
-.el \{\
-. sp -1
-. IP \(bu 2.3
-.\}
-\fBshare\-hits\fP: If \fBtrue\fP, write hits for this backend to primary storage. The
-default is \fBtrue\fP.
-.RE
.SS "Storage interaction"
.sp
-The table below describes the interaction between primary and secondary storage
-on cache hits and misses:
+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
-\fBPrimary storage\fP
+\fBLocal storage\fP
T}:T{
.sp
-\fBSecondary storage\fP
+\fBRemote storage\fP
T}:T{
.sp
\fBWhat happens\fP
@@ -1497,7 +1695,7 @@ T}:T{
miss
T}:T{
.sp
-Compile, write to primary, write to secondary[1]
+Compile, write to local, write to remote[1]
T}
T{
.sp
@@ -1507,7 +1705,7 @@ T}:T{
hit
T}:T{
.sp
-Read from secondary, write to primary[2]
+Read from remote, write to local
T}
T{
.sp
@@ -1517,25 +1715,62 @@ T}:T{
\-
T}:T{
.sp
-Read from primary, don\(cqt write to secondary[3]
+Read from local, don\(cqt write to remote[2]
T}
.TE
.sp
.sp
-[1] Unless secondary storage has attribute \fBread\-only=true\fP.
+[1] Unless remote storage has attribute \fBread\-only=true\fP.
.br
-[2] Unless secondary storage has attribute \fBshare\-hits=false\fP.
-.br
-[3] Unless primary storage is set to share its cache hits with the
+[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://DIRECTORY\fP
+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 (an absolute path), similar (but not identical) to the primary cache
-storage. A typical use case for this backend would be sharing a cache on an NFS
-directory.
+\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
@@ -1576,6 +1811,17 @@ Examples:
\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
@@ -1733,6 +1979,17 @@ Optional attributes:
. 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
@@ -1745,25 +2002,7 @@ Optional attributes:
. IP \(bu 2.3
.\}
\fBkeep\-alive\fP: If \fBtrue\fP, keep the HTTP connection to the storage server open
-to avoid reconnects. The default is \fBfalse\fP.
-.if n .sp
-.RS 4
-.it 1 an-trap
-.nr an-no-space-flag 1
-.nr an-break-flag 1
-.br
-.ps +1
-.B Note
-.ps -1
-.br
-.sp
-Connection keep\-alive is disabled by default because with the current
-HTTP implementation uploads to the remote end might fail in case the server
-closes the connection due to a keep\-alive timeout. If the general case with
-short compilation times should be accelerated or the server is configured with
-a long\-enough timeout, then connection keep\-alive could be enabled.
-.sp .5v
-.RE
+to avoid reconnects. The default is \fBtrue\fP.
.RE
.sp
.RS 4
@@ -1845,7 +2084,13 @@ The default is \fBsubdirs\fP.
.RE
.SS "Redis storage backend"
.sp
-URL format: \fBredis://[[USERNAME:]PASSWORD@]HOST[:PORT][/DBNUMBER]\fP
+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" ""
@@ -1895,7 +2140,7 @@ storage" for hints on setting up a Redis server for use with ccache.
.br
.sp
You can set up a cluster of Redis servers using the \fBshards\fP attribute
-described in \fI[_secondary_storage_backends]\fP.
+described in \fI[_remote_storage_backends]\fP.
.sp .5v
.RE
.sp
@@ -1923,6 +2168,39 @@ Examples:
\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
@@ -2011,6 +2289,10 @@ Set the size and file number counters to match the files that were kept.
The reason for removing more files than just those needed to not exceed the max
limits is that a cleanup is a fairly slow operation, so it would not be a good
idea to trigger it often, like after each cache miss.
+.sp
+The LRU cleanup makes use of the file modification time (mtime) of cache
+entries; ccache updates mtime of the cache entries 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, i.e. all
@@ -2113,7 +2395,7 @@ recompressed.
cleanups (number of performed cleanups, either implicitly due to a cache size
limit being reached or due to explicit \fBccache \-c\fP calls), overall hit rate, hit
rate for direct/preprocessed modes
-and hit rate for primary and secondary storage.
+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
@@ -2180,8 +2462,7 @@ T{
Could not write to output file
T}:T{
.sp
-The output path specified with \fB\-o\fP is not a file (e.g. a directory or a device
-node).
+The output path specified with \fB\-o\fP could not be written to.
T}
T{
.sp
@@ -2200,30 +2481,22 @@ A compiler check program specified by
T}
T{
.sp
-Compiler produced empty output
+Compiler output file missing
T}:T{
.sp
-The compiler\(cqs output file (typically an object file) was empty after
+One of the files expected to be produced by the compiler was missing after
compilation.
T}
T{
.sp
-Compiler produced no output
+Compiler produced empty output
T}:T{
.sp
-The compiler\(cqs output file (typically an object file) was missing after
+The compiler\(cqs output file (typically an object file) was empty after
compilation.
T}
T{
.sp
-Compiler produced stdout
-T}:T{
-.sp
-The compiler wrote data to standard output. This is something that compilers
-normally never do, so ccache is not designed to store such output in the cache.
-T}
-T{
-.sp
Could not find the compiler
T}:T{
.sp
@@ -2307,6 +2580,13 @@ 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
@@ -2616,7 +2896,8 @@ the string \fB__TIME__\fP is present in the source code
If the depend mode is enabled, ccache will not use the preprocessor at all. The
hash used to identify results in the cache will be based on the direct mode
hash described above plus information about include files read from the
-dependency file generated by the compiler with \fB\-MD\fP or \fB\-MMD\fP.
+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
@@ -2669,8 +2950,8 @@ to some types of changes of compiler options and source code changes.
. IP \(bu 2.3
.\}
If \-MD is used, the manifest entries will include system header files as
-well, thus slowing down cache hits slightly, just as using \-MD slows down
-make.
+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
@@ -2681,7 +2962,7 @@ make.
. sp -1
. IP \(bu 2.3
.\}
-If \-MMD is used, the manifest entries will not include system header files,
+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
@@ -2717,13 +2998,14 @@ The depend mode will be disabled if any of the following holds:
. sp -1
. IP \(bu 2.3
.\}
-The compiler is not generating dependencies using \fB\-MD\fP or \fB\-MMD\fP.
+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 the same second as the time compilation is being done, ccache disables
-the direct mode (or, in the case of a precompiled
+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
@@ -2833,35 +3115,35 @@ T}:T{
T}
T{
.sp
-\fB<objectfile>.ccache\-input\-c\fP
+\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>.ccache\-input\-d\fP
+\fB<objectfile>.<timestamp>.ccache\-input\-d\fP
T}:T{
.sp
Binary input only hashed by the direct mode.
T}
T{
.sp
-\fB<objectfile>.ccache\-input\-p\fP
+\fB<objectfile>.<timestamp>.ccache\-input\-p\fP
T}:T{
.sp
Binary input only hashed by the preprocessor mode.
T}
T{
.sp
-\fB<objectfile>.ccache\-input\-text\fP
+\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>.ccache\-log\fP
+\fB<objectfile>.<timestamp>.ccache\-log\fP
T}:T{
.sp
Log for this object file.
@@ -2869,7 +3151,16 @@ T}
.TE
.sp
.sp
-If \fBconfig_dir\fP (environment variable \fBCCACHE_DEBUGDIR\fP) is
+.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
@@ -2894,7 +3185,7 @@ something like this:
. sp -1
. IP " 1." 4.2
.\}
-Build with debug mode enabled.
+Enable \fBdebug\fP (\fBCCACHE_DEBUG\fP).
.RE
.sp
.RS 4
@@ -2905,7 +3196,7 @@ Build with debug mode enabled.
. sp -1
. IP " 2." 4.2
.\}
-Save the \fB<objectfile>.ccache\-*\fP files.
+Build.
.RE
.sp
.RS 4
@@ -2916,7 +3207,7 @@ Save the \fB<objectfile>.ccache\-*\fP files.
. sp -1
. IP " 3." 4.2
.\}
-Build again with debug mode enabled.
+Clean and build again.
.RE
.sp
.RS 4
@@ -2927,9 +3218,9 @@ Build again with debug mode enabled.
. sp -1
. IP " 4." 4.2
.\}
-Compare \fB<objectfile>.ccache\-input\-text\fP for the two builds. This together
-with the \fB<objectfile>.ccache\-log\fP files should give you some clues about
-what is happening.
+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
@@ -3033,8 +3324,8 @@ relative before computing the hash.
.RE
.SH "PRECOMPILED HEADERS"
.sp
-Ccache has support for GCC\(cqs precompiled headers. However, you have to do some
-things to make it work properly:
+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 \{\
@@ -3111,12 +3402,23 @@ the PCH file generated from the precompiled header; or
(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).
-.RE
.SH "C++ MODULES"
.sp
Ccache has support for Clang\(cqs \fB\-fmodules\fP option. In practice ccache only
@@ -3130,10 +3432,10 @@ You must use both \fBdirect mode\fP and
\fBdepend mode\fP. When using
the preprocessor mode Clang does not provide enough
information to allow hashing of \fBmodule.modulemap\fP files.
-.SH "SHARING A CACHE"
+.SH "SHARING A LOCAL CACHE"
.sp
-A group of developers can increase the cache hit rate by sharing a cache
-directory. To share a cache without unpleasant side effects, the following
+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
@@ -3263,7 +3565,7 @@ systems. One way of improving cache hit rate in that case is to set
headers.
.sp
An alternative to putting the main cache directory on NFS is to set up a
-secondary storage file cache.
+remote storage file cache.
.SH "USING CCACHE WITH OTHER COMPILER WRAPPERS"
.sp
The recommended way of combining ccache with another compiler wrapper (such as
diff --git a/srcpkgs/ccache/template b/srcpkgs/ccache/template
index 5c1dc8914258..4e15bf4207bb 100644
--- a/srcpkgs/ccache/template
+++ b/srcpkgs/ccache/template
@@ -1,18 +1,17 @@
# Template file for 'ccache'
pkgname=ccache
-version=4.6.3
+version=4.7.4
revision=1
build_style=cmake
configure_args="-DENABLE_TESTING=OFF -DREDIS_STORAGE_BACKEND=OFF"
-hostmakedepends="perl"
-makedepends="libzstd-devel zlib-devel"
+makedepends="libzstd-devel"
short_desc="Fast C/C++ Compiler Cache"
maintainer="Enno Boland <gottox@voidlinux.org>"
license="GPL-3.0-or-later"
-homepage="https://ccache.samba.org/"
+homepage="https://ccache.dev"
changelog="https://ccache.dev/releasenotes.html"
-distfiles="https://github.com/ccache/ccache/releases/download/v${version}/${pkgname}-${version}.tar.xz"
-checksum=1e3a251bb112632553b8255a78661fe526c3a16598496d51128c32b218fd8b22
+distfiles="https://github.com/ccache/ccache/releases/download/v${version}/ccache-${version}.tar.xz"
+checksum=df0c64d15d3efaf0b4f6837dd6b1467e40eeaaa807db25ce79c3a08a46a84e36
if [ -n "$XBPS_CHECK_PKGS" ]; then
configure_args+=" -DENABLE_TESTING=ON"
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: [PR PATCH] [Updated] ccache: update to 4.7.4.
2022-12-18 17:10 [PR PATCH] ccache: update to 4.7.4 r-ricci
` (3 preceding siblings ...)
2022-12-22 22:07 ` r-ricci
@ 2022-12-27 16:37 ` r-ricci
2022-12-27 17:45 ` [PR PATCH] [Merged]: " paper42
5 siblings, 0 replies; 7+ messages in thread
From: r-ricci @ 2022-12-27 16:37 UTC (permalink / raw)
To: ml
[-- Attachment #1: Type: text/plain, Size: 1448 bytes --]
There is an updated pull request by r-ricci against master on the void-packages repository
https://github.com/r-ricci/void-packages ccache
https://github.com/void-linux/void-packages/pull/41168
ccache: update to 4.7.4.
<!-- Uncomment relevant sections and delete options which are not applicable -->
It doesn't link to zlib since [version 4.0](https://ccache.dev/releasenotes.html#_ccache_4_0).
I don't know why perl was in hostmakedepends but the build log is identical with and without it.
@Gottox
#### Testing the changes
- I tested the changes in this PR: **YES**
<!--
#### New package
- This new package conforms to the [package requirements](https://github.com/void-linux/void-packages/blob/master/CONTRIBUTING.md#package-requirements): **YES**|**NO**
-->
<!-- Note: If the build is likely to take more than 2 hours, please add ci skip tag as described in
https://github.com/void-linux/void-packages/blob/master/CONTRIBUTING.md#continuous-integration
and test at least one native build and, if supported, at least one cross build.
Ignore this section if this PR is not skipping CI.
-->
<!--
#### Local build testing
- I built this PR locally for my native architecture, (ARCH-LIBC)
- I built this PR locally for these architectures (if supported. mark crossbuilds):
- aarch64-musl
- armv7l
- armv6l-musl
-->
A patch file from https://github.com/void-linux/void-packages/pull/41168.patch is attached
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: github-pr-ccache-41168.patch --]
[-- Type: text/x-diff, Size: 45688 bytes --]
From 9d227349d2f80e5526315df19e0b973a114a68e0 Mon Sep 17 00:00:00 2001
From: Roberto Ricci <ricci@disroot.org>
Date: Sat, 17 Dec 2022 23:34:19 +0100
Subject: [PATCH] ccache: update to 4.7.4.
---
srcpkgs/ccache/files/ccache.1 | 796 +++++++++++++++++++++++-----------
srcpkgs/ccache/template | 11 +-
2 files changed, 554 insertions(+), 253 deletions(-)
diff --git a/srcpkgs/ccache/files/ccache.1 b/srcpkgs/ccache/files/ccache.1
index 0fe62140c43f..366e4a2b68e2 100644
--- a/srcpkgs/ccache/files/ccache.1
+++ b/srcpkgs/ccache/files/ccache.1
@@ -2,12 +2,12 @@
.\" Title: ccache
.\" Author: [see the "AUTHOR(S)" section]
.\" Generator: Asciidoctor 2.0.15
-.\" Date: 2022-01-05
+.\" Date: 2022-12-18
.\" Manual: \ \&
-.\" Source: Ccache 4.5.1
+.\" Source: Ccache 4.7.4
.\" Language: English
.\"
-.TH "CCACHE" "1" "2022-01-05" "Ccache 4.5.1" "\ \&"
+.TH "CCACHE" "1" "2022-12-18" "Ccache 4.7.4" "\ \&"
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.ss \n[.ss] 0
@@ -34,7 +34,7 @@ ccache \- a fast C/C++ compiler cache
.nf
\fBccache\fP [\fIoptions\fP]
\fBccache\fP \fIcompiler\fP [\fIcompiler options\fP]
-\fIcompiler\fP [\fIcompiler options\fP] (via symbolic link)
+\fIcompiler\fP [\fIcompiler options\fP] (ccache masquerading as the compiler)
.fi
.br
.SH "DESCRIPTION"
@@ -50,16 +50,41 @@ goal are listed under \fICaveats\fP. If you discover an undocumented case where
ccache changes the output of your compiler, please let us know.
.SH "RUN MODES"
.sp
-There are two ways to use ccache. You can either prefix your compilation
-commands with \fBccache\fP or you can let ccache masquerade as the compiler by
-creating a symbolic link (named as the compiler) to ccache. The first method is
-most convenient if you just want to try out ccache or wish to use it for some
-specific projects. The second method is most useful for when you wish to use
-ccache for all your compilations.
+There are two different ways to use ccache to cache a compilation:
.sp
-To use the first method, just make sure that \fBccache\fP is in your \fBPATH\fP.
+.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
-To use the symlinks method, do something like this:
+.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
@@ -67,16 +92,25 @@ To use the symlinks method, do something like this:
cp ccache /usr/local/bin/
ln \-s ccache /usr/local/bin/gcc
ln \-s ccache /usr/local/bin/g++
-ln \-s ccache /usr/local/bin/cc
-ln \-s ccache /usr/local/bin/c++
.fam
.fi
.if n .RE
.sp
-And so forth. This will work as long as the directory with symlinks comes
-before the path to the compiler (which is usually in \fB/usr/bin\fP). After
-installing you may wish to run \(lqwhich gcc\(rq to make sure that the correct link
-is being used.
+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
@@ -93,26 +127,13 @@ but currently doesn\(cqt interact well with other tools that do the same thing.
\fI[_using_ccache_with_other_compiler_wrappers]\fP.
.sp .5v
.RE
-.if n .sp
-.RS 4
-.it 1 an-trap
-.nr an-no-space-flag 1
-.nr an-break-flag 1
-.br
-.ps +1
-.B Warning
-.ps -1
-.br
-.sp
-Use a symbolic links for masquerading, not hard links.
-.sp .5v
.RE
.SH "COMMAND LINE OPTIONS"
.sp
-These command line options only apply when you invoke ccache as \(lqccache\(rq.
-When invoked as a compiler (via a symlink as described in the previous
-section), the normal compiler options apply and you should refer to the
-compiler\(cqs documentation.
+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
@@ -135,8 +156,8 @@ configuration file.
\fB\-\-config\-path\fP \fIPATH\fP
.RS 4
Let the command line options operate on configuration file \fIPATH\fP instead of
-the default. Using this option has the same effect as setting the
-environment variable \fBCCACHE_CONFIGPATH\fP temporarily.
+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
@@ -186,7 +207,7 @@ future compilations.
.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
+\fBcompression_level\fP configuration option, or
the special value \fBuncompressed\fP for no compression. See
\fI[_cache_compression]\fP for more information. This can potentionally take a
long time since all files in the cache need to be visited. Only files that
@@ -241,12 +262,12 @@ Print version and copyright information.
.RS 4
Zero the cache statistics (but not the configuration options).
.RE
-.SS "Options for secondary storage"
+.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.
+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
@@ -258,17 +279,17 @@ by \fB\-\-trim\-max\-size\fP.
.ps -1
.br
.sp
-Don\(cqt use this option to trim the primary cache. To trim the primary
-cache directory to a certain size, use \fBCCACHE_MAXSIZE=\fISIZE\fP ccache \-c\fP.
+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: k, M, G, T (decimal), Ki, Mi, Gi or Ti (binary). The
-default suffix is G.
+Specify the maximum size for \fB\-\-trim\-dir\fP. \fISIZE\fP should be a number
+followed by an optional suffix: k, M, G, T (decimal), Ki, Mi, Gi or Ti
+(binary). The default suffix is G.
.RE
.sp
\fB\-\-trim\-method\fP \fIMETHOD\fP
@@ -295,23 +316,11 @@ Print the checksum (128 bit XXH3) of the file at \fIPATH\fP (\fB\-\fP for standa
input).
.RE
.sp
-\fB\-\-dump\-manifest\fP \fIPATH\fP
-.RS 4
-Dump manifest file at \fIPATH\fP (\fB\-\fP for standard input) in text format to
-standard output. This is only useful when debugging ccache and its behavior.
-.RE
-.sp
-\fB\-\-dump\-result\fP \fIPATH\fP
-.RS 4
-Dump result file at \fIPATH\fP (\fB\-\fP for standard input) in text format to
-standard output. This is only useful when debugging ccache and its behavior.
-.RE
-.sp
\fB\-\-extract\-result\fP \fIPATH\fP
.RS 4
Extract data stored in the result file at \fIPATH\fP (\fB\-\fP for standard input).
The data will be written to \fBccache\-result.*\fP files in to the current
-working directory. This is only useful when debugging ccache and its
+working directory. This option is only useful when debugging ccache and its
behavior.
.RE
.sp
@@ -327,6 +336,15 @@ 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
@@ -394,7 +412,7 @@ Environment variables.
. sp -1
. IP " 2." 4.2
.\}
-The primary (cache\-specific) configuration file (see below).
+The cache\-specific configuration file (see below).
.RE
.sp
.RS 4
@@ -405,9 +423,8 @@ The primary (cache\-specific) configuration file (see below).
. sp -1
. IP " 3." 4.2
.\}
-The secondary (system\-wide read\-only) configuration file
-\fB<sysconfdir>/ccache.conf\fP (typically \fB/etc/ccache.conf\fP or
-\fB/usr/local/etc/ccache.conf\fP).
+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
@@ -421,13 +438,13 @@ The secondary (system\-wide read\-only) configuration file
Compile\-time defaults.
.RE
.sp
-As a special case, if the the environment variable \fBCCACHE_CONFIGPATH\fP is set
-it specifies the primary configuration file and the secondary (system\-wide)
-configuration file won\(cqt be read.
-.SS "Location of the primary configuration file"
+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 primary (cache\-specific) configuration is determined like
-this:
+The location of the cache\-specific configuration file is determined like this on
+non\-Windows systems:
.sp
.RS 4
.ie n \{\
@@ -460,8 +477,8 @@ Otherwise, if the environment variable \fBCCACHE_DIR\fP is set then use
. sp -1
. IP " 3." 4.2
.\}
-Otherwise, if \fBcache_dir\fP is set in the secondary
-(system\-wide) configuration file then use \fB<cache_dir>/ccache.conf\fP.
+Otherwise, if \fBcache_dir\fP is set in the system
+configuration file then use \fB<cache_dir>/ccache.conf\fP.
.RE
.sp
.RS 4
@@ -496,10 +513,87 @@ Otherwise, if \fBXDG_CONFIG_HOME\fP is set then use
. sp -1
. IP " 6." 4.2
.\}
-Otherwise, use \fB%APPDATA%/ccache/ccache.conf\fP (Windows),
+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
@@ -639,19 +733,56 @@ 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.
-The default is \fB$XDG_CACHE_HOME/ccache\fP if \fBXDG_CACHE_HOME\fP is set,
-otherwise \fB$HOME/.cache/ccache\fP. Exception: If the legacy directory
-\fB$HOME/.ccache\fP exists then that directory is the default.
.sp
-See also \fI[_location_of_the_primary_configuration_file]\fP.
+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
-If you want to use another \fBCCACHE_DIR\fP value temporarily for one ccache
-invocation you can use the \fB\-d\fP/\fB\-\-dir\fP command line option instead.
+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 \fI[_location_of_the_configuration_file]\fP.
.RE
.sp
\fBcompiler\fP (\fBCCACHE_COMPILER\fP or (deprecated) \fBCCACHE_CC\fP)
@@ -665,8 +796,9 @@ command line.
.RS 4
By default, ccache includes the modification time (\(lqmtime\(rq) and size of
the compiler in the hash to ensure that results retrieved from the cache
-are accurate. This option can be used to select another strategy. Possible
-values are:
+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
@@ -756,11 +888,26 @@ symlinks). This is the default.
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.
@@ -770,11 +917,6 @@ NVCC (CUDA) compiler.
.RS 4
Any compiler other than the known types.
.RE
-.sp
-\fBpump\fP
-.RS 4
-distcc\(cqs \(lqpump\(rq script.
-.RE
.RE
.sp
\fBcompression\fP (\fBCCACHE_COMPRESS\fP or \fBCCACHE_NOCOMPRESS\fP, see \fI[_boolean_values]\fP above)
@@ -944,11 +1086,11 @@ Do not enable this option unless you are aware of these caveats:
If the resulting file is modified, the file in the cache will also be
modified since they share content, which corrupts the cache entry. As of
version 4.0, ccache makes stored and fetched object files read\-only as a
-safety measure guard. Furthermore, a simple integrity check is made for
-cached object files by verifying that their sizes are correct. This means
-that mistakes like \fBstrip file.o\fP or \fBecho >file.o\fP will be detected even if
-the object file is made writeable, but a modification that doesn\(cqt change the
-file size will not.
+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 writeable, but a modification that doesn\(cqt change the file
+size will not.
.RE
.sp
.RS 4
@@ -1024,20 +1166,32 @@ example, \fB\-fmessage\-length=*\fP will match both \fB\-fmessage\-length=20\fP
.sp
\fBinode_cache\fP (\fBCCACHE_INODECACHE\fP or \fBCCACHE_NOINODECACHE\fP, see \fI[_boolean_values]\fP above)
.RS 4
-If true, enables caching of source file hashes based on device, inode and
-timestamps. This will reduce the time spent on hashing included files as
-the result can be resused between compilations.
-.sp
-The feature is still experimental and thus off by default. It is currently not
-available on Windows.
+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 resused 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 feature requires \fBtemporary_dir\fP to be located on a local filesystem.
+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 \fI[_boolean_values]\fP above)
.RS 4
If true, ccache will not discard the comments before hashing preprocessor
-output. This can be used to check documentation with \fB\-Wdocumentation\fP.
+output. The default is false. This can be used to check documentation with
+\fB\-Wdocumentation\fP.
.RE
.sp
\fBlimit_multiple\fP (\fBCCACHE_LIMIT_MULTIPLE\fP)
@@ -1082,18 +1236,25 @@ Gi, Ti (binary). The default suffix is G. See also
\fI[_cache_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
+If set, the namespace string will be added to the hashed data for each
compilation. This will make the associated cache entries logically separate
from cache entries with other namespaces, but they will still share the same
-storage space. Cache entries can also be selectively removed from the
-primary cache with the command line option \fB\-\-evict\-namespace\fP, potentially
-in combination with \fB\-\-evict\-older\-than\fP.
-\&.
-For instance, if you use the same primary cache for several disparate projects,
+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 stop working with that
+cache entries that belong to a certain project if you stop working with that
project.
.RE
.sp
@@ -1155,40 +1316,20 @@ If true, ccache will not use any previously stored result. New results will
still be cached, possibly overwriting any pre\-existing results.
.RE
.sp
-\fBreshare\fP (\fBCCACHE_RESHARE\fP or \fBCCACHE_NORESHARE\fP, see \fI[_boolean_values]\fP above)
+\fBremote_only\fP (\fBCCACHE_REMOTE_ONLY\fP or \fBCCACHE_NOREMOTE_ONLY\fP, see \fI[_boolean_values]\fP above)
.RS 4
-If true, ccache will write results to secondary storage even for primary
-storage cache hits. The default is false.
+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
+\fI[_storage_interaction]\fP.
.RE
.sp
-\fBrun_second_cpp\fP (\fBCCACHE_CPP2\fP or \fBCCACHE_NOCPP2\fP, see \fI[_boolean_values]\fP above)
-.RS 4
-If true, ccache will first run the preprocessor to preprocess the source
-code (see \fI[_the_preprocessor_mode]\fP) and then on a cache miss run the
-compiler on the source code to get hold of the object file. This is the
-default.
-.sp
-If false, ccache will first run preprocessor to preprocess the source code and
-then on a cache miss run the compiler on the \fIpreprocessed source code\fP instead
-of the original source code. This makes cache misses slightly faster since the
-source code only has to be preprocessed once. The downside is that some
-compilers won\(cqt produce the same result (for instance diagnostics warnings)
-when compiling preprocessed source code.
-.sp
-A solution to the above mentioned downside is to set \fBrun_second_cpp\fP to false
-and pass \fB\-fdirectives\-only\fP (for GCC) or \fB\-frewrite\-includes\fP (for Clang) to
-the compiler. This will cause the compiler to leave the macros and other
-preprocessor information, and only process the \fB#include\fP directives. When run
-in this way, the preprocessor arguments will be passed to the compiler since it
-still has to do \fIsome\fP preprocessing (like macros).
-.RE
-.sp
-\fBsecondary_storage\fP (\fBCCACHE_SECONDARY_STORAGE\fP)
+\fBremote_storage\fP (\fBCCACHE_REMOTE_STORAGE\fP)
.RS 4
This option specifies one or several storage backends (separated by space)
-to query after the primary cache storage. See
-\fI[_secondary_storage_backends]\fP for documentation of syntax and available
-backends.
+to query after checking the local cache (unless
+\fBremote_only\fP is true). See \fI[Remote storage
+backends]\fP for documentation of syntax and available backends.
.sp
Examples:
.sp
@@ -1234,8 +1375,54 @@ Examples:
. 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 \fI[_boolean_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 \fI[_boolean_values]\fP above)
+.RS 4
+If true, ccache will first run the preprocessor to preprocess the source
+code (see \fI[_the_preprocessor_mode]\fP) and then on a cache miss run the
+compiler on the source code to get hold of the object file. This is the
+default.
+.sp
+If false, ccache will first run preprocessor to preprocess the source code and
+then on a cache miss run the compiler on the \fIpreprocessed source code\fP instead
+of the original source code. This makes cache misses slightly faster since the
+source code only has to be preprocessed once. The downside is that some
+compilers won\(cqt produce the same result (for instance diagnostics warnings)
+when compiling preprocessed source code.
+.sp
+A solution to the above mentioned downside is to set \fBrun_second_cpp\fP to false
+and pass \fB\-fdirectives\-only\fP (for GCC) or \fB\-frewrite\-includes\fP (for Clang) to
+the compiler. This will cause the compiler to leave the macros and other
+preprocessor information, and only process the \fB#include\fP directives. When run
+in this way, the preprocessor arguments will be passed to the compiler since it
+still has to do \fIsome\fP preprocessing (like macros).
+.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
@@ -1268,18 +1455,30 @@ 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 not cache a file if it includes a header whose ctime
-is too new. This sloppiness disables that check. See also
-\fI[_handling_of_newly_created_header_files]\fP.
+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 not cache a file if it includes a header whose mtime
-is too new. This sloppiness disables that check. See also
-\fI[_handling_of_newly_created_header_files]\fP.
+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
@@ -1297,18 +1496,25 @@ 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
+\fI[_c_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
\fI[_precompiled_headers]\fP for more information.
.RE
.sp
-\fBmodules\fP
+\fBrandom_seed\fP
.RS 4
-By default, ccache will not cache compilations if \fB\-fmodules\fP is used since
-it cannot hash the state of compiler\(cqs internal representation of relevant
-modules. This sloppiness allows caching in such a case. See
-\fI[_c_modules]\fP for more information.
+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
@@ -1357,7 +1563,8 @@ Lines in the stats log starting with a hash sign (\fB#\fP) are comments.
\fBtemporary_dir\fP (\fBCCACHE_TEMPDIR\fP)
.RS 4
This option specifies where ccache will put temporary files. The default is
-\fB/run/user/<UID>/ccache\-tmp\fP if \fB/run/user/<UID>\fP exists, otherwise
+\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
@@ -1382,23 +1589,25 @@ This option (an octal integer) specifies the umask for files and directories
in the cache directory. This is mostly useful when you wish to share your
cache with other users.
.RE
-.SH "SECONDARY STORAGE BACKENDS"
+.SH "REMOTE STORAGE BACKENDS"
.sp
-The \fBsecondary_storage\fP option lets you configure
-ccache to use one or several other storage backends in addition to the primary
-cache storage located in \fBcache_dir\fP. Note that cache
-statistics counters will still be kept in the primary cache directory \(em secondary storage backends only store cache results and manifests.
+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 secondary storage backend is specified with a URL, optionally followed by a
-pipe (\fB|\fP) and a pipe\-separated list of attributes. An attribute is
-\fIkey\fP=\fIvalue\fP or just \fIkey\fP as a short form of \fIkey\fP=\fBtrue\fP. Attribute values
-must be \c
+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.
+if they contain
+percent, pipe or space characters.
.SS "Attributes for all backends"
.sp
-These optional attributes are available for all secondary storage backends:
+These optional attributes are available for all remote storage backends:
.sp
.RS 4
.ie n \{\
@@ -1460,31 +1669,20 @@ of the cache on \fBredis://cache\-a.example.com\fP, 18% (1/5.5) on
\fBhttp://example.com/alpha\fP and 50% on \fBhttp://example.com/beta\fP.
.RE
.RE
-.sp
-.RS 4
-.ie n \{\
-\h'-04'\(bu\h'+03'\c
-.\}
-.el \{\
-. sp -1
-. IP \(bu 2.3
-.\}
-\fBshare\-hits\fP: If \fBtrue\fP, write hits for this backend to primary storage. The
-default is \fBtrue\fP.
-.RE
.SS "Storage interaction"
.sp
-The table below describes the interaction between primary and secondary storage
-on cache hits and misses:
+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
-\fBPrimary storage\fP
+\fBLocal storage\fP
T}:T{
.sp
-\fBSecondary storage\fP
+\fBRemote storage\fP
T}:T{
.sp
\fBWhat happens\fP
@@ -1497,7 +1695,7 @@ T}:T{
miss
T}:T{
.sp
-Compile, write to primary, write to secondary[1]
+Compile, write to local, write to remote[1]
T}
T{
.sp
@@ -1507,7 +1705,7 @@ T}:T{
hit
T}:T{
.sp
-Read from secondary, write to primary[2]
+Read from remote, write to local
T}
T{
.sp
@@ -1517,25 +1715,62 @@ T}:T{
\-
T}:T{
.sp
-Read from primary, don\(cqt write to secondary[3]
+Read from local, don\(cqt write to remote[2]
T}
.TE
.sp
.sp
-[1] Unless secondary storage has attribute \fBread\-only=true\fP.
+[1] Unless remote storage has attribute \fBread\-only=true\fP.
.br
-[2] Unless secondary storage has attribute \fBshare\-hits=false\fP.
-.br
-[3] Unless primary storage is set to share its cache hits with the
+[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://DIRECTORY\fP
+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 (an absolute path), similar (but not identical) to the primary cache
-storage. A typical use case for this backend would be sharing a cache on an NFS
-directory.
+\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
@@ -1576,6 +1811,17 @@ Examples:
\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
@@ -1733,6 +1979,17 @@ Optional attributes:
. 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
@@ -1745,25 +2002,7 @@ Optional attributes:
. IP \(bu 2.3
.\}
\fBkeep\-alive\fP: If \fBtrue\fP, keep the HTTP connection to the storage server open
-to avoid reconnects. The default is \fBfalse\fP.
-.if n .sp
-.RS 4
-.it 1 an-trap
-.nr an-no-space-flag 1
-.nr an-break-flag 1
-.br
-.ps +1
-.B Note
-.ps -1
-.br
-.sp
-Connection keep\-alive is disabled by default because with the current
-HTTP implementation uploads to the remote end might fail in case the server
-closes the connection due to a keep\-alive timeout. If the general case with
-short compilation times should be accelerated or the server is configured with
-a long\-enough timeout, then connection keep\-alive could be enabled.
-.sp .5v
-.RE
+to avoid reconnects. The default is \fBtrue\fP.
.RE
.sp
.RS 4
@@ -1845,7 +2084,13 @@ The default is \fBsubdirs\fP.
.RE
.SS "Redis storage backend"
.sp
-URL format: \fBredis://[[USERNAME:]PASSWORD@]HOST[:PORT][/DBNUMBER]\fP
+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" ""
@@ -1895,7 +2140,7 @@ storage" for hints on setting up a Redis server for use with ccache.
.br
.sp
You can set up a cluster of Redis servers using the \fBshards\fP attribute
-described in \fI[_secondary_storage_backends]\fP.
+described in \fI[_remote_storage_backends]\fP.
.sp .5v
.RE
.sp
@@ -1923,6 +2168,39 @@ Examples:
\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
@@ -2011,6 +2289,10 @@ Set the size and file number counters to match the files that were kept.
The reason for removing more files than just those needed to not exceed the max
limits is that a cleanup is a fairly slow operation, so it would not be a good
idea to trigger it often, like after each cache miss.
+.sp
+The LRU cleanup makes use of the file modification time (mtime) of cache
+entries; ccache updates mtime of the cache entries 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, i.e. all
@@ -2113,7 +2395,7 @@ recompressed.
cleanups (number of performed cleanups, either implicitly due to a cache size
limit being reached or due to explicit \fBccache \-c\fP calls), overall hit rate, hit
rate for direct/preprocessed modes
-and hit rate for primary and secondary storage.
+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
@@ -2180,8 +2462,7 @@ T{
Could not write to output file
T}:T{
.sp
-The output path specified with \fB\-o\fP is not a file (e.g. a directory or a device
-node).
+The output path specified with \fB\-o\fP could not be written to.
T}
T{
.sp
@@ -2200,30 +2481,22 @@ A compiler check program specified by
T}
T{
.sp
-Compiler produced empty output
+Compiler output file missing
T}:T{
.sp
-The compiler\(cqs output file (typically an object file) was empty after
+One of the files expected to be produced by the compiler was missing after
compilation.
T}
T{
.sp
-Compiler produced no output
+Compiler produced empty output
T}:T{
.sp
-The compiler\(cqs output file (typically an object file) was missing after
+The compiler\(cqs output file (typically an object file) was empty after
compilation.
T}
T{
.sp
-Compiler produced stdout
-T}:T{
-.sp
-The compiler wrote data to standard output. This is something that compilers
-normally never do, so ccache is not designed to store such output in the cache.
-T}
-T{
-.sp
Could not find the compiler
T}:T{
.sp
@@ -2307,6 +2580,13 @@ 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
@@ -2616,7 +2896,8 @@ the string \fB__TIME__\fP is present in the source code
If the depend mode is enabled, ccache will not use the preprocessor at all. The
hash used to identify results in the cache will be based on the direct mode
hash described above plus information about include files read from the
-dependency file generated by the compiler with \fB\-MD\fP or \fB\-MMD\fP.
+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
@@ -2669,8 +2950,8 @@ to some types of changes of compiler options and source code changes.
. IP \(bu 2.3
.\}
If \-MD is used, the manifest entries will include system header files as
-well, thus slowing down cache hits slightly, just as using \-MD slows down
-make.
+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
@@ -2681,7 +2962,7 @@ make.
. sp -1
. IP \(bu 2.3
.\}
-If \-MMD is used, the manifest entries will not include system header files,
+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
@@ -2717,13 +2998,14 @@ The depend mode will be disabled if any of the following holds:
. sp -1
. IP \(bu 2.3
.\}
-The compiler is not generating dependencies using \fB\-MD\fP or \fB\-MMD\fP.
+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 the same second as the time compilation is being done, ccache disables
-the direct mode (or, in the case of a precompiled
+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
@@ -2833,35 +3115,35 @@ T}:T{
T}
T{
.sp
-\fB<objectfile>.ccache\-input\-c\fP
+\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>.ccache\-input\-d\fP
+\fB<objectfile>.<timestamp>.ccache\-input\-d\fP
T}:T{
.sp
Binary input only hashed by the direct mode.
T}
T{
.sp
-\fB<objectfile>.ccache\-input\-p\fP
+\fB<objectfile>.<timestamp>.ccache\-input\-p\fP
T}:T{
.sp
Binary input only hashed by the preprocessor mode.
T}
T{
.sp
-\fB<objectfile>.ccache\-input\-text\fP
+\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>.ccache\-log\fP
+\fB<objectfile>.<timestamp>.ccache\-log\fP
T}:T{
.sp
Log for this object file.
@@ -2869,7 +3151,16 @@ T}
.TE
.sp
.sp
-If \fBconfig_dir\fP (environment variable \fBCCACHE_DEBUGDIR\fP) is
+.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
@@ -2894,7 +3185,7 @@ something like this:
. sp -1
. IP " 1." 4.2
.\}
-Build with debug mode enabled.
+Enable \fBdebug\fP (\fBCCACHE_DEBUG\fP).
.RE
.sp
.RS 4
@@ -2905,7 +3196,7 @@ Build with debug mode enabled.
. sp -1
. IP " 2." 4.2
.\}
-Save the \fB<objectfile>.ccache\-*\fP files.
+Build.
.RE
.sp
.RS 4
@@ -2916,7 +3207,7 @@ Save the \fB<objectfile>.ccache\-*\fP files.
. sp -1
. IP " 3." 4.2
.\}
-Build again with debug mode enabled.
+Clean and build again.
.RE
.sp
.RS 4
@@ -2927,9 +3218,9 @@ Build again with debug mode enabled.
. sp -1
. IP " 4." 4.2
.\}
-Compare \fB<objectfile>.ccache\-input\-text\fP for the two builds. This together
-with the \fB<objectfile>.ccache\-log\fP files should give you some clues about
-what is happening.
+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
@@ -3033,8 +3324,8 @@ relative before computing the hash.
.RE
.SH "PRECOMPILED HEADERS"
.sp
-Ccache has support for GCC\(cqs precompiled headers. However, you have to do some
-things to make it work properly:
+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 \{\
@@ -3111,12 +3402,23 @@ the PCH file generated from the precompiled header; or
(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).
-.RE
.SH "C++ MODULES"
.sp
Ccache has support for Clang\(cqs \fB\-fmodules\fP option. In practice ccache only
@@ -3130,10 +3432,10 @@ You must use both \fBdirect mode\fP and
\fBdepend mode\fP. When using
the preprocessor mode Clang does not provide enough
information to allow hashing of \fBmodule.modulemap\fP files.
-.SH "SHARING A CACHE"
+.SH "SHARING A LOCAL CACHE"
.sp
-A group of developers can increase the cache hit rate by sharing a cache
-directory. To share a cache without unpleasant side effects, the following
+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
@@ -3263,7 +3565,7 @@ systems. One way of improving cache hit rate in that case is to set
headers.
.sp
An alternative to putting the main cache directory on NFS is to set up a
-secondary storage file cache.
+remote storage file cache.
.SH "USING CCACHE WITH OTHER COMPILER WRAPPERS"
.sp
The recommended way of combining ccache with another compiler wrapper (such as
diff --git a/srcpkgs/ccache/template b/srcpkgs/ccache/template
index 5c1dc8914258..4e15bf4207bb 100644
--- a/srcpkgs/ccache/template
+++ b/srcpkgs/ccache/template
@@ -1,18 +1,17 @@
# Template file for 'ccache'
pkgname=ccache
-version=4.6.3
+version=4.7.4
revision=1
build_style=cmake
configure_args="-DENABLE_TESTING=OFF -DREDIS_STORAGE_BACKEND=OFF"
-hostmakedepends="perl"
-makedepends="libzstd-devel zlib-devel"
+makedepends="libzstd-devel"
short_desc="Fast C/C++ Compiler Cache"
maintainer="Enno Boland <gottox@voidlinux.org>"
license="GPL-3.0-or-later"
-homepage="https://ccache.samba.org/"
+homepage="https://ccache.dev"
changelog="https://ccache.dev/releasenotes.html"
-distfiles="https://github.com/ccache/ccache/releases/download/v${version}/${pkgname}-${version}.tar.xz"
-checksum=1e3a251bb112632553b8255a78661fe526c3a16598496d51128c32b218fd8b22
+distfiles="https://github.com/ccache/ccache/releases/download/v${version}/ccache-${version}.tar.xz"
+checksum=df0c64d15d3efaf0b4f6837dd6b1467e40eeaaa807db25ce79c3a08a46a84e36
if [ -n "$XBPS_CHECK_PKGS" ]; then
configure_args+=" -DENABLE_TESTING=ON"
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: [PR PATCH] [Merged]: ccache: update to 4.7.4.
2022-12-18 17:10 [PR PATCH] ccache: update to 4.7.4 r-ricci
` (4 preceding siblings ...)
2022-12-27 16:37 ` r-ricci
@ 2022-12-27 17:45 ` paper42
5 siblings, 0 replies; 7+ messages in thread
From: paper42 @ 2022-12-27 17:45 UTC (permalink / raw)
To: ml
[-- Attachment #1: Type: text/plain, Size: 1293 bytes --]
There's a merged pull request on the void-packages repository
ccache: update to 4.7.4.
https://github.com/void-linux/void-packages/pull/41168
Description:
<!-- Uncomment relevant sections and delete options which are not applicable -->
It doesn't link to zlib since [version 4.0](https://ccache.dev/releasenotes.html#_ccache_4_0).
I don't know why perl was in hostmakedepends but the build log is identical with and without it.
@Gottox
#### Testing the changes
- I tested the changes in this PR: **YES**
<!--
#### New package
- This new package conforms to the [package requirements](https://github.com/void-linux/void-packages/blob/master/CONTRIBUTING.md#package-requirements): **YES**|**NO**
-->
<!-- Note: If the build is likely to take more than 2 hours, please add ci skip tag as described in
https://github.com/void-linux/void-packages/blob/master/CONTRIBUTING.md#continuous-integration
and test at least one native build and, if supported, at least one cross build.
Ignore this section if this PR is not skipping CI.
-->
<!--
#### Local build testing
- I built this PR locally for my native architecture, (ARCH-LIBC)
- I built this PR locally for these architectures (if supported. mark crossbuilds):
- aarch64-musl
- armv7l
- armv6l-musl
-->
^ permalink raw reply [flat|nested] 7+ messages in thread
end of thread, other threads:[~2022-12-27 17:45 UTC | newest]
Thread overview: 7+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2022-12-18 17:10 [PR PATCH] ccache: update to 4.7.4 r-ricci
2022-12-19 5:36 ` [PR REVIEW] " classabbyamp
2022-12-19 7:42 ` icp1994
2022-12-19 20:25 ` [PR PATCH] [Updated] " r-ricci
2022-12-22 22:07 ` r-ricci
2022-12-27 16:37 ` r-ricci
2022-12-27 17:45 ` [PR PATCH] [Merged]: " paper42
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).