1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
\r
2 "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
\r
3 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
\r
5 <meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" />
\r
6 <meta name="generator" content="AsciiDoc 8.6.9" />
\r
7 <title>CCACHE(1)</title>
\r
8 <style type="text/css">
\r
9 /* Shared CSS for AsciiDoc xhtml11 and html5 backends */
\r
13 font-family: Georgia,serif;
\r
17 h1, h2, h3, h4, h5, h6,
\r
18 div.title, caption.title,
\r
19 thead, p.table.header,
\r
21 #author, #revnumber, #revdate, #revremark,
\r
23 font-family: Arial,Helvetica,sans-serif;
\r
27 margin: 1em 5% 1em 5%;
\r
32 text-decoration: underline;
\r
48 h1, h2, h3, h4, h5, h6 {
\r
51 margin-bottom: 0.5em;
\r
56 border-bottom: 2px solid silver;
\r
76 border: 1px solid silver;
\r
81 margin-bottom: 0.5em;
\r
87 ul > li { color: #aaa; }
\r
88 ul > li > * { color: black; }
\r
90 .monospaced, code, pre {
\r
91 font-family: "Courier New", Courier, monospace;
\r
98 white-space: pre-wrap;
\r
108 #revnumber, #revdate, #revremark {
\r
113 border-top: 2px solid silver;
\r
114 padding-top: 0.5em;
\r
119 padding-bottom: 0.5em;
\r
123 padding-bottom: 0.5em;
\r
128 margin-bottom: 1.5em;
\r
130 div.imageblock, div.exampleblock, div.verseblock,
\r
131 div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
\r
132 div.admonitionblock {
\r
134 margin-bottom: 1.5em;
\r
136 div.admonitionblock {
\r
138 margin-bottom: 2.0em;
\r
143 div.content { /* Block element content. */
\r
147 /* Block element titles. */
\r
148 div.title, caption.title {
\r
153 margin-bottom: 0.5em;
\r
159 td div.title:first-child {
\r
162 div.content div.title:first-child {
\r
165 div.content + div.title {
\r
169 div.sidebarblock > div.content {
\r
170 background: #ffffee;
\r
171 border: 1px solid #dddddd;
\r
172 border-left: 4px solid #f0f0f0;
\r
176 div.listingblock > div.content {
\r
177 border: 1px solid #dddddd;
\r
178 border-left: 5px solid #f0f0f0;
\r
179 background: #f8f8f8;
\r
183 div.quoteblock, div.verseblock {
\r
184 padding-left: 1.0em;
\r
185 margin-left: 1.0em;
\r
187 border-left: 5px solid #f0f0f0;
\r
191 div.quoteblock > div.attribution {
\r
192 padding-top: 0.5em;
\r
196 div.verseblock > pre.content {
\r
197 font-family: inherit;
\r
198 font-size: inherit;
\r
200 div.verseblock > div.attribution {
\r
201 padding-top: 0.75em;
\r
204 /* DEPRECATED: Pre version 8.2.7 verse style literal block. */
\r
205 div.verseblock + div.attribution {
\r
209 div.admonitionblock .icon {
\r
210 vertical-align: top;
\r
213 text-decoration: underline;
\r
215 padding-right: 0.5em;
\r
217 div.admonitionblock td.content {
\r
218 padding-left: 0.5em;
\r
219 border-left: 3px solid #dddddd;
\r
222 div.exampleblock > div.content {
\r
223 border-left: 3px solid #dddddd;
\r
224 padding-left: 0.5em;
\r
227 div.imageblock div.content { padding-left: 0; }
\r
228 span.image img { border-style: none; vertical-align: text-bottom; }
\r
229 a.image:visited { color: white; }
\r
233 margin-bottom: 0.8em;
\r
238 font-style: normal;
\r
241 dd > *:first-child {
\r
246 list-style-position: outside;
\r
249 list-style-type: decimal;
\r
252 list-style-type: lower-alpha;
\r
255 list-style-type: upper-alpha;
\r
258 list-style-type: lower-roman;
\r
261 list-style-type: upper-roman;
\r
264 div.compact ul, div.compact ol,
\r
265 div.compact p, div.compact p,
\r
266 div.compact div, div.compact div {
\r
268 margin-bottom: 0.1em;
\r
280 margin-bottom: 0.8em;
\r
283 padding-bottom: 15px;
\r
285 dt.hdlist1.strong, td.hdlist1.strong {
\r
289 vertical-align: top;
\r
290 font-style: normal;
\r
291 padding-right: 0.8em;
\r
295 vertical-align: top;
\r
297 div.hdlist.compact tr {
\r
303 background: yellow;
\r
306 .footnote, .footnoteref {
\r
310 span.footnote, span.footnoteref {
\r
311 vertical-align: super;
\r
315 margin: 20px 0 20px 0;
\r
316 padding: 7px 0 0 0;
\r
319 #footnotes div.footnote {
\r
325 border-top: 1px solid silver;
\r
334 padding-right: 0.5em;
\r
335 padding-bottom: 0.3em;
\r
336 vertical-align: top;
\r
338 div.colist td img {
\r
343 #footer-badges { display: none; }
\r
347 margin-bottom: 2.5em;
\r
355 margin-bottom: 0.1em;
\r
358 div.toclevel0, div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
\r
375 span.aqua { color: aqua; }
\r
376 span.black { color: black; }
\r
377 span.blue { color: blue; }
\r
378 span.fuchsia { color: fuchsia; }
\r
379 span.gray { color: gray; }
\r
380 span.green { color: green; }
\r
381 span.lime { color: lime; }
\r
382 span.maroon { color: maroon; }
\r
383 span.navy { color: navy; }
\r
384 span.olive { color: olive; }
\r
385 span.purple { color: purple; }
\r
386 span.red { color: red; }
\r
387 span.silver { color: silver; }
\r
388 span.teal { color: teal; }
\r
389 span.white { color: white; }
\r
390 span.yellow { color: yellow; }
\r
392 span.aqua-background { background: aqua; }
\r
393 span.black-background { background: black; }
\r
394 span.blue-background { background: blue; }
\r
395 span.fuchsia-background { background: fuchsia; }
\r
396 span.gray-background { background: gray; }
\r
397 span.green-background { background: green; }
\r
398 span.lime-background { background: lime; }
\r
399 span.maroon-background { background: maroon; }
\r
400 span.navy-background { background: navy; }
\r
401 span.olive-background { background: olive; }
\r
402 span.purple-background { background: purple; }
\r
403 span.red-background { background: red; }
\r
404 span.silver-background { background: silver; }
\r
405 span.teal-background { background: teal; }
\r
406 span.white-background { background: white; }
\r
407 span.yellow-background { background: yellow; }
\r
409 span.big { font-size: 2em; }
\r
410 span.small { font-size: 0.6em; }
\r
412 span.underline { text-decoration: underline; }
\r
413 span.overline { text-decoration: overline; }
\r
414 span.line-through { text-decoration: line-through; }
\r
416 div.unbreakable { page-break-inside: avoid; }
\r
426 margin-bottom: 1.5em;
\r
428 div.tableblock > table {
\r
429 border: 3px solid #527bbd;
\r
431 thead, p.table.header {
\r
438 /* Because the table frame attribute is overriden by CSS in most browsers. */
\r
439 div.tableblock > table[frame="void"] {
\r
440 border-style: none;
\r
442 div.tableblock > table[frame="hsides"] {
\r
443 border-left-style: none;
\r
444 border-right-style: none;
\r
446 div.tableblock > table[frame="vsides"] {
\r
447 border-top-style: none;
\r
448 border-bottom-style: none;
\r
459 margin-bottom: 1.5em;
\r
461 thead, p.tableblock.header {
\r
470 border-spacing: 0px;
\r
471 border-style: solid;
\r
472 border-color: #527bbd;
\r
473 border-collapse: collapse;
\r
475 th.tableblock, td.tableblock {
\r
478 border-style: solid;
\r
479 border-color: #527bbd;
\r
482 table.tableblock.frame-topbot {
\r
483 border-left-style: hidden;
\r
484 border-right-style: hidden;
\r
486 table.tableblock.frame-sides {
\r
487 border-top-style: hidden;
\r
488 border-bottom-style: hidden;
\r
490 table.tableblock.frame-none {
\r
491 border-style: hidden;
\r
494 th.tableblock.halign-left, td.tableblock.halign-left {
\r
497 th.tableblock.halign-center, td.tableblock.halign-center {
\r
498 text-align: center;
\r
500 th.tableblock.halign-right, td.tableblock.halign-right {
\r
504 th.tableblock.valign-top, td.tableblock.valign-top {
\r
505 vertical-align: top;
\r
507 th.tableblock.valign-middle, td.tableblock.valign-middle {
\r
508 vertical-align: middle;
\r
510 th.tableblock.valign-bottom, td.tableblock.valign-bottom {
\r
511 vertical-align: bottom;
\r
521 padding-top: 0.5em;
\r
522 padding-bottom: 0.5em;
\r
523 border-top: 2px solid silver;
\r
524 border-bottom: 2px solid silver;
\r
527 border-style: none;
\r
529 body.manpage div.sectionbody {
\r
534 body.manpage div#toc { display: none; }
\r
539 <script type="text/javascript">
\r
541 var asciidoc = { // Namespace.
\r
543 /////////////////////////////////////////////////////////////////////
\r
544 // Table Of Contents generator
\r
545 /////////////////////////////////////////////////////////////////////
\r
547 /* Author: Mihai Bazon, September 2002
\r
548 * http://students.infoiasi.ro/~mishoo
\r
550 * Table Of Content generator
\r
553 * Feel free to use this script under the terms of the GNU General Public
\r
554 * License, as long as you do not remove or alter this notice.
\r
557 /* modified by Troy D. Hanson, September 2006. License: GPL */
\r
558 /* modified by Stuart Rackham, 2006, 2009. License: GPL */
\r
560 // toclevels = 1..4.
\r
561 toc: function (toclevels) {
\r
563 function getText(el) {
\r
565 for (var i = el.firstChild; i != null; i = i.nextSibling) {
\r
566 if (i.nodeType == 3 /* Node.TEXT_NODE */) // IE doesn't speak constants.
\r
568 else if (i.firstChild != null)
\r
569 text += getText(i);
\r
574 function TocEntry(el, text, toclevel) {
\r
577 this.toclevel = toclevel;
\r
580 function tocEntries(el, toclevels) {
\r
581 var result = new Array;
\r
582 var re = new RegExp('[hH]([1-'+(toclevels+1)+'])');
\r
583 // Function that scans the DOM tree for header elements (the DOM2
\r
584 // nodeIterator API would be a better technique but not supported by all
\r
586 var iterate = function (el) {
\r
587 for (var i = el.firstChild; i != null; i = i.nextSibling) {
\r
588 if (i.nodeType == 1 /* Node.ELEMENT_NODE */) {
\r
589 var mo = re.exec(i.tagName);
\r
590 if (mo && (i.getAttribute("class") || i.getAttribute("className")) != "float") {
\r
591 result[result.length] = new TocEntry(i, getText(i), mo[1]-1);
\r
601 var toc = document.getElementById("toc");
\r
606 // Delete existing TOC entries in case we're reloading the TOC.
\r
607 var tocEntriesToRemove = [];
\r
609 for (i = 0; i < toc.childNodes.length; i++) {
\r
610 var entry = toc.childNodes[i];
\r
611 if (entry.nodeName.toLowerCase() == 'div'
\r
612 && entry.getAttribute("class")
\r
613 && entry.getAttribute("class").match(/^toclevel/))
\r
614 tocEntriesToRemove.push(entry);
\r
616 for (i = 0; i < tocEntriesToRemove.length; i++) {
\r
617 toc.removeChild(tocEntriesToRemove[i]);
\r
620 // Rebuild TOC entries.
\r
621 var entries = tocEntries(document.getElementById("content"), toclevels);
\r
622 for (var i = 0; i < entries.length; ++i) {
\r
623 var entry = entries[i];
\r
624 if (entry.element.id == "")
\r
625 entry.element.id = "_toc_" + i;
\r
626 var a = document.createElement("a");
\r
627 a.href = "#" + entry.element.id;
\r
628 a.appendChild(document.createTextNode(entry.text));
\r
629 var div = document.createElement("div");
\r
630 div.appendChild(a);
\r
631 div.className = "toclevel" + entry.toclevel;
\r
632 toc.appendChild(div);
\r
634 if (entries.length == 0)
\r
635 toc.parentNode.removeChild(toc);
\r
639 /////////////////////////////////////////////////////////////////////
\r
640 // Footnotes generator
\r
641 /////////////////////////////////////////////////////////////////////
\r
643 /* Based on footnote generation code from:
\r
644 * http://www.brandspankingnew.net/archive/2005/07/format_footnote.html
\r
647 footnotes: function () {
\r
648 // Delete existing footnote entries in case we're reloading the footnodes.
\r
650 var noteholder = document.getElementById("footnotes");
\r
654 var entriesToRemove = [];
\r
655 for (i = 0; i < noteholder.childNodes.length; i++) {
\r
656 var entry = noteholder.childNodes[i];
\r
657 if (entry.nodeName.toLowerCase() == 'div' && entry.getAttribute("class") == "footnote")
\r
658 entriesToRemove.push(entry);
\r
660 for (i = 0; i < entriesToRemove.length; i++) {
\r
661 noteholder.removeChild(entriesToRemove[i]);
\r
664 // Rebuild footnote entries.
\r
665 var cont = document.getElementById("content");
\r
666 var spans = cont.getElementsByTagName("span");
\r
669 for (i=0; i<spans.length; i++) {
\r
670 if (spans[i].className == "footnote") {
\r
672 var note = spans[i].getAttribute("data-note");
\r
674 // Use [\s\S] in place of . so multi-line matches work.
\r
675 // Because JavaScript has no s (dotall) regex flag.
\r
676 note = spans[i].innerHTML.match(/\s*\[([\s\S]*)]\s*/)[1];
\r
677 spans[i].innerHTML =
\r
678 "[<a id='_footnoteref_" + n + "' href='#_footnote_" + n +
\r
679 "' title='View footnote' class='footnote'>" + n + "</a>]";
\r
680 spans[i].setAttribute("data-note", note);
\r
682 noteholder.innerHTML +=
\r
683 "<div class='footnote' id='_footnote_" + n + "'>" +
\r
684 "<a href='#_footnoteref_" + n + "' title='Return to text'>" +
\r
685 n + "</a>. " + note + "</div>";
\r
686 var id =spans[i].getAttribute("id");
\r
687 if (id != null) refs["#"+id] = n;
\r
691 noteholder.parentNode.removeChild(noteholder);
\r
693 // Process footnoterefs.
\r
694 for (i=0; i<spans.length; i++) {
\r
695 if (spans[i].className == "footnoteref") {
\r
696 var href = spans[i].getElementsByTagName("a")[0].getAttribute("href");
\r
697 href = href.match(/#.*/)[0]; // Because IE return full URL.
\r
699 spans[i].innerHTML =
\r
700 "[<a href='#_footnote_" + n +
\r
701 "' title='View footnote' class='footnote'>" + n + "</a>]";
\r
707 install: function(toclevels) {
\r
710 function reinstall() {
\r
711 asciidoc.footnotes();
\r
713 asciidoc.toc(toclevels);
\r
717 function reinstallAndRemoveTimer() {
\r
718 clearInterval(timerId);
\r
722 timerId = setInterval(reinstall, 500);
\r
723 if (document.addEventListener)
\r
724 document.addEventListener("DOMContentLoaded", reinstallAndRemoveTimer, false);
\r
726 window.onload = reinstallAndRemoveTimer;
\r
730 asciidoc.install(2);
\r
734 <body class="article">
\r
737 <span id="revnumber">version 3.2.6</span>
\r
739 <div id="toctitle">Table of Contents</div>
740 <noscript><p><b>JavaScript must be enabled in your browser to display the table of contents.</b></p></noscript>
744 <div class="sect1">
\r
745 <h2 id="_name">Name</h2>
\r
746 <div class="sectionbody">
\r
747 <div class="paragraph"><p>ccache - a fast C/C++ compiler cache</p></div>
\r
750 <div class="sect1">
\r
751 <h2 id="_synopsis">Synopsis</h2>
\r
752 <div class="sectionbody">
\r
753 <div class="verseblock">
\r
754 <pre class="content"><strong>ccache</strong> [<em>options</em>]
\r
755 <strong>ccache</strong> <em>compiler</em> [<em>compiler options</em>]
\r
756 <em>compiler</em> [<em>compiler options</em>] (via symbolic link)</pre>
\r
757 <div class="attribution">
\r
761 <div class="sect1">
\r
762 <h2 id="_description">Description</h2>
\r
763 <div class="sectionbody">
\r
764 <div class="paragraph"><p>ccache is a compiler cache. It speeds up recompilation by caching the result of
\r
765 previous compilations and detecting when the same compilation is being done
\r
766 again. Supported languages are C, C++, Objective-C and Objective-C++.</p></div>
\r
767 <div class="paragraph"><p>ccache has been carefully written to always produce exactly the same compiler
\r
768 output that you would get without the cache. The only way you should be able to
\r
769 tell that you are using ccache is the speed. Currently known exceptions to this
\r
770 goal are listed under <a href="#_bugs">BUGS</a>. If you ever discover an undocumented case
\r
771 where ccache changes the output of your compiler, please let us know.</p></div>
\r
772 <div class="sect2">
\r
773 <h3 id="_features">Features</h3>
\r
774 <div class="ulist"><ul>
\r
777 Keeps statistics on hits/misses.
\r
782 Automatic cache size management.
\r
787 Can cache compilations that generate warnings.
\r
802 Optionally uses hard links where possible to avoid copies.
\r
807 Optionally compresses files in the cache to reduce disk space.
\r
812 <div class="sect2">
\r
813 <h3 id="_limitations">Limitations</h3>
\r
814 <div class="ulist"><ul>
\r
817 Only knows how to cache the compilation of a single
\r
818 C/C++/Objective-C/Objective-C++ file. Other types of compilations
\r
819 (multi-file compilation, linking, etc) will silently fall back to running the
\r
825 Only works with GCC and compilers that behave similar enough.
\r
830 Some compiler flags are not supported. If such a flag is detected, ccache
\r
831 will silently fall back to running the real compiler.
\r
838 <div class="sect1">
\r
839 <h2 id="_run_modes">Run modes</h2>
\r
840 <div class="sectionbody">
\r
841 <div class="paragraph"><p>There are two ways to use ccache. You can either prefix your compilation
\r
842 commands with <strong>ccache</strong> or you can let ccache masquerade as the compiler by
\r
843 creating a symbolic link (named as the compiler) to ccache. The first method is
\r
844 most convenient if you just want to try out ccache or wish to use it for some
\r
845 specific projects. The second method is most useful for when you wish to use
\r
846 ccache for all your compilations.</p></div>
\r
847 <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
848 <div class="paragraph"><p>To use the symlinks method, do something like this:</p></div>
\r
849 <div class="listingblock">
\r
850 <div class="content">
\r
851 <pre><code>cp ccache /usr/local/bin/
\r
852 ln -s ccache /usr/local/bin/gcc
\r
853 ln -s ccache /usr/local/bin/g++
\r
854 ln -s ccache /usr/local/bin/cc
\r
855 ln -s ccache /usr/local/bin/c++</code></pre>
\r
857 <div class="paragraph"><p>And so forth. This will work as long as the directory with symlinks comes
\r
858 before the path to the compiler (which is usually in <code>/usr/bin</code>). After
\r
859 installing you may wish to run “which gcc” to make sure that the correct link
\r
860 is being used.</p></div>
\r
861 <div class="admonitionblock">
\r
864 <div class="title">Warning</div>
\r
866 <td class="content">The technique of letting ccache masquerade as the compiler works well,
\r
867 but currently doesn’t interact well with other tools that do the same thing.
\r
868 See <a href="#_using_ccache_with_other_compiler_wrappers">USING CCACHE WITH OTHER COMPILER WRAPPERS</a>.</td>
\r
871 <div class="admonitionblock">
\r
874 <div class="title">Warning</div>
\r
876 <td class="content">Do not use a hard link, use a symbolic link. A hard link will cause
\r
877 “interesting” problems.</td>
\r
882 <div class="sect1">
\r
883 <h2 id="_options">Options</h2>
\r
884 <div class="sectionbody">
\r
885 <div class="paragraph"><p>These options only apply when you invoke ccache as “ccache”. When invoked as
\r
886 a compiler (via a symlink as described in the previous section), the normal
\r
887 compiler options apply and you should refer to the compiler’s documentation.</p></div>
\r
888 <div class="dlist"><dl>
\r
889 <dt class="hdlist1">
\r
890 <strong>-c, --cleanup</strong>
\r
894 Clean up the cache by removing old cached files until the specified file
\r
895 number and cache size limits are not exceeded. This also recalculates the
\r
896 cache file count and size totals. Normally, there is no need to initiate
\r
897 cleanup manually as ccache keeps the cache below the specified limits at
\r
898 runtime and keeps statistics up to date on each compilation. Forcing a
\r
899 cleanup is mostly useful if you manually modify the cache contents or
\r
900 believe that the cache size statistics may be inaccurate.
\r
903 <dt class="hdlist1">
\r
904 <strong>-C, --clear</strong>
\r
908 Clear the entire cache, removing all cached files, but keeping the
\r
909 configuration file.
\r
912 <dt class="hdlist1">
\r
913 <strong>-F, --max-files</strong>=<em>N</em>
\r
917 Set the maximum number of files allowed in the cache. Use 0 for no limit.
\r
918 The value is stored in a configuration file in the cache directory and
\r
919 applies to all future compilations.
\r
922 <dt class="hdlist1">
\r
923 <strong>-h, --help</strong>
\r
927 Print an options summary page.
\r
930 <dt class="hdlist1">
\r
931 <strong>-M, --max-size</strong>=<em>SIZE</em>
\r
935 Set the maximum size of the files stored in the cache. <em>SIZE</em> should be a
\r
936 number followed by an optional suffix: k, M, G, T (decimal), Ki, Mi, Gi or
\r
937 Ti (binary). The default suffix is G. Use 0 for no limit. The value is
\r
938 stored in a configuration file in the cache directory and applies to all
\r
939 future compilations.
\r
942 <dt class="hdlist1">
\r
943 <strong>-o, --set-config</strong>=<em>KEY=VALUE</em>
\r
947 Set configuration <em>KEY</em> to <em>VALUE</em>. See <a href="#_configuration">CONFIGURATION</a>
\r
948 for more information.
\r
951 <dt class="hdlist1">
\r
952 <strong>-p, --print-config</strong>
\r
956 Print current configuration options and from where they originate
\r
957 (environment variable, configuration file or compile-time default).
\r
960 <dt class="hdlist1">
\r
961 <strong>-s, --show-stats</strong>
\r
965 Print the current statistics summary for the cache.
\r
968 <dt class="hdlist1">
\r
969 <strong>-V, --version</strong>
\r
973 Print version and copyright information.
\r
976 <dt class="hdlist1">
\r
977 <strong>-z, --zero-stats</strong>
\r
981 Zero the cache statistics (but not the configuration options).
\r
987 <div class="sect1">
\r
988 <h2 id="_extra_options">Extra options</h2>
\r
989 <div class="sectionbody">
\r
990 <div class="paragraph"><p>When run as a compiler, ccache usually just takes the same command line options
\r
991 as the compiler you are using. The only exception to this is the option
\r
992 <strong>--ccache-skip</strong>. That option can be used to tell ccache to avoid interpreting
\r
993 the next option in any way and to pass it along to the compiler as-is. <strong>Note</strong>:
\r
994 <strong>--ccache-skip</strong> currently only tells ccache not to interpret the next option as
\r
995 a special compiler option — the option will still be included in the direct
\r
996 mode hash.</p></div>
\r
997 <div class="paragraph"><p>The reason this can be important is that ccache does need to parse the command
\r
998 line and determine what is an input filename and what is a compiler option, as
\r
999 it needs the input filename to determine the name of the resulting object file
\r
1000 (among other things). The heuristic ccache uses when parsing the command line
\r
1001 is that any argument that exists as a file is treated as an input file name. By
\r
1002 using <strong>--ccache-skip</strong> you can force an option to not be treated as an input
\r
1003 file name and instead be passed along to the compiler as a command line option.</p></div>
\r
1004 <div class="paragraph"><p>Another case where <strong>--ccache-skip</strong> can be useful is if ccache interprets an
\r
1005 option specially but shouldn’t, since the option has another meaning for your
\r
1006 compiler than what ccache thinks.</p></div>
\r
1009 <div class="sect1">
\r
1010 <h2 id="_configuration">Configuration</h2>
\r
1011 <div class="sectionbody">
\r
1012 <div class="paragraph"><p>ccache’s default behavior can be overridden by configuration file settings,
\r
1013 which in turn can be overridden by environment variables with names starting
\r
1014 with <strong>CCACHE_</strong>. ccache normally reads configuration from two files: first a
\r
1015 system-level configuration file and secondly a cache-specific configuration
\r
1016 file. The priority of configuration settings is as follows (where 1 is
\r
1017 highest):</p></div>
\r
1018 <div class="olist arabic"><ol class="arabic">
\r
1021 Environment variables.
\r
1026 The cache-specific configuration file <strong><ccachedir>/ccache.conf</strong> (typically
\r
1027 <strong>$HOME/.ccache/ccache.conf</strong>).
\r
1032 The system-wide configuration file <strong><sysconfdir>/ccache.conf</strong> (typically
\r
1033 <strong>/etc/ccache.conf</strong> or <strong>/usr/local/etc/ccache.conf</strong>).
\r
1038 Compile-time defaults.
\r
1042 <div class="paragraph"><p>As a special case, if the environment variable <strong>CCACHE_CONFIGPATH</strong> is set,
\r
1043 ccache reads configuration from the specified path instead of the default
\r
1045 <div class="sect2">
\r
1046 <h3 id="_configuration_file_syntax">Configuration file syntax</h3>
\r
1047 <div class="paragraph"><p>Configuration files are in a simple “key = value” format, one setting per
\r
1048 line. Lines starting with a hash sign are comments. Blank lines are ignored, as
\r
1049 is whitespace surrounding keys and values. Example:</p></div>
\r
1050 <div class="listingblock">
\r
1051 <div class="content">
\r
1052 <pre><code># Set maximum cache size to 10 GB:
\r
1053 max_size = 10G</code></pre>
\r
1056 <div class="sect2">
\r
1057 <h3 id="_boolean_values">Boolean values</h3>
\r
1058 <div class="paragraph"><p>Some settings are boolean values (i.e. truth values). In a configuration file,
\r
1059 such values must be set to the string <strong>true</strong> or <strong>false</strong>. For the corresponding
\r
1060 environment variables, the semantics are a bit different: a set environment
\r
1061 variable means “true” regardless of the value (even if set to the empty
\r
1062 string), and an unset environment variable means “false”. Each boolean
\r
1063 environment variable also has a negated form starting with <strong>CCACHE_NO</strong>. For
\r
1064 example, <strong>CCACHE_COMPRESS</strong> can be set to force compression and
\r
1065 <strong>CCACHE_NOCOMPRESS</strong> can be set to force no compression.</p></div>
\r
1067 <div class="sect2">
\r
1068 <h3 id="_configuration_settings">Configuration settings</h3>
\r
1069 <div class="paragraph"><p>Below is a list of available configuration settings. The corresponding
\r
1070 environment variable name is indicated in parentheses after each configuration
\r
1071 setting key.</p></div>
\r
1072 <div class="dlist"><dl>
\r
1073 <dt class="hdlist1">
\r
1074 <strong>base_dir</strong> (<strong>CCACHE_BASEDIR</strong>)
\r
1078 This setting should be an absolute path to a directory. ccache then
\r
1079 rewrites absolute paths into relative paths before computing the hash that
\r
1080 identifies the compilation, but only for paths under the specified
\r
1081 directory. If set to the empty string (which is the default), no rewriting
\r
1082 is done. See also the discussion under
\r
1083 <a href="#_compiling_in_different_directories">COMPILING IN DIFFERENT DIRECTORIES</a>.
\r
1086 <dt class="hdlist1">
\r
1087 <strong>cache_dir</strong> (<strong>CCACHE_DIR</strong>)
\r
1091 This setting specifies where ccache will keep its cached compiler outputs.
\r
1092 It will only take effect if set in the system-wide configuration file or as
\r
1093 an environment variable. The default is <strong>$HOME/.ccache</strong>.
\r
1096 <dt class="hdlist1">
\r
1097 <strong>cache_dir_levels</strong> (<strong>CCACHE_NLEVELS</strong>)
\r
1101 This setting allows you to choose the number of directory levels in the
\r
1102 cache directory. The default is 2. The minimum is 1 and the maximum is 8.
\r
1105 <dt class="hdlist1">
\r
1106 <strong>compiler</strong> (<strong>CCACHE_CC</strong>)
\r
1110 This setting can be used to force the name of the compiler to use. If set
\r
1111 to the empty string (which is the default), ccache works it out from the
\r
1115 <dt class="hdlist1">
\r
1116 <strong>compiler_check</strong> (<strong>CCACHE_COMPILERCHECK</strong>)
\r
1120 By default, ccache includes the modification time (“mtime”) and size of
\r
1121 the compiler in the hash to ensure that results retrieved from the cache
\r
1122 are accurate. This setting can be used to select another strategy. Possible
\r
1125 <div class="openblock">
\r
1126 <div class="content">
\r
1127 <div class="dlist"><dl>
\r
1128 <dt class="hdlist1">
\r
1129 <strong>content</strong>
\r
1133 Hash the content of the compiler binary. This makes ccache very slightly
\r
1134 slower compared to the <strong>mtime</strong> setting, but makes it cope better with
\r
1135 compiler upgrades during a build bootstrapping process.
\r
1138 <dt class="hdlist1">
\r
1139 <strong>mtime</strong>
\r
1143 Hash the compiler’s mtime and size, which is fast. This is the default.
\r
1146 <dt class="hdlist1">
\r
1147 <strong>none</strong>
\r
1151 Don’t hash anything. This may be good for situations where you can safely
\r
1152 use the cached results even though the compiler’s mtime or size has changed
\r
1153 (e.g. if the compiler is built as part of your build system and the
\r
1154 compiler’s source has not changed, or if the compiler only has changes that
\r
1155 don’t affect code generation). You should only use the <strong>none</strong> setting if
\r
1156 you know what you are doing.
\r
1159 <dt class="hdlist1">
\r
1160 <strong>string:value</strong>
\r
1164 Use <strong>value</strong> as the string to calculate hash from. This can be the compiler
\r
1165 revision number you retrieved earlier and set here via environment variable.
\r
1168 <dt class="hdlist1">
\r
1169 <em>a command string</em>
\r
1173 Hash the standard output and standard error output of the specified
\r
1174 command. The string will be split on whitespace to find out the command and
\r
1175 arguments to run. No other interpretation of the command string will be
\r
1176 done, except that the special word <strong>%compiler%</strong> will be replaced with the
\r
1177 path to the compiler. Several commands can be specified with semicolon as
\r
1178 separator. Examples:
\r
1180 <div class="openblock">
\r
1181 <div class="content">
\r
1182 <div class="ulist"><ul>
\r
1185 <code>%compiler% -v</code>
\r
1190 <code>%compiler% -dumpmachine; %compiler% -dumpversion</code>
\r
1194 <div class="paragraph"><p>You should make sure that the specified command is as fast as possible since it
\r
1195 will be run once for each ccache invocation.</p></div>
\r
1196 <div class="paragraph"><p>Identifying the compiler using a command is useful if you want to avoid cache
\r
1197 misses when the compiler has been rebuilt but not changed.</p></div>
\r
1198 <div class="paragraph"><p>Another case is when the compiler (as seen by ccache) actually isn’t the real
\r
1199 compiler but another compiler wrapper — in that case, the default <strong>mtime</strong>
\r
1200 method will hash the mtime and size of the other compiler wrapper, which means
\r
1201 that ccache won’t be able to detect a compiler upgrade. Using a suitable
\r
1202 command to identify the compiler is thus safer, but it’s also slower, so you
\r
1203 should consider continue using the <strong>mtime</strong> method in combination with
\r
1204 the <strong>prefix_command</strong> setting if possible. See
\r
1205 <a href="#_using_ccache_with_other_compiler_wrappers">USING CCACHE WITH OTHER COMPILER WRAPPERS</a>.</p></div>
\r
1211 <dt class="hdlist1">
\r
1212 <strong>compression</strong> (<strong>CCACHE_COMPRESS</strong> or <strong>CCACHE_NOCOMPRESS</strong>, see <a href="#_boolean_values">Boolean values</a> above)
\r
1216 If true, ccache will compress object files and other compiler output it
\r
1217 puts in the cache. However, this setting has no effect on how files are
\r
1218 retrieved from the cache; compressed and uncompressed results will still be
\r
1219 usable regardless of this setting. The default is false.
\r
1222 <dt class="hdlist1">
\r
1223 <strong>compression_level</strong> (<strong>CCACHE_COMPRESSLEVEL</strong>)
\r
1227 This setting determines the level at which ccache will compress object
\r
1228 files. It only has effect if <strong>compression</strong> is enabled. The value defaults
\r
1229 to 6, and must be no lower than 1 (fastest, worst compression) and no
\r
1230 higher than 9 (slowest, best compression).
\r
1233 <dt class="hdlist1">
\r
1234 <strong>cpp_extension</strong> (<strong>CCACHE_EXTENSION</strong>)
\r
1238 This setting can be used to force a certain extension for the intermediate
\r
1239 preprocessed file. The default is to automatically determine the extension
\r
1240 to use for intermediate preprocessor files based on the type of file being
\r
1241 compiled, but that sometimes doesn’t work. For example, when using the
\r
1242 “aCC” compiler on HP-UX, set the cpp extension to <strong>i</strong>.
\r
1245 <dt class="hdlist1">
\r
1246 <strong>direct_mode</strong> (<strong>CCACHE_DIRECT</strong> or <strong>CCACHE_NODIRECT</strong>, see <a href="#_boolean_values">Boolean values</a> above)
\r
1250 If true, the direct mode will be used. The default is true. See
\r
1251 <a href="#_the_direct_mode">THE DIRECT MODE</a>.
\r
1254 <dt class="hdlist1">
\r
1255 <strong>disable</strong> (<strong>CCACHE_DISABLE</strong> or <strong>CCACHE_NODISABLE</strong>, see <a href="#_boolean_values">Boolean values</a> above)
\r
1259 When true, ccache will just call the real compiler, bypassing the cache
\r
1260 completely. The default is false.
\r
1263 <dt class="hdlist1">
\r
1264 <strong>extra_files_to_hash</strong> (<strong>CCACHE_EXTRAFILES</strong>)
\r
1268 This setting is a list of paths to files that ccache will include in the
\r
1269 the hash sum that idetifies the build. The list separator is semicolon on
\r
1270 Windows systems and colon on other systems.
\r
1273 <dt class="hdlist1">
\r
1274 <strong>hard_link</strong> (<strong>CCACHE_HARDLINK</strong> or <strong>CCACHE_NOHARDLINK</strong>, see <a href="#_boolean_values">Boolean values</a> above)
\r
1278 If true, ccache will attempt to use hard links from the cache directory
\r
1279 when creating the compiler output rather than using a file copy. Using hard
\r
1280 links may be slightly faster in some situations, but can confuse programs
\r
1281 like “make” that rely on modification times. Another thing to keep in
\r
1282 mind is that if the resulting object file is modified in any way, this
\r
1283 corrupts the cached object file as well. Hard links are never made for
\r
1284 compressed cache files. This means that you should not enable compression
\r
1285 if you want to use hard links. The default is false.
\r
1288 <dt class="hdlist1">
\r
1289 <strong>hash_dir</strong> (<strong>CCACHE_HASHDIR</strong> or <strong>CCACHE_NOHASHDIR</strong>, see <a href="#_boolean_values">Boolean values</a> above)
\r
1293 If true, ccache will include the current working directory in the hash that
\r
1294 is used to distinguish two compilations. This prevents a problem with the
\r
1295 storage of the current working directory in the debug info of an object
\r
1296 file, which can lead ccache to give a cached object file that has the
\r
1297 working directory in the debug info set incorrectly. This option is off by
\r
1298 default as the incorrect setting of this debug info rarely causes problems.
\r
1299 If you strike problems with GDB not using the correct directory then enable
\r
1303 <dt class="hdlist1">
\r
1304 <strong>log_file</strong> (<strong>CCACHE_LOGFILE</strong>)
\r
1308 If set to a file path, ccache will write information on what it is doing to
\r
1309 the specified file. This is useful for tracking down problems.
\r
1312 <dt class="hdlist1">
\r
1313 <strong>max_files</strong> (<strong>CCACHE_MAXFILES</strong>)
\r
1317 This option specifies the maximum number of files to keep in the cache. Use
\r
1318 0 for no limit (which is the default).
\r
1321 <dt class="hdlist1">
\r
1322 <strong>max_size</strong> (<strong>CCACHE_MAXSIZE</strong>)
\r
1326 This option specifies the maximum size of the cache. Use 0 for no limit.
\r
1327 The default value is 5G. Available suffixes: k, M, G, T (decimal) and Ki,
\r
1328 Mi, Gi, Ti (binary). The default suffix is "G".
\r
1331 <dt class="hdlist1">
\r
1332 <strong>path</strong> (<strong>CCACHE_PATH</strong>)
\r
1336 If set, ccache will search directories in this list when looking for the
\r
1337 real compiler. The list separator is semicolon on Windows systems and colon
\r
1338 on other systems. If not set, ccache will look for the first executable
\r
1339 matching the compiler name in the normal <strong>PATH</strong> that isn’t a symbolic link
\r
1343 <dt class="hdlist1">
\r
1344 <strong>prefix_command</strong> (<strong>CCACHE_PREFIX</strong>)
\r
1348 This option adds a list of prefixes (separated by space) to the command
\r
1349 line that ccache uses when invoking the compiler. See also
\r
1350 <a href="#_using_ccache_with_other_compiler_wrappers">USING CCACHE WITH OTHER COMPILER WRAPPERS</a>.
\r
1353 <dt class="hdlist1">
\r
1354 <strong>read_only</strong> (<strong>CCACHE_READONLY</strong> or <strong>CCACHE_NOREADONLY</strong>, see <a href="#_boolean_values">Boolean values</a> above)
\r
1358 If true, ccache will attempt to use existing cached object files, but it
\r
1359 will not to try to add anything new to the cache. If you are using this
\r
1360 because your ccache directory is read-only, then you need to set
\r
1361 <strong>temporary_dir</strong> as otherwise ccache will fail to create temporary files.
\r
1364 <dt class="hdlist1">
\r
1365 <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
1369 Just like <strong>read_only</strong> except that ccache will only try to retrieve results
\r
1370 from the cache using the direct mode, not the preprocessor mode. See
\r
1371 documentation for <strong>read_only</strong> regarding using a read-only ccache directory.
\r
1374 <dt class="hdlist1">
\r
1375 <strong>recache</strong> (<strong>CCACHE_RECACHE</strong> or <strong>CCACHE_NORECACHE</strong>, see <a href="#_boolean_values">Boolean values</a> above)
\r
1379 If true, ccache will not use any previously stored result. New results will
\r
1380 still be cached, possibly overwriting any pre-existing results.
\r
1383 <dt class="hdlist1">
\r
1384 <strong>run_second_cpp</strong> (<strong>CCACHE_CPP2</strong> or <strong>CCACHE_NOCPP2</strong>, see <a href="#_boolean_values">Boolean values</a> above)
\r
1388 If true, ccache will not use the optimisation of avoiding the second call
\r
1389 to the preprocessor by compiling the preprocessed output that was used for
\r
1390 finding the hash in the case of a cache miss. This is primarily a debugging
\r
1391 option, although it is possible that some unusual compilers will have
\r
1392 problems with compiling the preprocessed output, in which case this option
\r
1393 could allow ccache to be used anyway.
\r
1396 <dt class="hdlist1">
\r
1397 <strong>sloppiness</strong> (<strong>CCACHE_SLOPPINESS</strong>)
\r
1401 By default, ccache tries to give as few false cache hits as possible.
\r
1402 However, in certain situations it’s possible that you know things that
\r
1403 ccache can’t take for granted. This setting makes it possible to tell
\r
1404 ccache to relax some checks in order to increase the hit rate. The value
\r
1405 should be a comma-separated string with options. Available options are:
\r
1407 <div class="openblock">
\r
1408 <div class="content">
\r
1409 <div class="dlist"><dl>
\r
1410 <dt class="hdlist1">
\r
1411 <strong>file_macro</strong>
\r
1415 Ignore <strong>__FILE__</strong> being present in the source.
\r
1418 <dt class="hdlist1">
\r
1419 <strong>file_stat_matches</strong>
\r
1423 ccache normally examines a file’s contents to determine whether it matches
\r
1424 the cached version. With this option set, ccache will consider a file as
\r
1425 matching its cached version if the sizes, mtimes and ctimes match.
\r
1428 <dt class="hdlist1">
\r
1429 <strong>include_file_ctime</strong>
\r
1433 By default, ccache also will not cache a file if it includes a header whose
\r
1434 ctime is too new. This option disables that check.
\r
1437 <dt class="hdlist1">
\r
1438 <strong>include_file_mtime</strong>
\r
1442 By default, ccache will not cache a file if it includes a header whose
\r
1443 mtime is too new. This option disables that check.
\r
1446 <dt class="hdlist1">
\r
1447 <strong>pch_defines</strong>
\r
1451 Be sloppy about #defines when precompiling a header file. See
\r
1452 <a href="#_precompiled_headers">PRECOMPILED HEADERS</a> for more information.
\r
1455 <dt class="hdlist1">
\r
1456 <strong>time_macros</strong>
\r
1460 Ignore <strong>__DATE__</strong> and <strong>__TIME__</strong> being present in the source code.
\r
1465 <div class="paragraph"><p>See the discussion under <a href="#_troubleshooting">TROUBLESHOOTING</a> for more
\r
1466 information.</p></div>
\r
1468 <dt class="hdlist1">
\r
1469 <strong>stats</strong> (<strong>CCACHE_STATS</strong> or <strong>CCACHE_NOSTATS</strong>, see <a href="#_boolean_values">Boolean values</a> above)
\r
1473 If true, ccache will update the statistics counters on each compilation.
\r
1474 The default is true.
\r
1477 <dt class="hdlist1">
\r
1478 <strong>temporary_dir</strong> (<strong>CCACHE_TEMPDIR</strong>)
\r
1482 This setting specifies where ccache will put temporary files. The default
\r
1483 is <strong><cache_dir>/tmp</strong>.
\r
1485 <div class="admonitionblock">
\r
1488 <div class="title">Note</div>
\r
1490 <td class="content">In previous versions of ccache, <strong>CCACHE_TEMPDIR</strong> had to be on the same
\r
1491 filesystem as the <strong>CCACHE_DIR</strong> path, but this requirement has been
\r
1496 <dt class="hdlist1">
\r
1497 <strong>umask</strong> (<strong>CCACHE_UMASK</strong>)
\r
1501 This setting specifies the umask for ccache and all child processes (such
\r
1502 as the compiler). This is mostly useful when you wish to share your cache
\r
1503 with other users. Note that this also affects the file permissions set on
\r
1504 the object files created from your compilations.
\r
1507 <dt class="hdlist1">
\r
1508 <strong>unify</strong> (<strong>CCACHE_UNIFY</strong> or <strong>CCACHE_NOUNIFY</strong>, see <a href="#_boolean_values">Boolean values</a> above)
\r
1512 If true, ccache will use a C/C++ unifier when hashing the preprocessor
\r
1513 output if the <strong>-g</strong> option is not used. The unifier is slower than a normal
\r
1514 hash, so setting this environment variable loses a little bit of speed, but
\r
1515 it means that ccache can take advantage of not recompiling when the changes
\r
1516 to the source code consist of reformatting only. Note that enabling the
\r
1517 unifier changes the hash, so cached compilations produced when the unifier
\r
1518 is enabled cannot be reused when the unifier is disabled, and vice versa.
\r
1519 Enabling the unifier may result in incorrect line number information in
\r
1520 compiler warning messages and expansions of the <strong>__LINE__</strong> macro. Also
\r
1521 note that enabling the unifier implies turning off the direct mode.
\r
1528 <div class="sect1">
\r
1529 <h2 id="_cache_size_management">Cache size management</h2>
\r
1530 <div class="sectionbody">
\r
1531 <div class="paragraph"><p>By default, ccache has a five gigabyte limit on the total size of files in the
\r
1532 cache and no maximum number of files. You can set different limits using the
\r
1533 <strong>-M</strong>/<strong>--max-size</strong> and <strong>-F</strong>/<strong>--max-files</strong> options. Use <strong>ccache -s/--show-stats</strong>
\r
1534 to see the cache size and the currently configured limits (in addition to other
\r
1535 various statistics).</p></div>
\r
1538 <div class="sect1">
\r
1539 <h2 id="_cache_compression">Cache compression</h2>
\r
1540 <div class="sectionbody">
\r
1541 <div class="paragraph"><p>ccache can optionally compress all files it puts into the cache using the
\r
1542 compression library zlib. While this may involve a tiny performance slowdown,
\r
1543 it increases the number of files that fit in the cache. You can turn on
\r
1544 compression with the <strong>compression</strong> configuration setting and you can also tweak
\r
1545 the compression level with <strong>compression_level</strong>.</p></div>
\r
1548 <div class="sect1">
\r
1549 <h2 id="_how_ccache_works">How ccache works</h2>
\r
1550 <div class="sectionbody">
\r
1551 <div class="paragraph"><p>The basic idea is to detect when you are compiling exactly the same code a
\r
1552 second time and reuse the previously produced output. The detection is done by
\r
1553 hashing different kinds of information that should be unique for the
\r
1554 compilation and then using the hash sum to identify the cached output. ccache
\r
1555 uses MD4, a very fast cryptographic hash algorithm, for the hashing. (MD4 is
\r
1556 nowadays too weak to be useful in cryptographic contexts, but it should be safe
\r
1557 enough to be used to identify recompilations.) On a cache hit, ccache is able
\r
1558 to supply all of the correct compiler outputs (including all warnings,
\r
1559 dependency file, etc) from the cache.</p></div>
\r
1560 <div class="paragraph"><p>ccache has two ways of doing the detection:</p></div>
\r
1561 <div class="ulist"><ul>
\r
1564 the <strong>direct mode</strong>, where ccache hashes the source code and include files
\r
1570 the <strong>preprocessor mode</strong>, where ccache runs the preprocessor on the source
\r
1571 code and hashes the result
\r
1575 <div class="paragraph"><p>The direct mode is generally faster since running the preprocessor has some
\r
1576 overhead.</p></div>
\r
1577 <div class="sect2">
\r
1578 <h3 id="_common_hashed_information">Common hashed information</h3>
\r
1579 <div class="paragraph"><p>For both modes, the following information is included in the hash:</p></div>
\r
1580 <div class="ulist"><ul>
\r
1583 the extension used by the compiler for a file with preprocessor output
\r
1584 (normally <strong>.i</strong> for C code and <strong>.ii</strong> for C++ code)
\r
1589 the compiler’s size and modification time (or other compiler-specific
\r
1590 information specified by the <strong>compiler_check</strong> setting)
\r
1595 the name of the compiler
\r
1600 the current directory (if the <strong>hash_dir</strong> setting is enabled)
\r
1605 contents of files specified by the <strong>extra_files_to_hash</strong> setting (if any)
\r
1610 <div class="sect2">
\r
1611 <h3 id="_the_direct_mode">The direct mode</h3>
\r
1612 <div class="paragraph"><p>In the direct mode, the hash is formed of the common information and:</p></div>
\r
1613 <div class="ulist"><ul>
\r
1616 the input source file
\r
1621 the command line options
\r
1625 <div class="paragraph"><p>Based on the hash, a data structure called “manifest” is looked up in the
\r
1626 cache. The manifest contains:</p></div>
\r
1627 <div class="ulist"><ul>
\r
1630 references to cached compilation results (object file, dependency file, etc)
\r
1631 that were produced by previous compilations that matched the hash
\r
1636 paths to the include files that were read at the time the compilation results
\r
1637 were stored in the cache
\r
1642 hash sums of the include files at the time the compilation results were
\r
1643 stored in the cache
\r
1647 <div class="paragraph"><p>The current contents of the include files are then hashed and compared to the
\r
1648 information in the manifest. If there is a match, ccache knows the result of
\r
1649 the compilation. If there is no match, ccache falls back to running the
\r
1650 preprocessor. The output from the preprocessor is parsed to find the include
\r
1651 files that were read. The paths and hash sums of those include files are then
\r
1652 stored in the manifest along with information about the produced compilation
\r
1654 <div class="paragraph"><p>There is a catch with the direct mode: header files that were used by the
\r
1655 compiler are recorded, but header files that were <strong>not</strong> used, but would have
\r
1656 been used if they existed, are not. So, when ccache checks if a result can be
\r
1657 taken from the cache, it currently can’t check if the existence of a new header
\r
1658 file should invalidate the result. In practice, the direct mode is safe to use
\r
1659 in the absolute majority of cases.</p></div>
\r
1660 <div class="paragraph"><p>The direct mode will be disabled if any of the following holds:</p></div>
\r
1661 <div class="ulist"><ul>
\r
1664 the configuration setting <strong>direct_mode</strong> is false
\r
1669 a modification time of one of the include files is too new (needed to avoid a
\r
1675 the unifier is enabled (the configuration setting <strong>unify</strong> is true)
\r
1680 a compiler option not supported by the direct mode is used:
\r
1682 <div class="ulist"><ul>
\r
1685 a <strong>-Wp,<em>X</em></strong> compiler option other than <strong>-Wp,-MD,<em>path</em></strong> and
\r
1686 <strong>-Wp,-MMD,<em>path</em></strong>
\r
1691 <strong>-Xpreprocessor</strong>
\r
1698 the string “__TIME__” is present in the source code
\r
1703 <div class="sect2">
\r
1704 <h3 id="_the_preprocessor_mode">The preprocessor mode</h3>
\r
1705 <div class="paragraph"><p>In the preprocessor mode, the hash is formed of the common information and:</p></div>
\r
1706 <div class="ulist"><ul>
\r
1709 the preprocessor output from running the compiler with <strong>-E</strong>
\r
1714 the command line options except options that affect include files (<strong>-I</strong>,
\r
1715 <strong>-include</strong>, <strong>-D</strong>, etc; the theory is that these options will change the
\r
1716 preprocessor output if they have any effect at all)
\r
1721 any standard error output generated by the preprocessor
\r
1725 <div class="paragraph"><p>Based on the hash, the cached compilation result can be looked up directly in
\r
1726 the cache.</p></div>
\r
1730 <div class="sect1">
\r
1731 <h2 id="_compiling_in_different_directories">Compiling in different directories</h2>
\r
1732 <div class="sectionbody">
\r
1733 <div class="paragraph"><p>Some information included in the hash that identifies a unique compilation may
\r
1734 contain absolute paths:</p></div>
\r
1735 <div class="ulist"><ul>
\r
1738 The preprocessed source code may contain absolute paths to include files if
\r
1739 the compiler option <strong>-g</strong> is used or if absolute paths are given to <strong>-I</strong> and
\r
1740 similar compiler options.
\r
1745 Paths specified by compiler options (such as <strong>-I</strong>, <strong>-MF</strong>, etc) may be
\r
1751 The source code file path may be absolute, and that path may substituted for
\r
1752 <strong>__FILE__</strong> macros in the source code or included in warnings emitted to
\r
1753 standard error by the preprocessor.
\r
1757 <div class="paragraph"><p>This means that if you compile the same code in different locations, you can’t
\r
1758 share compilation results between the different build directories since you get
\r
1759 cache misses because of the absolute build directory paths that are part of the
\r
1760 hash. To mitigate this problem, you can specify a “base directory” in the
\r
1761 configuration setting <strong>base_dir</strong> to an absolute path to the directory. ccache
\r
1762 will then rewrite absolute paths that are under the base directory (i.e., paths
\r
1763 that have the base directory as a prefix) to relative paths when constructing
\r
1764 the hash. A typical path to use as the base directory is your home directory or
\r
1765 another directory that is a parent of your build directories. (Don’t use <code>/</code> as
\r
1766 the base directory since that will make ccache also rewrite paths to system
\r
1767 header files, which doesn’t gain anything.)</p></div>
\r
1768 <div class="paragraph"><p>The drawbacks of using a base directory are:</p></div>
\r
1769 <div class="ulist"><ul>
\r
1772 If you specify an absolute path to the source code file, <strong>__FILE__</strong> macros
\r
1773 will be expanded to a relative path instead.
\r
1778 If you specify an absolute path to the source code file and compile with
\r
1779 <strong>-g</strong>, the source code path stored in the object file may point to the wrong
\r
1780 directory, which may prevent debuggers like GDB from finding the source code.
\r
1781 Sometimes, a work-around is to change the directory explicitly with the
\r
1782 “cd” command in GDB.
\r
1788 <div class="sect1">
\r
1789 <h2 id="_precompiled_headers">Precompiled headers</h2>
\r
1790 <div class="sectionbody">
\r
1791 <div class="paragraph"><p>ccache has support for GCC’s precompiled headers. However, you have to do some
\r
1792 things to make it work properly:</p></div>
\r
1793 <div class="ulist"><ul>
\r
1796 You must set <strong>sloppiness</strong> to <strong>pch_defines,time_macros</strong>. The reason is that
\r
1797 ccache can’t tell whether <strong>__TIME__</strong> or <strong>__DATE__</strong> is used when using a
\r
1798 precompiled header. Further, it can’t detect changes in #defines in the
\r
1799 source code because of how preprocessing works in combination with
\r
1800 precompiled headers.
\r
1807 <div class="openblock">
\r
1808 <div class="content">
\r
1809 <div class="ulist"><ul>
\r
1812 use the <strong>-include</strong> compiler option to include the precompiled header
\r
1813 (i.e., don’t use <strong>#include</strong> in the source code to include the header); or
\r
1818 (for the Clang compiler) use the <strong>-include-pch</strong> compiler option to include
\r
1819 the PCH file generated from the precompiled header; or
\r
1824 add the <strong>-fpch-preprocess</strong> compiler option when compiling.
\r
1828 <div class="paragraph"><p>If you don’t do this, either the non-precompiled version of the header file
\r
1829 will be used (if available) or ccache will fall back to running the real
\r
1830 compiler and increase the statistics counter “preprocessor error” (if the
\r
1831 non-precompiled header file is not available).</p></div>
\r
1837 <div class="sect1">
\r
1838 <h2 id="_sharing_a_cache">Sharing a cache</h2>
\r
1839 <div class="sectionbody">
\r
1840 <div class="paragraph"><p>A group of developers can increase the cache hit rate by sharing a cache
\r
1841 directory. To share a cache without unpleasant side effects, the following
\r
1842 conditions should to be met:</p></div>
\r
1843 <div class="ulist"><ul>
\r
1846 Use the same cache directory.
\r
1851 Make sure that the configuration setting <strong>hard_link</strong> is false (which is the
\r
1857 Make sure that all users are in the same group.
\r
1862 Set the configuration setting <strong>umask</strong> to 002. This ensures that cached files
\r
1863 are accessible to everyone in the group.
\r
1868 Make sure that all users have write permission in the entire cache directory
\r
1869 (and that you trust all users of the shared cache).
\r
1874 Make sure that the setgid bit is set on all directories in the cache. This
\r
1875 tells the filesystem to inherit group ownership for new directories. The
\r
1876 command “find $CCACHE_DIR -type d | xargs chmod g+s” might be useful for
\r
1881 <div class="paragraph"><p>The reason to avoid the hard link mode is that the hard links cause unwanted
\r
1882 side effects, as all links to a cached file share the file’s modification
\r
1883 timestamp. This results in false dependencies to be triggered by
\r
1884 timestamp-based build systems whenever another user links to an existing file.
\r
1885 Typically, users will see that their libraries and binaries are relinked
\r
1886 without reason.</p></div>
\r
1887 <div class="paragraph"><p>You may also want to make sure that a base directory is set appropriately, as
\r
1888 discussed in a previous section.</p></div>
\r
1891 <div class="sect1">
\r
1892 <h2 id="_sharing_a_cache_on_nfs">Sharing a cache on NFS</h2>
\r
1893 <div class="sectionbody">
\r
1894 <div class="paragraph"><p>It is possible to put the cache directory on an NFS filesystem (or similar
\r
1895 filesystems), but keep in mind that:</p></div>
\r
1896 <div class="ulist"><ul>
\r
1899 Having the cache on NFS may slow down compilation. Make sure to do some
\r
1900 benchmarking to see if it’s worth it.
\r
1905 ccache hasn’t been tested very thoroughly on NFS.
\r
1909 <div class="paragraph"><p>A tip is to set <strong>temporary_dir</strong> to a directory on the local host to avoid NFS
\r
1910 traffic for temporary files.</p></div>
\r
1913 <div class="sect1">
\r
1914 <h2 id="_using_ccache_with_other_compiler_wrappers">Using ccache with other compiler wrappers</h2>
\r
1915 <div class="sectionbody">
\r
1916 <div class="paragraph"><p>The recommended way of combining ccache with another compiler wrapper (such as
\r
1917 “distcc”) is by letting ccache execute the compiler wrapper. This is
\r
1918 accomplished by defining the configuration setting <strong>prefix_command</strong>, for
\r
1919 example by setting the environment variable <strong>CCACHE_PREFIX</strong> to the name of the
\r
1920 wrapper (e.g. <strong>distcc</strong>). ccache will then prefix the command line with the
\r
1921 specified command when running the compiler. To specify several prefix
\r
1922 commands, set <strong>prefix_command</strong> to a colon-separated list of commands.</p></div>
\r
1923 <div class="paragraph"><p>Unless you set <strong>compiler_check</strong> to a suitable command (see the description of
\r
1924 that configuration option), it is not recommended to use the form <strong>ccache
\r
1925 anotherwrapper compiler args</strong> as the compilation command. It’s also not
\r
1926 recommended to use the masquerading technique for the other compiler wrapper.
\r
1927 The reason is that by default, ccache will in both cases hash the mtime and
\r
1928 size of the other wrapper instead of the real compiler, which means that:</p></div>
\r
1929 <div class="ulist"><ul>
\r
1932 Compiler upgrades will not be detected properly.
\r
1937 The cached results will not be shared between compilations with and without
\r
1938 the other wrapper.
\r
1942 <div class="paragraph"><p>Another minor thing is that if <strong>prefix_command</strong> is used, ccache will not invoke
\r
1943 the other wrapper when running the preprocessor, which increase performance.</p></div>
\r
1946 <div class="sect1">
\r
1947 <h2 id="_bugs">Bugs</h2>
\r
1948 <div class="sectionbody">
\r
1949 <div class="ulist"><ul>
\r
1952 ccache doesn’t handle the GNU Assembler’s <strong>.incbin</strong> directive correctly. This
\r
1953 directive can be embedded in the source code inside an <strong><em>asm</em></strong> statement in
\r
1954 order to include a file verbatim in the object file. If the included file is
\r
1955 modified, ccache doesn’t pick up the change since the inclusion isn’t done by
\r
1956 the preprocessor. A workaround of this problem is to set
\r
1957 <strong>extra_files_to_hash</strong> to the path of the included file.
\r
1962 The direct mode fails to pick up new header files in some rare scenarios. See
\r
1963 <a href="#_the_direct_mode">THE DIRECT MODE</a> above.
\r
1969 <div class="sect1">
\r
1970 <h2 id="_troubleshooting">Troubleshooting</h2>
\r
1971 <div class="sectionbody">
\r
1972 <div class="sect2">
\r
1973 <h3 id="_general">General</h3>
\r
1974 <div class="paragraph"><p>A general tip for getting information about what ccache is doing is to enable
\r
1975 debug logging by setting <strong>log_file</strong>. The log contains executed commands,
\r
1976 important decisions that ccache makes, read and written files, etc. Another way
\r
1977 of keeping track of what is happening is to check the output of <strong>ccache -s</strong>.</p></div>
\r
1979 <div class="sect2">
\r
1980 <h3 id="_performance">Performance</h3>
\r
1981 <div class="paragraph"><p>ccache has been written to perform well out of the box, but sometimes you may
\r
1982 have to do some adjustments of how you use the compiler and ccache in order to
\r
1983 improve performance.</p></div>
\r
1984 <div class="paragraph"><p>Since ccache works best when I/O is fast, put the cache directory on a fast
\r
1985 storage device if possible. Having lots of free memory so that files in the
\r
1986 cache directory stay in the disk cache is also preferrable.</p></div>
\r
1987 <div class="paragraph"><p>A good way of monitoring how well ccache works is to run <strong>ccache -s</strong> before and
\r
1988 after your build and then compare the statistics counters. Here are some common
\r
1989 problems and what may be done to increase the hit rate:</p></div>
\r
1990 <div class="ulist"><ul>
\r
1993 If “cache hit (preprocessed)” has been incremented instead of “cache hit
\r
1994 (direct)”, ccache has fallen back to preprocessor mode, which is generally
\r
1995 slower. Some possible reasons are:
\r
1997 <div class="ulist"><ul>
\r
2000 The source code has been modified in such a way that the preprocessor output
\r
2006 Compiler arguments that are hashed in the direct mode but not in the
\r
2007 preprocessor mode have changed (<strong>-I</strong>, <strong>-include</strong>, <strong>-D</strong>, etc) and they didn’t
\r
2008 affect the preprocessor output.
\r
2013 The compiler option <strong>-Xpreprocessor</strong> or <strong>-Wp,<em>X</em></strong> (except <strong>-Wp,-MD,<em>path</em></strong>
\r
2014 and <strong>Wp,-MMD,<em>path</em></strong>) is used.
\r
2019 This was the first compilation with a new value of the base directory
\r
2025 A modification time of one of the include files is too new (created the same
\r
2026 second as the compilation is being done). This check is made to avoid a race
\r
2027 condition. To fix this, create the include file earlier in the build
\r
2028 process, if possible, or set <strong>sloppiness</strong> to <strong>include_file_mtime</strong> if you are
\r
2029 willing to take the risk. (The race condition consists of these events: the
\r
2030 preprocessor is run; an include file is modified by someone; the new include
\r
2031 file is hashed by ccache; the real compiler is run on the preprocessor’s
\r
2032 output, which contains data from the old header file; the wrong object file
\r
2033 is stored in the cache.)
\r
2038 The <strong>__TIME__</strong> preprocessor macro is (potentially) being used. ccache
\r
2039 turns off direct mode if “__TIME__” is present in the source code. This
\r
2040 is done as a safety measure since the string indicates that a <strong>__TIME__</strong>
\r
2041 macro <em>may</em> affect the output. (To be sure, ccache would have to run the
\r
2042 preprocessor, but the sole point of the direct mode is to avoid that.) If
\r
2043 you know that <strong>__TIME__</strong> isn’t used in practise, or don’t care if ccache
\r
2044 produces objects where <strong>__TIME__</strong> is expanded to something in the past,
\r
2045 you can set <strong>sloppiness</strong> to <strong>time_macros</strong>.
\r
2050 The <strong>__DATE__</strong> preprocessor macro is (potentially) being used and the
\r
2051 date has changed. This is similar to how <strong>__TIME__</strong> is handled. If
\r
2052 “__DATE__” is present in the source code, ccache hashes the current
\r
2053 date in order to be able to produce the correct object file if the
\r
2054 <strong>__DATE__</strong> macro affects the output. If you know that <strong>__DATE__</strong> isn’t
\r
2055 used in practise, or don’t care if ccache produces objects where
\r
2056 <strong>__DATE__</strong> is expanded to something in the past, you can set <strong>sloppiness</strong>
\r
2057 to <strong>time_macros</strong>.
\r
2062 The <strong>__FILE__</strong> preprocessor macro is (potentially) being used and the
\r
2063 file path has changed. If “__FILE__” is present in the source code,
\r
2064 ccache hashes the current input file path in order to be able to produce the
\r
2065 correct object file if the <strong>__FILE__</strong> macro affects the output. If you
\r
2066 know that <strong>__FILE__</strong> isn’t used in practise, or don’t care if ccache
\r
2067 produces objects where <strong>__FILE__</strong> is expanded to the wrong path, you can
\r
2068 set <strong>sloppiness</strong> to <strong>file_macro</strong>.
\r
2075 If “cache miss” has been incremented even though the same code has been
\r
2076 compiled and cached before, ccache has either detected that something has
\r
2077 changed anyway or a cleanup has been performed (either explicitly or
\r
2078 implicitly when a cache limit has been reached). Some perhaps unobvious
\r
2079 things that may result in a cache miss are usage of <strong>__TIME__</strong> or
\r
2080 <strong>__DATE__</strong> macros, or use of automatically generated code that contains a
\r
2081 timestamp, build counter or other volatile information.
\r
2086 If “multiple source files” has been incremented, it’s an indication that
\r
2087 the compiler has been invoked on several source code files at once. ccache
\r
2088 doesn’t support that. Compile the source code files separately if possible.
\r
2093 If “unsupported compiler option” has been incremented, enable debug logging
\r
2094 and check which option was rejected.
\r
2099 If “preprocessor error” has been incremented, one possible reason is that
\r
2100 precompiled headers are being used. See <a href="#_precompiled_headers">PRECOMPILED HEADERS</a> for how to remedy this.
\r
2105 If “can’t use precompiled header” has been incremented, see
\r
2106 <a href="#_precompiled_headers">PRECOMPILED HEADERS</a>.
\r
2111 <div class="sect2">
\r
2112 <h3 id="_errors_when_compiling_with_ccache">Errors when compiling with ccache</h3>
\r
2113 <div class="paragraph"><p>If compilation doesn’t work with ccache, but it works without it, one possible
\r
2114 reason is that the compiler can’t compile preprocessed output correctly. A
\r
2115 workaround that may work is to enable <strong>run_second_cpp</strong>*. This will make cache
\r
2116 misses slower, though, so it is better to find and fix the root cause.</p></div>
\r
2118 <div class="sect2">
\r
2119 <h3 id="_corrupt_object_files">Corrupt object files</h3>
\r
2120 <div class="paragraph"><p>It should be noted that ccache is susceptible to general storage problems. If a
\r
2121 bad object file sneaks into the cache for some reason, it will of course stay
\r
2122 bad. Some possible reasons for erroneous object files are bad hardware (disk
\r
2123 drive, disk controller, memory, etc), buggy drivers or file systems, a bad
\r
2124 <strong>prefix_command</strong> or compiler wrapper. If this happens, the easiest way of
\r
2125 fixing it is this:</p></div>
\r
2126 <div class="olist arabic"><ol class="arabic">
\r
2129 Build so that the bad object file ends up in the build tree.
\r
2134 Remove the bad object file from the build tree.
\r
2139 Rebuild with <strong>CCACHE_RECACHE</strong> set.
\r
2143 <div class="paragraph"><p>An alternative is to clear the whole cache with <strong>ccache -C</strong> if you don’t mind
\r
2144 losing other cached results.</p></div>
\r
2145 <div class="paragraph"><p>There are no reported issues about ccache producing broken object files
\r
2146 reproducibly. That doesn’t mean it can’t happen, so if you find a repeatable
\r
2147 case, please report it.</p></div>
\r
2151 <div class="sect1">
\r
2152 <h2 id="_more_information">More information</h2>
\r
2153 <div class="sectionbody">
\r
2154 <div class="paragraph"><p>Credits, mailing list information, bug reporting instructions, source code,
\r
2155 etc, can be found on ccache’s web site: <a href="http://ccache.samba.org">http://ccache.samba.org</a>.</p></div>
\r
2158 <div class="sect1">
\r
2159 <h2 id="_author">Author</h2>
\r
2160 <div class="sectionbody">
\r
2161 <div class="paragraph"><p>ccache was originally written by Andrew Tridgell and is currently developed and
\r
2162 maintained by Joel Rosdahl. See AUTHORS.txt or AUTHORS.html and
\r
2163 <a href="http://ccache.samba.org/credits.html">http://ccache.samba.org/credits.html</a> for a list of contributors.</p></div>
\r
2167 <div id="footnotes"><hr /></div>
\r
2169 <div id="footer-text">
\r
2170 Version 3.2.6<br />
\r
2172 2016-07-12 21:36:01 CEST
\r
projects / platform / upstream / ccache.git / blob