.\" Title: ccache
.\" Author: [see the "Author" section]
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
-.\" Date: 01/13/2018
+.\" Date: 02/11/2018
.\" Manual: ccache Manual
-.\" Source: ccache 3.3.5
+.\" Source: ccache 3.3.6+95_g181effa
.\" Language: English
.\"
-.TH "CCACHE" "1" "01/13/2018" "ccache 3\&.3\&.5" "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
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)
\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
.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
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