WARNING: The technique of letting ccache masquerade as the compiler works well,
but currently doesn't interact well with other tools that do the same thing.
-See <<_using_ccache_with_other_compiler_wrappers,USING CCACHE WITH OTHER
-COMPILER WRAPPERS>>.
+See _<<_using_ccache_with_other_compiler_wrappers,Using ccache with other
+compiler wrappers>>_.
WARNING: Use a symbolic links for masquerading, not hard links.
level can be an integer, with the same semantics as the
<<config_compression_level,*compression_level*>> configuration option), or
the special value *uncompressed* for no compression. See
- <<_cache_compression,CACHE COMPRESSION>> for more information. This can
+ _<<_cache_compression,Cache compression>>_ for more information. This can
potentionally take a long time since all files in the cache need to be
visited. Only files that are currently compressed with a different level
than _LEVEL_ will be recompressed.
*`-o`* _KEY=VALUE_, *`--set-config`* _KEY_=_VALUE_::
Set configuration option _KEY_ to _VALUE_. See
- <<_configuration,CONFIGURATION>> for more information.
+ _<<_configuration,Configuration>>_ for more information.
*`-x`*, *`--show-compression`*::
- Print cache compression statistics. See <<_cache_compression,CACHE
- COMPRESSION>> for more information. This can potentionally take a long time
- since all files in the cache need to be visited.
+ Print cache compression statistics. See _<<_cache_compression,Cache
+ compression>>_ for more information. This can potentionally take a long
+ time since all files in the cache need to be visited.
*`-p`*, *`--show-config`*::
*`-k`* _KEY_, *`--get-config`* _KEY_::
Print the value of configuration option _KEY_. See
- <<_configuration,CONFIGURATION>> for more information.
+ _<<_configuration,Configuration>>_ for more information.
*`--hash-file`* _PATH_::
*`--print-stats`*::
- Print statistics counter IDs and corresponding values machine-parsable
+ Print statistics counter IDs and corresponding values in machine-parsable
(tab-separated) format.
directory, but only absolute paths that begin with *base_dir*. Cache
results can then be shared for compilations in different directories even
if the project uses absolute paths in the compiler command line. See also
- the discussion under <<_compiling_in_different_directories,COMPILING IN
- DIFFERENT DIRECTORIES>>. If set to the empty string (which is the default),
- no rewriting is done.
+ the discussion under _<<_compiling_in_different_directories,Compiling in
+ different directories>>_. If set to the empty string (which is the
+ default), no rewriting is done.
+
A typical path to use as *base_dir* is your home directory or another directory
that is a parent of your project directories. Don't use `/` as the base
an environment variable. The default is *$XDG_CACHE_HOME/ccache* if
*XDG_CACHE_HOME* is set, otherwise *$HOME/.cache/ccache*. Exception: If the
legacy directory *$HOME/.ccache* exists then that directory is the default.
-
- See also <<_location_of_the_primary_configuration_file,LOCATION OF THE
- PRIMARY CONFIGURATION FILE>>.
-
- If you want to use another *CCACHE_DIR* value temporarily for one ccache
- invocation you can use the `-d/--directory` command line option instead.
+ See also _<<_location_of_the_primary_configuration_file,Location of the
+ primary configuration file>>_.
++
+If you want to use another *CCACHE_DIR* value temporarily for one ccache
+invocation you can use the `-d/--directory` command line option instead.
[[config_compiler]] *compiler* (*CCACHE_COMPILER* or (deprecated) *CCACHE_CC*)::
method will hash the mtime and size of the other compiler wrapper, which means
that ccache won't be able to detect a compiler upgrade. Using a suitable
command to identify the compiler is thus safer, but it's also slower, so you
-should consider continue using the *mtime* method in combination with
-the *prefix_command* option if possible. See
-<<_using_ccache_with_other_compiler_wrappers,USING CCACHE WITH OTHER COMPILER
-WRAPPERS>>.
+should consider continue using the *mtime* method in combination with the
+*prefix_command* option if possible. See
+_<<_using_ccache_with_other_compiler_wrappers,Using ccache with other compiler
+wrappers>>_.
--
--
distcc's "pump" script.
--
-[[config_compression]] *compression* (*CCACHE_COMPRESS* or *CCACHE_NOCOMPRESS*, see <<_boolean_values,Boolean values>> above)::
+[[config_compression]] *compression* (*CCACHE_COMPRESS* or *CCACHE_NOCOMPRESS*, see _<<_boolean_values,Boolean values>>_ above)::
If true, ccache will compress data it puts in the cache. However, this
option has no effect on how files are retrieved from the cache; compressed
compiled, but that sometimes doesn't work. For example, when using the
``aCC'' compiler on HP-UX, set the cpp extension to *i*.
-[[config_debug]] *debug* (*CCACHE_DEBUG* or *CCACHE_NODEBUG*, see <<_boolean_values,Boolean values>> above)::
+[[config_debug]] *debug* (*CCACHE_DEBUG* or *CCACHE_NODEBUG*, see _<<_boolean_values,Boolean values>>_ above)::
If true, enable the debug mode. The debug mode creates per-object debug
files that are helpful when debugging unexpected cache misses. Note however
that ccache performance will be reduced slightly. See
- <<_cache_debugging,debugging>> for more information. The default is false.
+ _<<_cache_debugging,Cache debugging>>_ for more information. The default is
+ false.
-[[config_depend_mode]] *depend_mode* (*CCACHE_DEPEND* or *CCACHE_NODEPEND*, see <<_boolean_values,Boolean values>> above)::
+[[config_depend_mode]] *depend_mode* (*CCACHE_DEPEND* or *CCACHE_NODEPEND*, see _<<_boolean_values,Boolean values>>_ above)::
If true, the depend mode will be used. The default is false. See
- <<_the_depend_mode,THE DEPEND MODE>>.
+ _<<_the_depend_mode,The depend mode>>_.
-[[config_direct_mode]] *direct_mode* (*CCACHE_DIRECT* or *CCACHE_NODIRECT*, see <<_boolean_values,Boolean values>> above)::
+[[config_direct_mode]] *direct_mode* (*CCACHE_DIRECT* or *CCACHE_NODIRECT*, see _<<_boolean_values,Boolean values>>_ above)::
If true, the direct mode will be used. The default is true. See
- <<_the_direct_mode,THE DIRECT MODE>>.
+ _<<_the_direct_mode,The direct mode>>_.
-[[config_disable]] *disable* (*CCACHE_DISABLE* or *CCACHE_NODISABLE*, see <<_boolean_values,Boolean values>> above)::
+[[config_disable]] *disable* (*CCACHE_DISABLE* or *CCACHE_NODISABLE*, see _<<_boolean_values,Boolean values>>_ above)::
When true, ccache will just call the real compiler, bypassing the cache
completely. The default is false.
hash sum that identifies the build. The list separator is semicolon on
Windows systems and colon on other systems.
-[[config_file_clone]] *file_clone* (*CCACHE_FILECLONE* or *CCACHE_NOFILECLONE*, see <<_boolean_values,Boolean values>> above)::
+[[config_file_clone]] *file_clone* (*CCACHE_FILECLONE* or *CCACHE_NOFILECLONE*, see _<<_boolean_values,Boolean values>>_ above)::
If true, ccache will attempt to use file cloning (also known as “copy on
write”, “CoW” or “reflinks”) to store and fetch cached compiler results.
systems, ccache will fall back to use plain copying (or hard links if
<<config_hard_link,*hard_link*>> is enabled).
-[[config_hard_link]] *hard_link* (*CCACHE_HARDLINK* or *CCACHE_NOHARDLINK*, see <<_boolean_values,Boolean values>> above)::
+[[config_hard_link]] *hard_link* (*CCACHE_HARDLINK* or *CCACHE_NOHARDLINK*, see _<<_boolean_values,Boolean values>>_ above)::
If true, ccache will attempt to use hard links to store and fetch cached
object files. The default is false.
*file.o* in build tree A as well. This can retrigger relinking in build tree
A even though nothing really has changed.
-[[config_hash_dir]] *hash_dir* (*CCACHE_HASHDIR* or *CCACHE_NOHASHDIR*, see <<_boolean_values,Boolean values>> above)::
+[[config_hash_dir]] *hash_dir* (*CCACHE_HASHDIR* or *CCACHE_NOHASHDIR*, see _<<_boolean_values,Boolean values>>_ above)::
If true (which is the default), ccache will include the current working
directory (CWD) in the hash that is used to distinguish two compilations
Exception: The CWD will not be included in the hash if
<<config_base_dir,*base_dir*>> is set (and matches the CWD) and the
compiler option *-fdebug-prefix-map* is used. See also the discussion under
- <<_compiling_in_different_directories,COMPILING IN DIFFERENT DIRECTORIES>>.
+ _<<_compiling_in_different_directories,Compiling in different
+ directories>>_.
+
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
example, `-fmessage-length=*` will match both `-fmessage-length=20` and
`-fmessage-length=70`.
-[[config_inode_cache]] *inode_cache* (*CCACHE_INODECACHE* or *CCACHE_NOINODECACHE*, see <<_boolean_values,Boolean values>> above)::
+[[config_inode_cache]] *inode_cache* (*CCACHE_INODECACHE* or *CCACHE_NOINODECACHE*, see _<<_boolean_values,Boolean values>>_ above)::
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 feature requires *temporary_dir* to be located on a local filesystem.
-[[config_keep_comments_cpp]] *keep_comments_cpp* (*CCACHE_COMMENTS* or *CCACHE_NOCOMMENTS*, see <<_boolean_values,Boolean values>> above)::
+[[config_keep_comments_cpp]] *keep_comments_cpp* (*CCACHE_COMMENTS* or *CCACHE_NOCOMMENTS*, see _<<_boolean_values,Boolean values>>_ above)::
If true, ccache will not discard the comments before hashing preprocessor
output. This can be used to check documentation with *-Wdocumentation*.
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,AUTOMATIC CLEANUP>> for more information.
+ _<<_automatic_cleanup,Automatic cleanup>>_ for more information.
[[config_log_file]] *log_file* (*CCACHE_LOGFILE*)::
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,CACHE SIZE MANAGEMENT>>.
+ _<<_cache_size_management,Cache size management>>_.
[[config_max_size]] *max_size* (*CCACHE_MAXSIZE*)::
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,CACHE SIZE MANAGEMENT>>.
+ _<<_cache_size_management,Cache size management>>_.
[[config_path]] *path* (*CCACHE_PATH*)::
matching the compiler name in the normal *PATH* that isn't a symbolic link
to ccache itself.
-[[config_pch_external_checksum]] *pch_external_checksum* (*CCACHE_PCH_EXTSUM* or *CCACHE_NOPCH_EXTSUM*, see <<_boolean_values,Boolean values>> above)::
+[[config_pch_external_checksum]] *pch_external_checksum* (*CCACHE_PCH_EXTSUM* or *CCACHE_NOPCH_EXTSUM*, see _<<_boolean_values,Boolean values>>_ above)::
When this option is set, and ccache finds a precompiled header file,
ccache will look for a file with the extension ``.sum'' added
This option adds a list of prefixes (separated by space) to the command
line that ccache uses when invoking the compiler. See also
- <<_using_ccache_with_other_compiler_wrappers,USING CCACHE WITH OTHER
- COMPILER WRAPPERS>>.
+ _<<_using_ccache_with_other_compiler_wrappers,Using ccache with other
+ compiler wrappers>>_.
[[config_prefix_command_cpp]] *prefix_command_cpp* (*CCACHE_PREFIX_CPP*)::
This option adds a list of prefixes (separated by space) to the command
line that ccache uses when invoking the preprocessor.
-[[config_read_only]] *read_only* (*CCACHE_READONLY* or *CCACHE_NOREADONLY*, see <<_boolean_values,Boolean values>> above)::
+[[config_read_only]] *read_only* (*CCACHE_READONLY* or *CCACHE_NOREADONLY*, see _<<_boolean_values,Boolean values>>_ above)::
If true, ccache will attempt to use existing cached results, but it will not
add new results to the cache. Statistics counters will still be updated,
temporary files otherwise. You may also want to set <<config_stats,*stats*>> to
*false* make ccache not even try to update stats files.
-[[config_read_only_direct]] *read_only_direct* (*CCACHE_READONLY_DIRECT* or *CCACHE_NOREADONLY_DIRECT*, see <<_boolean_values,Boolean values>> above)::
+[[config_read_only_direct]] *read_only_direct* (*CCACHE_READONLY_DIRECT* or *CCACHE_NOREADONLY_DIRECT*, see _<<_boolean_values,Boolean values>>_ above)::
Just like <<config_read_only,*read_only*>> except that ccache will only try
to retrieve results from the cache using the direct mode, not the
preprocessor mode. See documentation for <<config_read_only,*read_only*>>
regarding using a read-only ccache directory.
-[[config_recache]] *recache* (*CCACHE_RECACHE* or *CCACHE_NORECACHE*, see <<_boolean_values,Boolean values>> above)::
+[[config_recache]] *recache* (*CCACHE_RECACHE* or *CCACHE_NORECACHE*, see _<<_boolean_values,Boolean values>>_ above)::
If true, ccache will not use any previously stored result. New results will
still be cached, possibly overwriting any pre-existing results.
-[[config_run_second_cpp]] *run_second_cpp* (*CCACHE_CPP2* or *CCACHE_NOCPP2*, see <<_boolean_values,Boolean values>> above)::
+[[config_run_second_cpp]] *run_second_cpp* (*CCACHE_CPP2* or *CCACHE_NOCPP2*, see _<<_boolean_values,Boolean values>>_ above)::
If true, ccache will first run the preprocessor to preprocess the source
- code (see <<_the_preprocessor_mode,THE PREPROCESSOR MODE>>) and then on a
+ code (see _<<_the_preprocessor_mode,The preprocessor mode>>_) and then on a
cache miss run the compiler on the source code to get hold of the object
file. This is the default.
+
that.
*pch_defines*::
Be sloppy about **#define**s when precompiling a header file. See
- <<_precompiled_headers,PRECOMPILED HEADERS>> for more information.
+ _<<_precompiled_headers,Precompiled headers>>_ for more information.
*modules*::
By default, ccache will not cache compilations if *-fmodules* is used since
it cannot hash the state of compiler's internal representation of relevant
modules. This sloppiness allows caching in such a case. See
- <<_c_modules,C++ MODULES>> for more information.
+ _<<_c_modules,C++ modules>>_ for more information.
*system_headers*::
By default, ccache will also include all system headers in the manifest.
With this sloppiness set, ccache will only include system headers in the
source code.
--
+
-See the discussion under <<_troubleshooting,TROUBLESHOOTING>> for more
+See the discussion under _<<_troubleshooting,Troubleshooting>>_ for more
information.
-[[config_stats]] *stats* (*CCACHE_STATS* or *CCACHE_NOSTATS*, see <<_boolean_values,Boolean values>> above)::
+[[config_stats]] *stats* (*CCACHE_STATS* or *CCACHE_NOSTATS*, see _<<_boolean_values,Boolean values>>_ above)::
If true, ccache will update the statistics counters on each compilation.
The default is true.
If no previous result is detected (i.e., there is a cache miss) using the
direct mode, ccache will fall back to the preprocessor mode unless the *depend
mode* is enabled. In the depend mode, ccache never runs the preprocessor, not
-even on cache misses. Read more in <<_the_depend_mode,THE DEPEND MODE>>
+even on cache misses. Read more in _<<_the_depend_mode,The depend mode>>_
below.
-------
* The direct mode fails to pick up new header files in some rare scenarios. See
- <<_the_direct_mode,THE DIRECT MODE>> above.
+ _<<_the_direct_mode,The direct mode>>_ above.
Troubleshooting
A general tip for getting information about what ccache is doing is to enable
debug logging by setting the configuration option <<config_debug,*debug*>> (or
-the environment variable *CCACHE_DEBUG*); see <<_cache_debugging,debugging>>
-for more information. Another way of keeping track of what is happening is to
-check the output of *ccache -s*.
+the environment variable *CCACHE_DEBUG*); see _<<_cache_debugging,Cache
+debugging>>_ for more information. Another way of keeping track of what is
+happening is to check the output of *ccache -s*.
Performance
* If ``unsupported compiler option'' has been incremented, enable debug logging
and check which compiler option was rejected.
* If ``preprocessor error'' has been incremented, one possible reason is that
- precompiled headers are being used. See <<_precompiled_headers,PRECOMPILED
- HEADERS>> for how to remedy this.
+ precompiled headers are being used. See _<<_precompiled_headers,Precompiled
+ headers>>_ for how to remedy this.
* If ``can't use precompiled header'' has been incremented, see
- <<_precompiled_headers,PRECOMPILED HEADERS>>.
-* If ``can't use modules'' has been incremented, see
- <<_c_modules,C++ MODULES>>.
+ _<<_precompiled_headers,Precompiled headers>>_.
+* If ``can't use modules'' has been incremented, see _<<_c_modules,C++
+ modules>>_.
Corrupt object files
projects / thirdparty / ccache.git / commitdiff
