1 <?xml version="1.0" encoding="UTF-8"?>
\r
2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
\r
3 "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
\r
4 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
\r
6 <meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" />
\r
7 <meta name="generator" content="AsciiDoc 8.6.10" />
\r
8 <title>CCACHE(1)</title>
\r
9 <style type="text/css">
\r
10 /* Shared CSS for AsciiDoc xhtml11 and html5 backends */
\r
14 font-family: Georgia,serif;
\r
18 h1, h2, h3, h4, h5, h6,
\r
19 div.title, caption.title,
\r
20 thead, p.table.header,
\r
22 #author, #revnumber, #revdate, #revremark,
\r
24 font-family: Arial,Helvetica,sans-serif;
\r
28 margin: 1em 5% 1em 5%;
\r
33 text-decoration: underline;
\r
49 h1, h2, h3, h4, h5, h6 {
\r
52 margin-bottom: 0.5em;
\r
57 border-bottom: 2px solid silver;
\r
77 border: 1px solid silver;
\r
82 margin-bottom: 0.5em;
\r
88 ul > li { color: #aaa; }
\r
89 ul > li > * { color: black; }
\r
91 .monospaced, code, pre {
\r
92 font-family: "Courier New", Courier, monospace;
\r
99 white-space: pre-wrap;
\r
109 #revnumber, #revdate, #revremark {
\r
114 border-top: 2px solid silver;
\r
115 padding-top: 0.5em;
\r
120 padding-bottom: 0.5em;
\r
124 padding-bottom: 0.5em;
\r
129 margin-bottom: 1.5em;
\r
131 div.imageblock, div.exampleblock, div.verseblock,
\r
132 div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
\r
133 div.admonitionblock {
\r
135 margin-bottom: 1.5em;
\r
137 div.admonitionblock {
\r
139 margin-bottom: 2.0em;
\r
144 div.content { /* Block element content. */
\r
148 /* Block element titles. */
\r
149 div.title, caption.title {
\r
154 margin-bottom: 0.5em;
\r
160 td div.title:first-child {
\r
163 div.content div.title:first-child {
\r
166 div.content + div.title {
\r
170 div.sidebarblock > div.content {
\r
171 background: #ffffee;
\r
172 border: 1px solid #dddddd;
\r
173 border-left: 4px solid #f0f0f0;
\r
177 div.listingblock > div.content {
\r
178 border: 1px solid #dddddd;
\r
179 border-left: 5px solid #f0f0f0;
\r
180 background: #f8f8f8;
\r
184 div.quoteblock, div.verseblock {
\r
185 padding-left: 1.0em;
\r
186 margin-left: 1.0em;
\r
188 border-left: 5px solid #f0f0f0;
\r
192 div.quoteblock > div.attribution {
\r
193 padding-top: 0.5em;
\r
197 div.verseblock > pre.content {
\r
198 font-family: inherit;
\r
199 font-size: inherit;
\r
201 div.verseblock > div.attribution {
\r
202 padding-top: 0.75em;
\r
205 /* DEPRECATED: Pre version 8.2.7 verse style literal block. */
\r
206 div.verseblock + div.attribution {
\r
210 div.admonitionblock .icon {
\r
211 vertical-align: top;
\r
214 text-decoration: underline;
\r
216 padding-right: 0.5em;
\r
218 div.admonitionblock td.content {
\r
219 padding-left: 0.5em;
\r
220 border-left: 3px solid #dddddd;
\r
223 div.exampleblock > div.content {
\r
224 border-left: 3px solid #dddddd;
\r
225 padding-left: 0.5em;
\r
228 div.imageblock div.content { padding-left: 0; }
\r
229 span.image img { border-style: none; vertical-align: text-bottom; }
\r
230 a.image:visited { color: white; }
\r
234 margin-bottom: 0.8em;
\r
239 font-style: normal;
\r
242 dd > *:first-child {
\r
247 list-style-position: outside;
\r
250 list-style-type: decimal;
\r
253 list-style-type: lower-alpha;
\r
256 list-style-type: upper-alpha;
\r
259 list-style-type: lower-roman;
\r
262 list-style-type: upper-roman;
\r
265 div.compact ul, div.compact ol,
\r
266 div.compact p, div.compact p,
\r
267 div.compact div, div.compact div {
\r
269 margin-bottom: 0.1em;
\r
281 margin-bottom: 0.8em;
\r
284 padding-bottom: 15px;
\r
286 dt.hdlist1.strong, td.hdlist1.strong {
\r
290 vertical-align: top;
\r
291 font-style: normal;
\r
292 padding-right: 0.8em;
\r
296 vertical-align: top;
\r
298 div.hdlist.compact tr {
\r
304 background: yellow;
\r
307 .footnote, .footnoteref {
\r
311 span.footnote, span.footnoteref {
\r
312 vertical-align: super;
\r
316 margin: 20px 0 20px 0;
\r
317 padding: 7px 0 0 0;
\r
320 #footnotes div.footnote {
\r
326 border-top: 1px solid silver;
\r
335 padding-right: 0.5em;
\r
336 padding-bottom: 0.3em;
\r
337 vertical-align: top;
\r
339 div.colist td img {
\r
344 #footer-badges { display: none; }
\r
348 margin-bottom: 2.5em;
\r
356 margin-bottom: 0.1em;
\r
359 div.toclevel0, div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
\r
376 span.aqua { color: aqua; }
\r
377 span.black { color: black; }
\r
378 span.blue { color: blue; }
\r
379 span.fuchsia { color: fuchsia; }
\r
380 span.gray { color: gray; }
\r
381 span.green { color: green; }
\r
382 span.lime { color: lime; }
\r
383 span.maroon { color: maroon; }
\r
384 span.navy { color: navy; }
\r
385 span.olive { color: olive; }
\r
386 span.purple { color: purple; }
\r
387 span.red { color: red; }
\r
388 span.silver { color: silver; }
\r
389 span.teal { color: teal; }
\r
390 span.white { color: white; }
\r
391 span.yellow { color: yellow; }
\r
393 span.aqua-background { background: aqua; }
\r
394 span.black-background { background: black; }
\r
395 span.blue-background { background: blue; }
\r
396 span.fuchsia-background { background: fuchsia; }
\r
397 span.gray-background { background: gray; }
\r
398 span.green-background { background: green; }
\r
399 span.lime-background { background: lime; }
\r
400 span.maroon-background { background: maroon; }
\r
401 span.navy-background { background: navy; }
\r
402 span.olive-background { background: olive; }
\r
403 span.purple-background { background: purple; }
\r
404 span.red-background { background: red; }
\r
405 span.silver-background { background: silver; }
\r
406 span.teal-background { background: teal; }
\r
407 span.white-background { background: white; }
\r
408 span.yellow-background { background: yellow; }
\r
410 span.big { font-size: 2em; }
\r
411 span.small { font-size: 0.6em; }
\r
413 span.underline { text-decoration: underline; }
\r
414 span.overline { text-decoration: overline; }
\r
415 span.line-through { text-decoration: line-through; }
\r
417 div.unbreakable { page-break-inside: avoid; }
\r
427 margin-bottom: 1.5em;
\r
429 div.tableblock > table {
\r
430 border: 3px solid #527bbd;
\r
432 thead, p.table.header {
\r
439 /* Because the table frame attribute is overriden by CSS in most browsers. */
\r
440 div.tableblock > table[frame="void"] {
\r
441 border-style: none;
\r
443 div.tableblock > table[frame="hsides"] {
\r
444 border-left-style: none;
\r
445 border-right-style: none;
\r
447 div.tableblock > table[frame="vsides"] {
\r
448 border-top-style: none;
\r
449 border-bottom-style: none;
\r
460 margin-bottom: 1.5em;
\r
462 thead, p.tableblock.header {
\r
471 border-spacing: 0px;
\r
472 border-style: solid;
\r
473 border-color: #527bbd;
\r
474 border-collapse: collapse;
\r
476 th.tableblock, td.tableblock {
\r
479 border-style: solid;
\r
480 border-color: #527bbd;
\r
483 table.tableblock.frame-topbot {
\r
484 border-left-style: hidden;
\r
485 border-right-style: hidden;
\r
487 table.tableblock.frame-sides {
\r
488 border-top-style: hidden;
\r
489 border-bottom-style: hidden;
\r
491 table.tableblock.frame-none {
\r
492 border-style: hidden;
\r
495 th.tableblock.halign-left, td.tableblock.halign-left {
\r
498 th.tableblock.halign-center, td.tableblock.halign-center {
\r
499 text-align: center;
\r
501 th.tableblock.halign-right, td.tableblock.halign-right {
\r
505 th.tableblock.valign-top, td.tableblock.valign-top {
\r
506 vertical-align: top;
\r
508 th.tableblock.valign-middle, td.tableblock.valign-middle {
\r
509 vertical-align: middle;
\r
511 th.tableblock.valign-bottom, td.tableblock.valign-bottom {
\r
512 vertical-align: bottom;
\r
522 padding-top: 0.5em;
\r
523 padding-bottom: 0.5em;
\r
524 border-top: 2px solid silver;
\r
525 border-bottom: 2px solid silver;
\r
528 border-style: none;
\r
530 body.manpage div.sectionbody {
\r
535 body.manpage div#toc { display: none; }
\r
540 <script type="text/javascript">
\r
542 var asciidoc = { // Namespace.
\r
544 /////////////////////////////////////////////////////////////////////
\r
545 // Table Of Contents generator
\r
546 /////////////////////////////////////////////////////////////////////
\r
548 /* Author: Mihai Bazon, September 2002
\r
549 * http://students.infoiasi.ro/~mishoo
\r
551 * Table Of Content generator
\r
554 * Feel free to use this script under the terms of the GNU General Public
\r
555 * License, as long as you do not remove or alter this notice.
\r
558 /* modified by Troy D. Hanson, September 2006. License: GPL */
\r
559 /* modified by Stuart Rackham, 2006, 2009. License: GPL */
\r
561 // toclevels = 1..4.
\r
562 toc: function (toclevels) {
\r
564 function getText(el) {
\r
566 for (var i = el.firstChild; i != null; i = i.nextSibling) {
\r
567 if (i.nodeType == 3 /* Node.TEXT_NODE */) // IE doesn't speak constants.
\r
569 else if (i.firstChild != null)
\r
570 text += getText(i);
\r
575 function TocEntry(el, text, toclevel) {
\r
578 this.toclevel = toclevel;
\r
581 function tocEntries(el, toclevels) {
\r
582 var result = new Array;
\r
583 var re = new RegExp('[hH]([1-'+(toclevels+1)+'])');
\r
584 // Function that scans the DOM tree for header elements (the DOM2
\r
585 // nodeIterator API would be a better technique but not supported by all
\r
587 var iterate = function (el) {
\r
588 for (var i = el.firstChild; i != null; i = i.nextSibling) {
\r
589 if (i.nodeType == 1 /* Node.ELEMENT_NODE */) {
\r
590 var mo = re.exec(i.tagName);
\r
591 if (mo && (i.getAttribute("class") || i.getAttribute("className")) != "float") {
\r
592 result[result.length] = new TocEntry(i, getText(i), mo[1]-1);
\r
602 var toc = document.getElementById("toc");
\r
607 // Delete existing TOC entries in case we're reloading the TOC.
\r
608 var tocEntriesToRemove = [];
\r
610 for (i = 0; i < toc.childNodes.length; i++) {
\r
611 var entry = toc.childNodes[i];
\r
612 if (entry.nodeName.toLowerCase() == 'div'
\r
613 && entry.getAttribute("class")
\r
614 && entry.getAttribute("class").match(/^toclevel/))
\r
615 tocEntriesToRemove.push(entry);
\r
617 for (i = 0; i < tocEntriesToRemove.length; i++) {
\r
618 toc.removeChild(tocEntriesToRemove[i]);
\r
621 // Rebuild TOC entries.
\r
622 var entries = tocEntries(document.getElementById("content"), toclevels);
\r
623 for (var i = 0; i < entries.length; ++i) {
\r
624 var entry = entries[i];
\r
625 if (entry.element.id == "")
\r
626 entry.element.id = "_toc_" + i;
\r
627 var a = document.createElement("a");
\r
628 a.href = "#" + entry.element.id;
\r
629 a.appendChild(document.createTextNode(entry.text));
\r
630 var div = document.createElement("div");
\r
631 div.appendChild(a);
\r
632 div.className = "toclevel" + entry.toclevel;
\r
633 toc.appendChild(div);
\r
635 if (entries.length == 0)
\r
636 toc.parentNode.removeChild(toc);
\r
640 /////////////////////////////////////////////////////////////////////
\r
641 // Footnotes generator
\r
642 /////////////////////////////////////////////////////////////////////
\r
644 /* Based on footnote generation code from:
\r
645 * http://www.brandspankingnew.net/archive/2005/07/format_footnote.html
\r
648 footnotes: function () {
\r
649 // Delete existing footnote entries in case we're reloading the footnodes.
\r
651 var noteholder = document.getElementById("footnotes");
\r
655 var entriesToRemove = [];
\r
656 for (i = 0; i < noteholder.childNodes.length; i++) {
\r
657 var entry = noteholder.childNodes[i];
\r
658 if (entry.nodeName.toLowerCase() == 'div' && entry.getAttribute("class") == "footnote")
\r
659 entriesToRemove.push(entry);
\r
661 for (i = 0; i < entriesToRemove.length; i++) {
\r
662 noteholder.removeChild(entriesToRemove[i]);
\r
665 // Rebuild footnote entries.
\r
666 var cont = document.getElementById("content");
\r
667 var spans = cont.getElementsByTagName("span");
\r
670 for (i=0; i<spans.length; i++) {
\r
671 if (spans[i].className == "footnote") {
\r
673 var note = spans[i].getAttribute("data-note");
\r
675 // Use [\s\S] in place of . so multi-line matches work.
\r
676 // Because JavaScript has no s (dotall) regex flag.
\r
677 note = spans[i].innerHTML.match(/\s*\[([\s\S]*)]\s*/)[1];
\r
678 spans[i].innerHTML =
\r
679 "[<a id='_footnoteref_" + n + "' href='#_footnote_" + n +
\r
680 "' title='View footnote' class='footnote'>" + n + "</a>]";
\r
681 spans[i].setAttribute("data-note", note);
\r
683 noteholder.innerHTML +=
\r
684 "<div class='footnote' id='_footnote_" + n + "'>" +
\r
685 "<a href='#_footnoteref_" + n + "' title='Return to text'>" +
\r
686 n + "</a>. " + note + "</div>";
\r
687 var id =spans[i].getAttribute("id");
\r
688 if (id != null) refs["#"+id] = n;
\r
692 noteholder.parentNode.removeChild(noteholder);
\r
694 // Process footnoterefs.
\r
695 for (i=0; i<spans.length; i++) {
\r
696 if (spans[i].className == "footnoteref") {
\r
697 var href = spans[i].getElementsByTagName("a")[0].getAttribute("href");
\r
698 href = href.match(/#.*/)[0]; // Because IE return full URL.
\r
700 spans[i].innerHTML =
\r
701 "[<a href='#_footnote_" + n +
\r
702 "' title='View footnote' class='footnote'>" + n + "</a>]";
\r
708 install: function(toclevels) {
\r
711 function reinstall() {
\r
712 asciidoc.footnotes();
\r
714 asciidoc.toc(toclevels);
\r
718 function reinstallAndRemoveTimer() {
\r
719 clearInterval(timerId);
\r
723 timerId = setInterval(reinstall, 500);
\r
724 if (document.addEventListener)
\r
725 document.addEventListener("DOMContentLoaded", reinstallAndRemoveTimer, false);
\r
727 window.onload = reinstallAndRemoveTimer;
\r
731 asciidoc.install(2);
\r
735 <body class="article">
\r
738 <span id="revnumber">version 3.7</span>
\r
740 <div id="toctitle">Table of Contents</div>
741 <noscript><p><b>JavaScript must be enabled in your browser to display the table of contents.</b></p></noscript>
745 <div class="sect1">
\r
746 <h2 id="_name">Name</h2>
\r
747 <div class="sectionbody">
\r
748 <div class="paragraph"><p>ccache - a fast C/C++ compiler cache</p></div>
\r
751 <div class="sect1">
\r
752 <h2 id="_synopsis">Synopsis</h2>
\r
753 <div class="sectionbody">
\r
754 <div class="verseblock">
\r
755 <pre class="content"><strong>ccache</strong> [<em>options</em>]
\r
756 <strong>ccache</strong> <em>compiler</em> [<em>compiler options</em>]
\r
757 <em>compiler</em> [<em>compiler options</em>] (via symbolic link)</pre>
\r
758 <div class="attribution">
\r
762 <div class="sect1">
\r
763 <h2 id="_description">Description</h2>
\r
764 <div class="sectionbody">
\r
765 <div class="paragraph"><p>ccache is a compiler cache. It speeds up recompilation by caching the result of
\r
766 previous compilations and detecting when the same compilation is being done
\r
767 again. Supported languages are C, C++, Objective-C and Objective-C++.</p></div>
\r
768 <div class="paragraph"><p>ccache has been carefully written to always produce exactly the same compiler
\r
769 output that you would get without the cache. The only way you should be able to
\r
770 tell that you are using ccache is the speed. Currently known exceptions to this
\r
771 goal are listed under <a href="#_caveats">CAVEATS</a>. If you ever discover an
\r
772 undocumented case where ccache changes the output of your compiler, please let
\r
774 <div class="sect2">
\r
775 <h3 id="_features">Features</h3>
\r
776 <div class="ulist"><ul>
\r
779 Keeps statistics on hits/misses.
\r
784 Automatic cache size management.
\r
789 Can cache compilations that generate warnings.
\r
804 Optionally compresses files in the cache to reduce disk space.
\r
809 <div class="sect2">
\r
810 <h3 id="_limitations">Limitations</h3>
\r
811 <div class="ulist"><ul>
\r
814 Only knows how to cache the compilation of a single
\r
815 C/C++/Objective-C/Objective-C++ file. Other types of compilations
\r
816 (multi-file compilation, linking, etc) will silently fall back to running the
\r
822 Only works with GCC and compilers that behave similar enough.
\r
827 Some compiler flags are not supported. If such a flag is detected, ccache
\r
828 will silently fall back to running the real compiler.
\r
835 <div class="sect1">
\r
836 <h2 id="_run_modes">Run modes</h2>
\r
837 <div class="sectionbody">
\r
838 <div class="paragraph"><p>There are two ways to use ccache. You can either prefix your compilation
\r
839 commands with <strong>ccache</strong> or you can let ccache masquerade as the compiler by
\r
840 creating a symbolic link (named as the compiler) to ccache. The first method is
\r
841 most convenient if you just want to try out ccache or wish to use it for some
\r
842 specific projects. The second method is most useful for when you wish to use
\r
843 ccache for all your compilations.</p></div>
\r
844 <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
845 <div class="paragraph"><p>To use the symlinks method, do something like this:</p></div>
\r
846 <div class="listingblock">
\r
847 <div class="content">
\r
848 <pre><code>cp ccache /usr/local/bin/
\r
849 ln -s ccache /usr/local/bin/gcc
\r
850 ln -s ccache /usr/local/bin/g++
\r
851 ln -s ccache /usr/local/bin/cc
\r
852 ln -s ccache /usr/local/bin/c++</code></pre>
\r
854 <div class="paragraph"><p>And so forth. This will work as long as the directory with symlinks comes
\r
855 before the path to the compiler (which is usually in <code>/usr/bin</code>). After
\r
856 installing you may wish to run “which gcc” to make sure that the correct link
\r
857 is being used.</p></div>
\r
858 <div class="admonitionblock">
\r
861 <div class="title">Warning</div>
\r
863 <td class="content">The technique of letting ccache masquerade as the compiler works well,
\r
864 but currently doesn’t interact well with other tools that do the same thing.
\r
865 See <a href="#_using_ccache_with_other_compiler_wrappers">USING CCACHE WITH OTHER COMPILER WRAPPERS</a>.</td>
\r
868 <div class="admonitionblock">
\r
871 <div class="title">Warning</div>
\r
873 <td class="content">Do not use a hard link, use a symbolic link. A hard link will cause
\r
874 “interesting” problems.</td>
\r
879 <div class="sect1">
\r
880 <h2 id="_options">Options</h2>
\r
881 <div class="sectionbody">
\r
882 <div class="paragraph"><p>These options only apply when you invoke ccache as “ccache”. When invoked as
\r
883 a compiler (via a symlink as described in the previous section), the normal
\r
884 compiler options apply and you should refer to the compiler’s documentation.</p></div>
\r
885 <div class="dlist"><dl>
\r
886 <dt class="hdlist1">
\r
887 <strong><code>-c, --cleanup</code></strong>
\r
891 Clean up the cache by removing old cached files until the specified file
\r
892 number and cache size limits are not exceeded. This also recalculates the
\r
893 cache file count and size totals. Normally, there is no need to initiate
\r
894 cleanup manually as ccache keeps the cache below the specified limits at
\r
895 runtime and keeps statistics up to date on each compilation. Forcing a
\r
896 cleanup is mostly useful if you manually modify the cache contents or
\r
897 believe that the cache size statistics may be inaccurate.
\r
900 <dt class="hdlist1">
\r
901 <strong><code>-C, --clear</code></strong>
\r
905 Clear the entire cache, removing all cached files, but keeping the
\r
906 configuration file.
\r
909 <dt class="hdlist1">
\r
910 <strong><code>--dump-manifest</code></strong>=<em>PATH</em>
\r
914 Dump manifest file at PATH in text format. This is only useful when
\r
915 debugging ccache and its behavior.
\r
918 <dt class="hdlist1">
\r
919 <strong><code>-k, --get-config</code></strong>=<em>KEY</em>
\r
923 Print the value of configuration option <em>KEY</em>. See
\r
924 <a href="#_configuration">CONFIGURATION</a> for more information.
\r
927 <dt class="hdlist1">
\r
928 <strong><code>--hash-file</code></strong>=<em>PATH</em>
\r
932 Print the hash (in format <code><MD4>-<size></code>) of the file at PATH. This is only
\r
933 useful when debugging ccache and its behavior.
\r
936 <dt class="hdlist1">
\r
937 <strong><code>-h, --help</code></strong>
\r
941 Print an options summary page.
\r
944 <dt class="hdlist1">
\r
945 <strong><code>-F, --max-files</code></strong>=<em>N</em>
\r
949 Set the maximum number of files allowed in the cache. Use 0 for no limit.
\r
950 The value is stored in a configuration file in the cache directory and
\r
951 applies to all future compilations.
\r
954 <dt class="hdlist1">
\r
955 <strong><code>-M, --max-size</code></strong>=<em>SIZE</em>
\r
959 Set the maximum size of the files stored in the cache. <em>SIZE</em> should be a
\r
960 number followed by an optional suffix: k, M, G, T (decimal), Ki, Mi, Gi or
\r
961 Ti (binary). The default suffix is G. Use 0 for no limit. The value is
\r
962 stored in a configuration file in the cache directory and applies to all
\r
963 future compilations.
\r
966 <dt class="hdlist1">
\r
967 <strong><code>--print-stats</code></strong>
\r
971 Print statistics counter IDs and corresponding values machine-parsable
\r
972 (tab-separated) format.
\r
975 <dt class="hdlist1">
\r
976 <strong><code>-o, --set-config</code></strong>=<em>KEY=VALUE</em>
\r
980 Set configuration option <em>KEY</em> to <em>VALUE</em>. See
\r
981 <a href="#_configuration">CONFIGURATION</a> for more information.
\r
984 <dt class="hdlist1">
\r
985 <strong><code>-p, --show-config</code></strong>
\r
989 Print current configuration options and from where they originate
\r
990 (environment variable, configuration file or compile-time default) in
\r
991 human-readable format.
\r
994 <dt class="hdlist1">
\r
995 <strong><code>-s, --show-stats</code></strong>
\r
999 Print a summary of configuration and statistics counters in human-readable
\r
1003 <dt class="hdlist1">
\r
1004 <strong><code>-V, --version</code></strong>
\r
1008 Print version and copyright information.
\r
1011 <dt class="hdlist1">
\r
1012 <strong><code>-z, --zero-stats</code></strong>
\r
1016 Zero the cache statistics (but not the configuration options).
\r
1022 <div class="sect1">
\r
1023 <h2 id="_extra_options">Extra options</h2>
\r
1024 <div class="sectionbody">
\r
1025 <div class="paragraph"><p>When run as a compiler, ccache usually just takes the same command line options
\r
1026 as the compiler you are using. The only exception to this is the option
\r
1027 <strong>--ccache-skip</strong>. That option can be used to tell ccache to avoid interpreting
\r
1028 the next option in any way and to pass it along to the compiler as-is.</p></div>
\r
1029 <div class="admonitionblock">
\r
1032 <div class="title">Note</div>
\r
1034 <td class="content"><strong>--ccache-skip</strong> currently only tells ccache not to interpret the next
\r
1035 option as a special compiler option — the option will still be included in the
\r
1036 direct mode hash.</td>
\r
1039 <div class="paragraph"><p>The reason this can be important is that ccache does need to parse the command
\r
1040 line and determine what is an input filename and what is a compiler option, as
\r
1041 it needs the input filename to determine the name of the resulting object file
\r
1042 (among other things). The heuristic ccache uses when parsing the command line
\r
1043 is that any argument that exists as a file is treated as an input file name. By
\r
1044 using <strong>--ccache-skip</strong> you can force an option to not be treated as an input
\r
1045 file name and instead be passed along to the compiler as a command line option.</p></div>
\r
1046 <div class="paragraph"><p>Another case where <strong>--ccache-skip</strong> can be useful is if ccache interprets an
\r
1047 option specially but shouldn’t, since the option has another meaning for your
\r
1048 compiler than what ccache thinks.</p></div>
\r
1051 <div class="sect1">
\r
1052 <h2 id="_configuration">Configuration</h2>
\r
1053 <div class="sectionbody">
\r
1054 <div class="paragraph"><p>ccache’s default behavior can be overridden by configuration file settings,
\r
1055 which in turn can be overridden by environment variables with names starting
\r
1056 with <strong>CCACHE_</strong>. ccache normally reads configuration from two files: first a
\r
1057 system-level configuration file and secondly a cache-specific configuration
\r
1058 file. The priority of configuration settings is as follows (where 1 is
\r
1059 highest):</p></div>
\r
1060 <div class="olist arabic"><ol class="arabic">
\r
1063 Environment variables.
\r
1068 The cache-specific configuration file <strong><em><ccachedir></em>/ccache.conf</strong> (typically
\r
1069 <strong>$HOME/.ccache/ccache.conf</strong>).
\r
1074 The system-wide configuration file <strong><em><sysconfdir></em>/ccache.conf</strong> (typically
\r
1075 <strong>/etc/ccache.conf</strong> or <strong>/usr/local/etc/ccache.conf</strong>).
\r
1080 Compile-time defaults.
\r
1084 <div class="paragraph"><p>As a special case, if the environment variable <strong>CCACHE_CONFIGPATH</strong> is set,
\r
1085 ccache reads configuration from the specified path instead of the default
\r
1087 <div class="sect2">
\r
1088 <h3 id="_configuration_file_syntax">Configuration file syntax</h3>
\r
1089 <div class="paragraph"><p>Configuration files are in a simple “key = value” format, one setting per
\r
1090 line. Lines starting with a hash sign are comments. Blank lines are ignored, as
\r
1091 is whitespace surrounding keys and values. Example:</p></div>
\r
1092 <div class="listingblock">
\r
1093 <div class="content">
\r
1094 <pre><code># Set maximum cache size to 10 GB:
\r
1095 max_size = 10G</code></pre>
\r
1098 <div class="sect2">
\r
1099 <h3 id="_boolean_values">Boolean values</h3>
\r
1100 <div class="paragraph"><p>Some settings are boolean values (i.e. truth values). In a configuration file,
\r
1101 such values must be set to the string <strong>true</strong> or <strong>false</strong>. For the corresponding
\r
1102 environment variables, the semantics are a bit different: a set environment
\r
1103 variable means “true” (even if set to the empty string), the following
\r
1104 case-insensitive negative values are considered an error (rather than
\r
1105 surprising the user): <strong>0</strong>, <strong>false</strong>, <strong>disable</strong> and <strong>no</strong>, and an unset
\r
1106 environment variable means “false”. Each boolean environment variable also
\r
1107 has a negated form starting with <strong>CCACHE_NO</strong>. For example, <strong>CCACHE_COMPRESS</strong>
\r
1108 can be set to force compression and <strong>CCACHE_NOCOMPRESS</strong> can be set to force no
\r
1109 compression.</p></div>
\r
1111 <div class="sect2">
\r
1112 <h3 id="_configuration_settings">Configuration settings</h3>
\r
1113 <div class="paragraph"><p>Below is a list of available configuration settings. The corresponding
\r
1114 environment variable name is indicated in parentheses after each configuration
\r
1115 setting key.</p></div>
\r
1116 <div class="dlist"><dl>
\r
1117 <dt class="hdlist1">
\r
1118 <strong>base_dir</strong> (<strong>CCACHE_BASEDIR</strong>)
\r
1122 This setting should be an absolute path to a directory. ccache then
\r
1123 rewrites absolute paths into relative paths before computing the hash that
\r
1124 identifies the compilation, but only for paths under the specified
\r
1125 directory. If set to the empty string (which is the default), no rewriting
\r
1126 is done. A typical path to use as the base directory is your home directory
\r
1127 or another directory that is a parent of your build directories. Don’t use
\r
1128 <code>/</code> as the base directory since that will make ccache also rewrite paths to
\r
1129 system header files, which doesn’t gain anything.
\r
1131 <div class="paragraph"><p>See also the discussion under <a href="#_compiling_in_different_directories">COMPILING IN DIFFERENT DIRECTORIES</a>.</p></div>
\r
1133 <dt class="hdlist1">
\r
1134 <strong>cache_dir</strong> (<strong>CCACHE_DIR</strong>)
\r
1138 This setting specifies where ccache will keep its cached compiler outputs.
\r
1139 It will only take effect if set in the system-wide configuration file or as
\r
1140 an environment variable. The default is <strong>$HOME/.ccache</strong>.
\r
1143 <dt class="hdlist1">
\r
1144 <strong>cache_dir_levels</strong> (<strong>CCACHE_NLEVELS</strong>)
\r
1148 This setting allows you to choose the number of directory levels in the
\r
1149 cache directory. The default is 2. The minimum is 1 and the maximum is 8.
\r
1152 <dt class="hdlist1">
\r
1153 <strong>compiler</strong> (<strong>CCACHE_COMPILER</strong> or (deprecated) <strong>CCACHE_CC</strong>)
\r
1157 This setting can be used to force the name of the compiler to use. If set
\r
1158 to the empty string (which is the default), ccache works it out from the
\r
1162 <dt class="hdlist1">
\r
1163 <strong>compiler_check</strong> (<strong>CCACHE_COMPILERCHECK</strong>)
\r
1167 By default, ccache includes the modification time (“mtime”) and size of
\r
1168 the compiler in the hash to ensure that results retrieved from the cache
\r
1169 are accurate. This setting can be used to select another strategy. Possible
\r
1172 <div class="openblock">
\r
1173 <div class="content">
\r
1174 <div class="dlist"><dl>
\r
1175 <dt class="hdlist1">
\r
1176 <strong>content</strong>
\r
1180 Hash the content of the compiler binary. This makes ccache very slightly
\r
1181 slower compared to the <strong>mtime</strong> setting, but makes it cope better with
\r
1182 compiler upgrades during a build bootstrapping process.
\r
1185 <dt class="hdlist1">
\r
1186 <strong>mtime</strong>
\r
1190 Hash the compiler’s mtime and size, which is fast. This is the default.
\r
1193 <dt class="hdlist1">
\r
1194 <strong>none</strong>
\r
1198 Don’t hash anything. This may be good for situations where you can safely
\r
1199 use the cached results even though the compiler’s mtime or size has changed
\r
1200 (e.g. if the compiler is built as part of your build system and the
\r
1201 compiler’s source has not changed, or if the compiler only has changes that
\r
1202 don’t affect code generation). You should only use the <strong>none</strong> setting if
\r
1203 you know what you are doing.
\r
1206 <dt class="hdlist1">
\r
1207 <strong>string:value</strong>
\r
1211 Use <strong>value</strong> as the string to calculate hash from. This can be the compiler
\r
1212 revision number you retrieved earlier and set here via environment variable.
\r
1215 <dt class="hdlist1">
\r
1216 <em>a command string</em>
\r
1220 Hash the standard output and standard error output of the specified
\r
1221 command. The string will be split on whitespace to find out the command and
\r
1222 arguments to run. No other interpretation of the command string will be
\r
1223 done, except that the special word <strong>%compiler%</strong> will be replaced with the
\r
1224 path to the compiler. Several commands can be specified with semicolon as
\r
1225 separator. Examples:
\r
1227 <div class="openblock">
\r
1228 <div class="content">
\r
1229 <div class="listingblock">
\r
1230 <div class="content">
\r
1231 <pre><code>%compiler% -v</code></pre>
\r
1233 <div class="listingblock">
\r
1234 <div class="content">
\r
1235 <pre><code>%compiler% -dumpmachine; %compiler% -dumpversion</code></pre>
\r
1237 <div class="paragraph"><p>You should make sure that the specified command is as fast as possible since it
\r
1238 will be run once for each ccache invocation.</p></div>
\r
1239 <div class="paragraph"><p>Identifying the compiler using a command is useful if you want to avoid cache
\r
1240 misses when the compiler has been rebuilt but not changed.</p></div>
\r
1241 <div class="paragraph"><p>Another case is when the compiler (as seen by ccache) actually isn’t the real
\r
1242 compiler but another compiler wrapper — in that case, the default <strong>mtime</strong>
\r
1243 method will hash the mtime and size of the other compiler wrapper, which means
\r
1244 that ccache won’t be able to detect a compiler upgrade. Using a suitable
\r
1245 command to identify the compiler is thus safer, but it’s also slower, so you
\r
1246 should consider continue using the <strong>mtime</strong> method in combination with
\r
1247 the <strong>prefix_command</strong> setting if possible. See
\r
1248 <a href="#_using_ccache_with_other_compiler_wrappers">USING CCACHE WITH OTHER COMPILER WRAPPERS</a>.</p></div>
\r
1254 <dt class="hdlist1">
\r
1255 <strong>compression</strong> (<strong>CCACHE_COMPRESS</strong> or <strong>CCACHE_NOCOMPRESS</strong>, see <a href="#_boolean_values">Boolean values</a> above)
\r
1259 If true, ccache will compress object files and other compiler output it
\r
1260 puts in the cache. However, this setting has no effect on how files are
\r
1261 retrieved from the cache; compressed and uncompressed results will still be
\r
1262 usable regardless of this setting. The default is false.
\r
1265 <dt class="hdlist1">
\r
1266 <strong>compression_level</strong> (<strong>CCACHE_COMPRESSLEVEL</strong>)
\r
1270 This setting determines the level at which ccache will compress object
\r
1271 files. It only has effect if <strong>compression</strong> is enabled. The value defaults
\r
1272 to 6, and must be no lower than 1 (fastest, worst compression) and no
\r
1273 higher than 9 (slowest, best compression).
\r
1276 <dt class="hdlist1">
\r
1277 <strong>cpp_extension</strong> (<strong>CCACHE_EXTENSION</strong>)
\r
1281 This setting can be used to force a certain extension for the intermediate
\r
1282 preprocessed file. The default is to automatically determine the extension
\r
1283 to use for intermediate preprocessor files based on the type of file being
\r
1284 compiled, but that sometimes doesn’t work. For example, when using the
\r
1285 “aCC” compiler on HP-UX, set the cpp extension to <strong>i</strong>.
\r
1288 <dt class="hdlist1">
\r
1289 <strong>debug</strong> (<strong>CCACHE_DEBUG</strong> or <strong>CCACHE_NODEBUG</strong>, see <a href="#_boolean_values">Boolean values</a> above)
\r
1293 If true, enable the debug mode. The debug mode creates per-object debug
\r
1294 files that are helpful when debugging unexpected cache misses. Note however
\r
1295 that ccache performance will be reduced slightly. See
\r
1296 <a href="#_cache_debugging">debugging</a> for more information. The default is false.
\r
1299 <dt class="hdlist1">
\r
1300 <strong>depend_mode</strong> (<strong>CCACHE_DEPEND</strong> or <strong>CCACHE_NODEPEND</strong>, see <a href="#_boolean_values">Boolean values</a> above)
\r
1304 If true, the depend mode will be used. The default is false. See
\r
1305 <a href="#_the_depend_mode">THE DEPEND MODE</a>.
\r
1308 <dt class="hdlist1">
\r
1309 <strong>direct_mode</strong> (<strong>CCACHE_DIRECT</strong> or <strong>CCACHE_NODIRECT</strong>, see <a href="#_boolean_values">Boolean values</a> above)
\r
1313 If true, the direct mode will be used. The default is true. See
\r
1314 <a href="#_the_direct_mode">THE DIRECT MODE</a>.
\r
1317 <dt class="hdlist1">
\r
1318 <strong>disable</strong> (<strong>CCACHE_DISABLE</strong> or <strong>CCACHE_NODISABLE</strong>, see <a href="#_boolean_values">Boolean values</a> above)
\r
1322 When true, ccache will just call the real compiler, bypassing the cache
\r
1323 completely. The default is false.
\r
1326 <dt class="hdlist1">
\r
1327 <strong>extra_files_to_hash</strong> (<strong>CCACHE_EXTRAFILES</strong>)
\r
1331 This setting is a list of paths to files that ccache will include in the
\r
1332 the hash sum that identifies the build. The list separator is semicolon on
\r
1333 Windows systems and colon on other systems.
\r
1336 <dt class="hdlist1">
\r
1337 <strong>hard_link</strong> (<strong>CCACHE_HARDLINK</strong> or <strong>CCACHE_NOHARDLINK</strong>, see <a href="#_boolean_values">Boolean values</a> above)
\r
1341 If true, ccache will attempt to use hard links from the cache directory
\r
1342 when creating the compiler output rather than using a file copy. Hard links
\r
1343 are never made for compressed cache files. This means that you should not
\r
1344 enable compression if you want to use hard links. The default is false.
\r
1346 <div class="admonitionblock">
\r
1349 <div class="title">Warning</div>
\r
1351 <td class="content">Do not enable this option unless you are aware of the consequences.
\r
1352 Using hard links may be slightly faster in some situations, but there are
\r
1353 several pitfalls since the resulting object file will share i-node with the
\r
1354 cached object file:</td>
\r
1357 <div class="olist arabic"><ol class="arabic">
\r
1360 If the resulting object file is modified in any way, the cached object file
\r
1361 will be modified as well. For instance, if you run <code>strip object.o</code> or <code>echo
\r
1362 >object.o</code>, you will corrupt the cache.
\r
1367 Programs that rely on modification times (like “make”) can be confused
\r
1368 since ccache updates the cached files' modification times as part of the
\r
1369 automatic cache size management. This will affect object files in the build
\r
1370 tree as well, which can retrigger the linking step even though nothing
\r
1371 really has changed.
\r
1376 <dt class="hdlist1">
\r
1377 <strong>hash_dir</strong> (<strong>CCACHE_HASHDIR</strong> or <strong>CCACHE_NOHASHDIR</strong>, see <a href="#_boolean_values">Boolean values</a> above)
\r
1381 If true (which is the default), ccache will include the current working
\r
1382 directory (CWD) in the hash that is used to distinguish two compilations
\r
1383 when generating debug info (compiler option <strong>-g</strong> with variations).
\r
1384 Exception: The CWD will not be included in the hash if <strong>base_dir</strong> is set
\r
1385 (and matches the CWD) and the compiler option <strong>-fdebug-prefix-map</strong> is used.
\r
1386 See also the discussion under
\r
1387 <a href="#_compiling_in_different_directories">COMPILING IN DIFFERENT DIRECTORIES</a>.
\r
1389 <div class="paragraph"><p>The reason for including the CWD in the hash by default is to prevent a problem
\r
1390 with the storage of the current working directory in the debug info of an
\r
1391 object file, which can lead ccache to return a cached object file that has the
\r
1392 working directory in the debug info set incorrectly.</p></div>
\r
1393 <div class="paragraph"><p>You can disable this setting to get cache hits when compiling the same source
\r
1394 code in different directories if you don’t mind that CWD in the debug info
\r
1395 might be incorrect.</p></div>
\r
1397 <dt class="hdlist1">
\r
1398 <strong>ignore_headers_in_manifest</strong> (<strong>CCACHE_IGNOREHEADERS</strong>)
\r
1402 This setting is a list of paths to files (or directories with headers) that
\r
1403 ccache will <strong>not</strong> include in the manifest list that makes up the direct
\r
1404 mode. Note that this can cause stale cache hits if those headers do indeed
\r
1405 change. The list separator is semicolon on Windows systems and colon on
\r
1409 <dt class="hdlist1">
\r
1410 <strong>keep_comments_cpp</strong> (<strong>CCACHE_COMMENTS</strong> or <strong>CCACHE_NOCOMMENTS</strong>, see <a href="#_boolean_values">Boolean values</a> above)
\r
1414 If true, ccache will not discard the comments before hashing preprocessor
\r
1415 output. This can be used to check documentation with <strong>-Wdocumentation</strong>.
\r
1418 <dt class="hdlist1">
\r
1419 <strong>limit_multiple</strong> (<strong>CCACHE_LIMIT_MULTIPLE</strong>)
\r
1423 Sets the limit when cleaning up. Files are deleted (in LRU order) until the
\r
1424 levels are below the limit. The default is 0.8 (= 80%). See
\r
1425 <a href="#_automatic_cleanup">AUTOMATIC CLEANUP</a> for more information.
\r
1428 <dt class="hdlist1">
\r
1429 <strong>log_file</strong> (<strong>CCACHE_LOGFILE</strong>)
\r
1433 If set to a file path, ccache will write information on what it is doing to
\r
1434 the specified file. This is useful for tracking down problems.
\r
1437 <dt class="hdlist1">
\r
1438 <strong>max_files</strong> (<strong>CCACHE_MAXFILES</strong>)
\r
1442 This option specifies the maximum number of files to keep in the cache. Use
\r
1443 0 for no limit (which is the default). See also
\r
1444 <a href="#_cache_size_management">CACHE SIZE MANAGEMENT</a>.
\r
1447 <dt class="hdlist1">
\r
1448 <strong>max_size</strong> (<strong>CCACHE_MAXSIZE</strong>)
\r
1452 This option specifies the maximum size of the cache. Use 0 for no limit.
\r
1453 The default value is 5G. Available suffixes: k, M, G, T (decimal) and Ki,
\r
1454 Mi, Gi, Ti (binary). The default suffix is G. See also
\r
1455 <a href="#_cache_size_management">CACHE SIZE MANAGEMENT</a>.
\r
1458 <dt class="hdlist1">
\r
1459 <strong>path</strong> (<strong>CCACHE_PATH</strong>)
\r
1463 If set, ccache will search directories in this list when looking for the
\r
1464 real compiler. The list separator is semicolon on Windows systems and colon
\r
1465 on other systems. If not set, ccache will look for the first executable
\r
1466 matching the compiler name in the normal <strong>PATH</strong> that isn’t a symbolic link
\r
1470 <dt class="hdlist1">
\r
1471 <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
1475 When this option is set, and ccache finds a precompiled header file,
\r
1476 ccache will look for a file with the extension “.sum” added
\r
1477 (e.g. “pre.h.gch.sum”), and if found, it will hash this file instead
\r
1478 of the precompiled header itself to work around the performance
\r
1479 penalty of hashing very large files.
\r
1482 <dt class="hdlist1">
\r
1483 <strong>prefix_command</strong> (<strong>CCACHE_PREFIX</strong>)
\r
1487 This option adds a list of prefixes (separated by space) to the command
\r
1488 line that ccache uses when invoking the compiler. See also
\r
1489 <a href="#_using_ccache_with_other_compiler_wrappers">USING CCACHE WITH OTHER COMPILER WRAPPERS</a>.
\r
1492 <dt class="hdlist1">
\r
1493 <strong>prefix_command_cpp</strong> (<strong>CCACHE_PREFIX_CPP</strong>)
\r
1497 This option adds a list of prefixes (separated by space) to the command
\r
1498 line that ccache uses when invoking the preprocessor.
\r
1501 <dt class="hdlist1">
\r
1502 <strong>read_only</strong> (<strong>CCACHE_READONLY</strong> or <strong>CCACHE_NOREADONLY</strong>, see <a href="#_boolean_values">Boolean values</a> above)
\r
1506 If true, ccache will attempt to use existing cached object files, but it
\r
1507 will not to try to add anything new to the cache. If you are using this
\r
1508 because your ccache directory is read-only, then you need to set
\r
1509 <strong>temporary_dir</strong> as otherwise ccache will fail to create temporary files.
\r
1512 <dt class="hdlist1">
\r
1513 <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
1517 Just like <strong>read_only</strong> except that ccache will only try to retrieve results
\r
1518 from the cache using the direct mode, not the preprocessor mode. See
\r
1519 documentation for <strong>read_only</strong> regarding using a read-only ccache directory.
\r
1522 <dt class="hdlist1">
\r
1523 <strong>recache</strong> (<strong>CCACHE_RECACHE</strong> or <strong>CCACHE_NORECACHE</strong>, see <a href="#_boolean_values">Boolean values</a> above)
\r
1527 If true, ccache will not use any previously stored result. New results will
\r
1528 still be cached, possibly overwriting any pre-existing results.
\r
1531 <dt class="hdlist1">
\r
1532 <strong>run_second_cpp</strong> (<strong>CCACHE_CPP2</strong> or <strong>CCACHE_NOCPP2</strong>, see <a href="#_boolean_values">Boolean values</a> above)
\r
1536 If true, ccache will first run the preprocessor to preprocess the source
\r
1537 code (see <a href="#_the_preprocessor_mode">THE PREPROCESSOR MODE</a>) and then on a
\r
1538 cache miss run the compiler on the source code to get hold of the object
\r
1539 file. This is the default.
\r
1541 <div class="paragraph"><p>If false, ccache will first run preprocessor to preprocess the source code and
\r
1542 then on a cache miss run the compiler on the <em>preprocessed source code</em> instead
\r
1543 of the original source code. This makes cache misses slightly faster since the
\r
1544 source code only has to be preprocessed once. The downside is that some
\r
1545 compilers won’t produce the same result (for instance diagnostics warnings)
\r
1546 when compiling preprocessed source code.</p></div>
\r
1547 <div class="paragraph"><p>A solution to the above mentioned downside is to set <strong>run_second_cpp</strong> to false
\r
1548 and pass <strong>-fdirectives-only</strong> (for GCC) or <strong>-frewrite-includes</strong> (for Clang) to
\r
1549 the compiler. This will cause the compiler to leave the macros and other
\r
1550 preprocessor information, and only process the <strong>#include</strong> directives. When run
\r
1551 in this way, the preprocessor arguments will be passed to the compiler since it
\r
1552 still has to do <em>some</em> preprocessing (like macros).</p></div>
\r
1554 <dt class="hdlist1">
\r
1555 <strong>sloppiness</strong> (<strong>CCACHE_SLOPPINESS</strong>)
\r
1559 By default, ccache tries to give as few false cache hits as possible.
\r
1560 However, in certain situations it’s possible that you know things that
\r
1561 ccache can’t take for granted. This setting makes it possible to tell
\r
1562 ccache to relax some checks in order to increase the hit rate. The value
\r
1563 should be a comma-separated string with options. Available options are:
\r
1565 <div class="openblock">
\r
1566 <div class="content">
\r
1567 <div class="dlist"><dl>
\r
1568 <dt class="hdlist1">
\r
1569 <strong>clang_index_store</strong>
\r
1573 Ignore the Clang compiler option <strong>-index-store-path</strong> and its argument when
\r
1574 computing the manifest hash. This is useful if you use Xcode, which uses an
\r
1575 index store path derived from the local project path. Note that the index
\r
1576 store won’t be updated correctly on cache hits if you enable this option.
\r
1579 <dt class="hdlist1">
\r
1580 <strong>file_macro</strong>
\r
1584 ccache normally includes the input file path in the hash in order to be
\r
1585 able to produce the correct object file if the source code includes a
\r
1586 <code>__FILE__</code> macro. If you know that <code>__FILE__</code> isn’t used in practise, or
\r
1587 don’t care if ccache produces objects where <code>__FILE__</code> is expanded to the
\r
1588 wrong path, you can set <strong>sloppiness</strong> to <strong>file_macro</strong>. ccache will then
\r
1589 exclude the input file path from the hash.
\r
1592 <dt class="hdlist1">
\r
1593 <strong>file_stat_matches</strong>
\r
1597 ccache normally examines a file’s contents to determine whether it matches
\r
1598 the cached version. With this option set, ccache will consider a file as
\r
1599 matching its cached version if the mtimes and ctimes match.
\r
1602 <dt class="hdlist1">
\r
1603 <strong>file_stat_matches_ctime</strong>
\r
1607 Ignore ctimes when <strong>file_stat_matches</strong> is enabled. This can be useful when
\r
1608 backdating files' mtimes in a controlled way.
\r
1611 <dt class="hdlist1">
\r
1612 <strong>include_file_ctime</strong>
\r
1616 By default, ccache also will not cache a file if it includes a header whose
\r
1617 ctime is too new. This option disables that check.
\r
1620 <dt class="hdlist1">
\r
1621 <strong>include_file_mtime</strong>
\r
1625 By default, ccache will not cache a file if it includes a header whose
\r
1626 mtime is too new. This option disables that check.
\r
1629 <dt class="hdlist1">
\r
1630 <strong>locale</strong>
\r
1634 ccache includes the environment variables <strong>LANG</strong>, <strong>LC_ALL</strong>, <strong>LC_CTYPE</strong> and
\r
1635 <strong>LC_MESSAGES</strong> in the hash by default since they may affect localization of
\r
1636 compiler warning messages. Set this option to tell ccache not to do that.
\r
1639 <dt class="hdlist1">
\r
1640 <strong>pch_defines</strong>
\r
1644 Be sloppy about <strong>#define</strong>s when precompiling a header file. See
\r
1645 <a href="#_precompiled_headers">PRECOMPILED HEADERS</a> for more information.
\r
1648 <dt class="hdlist1">
\r
1649 <strong>system_headers</strong>
\r
1653 By default, ccache will also include all system headers in the manifest.
\r
1654 With this option set, ccache will only include system headers in the hash
\r
1655 but not add the system header files to the list of include files.
\r
1658 <dt class="hdlist1">
\r
1659 <strong>time_macros</strong>
\r
1663 Ignore <code>__DATE__</code> and <code>__TIME__</code> being present in the source code.
\r
1668 <div class="paragraph"><p>See the discussion under <a href="#_troubleshooting">TROUBLESHOOTING</a> for more
\r
1669 information.</p></div>
\r
1671 <dt class="hdlist1">
\r
1672 <strong>stats</strong> (<strong>CCACHE_STATS</strong> or <strong>CCACHE_NOSTATS</strong>, see <a href="#_boolean_values">Boolean values</a> above)
\r
1676 If true, ccache will update the statistics counters on each compilation.
\r
1677 The default is true.
\r
1680 <dt class="hdlist1">
\r
1681 <strong>temporary_dir</strong> (<strong>CCACHE_TEMPDIR</strong>)
\r
1685 This setting specifies where ccache will put temporary files. The default
\r
1686 is <strong><cache_dir>/tmp</strong>.
\r
1688 <div class="admonitionblock">
\r
1691 <div class="title">Note</div>
\r
1693 <td class="content">In previous versions of ccache, <strong>CCACHE_TEMPDIR</strong> had to be on the same
\r
1694 filesystem as the <strong>CCACHE_DIR</strong> path, but this requirement has been
\r
1699 <dt class="hdlist1">
\r
1700 <strong>umask</strong> (<strong>CCACHE_UMASK</strong>)
\r
1704 This setting specifies the umask for ccache and all child processes (such
\r
1705 as the compiler). This is mostly useful when you wish to share your cache
\r
1706 with other users. Note that this also affects the file permissions set on
\r
1707 the object files created from your compilations.
\r
1710 <dt class="hdlist1">
\r
1711 <strong>unify</strong> (<strong>CCACHE_UNIFY</strong> or <strong>CCACHE_NOUNIFY</strong>, see <a href="#_boolean_values">Boolean values</a> above)
\r
1715 If true, ccache will use a C/C++ unifier when hashing the preprocessor
\r
1716 output if the <strong>-g</strong> option is not used. The unifier is slower than a normal
\r
1717 hash, so setting this environment variable loses a little bit of speed, but
\r
1718 it means that ccache can take advantage of not recompiling when the changes
\r
1719 to the source code consist of reformatting only. Note that enabling the
\r
1720 unifier changes the hash, so cached compilations produced when the unifier
\r
1721 is enabled cannot be reused when the unifier is disabled, and vice versa.
\r
1722 Enabling the unifier may result in incorrect line number information in
\r
1723 compiler warning messages and expansions of the <code>__LINE__</code> macro.
\r
1730 <div class="sect1">
\r
1731 <h2 id="_cache_size_management">Cache size management</h2>
\r
1732 <div class="sectionbody">
\r
1733 <div class="paragraph"><p>By default, ccache has a 5 GB limit on the total size of files in the cache and
\r
1734 no limit on the number of files. You can set different limits using the
\r
1735 <strong>-M</strong>/<strong>--max-size</strong> and <strong>-F</strong>/<strong>--max-files</strong> options. Use <strong>ccache -s/--show-stats</strong>
\r
1736 to see the cache size and the currently configured limits (in addition to other
\r
1737 various statistics).</p></div>
\r
1738 <div class="paragraph"><p>Cleanup can be triggered in two different ways: automatic and manual.</p></div>
\r
1739 <div class="sect2">
\r
1740 <h3 id="_automatic_cleanup">Automatic cleanup</h3>
\r
1741 <div class="paragraph"><p>ccache maintains counters for various statistics about the cache, including the
\r
1742 size and number of all cached files. In order to improve performance and reduce
\r
1743 issues with concurrent ccache invocations, there is one statistics file for
\r
1744 each of the sixteen subdirectories in the cache.</p></div>
\r
1745 <div class="paragraph"><p>After a new compilation result has been written to the cache, ccache will
\r
1746 update the size and file number statistics for the subdirectory (one of
\r
1747 sixteen) to which the result was written. Then, if the size counter for said
\r
1748 subdirectory is greater than <strong>max_size / 16</strong> or the file number counter is
\r
1749 greater than <strong>max_files / 16</strong>, automatic cleanup is triggered.</p></div>
\r
1750 <div class="paragraph"><p>When automatic cleanup is triggered for a subdirectory in the cache, ccache
\r
1752 <div class="olist arabic"><ol class="arabic">
\r
1755 Count all files in the subdirectory and compute their aggregated size.
\r
1760 Remove files in LRU (least recently used) order until the size is at most
\r
1761 <strong>limit_multiple * max_size / 16</strong> and the number of files is at most
\r
1762 <strong>limit_multiple * max_files / 16</strong>, where <strong>limit_multiple</strong>, <strong>max_size</strong> and
\r
1763 <strong>max_files</strong> are configuration settings.
\r
1768 Set the size and file number counters to match the files that were kept.
\r
1772 <div class="paragraph"><p>The reason for removing more files than just those needed to not exceed the max
\r
1773 limits is that a cleanup is a fairly slow operation, so it would not be a good
\r
1774 idea to trigger it often, like after each cache miss.</p></div>
\r
1776 <div class="sect2">
\r
1777 <h3 id="_manual_cleanup">Manual cleanup</h3>
\r
1778 <div class="paragraph"><p>You can run <strong>ccache -c/--cleanup</strong> to force cleanup of the whole cache, i.e. all
\r
1779 of the sixteen subdirectories. This will recalculate the statistics counters
\r
1780 and make sure that the <strong>max_size</strong> and <strong>max_files</strong> settings are not exceeded.
\r
1781 Note that <strong>limit_multiple</strong> is not taken into account for manual cleanup.</p></div>
\r
1785 <div class="sect1">
\r
1786 <h2 id="_cache_compression">Cache compression</h2>
\r
1787 <div class="sectionbody">
\r
1788 <div class="paragraph"><p>ccache can optionally compress all files it puts into the cache using the
\r
1789 compression library zlib. While this may involve a tiny performance slowdown,
\r
1790 it increases the number of files that fit in the cache. You can turn on
\r
1791 compression with the <strong>compression</strong> configuration setting and you can also tweak
\r
1792 the compression level with <strong>compression_level</strong>.</p></div>
\r
1795 <div class="sect1">
\r
1796 <h2 id="_cache_statistics">Cache statistics</h2>
\r
1797 <div class="sectionbody">
\r
1798 <div class="paragraph"><p><strong>ccache -s/--show-stats</strong> can show the following statistics:</p></div>
\r
1799 <div class="tableblock">
\r
1800 <table rules="all"
\r
1803 cellspacing="0" cellpadding="4">
\r
1804 <col width="30%" />
\r
1805 <col width="70%" />
\r
1808 <th align="left" valign="top">Name </th>
\r
1809 <th align="left" valign="top"> Description</th>
\r
1814 <td align="left" valign="top"><p class="table">autoconf compile/link</p></td>
\r
1815 <td align="left" valign="top"><p class="table">Uncachable compilation or linking by an autoconf test.</p></td>
\r
1818 <td align="left" valign="top"><p class="table">bad compiler arguments</p></td>
\r
1819 <td align="left" valign="top"><p class="table">Malformed compiler argument, e.g. missing a value for an option that requires
\r
1820 an argument or failure to read a file specified by an option argument.</p></td>
\r
1823 <td align="left" valign="top"><p class="table">cache file missing</p></td>
\r
1824 <td align="left" valign="top"><p class="table">A file was unexpectedly missing from the cache. This only happens in rare
\r
1825 situations, e.g. if one ccache instance is about to get a file from the cache
\r
1826 while another instance removed the file as part of cache cleanup.</p></td>
\r
1829 <td align="left" valign="top"><p class="table">cache hit (direct)</p></td>
\r
1830 <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
1833 <td align="left" valign="top"><p class="table">cache hit (preprocessed)</p></td>
\r
1834 <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
1837 <td align="left" valign="top"><p class="table">cache miss</p></td>
\r
1838 <td align="left" valign="top"><p class="table">No result was found.</p></td>
\r
1841 <td align="left" valign="top"><p class="table">cache size</p></td>
\r
1842 <td align="left" valign="top"><p class="table">Current size of the cache.</p></td>
\r
1845 <td align="left" valign="top"><p class="table">called for link</p></td>
\r
1846 <td align="left" valign="top"><p class="table">The compiler was called for linking, not compiling.</p></td>
\r
1849 <td align="left" valign="top"><p class="table">called for preprocessing</p></td>
\r
1850 <td align="left" valign="top"><p class="table">The compiler was called for preprocessing, not compiling.</p></td>
\r
1853 <td align="left" valign="top"><p class="table">can’t use precompiled header</p></td>
\r
1854 <td align="left" valign="top"><p class="table">Preconditions for using <a href="#_precompiled_headers">precompiled headers</a> were not
\r
1855 fulfilled.</p></td>
\r
1858 <td align="left" valign="top"><p class="table">ccache internal error</p></td>
\r
1859 <td align="left" valign="top"><p class="table">Unexpected failure, e.g. due to problems reading/writing the cache.</p></td>
\r
1862 <td align="left" valign="top"><p class="table">cleanups performed</p></td>
\r
1863 <td align="left" valign="top"><p class="table">Number of cleanups performed, either implicitly due to the cache size limit
\r
1864 being reached or due to explicit <strong>ccache -c/--cleanup</strong> calls.</p></td>
\r
1867 <td align="left" valign="top"><p class="table">compile failed</p></td>
\r
1868 <td align="left" valign="top"><p class="table">The compilation failed. No result stored in the cache.</p></td>
\r
1871 <td align="left" valign="top"><p class="table">compiler check failed</p></td>
\r
1872 <td align="left" valign="top"><p class="table">A compiler check program specified by <strong>compiler_check</strong> (<strong>CCACHE_COMPILERCHECK</strong>)
\r
1876 <td align="left" valign="top"><p class="table">compiler produced empty output</p></td>
\r
1877 <td align="left" valign="top"><p class="table">The compiler’s output file (typically an object file) was empty after
\r
1878 compilation.</p></td>
\r
1881 <td align="left" valign="top"><p class="table">compiler produced no output</p></td>
\r
1882 <td align="left" valign="top"><p class="table">The compiler’s output file (typically an object file) was missing after
\r
1883 compilation.</p></td>
\r
1886 <td align="left" valign="top"><p class="table">compiler produced stdout</p></td>
\r
1887 <td align="left" valign="top"><p class="table">The compiler wrote data to standard output. This is something that compilers
\r
1888 normally never do, so ccache is not designed to store such output in the cache.</p></td>
\r
1891 <td align="left" valign="top"><p class="table">couldn’t find the compiler</p></td>
\r
1892 <td align="left" valign="top"><p class="table">The compiler to execute could not be found.</p></td>
\r
1895 <td align="left" valign="top"><p class="table">error hashing extra file</p></td>
\r
1896 <td align="left" valign="top"><p class="table">Failure reading a file specified by <strong>extra_files_to_hash</strong>
\r
1897 (<strong>CCACHE_EXTRAFILES</strong>).</p></td>
\r
1900 <td align="left" valign="top"><p class="table">files in cache</p></td>
\r
1901 <td align="left" valign="top"><p class="table">Current number of files in the cache.</p></td>
\r
1904 <td align="left" valign="top"><p class="table">multiple source files</p></td>
\r
1905 <td align="left" valign="top"><p class="table">The compiler was called to compile multiple source files in one go. This is not
\r
1906 supported by ccache.</p></td>
\r
1909 <td align="left" valign="top"><p class="table">no input file</p></td>
\r
1910 <td align="left" valign="top"><p class="table">No input file was specified to the compiler.</p></td>
\r
1913 <td align="left" valign="top"><p class="table">output to a non-regular file</p></td>
\r
1914 <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
1918 <td align="left" valign="top"><p class="table">output to stdout</p></td>
\r
1919 <td align="left" valign="top"><p class="table">The compiler was instructed to write its output to standard output using <strong>-o
\r
1920 -</strong>. This is not supported by ccache.</p></td>
\r
1923 <td align="left" valign="top"><p class="table">preprocessor error</p></td>
\r
1924 <td align="left" valign="top"><p class="table">Preprocessing the source code using the compiler’s <strong>-E</strong> option failed.</p></td>
\r
1927 <td align="left" valign="top"><p class="table">stats updated</p></td>
\r
1928 <td align="left" valign="top"><p class="table">When statistics were updated the last time.</p></td>
\r
1931 <td align="left" valign="top"><p class="table">stats zeroed</p></td>
\r
1932 <td align="left" valign="top"><p class="table">When <strong>ccache -z</strong> was called the last time.</p></td>
\r
1935 <td align="left" valign="top"><p class="table">unsupported code directive</p></td>
\r
1936 <td align="left" valign="top"><p class="table">Code like the assembler <strong>.incbin</strong> directive was found. This is not supported
\r
1937 by ccache.</p></td>
\r
1940 <td align="left" valign="top"><p class="table">unsupported compiler option</p></td>
\r
1941 <td align="left" valign="top"><p class="table">A compiler option not supported by ccache was found.</p></td>
\r
1944 <td align="left" valign="top"><p class="table">unsupported source language</p></td>
\r
1945 <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
1952 <div class="sect1">
\r
1953 <h2 id="_how_ccache_works">How ccache works</h2>
\r
1954 <div class="sectionbody">
\r
1955 <div class="paragraph"><p>The basic idea is to detect when you are compiling exactly the same code a
\r
1956 second time and reuse the previously produced output. The detection is done by
\r
1957 hashing different kinds of information that should be unique for the
\r
1958 compilation and then using the hash sum to identify the cached output. ccache
\r
1959 uses MD4, a very fast cryptographic hash algorithm, for the hashing. (MD4 is
\r
1960 nowadays too weak to be useful in cryptographic contexts, but it should be safe
\r
1961 enough to be used to identify recompilations.) On a cache hit, ccache is able
\r
1962 to supply all of the correct compiler outputs (including all warnings,
\r
1963 dependency file, etc) from the cache.</p></div>
\r
1964 <div class="paragraph"><p>ccache has two ways of gathering information used to look up results in the
\r
1966 <div class="ulist"><ul>
\r
1969 the <strong>direct mode</strong>, where ccache hashes the source code and include files
\r
1975 the <strong>preprocessor mode</strong>, where ccache runs the preprocessor on the source
\r
1976 code and hashes the result
\r
1980 <div class="paragraph"><p>The direct mode is generally faster since running the preprocessor has some
\r
1981 overhead.</p></div>
\r
1982 <div class="paragraph"><p>If no previous result is detected (i.e., there is a cache miss) using the
\r
1983 direct mode, ccache will fall back to the preprocessor mode unless the <strong>depend
\r
1984 mode</strong> is enabled. In the depend mode, ccache never runs the preprocessor, not
\r
1985 even on cache misses. Read more in <a href="#_the_depend_mode">THE DEPEND MODE</a>
\r
1987 <div class="sect2">
\r
1988 <h3 id="_common_hashed_information">Common hashed information</h3>
\r
1989 <div class="paragraph"><p>The following information is always included in the hash:</p></div>
\r
1990 <div class="ulist"><ul>
\r
1993 the extension used by the compiler for a file with preprocessor output
\r
1994 (normally <strong>.i</strong> for C code and <strong>.ii</strong> for C++ code)
\r
1999 the compiler’s size and modification time (or other compiler-specific
\r
2000 information specified by the <strong>compiler_check</strong> setting)
\r
2005 the name of the compiler
\r
2010 the current directory (if the <strong>hash_dir</strong> setting is enabled)
\r
2015 contents of files specified by the <strong>extra_files_to_hash</strong> setting (if any)
\r
2020 <div class="sect2">
\r
2021 <h3 id="_the_direct_mode">The direct mode</h3>
\r
2022 <div class="paragraph"><p>In the direct mode, the hash is formed of the common information and:</p></div>
\r
2023 <div class="ulist"><ul>
\r
2026 the input source file
\r
2031 the command line options
\r
2035 <div class="paragraph"><p>Based on the hash, a data structure called “manifest” is looked up in the
\r
2036 cache. The manifest contains:</p></div>
\r
2037 <div class="ulist"><ul>
\r
2040 references to cached compilation results (object file, dependency file, etc)
\r
2041 that were produced by previous compilations that matched the hash
\r
2046 paths to the include files that were read at the time the compilation results
\r
2047 were stored in the cache
\r
2052 hash sums of the include files at the time the compilation results were
\r
2053 stored in the cache
\r
2057 <div class="paragraph"><p>The current contents of the include files are then hashed and compared to the
\r
2058 information in the manifest. If there is a match, ccache knows the result of
\r
2059 the compilation. If there is no match, ccache falls back to running the
\r
2060 preprocessor. The output from the preprocessor is parsed to find the include
\r
2061 files that were read. The paths and hash sums of those include files are then
\r
2062 stored in the manifest along with information about the produced compilation
\r
2064 <div class="paragraph"><p>There is a catch with the direct mode: header files that were used by the
\r
2065 compiler are recorded, but header files that were <strong>not</strong> used, but would have
\r
2066 been used if they existed, are not. So, when ccache checks if a result can be
\r
2067 taken from the cache, it currently can’t check if the existence of a new header
\r
2068 file should invalidate the result. In practice, the direct mode is safe to use
\r
2069 in the absolute majority of cases.</p></div>
\r
2070 <div class="paragraph"><p>The direct mode will be disabled if any of the following holds:</p></div>
\r
2071 <div class="ulist"><ul>
\r
2074 the configuration setting <strong>direct_mode</strong> is false
\r
2079 a modification time of one of the include files is too new (needed to avoid a
\r
2085 a compiler option not supported by the direct mode is used:
\r
2087 <div class="ulist"><ul>
\r
2090 a <strong>-Wp,<em>X</em></strong> compiler option other than <strong>-Wp,-MD,<em>path</em></strong>,
\r
2091 <strong>-Wp,-MMD,<em>path</em></strong> and <strong>-Wp,-D_define_</strong>
\r
2096 <strong>-Xpreprocessor</strong>
\r
2103 the string <code>__TIME__</code> is present in the source code
\r
2108 <div class="sect2">
\r
2109 <h3 id="_the_preprocessor_mode">The preprocessor mode</h3>
\r
2110 <div class="paragraph"><p>In the preprocessor mode, the hash is formed of the common information and:</p></div>
\r
2111 <div class="ulist"><ul>
\r
2114 the preprocessor output from running the compiler with <strong>-E</strong>
\r
2119 the command line options except options that affect include files (<strong>-I</strong>,
\r
2120 <strong>-include</strong>, <strong>-D</strong>, etc; the theory is that these options will change the
\r
2121 preprocessor output if they have any effect at all)
\r
2126 any standard error output generated by the preprocessor
\r
2130 <div class="paragraph"><p>Based on the hash, the cached compilation result can be looked up directly in
\r
2131 the cache.</p></div>
\r
2133 <div class="sect2">
\r
2134 <h3 id="_the_depend_mode">The depend mode</h3>
\r
2135 <div class="paragraph"><p>If the depend mode is enabled, ccache will not use the preprocessor at all. The
\r
2136 hash used to identify results in the cache will be based on the direct mode
\r
2137 hash described above plus information about include files read from the
\r
2138 dependency file generated by the compiler with <strong>-MD</strong> or <strong>-MMD</strong>.</p></div>
\r
2139 <div class="paragraph"><p>Advantages:</p></div>
\r
2140 <div class="ulist"><ul>
\r
2143 The ccache overhead of a cache miss will be much smaller.
\r
2148 Not running the preprocessor at all can be good if compilation is performed
\r
2149 remotely, for instance when using distcc or similar; ccache then won’t make
\r
2150 potentially costly preprocessor calls on the local machine.
\r
2154 <div class="paragraph"><p>Disadvantages:</p></div>
\r
2155 <div class="ulist"><ul>
\r
2158 The cache hit rate will likely be lower since any change to compiler options
\r
2159 or source code will make the hash different. Compare this with the default
\r
2160 setup where ccache will fall back to the preprocessor mode, which is tolerant
\r
2161 to some types of changes of compiler options and source code changes.
\r
2166 The manifest entries will include system header files as well, thus slowing
\r
2167 down cache hits slightly.
\r
2171 <div class="paragraph"><p>The depend mode will be disabled if any of the following holds:</p></div>
\r
2172 <div class="ulist"><ul>
\r
2175 the configuration setting <strong>depend_mode</strong> is false
\r
2180 the configuration setting <strong>run_second_cpp</strong> is false
\r
2185 the configuration setting <strong>unify</strong> is true
\r
2190 the compiler is not generating dependencies using <strong>-MD</strong> or <strong>-MMD</strong>
\r
2197 <div class="sect1">
\r
2198 <h2 id="_cache_debugging">Cache debugging</h2>
\r
2199 <div class="sectionbody">
\r
2200 <div class="paragraph"><p>To find out what information ccache actually is hashing, you can enable the
\r
2201 debug mode via the configuration setting <strong>debug</strong> or by setting <strong>CCACHE_DEBUG</strong>
\r
2202 in the environment. This can be useful if you are investigating why you don’t
\r
2203 get cache hits. Note that performance will be reduced slightly.</p></div>
\r
2204 <div class="paragraph"><p>When the debug mode is enabled, ccache will create up to five additional files
\r
2205 next to the object file:</p></div>
\r
2206 <div class="tableblock">
\r
2207 <table rules="all"
\r
2210 cellspacing="0" cellpadding="4">
\r
2211 <col width="30%" />
\r
2212 <col width="70%" />
\r
2215 <th align="left" valign="top">Filename </th>
\r
2216 <th align="left" valign="top"> Description</th>
\r
2221 <td align="left" valign="top"><p class="table"><strong><objectfile>.ccache-input-c</strong></p></td>
\r
2222 <td align="left" valign="top"><p class="table">Binary input hashed by both the direct mode and the preprocessor mode.</p></td>
\r
2225 <td align="left" valign="top"><p class="table"><strong><objectfile>.ccache-input-d</strong></p></td>
\r
2226 <td align="left" valign="top"><p class="table">Binary input only hashed by the direct mode.</p></td>
\r
2229 <td align="left" valign="top"><p class="table"><strong><objectfile>.ccache-input-p</strong></p></td>
\r
2230 <td align="left" valign="top"><p class="table">Binary input only hashed by the preprocessor mode.</p></td>
\r
2233 <td align="left" valign="top"><p class="table"><strong><objectfile>.ccache-input-text</strong></p></td>
\r
2234 <td align="left" valign="top"><p class="table">Human-readable combined diffable text version of the three files above.</p></td>
\r
2237 <td align="left" valign="top"><p class="table"><strong><objectfile>.ccache-log</strong></p></td>
\r
2238 <td align="left" valign="top"><p class="table">Log for this object file.</p></td>
\r
2243 <div class="paragraph"><p>In the direct mode, ccache uses the MD4 hash of the <strong>ccache-input-c</strong>
\r
2244 + <strong>ccache-input-d</strong> data (where <strong>+</strong> means concatenation), while the
\r
2245 <strong>ccache-input-c</strong> + <strong>ccache-input-p</strong> data is used in the preprocessor mode.</p></div>
\r
2246 <div class="paragraph"><p>The <strong>ccache-input-text</strong> file is a combined text version of the three
\r
2247 binary input files. It has three sections (“COMMON”, “DIRECT MODE” and
\r
2248 “PREPROCESSOR MODE”), which is turn contain annotations that say what kind of
\r
2249 data comes next.</p></div>
\r
2250 <div class="paragraph"><p>To debug why you don’t get an expected cache hit for an object file, you can do
\r
2251 something like this:</p></div>
\r
2252 <div class="olist arabic"><ol class="arabic">
\r
2255 Build with debug mode enabled.
\r
2260 Save the <strong><objectfile>.ccache-*</strong> files.
\r
2265 Build again with debug mode enabled.
\r
2270 Compare <strong><objectfile>.ccache-input-text</strong> for the two builds. This together
\r
2271 with the <strong><objectfile>.ccache-log</strong> files should give you some clues about
\r
2272 what is happening.
\r
2278 <div class="sect1">
\r
2279 <h2 id="_compiling_in_different_directories">Compiling in different directories</h2>
\r
2280 <div class="sectionbody">
\r
2281 <div class="paragraph"><p>Some information included in the hash that identifies a unique compilation can
\r
2282 contain absolute paths:</p></div>
\r
2283 <div class="ulist"><ul>
\r
2286 The preprocessed source code may contain absolute paths to include files if
\r
2287 the compiler option <strong>-g</strong> is used or if absolute paths are given to <strong>-I</strong> and
\r
2288 similar compiler options.
\r
2293 Paths specified by compiler options (such as <strong>-I</strong>, <strong>-MF</strong>, etc) on the command
\r
2294 line may be absolute.
\r
2299 The source code file path may be absolute, and that path may substituted for
\r
2300 <code>__FILE__</code> macros in the source code or included in warnings emitted to
\r
2301 standard error by the preprocessor.
\r
2305 <div class="paragraph"><p>This means that if you compile the same code in different locations, you can’t
\r
2306 share compilation results between the different build directories since you get
\r
2307 cache misses because of the absolute build directory paths that are part of the
\r
2309 <div class="paragraph"><p>Here’s what can be done to enable cache hits between different build
\r
2310 directories:</p></div>
\r
2311 <div class="ulist"><ul>
\r
2314 If you build with <strong>-g</strong> (or similar) to add debug information to the object
\r
2315 file, you must either:
\r
2317 <div class="openblock">
\r
2318 <div class="content">
\r
2319 <div class="ulist"><ul>
\r
2322 use the <strong>-fdebug-prefix-map=<em>old</em>=<em>new</em></strong> option for relocating debug info to
\r
2323 a common prefix (e.g. <strong>-fdebug-prefix-map=$PWD=.</strong>); or
\r
2328 set <strong>hash_dir = false</strong>.
\r
2336 If you use absolute paths anywhere on the command line (e.g. the source code
\r
2337 file path or an argument to compiler options like <strong>-I</strong> and <strong>-MF</strong>), you must
\r
2338 to set <strong>base_dir</strong> to an absolute path to a “base directory”. ccache will
\r
2339 then rewrite absolute paths under that directory to relative before computing
\r
2346 <div class="sect1">
\r
2347 <h2 id="_precompiled_headers">Precompiled headers</h2>
\r
2348 <div class="sectionbody">
\r
2349 <div class="paragraph"><p>ccache has support for GCC’s precompiled headers. However, you have to do some
\r
2350 things to make it work properly:</p></div>
\r
2351 <div class="ulist"><ul>
\r
2354 You must set <strong>sloppiness</strong> to <strong>pch_defines,time_macros</strong>. The reason is that
\r
2355 ccache can’t tell whether <code>__TIME__</code> or <code>__DATE__</code> is used when using a
\r
2356 precompiled header. Further, it can’t detect changes in <strong>#define</strong>s in the
\r
2357 source code because of how preprocessing works in combination with
\r
2358 precompiled headers.
\r
2365 <div class="openblock">
\r
2366 <div class="content">
\r
2367 <div class="ulist"><ul>
\r
2370 use the <strong>-include</strong> compiler option to include the precompiled header
\r
2371 (i.e., don’t use <strong>#include</strong> in the source code to include the header); or
\r
2376 (for the Clang compiler) use the <strong>-include-pch</strong> compiler option to include
\r
2377 the PCH file generated from the precompiled header; or
\r
2382 add the <strong>-fpch-preprocess</strong> compiler option when compiling.
\r
2386 <div class="paragraph"><p>If you don’t do this, either the non-precompiled version of the header file
\r
2387 will be used (if available) or ccache will fall back to running the real
\r
2388 compiler and increase the statistics counter “preprocessor error” (if the
\r
2389 non-precompiled header file is not available).</p></div>
\r
2395 <div class="sect1">
\r
2396 <h2 id="_sharing_a_cache">Sharing a cache</h2>
\r
2397 <div class="sectionbody">
\r
2398 <div class="paragraph"><p>A group of developers can increase the cache hit rate by sharing a cache
\r
2399 directory. To share a cache without unpleasant side effects, the following
\r
2400 conditions should to be met:</p></div>
\r
2401 <div class="ulist"><ul>
\r
2404 Use the same cache directory.
\r
2409 Make sure that the configuration setting <strong>hard_link</strong> is false (which is the
\r
2415 Make sure that all users are in the same group.
\r
2420 Set the configuration setting <strong>umask</strong> to 002. This ensures that cached files
\r
2421 are accessible to everyone in the group.
\r
2426 Make sure that all users have write permission in the entire cache directory
\r
2427 (and that you trust all users of the shared cache).
\r
2432 Make sure that the setgid bit is set on all directories in the cache. This
\r
2433 tells the filesystem to inherit group ownership for new directories. The
\r
2434 following command might be useful for this:
\r
2436 <div class="openblock">
\r
2437 <div class="content">
\r
2438 <div class="listingblock">
\r
2439 <div class="content">
\r
2440 <pre><code>find $CCACHE_DIR -type d | xargs chmod g+s</code></pre>
\r
2445 <div class="paragraph"><p>The reason to avoid the hard link mode is that the hard links cause unwanted
\r
2446 side effects, as all links to a cached file share the file’s modification
\r
2447 timestamp. This results in false dependencies to be triggered by
\r
2448 timestamp-based build systems whenever another user links to an existing file.
\r
2449 Typically, users will see that their libraries and binaries are relinked
\r
2450 without reason.</p></div>
\r
2451 <div class="paragraph"><p>You may also want to make sure that a base directory is set appropriately, as
\r
2452 discussed in a previous section.</p></div>
\r
2455 <div class="sect1">
\r
2456 <h2 id="_sharing_a_cache_on_nfs">Sharing a cache on NFS</h2>
\r
2457 <div class="sectionbody">
\r
2458 <div class="paragraph"><p>It is possible to put the cache directory on an NFS filesystem (or similar
\r
2459 filesystems), but keep in mind that:</p></div>
\r
2460 <div class="ulist"><ul>
\r
2463 Having the cache on NFS may slow down compilation. Make sure to do some
\r
2464 benchmarking to see if it’s worth it.
\r
2469 ccache hasn’t been tested very thoroughly on NFS.
\r
2473 <div class="paragraph"><p>A tip is to set <strong>temporary_dir</strong> to a directory on the local host to avoid NFS
\r
2474 traffic for temporary files.</p></div>
\r
2477 <div class="sect1">
\r
2478 <h2 id="_using_ccache_with_other_compiler_wrappers">Using ccache with other compiler wrappers</h2>
\r
2479 <div class="sectionbody">
\r
2480 <div class="paragraph"><p>The recommended way of combining ccache with another compiler wrapper (such as
\r
2481 “distcc”) is by letting ccache execute the compiler wrapper. This is
\r
2482 accomplished by defining the configuration setting <strong>prefix_command</strong>, for
\r
2483 example by setting the environment variable <strong>CCACHE_PREFIX</strong> to the name of the
\r
2484 wrapper (e.g. <strong>distcc</strong>). ccache will then prefix the command line with the
\r
2485 specified command when running the compiler. To specify several prefix
\r
2486 commands, set <strong>prefix_command</strong> to a colon-separated list of commands.</p></div>
\r
2487 <div class="paragraph"><p>Unless you set <strong>compiler_check</strong> to a suitable command (see the description of
\r
2488 that configuration option), it is not recommended to use the form <strong>ccache
\r
2489 anotherwrapper compiler args</strong> as the compilation command. It’s also not
\r
2490 recommended to use the masquerading technique for the other compiler wrapper.
\r
2491 The reason is that by default, ccache will in both cases hash the mtime and
\r
2492 size of the other wrapper instead of the real compiler, which means that:</p></div>
\r
2493 <div class="ulist"><ul>
\r
2496 Compiler upgrades will not be detected properly.
\r
2501 The cached results will not be shared between compilations with and without
\r
2502 the other wrapper.
\r
2506 <div class="paragraph"><p>Another minor thing is that if <strong>prefix_command</strong> is used, ccache will not invoke
\r
2507 the other wrapper when running the preprocessor, which increases performance.
\r
2508 You can use the <strong>prefix_command_cpp</strong> configuration setting if you also want to
\r
2509 invoke the other wrapper when doing preprocessing (normally by adding <strong>-E</strong>).</p></div>
\r
2512 <div class="sect1">
\r
2513 <h2 id="_caveats">Caveats</h2>
\r
2514 <div class="sectionbody">
\r
2515 <div class="ulist"><ul>
\r
2518 The direct mode fails to pick up new header files in some rare scenarios. See
\r
2519 <a href="#_the_direct_mode">THE DIRECT MODE</a> above.
\r
2524 When run via ccache, warning messages produced by GCC 4.9 and newer will only
\r
2525 be colored when the environment variable <strong>GCC_COLORS</strong> is set. An alternative
\r
2526 to setting <strong>GCC_COLORS</strong> is to pass <code>-fdiagnostics-color</code> explicitly when
\r
2527 compiling (but then color codes will also be present when redirecting stderr
\r
2533 If ccache guesses that the compiler may emit colored warnings, then a
\r
2534 compilation with stderr referring to a TTY will be considered different from
\r
2535 a compilation with a redirected stderr, thus not sharing cache entries. This
\r
2536 happens for clang by default and for GCC when <strong>GCC_COLORS</strong> is set as
\r
2537 mentioned above. If you want to share cache hits, you can pass
\r
2538 <code>-f[no-]diagnostics-color</code> (GCC) or <code>-f[no-]color-diagnostics</code> (clang)
\r
2539 explicitly when compiling (but then color codes will be either on or off for
\r
2540 both the TTY and the redirected case).
\r
2546 <div class="sect1">
\r
2547 <h2 id="_troubleshooting">Troubleshooting</h2>
\r
2548 <div class="sectionbody">
\r
2549 <div class="sect2">
\r
2550 <h3 id="_general">General</h3>
\r
2551 <div class="paragraph"><p>A general tip for getting information about what ccache is doing is to enable
\r
2552 debug logging by setting the configuration option <strong>debug</strong> (or the environment
\r
2553 variable <strong>CCACHE_DEBUG</strong>); see <a href="#_cache_debugging">debugging</a> for more
\r
2554 information. Another way of keeping track of what is happening is to check the
\r
2555 output of <strong>ccache -s</strong>.</p></div>
\r
2557 <div class="sect2">
\r
2558 <h3 id="_performance">Performance</h3>
\r
2559 <div class="paragraph"><p>ccache has been written to perform well out of the box, but sometimes you may
\r
2560 have to do some adjustments of how you use the compiler and ccache in order to
\r
2561 improve performance.</p></div>
\r
2562 <div class="paragraph"><p>Since ccache works best when I/O is fast, put the cache directory on a fast
\r
2563 storage device if possible. Having lots of free memory so that files in the
\r
2564 cache directory stay in the disk cache is also preferable.</p></div>
\r
2565 <div class="paragraph"><p>A good way of monitoring how well ccache works is to run <strong>ccache -s</strong> before and
\r
2566 after your build and then compare the statistics counters. Here are some common
\r
2567 problems and what may be done to increase the hit rate:</p></div>
\r
2568 <div class="ulist"><ul>
\r
2571 If “cache hit (preprocessed)” has been incremented instead of “cache hit
\r
2572 (direct)”, ccache has fallen back to preprocessor mode, which is generally
\r
2573 slower. Some possible reasons are:
\r
2575 <div class="ulist"><ul>
\r
2578 The source code has been modified in such a way that the preprocessor output
\r
2584 Compiler arguments that are hashed in the direct mode but not in the
\r
2585 preprocessor mode have changed (<strong>-I</strong>, <strong>-include</strong>, <strong>-D</strong>, etc) and they didn’t
\r
2586 affect the preprocessor output.
\r
2591 The compiler option <strong>-Xpreprocessor</strong> or <strong>-Wp,<em>X</em></strong> (except <strong>-Wp,-MD,<em>path</em></strong>,
\r
2592 <strong>-Wp,-MMD,<em>path</em></strong>, and <strong>-Wp,-D_define_</strong>) is used.
\r
2597 This was the first compilation with a new value of the base directory
\r
2603 A modification time of one of the include files is too new (created the same
\r
2604 second as the compilation is being done). This check is made to avoid a race
\r
2605 condition. To fix this, create the include file earlier in the build
\r
2606 process, if possible, or set <strong>sloppiness</strong> to <strong>include_file_mtime</strong> if you are
\r
2607 willing to take the risk. (The race condition consists of these events: the
\r
2608 preprocessor is run; an include file is modified by someone; the new include
\r
2609 file is hashed by ccache; the real compiler is run on the preprocessor’s
\r
2610 output, which contains data from the old header file; the wrong object file
\r
2611 is stored in the cache.)
\r
2616 The <code>__TIME__</code> preprocessor macro is (potentially) being used. ccache turns
\r
2617 off direct mode if <code>__TIME__</code> is present in the source code. This is done as
\r
2618 a safety measure since the string indicates that a <code>__TIME__</code> macro <em>may</em>
\r
2619 affect the output. (To be sure, ccache would have to run the preprocessor,
\r
2620 but the sole point of the direct mode is to avoid that.) If you know that
\r
2621 <code>__TIME__</code> isn’t used in practise, or don’t care if ccache produces objects
\r
2622 where <code>__TIME__</code> is expanded to something in the past, you can set
\r
2623 <strong>sloppiness</strong> to <strong>time_macros</strong>.
\r
2628 The <code>__DATE__</code> preprocessor macro is (potentially) being used and the date
\r
2629 has changed. This is similar to how <code>__TIME__</code> is handled. If <code>__DATE__</code> is
\r
2630 present in the source code, ccache hashes the current date in order to be
\r
2631 able to produce the correct object file if the <code>__DATE__</code> macro affects the
\r
2632 output. If you know that <code>__DATE__</code> isn’t used in practise, or don’t care if
\r
2633 ccache produces objects where <code>__DATE__</code> is expanded to something in the
\r
2634 past, you can set <strong>sloppiness</strong> to <strong>time_macros</strong>.
\r
2639 The input file path has changed. ccache normally includes the input file
\r
2640 path in the hash in order to be able to produce the correct object file if
\r
2641 the source code includes a <code>__FILE__</code> macro. If you know that <code>__FILE__</code>
\r
2642 isn’t used in practise, or don’t care if ccache produces objects where
\r
2643 <code>__FILE__</code> is expanded to the wrong path, you can set <strong>sloppiness</strong> to
\r
2644 <strong>file_macro</strong>. ccache will then exclude the input file path from the hash.
\r
2651 If “cache miss” has been incremented even though the same code has been
\r
2652 compiled and cached before, ccache has either detected that something has
\r
2653 changed anyway or a cleanup has been performed (either explicitly or
\r
2654 implicitly when a cache limit has been reached). Some perhaps unobvious
\r
2655 things that may result in a cache miss are usage of <code>__TIME__</code> or
\r
2656 <code>__DATE__</code> macros, or use of automatically generated code that contains a
\r
2657 timestamp, build counter or other volatile information.
\r
2662 If “multiple source files” has been incremented, it’s an indication that
\r
2663 the compiler has been invoked on several source code files at once. ccache
\r
2664 doesn’t support that. Compile the source code files separately if possible.
\r
2669 If “unsupported compiler option” has been incremented, enable debug logging
\r
2670 and check which option was rejected.
\r
2675 If “preprocessor error” has been incremented, one possible reason is that
\r
2676 precompiled headers are being used. See <a href="#_precompiled_headers">PRECOMPILED HEADERS</a> for how to remedy this.
\r
2681 If “can’t use precompiled header” has been incremented, see
\r
2682 <a href="#_precompiled_headers">PRECOMPILED HEADERS</a>.
\r
2687 <div class="sect2">
\r
2688 <h3 id="_corrupt_object_files">Corrupt object files</h3>
\r
2689 <div class="paragraph"><p>It should be noted that ccache is susceptible to general storage problems. If a
\r
2690 bad object file sneaks into the cache for some reason, it will of course stay
\r
2691 bad. Some possible reasons for erroneous object files are bad hardware (disk
\r
2692 drive, disk controller, memory, etc), buggy drivers or file systems, a bad
\r
2693 <strong>prefix_command</strong> or compiler wrapper. If this happens, the easiest way of
\r
2694 fixing it is this:</p></div>
\r
2695 <div class="olist arabic"><ol class="arabic">
\r
2698 Build so that the bad object file ends up in the build tree.
\r
2703 Remove the bad object file from the build tree.
\r
2708 Rebuild with <strong>CCACHE_RECACHE</strong> set.
\r
2712 <div class="paragraph"><p>An alternative is to clear the whole cache with <strong>ccache -C</strong> if you don’t mind
\r
2713 losing other cached results.</p></div>
\r
2714 <div class="paragraph"><p>There are no reported issues about ccache producing broken object files
\r
2715 reproducibly. That doesn’t mean it can’t happen, so if you find a repeatable
\r
2716 case, please report it.</p></div>
\r
2720 <div class="sect1">
\r
2721 <h2 id="_more_information">More information</h2>
\r
2722 <div class="sectionbody">
\r
2723 <div class="paragraph"><p>Credits, mailing list information, bug reporting instructions, source code,
\r
2724 etc, can be found on ccache’s web site: <a href="https://ccache.dev">https://ccache.dev</a>.</p></div>
\r
2727 <div class="sect1">
\r
2728 <h2 id="_author">Author</h2>
\r
2729 <div class="sectionbody">
\r
2730 <div class="paragraph"><p>ccache was originally written by Andrew Tridgell and is currently developed and
\r
2731 maintained by Joel Rosdahl. See AUTHORS.txt or AUTHORS.html and
\r
2732 <a href="https://ccache.dev/credits.html">https://ccache.dev/credits.html</a> for a list of contributors.</p></div>
\r
2736 <div id="footnotes"><hr /></div>
\r
2738 <div id="footer-text">
\r
2741 2019-04-23 21:35:11 CEST
\r
projects / platform / upstream / ccache.git / blob