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.6</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>-F, --max-files</code></strong>=<em>N</em>
\r
914 Set the maximum number of files allowed in the cache. Use 0 for no limit.
\r
915 The value is stored in a configuration file in the cache directory and
\r
916 applies to all future compilations.
\r
919 <dt class="hdlist1">
\r
920 <strong><code>-h, --help</code></strong>
\r
924 Print an options summary page.
\r
927 <dt class="hdlist1">
\r
928 <strong><code>-M, --max-size</code></strong>=<em>SIZE</em>
\r
932 Set the maximum size of the files stored in the cache. <em>SIZE</em> should be a
\r
933 number followed by an optional suffix: k, M, G, T (decimal), Ki, Mi, Gi or
\r
934 Ti (binary). The default suffix is G. Use 0 for no limit. The value is
\r
935 stored in a configuration file in the cache directory and applies to all
\r
936 future compilations.
\r
939 <dt class="hdlist1">
\r
940 <strong><code>-o, --set-config</code></strong>=<em>KEY=VALUE</em>
\r
944 Set configuration <em>KEY</em> to <em>VALUE</em>. See <a href="#_configuration">CONFIGURATION</a>
\r
945 for more information.
\r
948 <dt class="hdlist1">
\r
949 <strong><code>-p, --print-config</code></strong>
\r
953 Print current configuration options and from where they originate
\r
954 (environment variable, configuration file or compile-time default).
\r
957 <dt class="hdlist1">
\r
958 <strong><code>-s, --show-stats</code></strong>
\r
962 Print the current statistics summary for the cache.
\r
965 <dt class="hdlist1">
\r
966 <strong><code>-V, --version</code></strong>
\r
970 Print version and copyright information.
\r
973 <dt class="hdlist1">
\r
974 <strong><code>-z, --zero-stats</code></strong>
\r
978 Zero the cache statistics (but not the configuration options).
\r
984 <div class="sect1">
\r
985 <h2 id="_extra_options">Extra options</h2>
\r
986 <div class="sectionbody">
\r
987 <div class="paragraph"><p>When run as a compiler, ccache usually just takes the same command line options
\r
988 as the compiler you are using. The only exception to this is the option
\r
989 <strong>--ccache-skip</strong>. That option can be used to tell ccache to avoid interpreting
\r
990 the next option in any way and to pass it along to the compiler as-is.</p></div>
\r
991 <div class="admonitionblock">
\r
994 <div class="title">Note</div>
\r
996 <td class="content"><strong>--ccache-skip</strong> currently only tells ccache not to interpret the next
\r
997 option as a special compiler option — the option will still be included in the
\r
998 direct mode hash.</td>
\r
1001 <div class="paragraph"><p>The reason this can be important is that ccache does need to parse the command
\r
1002 line and determine what is an input filename and what is a compiler option, as
\r
1003 it needs the input filename to determine the name of the resulting object file
\r
1004 (among other things). The heuristic ccache uses when parsing the command line
\r
1005 is that any argument that exists as a file is treated as an input file name. By
\r
1006 using <strong>--ccache-skip</strong> you can force an option to not be treated as an input
\r
1007 file name and instead be passed along to the compiler as a command line option.</p></div>
\r
1008 <div class="paragraph"><p>Another case where <strong>--ccache-skip</strong> can be useful is if ccache interprets an
\r
1009 option specially but shouldn’t, since the option has another meaning for your
\r
1010 compiler than what ccache thinks.</p></div>
\r
1013 <div class="sect1">
\r
1014 <h2 id="_configuration">Configuration</h2>
\r
1015 <div class="sectionbody">
\r
1016 <div class="paragraph"><p>ccache’s default behavior can be overridden by configuration file settings,
\r
1017 which in turn can be overridden by environment variables with names starting
\r
1018 with <strong>CCACHE_</strong>. ccache normally reads configuration from two files: first a
\r
1019 system-level configuration file and secondly a cache-specific configuration
\r
1020 file. The priority of configuration settings is as follows (where 1 is
\r
1021 highest):</p></div>
\r
1022 <div class="olist arabic"><ol class="arabic">
\r
1025 Environment variables.
\r
1030 The cache-specific configuration file <strong><em><ccachedir></em>/ccache.conf</strong> (typically
\r
1031 <strong>$HOME/.ccache/ccache.conf</strong>).
\r
1036 The system-wide configuration file <strong><em><sysconfdir></em>/ccache.conf</strong> (typically
\r
1037 <strong>/etc/ccache.conf</strong> or <strong>/usr/local/etc/ccache.conf</strong>).
\r
1042 Compile-time defaults.
\r
1046 <div class="paragraph"><p>As a special case, if the environment variable <strong>CCACHE_CONFIGPATH</strong> is set,
\r
1047 ccache reads configuration from the specified path instead of the default
\r
1049 <div class="sect2">
\r
1050 <h3 id="_configuration_file_syntax">Configuration file syntax</h3>
\r
1051 <div class="paragraph"><p>Configuration files are in a simple “key = value” format, one setting per
\r
1052 line. Lines starting with a hash sign are comments. Blank lines are ignored, as
\r
1053 is whitespace surrounding keys and values. Example:</p></div>
\r
1054 <div class="listingblock">
\r
1055 <div class="content">
\r
1056 <pre><code># Set maximum cache size to 10 GB:
\r
1057 max_size = 10G</code></pre>
\r
1060 <div class="sect2">
\r
1061 <h3 id="_boolean_values">Boolean values</h3>
\r
1062 <div class="paragraph"><p>Some settings are boolean values (i.e. truth values). In a configuration file,
\r
1063 such values must be set to the string <strong>true</strong> or <strong>false</strong>. For the corresponding
\r
1064 environment variables, the semantics are a bit different: a set environment
\r
1065 variable means “true” (even if set to the empty string), the following
\r
1066 case-insensitive negative values are considered an error (rather than
\r
1067 surprising the user): <strong>0</strong>, <strong>false</strong>, <strong>disable</strong> and <strong>no</strong>, and an unset
\r
1068 environment variable means “false”. Each boolean environment variable also
\r
1069 has a negated form starting with <strong>CCACHE_NO</strong>. For example, <strong>CCACHE_COMPRESS</strong>
\r
1070 can be set to force compression and <strong>CCACHE_NOCOMPRESS</strong> can be set to force no
\r
1071 compression.</p></div>
\r
1073 <div class="sect2">
\r
1074 <h3 id="_configuration_settings">Configuration settings</h3>
\r
1075 <div class="paragraph"><p>Below is a list of available configuration settings. The corresponding
\r
1076 environment variable name is indicated in parentheses after each configuration
\r
1077 setting key.</p></div>
\r
1078 <div class="dlist"><dl>
\r
1079 <dt class="hdlist1">
\r
1080 <strong>base_dir</strong> (<strong>CCACHE_BASEDIR</strong>)
\r
1084 This setting should be an absolute path to a directory. ccache then
\r
1085 rewrites absolute paths into relative paths before computing the hash that
\r
1086 identifies the compilation, but only for paths under the specified
\r
1087 directory. If set to the empty string (which is the default), no rewriting
\r
1088 is done. A typical path to use as the base directory is your home directory
\r
1089 or another directory that is a parent of your build directories. Don’t use
\r
1090 <code>/</code> as the base directory since that will make ccache also rewrite paths to
\r
1091 system header files, which doesn’t gain anything.
\r
1093 <div class="paragraph"><p>See also the discussion under <a href="#_compiling_in_different_directories">COMPILING IN DIFFERENT DIRECTORIES</a>.</p></div>
\r
1095 <dt class="hdlist1">
\r
1096 <strong>cache_dir</strong> (<strong>CCACHE_DIR</strong>)
\r
1100 This setting specifies where ccache will keep its cached compiler outputs.
\r
1101 It will only take effect if set in the system-wide configuration file or as
\r
1102 an environment variable. The default is <strong>$HOME/.ccache</strong>.
\r
1105 <dt class="hdlist1">
\r
1106 <strong>cache_dir_levels</strong> (<strong>CCACHE_NLEVELS</strong>)
\r
1110 This setting allows you to choose the number of directory levels in the
\r
1111 cache directory. The default is 2. The minimum is 1 and the maximum is 8.
\r
1114 <dt class="hdlist1">
\r
1115 <strong>compiler</strong> (<strong>CCACHE_COMPILER</strong> or (deprecated) <strong>CCACHE_CC</strong>)
\r
1119 This setting can be used to force the name of the compiler to use. If set
\r
1120 to the empty string (which is the default), ccache works it out from the
\r
1124 <dt class="hdlist1">
\r
1125 <strong>compiler_check</strong> (<strong>CCACHE_COMPILERCHECK</strong>)
\r
1129 By default, ccache includes the modification time (“mtime”) and size of
\r
1130 the compiler in the hash to ensure that results retrieved from the cache
\r
1131 are accurate. This setting can be used to select another strategy. Possible
\r
1134 <div class="openblock">
\r
1135 <div class="content">
\r
1136 <div class="dlist"><dl>
\r
1137 <dt class="hdlist1">
\r
1138 <strong>content</strong>
\r
1142 Hash the content of the compiler binary. This makes ccache very slightly
\r
1143 slower compared to the <strong>mtime</strong> setting, but makes it cope better with
\r
1144 compiler upgrades during a build bootstrapping process.
\r
1147 <dt class="hdlist1">
\r
1148 <strong>mtime</strong>
\r
1152 Hash the compiler’s mtime and size, which is fast. This is the default.
\r
1155 <dt class="hdlist1">
\r
1156 <strong>none</strong>
\r
1160 Don’t hash anything. This may be good for situations where you can safely
\r
1161 use the cached results even though the compiler’s mtime or size has changed
\r
1162 (e.g. if the compiler is built as part of your build system and the
\r
1163 compiler’s source has not changed, or if the compiler only has changes that
\r
1164 don’t affect code generation). You should only use the <strong>none</strong> setting if
\r
1165 you know what you are doing.
\r
1168 <dt class="hdlist1">
\r
1169 <strong>string:value</strong>
\r
1173 Use <strong>value</strong> as the string to calculate hash from. This can be the compiler
\r
1174 revision number you retrieved earlier and set here via environment variable.
\r
1177 <dt class="hdlist1">
\r
1178 <em>a command string</em>
\r
1182 Hash the standard output and standard error output of the specified
\r
1183 command. The string will be split on whitespace to find out the command and
\r
1184 arguments to run. No other interpretation of the command string will be
\r
1185 done, except that the special word <strong>%compiler%</strong> will be replaced with the
\r
1186 path to the compiler. Several commands can be specified with semicolon as
\r
1187 separator. Examples:
\r
1189 <div class="openblock">
\r
1190 <div class="content">
\r
1191 <div class="listingblock">
\r
1192 <div class="content">
\r
1193 <pre><code>%compiler% -v</code></pre>
\r
1195 <div class="listingblock">
\r
1196 <div class="content">
\r
1197 <pre><code>%compiler% -dumpmachine; %compiler% -dumpversion</code></pre>
\r
1199 <div class="paragraph"><p>You should make sure that the specified command is as fast as possible since it
\r
1200 will be run once for each ccache invocation.</p></div>
\r
1201 <div class="paragraph"><p>Identifying the compiler using a command is useful if you want to avoid cache
\r
1202 misses when the compiler has been rebuilt but not changed.</p></div>
\r
1203 <div class="paragraph"><p>Another case is when the compiler (as seen by ccache) actually isn’t the real
\r
1204 compiler but another compiler wrapper — in that case, the default <strong>mtime</strong>
\r
1205 method will hash the mtime and size of the other compiler wrapper, which means
\r
1206 that ccache won’t be able to detect a compiler upgrade. Using a suitable
\r
1207 command to identify the compiler is thus safer, but it’s also slower, so you
\r
1208 should consider continue using the <strong>mtime</strong> method in combination with
\r
1209 the <strong>prefix_command</strong> setting if possible. See
\r
1210 <a href="#_using_ccache_with_other_compiler_wrappers">USING CCACHE WITH OTHER COMPILER WRAPPERS</a>.</p></div>
\r
1216 <dt class="hdlist1">
\r
1217 <strong>compression</strong> (<strong>CCACHE_COMPRESS</strong> or <strong>CCACHE_NOCOMPRESS</strong>, see <a href="#_boolean_values">Boolean values</a> above)
\r
1221 If true, ccache will compress object files and other compiler output it
\r
1222 puts in the cache. However, this setting has no effect on how files are
\r
1223 retrieved from the cache; compressed and uncompressed results will still be
\r
1224 usable regardless of this setting. The default is false.
\r
1227 <dt class="hdlist1">
\r
1228 <strong>compression_level</strong> (<strong>CCACHE_COMPRESSLEVEL</strong>)
\r
1232 This setting determines the level at which ccache will compress object
\r
1233 files. It only has effect if <strong>compression</strong> is enabled. The value defaults
\r
1234 to 6, and must be no lower than 1 (fastest, worst compression) and no
\r
1235 higher than 9 (slowest, best compression).
\r
1238 <dt class="hdlist1">
\r
1239 <strong>cpp_extension</strong> (<strong>CCACHE_EXTENSION</strong>)
\r
1243 This setting can be used to force a certain extension for the intermediate
\r
1244 preprocessed file. The default is to automatically determine the extension
\r
1245 to use for intermediate preprocessor files based on the type of file being
\r
1246 compiled, but that sometimes doesn’t work. For example, when using the
\r
1247 “aCC” compiler on HP-UX, set the cpp extension to <strong>i</strong>.
\r
1250 <dt class="hdlist1">
\r
1251 <strong>debug</strong> (<strong>CCACHE_DEBUG</strong> or <strong>CCACHE_NODEBUG</strong>, see <a href="#_boolean_values">Boolean values</a> above)
\r
1255 If true, enable the debug mode. The debug mode creates per-object debug
\r
1256 files that are helpful when debugging unexpected cache misses. Note however
\r
1257 that ccache performance will be reduced slightly. See
\r
1258 <a href="#_cache_debugging">debugging</a> for more information. The default is false.
\r
1261 <dt class="hdlist1">
\r
1262 <strong>depend_mode</strong> (<strong>CCACHE_DEPEND</strong> or <strong>CCACHE_NODEPEND</strong>, see <a href="#_boolean_values">Boolean values</a> above)
\r
1266 If true, the depend mode will be used. The default is false. See
\r
1267 <a href="#_the_depend_mode">THE DEPEND MODE</a>.
\r
1270 <dt class="hdlist1">
\r
1271 <strong>direct_mode</strong> (<strong>CCACHE_DIRECT</strong> or <strong>CCACHE_NODIRECT</strong>, see <a href="#_boolean_values">Boolean values</a> above)
\r
1275 If true, the direct mode will be used. The default is true. See
\r
1276 <a href="#_the_direct_mode">THE DIRECT MODE</a>.
\r
1279 <dt class="hdlist1">
\r
1280 <strong>disable</strong> (<strong>CCACHE_DISABLE</strong> or <strong>CCACHE_NODISABLE</strong>, see <a href="#_boolean_values">Boolean values</a> above)
\r
1284 When true, ccache will just call the real compiler, bypassing the cache
\r
1285 completely. The default is false.
\r
1288 <dt class="hdlist1">
\r
1289 <strong>extra_files_to_hash</strong> (<strong>CCACHE_EXTRAFILES</strong>)
\r
1293 This setting is a list of paths to files that ccache will include in the
\r
1294 the hash sum that identifies the build. The list separator is semicolon on
\r
1295 Windows systems and colon on other systems.
\r
1298 <dt class="hdlist1">
\r
1299 <strong>hard_link</strong> (<strong>CCACHE_HARDLINK</strong> or <strong>CCACHE_NOHARDLINK</strong>, see <a href="#_boolean_values">Boolean values</a> above)
\r
1303 If true, ccache will attempt to use hard links from the cache directory
\r
1304 when creating the compiler output rather than using a file copy. Hard links
\r
1305 are never made for compressed cache files. This means that you should not
\r
1306 enable compression if you want to use hard links. The default is false.
\r
1308 <div class="admonitionblock">
\r
1311 <div class="title">Warning</div>
\r
1313 <td class="content">Do not enable this option unless you are aware of the consequences.
\r
1314 Using hard links may be slightly faster in some situations, but there are
\r
1315 several pitfalls since the resulting object file will share i-node with the
\r
1316 cached object file:</td>
\r
1319 <div class="olist arabic"><ol class="arabic">
\r
1322 If the resulting object file is modified in any way, the cached object file
\r
1323 will be modified as well. For instance, if you run <code>strip object.o</code> or <code>echo
\r
1324 >object.o</code>, you will corrupt the cache.
\r
1329 Programs that rely on modification times (like “make”) can be confused
\r
1330 since ccache updates the cached files' modification times as part of the
\r
1331 automatic cache size management. This will affect object files in the build
\r
1332 tree as well, which can retrigger the linking step even though nothing
\r
1333 really has changed.
\r
1338 <dt class="hdlist1">
\r
1339 <strong>hash_dir</strong> (<strong>CCACHE_HASHDIR</strong> or <strong>CCACHE_NOHASHDIR</strong>, see <a href="#_boolean_values">Boolean values</a> above)
\r
1343 If true (which is the default), ccache will include the current working
\r
1344 directory (CWD) in the hash that is used to distinguish two compilations
\r
1345 when generating debug info (compiler option <strong>-g</strong> with variations).
\r
1346 Exception: The CWD will not be included in the hash if <strong>base_dir</strong> is set
\r
1347 (and matches the CWD) and the compiler option <strong>-fdebug-prefix-map</strong> is used.
\r
1348 See also the discussion under
\r
1349 <a href="#_compiling_in_different_directories">COMPILING IN DIFFERENT DIRECTORIES</a>.
\r
1351 <div class="paragraph"><p>The reason for including the CWD in the hash by default is to prevent a problem
\r
1352 with the storage of the current working directory in the debug info of an
\r
1353 object file, which can lead ccache to return a cached object file that has the
\r
1354 working directory in the debug info set incorrectly.</p></div>
\r
1355 <div class="paragraph"><p>You can disable this setting to get cache hits when compiling the same source
\r
1356 code in different directories if you don’t mind that CWD in the debug info
\r
1357 might be incorrect.</p></div>
\r
1359 <dt class="hdlist1">
\r
1360 <strong>ignore_headers_in_manifest</strong> (<strong>CCACHE_IGNOREHEADERS</strong>)
\r
1364 This setting is a list of paths to files (or directories with headers) that
\r
1365 ccache will <strong>not</strong> include in the manifest list that makes up the direct
\r
1366 mode. Note that this can cause stale cache hits if those headers do indeed
\r
1367 change. The list separator is semicolon on Windows systems and colon on
\r
1371 <dt class="hdlist1">
\r
1372 <strong>keep_comments_cpp</strong> (<strong>CCACHE_COMMENTS</strong> or <strong>CCACHE_NOCOMMENTS</strong>, see <a href="#_boolean_values">Boolean values</a> above)
\r
1376 If true, ccache will not discard the comments before hashing preprocessor
\r
1377 output. This can be used to check documentation with <strong>-Wdocumentation</strong>.
\r
1380 <dt class="hdlist1">
\r
1381 <strong>limit_multiple</strong> (<strong>CCACHE_LIMIT_MULTIPLE</strong>)
\r
1385 Sets the limit when cleaning up. Files are deleted (in LRU order) until the
\r
1386 levels are below the limit. The default is 0.8 (= 80%). See
\r
1387 <a href="#_automatic_cleanup">AUTOMATIC CLEANUP</a> for more information.
\r
1390 <dt class="hdlist1">
\r
1391 <strong>log_file</strong> (<strong>CCACHE_LOGFILE</strong>)
\r
1395 If set to a file path, ccache will write information on what it is doing to
\r
1396 the specified file. This is useful for tracking down problems.
\r
1399 <dt class="hdlist1">
\r
1400 <strong>max_files</strong> (<strong>CCACHE_MAXFILES</strong>)
\r
1404 This option specifies the maximum number of files to keep in the cache. Use
\r
1405 0 for no limit (which is the default). See also
\r
1406 <a href="#_cache_size_management">CACHE SIZE MANAGEMENT</a>.
\r
1409 <dt class="hdlist1">
\r
1410 <strong>max_size</strong> (<strong>CCACHE_MAXSIZE</strong>)
\r
1414 This option specifies the maximum size of the cache. Use 0 for no limit.
\r
1415 The default value is 5G. Available suffixes: k, M, G, T (decimal) and Ki,
\r
1416 Mi, Gi, Ti (binary). The default suffix is G. See also
\r
1417 <a href="#_cache_size_management">CACHE SIZE MANAGEMENT</a>.
\r
1420 <dt class="hdlist1">
\r
1421 <strong>path</strong> (<strong>CCACHE_PATH</strong>)
\r
1425 If set, ccache will search directories in this list when looking for the
\r
1426 real compiler. The list separator is semicolon on Windows systems and colon
\r
1427 on other systems. If not set, ccache will look for the first executable
\r
1428 matching the compiler name in the normal <strong>PATH</strong> that isn’t a symbolic link
\r
1432 <dt class="hdlist1">
\r
1433 <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
1437 When this option is set, and ccache finds a precompiled header file,
\r
1438 ccache will look for a file with the extension “.sum” added
\r
1439 (e.g. “pre.h.gch.sum”), and if found, it will hash this file instead
\r
1440 of the precompiled header itself to work around the performance
\r
1441 penalty of hashing very large files.
\r
1444 <dt class="hdlist1">
\r
1445 <strong>prefix_command</strong> (<strong>CCACHE_PREFIX</strong>)
\r
1449 This option adds a list of prefixes (separated by space) to the command
\r
1450 line that ccache uses when invoking the compiler. See also
\r
1451 <a href="#_using_ccache_with_other_compiler_wrappers">USING CCACHE WITH OTHER COMPILER WRAPPERS</a>.
\r
1454 <dt class="hdlist1">
\r
1455 <strong>prefix_command_cpp</strong> (<strong>CCACHE_PREFIX_CPP</strong>)
\r
1459 This option adds a list of prefixes (separated by space) to the command
\r
1460 line that ccache uses when invoking the preprocessor.
\r
1463 <dt class="hdlist1">
\r
1464 <strong>read_only</strong> (<strong>CCACHE_READONLY</strong> or <strong>CCACHE_NOREADONLY</strong>, see <a href="#_boolean_values">Boolean values</a> above)
\r
1468 If true, ccache will attempt to use existing cached object files, but it
\r
1469 will not to try to add anything new to the cache. If you are using this
\r
1470 because your ccache directory is read-only, then you need to set
\r
1471 <strong>temporary_dir</strong> as otherwise ccache will fail to create temporary files.
\r
1474 <dt class="hdlist1">
\r
1475 <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
1479 Just like <strong>read_only</strong> except that ccache will only try to retrieve results
\r
1480 from the cache using the direct mode, not the preprocessor mode. See
\r
1481 documentation for <strong>read_only</strong> regarding using a read-only ccache directory.
\r
1484 <dt class="hdlist1">
\r
1485 <strong>recache</strong> (<strong>CCACHE_RECACHE</strong> or <strong>CCACHE_NORECACHE</strong>, see <a href="#_boolean_values">Boolean values</a> above)
\r
1489 If true, ccache will not use any previously stored result. New results will
\r
1490 still be cached, possibly overwriting any pre-existing results.
\r
1493 <dt class="hdlist1">
\r
1494 <strong>run_second_cpp</strong> (<strong>CCACHE_CPP2</strong> or <strong>CCACHE_NOCPP2</strong>, see <a href="#_boolean_values">Boolean values</a> above)
\r
1498 If true, ccache will first run the preprocessor to preprocess the source
\r
1499 code (see <a href="#_the_preprocessor_mode">THE PREPROCESSOR MODE</a>) and then on a
\r
1500 cache miss run the compiler on the source code to get hold of the object
\r
1501 file. This is the default.
\r
1503 <div class="paragraph"><p>If false, ccache will first run preprocessor to preprocess the source code and
\r
1504 then on a cache miss run the compiler on the <em>preprocessed source code</em> instead
\r
1505 of the original source code. This makes cache misses slightly faster since the
\r
1506 source code only has to be preprocessed once. The downside is that some
\r
1507 compilers won’t produce the same result (for instance diagnostics warnings)
\r
1508 when compiling preprocessed source code.</p></div>
\r
1509 <div class="paragraph"><p>A solution to the above mentioned downside is to set <strong>run_second_cpp</strong> to false
\r
1510 and pass <strong>-fdirectives-only</strong> (for GCC) or <strong>-frewrite-includes</strong> (for Clang) to
\r
1511 the compiler. This will cause the compiler to leave the macros and other
\r
1512 preprocessor information, and only process the <strong>#include</strong> directives. When run
\r
1513 in this way, the preprocessor arguments will be passed to the compiler since it
\r
1514 still has to do <em>some</em> preprocessing (like macros).</p></div>
\r
1516 <dt class="hdlist1">
\r
1517 <strong>sloppiness</strong> (<strong>CCACHE_SLOPPINESS</strong>)
\r
1521 By default, ccache tries to give as few false cache hits as possible.
\r
1522 However, in certain situations it’s possible that you know things that
\r
1523 ccache can’t take for granted. This setting makes it possible to tell
\r
1524 ccache to relax some checks in order to increase the hit rate. The value
\r
1525 should be a comma-separated string with options. Available options are:
\r
1527 <div class="openblock">
\r
1528 <div class="content">
\r
1529 <div class="dlist"><dl>
\r
1530 <dt class="hdlist1">
\r
1531 <strong>clang_index_store</strong>
\r
1535 Ignore the Clang compiler option <strong>-index-store-path</strong> and its argument when
\r
1536 computing the manifest hash. This is useful if you use Xcode, which uses an
\r
1537 index store path derived from the local project path. Note that the index
\r
1538 store won’t be updated correctly on cache hits if you enable this option.
\r
1541 <dt class="hdlist1">
\r
1542 <strong>file_macro</strong>
\r
1546 ccache normally includes the input file path in the hash in order to be
\r
1547 able to produce the correct object file if the source code includes a
\r
1548 <code>__FILE__</code> macro. If you know that <code>__FILE__</code> isn’t used in practise, or
\r
1549 don’t care if ccache produces objects where <code>__FILE__</code> is expanded to the
\r
1550 wrong path, you can set <strong>sloppiness</strong> to <strong>file_macro</strong>. ccache will then
\r
1551 exclude the input file path from the hash.
\r
1554 <dt class="hdlist1">
\r
1555 <strong>file_stat_matches</strong>
\r
1559 ccache normally examines a file’s contents to determine whether it matches
\r
1560 the cached version. With this option set, ccache will consider a file as
\r
1561 matching its cached version if the mtimes and ctimes match.
\r
1564 <dt class="hdlist1">
\r
1565 <strong>file_stat_matches_ctime</strong>
\r
1569 Ignore ctimes when <strong>file_stat_matches</strong> is enabled. This can be useful when
\r
1570 backdating files' mtimes in a controlled way.
\r
1573 <dt class="hdlist1">
\r
1574 <strong>include_file_ctime</strong>
\r
1578 By default, ccache also will not cache a file if it includes a header whose
\r
1579 ctime is too new. This option disables that check.
\r
1582 <dt class="hdlist1">
\r
1583 <strong>include_file_mtime</strong>
\r
1587 By default, ccache will not cache a file if it includes a header whose
\r
1588 mtime is too new. This option disables that check.
\r
1591 <dt class="hdlist1">
\r
1592 <strong>locale</strong>
\r
1596 ccache includes the environment variables <strong>LANG</strong>, <strong>LC_ALL</strong>, <strong>LC_CTYPE</strong> and
\r
1597 <strong>LC_MESSAGES</strong> in the hash by default since they may affect localization of
\r
1598 compiler warning messages. Set this option to tell ccache not to do that.
\r
1601 <dt class="hdlist1">
\r
1602 <strong>pch_defines</strong>
\r
1606 Be sloppy about <strong>#define</strong>s when precompiling a header file. See
\r
1607 <a href="#_precompiled_headers">PRECOMPILED HEADERS</a> for more information.
\r
1610 <dt class="hdlist1">
\r
1611 <strong>system_headers</strong>
\r
1615 By default, ccache will also include all system headers in the manifest.
\r
1616 With this option set, ccache will only include system headers in the hash
\r
1617 but not add the system header files to the list of include files.
\r
1620 <dt class="hdlist1">
\r
1621 <strong>time_macros</strong>
\r
1625 Ignore <code>__DATE__</code> and <code>__TIME__</code> being present in the source code.
\r
1630 <div class="paragraph"><p>See the discussion under <a href="#_troubleshooting">TROUBLESHOOTING</a> for more
\r
1631 information.</p></div>
\r
1633 <dt class="hdlist1">
\r
1634 <strong>stats</strong> (<strong>CCACHE_STATS</strong> or <strong>CCACHE_NOSTATS</strong>, see <a href="#_boolean_values">Boolean values</a> above)
\r
1638 If true, ccache will update the statistics counters on each compilation.
\r
1639 The default is true.
\r
1642 <dt class="hdlist1">
\r
1643 <strong>temporary_dir</strong> (<strong>CCACHE_TEMPDIR</strong>)
\r
1647 This setting specifies where ccache will put temporary files. The default
\r
1648 is <strong><cache_dir>/tmp</strong>.
\r
1650 <div class="admonitionblock">
\r
1653 <div class="title">Note</div>
\r
1655 <td class="content">In previous versions of ccache, <strong>CCACHE_TEMPDIR</strong> had to be on the same
\r
1656 filesystem as the <strong>CCACHE_DIR</strong> path, but this requirement has been
\r
1661 <dt class="hdlist1">
\r
1662 <strong>umask</strong> (<strong>CCACHE_UMASK</strong>)
\r
1666 This setting specifies the umask for ccache and all child processes (such
\r
1667 as the compiler). This is mostly useful when you wish to share your cache
\r
1668 with other users. Note that this also affects the file permissions set on
\r
1669 the object files created from your compilations.
\r
1672 <dt class="hdlist1">
\r
1673 <strong>unify</strong> (<strong>CCACHE_UNIFY</strong> or <strong>CCACHE_NOUNIFY</strong>, see <a href="#_boolean_values">Boolean values</a> above)
\r
1677 If true, ccache will use a C/C++ unifier when hashing the preprocessor
\r
1678 output if the <strong>-g</strong> option is not used. The unifier is slower than a normal
\r
1679 hash, so setting this environment variable loses a little bit of speed, but
\r
1680 it means that ccache can take advantage of not recompiling when the changes
\r
1681 to the source code consist of reformatting only. Note that enabling the
\r
1682 unifier changes the hash, so cached compilations produced when the unifier
\r
1683 is enabled cannot be reused when the unifier is disabled, and vice versa.
\r
1684 Enabling the unifier may result in incorrect line number information in
\r
1685 compiler warning messages and expansions of the <code>__LINE__</code> macro.
\r
1692 <div class="sect1">
\r
1693 <h2 id="_cache_size_management">Cache size management</h2>
\r
1694 <div class="sectionbody">
\r
1695 <div class="paragraph"><p>By default, ccache has a 5 GB limit on the total size of files in the cache and
\r
1696 no limit on the number of files. You can set different limits using the
\r
1697 <strong>-M</strong>/<strong>--max-size</strong> and <strong>-F</strong>/<strong>--max-files</strong> options. Use <strong>ccache -s/--show-stats</strong>
\r
1698 to see the cache size and the currently configured limits (in addition to other
\r
1699 various statistics).</p></div>
\r
1700 <div class="paragraph"><p>Cleanup can be triggered in two different ways: automatic and manual.</p></div>
\r
1701 <div class="sect2">
\r
1702 <h3 id="_automatic_cleanup">Automatic cleanup</h3>
\r
1703 <div class="paragraph"><p>ccache maintains counters for various statistics about the cache, including the
\r
1704 size and number of all cached files. In order to improve performance and reduce
\r
1705 issues with concurrent ccache invocations, there is one statistics file for
\r
1706 each of the sixteen subdirectories in the cache.</p></div>
\r
1707 <div class="paragraph"><p>After a new compilation result has been written to the cache, ccache will
\r
1708 update the size and file number statistics for the subdirectory (one of
\r
1709 sixteen) to which the result was written. Then, if the size counter for said
\r
1710 subdirectory is greater than <strong>max_size / 16</strong> or the file number counter is
\r
1711 greater than <strong>max_files / 16</strong>, automatic cleanup is triggered.</p></div>
\r
1712 <div class="paragraph"><p>When automatic cleanup is triggered for a subdirectory in the cache, ccache
\r
1714 <div class="olist arabic"><ol class="arabic">
\r
1717 Count all files in the subdirectory and compute their aggregated size.
\r
1722 Remove files in LRU (least recently used) order until the size is at most
\r
1723 <strong>limit_multiple * max_size / 16</strong> and the number of files is at most
\r
1724 <strong>limit_multiple * max_files / 16</strong>, where <strong>limit_multiple</strong>, <strong>max_size</strong> and
\r
1725 <strong>max_files</strong> are configuration settings.
\r
1730 Set the size and file number counters to match the files that were kept.
\r
1734 <div class="paragraph"><p>The reason for removing more files than just those needed to not exceed the max
\r
1735 limits is that a cleanup is a fairly slow operation, so it would not be a good
\r
1736 idea to trigger it often, like after each cache miss.</p></div>
\r
1738 <div class="sect2">
\r
1739 <h3 id="_manual_cleanup">Manual cleanup</h3>
\r
1740 <div class="paragraph"><p>You can run <strong>ccache -c/--cleanup</strong> to force cleanup of the whole cache, i.e. all
\r
1741 of the sixteen subdirectories. This will recalculate the statistics counters
\r
1742 and make sure that the <strong>max_size</strong> and <strong>max_files</strong> settings are not exceeded.
\r
1743 Note that <strong>limit_multiple</strong> is not taken into account for manual cleanup.</p></div>
\r
1747 <div class="sect1">
\r
1748 <h2 id="_cache_compression">Cache compression</h2>
\r
1749 <div class="sectionbody">
\r
1750 <div class="paragraph"><p>ccache can optionally compress all files it puts into the cache using the
\r
1751 compression library zlib. While this may involve a tiny performance slowdown,
\r
1752 it increases the number of files that fit in the cache. You can turn on
\r
1753 compression with the <strong>compression</strong> configuration setting and you can also tweak
\r
1754 the compression level with <strong>compression_level</strong>.</p></div>
\r
1757 <div class="sect1">
\r
1758 <h2 id="_cache_statistics">Cache statistics</h2>
\r
1759 <div class="sectionbody">
\r
1760 <div class="paragraph"><p><strong>ccache -s/--show-stats</strong> can show the following statistics:</p></div>
\r
1761 <div class="tableblock">
\r
1762 <table rules="all"
\r
1765 cellspacing="0" cellpadding="4">
\r
1766 <col width="30%" />
\r
1767 <col width="70%" />
\r
1770 <th align="left" valign="top">Name </th>
\r
1771 <th align="left" valign="top"> Description</th>
\r
1776 <td align="left" valign="top"><p class="table">autoconf compile/link</p></td>
\r
1777 <td align="left" valign="top"><p class="table">Uncachable compilation or linking by an autoconf test.</p></td>
\r
1780 <td align="left" valign="top"><p class="table">bad compiler arguments</p></td>
\r
1781 <td align="left" valign="top"><p class="table">Malformed compiler argument, e.g. missing a value for an option that requires
\r
1782 an argument or failure to read a file specified by an option argument.</p></td>
\r
1785 <td align="left" valign="top"><p class="table">cache file missing</p></td>
\r
1786 <td align="left" valign="top"><p class="table">A file was unexpectedly missing from the cache. This only happens in rare
\r
1787 situations, e.g. if one ccache instance is about to get a file from the cache
\r
1788 while another instance removed the file as part of cache cleanup.</p></td>
\r
1791 <td align="left" valign="top"><p class="table">cache hit (direct)</p></td>
\r
1792 <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
1795 <td align="left" valign="top"><p class="table">cache hit (preprocessed)</p></td>
\r
1796 <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
1799 <td align="left" valign="top"><p class="table">cache miss</p></td>
\r
1800 <td align="left" valign="top"><p class="table">No result was found.</p></td>
\r
1803 <td align="left" valign="top"><p class="table">cache size</p></td>
\r
1804 <td align="left" valign="top"><p class="table">Current size of the cache.</p></td>
\r
1807 <td align="left" valign="top"><p class="table">called for link</p></td>
\r
1808 <td align="left" valign="top"><p class="table">The compiler was called for linking, not compiling.</p></td>
\r
1811 <td align="left" valign="top"><p class="table">called for preprocessing</p></td>
\r
1812 <td align="left" valign="top"><p class="table">The compiler was called for preprocessing, not compiling.</p></td>
\r
1815 <td align="left" valign="top"><p class="table">can’t use precompiled header</p></td>
\r
1816 <td align="left" valign="top"><p class="table">Preconditions for using <a href="#_precompiled_headers">precompiled headers</a> were not
\r
1817 fulfilled.</p></td>
\r
1820 <td align="left" valign="top"><p class="table">ccache internal error</p></td>
\r
1821 <td align="left" valign="top"><p class="table">Unexpected failure, e.g. due to problems reading/writing the cache.</p></td>
\r
1824 <td align="left" valign="top"><p class="table">cleanups performed</p></td>
\r
1825 <td align="left" valign="top"><p class="table">Number of cleanups performed, either implicitly due to the cache size limit
\r
1826 being reached or due to explicit <strong>ccache -c/--cleanup</strong> calls.</p></td>
\r
1829 <td align="left" valign="top"><p class="table">compile failed</p></td>
\r
1830 <td align="left" valign="top"><p class="table">The compilation failed. No result stored in the cache.</p></td>
\r
1833 <td align="left" valign="top"><p class="table">compiler check failed</p></td>
\r
1834 <td align="left" valign="top"><p class="table">A compiler check program specified by <strong>compiler_check</strong> (<strong>CCACHE_COMPILERCHECK</strong>)
\r
1838 <td align="left" valign="top"><p class="table">compiler produced empty output</p></td>
\r
1839 <td align="left" valign="top"><p class="table">The compiler’s output file (typically an object file) was empty after
\r
1840 compilation.</p></td>
\r
1843 <td align="left" valign="top"><p class="table">compiler produced no output</p></td>
\r
1844 <td align="left" valign="top"><p class="table">The compiler’s output file (typically an object file) was missing after
\r
1845 compilation.</p></td>
\r
1848 <td align="left" valign="top"><p class="table">compiler produced stdout</p></td>
\r
1849 <td align="left" valign="top"><p class="table">The compiler wrote data to standard output. This is something that compilers
\r
1850 normally never do, so ccache is not designed to store such output in the cache.</p></td>
\r
1853 <td align="left" valign="top"><p class="table">couldn’t find the compiler</p></td>
\r
1854 <td align="left" valign="top"><p class="table">The compiler to execute could not be found.</p></td>
\r
1857 <td align="left" valign="top"><p class="table">error hashing extra file</p></td>
\r
1858 <td align="left" valign="top"><p class="table">Failure reading a file specified by <strong>extra_files_to_hash</strong>
\r
1859 (<strong>CCACHE_EXTRAFILES</strong>).</p></td>
\r
1862 <td align="left" valign="top"><p class="table">files in cache</p></td>
\r
1863 <td align="left" valign="top"><p class="table">Current number of files in the cache.</p></td>
\r
1866 <td align="left" valign="top"><p class="table">multiple source files</p></td>
\r
1867 <td align="left" valign="top"><p class="table">The compiler was called to compile multiple source files in one go. This is not
\r
1868 supported by ccache.</p></td>
\r
1871 <td align="left" valign="top"><p class="table">no input file</p></td>
\r
1872 <td align="left" valign="top"><p class="table">No input file was specified to the compiler.</p></td>
\r
1875 <td align="left" valign="top"><p class="table">output to a non-regular file</p></td>
\r
1876 <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
1880 <td align="left" valign="top"><p class="table">output to stdout</p></td>
\r
1881 <td align="left" valign="top"><p class="table">The compiler was instructed to write its output to standard output using <strong>-o
\r
1882 -</strong>. This is not supported by ccache.</p></td>
\r
1885 <td align="left" valign="top"><p class="table">preprocessor error</p></td>
\r
1886 <td align="left" valign="top"><p class="table">Preprocessing the source code using the compiler’s <strong>-E</strong> option failed.</p></td>
\r
1889 <td align="left" valign="top"><p class="table">stats updated</p></td>
\r
1890 <td align="left" valign="top"><p class="table">When statistics were updated the last time.</p></td>
\r
1893 <td align="left" valign="top"><p class="table">stats zeroed</p></td>
\r
1894 <td align="left" valign="top"><p class="table">When <strong>ccache -z</strong> was called the last time.</p></td>
\r
1897 <td align="left" valign="top"><p class="table">unsupported code directive</p></td>
\r
1898 <td align="left" valign="top"><p class="table">Code like the assembler <strong>.incbin</strong> directive was found. This is not supported
\r
1899 by ccache.</p></td>
\r
1902 <td align="left" valign="top"><p class="table">unsupported compiler option</p></td>
\r
1903 <td align="left" valign="top"><p class="table">A compiler option not supported by ccache was found.</p></td>
\r
1906 <td align="left" valign="top"><p class="table">unsupported source language</p></td>
\r
1907 <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
1914 <div class="sect1">
\r
1915 <h2 id="_how_ccache_works">How ccache works</h2>
\r
1916 <div class="sectionbody">
\r
1917 <div class="paragraph"><p>The basic idea is to detect when you are compiling exactly the same code a
\r
1918 second time and reuse the previously produced output. The detection is done by
\r
1919 hashing different kinds of information that should be unique for the
\r
1920 compilation and then using the hash sum to identify the cached output. ccache
\r
1921 uses MD4, a very fast cryptographic hash algorithm, for the hashing. (MD4 is
\r
1922 nowadays too weak to be useful in cryptographic contexts, but it should be safe
\r
1923 enough to be used to identify recompilations.) On a cache hit, ccache is able
\r
1924 to supply all of the correct compiler outputs (including all warnings,
\r
1925 dependency file, etc) from the cache.</p></div>
\r
1926 <div class="paragraph"><p>ccache has two ways of gathering information used to look up results in the
\r
1928 <div class="ulist"><ul>
\r
1931 the <strong>direct mode</strong>, where ccache hashes the source code and include files
\r
1937 the <strong>preprocessor mode</strong>, where ccache runs the preprocessor on the source
\r
1938 code and hashes the result
\r
1942 <div class="paragraph"><p>The direct mode is generally faster since running the preprocessor has some
\r
1943 overhead.</p></div>
\r
1944 <div class="paragraph"><p>If no previous result is detected (i.e., there is a cache miss) using the
\r
1945 direct mode, ccache will fall back to the preprocessor mode unless the <strong>depend
\r
1946 mode</strong> is enabled. In the depend mode, ccache never runs the preprocessor, not
\r
1947 even on cache misses. Read more in <a href="#_the_depend_mode">THE DEPEND MODE</a>
\r
1949 <div class="sect2">
\r
1950 <h3 id="_common_hashed_information">Common hashed information</h3>
\r
1951 <div class="paragraph"><p>The following information is always included in the hash:</p></div>
\r
1952 <div class="ulist"><ul>
\r
1955 the extension used by the compiler for a file with preprocessor output
\r
1956 (normally <strong>.i</strong> for C code and <strong>.ii</strong> for C++ code)
\r
1961 the compiler’s size and modification time (or other compiler-specific
\r
1962 information specified by the <strong>compiler_check</strong> setting)
\r
1967 the name of the compiler
\r
1972 the current directory (if the <strong>hash_dir</strong> setting is enabled)
\r
1977 contents of files specified by the <strong>extra_files_to_hash</strong> setting (if any)
\r
1982 <div class="sect2">
\r
1983 <h3 id="_the_direct_mode">The direct mode</h3>
\r
1984 <div class="paragraph"><p>In the direct mode, the hash is formed of the common information and:</p></div>
\r
1985 <div class="ulist"><ul>
\r
1988 the input source file
\r
1993 the command line options
\r
1997 <div class="paragraph"><p>Based on the hash, a data structure called “manifest” is looked up in the
\r
1998 cache. The manifest contains:</p></div>
\r
1999 <div class="ulist"><ul>
\r
2002 references to cached compilation results (object file, dependency file, etc)
\r
2003 that were produced by previous compilations that matched the hash
\r
2008 paths to the include files that were read at the time the compilation results
\r
2009 were stored in the cache
\r
2014 hash sums of the include files at the time the compilation results were
\r
2015 stored in the cache
\r
2019 <div class="paragraph"><p>The current contents of the include files are then hashed and compared to the
\r
2020 information in the manifest. If there is a match, ccache knows the result of
\r
2021 the compilation. If there is no match, ccache falls back to running the
\r
2022 preprocessor. The output from the preprocessor is parsed to find the include
\r
2023 files that were read. The paths and hash sums of those include files are then
\r
2024 stored in the manifest along with information about the produced compilation
\r
2026 <div class="paragraph"><p>There is a catch with the direct mode: header files that were used by the
\r
2027 compiler are recorded, but header files that were <strong>not</strong> used, but would have
\r
2028 been used if they existed, are not. So, when ccache checks if a result can be
\r
2029 taken from the cache, it currently can’t check if the existence of a new header
\r
2030 file should invalidate the result. In practice, the direct mode is safe to use
\r
2031 in the absolute majority of cases.</p></div>
\r
2032 <div class="paragraph"><p>The direct mode will be disabled if any of the following holds:</p></div>
\r
2033 <div class="ulist"><ul>
\r
2036 the configuration setting <strong>direct_mode</strong> is false
\r
2041 a modification time of one of the include files is too new (needed to avoid a
\r
2047 a compiler option not supported by the direct mode is used:
\r
2049 <div class="ulist"><ul>
\r
2052 a <strong>-Wp,<em>X</em></strong> compiler option other than <strong>-Wp,-MD,<em>path</em></strong>,
\r
2053 <strong>-Wp,-MMD,<em>path</em></strong> and <strong>-Wp,-D_define_</strong>
\r
2058 <strong>-Xpreprocessor</strong>
\r
2065 the string <code>__TIME__</code> is present in the source code
\r
2070 <div class="sect2">
\r
2071 <h3 id="_the_preprocessor_mode">The preprocessor mode</h3>
\r
2072 <div class="paragraph"><p>In the preprocessor mode, the hash is formed of the common information and:</p></div>
\r
2073 <div class="ulist"><ul>
\r
2076 the preprocessor output from running the compiler with <strong>-E</strong>
\r
2081 the command line options except options that affect include files (<strong>-I</strong>,
\r
2082 <strong>-include</strong>, <strong>-D</strong>, etc; the theory is that these options will change the
\r
2083 preprocessor output if they have any effect at all)
\r
2088 any standard error output generated by the preprocessor
\r
2092 <div class="paragraph"><p>Based on the hash, the cached compilation result can be looked up directly in
\r
2093 the cache.</p></div>
\r
2095 <div class="sect2">
\r
2096 <h3 id="_the_depend_mode">The depend mode</h3>
\r
2097 <div class="paragraph"><p>If the depend mode is enabled, ccache will not use the preprocessor at all. The
\r
2098 hash used to identify results in the cache will be based on the direct mode
\r
2099 hash described above plus information about include files read from the
\r
2100 dependency file generated by the compiler with <strong>-MD</strong> or <strong>-MMD</strong>.</p></div>
\r
2101 <div class="paragraph"><p>Advantages:</p></div>
\r
2102 <div class="ulist"><ul>
\r
2105 The ccache overhead of a cache miss will be much smaller.
\r
2110 Not running the preprocessor at all can be good if compilation is performed
\r
2111 remotely, for instance when using distcc or similar; ccache then won’t make
\r
2112 potentially costly preprocessor calls on the local machine.
\r
2116 <div class="paragraph"><p>Disadvantages:</p></div>
\r
2117 <div class="ulist"><ul>
\r
2120 The cache hit rate will likely be lower since any change to compiler options
\r
2121 or source code will make the hash different. Compare this with the default
\r
2122 setup where ccache will fall back to the preprocessor mode, which is tolerant
\r
2123 to some types of changes of compiler options and source code changes.
\r
2128 The manifest entries will include system header files as well, thus slowing
\r
2129 down cache hits slightly.
\r
2133 <div class="paragraph"><p>The depend mode will be disabled if any of the following holds:</p></div>
\r
2134 <div class="ulist"><ul>
\r
2137 the configuration setting <strong>depend_mode</strong> is false
\r
2142 the configuration setting <strong>run_second_cpp</strong> is false
\r
2147 the configuration setting <strong>unify</strong> is true
\r
2152 the compiler is not generating dependencies using <strong>-MD</strong> or <strong>-MMD</strong>
\r
2159 <div class="sect1">
\r
2160 <h2 id="_cache_debugging">Cache debugging</h2>
\r
2161 <div class="sectionbody">
\r
2162 <div class="paragraph"><p>To find out what information ccache actually is hashing, you can enable the
\r
2163 debug mode via the configuration setting <strong>debug</strong> or by setting <strong>CCACHE_DEBUG</strong>
\r
2164 in the environment. This can be useful if you are investigating why you don’t
\r
2165 get cache hits. Note that performance will be reduced slightly.</p></div>
\r
2166 <div class="paragraph"><p>When the debug mode is enabled, ccache will create up to five additional files
\r
2167 next to the object file:</p></div>
\r
2168 <div class="tableblock">
\r
2169 <table rules="all"
\r
2172 cellspacing="0" cellpadding="4">
\r
2173 <col width="30%" />
\r
2174 <col width="70%" />
\r
2177 <th align="left" valign="top">Filename </th>
\r
2178 <th align="left" valign="top"> Description</th>
\r
2183 <td align="left" valign="top"><p class="table"><strong><objectfile>.ccache-input-c</strong></p></td>
\r
2184 <td align="left" valign="top"><p class="table">Binary input hashed by both the direct mode and the preprocessor mode.</p></td>
\r
2187 <td align="left" valign="top"><p class="table"><strong><objectfile>.ccache-input-d</strong></p></td>
\r
2188 <td align="left" valign="top"><p class="table">Binary input only hashed by the direct mode.</p></td>
\r
2191 <td align="left" valign="top"><p class="table"><strong><objectfile>.ccache-input-p</strong></p></td>
\r
2192 <td align="left" valign="top"><p class="table">Binary input only hashed by the preprocessor mode.</p></td>
\r
2195 <td align="left" valign="top"><p class="table"><strong><objectfile>.ccache-input-text</strong></p></td>
\r
2196 <td align="left" valign="top"><p class="table">Human-readable combined diffable text version of the three files above.</p></td>
\r
2199 <td align="left" valign="top"><p class="table"><strong><objectfile>.ccache-log</strong></p></td>
\r
2200 <td align="left" valign="top"><p class="table">Log for this object file.</p></td>
\r
2205 <div class="paragraph"><p>In the direct mode, ccache uses the MD4 hash of the <strong>ccache-input-c</strong>
\r
2206 + <strong>ccache-input-d</strong> data (where <strong>+</strong> means concatenation), while the
\r
2207 <strong>ccache-input-c</strong> + <strong>ccache-input-p</strong> data is used in the preprocessor mode.</p></div>
\r
2208 <div class="paragraph"><p>The <strong>ccache-input-text</strong> file is a combined text version of the three
\r
2209 binary input files. It has three sections (“COMMON”, “DIRECT MODE” and
\r
2210 “PREPROCESSOR MODE”), which is turn contain annotations that say what kind of
\r
2211 data comes next.</p></div>
\r
2212 <div class="paragraph"><p>To debug why you don’t get an expected cache hit for an object file, you can do
\r
2213 something like this:</p></div>
\r
2214 <div class="olist arabic"><ol class="arabic">
\r
2217 Build with debug mode enabled.
\r
2222 Save the <strong><objectfile>.ccache-*</strong> files.
\r
2227 Build again with debug mode enabled.
\r
2232 Compare <strong><objectfile>.ccache-input-text</strong> for the two builds. This together
\r
2233 with the <strong><objectfile>.ccache-log</strong> files should give you some clues about
\r
2234 what is happening.
\r
2240 <div class="sect1">
\r
2241 <h2 id="_compiling_in_different_directories">Compiling in different directories</h2>
\r
2242 <div class="sectionbody">
\r
2243 <div class="paragraph"><p>Some information included in the hash that identifies a unique compilation can
\r
2244 contain absolute paths:</p></div>
\r
2245 <div class="ulist"><ul>
\r
2248 The preprocessed source code may contain absolute paths to include files if
\r
2249 the compiler option <strong>-g</strong> is used or if absolute paths are given to <strong>-I</strong> and
\r
2250 similar compiler options.
\r
2255 Paths specified by compiler options (such as <strong>-I</strong>, <strong>-MF</strong>, etc) on the command
\r
2256 line may be absolute.
\r
2261 The source code file path may be absolute, and that path may substituted for
\r
2262 <code>__FILE__</code> macros in the source code or included in warnings emitted to
\r
2263 standard error by the preprocessor.
\r
2267 <div class="paragraph"><p>This means that if you compile the same code in different locations, you can’t
\r
2268 share compilation results between the different build directories since you get
\r
2269 cache misses because of the absolute build directory paths that are part of the
\r
2271 <div class="paragraph"><p>Here’s what can be done to enable cache hits between different build
\r
2272 directories:</p></div>
\r
2273 <div class="ulist"><ul>
\r
2276 If you build with <strong>-g</strong> (or similar) to add debug information to the object
\r
2277 file, you must either:
\r
2279 <div class="openblock">
\r
2280 <div class="content">
\r
2281 <div class="ulist"><ul>
\r
2284 use the <strong>-fdebug-prefix-map=<em>old</em>=<em>new</em></strong> option for relocating debug info to
\r
2285 a common prefix (e.g. <strong>-fdebug-prefix-map=$PWD=.</strong>); or
\r
2290 set <strong>hash_dir = false</strong>.
\r
2298 If you use absolute paths anywhere on the command line (e.g. the source code
\r
2299 file path or an argument to compiler options like <strong>-I</strong> and <strong>-MF</strong>), you must
\r
2300 to set <strong>base_dir</strong> to an absolute path to a “base directory”. ccache will
\r
2301 then rewrite absolute paths under that directory to relative before computing
\r
2308 <div class="sect1">
\r
2309 <h2 id="_precompiled_headers">Precompiled headers</h2>
\r
2310 <div class="sectionbody">
\r
2311 <div class="paragraph"><p>ccache has support for GCC’s precompiled headers. However, you have to do some
\r
2312 things to make it work properly:</p></div>
\r
2313 <div class="ulist"><ul>
\r
2316 You must set <strong>sloppiness</strong> to <strong>pch_defines,time_macros</strong>. The reason is that
\r
2317 ccache can’t tell whether <code>__TIME__</code> or <code>__DATE__</code> is used when using a
\r
2318 precompiled header. Further, it can’t detect changes in <strong>#define</strong>s in the
\r
2319 source code because of how preprocessing works in combination with
\r
2320 precompiled headers.
\r
2327 <div class="openblock">
\r
2328 <div class="content">
\r
2329 <div class="ulist"><ul>
\r
2332 use the <strong>-include</strong> compiler option to include the precompiled header
\r
2333 (i.e., don’t use <strong>#include</strong> in the source code to include the header); or
\r
2338 (for the Clang compiler) use the <strong>-include-pch</strong> compiler option to include
\r
2339 the PCH file generated from the precompiled header; or
\r
2344 add the <strong>-fpch-preprocess</strong> compiler option when compiling.
\r
2348 <div class="paragraph"><p>If you don’t do this, either the non-precompiled version of the header file
\r
2349 will be used (if available) or ccache will fall back to running the real
\r
2350 compiler and increase the statistics counter “preprocessor error” (if the
\r
2351 non-precompiled header file is not available).</p></div>
\r
2357 <div class="sect1">
\r
2358 <h2 id="_sharing_a_cache">Sharing a cache</h2>
\r
2359 <div class="sectionbody">
\r
2360 <div class="paragraph"><p>A group of developers can increase the cache hit rate by sharing a cache
\r
2361 directory. To share a cache without unpleasant side effects, the following
\r
2362 conditions should to be met:</p></div>
\r
2363 <div class="ulist"><ul>
\r
2366 Use the same cache directory.
\r
2371 Make sure that the configuration setting <strong>hard_link</strong> is false (which is the
\r
2377 Make sure that all users are in the same group.
\r
2382 Set the configuration setting <strong>umask</strong> to 002. This ensures that cached files
\r
2383 are accessible to everyone in the group.
\r
2388 Make sure that all users have write permission in the entire cache directory
\r
2389 (and that you trust all users of the shared cache).
\r
2394 Make sure that the setgid bit is set on all directories in the cache. This
\r
2395 tells the filesystem to inherit group ownership for new directories. The
\r
2396 following command might be useful for this:
\r
2398 <div class="openblock">
\r
2399 <div class="content">
\r
2400 <div class="listingblock">
\r
2401 <div class="content">
\r
2402 <pre><code>find $CCACHE_DIR -type d | xargs chmod g+s</code></pre>
\r
2407 <div class="paragraph"><p>The reason to avoid the hard link mode is that the hard links cause unwanted
\r
2408 side effects, as all links to a cached file share the file’s modification
\r
2409 timestamp. This results in false dependencies to be triggered by
\r
2410 timestamp-based build systems whenever another user links to an existing file.
\r
2411 Typically, users will see that their libraries and binaries are relinked
\r
2412 without reason.</p></div>
\r
2413 <div class="paragraph"><p>You may also want to make sure that a base directory is set appropriately, as
\r
2414 discussed in a previous section.</p></div>
\r
2417 <div class="sect1">
\r
2418 <h2 id="_sharing_a_cache_on_nfs">Sharing a cache on NFS</h2>
\r
2419 <div class="sectionbody">
\r
2420 <div class="paragraph"><p>It is possible to put the cache directory on an NFS filesystem (or similar
\r
2421 filesystems), but keep in mind that:</p></div>
\r
2422 <div class="ulist"><ul>
\r
2425 Having the cache on NFS may slow down compilation. Make sure to do some
\r
2426 benchmarking to see if it’s worth it.
\r
2431 ccache hasn’t been tested very thoroughly on NFS.
\r
2435 <div class="paragraph"><p>A tip is to set <strong>temporary_dir</strong> to a directory on the local host to avoid NFS
\r
2436 traffic for temporary files.</p></div>
\r
2439 <div class="sect1">
\r
2440 <h2 id="_using_ccache_with_other_compiler_wrappers">Using ccache with other compiler wrappers</h2>
\r
2441 <div class="sectionbody">
\r
2442 <div class="paragraph"><p>The recommended way of combining ccache with another compiler wrapper (such as
\r
2443 “distcc”) is by letting ccache execute the compiler wrapper. This is
\r
2444 accomplished by defining the configuration setting <strong>prefix_command</strong>, for
\r
2445 example by setting the environment variable <strong>CCACHE_PREFIX</strong> to the name of the
\r
2446 wrapper (e.g. <strong>distcc</strong>). ccache will then prefix the command line with the
\r
2447 specified command when running the compiler. To specify several prefix
\r
2448 commands, set <strong>prefix_command</strong> to a colon-separated list of commands.</p></div>
\r
2449 <div class="paragraph"><p>Unless you set <strong>compiler_check</strong> to a suitable command (see the description of
\r
2450 that configuration option), it is not recommended to use the form <strong>ccache
\r
2451 anotherwrapper compiler args</strong> as the compilation command. It’s also not
\r
2452 recommended to use the masquerading technique for the other compiler wrapper.
\r
2453 The reason is that by default, ccache will in both cases hash the mtime and
\r
2454 size of the other wrapper instead of the real compiler, which means that:</p></div>
\r
2455 <div class="ulist"><ul>
\r
2458 Compiler upgrades will not be detected properly.
\r
2463 The cached results will not be shared between compilations with and without
\r
2464 the other wrapper.
\r
2468 <div class="paragraph"><p>Another minor thing is that if <strong>prefix_command</strong> is used, ccache will not invoke
\r
2469 the other wrapper when running the preprocessor, which increases performance.
\r
2470 You can use the <strong>prefix_command_cpp</strong> configuration setting if you also want to
\r
2471 invoke the other wrapper when doing preprocessing (normally by adding <strong>-E</strong>).</p></div>
\r
2474 <div class="sect1">
\r
2475 <h2 id="_caveats">Caveats</h2>
\r
2476 <div class="sectionbody">
\r
2477 <div class="ulist"><ul>
\r
2480 The direct mode fails to pick up new header files in some rare scenarios. See
\r
2481 <a href="#_the_direct_mode">THE DIRECT MODE</a> above.
\r
2486 When run via ccache, warning messages produced by GCC 4.9 and newer will only
\r
2487 be colored when the environment variable <strong>GCC_COLORS</strong> is set. An alternative
\r
2488 to setting <strong>GCC_COLORS</strong> is to pass <code>-fdiagnostics-color</code> explicitly when
\r
2489 compiling (but then color codes will also be present when redirecting stderr
\r
2495 If ccache guesses that the compiler may emit colored warnings, then a
\r
2496 compilation with stderr referring to a TTY will be considered different from
\r
2497 a compilation with a redirected stderr, thus not sharing cache entries. This
\r
2498 happens for clang by default and for GCC when <strong>GCC_COLORS</strong> is set as
\r
2499 mentioned above. If you want to share cache hits, you can pass
\r
2500 <code>-f[no-]diagnostics-color</code> (GCC) or <code>-f[no-]color-diagnostics</code> (clang)
\r
2501 explicitly when compiling (but then color codes will be either on or off for
\r
2502 both the TTY and the redirected case).
\r
2508 <div class="sect1">
\r
2509 <h2 id="_troubleshooting">Troubleshooting</h2>
\r
2510 <div class="sectionbody">
\r
2511 <div class="sect2">
\r
2512 <h3 id="_general">General</h3>
\r
2513 <div class="paragraph"><p>A general tip for getting information about what ccache is doing is to enable
\r
2514 debug logging by setting <strong>log_file</strong>. The log contains executed commands,
\r
2515 important decisions that ccache makes, read and written files, etc. Another way
\r
2516 of keeping track of what is happening is to check the output of <strong>ccache -s</strong>.</p></div>
\r
2518 <div class="sect2">
\r
2519 <h3 id="_performance">Performance</h3>
\r
2520 <div class="paragraph"><p>ccache has been written to perform well out of the box, but sometimes you may
\r
2521 have to do some adjustments of how you use the compiler and ccache in order to
\r
2522 improve performance.</p></div>
\r
2523 <div class="paragraph"><p>Since ccache works best when I/O is fast, put the cache directory on a fast
\r
2524 storage device if possible. Having lots of free memory so that files in the
\r
2525 cache directory stay in the disk cache is also preferable.</p></div>
\r
2526 <div class="paragraph"><p>A good way of monitoring how well ccache works is to run <strong>ccache -s</strong> before and
\r
2527 after your build and then compare the statistics counters. Here are some common
\r
2528 problems and what may be done to increase the hit rate:</p></div>
\r
2529 <div class="ulist"><ul>
\r
2532 If “cache hit (preprocessed)” has been incremented instead of “cache hit
\r
2533 (direct)”, ccache has fallen back to preprocessor mode, which is generally
\r
2534 slower. Some possible reasons are:
\r
2536 <div class="ulist"><ul>
\r
2539 The source code has been modified in such a way that the preprocessor output
\r
2545 Compiler arguments that are hashed in the direct mode but not in the
\r
2546 preprocessor mode have changed (<strong>-I</strong>, <strong>-include</strong>, <strong>-D</strong>, etc) and they didn’t
\r
2547 affect the preprocessor output.
\r
2552 The compiler option <strong>-Xpreprocessor</strong> or <strong>-Wp,<em>X</em></strong> (except <strong>-Wp,-MD,<em>path</em></strong>,
\r
2553 <strong>-Wp,-MMD,<em>path</em></strong>, and <strong>-Wp,-D_define_</strong>) is used.
\r
2558 This was the first compilation with a new value of the base directory
\r
2564 A modification time of one of the include files is too new (created the same
\r
2565 second as the compilation is being done). This check is made to avoid a race
\r
2566 condition. To fix this, create the include file earlier in the build
\r
2567 process, if possible, or set <strong>sloppiness</strong> to <strong>include_file_mtime</strong> if you are
\r
2568 willing to take the risk. (The race condition consists of these events: the
\r
2569 preprocessor is run; an include file is modified by someone; the new include
\r
2570 file is hashed by ccache; the real compiler is run on the preprocessor’s
\r
2571 output, which contains data from the old header file; the wrong object file
\r
2572 is stored in the cache.)
\r
2577 The <code>__TIME__</code> preprocessor macro is (potentially) being used. ccache turns
\r
2578 off direct mode if <code>__TIME__</code> is present in the source code. This is done as
\r
2579 a safety measure since the string indicates that a <code>__TIME__</code> macro <em>may</em>
\r
2580 affect the output. (To be sure, ccache would have to run the preprocessor,
\r
2581 but the sole point of the direct mode is to avoid that.) If you know that
\r
2582 <code>__TIME__</code> isn’t used in practise, or don’t care if ccache produces objects
\r
2583 where <code>__TIME__</code> is expanded to something in the past, you can set
\r
2584 <strong>sloppiness</strong> to <strong>time_macros</strong>.
\r
2589 The <code>__DATE__</code> preprocessor macro is (potentially) being used and the date
\r
2590 has changed. This is similar to how <code>__TIME__</code> is handled. If <code>__DATE__</code> is
\r
2591 present in the source code, ccache hashes the current date in order to be
\r
2592 able to produce the correct object file if the <code>__DATE__</code> macro affects the
\r
2593 output. If you know that <code>__DATE__</code> isn’t used in practise, or don’t care if
\r
2594 ccache produces objects where <code>__DATE__</code> is expanded to something in the
\r
2595 past, you can set <strong>sloppiness</strong> to <strong>time_macros</strong>.
\r
2600 The input file path has changed. ccache normally includes the input file
\r
2601 path in the hash in order to be able to produce the correct object file if
\r
2602 the source code includes a <code>__FILE__</code> macro. If you know that <code>__FILE__</code>
\r
2603 isn’t used in practise, or don’t care if ccache produces objects where
\r
2604 <code>__FILE__</code> is expanded to the wrong path, you can set <strong>sloppiness</strong> to
\r
2605 <strong>file_macro</strong>. ccache will then exclude the input file path from the hash.
\r
2612 If “cache miss” has been incremented even though the same code has been
\r
2613 compiled and cached before, ccache has either detected that something has
\r
2614 changed anyway or a cleanup has been performed (either explicitly or
\r
2615 implicitly when a cache limit has been reached). Some perhaps unobvious
\r
2616 things that may result in a cache miss are usage of <code>__TIME__</code> or
\r
2617 <code>__DATE__</code> macros, or use of automatically generated code that contains a
\r
2618 timestamp, build counter or other volatile information.
\r
2623 If “multiple source files” has been incremented, it’s an indication that
\r
2624 the compiler has been invoked on several source code files at once. ccache
\r
2625 doesn’t support that. Compile the source code files separately if possible.
\r
2630 If “unsupported compiler option” has been incremented, enable debug logging
\r
2631 and check which option was rejected.
\r
2636 If “preprocessor error” has been incremented, one possible reason is that
\r
2637 precompiled headers are being used. See <a href="#_precompiled_headers">PRECOMPILED HEADERS</a> for how to remedy this.
\r
2642 If “can’t use precompiled header” has been incremented, see
\r
2643 <a href="#_precompiled_headers">PRECOMPILED HEADERS</a>.
\r
2648 <div class="sect2">
\r
2649 <h3 id="_corrupt_object_files">Corrupt object files</h3>
\r
2650 <div class="paragraph"><p>It should be noted that ccache is susceptible to general storage problems. If a
\r
2651 bad object file sneaks into the cache for some reason, it will of course stay
\r
2652 bad. Some possible reasons for erroneous object files are bad hardware (disk
\r
2653 drive, disk controller, memory, etc), buggy drivers or file systems, a bad
\r
2654 <strong>prefix_command</strong> or compiler wrapper. If this happens, the easiest way of
\r
2655 fixing it is this:</p></div>
\r
2656 <div class="olist arabic"><ol class="arabic">
\r
2659 Build so that the bad object file ends up in the build tree.
\r
2664 Remove the bad object file from the build tree.
\r
2669 Rebuild with <strong>CCACHE_RECACHE</strong> set.
\r
2673 <div class="paragraph"><p>An alternative is to clear the whole cache with <strong>ccache -C</strong> if you don’t mind
\r
2674 losing other cached results.</p></div>
\r
2675 <div class="paragraph"><p>There are no reported issues about ccache producing broken object files
\r
2676 reproducibly. That doesn’t mean it can’t happen, so if you find a repeatable
\r
2677 case, please report it.</p></div>
\r
2681 <div class="sect1">
\r
2682 <h2 id="_more_information">More information</h2>
\r
2683 <div class="sectionbody">
\r
2684 <div class="paragraph"><p>Credits, mailing list information, bug reporting instructions, source code,
\r
2685 etc, can be found on ccache’s web site: <a href="https://ccache.samba.org">https://ccache.samba.org</a>.</p></div>
\r
2688 <div class="sect1">
\r
2689 <h2 id="_author">Author</h2>
\r
2690 <div class="sectionbody">
\r
2691 <div class="paragraph"><p>ccache was originally written by Andrew Tridgell and is currently developed and
\r
2692 maintained by Joel Rosdahl. See AUTHORS.txt or AUTHORS.html and
\r
2693 <a href="https://ccache.samba.org/credits.html">https://ccache.samba.org/credits.html</a> for a list of contributors.</p></div>
\r
2697 <div id="footnotes"><hr /></div>
\r
2699 <div id="footer-text">
\r
2702 2019-01-13 21:38:14 CET
\r
projects / platform / upstream / ccache.git / blob