+<?xml version="1.0" encoding="UTF-8"?>\r
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"\r
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">\r
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">\r
<head>\r
<meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" />\r
-<meta name="generator" content="AsciiDoc 8.6.9" />\r
+<meta name="generator" content="AsciiDoc 8.6.10" />\r
<title>CCACHE(1)</title>\r
<style type="text/css">\r
/* Shared CSS for AsciiDoc xhtml11 and html5 backends */\r
<body class="article">\r
<div id="header">\r
<h1>CCACHE(1)</h1>\r
-<span id="revnumber">version 3.4.2</span>\r
+<span id="revnumber">version 3.7.3</span>\r
<div id="toc">
<div id="toctitle">Table of Contents</div>
<noscript><p><b>JavaScript must be enabled in your browser to display the table of contents.</b></p></noscript>
</p>\r
</dd>\r
<dt class="hdlist1">\r
-<strong><code>-F, --max-files</code></strong>=<em>N</em>\r
+<strong><code>--dump-manifest</code></strong>=<em>PATH</em>\r
</dt>\r
<dd>\r
<p>\r
- Set the maximum number of files allowed in the cache. Use 0 for no limit.\r
- The value is stored in a configuration file in the cache directory and\r
- applies to all future compilations.\r
+ Dump manifest file at PATH in text format. This is only useful when\r
+ debugging ccache and its behavior.\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
+<strong><code>-k, --get-config</code></strong>=<em>KEY</em>\r
+</dt>\r
+<dd>\r
+<p>\r
+ Print the value of configuration option <em>KEY</em>. See\r
+ <a href="#_configuration">CONFIGURATION</a> for more information.\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
+<strong><code>--hash-file</code></strong>=<em>PATH</em>\r
+</dt>\r
+<dd>\r
+<p>\r
+ Print the hash (in format <code><MD4>-<size></code>) of the file at PATH. This is only\r
+ useful when debugging ccache and its behavior.\r
</p>\r
</dd>\r
<dt class="hdlist1">\r
</p>\r
</dd>\r
<dt class="hdlist1">\r
+<strong><code>-F, --max-files</code></strong>=<em>N</em>\r
+</dt>\r
+<dd>\r
+<p>\r
+ Set the maximum number of files allowed in the cache. Use 0 for no limit.\r
+ The value is stored in a configuration file in the cache directory and\r
+ applies to all future compilations.\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
<strong><code>-M, --max-size</code></strong>=<em>SIZE</em>\r
</dt>\r
<dd>\r
</p>\r
</dd>\r
<dt class="hdlist1">\r
+<strong><code>--print-stats</code></strong>\r
+</dt>\r
+<dd>\r
+<p>\r
+ Print statistics counter IDs and corresponding values machine-parsable\r
+ (tab-separated) format.\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
<strong><code>-o, --set-config</code></strong>=<em>KEY=VALUE</em>\r
</dt>\r
<dd>\r
<p>\r
- Set configuration <em>KEY</em> to <em>VALUE</em>. See <a href="#_configuration">CONFIGURATION</a>\r
- for more information.\r
+ Set configuration option <em>KEY</em> to <em>VALUE</em>. See\r
+ <a href="#_configuration">CONFIGURATION</a> for more information.\r
</p>\r
</dd>\r
<dt class="hdlist1">\r
-<strong><code>-p, --print-config</code></strong>\r
+<strong><code>-p, --show-config</code></strong>\r
</dt>\r
<dd>\r
<p>\r
Print current configuration options and from where they originate\r
- (environment variable, configuration file or compile-time default).\r
+ (environment variable, configuration file or compile-time default) in\r
+ human-readable format.\r
</p>\r
</dd>\r
<dt class="hdlist1">\r
</dt>\r
<dd>\r
<p>\r
- Print the current statistics summary for the cache.\r
+ Print a summary of configuration and statistics counters in human-readable\r
+ format.\r
</p>\r
</dd>\r
<dt class="hdlist1">\r
</p>\r
</dd>\r
<dt class="hdlist1">\r
-<strong>compiler</strong> (<strong>CCACHE_CC</strong>)\r
+<strong>compiler</strong> (<strong>CCACHE_COMPILER</strong> or (deprecated) <strong>CCACHE_CC</strong>)\r
</dt>\r
<dd>\r
<p>\r
</p>\r
</dd>\r
<dt class="hdlist1">\r
+<strong>debug</strong> (<strong>CCACHE_DEBUG</strong> or <strong>CCACHE_NODEBUG</strong>, see <a href="#_boolean_values">Boolean values</a> above)\r
+</dt>\r
+<dd>\r
+<p>\r
+ If true, enable the debug mode. The debug mode creates per-object debug\r
+ files that are helpful when debugging unexpected cache misses. Note however\r
+ that ccache performance will be reduced slightly. See\r
+ <a href="#_cache_debugging">debugging</a> for more information. The default is false.\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
+<strong>depend_mode</strong> (<strong>CCACHE_DEPEND</strong> or <strong>CCACHE_NODEPEND</strong>, see <a href="#_boolean_values">Boolean values</a> above)\r
+</dt>\r
+<dd>\r
+<p>\r
+ If true, the depend mode will be used. The default is false. See\r
+ <a href="#_the_depend_mode">THE DEPEND MODE</a>.\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
<strong>direct_mode</strong> (<strong>CCACHE_DIRECT</strong> or <strong>CCACHE_NODIRECT</strong>, see <a href="#_boolean_values">Boolean values</a> above)\r
</dt>\r
<dd>\r
</p>\r
</dd>\r
<dt class="hdlist1">\r
+<strong>pch_external_checksum</strong> (<strong>CCACHE_PCH_EXTSUM</strong> or <strong>CCACHE_NOPCH_EXTSUM</strong>, see <a href="#_boolean_values">Boolean values</a> above)\r
+</dt>\r
+<dd>\r
+<p>\r
+ When this option is set, and ccache finds a precompiled header file,\r
+ ccache will look for a file with the extension “.sum” added\r
+ (e.g. “pre.h.gch.sum”), and if found, it will hash this file instead\r
+ of the precompiled header itself to work around the performance\r
+ penalty of hashing very large files.\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
<strong>prefix_command</strong> (<strong>CCACHE_PREFIX</strong>)\r
</dt>\r
<dd>\r
<div class="content">\r
<div class="dlist"><dl>\r
<dt class="hdlist1">\r
+<strong>clang_index_store</strong>\r
+</dt>\r
+<dd>\r
+<p>\r
+ Ignore the Clang compiler option <strong>-index-store-path</strong> and its argument when\r
+ computing the manifest hash. This is useful if you use Xcode, which uses an\r
+ index store path derived from the local project path. Note that the index\r
+ store won’t be updated correctly on cache hits if you enable this option.\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
<strong>file_macro</strong>\r
</dt>\r
<dd>\r
<p>\r
- Ignore <code>__FILE__</code> being present in the source.\r
+ ccache normally includes the input file path in the hash in order to be\r
+ able to produce the correct object file if the source code includes a\r
+ <code>__FILE__</code> macro. If you know that <code>__FILE__</code> isn’t used in practise, or\r
+ don’t care if ccache produces objects where <code>__FILE__</code> is expanded to the\r
+ wrong path, you can set <strong>sloppiness</strong> to <strong>file_macro</strong>. ccache will then\r
+ exclude the input file path from the hash.\r
</p>\r
</dd>\r
<dt class="hdlist1">\r
</p>\r
</dd>\r
<dt class="hdlist1">\r
+<strong>file_stat_matches_ctime</strong>\r
+</dt>\r
+<dd>\r
+<p>\r
+ Ignore ctimes when <strong>file_stat_matches</strong> is enabled. This can be useful when\r
+ backdating files' mtimes in a controlled way.\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
<strong>include_file_ctime</strong>\r
</dt>\r
<dd>\r
</p>\r
</dd>\r
<dt class="hdlist1">\r
-<strong>no_system_headers</strong>\r
+<strong>locale</strong>\r
</dt>\r
<dd>\r
<p>\r
- By default, ccache will also include all system headers in the manifest.\r
- With this option set, ccache will only include system headers in the hash\r
- but not add the system header files to the list of include files.\r
+ ccache includes the environment variables <strong>LANG</strong>, <strong>LC_ALL</strong>, <strong>LC_CTYPE</strong> and\r
+ <strong>LC_MESSAGES</strong> in the hash by default since they may affect localization of\r
+ compiler warning messages. Set this option to tell ccache not to do that.\r
</p>\r
</dd>\r
<dt class="hdlist1">\r
</p>\r
</dd>\r
<dt class="hdlist1">\r
+<strong>system_headers</strong>\r
+</dt>\r
+<dd>\r
+<p>\r
+ By default, ccache will also include all system headers in the manifest.\r
+ With this option set, ccache will only include system headers in the hash\r
+ but not add the system header files to the list of include files.\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
<strong>time_macros</strong>\r
</dt>\r
<dd>\r
<td align="left" valign="top"><p class="table">Preprocessing the source code using the compiler’s <strong>-E</strong> option failed.</p></td>\r
</tr>\r
<tr>\r
+<td align="left" valign="top"><p class="table">stats updated</p></td>\r
+<td align="left" valign="top"><p class="table">When statistics were updated the last time.</p></td>\r
+</tr>\r
+<tr>\r
+<td align="left" valign="top"><p class="table">stats zeroed</p></td>\r
+<td align="left" valign="top"><p class="table">When <strong>ccache -z</strong> was called the last time.</p></td>\r
+</tr>\r
+<tr>\r
<td align="left" valign="top"><p class="table">unsupported code directive</p></td>\r
<td align="left" valign="top"><p class="table">Code like the assembler <strong>.incbin</strong> directive was found. This is not supported\r
by ccache.</p></td>\r
enough to be used to identify recompilations.) On a cache hit, ccache is able\r
to supply all of the correct compiler outputs (including all warnings,\r
dependency file, etc) from the cache.</p></div>\r
-<div class="paragraph"><p>ccache has two ways of doing the detection:</p></div>\r
+<div class="paragraph"><p>ccache has two ways of gathering information used to look up results in the\r
+cache:</p></div>\r
<div class="ulist"><ul>\r
<li>\r
<p>\r
</ul></div>\r
<div class="paragraph"><p>The direct mode is generally faster since running the preprocessor has some\r
overhead.</p></div>\r
+<div class="paragraph"><p>If no previous result is detected (i.e., there is a cache miss) using the\r
+direct mode, ccache will fall back to the preprocessor mode unless the <strong>depend\r
+mode</strong> is enabled. In the depend mode, ccache never runs the preprocessor, not\r
+even on cache misses. Read more in <a href="#_the_depend_mode">THE DEPEND MODE</a>\r
+below.</p></div>\r
<div class="sect2">\r
<h3 id="_common_hashed_information">Common hashed information</h3>\r
-<div class="paragraph"><p>For both modes, the following information is included in the hash:</p></div>\r
+<div class="paragraph"><p>The following information is always included in the hash:</p></div>\r
<div class="ulist"><ul>\r
<li>\r
<p>\r
<div class="paragraph"><p>Based on the hash, the cached compilation result can be looked up directly in\r
the cache.</p></div>\r
</div>\r
+<div class="sect2">\r
+<h3 id="_the_depend_mode">The depend mode</h3>\r
+<div class="paragraph"><p>If the depend mode is enabled, ccache will not use the preprocessor at all. The\r
+hash used to identify results in the cache will be based on the direct mode\r
+hash described above plus information about include files read from the\r
+dependency file generated by the compiler with <strong>-MD</strong> or <strong>-MMD</strong>.</p></div>\r
+<div class="paragraph"><p>Advantages:</p></div>\r
+<div class="ulist"><ul>\r
+<li>\r
+<p>\r
+The ccache overhead of a cache miss will be much smaller.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+Not running the preprocessor at all can be good if compilation is performed\r
+ remotely, for instance when using distcc or similar; ccache then won’t make\r
+ potentially costly preprocessor calls on the local machine.\r
+</p>\r
+</li>\r
+</ul></div>\r
+<div class="paragraph"><p>Disadvantages:</p></div>\r
+<div class="ulist"><ul>\r
+<li>\r
+<p>\r
+The cache hit rate will likely be lower since any change to compiler options\r
+ or source code will make the hash different. Compare this with the default\r
+ setup where ccache will fall back to the preprocessor mode, which is tolerant\r
+ to some types of changes of compiler options and source code changes.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+If -MD is used, the manifest entries will include system header files as\r
+ well, thus slowing down cache hits slightly, just as using -MD slows down\r
+ make.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+If -MMD is used, the manifest entries will not include system header files,\r
+ which means ccache will ignore changes in them.\r
+</p>\r
+</li>\r
+</ul></div>\r
+<div class="paragraph"><p>The depend mode will be disabled if any of the following holds:</p></div>\r
+<div class="ulist"><ul>\r
+<li>\r
+<p>\r
+the configuration setting <strong>depend_mode</strong> is false\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+the configuration setting <strong>run_second_cpp</strong> is false\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+the configuration setting <strong>unify</strong> is true\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+the compiler is not generating dependencies using <strong>-MD</strong> or <strong>-MMD</strong>\r
+</p>\r
+</li>\r
+</ul></div>\r
+</div>\r
+</div>\r
+</div>\r
+<div class="sect1">\r
+<h2 id="_cache_debugging">Cache debugging</h2>\r
+<div class="sectionbody">\r
+<div class="paragraph"><p>To find out what information ccache actually is hashing, you can enable the\r
+debug mode via the configuration setting <strong>debug</strong> or by setting <strong>CCACHE_DEBUG</strong>\r
+in the environment. This can be useful if you are investigating why you don’t\r
+get cache hits. Note that performance will be reduced slightly.</p></div>\r
+<div class="paragraph"><p>When the debug mode is enabled, ccache will create up to five additional files\r
+next to the object file:</p></div>\r
+<div class="tableblock">\r
+<table rules="all"\r
+width="100%"\r
+frame="border"\r
+cellspacing="0" cellpadding="4">\r
+<col width="30%" />\r
+<col width="70%" />\r
+<thead>\r
+<tr>\r
+<th align="left" valign="top">Filename </th>\r
+<th align="left" valign="top"> Description</th>\r
+</tr>\r
+</thead>\r
+<tbody>\r
+<tr>\r
+<td align="left" valign="top"><p class="table"><strong><objectfile>.ccache-input-c</strong></p></td>\r
+<td align="left" valign="top"><p class="table">Binary input hashed by both the direct mode and the preprocessor mode.</p></td>\r
+</tr>\r
+<tr>\r
+<td align="left" valign="top"><p class="table"><strong><objectfile>.ccache-input-d</strong></p></td>\r
+<td align="left" valign="top"><p class="table">Binary input only hashed by the direct mode.</p></td>\r
+</tr>\r
+<tr>\r
+<td align="left" valign="top"><p class="table"><strong><objectfile>.ccache-input-p</strong></p></td>\r
+<td align="left" valign="top"><p class="table">Binary input only hashed by the preprocessor mode.</p></td>\r
+</tr>\r
+<tr>\r
+<td align="left" valign="top"><p class="table"><strong><objectfile>.ccache-input-text</strong></p></td>\r
+<td align="left" valign="top"><p class="table">Human-readable combined diffable text version of the three files above.</p></td>\r
+</tr>\r
+<tr>\r
+<td align="left" valign="top"><p class="table"><strong><objectfile>.ccache-log</strong></p></td>\r
+<td align="left" valign="top"><p class="table">Log for this object file.</p></td>\r
+</tr>\r
+</tbody>\r
+</table>\r
+</div>\r
+<div class="paragraph"><p>In the direct mode, ccache uses the MD4 hash of the <strong>ccache-input-c</strong>\r
++ <strong>ccache-input-d</strong> data (where <strong>+</strong> means concatenation), while the\r
+<strong>ccache-input-c</strong> + <strong>ccache-input-p</strong> data is used in the preprocessor mode.</p></div>\r
+<div class="paragraph"><p>The <strong>ccache-input-text</strong> file is a combined text version of the three\r
+binary input files. It has three sections (“COMMON”, “DIRECT MODE” and\r
+“PREPROCESSOR MODE”), which is turn contain annotations that say what kind of\r
+data comes next.</p></div>\r
+<div class="paragraph"><p>To debug why you don’t get an expected cache hit for an object file, you can do\r
+something like this:</p></div>\r
+<div class="olist arabic"><ol class="arabic">\r
+<li>\r
+<p>\r
+Build with debug mode enabled.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+Save the <strong><objectfile>.ccache-*</strong> files.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+Build again with debug mode enabled.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+Compare <strong><objectfile>.ccache-input-text</strong> for the two builds. This together\r
+ with the <strong><objectfile>.ccache-log</strong> files should give you some clues about\r
+ what is happening.\r
+</p>\r
+</li>\r
+</ol></div>\r
</div>\r
</div>\r
<div class="sect1">\r
<div class="ulist"><ul>\r
<li>\r
<p>\r
-use the <strong>-include</strong> compiler option to include the precompiled header\r
- (i.e., don’t use <strong>#include</strong> in the source code to include the header); or\r
+use the <strong>-include</strong> compiler option to include the precompiled header (i.e.,\r
+ don’t use <strong>#include</strong> in the source code to include the header; the filename\r
+ itself must be sufficient to find the header, i.e. <strong>-I</strong> paths are not\r
+ searched); or\r
</p>\r
</li>\r
<li>\r
</li>\r
<li>\r
<p>\r
-add the <strong>-fpch-preprocess</strong> compiler option when compiling.\r
+(for the GCC compiler) add the <strong>-fpch-preprocess</strong> compiler option when\r
+ compiling.\r
</p>\r
</li>\r
</ul></div>\r
<div class="sect2">\r
<h3 id="_general">General</h3>\r
<div class="paragraph"><p>A general tip for getting information about what ccache is doing is to enable\r
-debug logging by setting <strong>log_file</strong>. The log contains executed commands,\r
-important decisions that ccache makes, read and written files, etc. Another way\r
-of keeping track of what is happening is to check the output of <strong>ccache -s</strong>.</p></div>\r
+debug logging by setting the configuration option <strong>debug</strong> (or the environment\r
+variable <strong>CCACHE_DEBUG</strong>); see <a href="#_cache_debugging">debugging</a> for more\r
+information. Another way of keeping track of what is happening is to check the\r
+output of <strong>ccache -s</strong>.</p></div>\r
</div>\r
<div class="sect2">\r
<h3 id="_performance">Performance</h3>\r
</li>\r
<li>\r
<p>\r
-The <code>__FILE__</code> preprocessor macro is (potentially) being used and the file\r
- path has changed. If <code>__FILE__</code> is present in the source code, ccache hashes\r
- the current input file path in order to be able to produce the correct\r
- object file if the <code>__FILE__</code> macro affects the output. If you know that\r
- <code>__FILE__</code> isn’t used in practise, or don’t care if ccache produces objects\r
- where <code>__FILE__</code> is expanded to the wrong path, you can set <strong>sloppiness</strong> to\r
- <strong>file_macro</strong>.\r
+The input file path has changed. ccache normally includes the input file\r
+ path in the hash in order to be able to produce the correct object file if\r
+ the source code includes a <code>__FILE__</code> macro. If you know that <code>__FILE__</code>\r
+ isn’t used in practise, or don’t care if ccache produces objects where\r
+ <code>__FILE__</code> is expanded to the wrong path, you can set <strong>sloppiness</strong> to\r
+ <strong>file_macro</strong>. ccache will then exclude the input file path from the hash.\r
</p>\r
</li>\r
</ul></div>\r
<h2 id="_more_information">More information</h2>\r
<div class="sectionbody">\r
<div class="paragraph"><p>Credits, mailing list information, bug reporting instructions, source code,\r
-etc, can be found on ccache’s web site: <a href="https://ccache.samba.org">https://ccache.samba.org</a>.</p></div>\r
+etc, can be found on ccache’s web site: <a href="https://ccache.dev">https://ccache.dev</a>.</p></div>\r
</div>\r
</div>\r
<div class="sect1">\r
<div class="sectionbody">\r
<div class="paragraph"><p>ccache was originally written by Andrew Tridgell and is currently developed and\r
maintained by Joel Rosdahl. See AUTHORS.txt or AUTHORS.html and\r
-<a href="https://ccache.samba.org/credits.html">https://ccache.samba.org/credits.html</a> for a list of contributors.</p></div>\r
+<a href="https://ccache.dev/credits.html">https://ccache.dev/credits.html</a> for a list of contributors.</p></div>\r
</div>\r
</div>\r
</div>\r
<div id="footnotes"><hr /></div>\r
<div id="footer">\r
<div id="footer-text">\r
-Version 3.4.2<br />\r
+Version 3.7.3<br />\r
Last updated\r
- 2018-03-15 21:34:36 CET\r
+ 2019-08-17 22:37:25 CEST\r
</div>\r
</div>\r
</body>\r
projects / platform / upstream / ccache.git / blobdiff