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.5.1</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>direct_mode</strong> (<strong>CCACHE_DIRECT</strong> or <strong>CCACHE_NODIRECT</strong>, see <a href="#_boolean_values">Boolean values</a> above)
\r
1266 If true, the direct mode will be used. The default is true. See
\r
1267 <a href="#_the_direct_mode">THE DIRECT MODE</a>.
\r
1270 <dt class="hdlist1">
\r
1271 <strong>disable</strong> (<strong>CCACHE_DISABLE</strong> or <strong>CCACHE_NODISABLE</strong>, see <a href="#_boolean_values">Boolean values</a> above)
\r
1275 When true, ccache will just call the real compiler, bypassing the cache
\r
1276 completely. The default is false.
\r
1279 <dt class="hdlist1">
\r
1280 <strong>extra_files_to_hash</strong> (<strong>CCACHE_EXTRAFILES</strong>)
\r
1284 This setting is a list of paths to files that ccache will include in the
\r
1285 the hash sum that identifies the build. The list separator is semicolon on
\r
1286 Windows systems and colon on other systems.
\r
1289 <dt class="hdlist1">
\r
1290 <strong>hard_link</strong> (<strong>CCACHE_HARDLINK</strong> or <strong>CCACHE_NOHARDLINK</strong>, see <a href="#_boolean_values">Boolean values</a> above)
\r
1294 If true, ccache will attempt to use hard links from the cache directory
\r
1295 when creating the compiler output rather than using a file copy. Hard links
\r
1296 are never made for compressed cache files. This means that you should not
\r
1297 enable compression if you want to use hard links. The default is false.
\r
1299 <div class="admonitionblock">
\r
1302 <div class="title">Warning</div>
\r
1304 <td class="content">Do not enable this option unless you are aware of the consequences.
\r
1305 Using hard links may be slightly faster in some situations, but there are
\r
1306 several pitfalls since the resulting object file will share i-node with the
\r
1307 cached object file:</td>
\r
1310 <div class="olist arabic"><ol class="arabic">
\r
1313 If the resulting object file is modified in any way, the cached object file
\r
1314 will be modified as well. For instance, if you run <code>strip object.o</code> or <code>echo
\r
1315 >object.o</code>, you will corrupt the cache.
\r
1320 Programs that rely on modification times (like “make”) can be confused
\r
1321 since ccache updates the cached files' modification times as part of the
\r
1322 automatic cache size management. This will affect object files in the build
\r
1323 tree as well, which can retrigger the linking step even though nothing
\r
1324 really has changed.
\r
1329 <dt class="hdlist1">
\r
1330 <strong>hash_dir</strong> (<strong>CCACHE_HASHDIR</strong> or <strong>CCACHE_NOHASHDIR</strong>, see <a href="#_boolean_values">Boolean values</a> above)
\r
1334 If true (which is the default), ccache will include the current working
\r
1335 directory (CWD) in the hash that is used to distinguish two compilations
\r
1336 when generating debug info (compiler option <strong>-g</strong> with variations).
\r
1337 Exception: The CWD will not be included in the hash if <strong>base_dir</strong> is set
\r
1338 (and matches the CWD) and the compiler option <strong>-fdebug-prefix-map</strong> is used.
\r
1339 See also the discussion under
\r
1340 <a href="#_compiling_in_different_directories">COMPILING IN DIFFERENT DIRECTORIES</a>.
\r
1342 <div class="paragraph"><p>The reason for including the CWD in the hash by default is to prevent a problem
\r
1343 with the storage of the current working directory in the debug info of an
\r
1344 object file, which can lead ccache to return a cached object file that has the
\r
1345 working directory in the debug info set incorrectly.</p></div>
\r
1346 <div class="paragraph"><p>You can disable this setting to get cache hits when compiling the same source
\r
1347 code in different directories if you don’t mind that CWD in the debug info
\r
1348 might be incorrect.</p></div>
\r
1350 <dt class="hdlist1">
\r
1351 <strong>ignore_headers_in_manifest</strong> (<strong>CCACHE_IGNOREHEADERS</strong>)
\r
1355 This setting is a list of paths to files (or directories with headers) that
\r
1356 ccache will <strong>not</strong> include in the manifest list that makes up the direct
\r
1357 mode. Note that this can cause stale cache hits if those headers do indeed
\r
1358 change. The list separator is semicolon on Windows systems and colon on
\r
1362 <dt class="hdlist1">
\r
1363 <strong>keep_comments_cpp</strong> (<strong>CCACHE_COMMENTS</strong> or <strong>CCACHE_NOCOMMENTS</strong>, see <a href="#_boolean_values">Boolean values</a> above)
\r
1367 If true, ccache will not discard the comments before hashing preprocessor
\r
1368 output. This can be used to check documentation with <strong>-Wdocumentation</strong>.
\r
1371 <dt class="hdlist1">
\r
1372 <strong>limit_multiple</strong> (<strong>CCACHE_LIMIT_MULTIPLE</strong>)
\r
1376 Sets the limit when cleaning up. Files are deleted (in LRU order) until the
\r
1377 levels are below the limit. The default is 0.8 (= 80%). See
\r
1378 <a href="#_automatic_cleanup">AUTOMATIC CLEANUP</a> for more information.
\r
1381 <dt class="hdlist1">
\r
1382 <strong>log_file</strong> (<strong>CCACHE_LOGFILE</strong>)
\r
1386 If set to a file path, ccache will write information on what it is doing to
\r
1387 the specified file. This is useful for tracking down problems.
\r
1390 <dt class="hdlist1">
\r
1391 <strong>max_files</strong> (<strong>CCACHE_MAXFILES</strong>)
\r
1395 This option specifies the maximum number of files to keep in the cache. Use
\r
1396 0 for no limit (which is the default). See also
\r
1397 <a href="#_cache_size_management">CACHE SIZE MANAGEMENT</a>.
\r
1400 <dt class="hdlist1">
\r
1401 <strong>max_size</strong> (<strong>CCACHE_MAXSIZE</strong>)
\r
1405 This option specifies the maximum size of the cache. Use 0 for no limit.
\r
1406 The default value is 5G. Available suffixes: k, M, G, T (decimal) and Ki,
\r
1407 Mi, Gi, Ti (binary). The default suffix is G. See also
\r
1408 <a href="#_cache_size_management">CACHE SIZE MANAGEMENT</a>.
\r
1411 <dt class="hdlist1">
\r
1412 <strong>path</strong> (<strong>CCACHE_PATH</strong>)
\r
1416 If set, ccache will search directories in this list when looking for the
\r
1417 real compiler. The list separator is semicolon on Windows systems and colon
\r
1418 on other systems. If not set, ccache will look for the first executable
\r
1419 matching the compiler name in the normal <strong>PATH</strong> that isn’t a symbolic link
\r
1423 <dt class="hdlist1">
\r
1424 <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
1428 When this option is set, and ccache finds a precompiled header file,
\r
1429 ccache will look for a file with the extension “.sum” added
\r
1430 (e.g. “pre.h.gch.sum”), and if found, it will hash this file instead
\r
1431 of the precompiled header itself to work around the performance
\r
1432 penalty of hashing very large files.
\r
1435 <dt class="hdlist1">
\r
1436 <strong>prefix_command</strong> (<strong>CCACHE_PREFIX</strong>)
\r
1440 This option adds a list of prefixes (separated by space) to the command
\r
1441 line that ccache uses when invoking the compiler. See also
\r
1442 <a href="#_using_ccache_with_other_compiler_wrappers">USING CCACHE WITH OTHER COMPILER WRAPPERS</a>.
\r
1445 <dt class="hdlist1">
\r
1446 <strong>prefix_command_cpp</strong> (<strong>CCACHE_PREFIX_CPP</strong>)
\r
1450 This option adds a list of prefixes (separated by space) to the command
\r
1451 line that ccache uses when invoking the preprocessor.
\r
1454 <dt class="hdlist1">
\r
1455 <strong>read_only</strong> (<strong>CCACHE_READONLY</strong> or <strong>CCACHE_NOREADONLY</strong>, see <a href="#_boolean_values">Boolean values</a> above)
\r
1459 If true, ccache will attempt to use existing cached object files, but it
\r
1460 will not to try to add anything new to the cache. If you are using this
\r
1461 because your ccache directory is read-only, then you need to set
\r
1462 <strong>temporary_dir</strong> as otherwise ccache will fail to create temporary files.
\r
1465 <dt class="hdlist1">
\r
1466 <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
1470 Just like <strong>read_only</strong> except that ccache will only try to retrieve results
\r
1471 from the cache using the direct mode, not the preprocessor mode. See
\r
1472 documentation for <strong>read_only</strong> regarding using a read-only ccache directory.
\r
1475 <dt class="hdlist1">
\r
1476 <strong>recache</strong> (<strong>CCACHE_RECACHE</strong> or <strong>CCACHE_NORECACHE</strong>, see <a href="#_boolean_values">Boolean values</a> above)
\r
1480 If true, ccache will not use any previously stored result. New results will
\r
1481 still be cached, possibly overwriting any pre-existing results.
\r
1484 <dt class="hdlist1">
\r
1485 <strong>run_second_cpp</strong> (<strong>CCACHE_CPP2</strong> or <strong>CCACHE_NOCPP2</strong>, see <a href="#_boolean_values">Boolean values</a> above)
\r
1489 If true, ccache will first run the preprocessor to preprocess the source
\r
1490 code (see <a href="#_the_preprocessor_mode">THE PREPROCESSOR MODE</a>) and then on a
\r
1491 cache miss run the compiler on the source code to get hold of the object
\r
1492 file. This is the default.
\r
1494 <div class="paragraph"><p>If false, ccache will first run preprocessor to preprocess the source code and
\r
1495 then on a cache miss run the compiler on the <em>preprocessed source code</em> instead
\r
1496 of the original source code. This makes cache misses slightly faster since the
\r
1497 source code only has to be preprocessed once. The downside is that some
\r
1498 compilers won’t produce the same result (for instance diagnostics warnings)
\r
1499 when compiling preprocessed source code.</p></div>
\r
1500 <div class="paragraph"><p>A solution to the above mentioned downside is to set <strong>run_second_cpp</strong> to false
\r
1501 and pass <strong>-fdirectives-only</strong> (for GCC) or <strong>-frewrite-includes</strong> (for Clang) to
\r
1502 the compiler. This will cause the compiler to leave the macros and other
\r
1503 preprocessor information, and only process the <strong>#include</strong> directives. When run
\r
1504 in this way, the preprocessor arguments will be passed to the compiler since it
\r
1505 still has to do <em>some</em> preprocessing (like macros).</p></div>
\r
1507 <dt class="hdlist1">
\r
1508 <strong>sloppiness</strong> (<strong>CCACHE_SLOPPINESS</strong>)
\r
1512 By default, ccache tries to give as few false cache hits as possible.
\r
1513 However, in certain situations it’s possible that you know things that
\r
1514 ccache can’t take for granted. This setting makes it possible to tell
\r
1515 ccache to relax some checks in order to increase the hit rate. The value
\r
1516 should be a comma-separated string with options. Available options are:
\r
1518 <div class="openblock">
\r
1519 <div class="content">
\r
1520 <div class="dlist"><dl>
\r
1521 <dt class="hdlist1">
\r
1522 <strong>file_macro</strong>
\r
1526 Ignore <code>__FILE__</code> being present in the source.
\r
1529 <dt class="hdlist1">
\r
1530 <strong>file_stat_matches</strong>
\r
1534 ccache normally examines a file’s contents to determine whether it matches
\r
1535 the cached version. With this option set, ccache will consider a file as
\r
1536 matching its cached version if the mtimes and ctimes match.
\r
1539 <dt class="hdlist1">
\r
1540 <strong>file_stat_matches_ctime</strong>
\r
1544 Ignore ctimes when <strong>file_stat_matches</strong> is enabled. This can be useful when
\r
1545 backdating files' mtimes in a controlled way.
\r
1548 <dt class="hdlist1">
\r
1549 <strong>include_file_ctime</strong>
\r
1553 By default, ccache also will not cache a file if it includes a header whose
\r
1554 ctime is too new. This option disables that check.
\r
1557 <dt class="hdlist1">
\r
1558 <strong>include_file_mtime</strong>
\r
1562 By default, ccache will not cache a file if it includes a header whose
\r
1563 mtime is too new. This option disables that check.
\r
1566 <dt class="hdlist1">
\r
1567 <strong>no_system_headers</strong>
\r
1571 By default, ccache will also include all system headers in the manifest.
\r
1572 With this option set, ccache will only include system headers in the hash
\r
1573 but not add the system header files to the list of include files.
\r
1576 <dt class="hdlist1">
\r
1577 <strong>pch_defines</strong>
\r
1581 Be sloppy about <strong>#define</strong>s when precompiling a header file. See
\r
1582 <a href="#_precompiled_headers">PRECOMPILED HEADERS</a> for more information.
\r
1585 <dt class="hdlist1">
\r
1586 <strong>time_macros</strong>
\r
1590 Ignore <code>__DATE__</code> and <code>__TIME__</code> being present in the source code.
\r
1595 <div class="paragraph"><p>See the discussion under <a href="#_troubleshooting">TROUBLESHOOTING</a> for more
\r
1596 information.</p></div>
\r
1598 <dt class="hdlist1">
\r
1599 <strong>stats</strong> (<strong>CCACHE_STATS</strong> or <strong>CCACHE_NOSTATS</strong>, see <a href="#_boolean_values">Boolean values</a> above)
\r
1603 If true, ccache will update the statistics counters on each compilation.
\r
1604 The default is true.
\r
1607 <dt class="hdlist1">
\r
1608 <strong>temporary_dir</strong> (<strong>CCACHE_TEMPDIR</strong>)
\r
1612 This setting specifies where ccache will put temporary files. The default
\r
1613 is <strong><cache_dir>/tmp</strong>.
\r
1615 <div class="admonitionblock">
\r
1618 <div class="title">Note</div>
\r
1620 <td class="content">In previous versions of ccache, <strong>CCACHE_TEMPDIR</strong> had to be on the same
\r
1621 filesystem as the <strong>CCACHE_DIR</strong> path, but this requirement has been
\r
1626 <dt class="hdlist1">
\r
1627 <strong>umask</strong> (<strong>CCACHE_UMASK</strong>)
\r
1631 This setting specifies the umask for ccache and all child processes (such
\r
1632 as the compiler). This is mostly useful when you wish to share your cache
\r
1633 with other users. Note that this also affects the file permissions set on
\r
1634 the object files created from your compilations.
\r
1637 <dt class="hdlist1">
\r
1638 <strong>unify</strong> (<strong>CCACHE_UNIFY</strong> or <strong>CCACHE_NOUNIFY</strong>, see <a href="#_boolean_values">Boolean values</a> above)
\r
1642 If true, ccache will use a C/C++ unifier when hashing the preprocessor
\r
1643 output if the <strong>-g</strong> option is not used. The unifier is slower than a normal
\r
1644 hash, so setting this environment variable loses a little bit of speed, but
\r
1645 it means that ccache can take advantage of not recompiling when the changes
\r
1646 to the source code consist of reformatting only. Note that enabling the
\r
1647 unifier changes the hash, so cached compilations produced when the unifier
\r
1648 is enabled cannot be reused when the unifier is disabled, and vice versa.
\r
1649 Enabling the unifier may result in incorrect line number information in
\r
1650 compiler warning messages and expansions of the <code>__LINE__</code> macro.
\r
1657 <div class="sect1">
\r
1658 <h2 id="_cache_size_management">Cache size management</h2>
\r
1659 <div class="sectionbody">
\r
1660 <div class="paragraph"><p>By default, ccache has a 5 GB limit on the total size of files in the cache and
\r
1661 no limit on the number of files. You can set different limits using the
\r
1662 <strong>-M</strong>/<strong>--max-size</strong> and <strong>-F</strong>/<strong>--max-files</strong> options. Use <strong>ccache -s/--show-stats</strong>
\r
1663 to see the cache size and the currently configured limits (in addition to other
\r
1664 various statistics).</p></div>
\r
1665 <div class="paragraph"><p>Cleanup can be triggered in two different ways: automatic and manual.</p></div>
\r
1666 <div class="sect2">
\r
1667 <h3 id="_automatic_cleanup">Automatic cleanup</h3>
\r
1668 <div class="paragraph"><p>ccache maintains counters for various statistics about the cache, including the
\r
1669 size and number of all cached files. In order to improve performance and reduce
\r
1670 issues with concurrent ccache invocations, there is one statistics file for
\r
1671 each of the sixteen subdirectories in the cache.</p></div>
\r
1672 <div class="paragraph"><p>After a new compilation result has been written to the cache, ccache will
\r
1673 update the size and file number statistics for the subdirectory (one of
\r
1674 sixteen) to which the result was written. Then, if the size counter for said
\r
1675 subdirectory is greater than <strong>max_size / 16</strong> or the file number counter is
\r
1676 greater than <strong>max_files / 16</strong>, automatic cleanup is triggered.</p></div>
\r
1677 <div class="paragraph"><p>When automatic cleanup is triggered for a subdirectory in the cache, ccache
\r
1679 <div class="olist arabic"><ol class="arabic">
\r
1682 Count all files in the subdirectory and compute their aggregated size.
\r
1687 Remove files in LRU (least recently used) order until the size is at most
\r
1688 <strong>limit_multiple * max_size / 16</strong> and the number of files is at most
\r
1689 <strong>limit_multiple * max_files / 16</strong>, where <strong>limit_multiple</strong>, <strong>max_size</strong> and
\r
1690 <strong>max_files</strong> are configuration settings.
\r
1695 Set the size and file number counters to match the files that were kept.
\r
1699 <div class="paragraph"><p>The reason for removing more files than just those needed to not exceed the max
\r
1700 limits is that a cleanup is a fairly slow operation, so it would not be a good
\r
1701 idea to trigger it often, like after each cache miss.</p></div>
\r
1703 <div class="sect2">
\r
1704 <h3 id="_manual_cleanup">Manual cleanup</h3>
\r
1705 <div class="paragraph"><p>You can run <strong>ccache -c/--cleanup</strong> to force cleanup of the whole cache, i.e. all
\r
1706 of the sixteen subdirectories. This will recalculate the statistics counters
\r
1707 and make sure that the <strong>max_size</strong> and <strong>max_files</strong> settings are not exceeded.
\r
1708 Note that <strong>limit_multiple</strong> is not taken into account for manual cleanup.</p></div>
\r
1712 <div class="sect1">
\r
1713 <h2 id="_cache_compression">Cache compression</h2>
\r
1714 <div class="sectionbody">
\r
1715 <div class="paragraph"><p>ccache can optionally compress all files it puts into the cache using the
\r
1716 compression library zlib. While this may involve a tiny performance slowdown,
\r
1717 it increases the number of files that fit in the cache. You can turn on
\r
1718 compression with the <strong>compression</strong> configuration setting and you can also tweak
\r
1719 the compression level with <strong>compression_level</strong>.</p></div>
\r
1722 <div class="sect1">
\r
1723 <h2 id="_cache_statistics">Cache statistics</h2>
\r
1724 <div class="sectionbody">
\r
1725 <div class="paragraph"><p><strong>ccache -s/--show-stats</strong> can show the following statistics:</p></div>
\r
1726 <div class="tableblock">
\r
1727 <table rules="all"
\r
1730 cellspacing="0" cellpadding="4">
\r
1731 <col width="30%" />
\r
1732 <col width="70%" />
\r
1735 <th align="left" valign="top">Name </th>
\r
1736 <th align="left" valign="top"> Description</th>
\r
1741 <td align="left" valign="top"><p class="table">autoconf compile/link</p></td>
\r
1742 <td align="left" valign="top"><p class="table">Uncachable compilation or linking by an autoconf test.</p></td>
\r
1745 <td align="left" valign="top"><p class="table">bad compiler arguments</p></td>
\r
1746 <td align="left" valign="top"><p class="table">Malformed compiler argument, e.g. missing a value for an option that requires
\r
1747 an argument or failure to read a file specified by an option argument.</p></td>
\r
1750 <td align="left" valign="top"><p class="table">cache file missing</p></td>
\r
1751 <td align="left" valign="top"><p class="table">A file was unexpectedly missing from the cache. This only happens in rare
\r
1752 situations, e.g. if one ccache instance is about to get a file from the cache
\r
1753 while another instance removed the file as part of cache cleanup.</p></td>
\r
1756 <td align="left" valign="top"><p class="table">cache hit (direct)</p></td>
\r
1757 <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
1760 <td align="left" valign="top"><p class="table">cache hit (preprocessed)</p></td>
\r
1761 <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
1764 <td align="left" valign="top"><p class="table">cache miss</p></td>
\r
1765 <td align="left" valign="top"><p class="table">No result was found.</p></td>
\r
1768 <td align="left" valign="top"><p class="table">cache size</p></td>
\r
1769 <td align="left" valign="top"><p class="table">Current size of the cache.</p></td>
\r
1772 <td align="left" valign="top"><p class="table">called for link</p></td>
\r
1773 <td align="left" valign="top"><p class="table">The compiler was called for linking, not compiling.</p></td>
\r
1776 <td align="left" valign="top"><p class="table">called for preprocessing</p></td>
\r
1777 <td align="left" valign="top"><p class="table">The compiler was called for preprocessing, not compiling.</p></td>
\r
1780 <td align="left" valign="top"><p class="table">can’t use precompiled header</p></td>
\r
1781 <td align="left" valign="top"><p class="table">Preconditions for using <a href="#_precompiled_headers">precompiled headers</a> were not
\r
1782 fulfilled.</p></td>
\r
1785 <td align="left" valign="top"><p class="table">ccache internal error</p></td>
\r
1786 <td align="left" valign="top"><p class="table">Unexpected failure, e.g. due to problems reading/writing the cache.</p></td>
\r
1789 <td align="left" valign="top"><p class="table">cleanups performed</p></td>
\r
1790 <td align="left" valign="top"><p class="table">Number of cleanups performed, either implicitly due to the cache size limit
\r
1791 being reached or due to explicit <strong>ccache -c/--cleanup</strong> calls.</p></td>
\r
1794 <td align="left" valign="top"><p class="table">compile failed</p></td>
\r
1795 <td align="left" valign="top"><p class="table">The compilation failed. No result stored in the cache.</p></td>
\r
1798 <td align="left" valign="top"><p class="table">compiler check failed</p></td>
\r
1799 <td align="left" valign="top"><p class="table">A compiler check program specified by <strong>compiler_check</strong> (<strong>CCACHE_COMPILERCHECK</strong>)
\r
1803 <td align="left" valign="top"><p class="table">compiler produced empty output</p></td>
\r
1804 <td align="left" valign="top"><p class="table">The compiler’s output file (typically an object file) was empty after
\r
1805 compilation.</p></td>
\r
1808 <td align="left" valign="top"><p class="table">compiler produced no output</p></td>
\r
1809 <td align="left" valign="top"><p class="table">The compiler’s output file (typically an object file) was missing after
\r
1810 compilation.</p></td>
\r
1813 <td align="left" valign="top"><p class="table">compiler produced stdout</p></td>
\r
1814 <td align="left" valign="top"><p class="table">The compiler wrote data to standard output. This is something that compilers
\r
1815 normally never do, so ccache is not designed to store such output in the cache.</p></td>
\r
1818 <td align="left" valign="top"><p class="table">couldn’t find the compiler</p></td>
\r
1819 <td align="left" valign="top"><p class="table">The compiler to execute could not be found.</p></td>
\r
1822 <td align="left" valign="top"><p class="table">error hashing extra file</p></td>
\r
1823 <td align="left" valign="top"><p class="table">Failure reading a file specified by <strong>extra_files_to_hash</strong>
\r
1824 (<strong>CCACHE_EXTRAFILES</strong>).</p></td>
\r
1827 <td align="left" valign="top"><p class="table">files in cache</p></td>
\r
1828 <td align="left" valign="top"><p class="table">Current number of files in the cache.</p></td>
\r
1831 <td align="left" valign="top"><p class="table">multiple source files</p></td>
\r
1832 <td align="left" valign="top"><p class="table">The compiler was called to compile multiple source files in one go. This is not
\r
1833 supported by ccache.</p></td>
\r
1836 <td align="left" valign="top"><p class="table">no input file</p></td>
\r
1837 <td align="left" valign="top"><p class="table">No input file was specified to the compiler.</p></td>
\r
1840 <td align="left" valign="top"><p class="table">output to a non-regular file</p></td>
\r
1841 <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
1845 <td align="left" valign="top"><p class="table">output to stdout</p></td>
\r
1846 <td align="left" valign="top"><p class="table">The compiler was instructed to write its output to standard output using <strong>-o
\r
1847 -</strong>. This is not supported by ccache.</p></td>
\r
1850 <td align="left" valign="top"><p class="table">preprocessor error</p></td>
\r
1851 <td align="left" valign="top"><p class="table">Preprocessing the source code using the compiler’s <strong>-E</strong> option failed.</p></td>
\r
1854 <td align="left" valign="top"><p class="table">stats updated</p></td>
\r
1855 <td align="left" valign="top"><p class="table">When statistics were updated the last time.</p></td>
\r
1858 <td align="left" valign="top"><p class="table">stats zeroed</p></td>
\r
1859 <td align="left" valign="top"><p class="table">When <strong>ccache -z</strong> was called the last time.</p></td>
\r
1862 <td align="left" valign="top"><p class="table">unsupported code directive</p></td>
\r
1863 <td align="left" valign="top"><p class="table">Code like the assembler <strong>.incbin</strong> directive was found. This is not supported
\r
1864 by ccache.</p></td>
\r
1867 <td align="left" valign="top"><p class="table">unsupported compiler option</p></td>
\r
1868 <td align="left" valign="top"><p class="table">A compiler option not supported by ccache was found.</p></td>
\r
1871 <td align="left" valign="top"><p class="table">unsupported source language</p></td>
\r
1872 <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
1879 <div class="sect1">
\r
1880 <h2 id="_how_ccache_works">How ccache works</h2>
\r
1881 <div class="sectionbody">
\r
1882 <div class="paragraph"><p>The basic idea is to detect when you are compiling exactly the same code a
\r
1883 second time and reuse the previously produced output. The detection is done by
\r
1884 hashing different kinds of information that should be unique for the
\r
1885 compilation and then using the hash sum to identify the cached output. ccache
\r
1886 uses MD4, a very fast cryptographic hash algorithm, for the hashing. (MD4 is
\r
1887 nowadays too weak to be useful in cryptographic contexts, but it should be safe
\r
1888 enough to be used to identify recompilations.) On a cache hit, ccache is able
\r
1889 to supply all of the correct compiler outputs (including all warnings,
\r
1890 dependency file, etc) from the cache.</p></div>
\r
1891 <div class="paragraph"><p>ccache has two ways of doing the detection:</p></div>
\r
1892 <div class="ulist"><ul>
\r
1895 the <strong>direct mode</strong>, where ccache hashes the source code and include files
\r
1901 the <strong>preprocessor mode</strong>, where ccache runs the preprocessor on the source
\r
1902 code and hashes the result
\r
1906 <div class="paragraph"><p>The direct mode is generally faster since running the preprocessor has some
\r
1907 overhead.</p></div>
\r
1908 <div class="sect2">
\r
1909 <h3 id="_common_hashed_information">Common hashed information</h3>
\r
1910 <div class="paragraph"><p>For both modes, the following information is included in the hash:</p></div>
\r
1911 <div class="ulist"><ul>
\r
1914 the extension used by the compiler for a file with preprocessor output
\r
1915 (normally <strong>.i</strong> for C code and <strong>.ii</strong> for C++ code)
\r
1920 the compiler’s size and modification time (or other compiler-specific
\r
1921 information specified by the <strong>compiler_check</strong> setting)
\r
1926 the name of the compiler
\r
1931 the current directory (if the <strong>hash_dir</strong> setting is enabled)
\r
1936 contents of files specified by the <strong>extra_files_to_hash</strong> setting (if any)
\r
1941 <div class="sect2">
\r
1942 <h3 id="_the_direct_mode">The direct mode</h3>
\r
1943 <div class="paragraph"><p>In the direct mode, the hash is formed of the common information and:</p></div>
\r
1944 <div class="ulist"><ul>
\r
1947 the input source file
\r
1952 the command line options
\r
1956 <div class="paragraph"><p>Based on the hash, a data structure called “manifest” is looked up in the
\r
1957 cache. The manifest contains:</p></div>
\r
1958 <div class="ulist"><ul>
\r
1961 references to cached compilation results (object file, dependency file, etc)
\r
1962 that were produced by previous compilations that matched the hash
\r
1967 paths to the include files that were read at the time the compilation results
\r
1968 were stored in the cache
\r
1973 hash sums of the include files at the time the compilation results were
\r
1974 stored in the cache
\r
1978 <div class="paragraph"><p>The current contents of the include files are then hashed and compared to the
\r
1979 information in the manifest. If there is a match, ccache knows the result of
\r
1980 the compilation. If there is no match, ccache falls back to running the
\r
1981 preprocessor. The output from the preprocessor is parsed to find the include
\r
1982 files that were read. The paths and hash sums of those include files are then
\r
1983 stored in the manifest along with information about the produced compilation
\r
1985 <div class="paragraph"><p>There is a catch with the direct mode: header files that were used by the
\r
1986 compiler are recorded, but header files that were <strong>not</strong> used, but would have
\r
1987 been used if they existed, are not. So, when ccache checks if a result can be
\r
1988 taken from the cache, it currently can’t check if the existence of a new header
\r
1989 file should invalidate the result. In practice, the direct mode is safe to use
\r
1990 in the absolute majority of cases.</p></div>
\r
1991 <div class="paragraph"><p>The direct mode will be disabled if any of the following holds:</p></div>
\r
1992 <div class="ulist"><ul>
\r
1995 the configuration setting <strong>direct_mode</strong> is false
\r
2000 a modification time of one of the include files is too new (needed to avoid a
\r
2006 a compiler option not supported by the direct mode is used:
\r
2008 <div class="ulist"><ul>
\r
2011 a <strong>-Wp,<em>X</em></strong> compiler option other than <strong>-Wp,-MD,<em>path</em></strong>,
\r
2012 <strong>-Wp,-MMD,<em>path</em></strong> and <strong>-Wp,-D_define_</strong>
\r
2017 <strong>-Xpreprocessor</strong>
\r
2024 the string <code>__TIME__</code> is present in the source code
\r
2029 <div class="sect2">
\r
2030 <h3 id="_the_preprocessor_mode">The preprocessor mode</h3>
\r
2031 <div class="paragraph"><p>In the preprocessor mode, the hash is formed of the common information and:</p></div>
\r
2032 <div class="ulist"><ul>
\r
2035 the preprocessor output from running the compiler with <strong>-E</strong>
\r
2040 the command line options except options that affect include files (<strong>-I</strong>,
\r
2041 <strong>-include</strong>, <strong>-D</strong>, etc; the theory is that these options will change the
\r
2042 preprocessor output if they have any effect at all)
\r
2047 any standard error output generated by the preprocessor
\r
2051 <div class="paragraph"><p>Based on the hash, the cached compilation result can be looked up directly in
\r
2052 the cache.</p></div>
\r
2056 <div class="sect1">
\r
2057 <h2 id="_cache_debugging">Cache debugging</h2>
\r
2058 <div class="sectionbody">
\r
2059 <div class="paragraph"><p>To find out what information ccache actually is hashing, you can enable the
\r
2060 debug mode via the configuration setting <strong>debug</strong> or by setting <strong>CCACHE_DEBUG</strong>
\r
2061 in the environment. This can be useful if you are investigating why you don’t
\r
2062 get cache hits. Note that performance will be reduced slightly.</p></div>
\r
2063 <div class="paragraph"><p>When the debug mode is enabled, ccache will create up to five additional files
\r
2064 next to the object file:</p></div>
\r
2065 <div class="tableblock">
\r
2066 <table rules="all"
\r
2069 cellspacing="0" cellpadding="4">
\r
2070 <col width="30%" />
\r
2071 <col width="70%" />
\r
2074 <th align="left" valign="top">Filename </th>
\r
2075 <th align="left" valign="top"> Description</th>
\r
2080 <td align="left" valign="top"><p class="table"><strong><objectfile>.ccache-input-c</strong></p></td>
\r
2081 <td align="left" valign="top"><p class="table">Binary input hashed by both the direct mode and the preprocessor mode.</p></td>
\r
2084 <td align="left" valign="top"><p class="table"><strong><objectfile>.ccache-input-d</strong></p></td>
\r
2085 <td align="left" valign="top"><p class="table">Binary input only hashed by the direct mode.</p></td>
\r
2088 <td align="left" valign="top"><p class="table"><strong><objectfile>.ccache-input-p</strong></p></td>
\r
2089 <td align="left" valign="top"><p class="table">Binary input only hashed by the preprocessor mode.</p></td>
\r
2092 <td align="left" valign="top"><p class="table"><strong><objectfile>.ccache-input-text</strong></p></td>
\r
2093 <td align="left" valign="top"><p class="table">Human-readable combined diffable text version of the three files above.</p></td>
\r
2096 <td align="left" valign="top"><p class="table"><strong><objectfile>.ccache-log</strong></p></td>
\r
2097 <td align="left" valign="top"><p class="table">Log for this object file.</p></td>
\r
2102 <div class="paragraph"><p>In the direct mode, ccache uses the MD4 hash of the <strong>ccache-input-c</strong>
\r
2103 + <strong>ccache-input-d</strong> data (where <strong>+</strong> means concatenation), while the
\r
2104 <strong>ccache-input-c</strong> + <strong>ccache-input-p</strong> data is used in the preprocessor mode.</p></div>
\r
2105 <div class="paragraph"><p>The <strong>ccache-input-text</strong> file is a combined text version of the three
\r
2106 binary input files. It has three sections (“COMMON”, “DIRECT MODE” and
\r
2107 “PREPROCESSOR MODE”), which is turn contain annotations that say what kind of
\r
2108 data comes next.</p></div>
\r
2109 <div class="paragraph"><p>To debug why you don’t get an expected cache hit for an object file, you can do
\r
2110 something like this:</p></div>
\r
2111 <div class="olist arabic"><ol class="arabic">
\r
2114 Build with debug mode enabled.
\r
2119 Save the <strong><objectfile>.ccache-*</strong> files.
\r
2124 Build again with debug mode enabled.
\r
2129 Compare <strong><objectfile>.ccache-input-text</strong> for the two builds. This together
\r
2130 with the <strong><objectfile>.ccache-log</strong> files should give you some clues about
\r
2131 what is happening.
\r
2137 <div class="sect1">
\r
2138 <h2 id="_compiling_in_different_directories">Compiling in different directories</h2>
\r
2139 <div class="sectionbody">
\r
2140 <div class="paragraph"><p>Some information included in the hash that identifies a unique compilation can
\r
2141 contain absolute paths:</p></div>
\r
2142 <div class="ulist"><ul>
\r
2145 The preprocessed source code may contain absolute paths to include files if
\r
2146 the compiler option <strong>-g</strong> is used or if absolute paths are given to <strong>-I</strong> and
\r
2147 similar compiler options.
\r
2152 Paths specified by compiler options (such as <strong>-I</strong>, <strong>-MF</strong>, etc) on the command
\r
2153 line may be absolute.
\r
2158 The source code file path may be absolute, and that path may substituted for
\r
2159 <code>__FILE__</code> macros in the source code or included in warnings emitted to
\r
2160 standard error by the preprocessor.
\r
2164 <div class="paragraph"><p>This means that if you compile the same code in different locations, you can’t
\r
2165 share compilation results between the different build directories since you get
\r
2166 cache misses because of the absolute build directory paths that are part of the
\r
2168 <div class="paragraph"><p>Here’s what can be done to enable cache hits between different build
\r
2169 directories:</p></div>
\r
2170 <div class="ulist"><ul>
\r
2173 If you build with <strong>-g</strong> (or similar) to add debug information to the object
\r
2174 file, you must either:
\r
2176 <div class="openblock">
\r
2177 <div class="content">
\r
2178 <div class="ulist"><ul>
\r
2181 use the <strong>-fdebug-prefix-map=<em>old</em>=<em>new</em></strong> option for relocating debug info to
\r
2182 a common prefix (e.g. <strong>-fdebug-prefix-map=$PWD=.</strong>); or
\r
2187 set <strong>hash_dir = false</strong>.
\r
2195 If you use absolute paths anywhere on the command line (e.g. the source code
\r
2196 file path or an argument to compiler options like <strong>-I</strong> and <strong>-MF</strong>), you must
\r
2197 to set <strong>base_dir</strong> to an absolute path to a “base directory”. ccache will
\r
2198 then rewrite absolute paths under that directory to relative before computing
\r
2205 <div class="sect1">
\r
2206 <h2 id="_precompiled_headers">Precompiled headers</h2>
\r
2207 <div class="sectionbody">
\r
2208 <div class="paragraph"><p>ccache has support for GCC’s precompiled headers. However, you have to do some
\r
2209 things to make it work properly:</p></div>
\r
2210 <div class="ulist"><ul>
\r
2213 You must set <strong>sloppiness</strong> to <strong>pch_defines,time_macros</strong>. The reason is that
\r
2214 ccache can’t tell whether <code>__TIME__</code> or <code>__DATE__</code> is used when using a
\r
2215 precompiled header. Further, it can’t detect changes in <strong>#define</strong>s in the
\r
2216 source code because of how preprocessing works in combination with
\r
2217 precompiled headers.
\r
2224 <div class="openblock">
\r
2225 <div class="content">
\r
2226 <div class="ulist"><ul>
\r
2229 use the <strong>-include</strong> compiler option to include the precompiled header
\r
2230 (i.e., don’t use <strong>#include</strong> in the source code to include the header); or
\r
2235 (for the Clang compiler) use the <strong>-include-pch</strong> compiler option to include
\r
2236 the PCH file generated from the precompiled header; or
\r
2241 add the <strong>-fpch-preprocess</strong> compiler option when compiling.
\r
2245 <div class="paragraph"><p>If you don’t do this, either the non-precompiled version of the header file
\r
2246 will be used (if available) or ccache will fall back to running the real
\r
2247 compiler and increase the statistics counter “preprocessor error” (if the
\r
2248 non-precompiled header file is not available).</p></div>
\r
2254 <div class="sect1">
\r
2255 <h2 id="_sharing_a_cache">Sharing a cache</h2>
\r
2256 <div class="sectionbody">
\r
2257 <div class="paragraph"><p>A group of developers can increase the cache hit rate by sharing a cache
\r
2258 directory. To share a cache without unpleasant side effects, the following
\r
2259 conditions should to be met:</p></div>
\r
2260 <div class="ulist"><ul>
\r
2263 Use the same cache directory.
\r
2268 Make sure that the configuration setting <strong>hard_link</strong> is false (which is the
\r
2274 Make sure that all users are in the same group.
\r
2279 Set the configuration setting <strong>umask</strong> to 002. This ensures that cached files
\r
2280 are accessible to everyone in the group.
\r
2285 Make sure that all users have write permission in the entire cache directory
\r
2286 (and that you trust all users of the shared cache).
\r
2291 Make sure that the setgid bit is set on all directories in the cache. This
\r
2292 tells the filesystem to inherit group ownership for new directories. The
\r
2293 following command might be useful for this:
\r
2295 <div class="openblock">
\r
2296 <div class="content">
\r
2297 <div class="listingblock">
\r
2298 <div class="content">
\r
2299 <pre><code>find $CCACHE_DIR -type d | xargs chmod g+s</code></pre>
\r
2304 <div class="paragraph"><p>The reason to avoid the hard link mode is that the hard links cause unwanted
\r
2305 side effects, as all links to a cached file share the file’s modification
\r
2306 timestamp. This results in false dependencies to be triggered by
\r
2307 timestamp-based build systems whenever another user links to an existing file.
\r
2308 Typically, users will see that their libraries and binaries are relinked
\r
2309 without reason.</p></div>
\r
2310 <div class="paragraph"><p>You may also want to make sure that a base directory is set appropriately, as
\r
2311 discussed in a previous section.</p></div>
\r
2314 <div class="sect1">
\r
2315 <h2 id="_sharing_a_cache_on_nfs">Sharing a cache on NFS</h2>
\r
2316 <div class="sectionbody">
\r
2317 <div class="paragraph"><p>It is possible to put the cache directory on an NFS filesystem (or similar
\r
2318 filesystems), but keep in mind that:</p></div>
\r
2319 <div class="ulist"><ul>
\r
2322 Having the cache on NFS may slow down compilation. Make sure to do some
\r
2323 benchmarking to see if it’s worth it.
\r
2328 ccache hasn’t been tested very thoroughly on NFS.
\r
2332 <div class="paragraph"><p>A tip is to set <strong>temporary_dir</strong> to a directory on the local host to avoid NFS
\r
2333 traffic for temporary files.</p></div>
\r
2336 <div class="sect1">
\r
2337 <h2 id="_using_ccache_with_other_compiler_wrappers">Using ccache with other compiler wrappers</h2>
\r
2338 <div class="sectionbody">
\r
2339 <div class="paragraph"><p>The recommended way of combining ccache with another compiler wrapper (such as
\r
2340 “distcc”) is by letting ccache execute the compiler wrapper. This is
\r
2341 accomplished by defining the configuration setting <strong>prefix_command</strong>, for
\r
2342 example by setting the environment variable <strong>CCACHE_PREFIX</strong> to the name of the
\r
2343 wrapper (e.g. <strong>distcc</strong>). ccache will then prefix the command line with the
\r
2344 specified command when running the compiler. To specify several prefix
\r
2345 commands, set <strong>prefix_command</strong> to a colon-separated list of commands.</p></div>
\r
2346 <div class="paragraph"><p>Unless you set <strong>compiler_check</strong> to a suitable command (see the description of
\r
2347 that configuration option), it is not recommended to use the form <strong>ccache
\r
2348 anotherwrapper compiler args</strong> as the compilation command. It’s also not
\r
2349 recommended to use the masquerading technique for the other compiler wrapper.
\r
2350 The reason is that by default, ccache will in both cases hash the mtime and
\r
2351 size of the other wrapper instead of the real compiler, which means that:</p></div>
\r
2352 <div class="ulist"><ul>
\r
2355 Compiler upgrades will not be detected properly.
\r
2360 The cached results will not be shared between compilations with and without
\r
2361 the other wrapper.
\r
2365 <div class="paragraph"><p>Another minor thing is that if <strong>prefix_command</strong> is used, ccache will not invoke
\r
2366 the other wrapper when running the preprocessor, which increases performance.
\r
2367 You can use the <strong>prefix_command_cpp</strong> configuration setting if you also want to
\r
2368 invoke the other wrapper when doing preprocessing (normally by adding <strong>-E</strong>).</p></div>
\r
2371 <div class="sect1">
\r
2372 <h2 id="_caveats">Caveats</h2>
\r
2373 <div class="sectionbody">
\r
2374 <div class="ulist"><ul>
\r
2377 The direct mode fails to pick up new header files in some rare scenarios. See
\r
2378 <a href="#_the_direct_mode">THE DIRECT MODE</a> above.
\r
2383 When run via ccache, warning messages produced by GCC 4.9 and newer will only
\r
2384 be colored when the environment variable <strong>GCC_COLORS</strong> is set. An alternative
\r
2385 to setting <strong>GCC_COLORS</strong> is to pass <code>-fdiagnostics-color</code> explicitly when
\r
2386 compiling (but then color codes will also be present when redirecting stderr
\r
2392 If ccache guesses that the compiler may emit colored warnings, then a
\r
2393 compilation with stderr referring to a TTY will be considered different from
\r
2394 a compilation with a redirected stderr, thus not sharing cache entries. This
\r
2395 happens for clang by default and for GCC when <strong>GCC_COLORS</strong> is set as
\r
2396 mentioned above. If you want to share cache hits, you can pass
\r
2397 <code>-f[no-]diagnostics-color</code> (GCC) or <code>-f[no-]color-diagnostics</code> (clang)
\r
2398 explicitly when compiling (but then color codes will be either on or off for
\r
2399 both the TTY and the redirected case).
\r
2405 <div class="sect1">
\r
2406 <h2 id="_troubleshooting">Troubleshooting</h2>
\r
2407 <div class="sectionbody">
\r
2408 <div class="sect2">
\r
2409 <h3 id="_general">General</h3>
\r
2410 <div class="paragraph"><p>A general tip for getting information about what ccache is doing is to enable
\r
2411 debug logging by setting <strong>log_file</strong>. The log contains executed commands,
\r
2412 important decisions that ccache makes, read and written files, etc. Another way
\r
2413 of keeping track of what is happening is to check the output of <strong>ccache -s</strong>.</p></div>
\r
2415 <div class="sect2">
\r
2416 <h3 id="_performance">Performance</h3>
\r
2417 <div class="paragraph"><p>ccache has been written to perform well out of the box, but sometimes you may
\r
2418 have to do some adjustments of how you use the compiler and ccache in order to
\r
2419 improve performance.</p></div>
\r
2420 <div class="paragraph"><p>Since ccache works best when I/O is fast, put the cache directory on a fast
\r
2421 storage device if possible. Having lots of free memory so that files in the
\r
2422 cache directory stay in the disk cache is also preferable.</p></div>
\r
2423 <div class="paragraph"><p>A good way of monitoring how well ccache works is to run <strong>ccache -s</strong> before and
\r
2424 after your build and then compare the statistics counters. Here are some common
\r
2425 problems and what may be done to increase the hit rate:</p></div>
\r
2426 <div class="ulist"><ul>
\r
2429 If “cache hit (preprocessed)” has been incremented instead of “cache hit
\r
2430 (direct)”, ccache has fallen back to preprocessor mode, which is generally
\r
2431 slower. Some possible reasons are:
\r
2433 <div class="ulist"><ul>
\r
2436 The source code has been modified in such a way that the preprocessor output
\r
2442 Compiler arguments that are hashed in the direct mode but not in the
\r
2443 preprocessor mode have changed (<strong>-I</strong>, <strong>-include</strong>, <strong>-D</strong>, etc) and they didn’t
\r
2444 affect the preprocessor output.
\r
2449 The compiler option <strong>-Xpreprocessor</strong> or <strong>-Wp,<em>X</em></strong> (except <strong>-Wp,-MD,<em>path</em></strong>,
\r
2450 <strong>-Wp,-MMD,<em>path</em></strong>, and <strong>-Wp,-D_define_</strong>) is used.
\r
2455 This was the first compilation with a new value of the base directory
\r
2461 A modification time of one of the include files is too new (created the same
\r
2462 second as the compilation is being done). This check is made to avoid a race
\r
2463 condition. To fix this, create the include file earlier in the build
\r
2464 process, if possible, or set <strong>sloppiness</strong> to <strong>include_file_mtime</strong> if you are
\r
2465 willing to take the risk. (The race condition consists of these events: the
\r
2466 preprocessor is run; an include file is modified by someone; the new include
\r
2467 file is hashed by ccache; the real compiler is run on the preprocessor’s
\r
2468 output, which contains data from the old header file; the wrong object file
\r
2469 is stored in the cache.)
\r
2474 The <code>__TIME__</code> preprocessor macro is (potentially) being used. ccache turns
\r
2475 off direct mode if <code>__TIME__</code> is present in the source code. This is done as
\r
2476 a safety measure since the string indicates that a <code>__TIME__</code> macro <em>may</em>
\r
2477 affect the output. (To be sure, ccache would have to run the preprocessor,
\r
2478 but the sole point of the direct mode is to avoid that.) If you know that
\r
2479 <code>__TIME__</code> isn’t used in practise, or don’t care if ccache produces objects
\r
2480 where <code>__TIME__</code> is expanded to something in the past, you can set
\r
2481 <strong>sloppiness</strong> to <strong>time_macros</strong>.
\r
2486 The <code>__DATE__</code> preprocessor macro is (potentially) being used and the date
\r
2487 has changed. This is similar to how <code>__TIME__</code> is handled. If <code>__DATE__</code> is
\r
2488 present in the source code, ccache hashes the current date in order to be
\r
2489 able to produce the correct object file if the <code>__DATE__</code> macro affects the
\r
2490 output. If you know that <code>__DATE__</code> isn’t used in practise, or don’t care if
\r
2491 ccache produces objects where <code>__DATE__</code> is expanded to something in the
\r
2492 past, you can set <strong>sloppiness</strong> to <strong>time_macros</strong>.
\r
2497 The <code>__FILE__</code> preprocessor macro is (potentially) being used and the file
\r
2498 path has changed. If <code>__FILE__</code> is present in the source code, ccache hashes
\r
2499 the current input file path in order to be able to produce the correct
\r
2500 object file if the <code>__FILE__</code> macro affects the output. If you know that
\r
2501 <code>__FILE__</code> isn’t used in practise, or don’t care if ccache produces objects
\r
2502 where <code>__FILE__</code> is expanded to the wrong path, you can set <strong>sloppiness</strong> to
\r
2503 <strong>file_macro</strong>.
\r
2510 If “cache miss” has been incremented even though the same code has been
\r
2511 compiled and cached before, ccache has either detected that something has
\r
2512 changed anyway or a cleanup has been performed (either explicitly or
\r
2513 implicitly when a cache limit has been reached). Some perhaps unobvious
\r
2514 things that may result in a cache miss are usage of <code>__TIME__</code> or
\r
2515 <code>__DATE__</code> macros, or use of automatically generated code that contains a
\r
2516 timestamp, build counter or other volatile information.
\r
2521 If “multiple source files” has been incremented, it’s an indication that
\r
2522 the compiler has been invoked on several source code files at once. ccache
\r
2523 doesn’t support that. Compile the source code files separately if possible.
\r
2528 If “unsupported compiler option” has been incremented, enable debug logging
\r
2529 and check which option was rejected.
\r
2534 If “preprocessor error” has been incremented, one possible reason is that
\r
2535 precompiled headers are being used. See <a href="#_precompiled_headers">PRECOMPILED HEADERS</a> for how to remedy this.
\r
2540 If “can’t use precompiled header” has been incremented, see
\r
2541 <a href="#_precompiled_headers">PRECOMPILED HEADERS</a>.
\r
2546 <div class="sect2">
\r
2547 <h3 id="_corrupt_object_files">Corrupt object files</h3>
\r
2548 <div class="paragraph"><p>It should be noted that ccache is susceptible to general storage problems. If a
\r
2549 bad object file sneaks into the cache for some reason, it will of course stay
\r
2550 bad. Some possible reasons for erroneous object files are bad hardware (disk
\r
2551 drive, disk controller, memory, etc), buggy drivers or file systems, a bad
\r
2552 <strong>prefix_command</strong> or compiler wrapper. If this happens, the easiest way of
\r
2553 fixing it is this:</p></div>
\r
2554 <div class="olist arabic"><ol class="arabic">
\r
2557 Build so that the bad object file ends up in the build tree.
\r
2562 Remove the bad object file from the build tree.
\r
2567 Rebuild with <strong>CCACHE_RECACHE</strong> set.
\r
2571 <div class="paragraph"><p>An alternative is to clear the whole cache with <strong>ccache -C</strong> if you don’t mind
\r
2572 losing other cached results.</p></div>
\r
2573 <div class="paragraph"><p>There are no reported issues about ccache producing broken object files
\r
2574 reproducibly. That doesn’t mean it can’t happen, so if you find a repeatable
\r
2575 case, please report it.</p></div>
\r
2579 <div class="sect1">
\r
2580 <h2 id="_more_information">More information</h2>
\r
2581 <div class="sectionbody">
\r
2582 <div class="paragraph"><p>Credits, mailing list information, bug reporting instructions, source code,
\r
2583 etc, can be found on ccache’s web site: <a href="https://ccache.samba.org">https://ccache.samba.org</a>.</p></div>
\r
2586 <div class="sect1">
\r
2587 <h2 id="_author">Author</h2>
\r
2588 <div class="sectionbody">
\r
2589 <div class="paragraph"><p>ccache was originally written by Andrew Tridgell and is currently developed and
\r
2590 maintained by Joel Rosdahl. See AUTHORS.txt or AUTHORS.html and
\r
2591 <a href="https://ccache.samba.org/credits.html">https://ccache.samba.org/credits.html</a> for a list of contributors.</p></div>
\r
2595 <div id="footnotes"><hr /></div>
\r
2597 <div id="footer-text">
\r
2598 Version 3.5.1<br />
\r
2600 2019-01-03 21:16:33 CET
\r
projects / platform / upstream / ccache.git / blob