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.3" />
\r
7 <title>CCACHE(1)</title>
\r
8 <style type="text/css">
\r
9 /* Sans-serif font. */
\r
10 h1, h2, h3, h4, h5, h6,
\r
11 div.title, caption.title,
\r
12 thead, p.table.header,
\r
14 span#author, span#revnumber, span#revdate, span#revremark,
\r
16 font-family: Arial,Helvetica,sans-serif;
\r
21 font-family: Georgia,"Times New Roman",Times,serif;
\r
24 /* Monospace font. */
\r
30 margin: 1em 5% 1em 5%;
\r
35 text-decoration: underline;
\r
56 h1, h2, h3, h4, h5, h6 {
\r
59 margin-bottom: 0.5em;
\r
64 border-bottom: 2px solid silver;
\r
81 border: 1px solid silver;
\r
86 margin-bottom: 0.5em;
\r
92 ul > li { color: #aaa; }
\r
93 ul > li > * { color: black; }
\r
107 span#revnumber, span#revdate, span#revremark {
\r
112 border-top: 2px solid silver;
\r
113 padding-top: 0.5em;
\r
118 padding-bottom: 0.5em;
\r
120 div#footer-badges {
\r
122 padding-bottom: 0.5em;
\r
127 margin-bottom: 1.5em;
\r
129 div.tableblock, div.imageblock, div.exampleblock, div.verseblock,
\r
130 div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
\r
131 div.admonitionblock {
\r
133 margin-bottom: 1.5em;
\r
135 div.admonitionblock {
\r
137 margin-bottom: 2.0em;
\r
142 div.content { /* Block element content. */
\r
146 /* Block element titles. */
\r
147 div.title, caption.title {
\r
152 margin-bottom: 0.5em;
\r
158 td div.title:first-child {
\r
161 div.content div.title:first-child {
\r
164 div.content + div.title {
\r
168 div.sidebarblock > div.content {
\r
169 background: #ffffee;
\r
170 border: 1px solid #dddddd;
\r
171 border-left: 4px solid #f0f0f0;
\r
175 div.listingblock > div.content {
\r
176 border: 1px solid #dddddd;
\r
177 border-left: 5px solid #f0f0f0;
\r
178 background: #f8f8f8;
\r
182 div.quoteblock, div.verseblock {
\r
183 padding-left: 1.0em;
\r
184 margin-left: 1.0em;
\r
186 border-left: 5px solid #f0f0f0;
\r
190 div.quoteblock > div.attribution {
\r
191 padding-top: 0.5em;
\r
195 div.verseblock > pre.content {
\r
196 font-family: inherit;
\r
197 font-size: inherit;
\r
199 div.verseblock > div.attribution {
\r
200 padding-top: 0.75em;
\r
203 /* DEPRECATED: Pre version 8.2.7 verse style literal block. */
\r
204 div.verseblock + div.attribution {
\r
208 div.admonitionblock .icon {
\r
209 vertical-align: top;
\r
212 text-decoration: underline;
\r
214 padding-right: 0.5em;
\r
216 div.admonitionblock td.content {
\r
217 padding-left: 0.5em;
\r
218 border-left: 3px solid #dddddd;
\r
221 div.exampleblock > div.content {
\r
222 border-left: 3px solid #dddddd;
\r
223 padding-left: 0.5em;
\r
226 div.imageblock div.content { padding-left: 0; }
\r
227 span.image img { border-style: none; }
\r
228 a.image:visited { color: white; }
\r
232 margin-bottom: 0.8em;
\r
237 font-style: normal;
\r
240 dd > *:first-child {
\r
245 list-style-position: outside;
\r
248 list-style-type: decimal;
\r
251 list-style-type: lower-alpha;
\r
254 list-style-type: upper-alpha;
\r
257 list-style-type: lower-roman;
\r
260 list-style-type: upper-roman;
\r
263 div.compact ul, div.compact ol,
\r
264 div.compact p, div.compact p,
\r
265 div.compact div, div.compact div {
\r
267 margin-bottom: 0.1em;
\r
270 div.tableblock > table {
\r
271 border: 3px solid #527bbd;
\r
273 thead, p.table.header {
\r
286 /* Because the table frame attribute is overriden by CSS in most browsers. */
\r
287 div.tableblock > table[frame="void"] {
\r
288 border-style: none;
\r
290 div.tableblock > table[frame="hsides"] {
\r
291 border-left-style: none;
\r
292 border-right-style: none;
\r
294 div.tableblock > table[frame="vsides"] {
\r
295 border-top-style: none;
\r
296 border-bottom-style: none;
\r
302 margin-bottom: 0.8em;
\r
305 padding-bottom: 15px;
\r
307 dt.hdlist1.strong, td.hdlist1.strong {
\r
311 vertical-align: top;
\r
312 font-style: normal;
\r
313 padding-right: 0.8em;
\r
317 vertical-align: top;
\r
319 div.hdlist.compact tr {
\r
325 background: yellow;
\r
328 .footnote, .footnoteref {
\r
332 span.footnote, span.footnoteref {
\r
333 vertical-align: super;
\r
337 margin: 20px 0 20px 0;
\r
338 padding: 7px 0 0 0;
\r
341 #footnotes div.footnote {
\r
347 border-top: 1px solid silver;
\r
356 padding-right: 0.5em;
\r
357 padding-bottom: 0.3em;
\r
358 vertical-align: top;
\r
360 div.colist td img {
\r
365 div#footer-badges { display: none; }
\r
369 margin-bottom: 2.5em;
\r
377 margin-bottom: 0.1em;
\r
380 div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
\r
398 <script type="text/javascript">
\r
400 window.onload = function(){asciidoc.footnotes(); asciidoc.toc(2);}
\r
401 var asciidoc = { // Namespace.
\r
403 /////////////////////////////////////////////////////////////////////
\r
404 // Table Of Contents generator
\r
405 /////////////////////////////////////////////////////////////////////
\r
407 /* Author: Mihai Bazon, September 2002
\r
408 * http://students.infoiasi.ro/~mishoo
\r
410 * Table Of Content generator
\r
413 * Feel free to use this script under the terms of the GNU General Public
\r
414 * License, as long as you do not remove or alter this notice.
\r
417 /* modified by Troy D. Hanson, September 2006. License: GPL */
\r
418 /* modified by Stuart Rackham, 2006, 2009. License: GPL */
\r
420 // toclevels = 1..4.
\r
421 toc: function (toclevels) {
\r
423 function getText(el) {
\r
425 for (var i = el.firstChild; i != null; i = i.nextSibling) {
\r
426 if (i.nodeType == 3 /* Node.TEXT_NODE */) // IE doesn't speak constants.
\r
428 else if (i.firstChild != null)
\r
429 text += getText(i);
\r
434 function TocEntry(el, text, toclevel) {
\r
437 this.toclevel = toclevel;
\r
440 function tocEntries(el, toclevels) {
\r
441 var result = new Array;
\r
442 var re = new RegExp('[hH]([2-'+(toclevels+1)+'])');
\r
443 // Function that scans the DOM tree for header elements (the DOM2
\r
444 // nodeIterator API would be a better technique but not supported by all
\r
446 var iterate = function (el) {
\r
447 for (var i = el.firstChild; i != null; i = i.nextSibling) {
\r
448 if (i.nodeType == 1 /* Node.ELEMENT_NODE */) {
\r
449 var mo = re.exec(i.tagName);
\r
450 if (mo && (i.getAttribute("class") || i.getAttribute("className")) != "float") {
\r
451 result[result.length] = new TocEntry(i, getText(i), mo[1]-1);
\r
461 var toc = document.getElementById("toc");
\r
462 var entries = tocEntries(document.getElementById("content"), toclevels);
\r
463 for (var i = 0; i < entries.length; ++i) {
\r
464 var entry = entries[i];
\r
465 if (entry.element.id == "")
\r
466 entry.element.id = "_toc_" + i;
\r
467 var a = document.createElement("a");
\r
468 a.href = "#" + entry.element.id;
\r
469 a.appendChild(document.createTextNode(entry.text));
\r
470 var div = document.createElement("div");
\r
471 div.appendChild(a);
\r
472 div.className = "toclevel" + entry.toclevel;
\r
473 toc.appendChild(div);
\r
475 if (entries.length == 0)
\r
476 toc.parentNode.removeChild(toc);
\r
480 /////////////////////////////////////////////////////////////////////
\r
481 // Footnotes generator
\r
482 /////////////////////////////////////////////////////////////////////
\r
484 /* Based on footnote generation code from:
\r
485 * http://www.brandspankingnew.net/archive/2005/07/format_footnote.html
\r
488 footnotes: function () {
\r
489 var cont = document.getElementById("content");
\r
490 var noteholder = document.getElementById("footnotes");
\r
491 var spans = cont.getElementsByTagName("span");
\r
494 for (i=0; i<spans.length; i++) {
\r
495 if (spans[i].className == "footnote") {
\r
497 // Use [\s\S] in place of . so multi-line matches work.
\r
498 // Because JavaScript has no s (dotall) regex flag.
\r
499 note = spans[i].innerHTML.match(/\s*\[([\s\S]*)]\s*/)[1];
\r
500 noteholder.innerHTML +=
\r
501 "<div class='footnote' id='_footnote_" + n + "'>" +
\r
502 "<a href='#_footnoteref_" + n + "' title='Return to text'>" +
\r
503 n + "</a>. " + note + "</div>";
\r
504 spans[i].innerHTML =
\r
505 "[<a id='_footnoteref_" + n + "' href='#_footnote_" + n +
\r
506 "' title='View footnote' class='footnote'>" + n + "</a>]";
\r
507 var id =spans[i].getAttribute("id");
\r
508 if (id != null) refs["#"+id] = n;
\r
512 noteholder.parentNode.removeChild(noteholder);
\r
514 // Process footnoterefs.
\r
515 for (i=0; i<spans.length; i++) {
\r
516 if (spans[i].className == "footnoteref") {
\r
517 var href = spans[i].getElementsByTagName("a")[0].getAttribute("href");
\r
518 href = href.match(/#.*/)[0]; // Because IE return full URL.
\r
520 spans[i].innerHTML =
\r
521 "[<a href='#_footnote_" + n +
\r
522 "' title='View footnote' class='footnote'>" + n + "</a>]";
\r
532 <body class="article">
\r
535 <span id="revnumber">version 3.1.6</span>
\r
537 <div id="toctitle">Table of Contents</div>
538 <noscript><p><b>JavaScript must be enabled in your browser to display the table of contents.</b></p></noscript>
542 <div class="sect1">
\r
543 <h2 id="_name">Name</h2>
\r
544 <div class="sectionbody">
\r
545 <div class="paragraph"><p>ccache - a fast C/C++ compiler cache</p></div>
\r
548 <div class="sect1">
\r
549 <h2 id="_synopsis">Synopsis</h2>
\r
550 <div class="sectionbody">
\r
551 <div class="verseblock">
\r
552 <pre class="content"><strong>ccache</strong> [<em>options</em>]
\r
553 <strong>ccache</strong> <em>compiler</em> [<em>compiler options</em>]
\r
554 <em>compiler</em> [<em>compiler options</em>] (via symbolic link)</pre>
\r
555 <div class="attribution">
\r
559 <div class="sect1">
\r
560 <h2 id="_description">Description</h2>
\r
561 <div class="sectionbody">
\r
562 <div class="paragraph"><p>ccache is a compiler cache. It speeds up recompilation by caching the result of
\r
563 previous compilations and detecting when the same compilation is being done
\r
564 again. Supported languages are C, C++, Objective-C and Objective-C++.</p></div>
\r
565 <div class="paragraph"><p>ccache has been carefully written to always produce exactly the same compiler
\r
566 output that you would get without the cache. The only way you should be able to
\r
567 tell that you are using ccache is the speed. Currently known exceptions to this
\r
568 goal are listed under <a href="#_bugs">BUGS</a>. If you ever discover an undocumented case
\r
569 where ccache changes the output of your compiler, please let us know.</p></div>
\r
570 <div class="sect2">
\r
571 <h3 id="_features">Features</h3>
\r
572 <div class="ulist"><ul>
\r
575 Keeps statistics on hits/misses.
\r
580 Automatic cache size management.
\r
585 Can cache compilations that generate warnings.
\r
600 Optionally uses hard links where possible to avoid copies.
\r
605 Optionally compresses files in the cache to reduce disk space.
\r
610 <div class="sect2">
\r
611 <h3 id="_limitations">Limitations</h3>
\r
612 <div class="ulist"><ul>
\r
615 Only knows how to cache the compilation of a single
\r
616 C/C++/Objective-C/Objective-C++ file. Other types of compilations
\r
617 (multi-file compilation, linking, etc) will silently fall back to running the
\r
623 Only works with GCC and compilers that behave similar enough.
\r
628 Some compiler flags are not supported. If such a flag is detected, ccache
\r
629 will silently fall back to running the real compiler.
\r
636 <div class="sect1">
\r
637 <h2 id="_run_modes">Run modes</h2>
\r
638 <div class="sectionbody">
\r
639 <div class="paragraph"><p>There are two ways to use ccache. You can either prefix your compilation
\r
640 commands with <strong>ccache</strong> or you can let ccache masquerade as the compiler by
\r
641 creating a symbolic link (named as the compiler) to ccache. The first method is
\r
642 most convenient if you just want to try out ccache or wish to use it for some
\r
643 specific projects. The second method is most useful for when you wish to use
\r
644 ccache for all your compilations.</p></div>
\r
645 <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
646 <div class="paragraph"><p>To use the symlinks method, do something like this:</p></div>
\r
647 <div class="listingblock">
\r
648 <div class="content">
\r
649 <pre><tt>cp ccache /usr/local/bin/
\r
650 ln -s ccache /usr/local/bin/gcc
\r
651 ln -s ccache /usr/local/bin/g++
\r
652 ln -s ccache /usr/local/bin/cc
\r
653 ln -s ccache /usr/local/bin/c++</tt></pre>
\r
655 <div class="paragraph"><p>And so forth. This will work as long as the directory with symlinks comes
\r
656 before the path to the compiler (which is usually in <tt>/usr/bin</tt>). After
\r
657 installing you may wish to run “which gcc” to make sure that the correct link
\r
658 is being used.</p></div>
\r
659 <div class="admonitionblock">
\r
662 <div class="title">Warning</div>
\r
664 <td class="content">The technique of letting ccache masquerade as the compiler works well,
\r
665 but currently doesn’t interact well with other tools that do the same thing.
\r
666 See <a href="#_using_ccache_with_other_compiler_wrappers">USING CCACHE WITH OTHER COMPILER WRAPPERS</a>.</td>
\r
669 <div class="admonitionblock">
\r
672 <div class="title">Warning</div>
\r
674 <td class="content">Do not use a hard link, use a symbolic link. A hard link will cause
\r
675 “interesting” problems.</td>
\r
680 <div class="sect1">
\r
681 <h2 id="_options">Options</h2>
\r
682 <div class="sectionbody">
\r
683 <div class="paragraph"><p>These options only apply when you invoke ccache as “ccache”. When invoked as
\r
684 a compiler (via a symlink as described in the previous section), the normal
\r
685 compiler options apply and you should refer to the compiler’s documentation.</p></div>
\r
686 <div class="dlist"><dl>
\r
687 <dt class="hdlist1">
\r
688 <strong>-c, --cleanup</strong>
\r
692 Clean up the cache by removing old cached files until the specified file
\r
693 number and cache size limits are not exceeded. This also recalculates the
\r
694 cache file count and size totals. Normally, it’s not needed to initiate
\r
695 cleanup manually as ccache keeps the cache below the specified limits at
\r
696 runtime and keeps statistics up to date on each compilation. Forcing a
\r
697 cleanup is mostly useful if you manually modify the cache contents or
\r
698 believe that the cache size statistics may be inaccurate.
\r
701 <dt class="hdlist1">
\r
702 <strong>-C, --clear</strong>
\r
706 Clear the entire cache, removing all cached files.
\r
709 <dt class="hdlist1">
\r
710 <strong>-F, --max-files</strong>=<em>N</em>
\r
714 Set the maximum number of files allowed in the cache. The value is stored
\r
715 inside the cache directory and applies to all future compilations. Due to
\r
716 the way the value is stored the actual value used is always rounded down to
\r
717 the nearest multiple of 16.
\r
720 <dt class="hdlist1">
\r
721 <strong>-h, --help</strong>
\r
725 Print an options summary page.
\r
728 <dt class="hdlist1">
\r
729 <strong>-M, --max-size</strong>=<em>SIZE</em>
\r
733 Set the maximum size of the files stored in the cache. You can specify a
\r
734 value in gigabytes, megabytes or kilobytes by appending a G, M or K to the
\r
735 value. The default is gigabytes. The actual value stored is rounded down to
\r
736 the nearest multiple of 16 kilobytes.
\r
739 <dt class="hdlist1">
\r
740 <strong>-s, --show-stats</strong>
\r
744 Print the current statistics summary for the cache.
\r
747 <dt class="hdlist1">
\r
748 <strong>-V, --version</strong>
\r
752 Print version and copyright information.
\r
755 <dt class="hdlist1">
\r
756 <strong>-z, --zero-stats</strong>
\r
760 Zero the cache statistics (but not the configured limits).
\r
766 <div class="sect1">
\r
767 <h2 id="_extra_options">Extra options</h2>
\r
768 <div class="sectionbody">
\r
769 <div class="paragraph"><p>When run as a compiler, ccache usually just takes the same command line options
\r
770 as the compiler you are using. The only exception to this is the option
\r
771 <strong>--ccache-skip</strong>. That option can be used to tell ccache to avoid interpreting
\r
772 the next option in any way and to pass it along to the compiler as-is.</p></div>
\r
773 <div class="paragraph"><p>The reason this can be important is that ccache does need to parse the command
\r
774 line and determine what is an input filename and what is a compiler option, as
\r
775 it needs the input filename to determine the name of the resulting object file
\r
776 (among other things). The heuristic ccache uses when parsing the command line
\r
777 is that any argument that exists as a file is treated as an input file name. By
\r
778 using <strong>--ccache-skip</strong> you can force an option to not be treated as an input
\r
779 file name and instead be passed along to the compiler as a command line option.</p></div>
\r
780 <div class="paragraph"><p>Another case where <strong>--ccache-skip</strong> can be useful is if ccache interprets an
\r
781 option specially but shouldn’t, since the option has another meaning for your
\r
782 compiler than what ccache thinks.</p></div>
\r
785 <div class="sect1">
\r
786 <h2 id="_environment_variables">Environment variables</h2>
\r
787 <div class="sectionbody">
\r
788 <div class="paragraph"><p>ccache uses a number of environment variables to control operation. In most
\r
789 cases you won’t need any of these as the defaults will be fine.</p></div>
\r
790 <div class="dlist"><dl>
\r
791 <dt class="hdlist1">
\r
792 <strong>CCACHE_BASEDIR</strong>
\r
796 If you set the environment variable <strong>CCACHE_BASEDIR</strong> to an absolute path to
\r
797 a directory, ccache rewrites absolute paths into relative paths before
\r
798 computing the hash that identifies the compilation, but only for paths
\r
799 under the specified directory. See the discussion under
\r
800 <a href="#_compiling_in_different_directories">COMPILING IN DIFFERENT DIRECTORIES</a>.
\r
803 <dt class="hdlist1">
\r
804 <strong>CCACHE_CC</strong>
\r
808 You can optionally set <strong>CCACHE_CC</strong> to force the name of the compiler to
\r
809 use. If you don’t do this then ccache works it out from the command line.
\r
812 <dt class="hdlist1">
\r
813 <strong>CCACHE_COMPILERCHECK</strong>
\r
817 By default, ccache includes the modification time (“mtime”) and size of
\r
818 the compiler in the hash to ensure that results retrieved from the cache
\r
819 are accurate. The <strong>CCACHE_COMPILERCHECK</strong> environment variable can be used
\r
820 to select another strategy. Possible values are:
\r
822 <div class="openblock">
\r
823 <div class="content">
\r
824 <div class="dlist"><dl>
\r
825 <dt class="hdlist1">
\r
826 <strong>content</strong>
\r
830 Hash the content of the compiler binary. This makes ccache very slightly
\r
831 slower compared to the <strong>mtime</strong> setting, but makes it cope better with
\r
832 compiler upgrades during a build bootstrapping process.
\r
835 <dt class="hdlist1">
\r
836 <strong>mtime</strong>
\r
840 Hash the compiler’s mtime and size, which is fast. This is the default.
\r
843 <dt class="hdlist1">
\r
844 <strong>none</strong>
\r
848 Don’t hash anything. This may be good for situations where you can safely
\r
849 use the cached results even though the compiler’s mtime or size has changed
\r
850 (e.g. if the compiler is built as part of your build system and the
\r
851 compiler’s source has not changed, or if the compiler only has changes that
\r
852 don’t affect code generation). You should only use the <strong>none</strong> setting if
\r
853 you know what you are doing.
\r
856 <dt class="hdlist1">
\r
857 <em>a command string</em>
\r
861 Hash the standard output and standard error output of the specified
\r
862 command. The string will be split on whitespace to find out the command and
\r
863 arguments to run. No other interpretation of the command string will be
\r
864 done, except that the special word “%compiler%” will be replaced with the
\r
865 path to the compiler. Several commands can be specified with semicolon as
\r
866 separator. Examples:
\r
868 <div class="openblock">
\r
869 <div class="content">
\r
870 <div class="ulist"><ul>
\r
873 <tt>%compiler% -v</tt>
\r
878 <tt>%compiler% -dumpmachine; %compiler% -dumpversion</tt>
\r
882 <div class="paragraph"><p>You should make sure that the specified command is as fast as possible since it
\r
883 will be run once for each ccache invocation.</p></div>
\r
884 <div class="paragraph"><p>Identifying the compiler using a command is useful if you want to avoid cache
\r
885 misses when the compiler has been rebuilt but not changed.</p></div>
\r
886 <div class="paragraph"><p>Another case is when the compiler (as seen by ccache) actually isn’t the real
\r
887 compiler but another compiler wrapper — in that case, the default <strong>mtime</strong>
\r
888 method will hash the mtime and size of the other compiler wrapper, which means
\r
889 that ccache won’t be able to detect a compiler upgrade. Using a suitable
\r
890 command to identify the compiler is thus safer, but it’s also slower, so you
\r
891 should consider continue using the <strong>mtime</strong> method in combination with
\r
892 <strong>CCACHE_PREFIX</strong> if possible. See
\r
893 <a href="#_using_ccache_with_other_compiler_wrappers">USING CCACHE WITH OTHER COMPILER WRAPPERS</a>.</p></div>
\r
899 <dt class="hdlist1">
\r
900 <strong>CCACHE_COMPRESS</strong>
\r
904 If you set the environment variable <strong>CCACHE_COMPRESS</strong> then ccache will
\r
905 compress object files and other compiler output it puts in the cache.
\r
906 However, this setting has no effect on how files are retrieved from the
\r
907 cache; compressed and uncompressed results will still be usable regardless
\r
911 <dt class="hdlist1">
\r
912 <strong>CCACHE_CPP2</strong>
\r
916 If you set the environment variable <strong>CCACHE_CPP2</strong> then ccache will not use
\r
917 the optimisation of avoiding the second call to the preprocessor by
\r
918 compiling the preprocessed output that was used for finding the hash in the
\r
919 case of a cache miss. This is primarily a debugging option, although it is
\r
920 possible that some unusual compilers will have problems with the
\r
921 intermediate filename extensions used in this optimisation, in which case
\r
922 this option could allow ccache to be used anyway.
\r
925 <dt class="hdlist1">
\r
926 <strong>CCACHE_DETECT_SHEBANG</strong>
\r
930 The <strong>CCACHE_DETECT_SHEBANG</strong> environment variable only has meaning on
\r
931 Windows. It instructs ccache to open the executable file to detect the
\r
932 <strong>#!/bin/sh</strong> string, in which case ccache will search for <strong>sh.exe</strong> in
\r
933 <strong>PATH</strong> and use that to launch the executable.
\r
936 <dt class="hdlist1">
\r
937 <strong>CCACHE_DIR</strong>
\r
941 The <strong>CCACHE_DIR</strong> environment variable specifies where ccache will keep its
\r
942 cached compiler output. The default is <strong>$HOME/.ccache</strong>.
\r
945 <dt class="hdlist1">
\r
946 <strong>CCACHE_DISABLE</strong>
\r
950 If you set the environment variable <strong>CCACHE_DISABLE</strong> then ccache will just
\r
951 call the real compiler, bypassing the cache completely.
\r
954 <dt class="hdlist1">
\r
955 <strong>CCACHE_EXTENSION</strong>
\r
959 ccache tries to automatically determine the extension to use for
\r
960 intermediate preprocessor files based on the type of file being compiled.
\r
961 Unfortunately this sometimes doesn’t work, for example when using the
\r
962 “aCC” compiler on HP-UX. On systems like this you can use the
\r
963 <strong>CCACHE_EXTENSION</strong> option to override the default. On HP-UX set this
\r
964 environment variable to <strong>i</strong> if you use the “aCC” compiler.
\r
967 <dt class="hdlist1">
\r
968 <strong>CCACHE_EXTRAFILES</strong>
\r
972 If you set the environment variable <strong>CCACHE_EXTRAFILES</strong> to a list of paths
\r
973 then ccache will include the contents of those files when calculating the
\r
974 hash sum. The list separator is semicolon in Windows systems and colon on
\r
978 <dt class="hdlist1">
\r
979 <strong>CCACHE_HARDLINK</strong>
\r
983 If you set the environment variable <strong>CCACHE_HARDLINK</strong> then ccache will
\r
984 attempt to use hard links from the cache directory when creating the
\r
985 compiler output rather than using a file copy. Using hard links may be
\r
986 slightly faster in some situations, but can confuse programs like “make”
\r
987 that rely on modification times. Another thing to keep in mind is that if
\r
988 the resulting object file is modified in any way, this corrupts the cached
\r
989 object file as well. Hard links are never made for compressed cache files.
\r
990 This means that you should not set the <strong>CCACHE_COMPRESS</strong> variable if you
\r
991 want to use hard links.
\r
994 <dt class="hdlist1">
\r
995 <strong>CCACHE_HASHDIR</strong>
\r
999 This tells ccache to hash the current working directory when calculating
\r
1000 the hash that is used to distinguish two compilations. This prevents a
\r
1001 problem with the storage of the current working directory in the debug info
\r
1002 of a object file, which can lead ccache to give a cached object file that
\r
1003 has the working directory in the debug info set incorrectly. This option is
\r
1004 off by default as the incorrect setting of this debug info rarely causes
\r
1005 problems. If you strike problems with GDB not using the correct directory
\r
1006 then enable this option.
\r
1009 <dt class="hdlist1">
\r
1010 <strong>CCACHE_LOGFILE</strong>
\r
1014 If you set the <strong>CCACHE_LOGFILE</strong> environment variable then ccache will write
\r
1015 information on what it is doing to the specified file. This is useful for
\r
1016 tracking down problems.
\r
1019 <dt class="hdlist1">
\r
1020 <strong>CCACHE_NLEVELS</strong>
\r
1024 The environment variable <strong>CCACHE_NLEVELS</strong> allows you to choose the number
\r
1025 of levels of hash in the cache directory. The default is 2. The minimum is
\r
1026 1 and the maximum is 8.
\r
1029 <dt class="hdlist1">
\r
1030 <strong>CCACHE_NODIRECT</strong>
\r
1034 If you set the environment variable <strong>CCACHE_NODIRECT</strong> then ccache will not
\r
1035 use the direct mode.
\r
1038 <dt class="hdlist1">
\r
1039 <strong>CCACHE_NOSTATS</strong>
\r
1043 If you set the environment variable <strong>CCACHE_NOSTATS</strong> then ccache will not
\r
1044 update the statistics files on each compilation.
\r
1047 <dt class="hdlist1">
\r
1048 <strong>CCACHE_PATH</strong>
\r
1052 You can optionally set <strong>CCACHE_PATH</strong> to a colon-separated path where ccache
\r
1053 will look for the real compilers. If you don’t do this then ccache will
\r
1054 look for the first executable matching the compiler name in the normal
\r
1055 <strong>PATH</strong> that isn’t a symbolic link to ccache itself.
\r
1058 <dt class="hdlist1">
\r
1059 <strong>CCACHE_PREFIX</strong>
\r
1063 This option adds a prefix to the command line that ccache runs when
\r
1064 invoking the compiler. Also see the section below on using ccache with
\r
1065 “distcc”.
\r
1068 <dt class="hdlist1">
\r
1069 <strong>CCACHE_READONLY</strong>
\r
1073 The <strong>CCACHE_READONLY</strong> environment variable tells ccache to attempt to use
\r
1074 existing cached object files, but not to try to add anything new to the
\r
1075 cache. If you are using this because your <strong>CCACHE_DIR</strong> is read-only, then
\r
1076 you may find that you also need to set <strong>CCACHE_TEMPDIR</strong> as otherwise ccache
\r
1077 will fail to create temporary files.
\r
1080 <dt class="hdlist1">
\r
1081 <strong>CCACHE_RECACHE</strong>
\r
1085 This forces ccache to not use any cached results, even if it finds them.
\r
1086 New results are still cached, but existing cache entries are ignored.
\r
1089 <dt class="hdlist1">
\r
1090 <strong>CCACHE_SLOPPINESS</strong>
\r
1094 By default, ccache tries to give as few false cache hits as possible.
\r
1095 However, in certain situations it’s possible that you know things that
\r
1096 ccache can’t take for granted. The <strong>CCACHE_SLOPPINESS</strong> environment variable
\r
1097 makes it possible to tell ccache to relax some checks in order to increase
\r
1098 the hit rate. The value should be a comma-separated string with options.
\r
1099 Available options are:
\r
1101 <div class="openblock">
\r
1102 <div class="content">
\r
1103 <div class="dlist"><dl>
\r
1104 <dt class="hdlist1">
\r
1105 <strong>file_macro</strong>
\r
1109 Ignore <strong>__FILE__</strong> being present in the source.
\r
1112 <dt class="hdlist1">
\r
1113 <strong>include_file_mtime</strong>
\r
1117 Don’t check the modification time of include files in the direct mode.
\r
1120 <dt class="hdlist1">
\r
1121 <strong>time_macros</strong>
\r
1125 Ignore <strong>__DATE__</strong> and <strong>__TIME__</strong> being present in the source code.
\r
1130 <div class="paragraph"><p>See the discussion under <a href="#_troubleshooting">TROUBLESHOOTING</a> for more
\r
1131 information.</p></div>
\r
1133 <dt class="hdlist1">
\r
1134 <strong>CCACHE_TEMPDIR</strong>
\r
1138 The <strong>CCACHE_TEMPDIR</strong> environment variable specifies where ccache will put
\r
1139 temporary files. The default is <strong>$CCACHE_DIR/tmp</strong>.
\r
1141 <div class="admonitionblock">
\r
1144 <div class="title">Note</div>
\r
1146 <td class="content">In previous versions of ccache, <strong>CCACHE_TEMPDIR</strong> had to be on the same
\r
1147 filesystem as the <strong>CCACHE_DIR</strong> path, but this requirement has been
\r
1152 <dt class="hdlist1">
\r
1153 <strong>CCACHE_UMASK</strong>
\r
1157 This sets the umask for ccache and all child processes (such as the
\r
1158 compiler). This is mostly useful when you wish to share your cache with
\r
1159 other users. Note that this also affects the file permissions set on the
\r
1160 object files created from your compilations.
\r
1163 <dt class="hdlist1">
\r
1164 <strong>CCACHE_UNIFY</strong>
\r
1168 If you set the environment variable <strong>CCACHE_UNIFY</strong> then ccache will use a
\r
1169 C/C++ unifier when hashing the preprocessor output if the <strong>-g</strong> option is
\r
1170 not used. The unifier is slower than a normal hash, so setting this
\r
1171 environment variable loses a little bit of speed, but it means that ccache
\r
1172 can take advantage of not recompiling when the changes to the source code
\r
1173 consist of reformatting only. Note that using <strong>CCACHE_UNIFY</strong> changes the
\r
1174 hash, so cached compilations with <strong>CCACHE_UNIFY</strong> set cannot be used when
\r
1175 <strong>CCACHE_UNIFY</strong> is not set and vice versa. The reason the unifier is off by
\r
1176 default is that it can give incorrect line number information in compiler
\r
1177 warning messages. Also note that enabling the unifier implies turning off
\r
1184 <div class="sect1">
\r
1185 <h2 id="_cache_size_management">Cache size management</h2>
\r
1186 <div class="sectionbody">
\r
1187 <div class="paragraph"><p>By default ccache has a one gigabyte limit on the total size of files in the
\r
1188 cache and no maximum number of files. You can set different limits using the
\r
1189 <strong>-M</strong>/<strong>--max-size</strong> and <strong>-F</strong>/<strong>--max-files</strong> options. Use <strong>ccache -s/--show-stats</strong>
\r
1190 to see the cache size and the currently configured limits (in addition to other
\r
1191 various statistics).</p></div>
\r
1194 <div class="sect1">
\r
1195 <h2 id="_cache_compression">Cache compression</h2>
\r
1196 <div class="sectionbody">
\r
1197 <div class="paragraph"><p>ccache can optionally compress all files it puts into the cache using the
\r
1198 compression library zlib. While this involves a negligible performance
\r
1199 slowdown, it significantly increases the number of files that fit in the cache.
\r
1200 You can turn on compression by setting the <strong>CCACHE_COMPRESS</strong> environment
\r
1201 variable.</p></div>
\r
1204 <div class="sect1">
\r
1205 <h2 id="_how_ccache_works">How ccache works</h2>
\r
1206 <div class="sectionbody">
\r
1207 <div class="paragraph"><p>The basic idea is to detect when you are compiling exactly the same code a
\r
1208 second time and reuse the previously produced output. The detection is done by
\r
1209 hashing different kinds of information that should be unique for the
\r
1210 compilation and then using the hash sum to identify the cached output. ccache
\r
1211 uses MD4, a very fast cryptographic hash algorithm, for the hashing. (MD4 is
\r
1212 nowadays too weak to be useful in cryptographic contexts, but it should be safe
\r
1213 enough to be used to identify recompilations.) On a cache hit, ccache is able
\r
1214 to supply all of the correct compiler outputs (including all warnings,
\r
1215 dependency file, etc) from the cache.</p></div>
\r
1216 <div class="paragraph"><p>ccache has two ways of doing the detection:</p></div>
\r
1217 <div class="ulist"><ul>
\r
1220 the <strong>direct mode</strong>, where ccache hashes the source code and include files
\r
1226 the <strong>preprocessor mode</strong>, where ccache runs the preprocessor on the source
\r
1227 code and hashes the result
\r
1231 <div class="paragraph"><p>The direct mode is generally faster since running the preprocessor has some
\r
1232 overhead.</p></div>
\r
1233 <div class="sect2">
\r
1234 <h3 id="_common_hashed_information">Common hashed information</h3>
\r
1235 <div class="paragraph"><p>For both modes, the following information is included in the hash:</p></div>
\r
1236 <div class="ulist"><ul>
\r
1239 the extension used by the compiler for a file with preprocessor output
\r
1240 (normally <strong>.i</strong> for C code and <strong>.ii</strong> for C++ code)
\r
1245 the compiler’s size and modification time (or other compiler-specific
\r
1246 information specified by <strong>CCACHE_COMPILERCHECK</strong>)
\r
1251 the name of the compiler
\r
1256 the current directory (if <strong>CCACHE_HASHDIR</strong> is set)
\r
1261 contents of files specified by <strong>CCACHE_EXTRAFILES</strong> (if any)
\r
1266 <div class="sect2">
\r
1267 <h3 id="_the_direct_mode">The direct mode</h3>
\r
1268 <div class="paragraph"><p>In the direct mode, the hash is formed of the common information and:</p></div>
\r
1269 <div class="ulist"><ul>
\r
1272 the input source file
\r
1277 the command line options
\r
1281 <div class="paragraph"><p>Based on the hash, a data structure called “manifest” is looked up in the
\r
1282 cache. The manifest contains:</p></div>
\r
1283 <div class="ulist"><ul>
\r
1286 references to cached compilation results (object file, dependency file, etc)
\r
1287 that were produced by previous compilations that matched the hash
\r
1292 paths to the include files that were read at the time the compilation results
\r
1293 were stored in the cache
\r
1298 hash sums of the include files at the time the compilation results were
\r
1299 stored in the cache
\r
1303 <div class="paragraph"><p>The current contents of the include files are then hashed and compared to the
\r
1304 information in the manifest. If there is a match, ccache knows the result of
\r
1305 the compilation. If there is no match, ccache falls back to running the
\r
1306 preprocessor. The output from the preprocessor is parsed to find the include
\r
1307 files that were read. The paths and hash sums of those include files are then
\r
1308 stored in the manifest along with information about the produced compilation
\r
1310 <div class="paragraph"><p>The direct mode will be disabled if any of the following holds:</p></div>
\r
1311 <div class="ulist"><ul>
\r
1314 the environment variable <strong>CCACHE_NODIRECT</strong> is set
\r
1319 a modification time of one of the include files is too new (needed to avoid a
\r
1325 the unifier is enabled (the environment variable <strong>CCACHE_UNIFY</strong> is set)
\r
1330 a compiler option not supported by the direct mode is used:
\r
1332 <div class="ulist"><ul>
\r
1335 a <strong>-Wp,<em>X</em></strong> compiler option other than <strong>-Wp,-MD,<em>path</em></strong> and
\r
1336 <strong>-Wp,-MMD,<em>path</em></strong>
\r
1341 <strong>-Xpreprocessor</strong>
\r
1348 the string “__TIME__” is present outside comments and string literals in
\r
1354 <div class="sect2">
\r
1355 <h3 id="_the_preprocessor_mode">The preprocessor mode</h3>
\r
1356 <div class="paragraph"><p>In the preprocessor mode, the hash is formed of the common information and:</p></div>
\r
1357 <div class="ulist"><ul>
\r
1360 the preprocessor output from running the compiler with <strong>-E</strong>
\r
1365 the command line options except options that affect include files (<strong>-I</strong>,
\r
1366 <strong>-include</strong>, <strong>-D</strong>, etc; the theory is that these options will change the
\r
1367 preprocessor output if they have any effect at all)
\r
1372 any standard error output generated by the preprocessor
\r
1376 <div class="paragraph"><p>Based on the hash, the cached compilation result can be looked up directly in
\r
1377 the cache.</p></div>
\r
1381 <div class="sect1">
\r
1382 <h2 id="_compiling_in_different_directories">Compiling in different directories</h2>
\r
1383 <div class="sectionbody">
\r
1384 <div class="paragraph"><p>Some information included in the hash that identifies a unique compilation may
\r
1385 contain absolute paths:</p></div>
\r
1386 <div class="ulist"><ul>
\r
1389 The preprocessed source code may contain absolute paths to include files if
\r
1390 the compiler option <strong>-g</strong> is used or if absolute paths are given to <strong>-I</strong> and
\r
1391 similar compiler options.
\r
1396 Paths specified by compiler options (such as <strong>-I</strong>, <strong>-MF</strong>, etc) may be
\r
1402 The source code file path may be absolute, and that path may substituted for
\r
1403 <strong>__FILE__</strong> macros in the source code or included in warnings emitted to
\r
1404 standard error by the preprocessor.
\r
1408 <div class="paragraph"><p>This means that if you compile the same code in different locations, you can’t
\r
1409 share compilation results between the different build directories since you get
\r
1410 cache misses because of the absolute build directory paths that are part of the
\r
1411 hash. To mitigate this problem, you can specify a “base directory” by setting
\r
1412 the <strong>CCACHE_BASEDIR</strong> variable to an absolute path to the directory. ccache will
\r
1413 then rewrite absolute paths that are under the base directory (i.e., paths that
\r
1414 have the base directory as a prefix) to relative paths when constructing the
\r
1415 hash. A typical path to use as the base directory is your home directory or
\r
1416 another directory that is a parent of your build directories. (Don’t use <tt>/</tt> as
\r
1417 the base directory since that will make ccache also rewrite paths to system
\r
1418 header files, which doesn’t gain anything.)</p></div>
\r
1419 <div class="paragraph"><p>The drawbacks of using <strong>CCACHE_BASEDIR</strong> are:</p></div>
\r
1420 <div class="ulist"><ul>
\r
1423 If you specify an absolute path to the source code file, <strong>__FILE__</strong> macros
\r
1424 will be expanded to a relative path instead.
\r
1429 If you specify an absolute path to the source code file and compile with
\r
1430 <strong>-g</strong>, the source code path stored in the object file may point to the wrong
\r
1431 directory, which may prevent debuggers like GDB from finding the source code.
\r
1432 Sometimes, a work-around is to change the directory explicitly with the
\r
1433 “cd” command in GDB.
\r
1439 <div class="sect1">
\r
1440 <h2 id="_precompiled_headers">Precompiled headers</h2>
\r
1441 <div class="sectionbody">
\r
1442 <div class="paragraph"><p>ccache has support for GCC’s precompiled headers. However, you have to do some
\r
1443 things to make it work properly:</p></div>
\r
1444 <div class="ulist"><ul>
\r
1447 You must set <strong>CCACHE_SLOPPINESS</strong> to <strong>time_macros</strong>. The reason is that ccache
\r
1448 can’t tell whether <strong>__TIME__</strong> or <strong>__DATE__</strong> is used when using a
\r
1449 precompiled header.
\r
1456 <div class="openblock">
\r
1457 <div class="content">
\r
1458 <div class="ulist"><ul>
\r
1461 use the <strong>-include</strong> compiler option to include the precompiled header
\r
1462 (i.e., don’t use <strong>#include</strong> in the source code to include the header); or
\r
1467 add the <strong>-fpch-preprocess</strong> compiler option when compiling.
\r
1471 <div class="paragraph"><p>If you don’t do this, either the non-precompiled version of the header file
\r
1472 will be used (if available) or ccache will fall back to running the real
\r
1473 compiler and increase the statistics counter “preprocessor error” (if the
\r
1474 non-precompiled header file is not available).</p></div>
\r
1480 <div class="sect1">
\r
1481 <h2 id="_sharing_a_cache">Sharing a cache</h2>
\r
1482 <div class="sectionbody">
\r
1483 <div class="paragraph"><p>A group of developers can increase the cache hit rate by sharing a cache
\r
1484 directory. To share a cache without unpleasant side effects, the following
\r
1485 conditions should to be met:</p></div>
\r
1486 <div class="ulist"><ul>
\r
1489 Use the same <strong>CCACHE_DIR</strong> environment variable setting.
\r
1494 Unset the <strong>CCACHE_HARDLINK</strong> environment variable.
\r
1499 Make sure everyone sets the <strong>CCACHE_UMASK</strong> environment variable to 002. This
\r
1500 ensures that cached files are accessible to everyone in the group.
\r
1505 Make sure that all users have write permission in the entire cache directory
\r
1506 (and that you trust all users of the shared cache).
\r
1511 Make sure that the setgid bit is set on all directories in the cache. This
\r
1512 tells the filesystem to inherit group ownership for new directories. The
\r
1513 command “find $CCACHE_DIR -type d | xargs chmod g+s” might be useful for
\r
1518 <div class="paragraph"><p>The reason to avoid the hard link mode is that the hard links cause unwanted
\r
1519 side effects, as all links to a cached file share the file’s modification
\r
1520 timestamp. This results in false dependencies to be triggered by
\r
1521 timestamp-based build systems whenever another user links to an existing file.
\r
1522 Typically, users will see that their libraries and binaries are relinked
\r
1523 without reason.</p></div>
\r
1524 <div class="paragraph"><p>You may also want to make sure that the developers have <strong>CCACHE_BASEDIR</strong> set
\r
1525 appropriately, as discussed in the previous section.</p></div>
\r
1528 <div class="sect1">
\r
1529 <h2 id="_sharing_a_cache_on_nfs">Sharing a cache on NFS</h2>
\r
1530 <div class="sectionbody">
\r
1531 <div class="paragraph"><p>It is possible to put the cache directory on an NFS filesystem (or similar
\r
1532 filesystems), but keep in mind that:</p></div>
\r
1533 <div class="ulist"><ul>
\r
1536 Having the cache on NFS may slow down compilation. Make sure to do some
\r
1537 benchmarking to see if it’s worth it.
\r
1542 ccache hasn’t been tested very thoroughly on NFS.
\r
1546 <div class="paragraph"><p>A tip is to set <strong>CCACHE_TEMPDIR</strong> to a directory on the local host to avoid NFS
\r
1547 traffic for temporary files.</p></div>
\r
1550 <div class="sect1">
\r
1551 <h2 id="_using_ccache_with_other_compiler_wrappers">Using ccache with other compiler wrappers</h2>
\r
1552 <div class="sectionbody">
\r
1553 <div class="paragraph"><p>The recommended way of combining ccache with another compiler wrapper (such as
\r
1554 “distcc”) is by using the <strong>CCACHE_PREFIX</strong> option. You just need to set the
\r
1555 environment variable <strong>CCACHE_PREFIX</strong> to the name of the wrapper (e.g. <strong>distcc</strong>)
\r
1556 and ccache will prefix the command line with the specified command when running
\r
1557 the compiler.</p></div>
\r
1558 <div class="paragraph"><p>Unless you set <strong>CCACHE_COMPILERCHECK</strong> to a suitable command (see the
\r
1559 description of that configuration option), it is not recommended to use the
\r
1560 form <strong>ccache anotherwrapper compiler args</strong> as the compilation command. It’s
\r
1561 also not recommended to use the masquerading technique for the other compiler
\r
1562 wrapper. The reason is that by default, ccache will in both cases hash the
\r
1563 mtime and size of the other wrapper instead of the real compiler, which means
\r
1565 <div class="ulist"><ul>
\r
1568 Compiler upgrades will not be detected properly.
\r
1573 The cached results will not be shared between compilations with and without
\r
1574 the other wrapper.
\r
1578 <div class="paragraph"><p>Another minor thing is that if <strong>CCACHE_PREFIX</strong> is not used, ccache will
\r
1579 needlessly invoke the other wrapper when running the preprocessor.</p></div>
\r
1582 <div class="sect1">
\r
1583 <h2 id="_bugs">Bugs</h2>
\r
1584 <div class="sectionbody">
\r
1585 <div class="ulist"><ul>
\r
1588 ccache doesn’t handle the GNU Assembler’s <strong>.incbin</strong> directive correctly. This
\r
1589 directive can be embedded in the source code inside an <strong><em>asm</em></strong> statement in
\r
1590 order to include a file verbatim in the object file. If the included file is
\r
1591 modified, ccache doesn’t pick up the change since the inclusion isn’t done by
\r
1592 the preprocessor. A workaround of this problem is to set <strong>CCACHE_EXTRAFILES</strong>
\r
1593 to the path of the included file.
\r
1599 <div class="sect1">
\r
1600 <h2 id="_troubleshooting">Troubleshooting</h2>
\r
1601 <div class="sectionbody">
\r
1602 <div class="sect2">
\r
1603 <h3 id="_general">General</h3>
\r
1604 <div class="paragraph"><p>A general tip for getting information about what ccache is doing is to enable
\r
1605 debug logging by setting <strong>CCACHE_LOGFILE</strong>. The log contains executed commands,
\r
1606 important decisions that ccache makes, read and written files, etc. Another way
\r
1607 of keeping track of what is happening is to check the output of <strong>ccache -s</strong>.</p></div>
\r
1609 <div class="sect2">
\r
1610 <h3 id="_performance">Performance</h3>
\r
1611 <div class="paragraph"><p>ccache has been written to perform well out of the box, but sometimes you may
\r
1612 have to do some adjustments of how you use the compiler and ccache in order to
\r
1613 improve performance.</p></div>
\r
1614 <div class="paragraph"><p>Since ccache works best when I/O is fast, put the cache directory on a fast
\r
1615 storage device if possible. Having lots of free memory so that files in the
\r
1616 cache directory stay in the disk cache is also preferrable.</p></div>
\r
1617 <div class="paragraph"><p>A good way of monitoring how well ccache works is to run <strong>ccache -s</strong> before and
\r
1618 after your build and then compare the statistics counters. Here are some common
\r
1619 problems and what may be done to increase the hit rate:</p></div>
\r
1620 <div class="ulist"><ul>
\r
1623 If “cache hit (preprocessed)” has been incremented instead of “cache hit
\r
1624 (direct)”, ccache has fallen back to preprocessor mode, which is generally
\r
1625 slower. Some possible reasons are:
\r
1627 <div class="ulist"><ul>
\r
1630 The source code has been modified in such a way that the preprocessor output
\r
1636 Compiler arguments that are hashed in the direct mode but not in the
\r
1637 preprocessor mode have changed (<strong>-I</strong>, <strong>-include</strong>, <strong>-D</strong>, etc) and they didn’t
\r
1638 affect the preprocessor output.
\r
1643 The compiler option <strong>-Xpreprocessor</strong> or <strong>-Wp,<em>X</em></strong> (except <strong>-Wp,-MD,<em>path</em></strong>
\r
1644 and <strong>Wp,-MMD,<em>path</em></strong>) is used.
\r
1649 This was the first compilation with a new value of <strong>CCACHE_BASEDIR</strong>.
\r
1654 A modification time of one of the include files is too new (created the same
\r
1655 second as the compilation is being done). This check is made to avoid a race
\r
1656 condition. To fix this, create the include file earlier in the build
\r
1657 process, if possible, or set <strong>CCACHE_SLOPPINESS</strong> to <strong>include_file_mtime</strong> if
\r
1658 you are willing to take the risk. (The race condition consists of these
\r
1659 events: the preprocessor is run; an include file is modified by someone; the
\r
1660 new include file is hashed by ccache; the real compiler is run on the
\r
1661 preprocessor’s output, which contains data from the old header file; the
\r
1662 wrong object file is stored in the cache.)
\r
1667 The <strong>__TIME__</strong> preprocessor macro is (potentially) being used. ccache
\r
1668 turns off direct mode if “__TIME__” is present in the source code
\r
1669 outside comments and string literals. This is done as a safety measure since
\r
1670 the string indicates that a <strong>__TIME__</strong> macro <em>may</em> affect the output. (To
\r
1671 be sure, ccache would have to run the preprocessor, but the sole point of
\r
1672 the direct mode is to avoid that.) If you know that <strong>__TIME__</strong> isn’t used
\r
1673 in practise, or don’t care if ccache produces objects where <strong>__TIME__</strong> is
\r
1674 expanded to something in the past, you can set <strong>CCACHE_SLOPPINESS</strong> to
\r
1675 <strong>time_macros</strong>.
\r
1680 The <strong>__DATE__</strong> preprocessor macro is (potentially) being used and the
\r
1681 date has changed. This is similar to how <strong>__TIME__</strong> is handled. If
\r
1682 “__DATE__” is present in the source code outside comments and string
\r
1683 literals, ccache hashes the current date in order to be able to produce the
\r
1684 correct object file if the <strong>__DATE__</strong> macro affects the output. If you
\r
1685 know that <strong>__DATE__</strong> isn’t used in practise, or don’t care if ccache
\r
1686 produces objects where <strong>__DATE__</strong> is expanded to something in the past,
\r
1687 you can set <strong>CCACHE_SLOPPINESS</strong> to <strong>time_macros</strong>.
\r
1692 The <strong>__FILE__</strong> preprocessor macro is (potentially) being used and the
\r
1693 file path has changed. If “__FILE__” is present in the source code
\r
1694 outside comments and string literals, ccache hashes the current input file
\r
1695 path in order to be able to produce the correct object file if the
\r
1696 <strong>__FILE__</strong> macro affects the output. If you know that <strong>__FILE__</strong> isn’t
\r
1697 used in practise, or don’t care if ccache produces objects where
\r
1698 <strong>__FILE__</strong> is expanded to the wrong path, you can set <strong>CCACHE_SLOPPINESS</strong>
\r
1699 to <strong>file_macro</strong>.
\r
1706 If “cache miss” has been incremented even though the same code has been
\r
1707 compiled and cached before, ccache has either detected that something has
\r
1708 changed anyway or a cleanup has been performed (either explicitly or
\r
1709 implicitly when a cache limit has been reached). Some perhaps unobvious
\r
1710 things that may result in a cache miss are usage of <strong>__TIME__</strong> or
\r
1711 <strong>__DATE__</strong> macros, or use of automatically generated code that contains a
\r
1712 timestamp, build counter or other volatile information.
\r
1717 If “multiple source files” has been incremented, it’s an indication that
\r
1718 the compiler has been invoked on several source code files at once. ccache
\r
1719 doesn’t support that. Compile the source code files separately if possible.
\r
1724 If “unsupported compiler option” has been incremented, enable debug logging
\r
1725 and check which option was rejected.
\r
1730 If “preprocessor error” has been incremented, one possible reason is that
\r
1731 precompiled headers are being used. See <a href="#_precompiled_headers">PRECOMPILED HEADERS</a> for how to remedy this.
\r
1736 If “can’t use precompiled header” has been incremented, see
\r
1737 <a href="#_precompiled_headers">PRECOMPILED HEADERS</a>.
\r
1742 <div class="sect2">
\r
1743 <h3 id="_errors_when_compiling_with_ccache">Errors when compiling with ccache</h3>
\r
1744 <div class="paragraph"><p>If compilation doesn’t work with ccache, but it works without it, one possible
\r
1745 reason is that the compiler can’t compile preprocessed output correctly. A
\r
1746 workaround that may work is to set <strong>CCACHE_CPP2</strong>. This will make cache misses
\r
1747 slower, though, so it is better to find and fix the root cause.</p></div>
\r
1749 <div class="sect2">
\r
1750 <h3 id="_corrupt_object_files">Corrupt object files</h3>
\r
1751 <div class="paragraph"><p>It should be noted that ccache is susceptible to general storage problems. If a
\r
1752 bad object file sneaks into the cache for some reason, it will of course stay
\r
1753 bad. Some possible reasons for erroneous object files are bad hardware (disk
\r
1754 drive, disk controller, memory, etc), buggy drivers or file systems, a bad
\r
1755 <strong>CCACHE_PREFIX</strong> command or compiler wrapper. If this happens, you can either
\r
1756 find out which object file is broken by reading the debug log and then delete
\r
1757 the bad object file from the cache, or you can simply clear the whole cache
\r
1758 with <strong>ccache -C</strong> if you don’t mind losing other cached results.</p></div>
\r
1759 <div class="paragraph"><p>There are no reported issues about ccache producing broken object files
\r
1760 reproducibly. That doesn’t mean it can’t happen, so if you find a repeatable
\r
1761 case, please report it.</p></div>
\r
1765 <div class="sect1">
\r
1766 <h2 id="_more_information">More information</h2>
\r
1767 <div class="sectionbody">
\r
1768 <div class="paragraph"><p>Credits, mailing list information, bug reporting instructions, source code,
\r
1769 etc, can be found on ccache’s web site: <a href="http://ccache.samba.org">http://ccache.samba.org</a>.</p></div>
\r
1772 <div class="sect1">
\r
1773 <h2 id="_author">Author</h2>
\r
1774 <div class="sectionbody">
\r
1775 <div class="paragraph"><p>ccache was originally written by Andrew Tridgell and is currently developed and
\r
1776 maintained by Joel Rosdahl. See AUTHORS.txt or AUTHORS.html and
\r
1777 <a href="http://ccache.samba.org/credits.html">http://ccache.samba.org/credits.html</a> for a list of contributors.</p></div>
\r
1781 <div id="footnotes"><hr /></div>
\r
1783 <div id="footer-text">
\r
1784 Version 3.1.6<br />
\r
1785 Last updated 2011-08-14 21:46:15 CEST
\r
projects / platform / upstream / ccache.git / blob