.\" Title: ccache
.\" Author: [see the "Author" section]
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
-.\" Date: 02/17/2017
+.\" Date: 02/11/2018
.\" Manual: ccache Manual
-.\" Source: ccache 3.3.4
+.\" Source: ccache 3.3.6+95_g181effa
.\" Language: English
.\"
-.TH "CCACHE" "1" "02/17/2017" "ccache 3\&.3\&.4" "ccache Manual"
+.TH "CCACHE" "1" "02/11/2018" "ccache 3\&.3\&.6+95_g181effa" "ccache Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.sp -1
.IP \(bu 2.3
.\}
-Optionally uses hard links where possible to avoid copies\&.
-.RE
-.sp
-.RS 4
-.ie n \{\
-\h'-04'\(bu\h'+03'\c
-.\}
-.el \{\
-.sp -1
-.IP \(bu 2.3
-.\}
Optionally compresses files in the cache to reduce disk space\&.
.RE
.SS "Limitations"
.\}
.SS "Boolean values"
.sp
-Some settings are boolean values (i\&.e\&. truth values)\&. In a configuration file, such values must be set to the string \fBtrue\fR or \fBfalse\fR\&. For the corresponding environment variables, the semantics are a bit different: a set environment variable means \(lqtrue\(rq regardless of the value (even if set to the empty string), and an unset environment variable means \(lqfalse\(rq\&. Each boolean environment variable also has a negated form starting with \fBCCACHE_NO\fR\&. For example, \fBCCACHE_COMPRESS\fR can be set to force compression and \fBCCACHE_NOCOMPRESS\fR can be set to force no compression\&.
+Some settings are boolean values (i\&.e\&. truth values)\&. In a configuration file, such values must be set to the string \fBtrue\fR or \fBfalse\fR\&. For the corresponding environment variables, the semantics are a bit different: a set environment variable means \(lqtrue\(rq (even if set to the empty string), the following case\-insensitive negative values are considered an error (rather than surprising the user): \fB0\fR, \fBfalse\fR, \fBdisable\fR and \fBno\fR, and an unset environment variable means \(lqfalse\(rq\&. Each boolean environment variable also has a negated form starting with \fBCCACHE_NO\fR\&. For example, \fBCCACHE_COMPRESS\fR can be set to force compression and \fBCCACHE_NOCOMPRESS\fR can be set to force no compression\&.
.SS "Configuration settings"
.sp
Below is a list of available configuration settings\&. The corresponding environment variable name is indicated in parentheses after each configuration setting key\&.
.PP
\fBbase_dir\fR (\fBCCACHE_BASEDIR\fR)
.RS 4
-This setting should be an absolute path to a directory\&. ccache then rewrites absolute paths into relative paths before computing the hash that identifies the compilation, but only for paths under the specified directory\&. If set to the empty string (which is the default), no rewriting is done\&. See also the discussion under
-COMPILING IN DIFFERENT DIRECTORIES\&. If using GCC or newer versions of Clang, you might want to look into the
-\fB\-fdebug\-prefix\-map=old=new\fR
-option for relocating debug info to a common prefix (mapping prefix with old=new)\&.
+This setting should be an absolute path to a directory\&. ccache then rewrites absolute paths into relative paths before computing the hash that identifies the compilation, but only for paths under the specified directory\&. If set to the empty string (which is the default), no rewriting is done\&. A typical path to use as the base directory is your home directory or another directory that is a parent of your build directories\&. Don\(cqt use
+/
+as the base directory since that will make ccache also rewrite paths to system header files, which doesn\(cqt gain anything\&.
+.sp
+See also the discussion under
+COMPILING IN DIFFERENT DIRECTORIES\&.
.RE
.PP
\fBcache_dir\fR (\fBCCACHE_DIR\fR)
.PP
\fBhard_link\fR (\fBCCACHE_HARDLINK\fR or \fBCCACHE_NOHARDLINK\fR, see Boolean values above)
.RS 4
-If true, ccache will attempt to use hard links from the cache directory when creating the compiler output rather than using a file copy\&. Using hard links may be slightly faster in some situations, but can confuse programs like \(lqmake\(rq that rely on modification times\&. Another thing to keep in mind is that if the resulting object file is modified in any way, this corrupts the cached object file as well\&. Hard links are never made for compressed cache files\&. This means that you should not enable compression if you want to use hard links\&. The default is false\&.
+If true, ccache will attempt to use hard links from the cache directory when creating the compiler output rather than using a file copy\&. Hard links are never made for compressed cache files\&. This means that you should not enable compression if you want to use hard links\&. The default is false\&.
+.if n \{\
+.sp
+.\}
+.RS 4
+.it 1 an-trap
+.nr an-no-space-flag 1
+.nr an-break-flag 1
+.br
+.ps +1
+\fBWarning\fR
+.ps -1
+.br
+Do not enable this option unless you are aware of the consequences\&. Using hard links may be slightly faster in some situations, but there are several pitfalls since the resulting object file will share i\-node with the cached object file:
+.sp .5v
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04' 1.\h'+01'\c
+.\}
+.el \{\
+.sp -1
+.IP " 1." 4.2
+.\}
+If the resulting object file is modified in any way, the cached object file will be modified as well\&. For instance, if you run
+\fBstrip object\&.o\fR
+or
+\fBecho >object\&.o\fR, you will corrupt the cache\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04' 2.\h'+01'\c
+.\}
+.el \{\
+.sp -1
+.IP " 2." 4.2
+.\}
+Programs that rely on modification times (like \(lqmake\(rq) can be confused since ccache updates the cached files\*(Aq modification times as part of the automatic cache size management\&. This will affect object files in the build tree as well, which can retrigger the linking step even though nothing really has changed\&.
+.RE
.RE
.PP
\fBhash_dir\fR (\fBCCACHE_HASHDIR\fR or \fBCCACHE_NOHASHDIR\fR, see Boolean values above)
\fBbase_dir\fR
is set (and matches the CWD) and the compiler option
\fB\-fdebug\-prefix\-map\fR
-is used\&.
+is used\&. See also the discussion under
+COMPILING IN DIFFERENT DIRECTORIES\&.
.sp
The reason for including the CWD in the hash by default is to prevent a problem with the storage of the current working directory in the debug info of an object file, which can lead ccache to return a cached object file that has the working directory in the debug info set incorrectly\&.
.sp
.PP
\fBlimit_multiple\fR (\fBCCACHE_LIMIT_MULTIPLE\fR)
.RS 4
-Sets the limit when cleaning up\&. Files are deleted (in LRU order) until the levels are below the limit\&. The default is 0\&.8 (= 80%)\&.
+Sets the limit when cleaning up\&. Files are deleted (in LRU order) until the levels are below the limit\&. The default is 0\&.8 (= 80%)\&. See
+AUTOMATIC CLEANUP
+for more information\&.
.RE
.PP
\fBlog_file\fR (\fBCCACHE_LOGFILE\fR)
.PP
\fBmax_files\fR (\fBCCACHE_MAXFILES\fR)
.RS 4
-This option specifies the maximum number of files to keep in the cache\&. Use 0 for no limit (which is the default)\&.
+This option specifies the maximum number of files to keep in the cache\&. Use 0 for no limit (which is the default)\&. See also
+CACHE SIZE MANAGEMENT\&.
.RE
.PP
\fBmax_size\fR (\fBCCACHE_MAXSIZE\fR)
.RS 4
-This option specifies the maximum size of the cache\&. Use 0 for no limit\&. The default value is 5G\&. Available suffixes: k, M, G, T (decimal) and Ki, Mi, Gi, Ti (binary)\&. The default suffix is "G"\&.
+This option specifies the maximum size of the cache\&. Use 0 for no limit\&. The default value is 5G\&. Available suffixes: k, M, G, T (decimal) and Ki, Mi, Gi, Ti (binary)\&. The default suffix is "G"\&. See also
+CACHE SIZE MANAGEMENT\&.
.RE
.PP
\fBpath\fR (\fBCCACHE_PATH\fR)
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\fR
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\fR
+to false and pass
+\fB\-fdirectives\-only\fR
+(for GCC) or
+\fB\-frewrite\-includes\fR
+(for Clang) to the compiler\&. This will cause the compiler to leave the macros and other preprocessor information, and only process the
+\fB#include\fR
+directives\&. When run in this way, the preprocessor arguments will be passed to the compiler since it still has to do
+\fIsome\fR
+preprocessing (like macros)\&.
.RE
.PP
\fBsloppiness\fR (\fBCCACHE_SLOPPINESS\fR)
.PP
\fBfile_stat_matches\fR
.RS 4
-ccache normally examines a file\(cqs contents to determine whether it matches the cached version\&. With this option set, ccache will consider a file as matching its cached version if the sizes, mtimes and ctimes match\&.
+ccache normally examines a file\(cqs contents to determine whether it matches the cached version\&. With this option set, ccache will consider a file as matching its cached version if the mtimes and ctimes match\&.
.RE
.PP
\fBinclude_file_ctime\fR
.PP
\fBpch_defines\fR
.RS 4
-Be sloppy about #defines when precompiling a header file\&. See
+Be sloppy about
+\fB#define\fRs when precompiling a header file\&. See
PRECOMPILED HEADERS
for more information\&.
.RE
\fB\-g\fR
option is not used\&. The unifier is slower than a normal hash, so setting this environment variable loses a little bit of speed, but it means that ccache can take advantage of not recompiling when the changes to the source code consist of reformatting only\&. Note that enabling the unifier changes the hash, so cached compilations produced when the unifier is enabled cannot be reused when the unifier is disabled, and vice versa\&. Enabling the unifier may result in incorrect line number information in compiler warning messages and expansions of the
\fB__LINE__\fR
-macro\&. Also note that enabling the unifier implies turning off the direct mode\&.
+macro\&.
.RE
.SH "CACHE SIZE MANAGEMENT"
.sp
-By default, ccache has a five gigabyte limit on the total size of files in the cache and no maximum number of files\&. You can set different limits using the \fB\-M\fR/\fB\-\-max\-size\fR and \fB\-F\fR/\fB\-\-max\-files\fR options\&. Use \fBccache \-s/\-\-show\-stats\fR to see the cache size and the currently configured limits (in addition to other various statistics)\&.
+By default, ccache has a 5 GB limit on the total size of files in the cache and no limit on the number of files\&. You can set different limits using the \fB\-M\fR/\fB\-\-max\-size\fR and \fB\-F\fR/\fB\-\-max\-files\fR options\&. Use \fBccache \-s/\-\-show\-stats\fR to see the cache size and the currently configured limits (in addition to other various statistics)\&.
+.sp
+Cleanup can be triggered in two different ways: automatic and manual\&.
+.SS "Automatic cleanup"
+.sp
+ccache maintains counters for various statistics about the cache, including the size and number of all cached files\&. In order to improve performance and reduce issues with concurrent ccache invocations, there is one statistics file for each of the sixteen subdirectories in the cache\&.
+.sp
+After a new compilation result has been written to the cache, ccache will update the size and file number statistics for the subdirectory (one of sixteen) to which the result was written\&. Then, if the size counter for said subdirectory is greater than \fBmax_size / 16\fR or the file number counter is greater than \fBmax_files / 16\fR, automatic cleanup is triggered\&.
+.sp
+When automatic cleanup is triggered for a subdirectory in the cache, ccache will:
+.sp
+.RS 4
+.ie n \{\
+\h'-04' 1.\h'+01'\c
+.\}
+.el \{\
+.sp -1
+.IP " 1." 4.2
+.\}
+Count all files in the subdirectory and compute their aggregated size\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04' 2.\h'+01'\c
+.\}
+.el \{\
+.sp -1
+.IP " 2." 4.2
+.\}
+Remove files in LRU (least recently used) order until the size is at most
+\fBlimit_multiple * max_size / 16\fR
+and the number of files is at most
+\fBlimit_multiple * max_files / 16\fR, where
+\fBlimit_multiple\fR,
+\fBmax_size\fR
+and
+\fBmax_files\fR
+are configuration settings\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04' 3.\h'+01'\c
+.\}
+.el \{\
+.sp -1
+.IP " 3." 4.2
+.\}
+Set the size and file number counters to match the files that were kept\&.
+.RE
+.sp
+The reason for removing more files than just those needed to not exceed the max limits is that a cleanup is a fairly slow operation, so it would not be a good idea to trigger it often, like after each cache miss\&.
+.SS "Manual cleanup"
+.sp
+You can run \fBccache \-c/\-\-cleanup\fR to force cleanup of the whole cache, i\&.e\&. all of the sixteen subdirectories\&. This will recalculate the statistics counters and make sure that the \fBmax_size\fR and \fBmax_files\fR settings are not exceeded\&. Note that \fBlimit_multiple\fR is not taken into account for manual cleanup\&.
.SH "CACHE COMPRESSION"
.sp
ccache can optionally compress all files it puts into the cache using the compression library zlib\&. While this may involve a tiny performance slowdown, it increases the number of files that fit in the cache\&. You can turn on compression with the \fBcompression\fR configuration setting and you can also tweak the compression level with \fBcompression_level\fR\&.
.sp -1
.IP \(bu 2.3
.\}
-the unifier is enabled (the configuration setting
-\fBunify\fR
-is true)
-.RE
-.sp
-.RS 4
-.ie n \{\
-\h'-04'\(bu\h'+03'\c
-.\}
-.el \{\
-.sp -1
-.IP \(bu 2.3
-.\}
a compiler option not supported by the direct mode is used:
.sp
.RS 4
Based on the hash, the cached compilation result can be looked up directly in the cache\&.
.SH "COMPILING IN DIFFERENT DIRECTORIES"
.sp
-Some information included in the hash that identifies a unique compilation may contain absolute paths:
+Some information included in the hash that identifies a unique compilation can contain absolute paths:
.sp
.RS 4
.ie n \{\
.\}
Paths specified by compiler options (such as
\fB\-I\fR,
-\fB\-MF\fR, etc) may be absolute\&.
+\fB\-MF\fR, etc) on the command line may be absolute\&.
.RE
.sp
.RS 4
macros in the source code or included in warnings emitted to standard error by the preprocessor\&.
.RE
.sp
-This means that if you compile the same code in different locations, you can\(cqt share compilation results between the different build directories since you get cache misses because of the absolute build directory paths that are part of the hash\&. To mitigate this problem, you can specify a \(lqbase directory\(rq in the configuration setting \fBbase_dir\fR to an absolute path to the directory\&. ccache will then rewrite absolute paths that are under the base directory (i\&.e\&., paths that have the base directory as a prefix) to relative paths when constructing the hash\&. A typical path to use as the base directory is your home directory or another directory that is a parent of your build directories\&. (Don\(cqt use / as the base directory since that will make ccache also rewrite paths to system header files, which doesn\(cqt gain anything\&.)
+This means that if you compile the same code in different locations, you can\(cqt share compilation results between the different build directories since you get cache misses because of the absolute build directory paths that are part of the hash\&.
.sp
-The drawbacks of using a base directory are:
+Here\(cqs what can be done to enable cache hits between different build directories:
.sp
.RS 4
.ie n \{\
.sp -1
.IP \(bu 2.3
.\}
-If you specify an absolute path to the source code file,
-\fB__FILE__\fR
-macros will be expanded to a relative path instead\&.
+If you build with
+\fB\-g\fR
+(or similar) to add debug information to the object file, you must either:
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+use the
+\fB\-fdebug\-prefix\-map=\fR\fB\fIold\fR\fR\fB=\fR\fB\fInew\fR\fR
+option for relocating debug info to a common prefix (e\&.g\&.
+\fB\-fdebug\-prefix\-map=$PWD=\&.\fR); or
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+set
+\fBhash_dir = false\fR\&.
+.RE
.RE
.sp
.RS 4
.sp -1
.IP \(bu 2.3
.\}
-If you specify an absolute path to the source code file and compile with
-\fB\-g\fR, the source code path stored in the object file may point to the wrong directory, which may prevent debuggers like GDB from finding the source code\&. Sometimes, a work\-around is to change the directory explicitly with the \(lqcd\(rq command in GDB\&.
+If you use absolute paths anywhere on the command line (e\&.g\&. the source code file path or an argument to compiler options like
+\fB\-I\fR
+and
+\fB\-MF\fR), you must to set
+\fBbase_dir\fR
+to an absolute path to a \(lqbase directory\(rq\&. ccache will then rewrite absolute paths under that directory to relative before computing the hash\&.
.RE
.SH "PRECOMPILED HEADERS"
.sp
\fB__TIME__\fR
or
\fB__DATE__\fR
-is used when using a precompiled header\&. Further, it can\(cqt detect changes in #defines in the source code because of how preprocessing works in combination with precompiled headers\&.
+is used when using a precompiled header\&. Further, it can\(cqt detect changes in
+\fB#define\fRs in the source code because of how preprocessing works in combination with precompiled headers\&.
.RE
.sp
.RS 4
THE DIRECT MODE
above\&.
.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+When run via ccache, warning messages produced by GCC 4\&.9 and newer will only be colored when the environment variable
+\fBGCC_COLORS\fR
+is set\&. An alternative to setting
+\fBGCC_COLORS\fR
+is to pass
+\-fdiagnostics\-color
+explicitly when compiling (but then color codes will also be present when redirecting stderr to a file)\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+If ccache guesses that the compiler may emit colored warnings, then a compilation with stderr referring to a TTY will be considered different from a compilation with a redirected stderr, thus not sharing cache entries\&. This happens for clang by default and for GCC when
+\fBGCC_COLORS\fR
+is set as mentioned above\&. If you want to share cache hits, you can pass
+\-f[no\-]diagnostics\-color
+(GCC) or
+\-f[no\-]color\-diagnostics
+(clang) explicitly when compiling (but then color codes will be either on or off for both the TTY and the redirected case)\&.
+.RE
.SH "TROUBLESHOOTING"
.SS "General"
.sp
projects / platform / upstream / ccache.git / blobdiff