1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
\r
2 "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
\r
3 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
\r
5 <meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" />
\r
6 <meta name="generator" content="AsciiDoc 8.6.9" />
\r
7 <title>CCACHE(1)</title>
\r
8 <style type="text/css">
\r
9 /* Shared CSS for AsciiDoc xhtml11 and html5 backends */
\r
13 font-family: Georgia,serif;
\r
17 h1, h2, h3, h4, h5, h6,
\r
18 div.title, caption.title,
\r
19 thead, p.table.header,
\r
21 #author, #revnumber, #revdate, #revremark,
\r
23 font-family: Arial,Helvetica,sans-serif;
\r
27 margin: 1em 5% 1em 5%;
\r
32 text-decoration: underline;
\r
48 h1, h2, h3, h4, h5, h6 {
\r
51 margin-bottom: 0.5em;
\r
56 border-bottom: 2px solid silver;
\r
76 border: 1px solid silver;
\r
81 margin-bottom: 0.5em;
\r
87 ul > li { color: #aaa; }
\r
88 ul > li > * { color: black; }
\r
90 .monospaced, code, pre {
\r
91 font-family: "Courier New", Courier, monospace;
\r
98 white-space: pre-wrap;
\r
108 #revnumber, #revdate, #revremark {
\r
113 border-top: 2px solid silver;
\r
114 padding-top: 0.5em;
\r
119 padding-bottom: 0.5em;
\r
123 padding-bottom: 0.5em;
\r
128 margin-bottom: 1.5em;
\r
130 div.imageblock, div.exampleblock, div.verseblock,
\r
131 div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
\r
132 div.admonitionblock {
\r
134 margin-bottom: 1.5em;
\r
136 div.admonitionblock {
\r
138 margin-bottom: 2.0em;
\r
143 div.content { /* Block element content. */
\r
147 /* Block element titles. */
\r
148 div.title, caption.title {
\r
153 margin-bottom: 0.5em;
\r
159 td div.title:first-child {
\r
162 div.content div.title:first-child {
\r
165 div.content + div.title {
\r
169 div.sidebarblock > div.content {
\r
170 background: #ffffee;
\r
171 border: 1px solid #dddddd;
\r
172 border-left: 4px solid #f0f0f0;
\r
176 div.listingblock > div.content {
\r
177 border: 1px solid #dddddd;
\r
178 border-left: 5px solid #f0f0f0;
\r
179 background: #f8f8f8;
\r
183 div.quoteblock, div.verseblock {
\r
184 padding-left: 1.0em;
\r
185 margin-left: 1.0em;
\r
187 border-left: 5px solid #f0f0f0;
\r
191 div.quoteblock > div.attribution {
\r
192 padding-top: 0.5em;
\r
196 div.verseblock > pre.content {
\r
197 font-family: inherit;
\r
198 font-size: inherit;
\r
200 div.verseblock > div.attribution {
\r
201 padding-top: 0.75em;
\r
204 /* DEPRECATED: Pre version 8.2.7 verse style literal block. */
\r
205 div.verseblock + div.attribution {
\r
209 div.admonitionblock .icon {
\r
210 vertical-align: top;
\r
213 text-decoration: underline;
\r
215 padding-right: 0.5em;
\r
217 div.admonitionblock td.content {
\r
218 padding-left: 0.5em;
\r
219 border-left: 3px solid #dddddd;
\r
222 div.exampleblock > div.content {
\r
223 border-left: 3px solid #dddddd;
\r
224 padding-left: 0.5em;
\r
227 div.imageblock div.content { padding-left: 0; }
\r
228 span.image img { border-style: none; vertical-align: text-bottom; }
\r
229 a.image:visited { color: white; }
\r
233 margin-bottom: 0.8em;
\r
238 font-style: normal;
\r
241 dd > *:first-child {
\r
246 list-style-position: outside;
\r
249 list-style-type: decimal;
\r
252 list-style-type: lower-alpha;
\r
255 list-style-type: upper-alpha;
\r
258 list-style-type: lower-roman;
\r
261 list-style-type: upper-roman;
\r
264 div.compact ul, div.compact ol,
\r
265 div.compact p, div.compact p,
\r
266 div.compact div, div.compact div {
\r
268 margin-bottom: 0.1em;
\r
280 margin-bottom: 0.8em;
\r
283 padding-bottom: 15px;
\r
285 dt.hdlist1.strong, td.hdlist1.strong {
\r
289 vertical-align: top;
\r
290 font-style: normal;
\r
291 padding-right: 0.8em;
\r
295 vertical-align: top;
\r
297 div.hdlist.compact tr {
\r
303 background: yellow;
\r
306 .footnote, .footnoteref {
\r
310 span.footnote, span.footnoteref {
\r
311 vertical-align: super;
\r
315 margin: 20px 0 20px 0;
\r
316 padding: 7px 0 0 0;
\r
319 #footnotes div.footnote {
\r
325 border-top: 1px solid silver;
\r
334 padding-right: 0.5em;
\r
335 padding-bottom: 0.3em;
\r
336 vertical-align: top;
\r
338 div.colist td img {
\r
343 #footer-badges { display: none; }
\r
347 margin-bottom: 2.5em;
\r
355 margin-bottom: 0.1em;
\r
358 div.toclevel0, div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
\r
375 span.aqua { color: aqua; }
\r
376 span.black { color: black; }
\r
377 span.blue { color: blue; }
\r
378 span.fuchsia { color: fuchsia; }
\r
379 span.gray { color: gray; }
\r
380 span.green { color: green; }
\r
381 span.lime { color: lime; }
\r
382 span.maroon { color: maroon; }
\r
383 span.navy { color: navy; }
\r
384 span.olive { color: olive; }
\r
385 span.purple { color: purple; }
\r
386 span.red { color: red; }
\r
387 span.silver { color: silver; }
\r
388 span.teal { color: teal; }
\r
389 span.white { color: white; }
\r
390 span.yellow { color: yellow; }
\r
392 span.aqua-background { background: aqua; }
\r
393 span.black-background { background: black; }
\r
394 span.blue-background { background: blue; }
\r
395 span.fuchsia-background { background: fuchsia; }
\r
396 span.gray-background { background: gray; }
\r
397 span.green-background { background: green; }
\r
398 span.lime-background { background: lime; }
\r
399 span.maroon-background { background: maroon; }
\r
400 span.navy-background { background: navy; }
\r
401 span.olive-background { background: olive; }
\r
402 span.purple-background { background: purple; }
\r
403 span.red-background { background: red; }
\r
404 span.silver-background { background: silver; }
\r
405 span.teal-background { background: teal; }
\r
406 span.white-background { background: white; }
\r
407 span.yellow-background { background: yellow; }
\r
409 span.big { font-size: 2em; }
\r
410 span.small { font-size: 0.6em; }
\r
412 span.underline { text-decoration: underline; }
\r
413 span.overline { text-decoration: overline; }
\r
414 span.line-through { text-decoration: line-through; }
\r
416 div.unbreakable { page-break-inside: avoid; }
\r
426 margin-bottom: 1.5em;
\r
428 div.tableblock > table {
\r
429 border: 3px solid #527bbd;
\r
431 thead, p.table.header {
\r
438 /* Because the table frame attribute is overriden by CSS in most browsers. */
\r
439 div.tableblock > table[frame="void"] {
\r
440 border-style: none;
\r
442 div.tableblock > table[frame="hsides"] {
\r
443 border-left-style: none;
\r
444 border-right-style: none;
\r
446 div.tableblock > table[frame="vsides"] {
\r
447 border-top-style: none;
\r
448 border-bottom-style: none;
\r
459 margin-bottom: 1.5em;
\r
461 thead, p.tableblock.header {
\r
470 border-spacing: 0px;
\r
471 border-style: solid;
\r
472 border-color: #527bbd;
\r
473 border-collapse: collapse;
\r
475 th.tableblock, td.tableblock {
\r
478 border-style: solid;
\r
479 border-color: #527bbd;
\r
482 table.tableblock.frame-topbot {
\r
483 border-left-style: hidden;
\r
484 border-right-style: hidden;
\r
486 table.tableblock.frame-sides {
\r
487 border-top-style: hidden;
\r
488 border-bottom-style: hidden;
\r
490 table.tableblock.frame-none {
\r
491 border-style: hidden;
\r
494 th.tableblock.halign-left, td.tableblock.halign-left {
\r
497 th.tableblock.halign-center, td.tableblock.halign-center {
\r
498 text-align: center;
\r
500 th.tableblock.halign-right, td.tableblock.halign-right {
\r
504 th.tableblock.valign-top, td.tableblock.valign-top {
\r
505 vertical-align: top;
\r
507 th.tableblock.valign-middle, td.tableblock.valign-middle {
\r
508 vertical-align: middle;
\r
510 th.tableblock.valign-bottom, td.tableblock.valign-bottom {
\r
511 vertical-align: bottom;
\r
521 padding-top: 0.5em;
\r
522 padding-bottom: 0.5em;
\r
523 border-top: 2px solid silver;
\r
524 border-bottom: 2px solid silver;
\r
527 border-style: none;
\r
529 body.manpage div.sectionbody {
\r
534 body.manpage div#toc { display: none; }
\r
539 <script type="text/javascript">
\r
541 var asciidoc = { // Namespace.
\r
543 /////////////////////////////////////////////////////////////////////
\r
544 // Table Of Contents generator
\r
545 /////////////////////////////////////////////////////////////////////
\r
547 /* Author: Mihai Bazon, September 2002
\r
548 * http://students.infoiasi.ro/~mishoo
\r
550 * Table Of Content generator
\r
553 * Feel free to use this script under the terms of the GNU General Public
\r
554 * License, as long as you do not remove or alter this notice.
\r
557 /* modified by Troy D. Hanson, September 2006. License: GPL */
\r
558 /* modified by Stuart Rackham, 2006, 2009. License: GPL */
\r
560 // toclevels = 1..4.
\r
561 toc: function (toclevels) {
\r
563 function getText(el) {
\r
565 for (var i = el.firstChild; i != null; i = i.nextSibling) {
\r
566 if (i.nodeType == 3 /* Node.TEXT_NODE */) // IE doesn't speak constants.
\r
568 else if (i.firstChild != null)
\r
569 text += getText(i);
\r
574 function TocEntry(el, text, toclevel) {
\r
577 this.toclevel = toclevel;
\r
580 function tocEntries(el, toclevels) {
\r
581 var result = new Array;
\r
582 var re = new RegExp('[hH]([1-'+(toclevels+1)+'])');
\r
583 // Function that scans the DOM tree for header elements (the DOM2
\r
584 // nodeIterator API would be a better technique but not supported by all
\r
586 var iterate = function (el) {
\r
587 for (var i = el.firstChild; i != null; i = i.nextSibling) {
\r
588 if (i.nodeType == 1 /* Node.ELEMENT_NODE */) {
\r
589 var mo = re.exec(i.tagName);
\r
590 if (mo && (i.getAttribute("class") || i.getAttribute("className")) != "float") {
\r
591 result[result.length] = new TocEntry(i, getText(i), mo[1]-1);
\r
601 var toc = document.getElementById("toc");
\r
606 // Delete existing TOC entries in case we're reloading the TOC.
\r
607 var tocEntriesToRemove = [];
\r
609 for (i = 0; i < toc.childNodes.length; i++) {
\r
610 var entry = toc.childNodes[i];
\r
611 if (entry.nodeName.toLowerCase() == 'div'
\r
612 && entry.getAttribute("class")
\r
613 && entry.getAttribute("class").match(/^toclevel/))
\r
614 tocEntriesToRemove.push(entry);
\r
616 for (i = 0; i < tocEntriesToRemove.length; i++) {
\r
617 toc.removeChild(tocEntriesToRemove[i]);
\r
620 // Rebuild TOC entries.
\r
621 var entries = tocEntries(document.getElementById("content"), toclevels);
\r
622 for (var i = 0; i < entries.length; ++i) {
\r
623 var entry = entries[i];
\r
624 if (entry.element.id == "")
\r
625 entry.element.id = "_toc_" + i;
\r
626 var a = document.createElement("a");
\r
627 a.href = "#" + entry.element.id;
\r
628 a.appendChild(document.createTextNode(entry.text));
\r
629 var div = document.createElement("div");
\r
630 div.appendChild(a);
\r
631 div.className = "toclevel" + entry.toclevel;
\r
632 toc.appendChild(div);
\r
634 if (entries.length == 0)
\r
635 toc.parentNode.removeChild(toc);
\r
639 /////////////////////////////////////////////////////////////////////
\r
640 // Footnotes generator
\r
641 /////////////////////////////////////////////////////////////////////
\r
643 /* Based on footnote generation code from:
\r
644 * http://www.brandspankingnew.net/archive/2005/07/format_footnote.html
\r
647 footnotes: function () {
\r
648 // Delete existing footnote entries in case we're reloading the footnodes.
\r
650 var noteholder = document.getElementById("footnotes");
\r
654 var entriesToRemove = [];
\r
655 for (i = 0; i < noteholder.childNodes.length; i++) {
\r
656 var entry = noteholder.childNodes[i];
\r
657 if (entry.nodeName.toLowerCase() == 'div' && entry.getAttribute("class") == "footnote")
\r
658 entriesToRemove.push(entry);
\r
660 for (i = 0; i < entriesToRemove.length; i++) {
\r
661 noteholder.removeChild(entriesToRemove[i]);
\r
664 // Rebuild footnote entries.
\r
665 var cont = document.getElementById("content");
\r
666 var spans = cont.getElementsByTagName("span");
\r
669 for (i=0; i<spans.length; i++) {
\r
670 if (spans[i].className == "footnote") {
\r
672 var note = spans[i].getAttribute("data-note");
\r
674 // Use [\s\S] in place of . so multi-line matches work.
\r
675 // Because JavaScript has no s (dotall) regex flag.
\r
676 note = spans[i].innerHTML.match(/\s*\[([\s\S]*)]\s*/)[1];
\r
677 spans[i].innerHTML =
\r
678 "[<a id='_footnoteref_" + n + "' href='#_footnote_" + n +
\r
679 "' title='View footnote' class='footnote'>" + n + "</a>]";
\r
680 spans[i].setAttribute("data-note", note);
\r
682 noteholder.innerHTML +=
\r
683 "<div class='footnote' id='_footnote_" + n + "'>" +
\r
684 "<a href='#_footnoteref_" + n + "' title='Return to text'>" +
\r
685 n + "</a>. " + note + "</div>";
\r
686 var id =spans[i].getAttribute("id");
\r
687 if (id != null) refs["#"+id] = n;
\r
691 noteholder.parentNode.removeChild(noteholder);
\r
693 // Process footnoterefs.
\r
694 for (i=0; i<spans.length; i++) {
\r
695 if (spans[i].className == "footnoteref") {
\r
696 var href = spans[i].getElementsByTagName("a")[0].getAttribute("href");
\r
697 href = href.match(/#.*/)[0]; // Because IE return full URL.
\r
699 spans[i].innerHTML =
\r
700 "[<a href='#_footnote_" + n +
\r
701 "' title='View footnote' class='footnote'>" + n + "</a>]";
\r
707 install: function(toclevels) {
\r
710 function reinstall() {
\r
711 asciidoc.footnotes();
\r
713 asciidoc.toc(toclevels);
\r
717 function reinstallAndRemoveTimer() {
\r
718 clearInterval(timerId);
\r
722 timerId = setInterval(reinstall, 500);
\r
723 if (document.addEventListener)
\r
724 document.addEventListener("DOMContentLoaded", reinstallAndRemoveTimer, false);
\r
726 window.onload = reinstallAndRemoveTimer;
\r
730 asciidoc.install(2);
\r
734 <body class="article">
\r
737 <span id="revnumber">version 3.4</span>
\r
739 <div id="toctitle">Table of Contents</div>
740 <noscript><p><b>JavaScript must be enabled in your browser to display the table of contents.</b></p></noscript>
744 <div class="sect1">
\r
745 <h2 id="_name">Name</h2>
\r
746 <div class="sectionbody">
\r
747 <div class="paragraph"><p>ccache - a fast C/C++ compiler cache</p></div>
\r
750 <div class="sect1">
\r
751 <h2 id="_synopsis">Synopsis</h2>
\r
752 <div class="sectionbody">
\r
753 <div class="verseblock">
\r
754 <pre class="content"><strong>ccache</strong> [<em>options</em>]
\r
755 <strong>ccache</strong> <em>compiler</em> [<em>compiler options</em>]
\r
756 <em>compiler</em> [<em>compiler options</em>] (via symbolic link)</pre>
\r
757 <div class="attribution">
\r
761 <div class="sect1">
\r
762 <h2 id="_description">Description</h2>
\r
763 <div class="sectionbody">
\r
764 <div class="paragraph"><p>ccache is a compiler cache. It speeds up recompilation by caching the result of
\r
765 previous compilations and detecting when the same compilation is being done
\r
766 again. Supported languages are C, C++, Objective-C and Objective-C++.</p></div>
\r
767 <div class="paragraph"><p>ccache has been carefully written to always produce exactly the same compiler
\r
768 output that you would get without the cache. The only way you should be able to
\r
769 tell that you are using ccache is the speed. Currently known exceptions to this
\r
770 goal are listed under <a href="#_caveats">CAVEATS</a>. If you ever discover an
\r
771 undocumented case where ccache changes the output of your compiler, please let
\r
773 <div class="sect2">
\r
774 <h3 id="_features">Features</h3>
\r
775 <div class="ulist"><ul>
\r
778 Keeps statistics on hits/misses.
\r
783 Automatic cache size management.
\r
788 Can cache compilations that generate warnings.
\r
803 Optionally compresses files in the cache to reduce disk space.
\r
808 <div class="sect2">
\r
809 <h3 id="_limitations">Limitations</h3>
\r
810 <div class="ulist"><ul>
\r
813 Only knows how to cache the compilation of a single
\r
814 C/C++/Objective-C/Objective-C++ file. Other types of compilations
\r
815 (multi-file compilation, linking, etc) will silently fall back to running the
\r
821 Only works with GCC and compilers that behave similar enough.
\r
826 Some compiler flags are not supported. If such a flag is detected, ccache
\r
827 will silently fall back to running the real compiler.
\r
834 <div class="sect1">
\r
835 <h2 id="_run_modes">Run modes</h2>
\r
836 <div class="sectionbody">
\r
837 <div class="paragraph"><p>There are two ways to use ccache. You can either prefix your compilation
\r
838 commands with <strong>ccache</strong> or you can let ccache masquerade as the compiler by
\r
839 creating a symbolic link (named as the compiler) to ccache. The first method is
\r
840 most convenient if you just want to try out ccache or wish to use it for some
\r
841 specific projects. The second method is most useful for when you wish to use
\r
842 ccache for all your compilations.</p></div>
\r
843 <div class="paragraph"><p>To use the first method, just make sure that <strong>ccache</strong> is in your <strong>PATH</strong>.</p></div>
\r
844 <div class="paragraph"><p>To use the symlinks method, do something like this:</p></div>
\r
845 <div class="listingblock">
\r
846 <div class="content">
\r
847 <pre><code>cp ccache /usr/local/bin/
\r
848 ln -s ccache /usr/local/bin/gcc
\r
849 ln -s ccache /usr/local/bin/g++
\r
850 ln -s ccache /usr/local/bin/cc
\r
851 ln -s ccache /usr/local/bin/c++</code></pre>
\r
853 <div class="paragraph"><p>And so forth. This will work as long as the directory with symlinks comes
\r
854 before the path to the compiler (which is usually in <code>/usr/bin</code>). After
\r
855 installing you may wish to run “which gcc” to make sure that the correct link
\r
856 is being used.</p></div>
\r
857 <div class="admonitionblock">
\r
860 <div class="title">Warning</div>
\r
862 <td class="content">The technique of letting ccache masquerade as the compiler works well,
\r
863 but currently doesn’t interact well with other tools that do the same thing.
\r
864 See <a href="#_using_ccache_with_other_compiler_wrappers">USING CCACHE WITH OTHER COMPILER WRAPPERS</a>.</td>
\r
867 <div class="admonitionblock">
\r
870 <div class="title">Warning</div>
\r
872 <td class="content">Do not use a hard link, use a symbolic link. A hard link will cause
\r
873 “interesting” problems.</td>
\r
878 <div class="sect1">
\r
879 <h2 id="_options">Options</h2>
\r
880 <div class="sectionbody">
\r
881 <div class="paragraph"><p>These options only apply when you invoke ccache as “ccache”. When invoked as
\r
882 a compiler (via a symlink as described in the previous section), the normal
\r
883 compiler options apply and you should refer to the compiler’s documentation.</p></div>
\r
884 <div class="dlist"><dl>
\r
885 <dt class="hdlist1">
\r
886 <strong>-c, --cleanup</strong>
\r
890 Clean up the cache by removing old cached files until the specified file
\r
891 number and cache size limits are not exceeded. This also recalculates the
\r
892 cache file count and size totals. Normally, there is no need to initiate
\r
893 cleanup manually as ccache keeps the cache below the specified limits at
\r
894 runtime and keeps statistics up to date on each compilation. Forcing a
\r
895 cleanup is mostly useful if you manually modify the cache contents or
\r
896 believe that the cache size statistics may be inaccurate.
\r
899 <dt class="hdlist1">
\r
900 <strong>-C, --clear</strong>
\r
904 Clear the entire cache, removing all cached files, but keeping the
\r
905 configuration file.
\r
908 <dt class="hdlist1">
\r
909 <strong>-F, --max-files</strong>=<em>N</em>
\r
913 Set the maximum number of files allowed in the cache. Use 0 for no limit.
\r
914 The value is stored in a configuration file in the cache directory and
\r
915 applies to all future compilations.
\r
918 <dt class="hdlist1">
\r
919 <strong>-h, --help</strong>
\r
923 Print an options summary page.
\r
926 <dt class="hdlist1">
\r
927 <strong>-M, --max-size</strong>=<em>SIZE</em>
\r
931 Set the maximum size of the files stored in the cache. <em>SIZE</em> should be a
\r
932 number followed by an optional suffix: k, M, G, T (decimal), Ki, Mi, Gi or
\r
933 Ti (binary). The default suffix is G. Use 0 for no limit. The value is
\r
934 stored in a configuration file in the cache directory and applies to all
\r
935 future compilations.
\r
938 <dt class="hdlist1">
\r
939 <strong>-o, --set-config</strong>=<em>KEY=VALUE</em>
\r
943 Set configuration <em>KEY</em> to <em>VALUE</em>. See <a href="#_configuration">CONFIGURATION</a>
\r
944 for more information.
\r
947 <dt class="hdlist1">
\r
948 <strong>-p, --print-config</strong>
\r
952 Print current configuration options and from where they originate
\r
953 (environment variable, configuration file or compile-time default).
\r
956 <dt class="hdlist1">
\r
957 <strong>-s, --show-stats</strong>
\r
961 Print the current statistics summary for the cache.
\r
964 <dt class="hdlist1">
\r
965 <strong>-V, --version</strong>
\r
969 Print version and copyright information.
\r
972 <dt class="hdlist1">
\r
973 <strong>-z, --zero-stats</strong>
\r
977 Zero the cache statistics (but not the configuration options).
\r
983 <div class="sect1">
\r
984 <h2 id="_extra_options">Extra options</h2>
\r
985 <div class="sectionbody">
\r
986 <div class="paragraph"><p>When run as a compiler, ccache usually just takes the same command line options
\r
987 as the compiler you are using. The only exception to this is the option
\r
988 <strong>--ccache-skip</strong>. That option can be used to tell ccache to avoid interpreting
\r
989 the next option in any way and to pass it along to the compiler as-is.</p></div>
\r
990 <div class="admonitionblock">
\r
993 <div class="title">Note</div>
\r
995 <td class="content"><strong>--ccache-skip</strong> currently only tells ccache not to interpret the next
\r
996 option as a special compiler option — the option will still be included in the
\r
997 direct mode hash.</td>
\r
1000 <div class="paragraph"><p>The reason this can be important is that ccache does need to parse the command
\r
1001 line and determine what is an input filename and what is a compiler option, as
\r
1002 it needs the input filename to determine the name of the resulting object file
\r
1003 (among other things). The heuristic ccache uses when parsing the command line
\r
1004 is that any argument that exists as a file is treated as an input file name. By
\r
1005 using <strong>--ccache-skip</strong> you can force an option to not be treated as an input
\r
1006 file name and instead be passed along to the compiler as a command line option.</p></div>
\r
1007 <div class="paragraph"><p>Another case where <strong>--ccache-skip</strong> can be useful is if ccache interprets an
\r
1008 option specially but shouldn’t, since the option has another meaning for your
\r
1009 compiler than what ccache thinks.</p></div>
\r
1012 <div class="sect1">
\r
1013 <h2 id="_configuration">Configuration</h2>
\r
1014 <div class="sectionbody">
\r
1015 <div class="paragraph"><p>ccache’s default behavior can be overridden by configuration file settings,
\r
1016 which in turn can be overridden by environment variables with names starting
\r
1017 with <strong>CCACHE_</strong>. ccache normally reads configuration from two files: first a
\r
1018 system-level configuration file and secondly a cache-specific configuration
\r
1019 file. The priority of configuration settings is as follows (where 1 is
\r
1020 highest):</p></div>
\r
1021 <div class="olist arabic"><ol class="arabic">
\r
1024 Environment variables.
\r
1029 The cache-specific configuration file <strong><ccachedir>/ccache.conf</strong> (typically
\r
1030 <strong>$HOME/.ccache/ccache.conf</strong>).
\r
1035 The system-wide configuration file <strong><sysconfdir>/ccache.conf</strong> (typically
\r
1036 <strong>/etc/ccache.conf</strong> or <strong>/usr/local/etc/ccache.conf</strong>).
\r
1041 Compile-time defaults.
\r
1045 <div class="paragraph"><p>As a special case, if the environment variable <strong>CCACHE_CONFIGPATH</strong> is set,
\r
1046 ccache reads configuration from the specified path instead of the default
\r
1048 <div class="sect2">
\r
1049 <h3 id="_configuration_file_syntax">Configuration file syntax</h3>
\r
1050 <div class="paragraph"><p>Configuration files are in a simple “key = value” format, one setting per
\r
1051 line. Lines starting with a hash sign are comments. Blank lines are ignored, as
\r
1052 is whitespace surrounding keys and values. Example:</p></div>
\r
1053 <div class="listingblock">
\r
1054 <div class="content">
\r
1055 <pre><code># Set maximum cache size to 10 GB:
\r
1056 max_size = 10G</code></pre>
\r
1059 <div class="sect2">
\r
1060 <h3 id="_boolean_values">Boolean values</h3>
\r
1061 <div class="paragraph"><p>Some settings are boolean values (i.e. truth values). In a configuration file,
\r
1062 such values must be set to the string <strong>true</strong> or <strong>false</strong>. For the corresponding
\r
1063 environment variables, the semantics are a bit different: a set environment
\r
1064 variable means “true” (even if set to the empty string), the following
\r
1065 case-insensitive negative values are considered an error (rather than
\r
1066 surprising the user): <strong>0</strong>, <strong>false</strong>, <strong>disable</strong> and <strong>no</strong>, and an unset
\r
1067 environment variable means “false”. Each boolean environment variable also
\r
1068 has a negated form starting with <strong>CCACHE_NO</strong>. For example, <strong>CCACHE_COMPRESS</strong>
\r
1069 can be set to force compression and <strong>CCACHE_NOCOMPRESS</strong> can be set to force no
\r
1070 compression.</p></div>
\r
1072 <div class="sect2">
\r
1073 <h3 id="_configuration_settings">Configuration settings</h3>
\r
1074 <div class="paragraph"><p>Below is a list of available configuration settings. The corresponding
\r
1075 environment variable name is indicated in parentheses after each configuration
\r
1076 setting key.</p></div>
\r
1077 <div class="dlist"><dl>
\r
1078 <dt class="hdlist1">
\r
1079 <strong>base_dir</strong> (<strong>CCACHE_BASEDIR</strong>)
\r
1083 This setting should be an absolute path to a directory. ccache then
\r
1084 rewrites absolute paths into relative paths before computing the hash that
\r
1085 identifies the compilation, but only for paths under the specified
\r
1086 directory. If set to the empty string (which is the default), no rewriting
\r
1087 is done. A typical path to use as the base directory is your home directory
\r
1088 or another directory that is a parent of your build directories. Don’t use
\r
1089 <code>/</code> as the base directory since that will make ccache also rewrite paths to
\r
1090 system header files, which doesn’t gain anything.
\r
1092 <div class="paragraph"><p>See also the discussion under <a href="#_compiling_in_different_directories">COMPILING IN DIFFERENT DIRECTORIES</a>.</p></div>
\r
1094 <dt class="hdlist1">
\r
1095 <strong>cache_dir</strong> (<strong>CCACHE_DIR</strong>)
\r
1099 This setting specifies where ccache will keep its cached compiler outputs.
\r
1100 It will only take effect if set in the system-wide configuration file or as
\r
1101 an environment variable. The default is <strong>$HOME/.ccache</strong>.
\r
1104 <dt class="hdlist1">
\r
1105 <strong>cache_dir_levels</strong> (<strong>CCACHE_NLEVELS</strong>)
\r
1109 This setting allows you to choose the number of directory levels in the
\r
1110 cache directory. The default is 2. The minimum is 1 and the maximum is 8.
\r
1113 <dt class="hdlist1">
\r
1114 <strong>compiler</strong> (<strong>CCACHE_CC</strong>)
\r
1118 This setting can be used to force the name of the compiler to use. If set
\r
1119 to the empty string (which is the default), ccache works it out from the
\r
1123 <dt class="hdlist1">
\r
1124 <strong>compiler_check</strong> (<strong>CCACHE_COMPILERCHECK</strong>)
\r
1128 By default, ccache includes the modification time (“mtime”) and size of
\r
1129 the compiler in the hash to ensure that results retrieved from the cache
\r
1130 are accurate. This setting can be used to select another strategy. Possible
\r
1133 <div class="openblock">
\r
1134 <div class="content">
\r
1135 <div class="dlist"><dl>
\r
1136 <dt class="hdlist1">
\r
1137 <strong>content</strong>
\r
1141 Hash the content of the compiler binary. This makes ccache very slightly
\r
1142 slower compared to the <strong>mtime</strong> setting, but makes it cope better with
\r
1143 compiler upgrades during a build bootstrapping process.
\r
1146 <dt class="hdlist1">
\r
1147 <strong>mtime</strong>
\r
1151 Hash the compiler’s mtime and size, which is fast. This is the default.
\r
1154 <dt class="hdlist1">
\r
1155 <strong>none</strong>
\r
1159 Don’t hash anything. This may be good for situations where you can safely
\r
1160 use the cached results even though the compiler’s mtime or size has changed
\r
1161 (e.g. if the compiler is built as part of your build system and the
\r
1162 compiler’s source has not changed, or if the compiler only has changes that
\r
1163 don’t affect code generation). You should only use the <strong>none</strong> setting if
\r
1164 you know what you are doing.
\r
1167 <dt class="hdlist1">
\r
1168 <strong>string:value</strong>
\r
1172 Use <strong>value</strong> as the string to calculate hash from. This can be the compiler
\r
1173 revision number you retrieved earlier and set here via environment variable.
\r
1176 <dt class="hdlist1">
\r
1177 <em>a command string</em>
\r
1181 Hash the standard output and standard error output of the specified
\r
1182 command. The string will be split on whitespace to find out the command and
\r
1183 arguments to run. No other interpretation of the command string will be
\r
1184 done, except that the special word <strong>%compiler%</strong> will be replaced with the
\r
1185 path to the compiler. Several commands can be specified with semicolon as
\r
1186 separator. Examples:
\r
1188 <div class="openblock">
\r
1189 <div class="content">
\r
1190 <div class="listingblock">
\r
1191 <div class="content">
\r
1192 <pre><code>%compiler% -v</code></pre>
\r
1194 <div class="listingblock">
\r
1195 <div class="content">
\r
1196 <pre><code>%compiler% -dumpmachine; %compiler% -dumpversion</code></pre>
\r
1198 <div class="paragraph"><p>You should make sure that the specified command is as fast as possible since it
\r
1199 will be run once for each ccache invocation.</p></div>
\r
1200 <div class="paragraph"><p>Identifying the compiler using a command is useful if you want to avoid cache
\r
1201 misses when the compiler has been rebuilt but not changed.</p></div>
\r
1202 <div class="paragraph"><p>Another case is when the compiler (as seen by ccache) actually isn’t the real
\r
1203 compiler but another compiler wrapper — in that case, the default <strong>mtime</strong>
\r
1204 method will hash the mtime and size of the other compiler wrapper, which means
\r
1205 that ccache won’t be able to detect a compiler upgrade. Using a suitable
\r
1206 command to identify the compiler is thus safer, but it’s also slower, so you
\r
1207 should consider continue using the <strong>mtime</strong> method in combination with
\r
1208 the <strong>prefix_command</strong> setting if possible. See
\r
1209 <a href="#_using_ccache_with_other_compiler_wrappers">USING CCACHE WITH OTHER COMPILER WRAPPERS</a>.</p></div>
\r
1215 <dt class="hdlist1">
\r
1216 <strong>compression</strong> (<strong>CCACHE_COMPRESS</strong> or <strong>CCACHE_NOCOMPRESS</strong>, see <a href="#_boolean_values">Boolean values</a> above)
\r
1220 If true, ccache will compress object files and other compiler output it
\r
1221 puts in the cache. However, this setting has no effect on how files are
\r
1222 retrieved from the cache; compressed and uncompressed results will still be
\r
1223 usable regardless of this setting. The default is false.
\r
1226 <dt class="hdlist1">
\r
1227 <strong>compression_level</strong> (<strong>CCACHE_COMPRESSLEVEL</strong>)
\r
1231 This setting determines the level at which ccache will compress object
\r
1232 files. It only has effect if <strong>compression</strong> is enabled. The value defaults
\r
1233 to 6, and must be no lower than 1 (fastest, worst compression) and no
\r
1234 higher than 9 (slowest, best compression).
\r
1237 <dt class="hdlist1">
\r
1238 <strong>cpp_extension</strong> (<strong>CCACHE_EXTENSION</strong>)
\r
1242 This setting can be used to force a certain extension for the intermediate
\r
1243 preprocessed file. The default is to automatically determine the extension
\r
1244 to use for intermediate preprocessor files based on the type of file being
\r
1245 compiled, but that sometimes doesn’t work. For example, when using the
\r
1246 “aCC” compiler on HP-UX, set the cpp extension to <strong>i</strong>.
\r
1249 <dt class="hdlist1">
\r
1250 <strong>direct_mode</strong> (<strong>CCACHE_DIRECT</strong> or <strong>CCACHE_NODIRECT</strong>, see <a href="#_boolean_values">Boolean values</a> above)
\r
1254 If true, the direct mode will be used. The default is true. See
\r
1255 <a href="#_the_direct_mode">THE DIRECT MODE</a>.
\r
1258 <dt class="hdlist1">
\r
1259 <strong>disable</strong> (<strong>CCACHE_DISABLE</strong> or <strong>CCACHE_NODISABLE</strong>, see <a href="#_boolean_values">Boolean values</a> above)
\r
1263 When true, ccache will just call the real compiler, bypassing the cache
\r
1264 completely. The default is false.
\r
1267 <dt class="hdlist1">
\r
1268 <strong>extra_files_to_hash</strong> (<strong>CCACHE_EXTRAFILES</strong>)
\r
1272 This setting is a list of paths to files that ccache will include in the
\r
1273 the hash sum that identifies the build. The list separator is semicolon on
\r
1274 Windows systems and colon on other systems.
\r
1277 <dt class="hdlist1">
\r
1278 <strong>hard_link</strong> (<strong>CCACHE_HARDLINK</strong> or <strong>CCACHE_NOHARDLINK</strong>, see <a href="#_boolean_values">Boolean values</a> above)
\r
1282 If true, ccache will attempt to use hard links from the cache directory
\r
1283 when creating the compiler output rather than using a file copy. Hard links
\r
1284 are never made for compressed cache files. This means that you should not
\r
1285 enable compression if you want to use hard links. The default is false.
\r
1287 <div class="admonitionblock">
\r
1290 <div class="title">Warning</div>
\r
1292 <td class="content">Do not enable this option unless you are aware of the consequences.
\r
1293 Using hard links may be slightly faster in some situations, but there are
\r
1294 several pitfalls since the resulting object file will share i-node with the
\r
1295 cached object file:</td>
\r
1298 <div class="olist arabic"><ol class="arabic">
\r
1301 If the resulting object file is modified in any way, the cached object file
\r
1302 will be modified as well. For instance, if you run <strong>strip object.o</strong> or <strong>echo
\r
1303 >object.o</strong>, you will corrupt the cache.
\r
1308 Programs that rely on modification times (like “make”) can be confused
\r
1309 since ccache updates the cached files' modification times as part of the
\r
1310 automatic cache size management. This will affect object files in the build
\r
1311 tree as well, which can retrigger the linking step even though nothing
\r
1312 really has changed.
\r
1317 <dt class="hdlist1">
\r
1318 <strong>hash_dir</strong> (<strong>CCACHE_HASHDIR</strong> or <strong>CCACHE_NOHASHDIR</strong>, see <a href="#_boolean_values">Boolean values</a> above)
\r
1322 If true (which is the default), ccache will include the current working
\r
1323 directory (CWD) in the hash that is used to distinguish two compilations
\r
1324 when generating debug info (compiler option <strong>-g</strong> with variations).
\r
1325 Exception: The CWD will not be included in the hash if <strong>base_dir</strong> is set
\r
1326 (and matches the CWD) and the compiler option <strong>-fdebug-prefix-map</strong> is used.
\r
1327 See also the discussion under
\r
1328 <a href="#_compiling_in_different_directories">COMPILING IN DIFFERENT DIRECTORIES</a>.
\r
1330 <div class="paragraph"><p>The reason for including the CWD in the hash by default is to prevent a problem
\r
1331 with the storage of the current working directory in the debug info of an
\r
1332 object file, which can lead ccache to return a cached object file that has the
\r
1333 working directory in the debug info set incorrectly.</p></div>
\r
1334 <div class="paragraph"><p>You can disable this setting to get cache hits when compiling the same source
\r
1335 code in different directories if you don’t mind that CWD in the debug info
\r
1336 might be incorrect.</p></div>
\r
1338 <dt class="hdlist1">
\r
1339 <strong>ignore_headers_in_manifest</strong> (<strong>CCACHE_IGNOREHEADERS</strong>)
\r
1343 This setting is a list of paths to files (or directories with headers) that
\r
1344 ccache will <strong>not</strong> include in the manifest list that makes up the direct
\r
1345 mode. Note that this can cause stale cache hits if those headers do indeed
\r
1346 change. The list separator is semicolon on Windows systems and colon on
\r
1350 <dt class="hdlist1">
\r
1351 <strong>keep_comments_cpp</strong> (<strong>CCACHE_COMMENTS</strong> or <strong>CCACHE_NOCOMMENTS</strong>, see <a href="#_boolean_values">Boolean values</a> above)
\r
1355 If true, ccache will not discard the comments before hashing preprocessor
\r
1356 output. This can be used to check documentation with <strong>-Wdocumentation</strong>.
\r
1359 <dt class="hdlist1">
\r
1360 <strong>limit_multiple</strong> (<strong>CCACHE_LIMIT_MULTIPLE</strong>)
\r
1364 Sets the limit when cleaning up. Files are deleted (in LRU order) until the
\r
1365 levels are below the limit. The default is 0.8 (= 80%). See
\r
1366 <a href="#_automatic_cleanup">AUTOMATIC CLEANUP</a> for more information.
\r
1369 <dt class="hdlist1">
\r
1370 <strong>log_file</strong> (<strong>CCACHE_LOGFILE</strong>)
\r
1374 If set to a file path, ccache will write information on what it is doing to
\r
1375 the specified file. This is useful for tracking down problems.
\r
1378 <dt class="hdlist1">
\r
1379 <strong>max_files</strong> (<strong>CCACHE_MAXFILES</strong>)
\r
1383 This option specifies the maximum number of files to keep in the cache. Use
\r
1384 0 for no limit (which is the default). See also
\r
1385 <a href="#_cache_size_management">CACHE SIZE MANAGEMENT</a>.
\r
1388 <dt class="hdlist1">
\r
1389 <strong>max_size</strong> (<strong>CCACHE_MAXSIZE</strong>)
\r
1393 This option specifies the maximum size of the cache. Use 0 for no limit.
\r
1394 The default value is 5G. Available suffixes: k, M, G, T (decimal) and Ki,
\r
1395 Mi, Gi, Ti (binary). The default suffix is "G". See also
\r
1396 <a href="#_cache_size_management">CACHE SIZE MANAGEMENT</a>.
\r
1399 <dt class="hdlist1">
\r
1400 <strong>path</strong> (<strong>CCACHE_PATH</strong>)
\r
1404 If set, ccache will search directories in this list when looking for the
\r
1405 real compiler. The list separator is semicolon on Windows systems and colon
\r
1406 on other systems. If not set, ccache will look for the first executable
\r
1407 matching the compiler name in the normal <strong>PATH</strong> that isn’t a symbolic link
\r
1411 <dt class="hdlist1">
\r
1412 <strong>prefix_command</strong> (<strong>CCACHE_PREFIX</strong>)
\r
1416 This option adds a list of prefixes (separated by space) to the command
\r
1417 line that ccache uses when invoking the compiler. See also
\r
1418 <a href="#_using_ccache_with_other_compiler_wrappers">USING CCACHE WITH OTHER COMPILER WRAPPERS</a>.
\r
1421 <dt class="hdlist1">
\r
1422 <strong>prefix_command_cpp</strong> (<strong>CCACHE_PREFIX_CPP</strong>)
\r
1426 This option adds a list of prefixes (separated by space) to the command
\r
1427 line that ccache uses when invoking the preprocessor.
\r
1430 <dt class="hdlist1">
\r
1431 <strong>read_only</strong> (<strong>CCACHE_READONLY</strong> or <strong>CCACHE_NOREADONLY</strong>, see <a href="#_boolean_values">Boolean values</a> above)
\r
1435 If true, ccache will attempt to use existing cached object files, but it
\r
1436 will not to try to add anything new to the cache. If you are using this
\r
1437 because your ccache directory is read-only, then you need to set
\r
1438 <strong>temporary_dir</strong> as otherwise ccache will fail to create temporary files.
\r
1441 <dt class="hdlist1">
\r
1442 <strong>read_only_direct</strong> (<strong>CCACHE_READONLY_DIRECT</strong> or <strong>CCACHE_NOREADONLY_DIRECT</strong>, see <a href="#_boolean_values">Boolean values</a> above)
\r
1446 Just like <strong>read_only</strong> except that ccache will only try to retrieve results
\r
1447 from the cache using the direct mode, not the preprocessor mode. See
\r
1448 documentation for <strong>read_only</strong> regarding using a read-only ccache directory.
\r
1451 <dt class="hdlist1">
\r
1452 <strong>recache</strong> (<strong>CCACHE_RECACHE</strong> or <strong>CCACHE_NORECACHE</strong>, see <a href="#_boolean_values">Boolean values</a> above)
\r
1456 If true, ccache will not use any previously stored result. New results will
\r
1457 still be cached, possibly overwriting any pre-existing results.
\r
1460 <dt class="hdlist1">
\r
1461 <strong>run_second_cpp</strong> (<strong>CCACHE_CPP2</strong> or <strong>CCACHE_NOCPP2</strong>, see <a href="#_boolean_values">Boolean values</a> above)
\r
1465 If true, ccache will first run the preprocessor to preprocess the source
\r
1466 code (see <a href="#_the_preprocessor_mode">THE PREPROCESSOR MODE</a>) and then on a
\r
1467 cache miss run the compiler on the source code to get hold of the object
\r
1468 file. This is the default.
\r
1470 <div class="paragraph"><p>If false, ccache will first run preprocessor to preprocess the source code and
\r
1471 then on a cache miss run the compiler on the <em>preprocessed source code</em> instead
\r
1472 of the original source code. This makes cache misses slightly faster since the
\r
1473 source code only has to be preprocessed once. The downside is that some
\r
1474 compilers won’t produce the same result (for instance diagnostics warnings)
\r
1475 when compiling preprocessed source code.</p></div>
\r
1476 <div class="paragraph"><p>A solution to the above mentioned downside is to set <strong>run_second_cpp</strong> to false
\r
1477 and pass <strong>-fdirectives-only</strong> (for GCC) or <strong>-frewrite-includes</strong> (for Clang) to
\r
1478 the compiler. This will cause the compiler to leave the macros and other
\r
1479 preprocessor information, and only process the <strong>#include</strong> directives. When run
\r
1480 in this way, the preprocessor arguments will be passed to the compiler since it
\r
1481 still has to do <em>some</em> preprocessing (like macros).</p></div>
\r
1483 <dt class="hdlist1">
\r
1484 <strong>sloppiness</strong> (<strong>CCACHE_SLOPPINESS</strong>)
\r
1488 By default, ccache tries to give as few false cache hits as possible.
\r
1489 However, in certain situations it’s possible that you know things that
\r
1490 ccache can’t take for granted. This setting makes it possible to tell
\r
1491 ccache to relax some checks in order to increase the hit rate. The value
\r
1492 should be a comma-separated string with options. Available options are:
\r
1494 <div class="openblock">
\r
1495 <div class="content">
\r
1496 <div class="dlist"><dl>
\r
1497 <dt class="hdlist1">
\r
1498 <strong>file_macro</strong>
\r
1502 Ignore <strong>__FILE__</strong> being present in the source.
\r
1505 <dt class="hdlist1">
\r
1506 <strong>file_stat_matches</strong>
\r
1510 ccache normally examines a file’s contents to determine whether it matches
\r
1511 the cached version. With this option set, ccache will consider a file as
\r
1512 matching its cached version if the mtimes and ctimes match.
\r
1515 <dt class="hdlist1">
\r
1516 <strong>include_file_ctime</strong>
\r
1520 By default, ccache also will not cache a file if it includes a header whose
\r
1521 ctime is too new. This option disables that check.
\r
1524 <dt class="hdlist1">
\r
1525 <strong>include_file_mtime</strong>
\r
1529 By default, ccache will not cache a file if it includes a header whose
\r
1530 mtime is too new. This option disables that check.
\r
1533 <dt class="hdlist1">
\r
1534 <strong>no_system_headers</strong>
\r
1538 By default, ccache will also include all system headers in the manifest.
\r
1539 With this option set, ccache will only include system headers in the hash
\r
1540 but not add the system header files to the list of include files.
\r
1543 <dt class="hdlist1">
\r
1544 <strong>pch_defines</strong>
\r
1548 Be sloppy about <strong>#define</strong>s when precompiling a header file. See
\r
1549 <a href="#_precompiled_headers">PRECOMPILED HEADERS</a> for more information.
\r
1552 <dt class="hdlist1">
\r
1553 <strong>time_macros</strong>
\r
1557 Ignore <strong>__DATE__</strong> and <strong>__TIME__</strong> being present in the source code.
\r
1562 <div class="paragraph"><p>See the discussion under <a href="#_troubleshooting">TROUBLESHOOTING</a> for more
\r
1563 information.</p></div>
\r
1565 <dt class="hdlist1">
\r
1566 <strong>stats</strong> (<strong>CCACHE_STATS</strong> or <strong>CCACHE_NOSTATS</strong>, see <a href="#_boolean_values">Boolean values</a> above)
\r
1570 If true, ccache will update the statistics counters on each compilation.
\r
1571 The default is true.
\r
1574 <dt class="hdlist1">
\r
1575 <strong>temporary_dir</strong> (<strong>CCACHE_TEMPDIR</strong>)
\r
1579 This setting specifies where ccache will put temporary files. The default
\r
1580 is <strong><cache_dir>/tmp</strong>.
\r
1582 <div class="admonitionblock">
\r
1585 <div class="title">Note</div>
\r
1587 <td class="content">In previous versions of ccache, <strong>CCACHE_TEMPDIR</strong> had to be on the same
\r
1588 filesystem as the <strong>CCACHE_DIR</strong> path, but this requirement has been
\r
1593 <dt class="hdlist1">
\r
1594 <strong>umask</strong> (<strong>CCACHE_UMASK</strong>)
\r
1598 This setting specifies the umask for ccache and all child processes (such
\r
1599 as the compiler). This is mostly useful when you wish to share your cache
\r
1600 with other users. Note that this also affects the file permissions set on
\r
1601 the object files created from your compilations.
\r
1604 <dt class="hdlist1">
\r
1605 <strong>unify</strong> (<strong>CCACHE_UNIFY</strong> or <strong>CCACHE_NOUNIFY</strong>, see <a href="#_boolean_values">Boolean values</a> above)
\r
1609 If true, ccache will use a C/C++ unifier when hashing the preprocessor
\r
1610 output if the <strong>-g</strong> option is not used. The unifier is slower than a normal
\r
1611 hash, so setting this environment variable loses a little bit of speed, but
\r
1612 it means that ccache can take advantage of not recompiling when the changes
\r
1613 to the source code consist of reformatting only. Note that enabling the
\r
1614 unifier changes the hash, so cached compilations produced when the unifier
\r
1615 is enabled cannot be reused when the unifier is disabled, and vice versa.
\r
1616 Enabling the unifier may result in incorrect line number information in
\r
1617 compiler warning messages and expansions of the <strong>__LINE__</strong> macro.
\r
1624 <div class="sect1">
\r
1625 <h2 id="_cache_size_management">Cache size management</h2>
\r
1626 <div class="sectionbody">
\r
1627 <div class="paragraph"><p>By default, ccache has a 5 GB limit on the total size of files in the cache and
\r
1628 no limit on the number of files. You can set different limits using the
\r
1629 <strong>-M</strong>/<strong>--max-size</strong> and <strong>-F</strong>/<strong>--max-files</strong> options. Use <strong>ccache -s/--show-stats</strong>
\r
1630 to see the cache size and the currently configured limits (in addition to other
\r
1631 various statistics).</p></div>
\r
1632 <div class="paragraph"><p>Cleanup can be triggered in two different ways: automatic and manual.</p></div>
\r
1633 <div class="sect2">
\r
1634 <h3 id="_automatic_cleanup">Automatic cleanup</h3>
\r
1635 <div class="paragraph"><p>ccache maintains counters for various statistics about the cache, including the
\r
1636 size and number of all cached files. In order to improve performance and reduce
\r
1637 issues with concurrent ccache invocations, there is one statistics file for
\r
1638 each of the sixteen subdirectories in the cache.</p></div>
\r
1639 <div class="paragraph"><p>After a new compilation result has been written to the cache, ccache will
\r
1640 update the size and file number statistics for the subdirectory (one of
\r
1641 sixteen) to which the result was written. Then, if the size counter for said
\r
1642 subdirectory is greater than <strong>max_size / 16</strong> or the file number counter is
\r
1643 greater than <strong>max_files / 16</strong>, automatic cleanup is triggered.</p></div>
\r
1644 <div class="paragraph"><p>When automatic cleanup is triggered for a subdirectory in the cache, ccache
\r
1646 <div class="olist arabic"><ol class="arabic">
\r
1649 Count all files in the subdirectory and compute their aggregated size.
\r
1654 Remove files in LRU (least recently used) order until the size is at most
\r
1655 <strong>limit_multiple * max_size / 16</strong> and the number of files is at most
\r
1656 <strong>limit_multiple * max_files / 16</strong>, where <strong>limit_multiple</strong>, <strong>max_size</strong> and
\r
1657 <strong>max_files</strong> are configuration settings.
\r
1662 Set the size and file number counters to match the files that were kept.
\r
1666 <div class="paragraph"><p>The reason for removing more files than just those needed to not exceed the max
\r
1667 limits is that a cleanup is a fairly slow operation, so it would not be a good
\r
1668 idea to trigger it often, like after each cache miss.</p></div>
\r
1670 <div class="sect2">
\r
1671 <h3 id="_manual_cleanup">Manual cleanup</h3>
\r
1672 <div class="paragraph"><p>You can run <strong>ccache -c/--cleanup</strong> to force cleanup of the whole cache, i.e. all
\r
1673 of the sixteen subdirectories. This will recalculate the statistics counters
\r
1674 and make sure that the <strong>max_size</strong> and <strong>max_files</strong> settings are not exceeded.
\r
1675 Note that <strong>limit_multiple</strong> is not taken into account for manual cleanup.</p></div>
\r
1679 <div class="sect1">
\r
1680 <h2 id="_cache_compression">Cache compression</h2>
\r
1681 <div class="sectionbody">
\r
1682 <div class="paragraph"><p>ccache can optionally compress all files it puts into the cache using the
\r
1683 compression library zlib. While this may involve a tiny performance slowdown,
\r
1684 it increases the number of files that fit in the cache. You can turn on
\r
1685 compression with the <strong>compression</strong> configuration setting and you can also tweak
\r
1686 the compression level with <strong>compression_level</strong>.</p></div>
\r
1689 <div class="sect1">
\r
1690 <h2 id="_cache_statistics">Cache statistics</h2>
\r
1691 <div class="sectionbody">
\r
1692 <div class="paragraph"><p><strong>ccache -s/--show-stats</strong> can show the following statistics:</p></div>
\r
1693 <div class="tableblock">
\r
1694 <table rules="all"
\r
1697 cellspacing="0" cellpadding="4">
\r
1698 <col width="30%" />
\r
1699 <col width="70%" />
\r
1702 <th align="left" valign="top">Name </th>
\r
1703 <th align="left" valign="top"> Description</th>
\r
1708 <td align="left" valign="top"><p class="table">autoconf compile/link</p></td>
\r
1709 <td align="left" valign="top"><p class="table">Uncachable compilation or linking by an autoconf test.</p></td>
\r
1712 <td align="left" valign="top"><p class="table">bad compiler arguments</p></td>
\r
1713 <td align="left" valign="top"><p class="table">Malformed compiler argument, e.g. missing a value for an option that requires
\r
1714 an argument or failure to read a file specified by an option argument.</p></td>
\r
1717 <td align="left" valign="top"><p class="table">cache file missing</p></td>
\r
1718 <td align="left" valign="top"><p class="table">A file was unexpectedly missing from the cache. This only happens in rare
\r
1719 situations, e.g. if one ccache instance is about to get a file from the cache
\r
1720 while another instance removed the file as part of cache cleanup.</p></td>
\r
1723 <td align="left" valign="top"><p class="table">cache hit (direct)</p></td>
\r
1724 <td align="left" valign="top"><p class="table">A result was successfully found using <a href="#_the_direct_mode">the direct mode</a>.</p></td>
\r
1727 <td align="left" valign="top"><p class="table">cache hit (preprocessed)</p></td>
\r
1728 <td align="left" valign="top"><p class="table">A result was successfully found using <a href="#_the_preprocessor_mode">the preprocessor mode</a>.</p></td>
\r
1731 <td align="left" valign="top"><p class="table">cache miss</p></td>
\r
1732 <td align="left" valign="top"><p class="table">No result was found.</p></td>
\r
1735 <td align="left" valign="top"><p class="table">cache size</p></td>
\r
1736 <td align="left" valign="top"><p class="table">Current size of the cache.</p></td>
\r
1739 <td align="left" valign="top"><p class="table">called for link</p></td>
\r
1740 <td align="left" valign="top"><p class="table">The compiler was called for linking, not compiling.</p></td>
\r
1743 <td align="left" valign="top"><p class="table">called for preprocessing</p></td>
\r
1744 <td align="left" valign="top"><p class="table">The compiler was called for preprocessing, not compiling.</p></td>
\r
1747 <td align="left" valign="top"><p class="table">can’t use precompiled header</p></td>
\r
1748 <td align="left" valign="top"><p class="table">Preconditions for using <a href="#_precompiled_headers">precompiled headers</a> were not
\r
1749 fulfilled.</p></td>
\r
1752 <td align="left" valign="top"><p class="table">ccache internal error</p></td>
\r
1753 <td align="left" valign="top"><p class="table">Unexpected failure, e.g. due to problems reading/writing the cache.</p></td>
\r
1756 <td align="left" valign="top"><p class="table">cleanups performed</p></td>
\r
1757 <td align="left" valign="top"><p class="table">Number of cleanups performed, either implicitly due to the cache size limit
\r
1758 being reached or due to explicit <strong>ccache -c/--cleanup</strong> calls.</p></td>
\r
1761 <td align="left" valign="top"><p class="table">compile failed</p></td>
\r
1762 <td align="left" valign="top"><p class="table">The compilation failed. No result stored in the cache.</p></td>
\r
1765 <td align="left" valign="top"><p class="table">compiler check failed</p></td>
\r
1766 <td align="left" valign="top"><p class="table">A compiler check program specified by <strong>compiler_check</strong> (<strong>CCACHE_COMPILERCHECK</strong>)
\r
1770 <td align="left" valign="top"><p class="table">compiler produced empty output</p></td>
\r
1771 <td align="left" valign="top"><p class="table">The compiler’s output file (typically an object file) was empty after
\r
1772 compilation.</p></td>
\r
1775 <td align="left" valign="top"><p class="table">compiler produced no output</p></td>
\r
1776 <td align="left" valign="top"><p class="table">The compiler’s output file (typically an object file) was missing after
\r
1777 compilation.</p></td>
\r
1780 <td align="left" valign="top"><p class="table">compiler produced stdout</p></td>
\r
1781 <td align="left" valign="top"><p class="table">The compiler wrote data to standard output. This is something that compilers
\r
1782 normally never do, so ccache is not designed to store such output in the cache.</p></td>
\r
1785 <td align="left" valign="top"><p class="table">couldn’t find the compiler</p></td>
\r
1786 <td align="left" valign="top"><p class="table">The compiler to execute could not be found.</p></td>
\r
1789 <td align="left" valign="top"><p class="table">error hashing extra file</p></td>
\r
1790 <td align="left" valign="top"><p class="table">Failure reading a file specified by <strong>extra_files_to_hash</strong>
\r
1791 (<strong>CCACHE_EXTRAFILES</strong>).</p></td>
\r
1794 <td align="left" valign="top"><p class="table">files in cache</p></td>
\r
1795 <td align="left" valign="top"><p class="table">Current number of files in the cache.</p></td>
\r
1798 <td align="left" valign="top"><p class="table">multiple source files</p></td>
\r
1799 <td align="left" valign="top"><p class="table">The compiler was called to compile multiple source files in one go. This is not
\r
1800 supported by ccache.</p></td>
\r
1803 <td align="left" valign="top"><p class="table">no input file</p></td>
\r
1804 <td align="left" valign="top"><p class="table">No input file was specified to the compiler.</p></td>
\r
1807 <td align="left" valign="top"><p class="table">output to a non-regular file</p></td>
\r
1808 <td align="left" valign="top"><p class="table">The output path specified with <strong>-o</strong> is not a file (e.g. a directory or a device
\r
1812 <td align="left" valign="top"><p class="table">output to stdout</p></td>
\r
1813 <td align="left" valign="top"><p class="table">The compiler was instructed to write its output to standard output using <strong>-o
\r
1814 -</strong>. This is not supported by ccache.</p></td>
\r
1817 <td align="left" valign="top"><p class="table">preprocessor error</p></td>
\r
1818 <td align="left" valign="top"><p class="table">Preprocessing the source code using the compiler’s <strong>-E</strong> option failed.</p></td>
\r
1821 <td align="left" valign="top"><p class="table">unsupported code directive</p></td>
\r
1822 <td align="left" valign="top"><p class="table">Code like the assembler “.incbin” directive was found. This is not supported
\r
1823 by ccache.</p></td>
\r
1826 <td align="left" valign="top"><p class="table">unsupported compiler option</p></td>
\r
1827 <td align="left" valign="top"><p class="table">A compiler option not supported by ccache was found.</p></td>
\r
1830 <td align="left" valign="top"><p class="table">unsupported source language</p></td>
\r
1831 <td align="left" valign="top"><p class="table">A source language e.g. specified with <strong>-x</strong> was unsupported by ccache.</p></td>
\r
1838 <div class="sect1">
\r
1839 <h2 id="_how_ccache_works">How ccache works</h2>
\r
1840 <div class="sectionbody">
\r
1841 <div class="paragraph"><p>The basic idea is to detect when you are compiling exactly the same code a
\r
1842 second time and reuse the previously produced output. The detection is done by
\r
1843 hashing different kinds of information that should be unique for the
\r
1844 compilation and then using the hash sum to identify the cached output. ccache
\r
1845 uses MD4, a very fast cryptographic hash algorithm, for the hashing. (MD4 is
\r
1846 nowadays too weak to be useful in cryptographic contexts, but it should be safe
\r
1847 enough to be used to identify recompilations.) On a cache hit, ccache is able
\r
1848 to supply all of the correct compiler outputs (including all warnings,
\r
1849 dependency file, etc) from the cache.</p></div>
\r
1850 <div class="paragraph"><p>ccache has two ways of doing the detection:</p></div>
\r
1851 <div class="ulist"><ul>
\r
1854 the <strong>direct mode</strong>, where ccache hashes the source code and include files
\r
1860 the <strong>preprocessor mode</strong>, where ccache runs the preprocessor on the source
\r
1861 code and hashes the result
\r
1865 <div class="paragraph"><p>The direct mode is generally faster since running the preprocessor has some
\r
1866 overhead.</p></div>
\r
1867 <div class="sect2">
\r
1868 <h3 id="_common_hashed_information">Common hashed information</h3>
\r
1869 <div class="paragraph"><p>For both modes, the following information is included in the hash:</p></div>
\r
1870 <div class="ulist"><ul>
\r
1873 the extension used by the compiler for a file with preprocessor output
\r
1874 (normally <strong>.i</strong> for C code and <strong>.ii</strong> for C++ code)
\r
1879 the compiler’s size and modification time (or other compiler-specific
\r
1880 information specified by the <strong>compiler_check</strong> setting)
\r
1885 the name of the compiler
\r
1890 the current directory (if the <strong>hash_dir</strong> setting is enabled)
\r
1895 contents of files specified by the <strong>extra_files_to_hash</strong> setting (if any)
\r
1900 <div class="sect2">
\r
1901 <h3 id="_the_direct_mode">The direct mode</h3>
\r
1902 <div class="paragraph"><p>In the direct mode, the hash is formed of the common information and:</p></div>
\r
1903 <div class="ulist"><ul>
\r
1906 the input source file
\r
1911 the command line options
\r
1915 <div class="paragraph"><p>Based on the hash, a data structure called “manifest” is looked up in the
\r
1916 cache. The manifest contains:</p></div>
\r
1917 <div class="ulist"><ul>
\r
1920 references to cached compilation results (object file, dependency file, etc)
\r
1921 that were produced by previous compilations that matched the hash
\r
1926 paths to the include files that were read at the time the compilation results
\r
1927 were stored in the cache
\r
1932 hash sums of the include files at the time the compilation results were
\r
1933 stored in the cache
\r
1937 <div class="paragraph"><p>The current contents of the include files are then hashed and compared to the
\r
1938 information in the manifest. If there is a match, ccache knows the result of
\r
1939 the compilation. If there is no match, ccache falls back to running the
\r
1940 preprocessor. The output from the preprocessor is parsed to find the include
\r
1941 files that were read. The paths and hash sums of those include files are then
\r
1942 stored in the manifest along with information about the produced compilation
\r
1944 <div class="paragraph"><p>There is a catch with the direct mode: header files that were used by the
\r
1945 compiler are recorded, but header files that were <strong>not</strong> used, but would have
\r
1946 been used if they existed, are not. So, when ccache checks if a result can be
\r
1947 taken from the cache, it currently can’t check if the existence of a new header
\r
1948 file should invalidate the result. In practice, the direct mode is safe to use
\r
1949 in the absolute majority of cases.</p></div>
\r
1950 <div class="paragraph"><p>The direct mode will be disabled if any of the following holds:</p></div>
\r
1951 <div class="ulist"><ul>
\r
1954 the configuration setting <strong>direct_mode</strong> is false
\r
1959 a modification time of one of the include files is too new (needed to avoid a
\r
1965 a compiler option not supported by the direct mode is used:
\r
1967 <div class="ulist"><ul>
\r
1970 a <strong>-Wp,<em>X</em></strong> compiler option other than <strong>-Wp,-MD,<em>path</em></strong>,
\r
1971 <strong>-Wp,-MMD,<em>path</em></strong> and <strong>-Wp,-D_define_</strong>
\r
1976 <strong>-Xpreprocessor</strong>
\r
1983 the string “__TIME__” is present in the source code
\r
1988 <div class="sect2">
\r
1989 <h3 id="_the_preprocessor_mode">The preprocessor mode</h3>
\r
1990 <div class="paragraph"><p>In the preprocessor mode, the hash is formed of the common information and:</p></div>
\r
1991 <div class="ulist"><ul>
\r
1994 the preprocessor output from running the compiler with <strong>-E</strong>
\r
1999 the command line options except options that affect include files (<strong>-I</strong>,
\r
2000 <strong>-include</strong>, <strong>-D</strong>, etc; the theory is that these options will change the
\r
2001 preprocessor output if they have any effect at all)
\r
2006 any standard error output generated by the preprocessor
\r
2010 <div class="paragraph"><p>Based on the hash, the cached compilation result can be looked up directly in
\r
2011 the cache.</p></div>
\r
2015 <div class="sect1">
\r
2016 <h2 id="_compiling_in_different_directories">Compiling in different directories</h2>
\r
2017 <div class="sectionbody">
\r
2018 <div class="paragraph"><p>Some information included in the hash that identifies a unique compilation can
\r
2019 contain absolute paths:</p></div>
\r
2020 <div class="ulist"><ul>
\r
2023 The preprocessed source code may contain absolute paths to include files if
\r
2024 the compiler option <strong>-g</strong> is used or if absolute paths are given to <strong>-I</strong> and
\r
2025 similar compiler options.
\r
2030 Paths specified by compiler options (such as <strong>-I</strong>, <strong>-MF</strong>, etc) on the command
\r
2031 line may be absolute.
\r
2036 The source code file path may be absolute, and that path may substituted for
\r
2037 <strong>__FILE__</strong> macros in the source code or included in warnings emitted to
\r
2038 standard error by the preprocessor.
\r
2042 <div class="paragraph"><p>This means that if you compile the same code in different locations, you can’t
\r
2043 share compilation results between the different build directories since you get
\r
2044 cache misses because of the absolute build directory paths that are part of the
\r
2046 <div class="paragraph"><p>Here’s what can be done to enable cache hits between different build
\r
2047 directories:</p></div>
\r
2048 <div class="ulist"><ul>
\r
2051 If you build with <strong>-g</strong> (or similar) to add debug information to the object
\r
2052 file, you must either:
\r
2054 <div class="openblock">
\r
2055 <div class="content">
\r
2056 <div class="ulist"><ul>
\r
2059 use the <strong>-fdebug-prefix-map=<em>old</em>=<em>new</em></strong> option for relocating debug info to
\r
2060 a common prefix (e.g. <strong>-fdebug-prefix-map=$PWD=.</strong>); or
\r
2065 set <strong>hash_dir = false</strong>.
\r
2073 If you use absolute paths anywhere on the command line (e.g. the source code
\r
2074 file path or an argument to compiler options like <strong>-I</strong> and <strong>-MF</strong>), you must
\r
2075 to set <strong>base_dir</strong> to an absolute path to a “base directory”. ccache will
\r
2076 then rewrite absolute paths under that directory to relative before computing
\r
2083 <div class="sect1">
\r
2084 <h2 id="_precompiled_headers">Precompiled headers</h2>
\r
2085 <div class="sectionbody">
\r
2086 <div class="paragraph"><p>ccache has support for GCC’s precompiled headers. However, you have to do some
\r
2087 things to make it work properly:</p></div>
\r
2088 <div class="ulist"><ul>
\r
2091 You must set <strong>sloppiness</strong> to <strong>pch_defines,time_macros</strong>. The reason is that
\r
2092 ccache can’t tell whether <strong>__TIME__</strong> or <strong>__DATE__</strong> is used when using a
\r
2093 precompiled header. Further, it can’t detect changes in <strong>#define</strong>s in the
\r
2094 source code because of how preprocessing works in combination with
\r
2095 precompiled headers.
\r
2102 <div class="openblock">
\r
2103 <div class="content">
\r
2104 <div class="ulist"><ul>
\r
2107 use the <strong>-include</strong> compiler option to include the precompiled header
\r
2108 (i.e., don’t use <strong>#include</strong> in the source code to include the header); or
\r
2113 (for the Clang compiler) use the <strong>-include-pch</strong> compiler option to include
\r
2114 the PCH file generated from the precompiled header; or
\r
2119 add the <strong>-fpch-preprocess</strong> compiler option when compiling.
\r
2123 <div class="paragraph"><p>If you don’t do this, either the non-precompiled version of the header file
\r
2124 will be used (if available) or ccache will fall back to running the real
\r
2125 compiler and increase the statistics counter “preprocessor error” (if the
\r
2126 non-precompiled header file is not available).</p></div>
\r
2132 <div class="sect1">
\r
2133 <h2 id="_sharing_a_cache">Sharing a cache</h2>
\r
2134 <div class="sectionbody">
\r
2135 <div class="paragraph"><p>A group of developers can increase the cache hit rate by sharing a cache
\r
2136 directory. To share a cache without unpleasant side effects, the following
\r
2137 conditions should to be met:</p></div>
\r
2138 <div class="ulist"><ul>
\r
2141 Use the same cache directory.
\r
2146 Make sure that the configuration setting <strong>hard_link</strong> is false (which is the
\r
2152 Make sure that all users are in the same group.
\r
2157 Set the configuration setting <strong>umask</strong> to 002. This ensures that cached files
\r
2158 are accessible to everyone in the group.
\r
2163 Make sure that all users have write permission in the entire cache directory
\r
2164 (and that you trust all users of the shared cache).
\r
2169 Make sure that the setgid bit is set on all directories in the cache. This
\r
2170 tells the filesystem to inherit group ownership for new directories. The
\r
2171 following command might be useful for this:
\r
2173 <div class="openblock">
\r
2174 <div class="content">
\r
2175 <div class="listingblock">
\r
2176 <div class="content">
\r
2177 <pre><code>find $CCACHE_DIR -type d | xargs chmod g+s</code></pre>
\r
2182 <div class="paragraph"><p>The reason to avoid the hard link mode is that the hard links cause unwanted
\r
2183 side effects, as all links to a cached file share the file’s modification
\r
2184 timestamp. This results in false dependencies to be triggered by
\r
2185 timestamp-based build systems whenever another user links to an existing file.
\r
2186 Typically, users will see that their libraries and binaries are relinked
\r
2187 without reason.</p></div>
\r
2188 <div class="paragraph"><p>You may also want to make sure that a base directory is set appropriately, as
\r
2189 discussed in a previous section.</p></div>
\r
2192 <div class="sect1">
\r
2193 <h2 id="_sharing_a_cache_on_nfs">Sharing a cache on NFS</h2>
\r
2194 <div class="sectionbody">
\r
2195 <div class="paragraph"><p>It is possible to put the cache directory on an NFS filesystem (or similar
\r
2196 filesystems), but keep in mind that:</p></div>
\r
2197 <div class="ulist"><ul>
\r
2200 Having the cache on NFS may slow down compilation. Make sure to do some
\r
2201 benchmarking to see if it’s worth it.
\r
2206 ccache hasn’t been tested very thoroughly on NFS.
\r
2210 <div class="paragraph"><p>A tip is to set <strong>temporary_dir</strong> to a directory on the local host to avoid NFS
\r
2211 traffic for temporary files.</p></div>
\r
2214 <div class="sect1">
\r
2215 <h2 id="_using_ccache_with_other_compiler_wrappers">Using ccache with other compiler wrappers</h2>
\r
2216 <div class="sectionbody">
\r
2217 <div class="paragraph"><p>The recommended way of combining ccache with another compiler wrapper (such as
\r
2218 “distcc”) is by letting ccache execute the compiler wrapper. This is
\r
2219 accomplished by defining the configuration setting <strong>prefix_command</strong>, for
\r
2220 example by setting the environment variable <strong>CCACHE_PREFIX</strong> to the name of the
\r
2221 wrapper (e.g. <strong>distcc</strong>). ccache will then prefix the command line with the
\r
2222 specified command when running the compiler. To specify several prefix
\r
2223 commands, set <strong>prefix_command</strong> to a colon-separated list of commands.</p></div>
\r
2224 <div class="paragraph"><p>Unless you set <strong>compiler_check</strong> to a suitable command (see the description of
\r
2225 that configuration option), it is not recommended to use the form <strong>ccache
\r
2226 anotherwrapper compiler args</strong> as the compilation command. It’s also not
\r
2227 recommended to use the masquerading technique for the other compiler wrapper.
\r
2228 The reason is that by default, ccache will in both cases hash the mtime and
\r
2229 size of the other wrapper instead of the real compiler, which means that:</p></div>
\r
2230 <div class="ulist"><ul>
\r
2233 Compiler upgrades will not be detected properly.
\r
2238 The cached results will not be shared between compilations with and without
\r
2239 the other wrapper.
\r
2243 <div class="paragraph"><p>Another minor thing is that if <strong>prefix_command</strong> is used, ccache will not invoke
\r
2244 the other wrapper when running the preprocessor, which increases performance.
\r
2245 You can use the <strong>prefix_command_cpp</strong> configuration setting if you also want to
\r
2246 invoke the other wrapper when doing preprocessing (normally by adding <strong>-E</strong>).</p></div>
\r
2249 <div class="sect1">
\r
2250 <h2 id="_caveats">Caveats</h2>
\r
2251 <div class="sectionbody">
\r
2252 <div class="ulist"><ul>
\r
2255 The direct mode fails to pick up new header files in some rare scenarios. See
\r
2256 <a href="#_the_direct_mode">THE DIRECT MODE</a> above.
\r
2261 When run via ccache, warning messages produced by GCC 4.9 and newer will only
\r
2262 be colored when the environment variable <strong>GCC_COLORS</strong> is set. An alternative
\r
2263 to setting <strong>GCC_COLORS</strong> is to pass <code>-fdiagnostics-color</code> explicitly when
\r
2264 compiling (but then color codes will also be present when redirecting stderr
\r
2270 If ccache guesses that the compiler may emit colored warnings, then a
\r
2271 compilation with stderr referring to a TTY will be considered different from
\r
2272 a compilation with a redirected stderr, thus not sharing cache entries. This
\r
2273 happens for clang by default and for GCC when <strong>GCC_COLORS</strong> is set as
\r
2274 mentioned above. If you want to share cache hits, you can pass
\r
2275 <code>-f[no-]diagnostics-color</code> (GCC) or <code>-f[no-]color-diagnostics</code> (clang)
\r
2276 explicitly when compiling (but then color codes will be either on or off for
\r
2277 both the TTY and the redirected case).
\r
2283 <div class="sect1">
\r
2284 <h2 id="_troubleshooting">Troubleshooting</h2>
\r
2285 <div class="sectionbody">
\r
2286 <div class="sect2">
\r
2287 <h3 id="_general">General</h3>
\r
2288 <div class="paragraph"><p>A general tip for getting information about what ccache is doing is to enable
\r
2289 debug logging by setting <strong>log_file</strong>. The log contains executed commands,
\r
2290 important decisions that ccache makes, read and written files, etc. Another way
\r
2291 of keeping track of what is happening is to check the output of <strong>ccache -s</strong>.</p></div>
\r
2293 <div class="sect2">
\r
2294 <h3 id="_performance">Performance</h3>
\r
2295 <div class="paragraph"><p>ccache has been written to perform well out of the box, but sometimes you may
\r
2296 have to do some adjustments of how you use the compiler and ccache in order to
\r
2297 improve performance.</p></div>
\r
2298 <div class="paragraph"><p>Since ccache works best when I/O is fast, put the cache directory on a fast
\r
2299 storage device if possible. Having lots of free memory so that files in the
\r
2300 cache directory stay in the disk cache is also preferable.</p></div>
\r
2301 <div class="paragraph"><p>A good way of monitoring how well ccache works is to run <strong>ccache -s</strong> before and
\r
2302 after your build and then compare the statistics counters. Here are some common
\r
2303 problems and what may be done to increase the hit rate:</p></div>
\r
2304 <div class="ulist"><ul>
\r
2307 If “cache hit (preprocessed)” has been incremented instead of “cache hit
\r
2308 (direct)”, ccache has fallen back to preprocessor mode, which is generally
\r
2309 slower. Some possible reasons are:
\r
2311 <div class="ulist"><ul>
\r
2314 The source code has been modified in such a way that the preprocessor output
\r
2320 Compiler arguments that are hashed in the direct mode but not in the
\r
2321 preprocessor mode have changed (<strong>-I</strong>, <strong>-include</strong>, <strong>-D</strong>, etc) and they didn’t
\r
2322 affect the preprocessor output.
\r
2327 The compiler option <strong>-Xpreprocessor</strong> or <strong>-Wp,<em>X</em></strong> (except <strong>-Wp,-MD,<em>path</em></strong>,
\r
2328 <strong>-Wp,-MMD,<em>path</em></strong>, and <strong>-Wp,-D_define_</strong>) is used.
\r
2333 This was the first compilation with a new value of the base directory
\r
2339 A modification time of one of the include files is too new (created the same
\r
2340 second as the compilation is being done). This check is made to avoid a race
\r
2341 condition. To fix this, create the include file earlier in the build
\r
2342 process, if possible, or set <strong>sloppiness</strong> to <strong>include_file_mtime</strong> if you are
\r
2343 willing to take the risk. (The race condition consists of these events: the
\r
2344 preprocessor is run; an include file is modified by someone; the new include
\r
2345 file is hashed by ccache; the real compiler is run on the preprocessor’s
\r
2346 output, which contains data from the old header file; the wrong object file
\r
2347 is stored in the cache.)
\r
2352 The <strong>__TIME__</strong> preprocessor macro is (potentially) being used. ccache
\r
2353 turns off direct mode if “__TIME__” is present in the source code. This
\r
2354 is done as a safety measure since the string indicates that a <strong>__TIME__</strong>
\r
2355 macro <em>may</em> affect the output. (To be sure, ccache would have to run the
\r
2356 preprocessor, but the sole point of the direct mode is to avoid that.) If
\r
2357 you know that <strong>__TIME__</strong> isn’t used in practise, or don’t care if ccache
\r
2358 produces objects where <strong>__TIME__</strong> is expanded to something in the past,
\r
2359 you can set <strong>sloppiness</strong> to <strong>time_macros</strong>.
\r
2364 The <strong>__DATE__</strong> preprocessor macro is (potentially) being used and the
\r
2365 date has changed. This is similar to how <strong>__TIME__</strong> is handled. If
\r
2366 “__DATE__” is present in the source code, ccache hashes the current
\r
2367 date in order to be able to produce the correct object file if the
\r
2368 <strong>__DATE__</strong> macro affects the output. If you know that <strong>__DATE__</strong> isn’t
\r
2369 used in practise, or don’t care if ccache produces objects where
\r
2370 <strong>__DATE__</strong> is expanded to something in the past, you can set <strong>sloppiness</strong>
\r
2371 to <strong>time_macros</strong>.
\r
2376 The <strong>__FILE__</strong> preprocessor macro is (potentially) being used and the
\r
2377 file path has changed. If “__FILE__” is present in the source code,
\r
2378 ccache hashes the current input file path in order to be able to produce the
\r
2379 correct object file if the <strong>__FILE__</strong> macro affects the output. If you
\r
2380 know that <strong>__FILE__</strong> isn’t used in practise, or don’t care if ccache
\r
2381 produces objects where <strong>__FILE__</strong> is expanded to the wrong path, you can
\r
2382 set <strong>sloppiness</strong> to <strong>file_macro</strong>.
\r
2389 If “cache miss” has been incremented even though the same code has been
\r
2390 compiled and cached before, ccache has either detected that something has
\r
2391 changed anyway or a cleanup has been performed (either explicitly or
\r
2392 implicitly when a cache limit has been reached). Some perhaps unobvious
\r
2393 things that may result in a cache miss are usage of <strong>__TIME__</strong> or
\r
2394 <strong>__DATE__</strong> macros, or use of automatically generated code that contains a
\r
2395 timestamp, build counter or other volatile information.
\r
2400 If “multiple source files” has been incremented, it’s an indication that
\r
2401 the compiler has been invoked on several source code files at once. ccache
\r
2402 doesn’t support that. Compile the source code files separately if possible.
\r
2407 If “unsupported compiler option” has been incremented, enable debug logging
\r
2408 and check which option was rejected.
\r
2413 If “preprocessor error” has been incremented, one possible reason is that
\r
2414 precompiled headers are being used. See <a href="#_precompiled_headers">PRECOMPILED HEADERS</a> for how to remedy this.
\r
2419 If “can’t use precompiled header” has been incremented, see
\r
2420 <a href="#_precompiled_headers">PRECOMPILED HEADERS</a>.
\r
2425 <div class="sect2">
\r
2426 <h3 id="_corrupt_object_files">Corrupt object files</h3>
\r
2427 <div class="paragraph"><p>It should be noted that ccache is susceptible to general storage problems. If a
\r
2428 bad object file sneaks into the cache for some reason, it will of course stay
\r
2429 bad. Some possible reasons for erroneous object files are bad hardware (disk
\r
2430 drive, disk controller, memory, etc), buggy drivers or file systems, a bad
\r
2431 <strong>prefix_command</strong> or compiler wrapper. If this happens, the easiest way of
\r
2432 fixing it is this:</p></div>
\r
2433 <div class="olist arabic"><ol class="arabic">
\r
2436 Build so that the bad object file ends up in the build tree.
\r
2441 Remove the bad object file from the build tree.
\r
2446 Rebuild with <strong>CCACHE_RECACHE</strong> set.
\r
2450 <div class="paragraph"><p>An alternative is to clear the whole cache with <strong>ccache -C</strong> if you don’t mind
\r
2451 losing other cached results.</p></div>
\r
2452 <div class="paragraph"><p>There are no reported issues about ccache producing broken object files
\r
2453 reproducibly. That doesn’t mean it can’t happen, so if you find a repeatable
\r
2454 case, please report it.</p></div>
\r
2458 <div class="sect1">
\r
2459 <h2 id="_more_information">More information</h2>
\r
2460 <div class="sectionbody">
\r
2461 <div class="paragraph"><p>Credits, mailing list information, bug reporting instructions, source code,
\r
2462 etc, can be found on ccache’s web site: <a href="https://ccache.samba.org">https://ccache.samba.org</a>.</p></div>
\r
2465 <div class="sect1">
\r
2466 <h2 id="_author">Author</h2>
\r
2467 <div class="sectionbody">
\r
2468 <div class="paragraph"><p>ccache was originally written by Andrew Tridgell and is currently developed and
\r
2469 maintained by Joel Rosdahl. See AUTHORS.txt or AUTHORS.html and
\r
2470 <a href="https://ccache.samba.org/credits.html">https://ccache.samba.org/credits.html</a> for a list of contributors.</p></div>
\r
2474 <div id="footnotes"><hr /></div>
\r
2476 <div id="footer-text">
\r
2479 2018-02-06 21:44:11 CET
\r
projects / platform / upstream / ccache.git / blob