« back to all changes in this revision
Viewing changes to MANUAL.html
- browse files at revision 11
- compare with another revision
- download diff
- download tarball
- view history from revision 11
- Committer: Bazaar Package Importer
- Author(s): Joel Rosdahl
- Date: 2010-12-02 21:05:17 UTC
- mfrom: (5.1.4 sid)
- Revision ID: james.westby@ubuntu.com-20101202210517-ji5owl2qa3s5c1rg
New upstream version.
- files added:
- .pc/debian-changes-3.1.3-1
- .pc/debian-changes-3.1.3-1/patches
- test
- files removed:
- .pc/debian-changes-3.0.1-1
- .pc/debian-changes-3.0.1-1/patches
- files modified:
- .pc/applied-patches
added
removed
MANUAL.html
1
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
2
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
3
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
4
<head>
5
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
6
<meta name="generator" content="AsciiDoc 8.5.2" />
7
<title>CCACHE(1)</title>
8
<style type="text/css">
9
/* Debug borders */
10
p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {
11
/*
12
border: 1px solid red;
13
*/
14
}
15
16
body {
17
margin: 1em 5% 1em 5%;
18
}
19
20
a {
21
color: blue;
22
text-decoration: underline;
23
}
24
a:visited {
25
color: fuchsia;
26
}
27
28
em {
29
font-style: italic;
30
color: navy;
31
}
32
33
strong {
34
font-weight: bold;
35
color: #083194;
36
}
37
38
tt {
39
color: navy;
40
}
41
42
h1, h2, h3, h4, h5, h6 {
43
color: #527bbd;
44
font-family: sans-serif;
45
margin-top: 1.2em;
46
margin-bottom: 0.5em;
47
line-height: 1.3;
48
}
49
50
h1, h2, h3 {
51
border-bottom: 2px solid silver;
52
}
53
h2 {
54
padding-top: 0.5em;
55
}
56
h3 {
57
float: left;
58
}
59
h3 + * {
60
clear: left;
61
}
62
63
div.sectionbody {
64
font-family: serif;
65
margin-left: 0;
66
}
67
68
hr {
69
border: 1px solid silver;
70
}
71
72
p {
73
margin-top: 0.5em;
74
margin-bottom: 0.5em;
75
}
76
77
ul, ol, li > p {
78
margin-top: 0;
79
}
80
81
pre {
82
padding: 0;
83
margin: 0;
84
}
85
86
span#author {
87
color: #527bbd;
88
font-family: sans-serif;
89
font-weight: bold;
90
font-size: 1.1em;
91
}
92
span#email {
93
}
94
span#revnumber, span#revdate, span#revremark {
95
font-family: sans-serif;
96
}
97
98
div#footer {
99
font-family: sans-serif;
100
font-size: small;
101
border-top: 2px solid silver;
102
padding-top: 0.5em;
103
margin-top: 4.0em;
104
}
105
div#footer-text {
106
float: left;
107
padding-bottom: 0.5em;
108
}
109
div#footer-badges {
110
float: right;
111
padding-bottom: 0.5em;
112
}
113
114
div#preamble {
115
margin-top: 1.5em;
116
margin-bottom: 1.5em;
117
}
118
div.tableblock, div.imageblock, div.exampleblock, div.verseblock,
119
div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
120
div.admonitionblock {
121
margin-top: 1.0em;
122
margin-bottom: 1.5em;
123
}
124
div.admonitionblock {
125
margin-top: 2.0em;
126
margin-bottom: 2.0em;
127
margin-right: 10%;
128
color: #606060;
129
}
130
131
div.content { /* Block element content. */
132
padding: 0;
133
}
134
135
/* Block element titles. */
136
div.title, caption.title {
137
color: #527bbd;
138
font-family: sans-serif;
139
font-weight: bold;
140
text-align: left;
141
margin-top: 1.0em;
142
margin-bottom: 0.5em;
143
}
144
div.title + * {
145
margin-top: 0;
146
}
147
148
td div.title:first-child {
149
margin-top: 0.0em;
150
}
151
div.content div.title:first-child {
152
margin-top: 0.0em;
153
}
154
div.content + div.title {
155
margin-top: 0.0em;
156
}
157
158
div.sidebarblock > div.content {
159
background: #ffffee;
160
border: 1px solid silver;
161
padding: 0.5em;
162
}
163
164
div.listingblock > div.content {
165
border: 1px solid silver;
166
background: #f4f4f4;
167
padding: 0.5em;
168
}
169
170
div.quoteblock, div.verseblock {
171
padding-left: 1.0em;
172
margin-left: 1.0em;
173
margin-right: 10%;
174
border-left: 5px solid #dddddd;
175
color: #777777;
176
}
177
178
div.quoteblock > div.attribution {
179
padding-top: 0.5em;
180
text-align: right;
181
}
182
183
div.verseblock > div.content {
184
white-space: pre;
185
}
186
div.verseblock > div.attribution {
187
padding-top: 0.75em;
188
text-align: left;
189
}
190
/* DEPRECATED: Pre version 8.2.7 verse style literal block. */
191
div.verseblock + div.attribution {
192
text-align: left;
193
}
194
195
div.admonitionblock .icon {
196
vertical-align: top;
197
font-size: 1.1em;
198
font-weight: bold;
199
text-decoration: underline;
200
color: #527bbd;
201
padding-right: 0.5em;
202
}
203
div.admonitionblock td.content {
204
padding-left: 0.5em;
205
border-left: 3px solid #dddddd;
206
}
207
208
div.exampleblock > div.content {
209
border-left: 3px solid #dddddd;
210
padding-left: 0.5em;
211
}
212
213
div.imageblock div.content { padding-left: 0; }
214
span.image img { border-style: none; }
215
a.image:visited { color: white; }
216
217
dl {
218
margin-top: 0.8em;
219
margin-bottom: 0.8em;
220
}
221
dt {
222
margin-top: 0.5em;
223
margin-bottom: 0;
224
font-style: normal;
225
color: navy;
226
}
227
dd > *:first-child {
228
margin-top: 0.1em;
229
}
230
231
ul, ol {
232
list-style-position: outside;
233
}
234
ol.arabic {
235
list-style-type: decimal;
236
}
237
ol.loweralpha {
238
list-style-type: lower-alpha;
239
}
240
ol.upperalpha {
241
list-style-type: upper-alpha;
242
}
243
ol.lowerroman {
244
list-style-type: lower-roman;
245
}
246
ol.upperroman {
247
list-style-type: upper-roman;
248
}
249
250
div.compact ul, div.compact ol,
251
div.compact p, div.compact p,
252
div.compact div, div.compact div {
253
margin-top: 0.1em;
254
margin-bottom: 0.1em;
255
}
256
257
div.tableblock > table {
258
border: 3px solid #527bbd;
259
}
260
thead, p.table.header {
261
font-family: sans-serif;
262
font-weight: bold;
263
}
264
tfoot {
265
font-weight: bold;
266
}
267
td > div.verse {
268
white-space: pre;
269
}
270
p.table {
271
margin-top: 0;
272
}
273
/* Because the table frame attribute is overriden by CSS in most browsers. */
274
div.tableblock > table[frame="void"] {
275
border-style: none;
276
}
277
div.tableblock > table[frame="hsides"] {
278
border-left-style: none;
279
border-right-style: none;
280
}
281
div.tableblock > table[frame="vsides"] {
282
border-top-style: none;
283
border-bottom-style: none;
284
}
285
286
287
div.hdlist {
288
margin-top: 0.8em;
289
margin-bottom: 0.8em;
290
}
291
div.hdlist tr {
292
padding-bottom: 15px;
293
}
294
dt.hdlist1.strong, td.hdlist1.strong {
295
font-weight: bold;
296
}
297
td.hdlist1 {
298
vertical-align: top;
299
font-style: normal;
300
padding-right: 0.8em;
301
color: navy;
302
}
303
td.hdlist2 {
304
vertical-align: top;
305
}
306
div.hdlist.compact tr {
307
margin: 0;
308
padding-bottom: 0;
309
}
310
311
.comment {
312
background: yellow;
313
}
314
315
.footnote, .footnoteref {
316
font-size: 0.8em;
317
}
318
319
span.footnote, span.footnoteref {
320
vertical-align: super;
321
}
322
323
#footnotes {
324
margin: 20px 0 20px 0;
325
padding: 7px 0 0 0;
326
}
327
328
#footnotes div.footnote {
329
margin: 0 0 5px 0;
330
}
331
332
#footnotes hr {
333
border: none;
334
border-top: 1px solid silver;
335
height: 1px;
336
text-align: left;
337
margin-left: 0;
338
width: 20%;
339
min-width: 100px;
340
}
341
342
343
@media print {
344
div#footer-badges { display: none; }
345
}
346
347
div#toc {
348
margin-bottom: 2.5em;
349
}
350
351
div#toctitle {
352
color: #527bbd;
353
font-family: sans-serif;
354
font-size: 1.1em;
355
font-weight: bold;
356
margin-top: 1.0em;
357
margin-bottom: 0.1em;
358
}
359
360
div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
361
margin-top: 0;
362
margin-bottom: 0;
363
}
364
div.toclevel2 {
365
margin-left: 2em;
366
font-size: 0.9em;
367
}
368
div.toclevel3 {
369
margin-left: 4em;
370
font-size: 0.9em;
371
}
372
div.toclevel4 {
373
margin-left: 6em;
374
font-size: 0.9em;
375
}
376
/* Workarounds for IE6's broken and incomplete CSS2. */
377
378
div.sidebar-content {
379
background: #ffffee;
380
border: 1px solid silver;
381
padding: 0.5em;
382
}
383
div.sidebar-title, div.image-title {
384
color: #527bbd;
385
font-family: sans-serif;
386
font-weight: bold;
387
margin-top: 0.0em;
388
margin-bottom: 0.5em;
389
}
390
391
div.listingblock div.content {
392
border: 1px solid silver;
393
background: #f4f4f4;
394
padding: 0.5em;
395
}
396
397
div.quoteblock-attribution {
398
padding-top: 0.5em;
399
text-align: right;
400
}
401
402
div.verseblock-content {
403
white-space: pre;
404
}
405
div.verseblock-attribution {
406
padding-top: 0.75em;
407
text-align: left;
408
}
409
410
div.exampleblock-content {
411
border-left: 3px solid #dddddd;
412
padding-left: 0.5em;
413
}
414
415
/* IE6 sets dynamically generated links as visited. */
416
div#toc a:visited { color: blue; }
417
</style>
418
<script type="text/javascript">
419
/*<+'])');
463
// Function that scans the DOM tree for header elements (the DOM2
464
// nodeIterator API would be a better technique but not supported by all
465
// browsers).
466
var iterate = function (el) {
467
for (var i = el.firstChild; i != null; i = i.nextSibling) {
468
if (i.nodeType == 1 /* Node.ELEMENT_NODE */) {
469
var mo = re.exec(i.tagName);
470
if (mo && (i.getAttribute("class") || i.getAttribute("className")) != "float") {
471
result[result.length] = new TocEntry(i, getText(i), mo[1]-1);
472
}
473
iterate(i);
474
}
475
}
476
}
477
iterate(el);
478
return result;
479
}
480
481
var toc = document.getElementById("toc");
482
var entries = tocEntries(document.getElementById("content"), toclevels);
483
for (var i = 0; i < entries.length; ++i) {
484
var entry = entries[i];
485
if (entry.element.id == "")
486
entry.element.id = "_toc_" + i;
487
var a = document.createElement("a");
488
a.href = "#" + entry.element.id;
489
a.appendChild(document.createTextNode(entry.text));
490
var div = document.createElement("div");
491
div.appendChild(a);
492
div.className = "toclevel" + entry.toclevel;
493
toc.appendChild(div);
494
}
495
if (entries.length == 0)
496
toc.parentNode.removeChild(toc);
497
},
498
499
500
/////////////////////////////////////////////////////////////////////
501
// Footnotes generator
502
/////////////////////////////////////////////////////////////////////
503
504
/* Based on footnote generation code from:
505
* http://www.brandspankingnew.net/archive/2005/07/format_footnote.html
506
*/
507
508
footnotes: function () {
509
var cont = document.getElementById("content");
510
var noteholder = document.getElementById("footnotes");
511
var spans = cont.getElementsByTagName("span");
512
var refs = {};
513
var n = 0;
514
for (i=0; i<spans.length; i++) {
515
if (spans[i].className == "footnote") {
516
n++;
517
// Use [\s\S] in place of . so multi-line matches work.
518
// Because JavaScript has no s (dotall) regex flag.
519
note = spans[i].innerHTML.match(/\s*\[([\s\S]*)]\s*/)[1];
520
noteholder.innerHTML +=
521
"<div class='footnote' id='_footnote_" + n + "'>" +
522
"<a href='#_footnoteref_" + n + "' title='Return to text'>" +
523
n + "</a>. " + note + "</div>";
524
spans[i].innerHTML =
525
"[<a id='_footnoteref_" + n + "' href='#_footnote_" + n +
526
"' title='View footnote' class='footnote'>" + n + "</a>]";
527
var id =spans[i].getAttribute("id");
528
if (id != null) refs["#"+id] = n;
529
}
530
}
531
if (n == 0)
532
noteholder.parentNode.removeChild(noteholder);
533
else {
534
// Process footnoterefs.
535
for (i=0; i<spans.length; i++) {
536
if (spans[i].className == "footnoteref") {
537
var href = spans[i].getElementsByTagName("a")[0].getAttribute("href");
538
href = href.match(/#.*/)[0]; // Because IE return full URL.
539
n = refs[href];
540
spans[i].innerHTML =
541
"[<a href='#_footnote_" + n +
542
"' title='View footnote' class='footnote'>" + n + "</a>]";
543
}
544
}
545
}
546
}
547
548
}
549
/*]]>*/
550
</script>
551
</head>
552
<body>
553
<div id="header">
554
<h1>CCACHE(1)</h1>
555
<span id="revnumber">version 3.1.3</span>
556
<div id="toc">
557
<div id="toctitle">Table of Contents</div>
558
<noscript><p><b>JavaScript must be enabled in your browser to display the table of contents.</b></p></noscript>
559
</div>
560
</div>
561
<div id="content">
562
<h2 id="_name">Name</h2>
563
<div class="sectionbody">
564
<div class="paragraph"><p>ccache - a fast C/C++ compiler cache</p></div>
565
</div>
566
<h2 id="_synopsis">Synopsis</h2>
567
<div class="sectionbody">
568
<div class="verseblock">
569
<div class="verseblock-content"><strong>ccache</strong> [<em>options</em>]
570
<strong>ccache</strong> <em>compiler</em> [<em>compiler options</em>]
571
<em>compiler</em> [<em>compiler options</em>] (via symbolic link)</div>
572
<div class="verseblock-attribution">
573
</div></div>
574
</div>
575
<h2 id="_description">Description</h2>
576
<div class="sectionbody">
577
<div class="paragraph"><p>ccache is a compiler cache. It speeds up recompilation by caching the result of
578
previous compilations and detecting when the same compilation is being done
579
again. Supported languages are C, C++, Objective-C and Objective-C++.</p></div>
580
<div class="paragraph"><p>ccache has been carefully written to always produce exactly the same compiler
581
output that you would get without the cache. The only way you should be able to
582
tell that you are using ccache is the speed. Currently known exceptions to this
583
goal are listed under <a href="#_bugs">BUGS</a>. If you ever discover an undocumented case
584
where ccache changes the output of your compiler, please let us know.</p></div>
585
<h3 id="_features">Features</h3><div style="clear:left"></div>
586
<div class="ulist"><ul>
587
<li>
588
<p>
589
Keeps statistics on hits/misses.
590
</p>
591
</li>
592
<li>
593
<p>
594
Automatic cache size management.
595
</p>
596
</li>
597
<li>
598
<p>
599
Can cache compilations that generate warnings.
600
</p>
601
</li>
602
<li>
603
<p>
604
Easy installation.
605
</p>
606
</li>
607
<li>
608
<p>
609
Low overhead.
610
</p>
611
</li>
612
<li>
613
<p>
614
Optionally uses hard links where possible to avoid copies.
615
</p>
616
</li>
617
<li>
618
<p>
619
Optionally compresses files in the cache to reduce disk space.
620
</p>
621
</li>
622
</ul></div>
623
<h3 id="_limitations">Limitations</h3><div style="clear:left"></div>
624
<div class="ulist"><ul>
625
<li>
626
<p>
627
Only knows how to cache the compilation of a single
628
C/C++/Objective-C/Objective-C++ file. Other types of compilations
629
(multi-file compilation, linking, etc) will silently fall back to running the
630
real compiler.
631
</p>
632
</li>
633
<li>
634
<p>
635
Only works with GCC and compilers that behave similar enough.
636
</p>
637
</li>
638
<li>
639
<p>
640
Some compiler flags are not supported. If such a flag is detected, ccache
641
will silently fall back to running the real compiler.
642
</p>
643
</li>
644
</ul></div>
645
</div>
646
<h2 id="_run_modes">Run modes</h2>
647
<div class="sectionbody">
648
<div class="paragraph"><p>There are two ways to use ccache. You can either prefix your compilation
649
commands with <strong>ccache</strong> or you can let ccache masquerade as the compiler by
650
creating a symbolic link (named as the compiler) to ccache. The first method is
651
most convenient if you just want to try out ccache or wish to use it for some
652
specific projects. The second method is most useful for when you wish to use
653
ccache for all your compilations.</p></div>
654
<div class="paragraph"><p>To use the first method, just make sure that <strong>ccache</strong> is in your <strong>PATH</strong>.</p></div>
655
<div class="paragraph"><p>To use the symlinks method, do something like this:</p></div>
656
<div class="listingblock">
657
<div class="content">
658
<pre><tt>cp ccache /usr/local/bin/
659
ln -s ccache /usr/local/bin/gcc
660
ln -s ccache /usr/local/bin/g++
661
ln -s ccache /usr/local/bin/cc
662
ln -s ccache /usr/local/bin/c++</tt></pre>
663
</div></div>
664
<div class="paragraph"><p>And so forth. This will work as long as the directory with symlinks comes
665
before the path to the compiler (which is usually in <tt>/usr/bin</tt>). After
666
installing you may wish to run “which gcc” to make sure that the correct link
667
is being used.</p></div>
668
<div class="admonitionblock">
669
<table><tr>
670
<td class="icon">
671
<div class="title">Warning</div>
672
</td>
673
<td class="content">The technique of letting ccache masquerade as the compiler works well,
674
but currently doesn’t interact well with other tools that do the same thing.
675
See <a href="#_using_ccache_with_other_compiler_wrappers">USING CCACHE WITH OTHER COMPILER WRAPPERS</a>.</td>
676
</tr></table>
677
</div>
678
<div class="admonitionblock">
679
<table><tr>
680
<td class="icon">
681
<div class="title">Warning</div>
682
</td>
683
<td class="content">Do not use a hard link, use a symbolic link. A hard link will cause
684
“interesting” problems.</td>
685
</tr></table>
686
</div>
687
</div>
688
<h2 id="_options">Options</h2>
689
<div class="sectionbody">
690
<div class="paragraph"><p>These options only apply when you invoke ccache as “ccache”. When invoked as
691
a compiler (via a symlink as described in the previous section), the normal
692
compiler options apply and you should refer to the compiler’s documentation.</p></div>
693
<div class="dlist"><dl>
694
<dt class="hdlist1">
695
<strong>-c, --cleanup</strong>
696
</dt>
697
<dd>
698
<p>
699
Clean up the cache by removing old cached files until the specified file
700
number and cache size limits are not exceeded. This also recalculates the
701
cache file count and size totals. Normally, it’s not needed to initiate
702
cleanup manually as ccache keeps the cache below the specified limits at
703
runtime and keeps statistics up to date on each compilation. Forcing a
704
cleanup is mostly useful if you manually modify the cache contents or
705
believe that the cache size statistics may be inaccurate.
706
</p>
707
</dd>
708
<dt class="hdlist1">
709
<strong>-C, --clear</strong>
710
</dt>
711
<dd>
712
<p>
713
Clear the entire cache, removing all cached files.
714
</p>
715
</dd>
716
<dt class="hdlist1">
717
<strong>-F, --max-files</strong>=<em>N</em>
718
</dt>
719
<dd>
720
<p>
721
Set the maximum number of files allowed in the cache. The value is stored
722
inside the cache directory and applies to all future compilations. Due to
723
the way the value is stored the actual value used is always rounded down to
724
the nearest multiple of 16.
725
</p>
726
</dd>
727
<dt class="hdlist1">
728
<strong>-h, --help</strong>
729
</dt>
730
<dd>
731
<p>
732
Print an options summary page.
733
</p>
734
</dd>
735
<dt class="hdlist1">
736
<strong>-M, --max-size</strong>=<em>SIZE</em>
737
</dt>
738
<dd>
739
<p>
740
Set the maximum size of the files stored in the cache. You can specify a
741
value in gigabytes, megabytes or kilobytes by appending a G, M or K to the
742
value. The default is gigabytes. The actual value stored is rounded down to
743
the nearest multiple of 16 kilobytes.
744
</p>
745
</dd>
746
<dt class="hdlist1">
747
<strong>-s, --show-stats</strong>
748
</dt>
749
<dd>
750
<p>
751
Print the current statistics summary for the cache.
752
</p>
753
</dd>
754
<dt class="hdlist1">
755
<strong>-V, --version</strong>
756
</dt>
757
<dd>
758
<p>
759
Print version and copyright information.
760
</p>
761
</dd>
762
<dt class="hdlist1">
763
<strong>-z, --zero-stats</strong>
764
</dt>
765
<dd>
766
<p>
767
Zero the cache statistics (but not the configured limits).
768
</p>
769
</dd>
770
</dl></div>
771
</div>
772
<h2 id="_extra_options">Extra options</h2>
773
<div class="sectionbody">
774
<div class="paragraph"><p>When run as a compiler, ccache usually just takes the same command line options
775
as the compiler you are using. The only exception to this is the option
776
<strong>--ccache-skip</strong>. That option can be used to tell ccache to avoid interpreting
777
the next option in any way and to pass it along to the compiler as-is.</p></div>
778
<div class="paragraph"><p>The reason this can be important is that ccache does need to parse the command
779
line and determine what is an input filename and what is a compiler option, as
780
it needs the input filename to determine the name of the resulting object file
781
(among other things). The heuristic ccache uses when parsing the command line
782
is that any argument that exists as a file is treated as an input file name. By
783
using <strong>--ccache-skip</strong> you can force an option to not be treated as an input
784
file name and instead be passed along to the compiler as a command line option.</p></div>
785
<div class="paragraph"><p>Another case where <strong>--ccache-skip</strong> can be useful is if ccache interprets an
786
option specially but shouldn’t, since the option has another meaning for your
787
compiler than what ccache thinks.</p></div>
788
</div>
789
<h2 id="_environment_variables">Environment variables</h2>
790
<div class="sectionbody">
791
<div class="paragraph"><p>ccache uses a number of environment variables to control operation. In most
792
cases you won’t need any of these as the defaults will be fine.</p></div>
793
<div class="dlist"><dl>
794
<dt class="hdlist1">
795
<strong>CCACHE_BASEDIR</strong>
796
</dt>
797
<dd>
798
<p>
799
If you set the environment variable <strong>CCACHE_BASEDIR</strong> to an absolute path to
800
a directory, ccache rewrites absolute paths into relative paths before
801
computing the hash that identifies the compilation, but only for paths
802
under the specified directory. See the discussion under
803
<a href="#_compiling_in_different_directories">COMPILING IN DIFFERENT DIRECTORIES</a>.
804
</p>
805
</dd>
806
<dt class="hdlist1">
807
<strong>CCACHE_CC</strong>
808
</dt>
809
<dd>
810
<p>
811
You can optionally set <strong>CCACHE_CC</strong> to force the name of the compiler to
812
use. If you don’t do this then ccache works it out from the command line.
813
</p>
814
</dd>
815
<dt class="hdlist1">
816
<strong>CCACHE_COMPILERCHECK</strong>
817
</dt>
818
<dd>
819
<p>
820
By default, ccache includes the modification time (“mtime”) and size of
821
the compiler in the hash to ensure that results retrieved from the cache
822
are accurate. The <strong>CCACHE_COMPILERCHECK</strong> environment variable can be used
823
to select another strategy. Possible values are:
824
</p>
825
<div class="dlist"><dl>
826
<dt class="hdlist1">
827
<strong>content</strong>
828
</dt>
829
<dd>
830
<p>
831
Hash the content of the compiler binary. This makes ccache very slightly
832
slower compared to the <strong>mtime</strong> setting, but makes it cope better with
833
compiler upgrades during a build bootstrapping process.
834
</p>
835
</dd>
836
<dt class="hdlist1">
837
<strong>mtime</strong>
838
</dt>
839
<dd>
840
<p>
841
Hash the compiler’s mtime and size, which is fast. This is the default.
842
</p>
843
</dd>
844
<dt class="hdlist1">
845
<strong>none</strong>
846
</dt>
847
<dd>
848
<p>
849
Don’t hash anything. This may be good for situations where you can safely
850
use the cached results even though the compiler’s mtime or size has changed
851
(e.g. if the compiler is built as part of your build system and the
852
compiler’s source has not changed, or if the compiler only has changes that
853
don’t affect code generation). You should only use the <strong>none</strong> setting if
854
you know what you are doing.
855
</p>
856
</dd>
857
<dt class="hdlist1">
858
<em>a command string</em>
859
</dt>
860
<dd>
861
<p>
862
Hash the standard output and standard error output of the specified
863
command. The string will be split on whitespace to find out the command and
864
arguments to run. No other interpretation of the command string will be
865
done, except that the special word “%compiler%” will be replaced with the
866
path to the compiler. Several commands can be specified with semicolon as
867
separator. Examples:
868
</p>
869
<div class="ulist"><ul>
870
<li>
871
<p>
872
<tt>%compiler% -v</tt>
873
</p>
874
</li>
875
<li>
876
<p>
877
<tt>%compiler% -dumpmachine; %compiler% -dumpversion</tt>
878
</p>
879
</li>
880
</ul></div>
881
<div class="paragraph"><p>You should make sure that the specified command is as fast as possible since it
882
will be run once for each ccache invocation.</p></div>
883
<div class="paragraph"><p>Identifying the compiler using a command is useful if you want to avoid cache
884
misses when the compiler has been rebuilt but not changed.</p></div>
885
<div class="paragraph"><p>Another case is when the compiler (as seen by ccache) actually isn’t the real
886
compiler but another compiler wrapper — in that case, the default <strong>mtime</strong>
887
method will hash the mtime and size of the other compiler wrapper, which means
888
that ccache won’t be able to detect a compiler upgrade. Using a suitable
889
command to identify the compiler is thus safer, but it’s also slower, so you
890
should consider continue using the <strong>mtime</strong> method in combination with
891
<strong>CCACHE_PREFIX</strong> if possible. See
892
<a href="#_using_ccache_with_other_compiler_wrappers">USING CCACHE WITH OTHER COMPILER WRAPPERS</a>.</p></div>
893
</dd>
894
</dl></div>
895
</dd>
896
<dt class="hdlist1">
897
<strong>CCACHE_COMPRESS</strong>
898
</dt>
899
<dd>
900
<p>
901
If you set the environment variable <strong>CCACHE_COMPRESS</strong> then ccache will
902
compress object files and other compiler output it puts in the cache.
903
However, this setting has no effect on how files are retrieved from the
904
cache; compressed and uncompressed results will still be usable regardless
905
of this setting.
906
</p>
907
</dd>
908
<dt class="hdlist1">
909
<strong>CCACHE_CPP2</strong>
910
</dt>
911
<dd>
912
<p>
913
If you set the environment variable <strong>CCACHE_CPP2</strong> then ccache will not use
914
the optimisation of avoiding the second call to the preprocessor by
915
compiling the preprocessed output that was used for finding the hash in the
916
case of a cache miss. This is primarily a debugging option, although it is
917
possible that some unusual compilers will have problems with the
918
intermediate filename extensions used in this optimisation, in which case
919
this option could allow ccache to be used anyway.
920
</p>
921
</dd>
922
<dt class="hdlist1">
923
<strong>CCACHE_DETECT_SHEBANG</strong>
924
</dt>
925
<dd>
926
<p>
927
The <strong>CCACHE_DETECT_SHEBANG</strong> environment variable only has meaning on
928
Windows. It instructs ccache to open the executable file to detect the
929
<strong>#!/bin/sh</strong> string, in which case ccache will search for <strong>sh.exe</strong> in
930
<strong>PATH</strong> and use that to launch the executable.
931
</p>
932
</dd>
933
<dt class="hdlist1">
934
<strong>CCACHE_DIR</strong>
935
</dt>
936
<dd>
937
<p>
938
The <strong>CCACHE_DIR</strong> environment variable specifies where ccache will keep its
939
cached compiler output. The default is <strong>$HOME/.ccache</strong>.
940
</p>
941
</dd>
942
<dt class="hdlist1">
943
<strong>CCACHE_DISABLE</strong>
944
</dt>
945
<dd>
946
<p>
947
If you set the environment variable <strong>CCACHE_DISABLE</strong> then ccache will just
948
call the real compiler, bypassing the cache completely.
949
</p>
950
</dd>
951
<dt class="hdlist1">
952
<strong>CCACHE_EXTENSION</strong>
953
</dt>
954
<dd>
955
<p>
956
ccache tries to automatically determine the extension to use for
957
intermediate preprocessor files based on the type of file being compiled.
958
Unfortunately this sometimes doesn’t work, for example when using the
959
“aCC” compiler on HP-UX. On systems like this you can use the
960
<strong>CCACHE_EXTENSION</strong> option to override the default. On HP-UX set this
961
environment variable to <strong>i</strong> if you use the “aCC” compiler.
962
</p>
963
</dd>
964
<dt class="hdlist1">
965
<strong>CCACHE_EXTRAFILES</strong>
966
</dt>
967
<dd>
968
<p>
969
If you set the environment variable <strong>CCACHE_EXTRAFILES</strong> to a list of paths
970
then ccache will include the contents of those files when calculating the
971
hash sum. The list separator is semicolon in Windows systems and colon on
972
other systems.
973
</p>
974
</dd>
975
<dt class="hdlist1">
976
<strong>CCACHE_HARDLINK</strong>
977
</dt>
978
<dd>
979
<p>
980
If you set the environment variable <strong>CCACHE_HARDLINK</strong> then ccache will
981
attempt to use hard links from the cache directory when creating the
982
compiler output rather than using a file copy. Using hard links may be
983
slightly faster in some situations, but can confuse programs like “make”
984
that rely on modification times. Another thing to keep in mind is that if
985
the resulting object file is modified in any way, this corrupts the cached
986
object file as well. Hard links are never made for compressed cache files.
987
This means that you should not set the <strong>CCACHE_COMPRESS</strong> variable if you
988
want to use hard links.
989
</p>
990
</dd>
991
<dt class="hdlist1">
992
<strong>CCACHE_HASHDIR</strong>
993
</dt>
994
<dd>
995
<p>
996
This tells ccache to hash the current working directory when calculating
997
the hash that is used to distinguish two compilations. This prevents a
998
problem with the storage of the current working directory in the debug info
999
of a object file, which can lead ccache to give a cached object file that
1000
has the working directory in the debug info set incorrectly. This option is
1001
off by default as the incorrect setting of this debug info rarely causes
1002
problems. If you strike problems with GDB not using the correct directory
1003
then enable this option.
1004
</p>
1005
</dd>
1006
<dt class="hdlist1">
1007
<strong>CCACHE_LOGFILE</strong>
1008
</dt>
1009
<dd>
1010
<p>
1011
If you set the <strong>CCACHE_LOGFILE</strong> environment variable then ccache will write
1012
information on what it is doing to the specified file. This is useful for
1013
tracking down problems.
1014
</p>
1015
</dd>
1016
<dt class="hdlist1">
1017
<strong>CCACHE_NLEVELS</strong>
1018
</dt>
1019
<dd>
1020
<p>
1021
The environment variable <strong>CCACHE_NLEVELS</strong> allows you to choose the number
1022
of levels of hash in the cache directory. The default is 2. The minimum is
1023
1 and the maximum is 8.
1024
</p>
1025
</dd>
1026
<dt class="hdlist1">
1027
<strong>CCACHE_NODIRECT</strong>
1028
</dt>
1029
<dd>
1030
<p>
1031
If you set the environment variable <strong>CCACHE_NODIRECT</strong> then ccache will not
1032
use the direct mode.
1033
</p>
1034
</dd>
1035
<dt class="hdlist1">
1036
<strong>CCACHE_NOSTATS</strong>
1037
</dt>
1038
<dd>
1039
<p>
1040
If you set the environment variable <strong>CCACHE_NOSTATS</strong> then ccache will not
1041
update the statistics files on each compilation.
1042
</p>
1043
</dd>
1044
<dt class="hdlist1">
1045
<strong>CCACHE_PATH</strong>
1046
</dt>
1047
<dd>
1048
<p>
1049
You can optionally set <strong>CCACHE_PATH</strong> to a colon-separated path where ccache
1050
will look for the real compilers. If you don’t do this then ccache will
1051
look for the first executable matching the compiler name in the normal
1052
<strong>PATH</strong> that isn’t a symbolic link to ccache itself.
1053
</p>
1054
</dd>
1055
<dt class="hdlist1">
1056
<strong>CCACHE_PREFIX</strong>
1057
</dt>
1058
<dd>
1059
<p>
1060
This option adds a prefix to the command line that ccache runs when
1061
invoking the compiler. Also see the section below on using ccache with
1062
“distcc”.
1063
</p>
1064
</dd>
1065
<dt class="hdlist1">
1066
<strong>CCACHE_READONLY</strong>
1067
</dt>
1068
<dd>
1069
<p>
1070
The <strong>CCACHE_READONLY</strong> environment variable tells ccache to attempt to use
1071
existing cached object files, but not to try to add anything new to the
1072
cache. If you are using this because your <strong>CCACHE_DIR</strong> is read-only, then
1073
you may find that you also need to set <strong>CCACHE_TEMPDIR</strong> as otherwise ccache
1074
will fail to create temporary files.
1075
</p>
1076
</dd>
1077
<dt class="hdlist1">
1078
<strong>CCACHE_RECACHE</strong>
1079
</dt>
1080
<dd>
1081
<p>
1082
This forces ccache to not use any cached results, even if it finds them.
1083
New results are still cached, but existing cache entries are ignored.
1084
</p>
1085
</dd>
1086
<dt class="hdlist1">
1087
<strong>CCACHE_SLOPPINESS</strong>
1088
</dt>
1089
<dd>
1090
<p>
1091
By default, ccache tries to give as few false cache hits as possible.
1092
However, in certain situations it’s possible that you know things that
1093
ccache can’t take for granted. The <strong>CCACHE_SLOPPINESS</strong> environment variable
1094
makes it possible to tell ccache to relax some checks in order to increase
1095
the hit rate. The value should be a comma-separated string with options.
1096
Available options are:
1097
</p>
1098
<div class="dlist"><dl>
1099
<dt class="hdlist1">
1100
<strong>file_macro</strong>
1101
</dt>
1102
<dd>
1103
<p>
1104
Ignore <strong>__FILE__</strong> being present in the source.
1105
</p>
1106
</dd>
1107
<dt class="hdlist1">
1108
<strong>include_file_mtime</strong>
1109
</dt>
1110
<dd>
1111
<p>
1112
Don’t check the modification time of include files in the direct mode.
1113
</p>
1114
</dd>
1115
<dt class="hdlist1">
1116
<strong>time_macros</strong>
1117
</dt>
1118
<dd>
1119
<p>
1120
Ignore <strong>__DATE__</strong> and <strong>__TIME__</strong> being present in the source code.
1121
</p>
1122
</dd>
1123
</dl></div>
1124
<div class="paragraph"><p>See the discussion under <a href="#_troubleshooting">TROUBLESHOOTING</a> for more
1125
information.</p></div>
1126
</dd>
1127
<dt class="hdlist1">
1128
<strong>CCACHE_TEMPDIR</strong>
1129
</dt>
1130
<dd>
1131
<p>
1132
The <strong>CCACHE_TEMPDIR</strong> environment variable specifies where ccache will put
1133
temporary files. The default is <strong>$CCACHE_DIR/tmp</strong>.
1134
</p>
1135
<div class="admonitionblock">
1136
<table><tr>
1137
<td class="icon">
1138
<div class="title">Note</div>
1139
</td>
1140
<td class="content">In previous versions of ccache, <strong>CCACHE_TEMPDIR</strong> had to be on the same
1141
filesystem as the <strong>CCACHE_DIR</strong> path, but this requirement has been
1142
relaxed.)</td>
1143
</tr></table>
1144
</div>
1145
</dd>
1146
<dt class="hdlist1">
1147
<strong>CCACHE_UMASK</strong>
1148
</dt>
1149
<dd>
1150
<p>
1151
This sets the umask for ccache and all child processes (such as the
1152
compiler). This is mostly useful when you wish to share your cache with
1153
other users. Note that this also affects the file permissions set on the
1154
object files created from your compilations.
1155
</p>
1156
</dd>
1157
<dt class="hdlist1">
1158
<strong>CCACHE_UNIFY</strong>
1159
</dt>
1160
<dd>
1161
<p>
1162
If you set the environment variable <strong>CCACHE_UNIFY</strong> then ccache will use a
1163
C/C++ unifier when hashing the preprocessor output if the <strong>-g</strong> option is
1164
not used. The unifier is slower than a normal hash, so setting this
1165
environment variable loses a little bit of speed, but it means that ccache
1166
can take advantage of not recompiling when the changes to the source code
1167
consist of reformatting only. Note that using <strong>CCACHE_UNIFY</strong> changes the
1168
hash, so cached compilations with <strong>CCACHE_UNIFY</strong> set cannot be used when
1169
<strong>CCACHE_UNIFY</strong> is not set and vice versa. The reason the unifier is off by
1170
default is that it can give incorrect line number information in compiler
1171
warning messages. Also note that enabling the unifier implies turning off
1172
the direct mode.
1173
</p>
1174
</dd>
1175
</dl></div>
1176
</div>
1177
<h2 id="_cache_size_management">Cache size management</h2>
1178
<div class="sectionbody">
1179
<div class="paragraph"><p>By default ccache has a one gigabyte limit on the total size of files in the
1180
cache and no maximum number of files. You can set different limits using the
1181
<strong>-M</strong>/<strong>--max-size</strong> and <strong>-F</strong>/<strong>--max-files</strong> options. Use <strong>ccache -s/--show-stats</strong>
1182
to see the cache size and the currently configured limits (in addition to other
1183
various statistics).</p></div>
1184
</div>
1185
<h2 id="_cache_compression">Cache compression</h2>
1186
<div class="sectionbody">
1187
<div class="paragraph"><p>ccache can optionally compress all files it puts into the cache using the
1188
compression library zlib. While this involves a negligible performance
1189
slowdown, it significantly increases the number of files that fit in the cache.
1190
You can turn on compression by setting the <strong>CCACHE_COMPRESS</strong> environment
1191
variable.</p></div>
1192
</div>
1193
<h2 id="_how_ccache_works">How ccache works</h2>
1194
<div class="sectionbody">
1195
<div class="paragraph"><p>The basic idea is to detect when you are compiling exactly the same code a
1196
second time and reuse the previously produced output. The detection is done by
1197
hashing different kinds of information that should be unique for the
1198
compilation and then using the hash sum to identify the cached output. ccache
1199
uses MD4, a very fast cryptographic hash algorithm, for the hashing. (MD4 is
1200
nowadays too weak to be useful in cryptographic contexts, but it should be safe
1201
enough to be used to identify recompilations.) On a cache hit, ccache is able
1202
to supply all of the correct compiler outputs (including all warnings,
1203
dependency file, etc) from the cache.</p></div>
1204
<div class="paragraph"><p>ccache has two ways of doing the detection:</p></div>
1205
<div class="ulist"><ul>
1206
<li>
1207
<p>
1208
the <strong>direct mode</strong>, where ccache hashes the source code and include files
1209
directly
1210
</p>
1211
</li>
1212
<li>
1213
<p>
1214
the <strong>preprocessor mode</strong>, where ccache runs the preprocessor on the source
1215
code and hashes the result
1216
</p>
1217
</li>
1218
</ul></div>
1219
<div class="paragraph"><p>The direct mode is generally faster since running the preprocessor has some
1220
overhead.</p></div>
1221
<h3 id="_common_hashed_information">Common hashed information</h3><div style="clear:left"></div>
1222
<div class="paragraph"><p>For both modes, the following information is included in the hash:</p></div>
1223
<div class="ulist"><ul>
1224
<li>
1225
<p>
1226
the extension used by the compiler for a file with preprocessor output
1227
(normally <strong>.i</strong> for C code and <strong>.ii</strong> for C++ code)
1228
</p>
1229
</li>
1230
<li>
1231
<p>
1232
the compiler’s size and modification time (or other compiler-specific
1233
information specified by <strong>CCACHE_COMPILERCHECK</strong>)
1234
</p>
1235
</li>
1236
<li>
1237
<p>
1238
the name of the compiler
1239
</p>
1240
</li>
1241
<li>
1242
<p>
1243
the current directory (if <strong>CCACHE_HASHDIR</strong> is set)
1244
</p>
1245
</li>
1246
<li>
1247
<p>
1248
contents of files specified by <strong>CCACHE_EXTRAFILES</strong> (if any)
1249
</p>
1250
</li>
1251
</ul></div>
1252
<h3 id="_the_direct_mode">The direct mode</h3><div style="clear:left"></div>
1253
<div class="paragraph"><p>In the direct mode, the hash is formed of the common information and:</p></div>
1254
<div class="ulist"><ul>
1255
<li>
1256
<p>
1257
the input source file
1258
</p>
1259
</li>
1260
<li>
1261
<p>
1262
the command line options
1263
</p>
1264
</li>
1265
</ul></div>
1266
<div class="paragraph"><p>Based on the hash, a data structure called “manifest” is looked up in the
1267
cache. The manifest contains:</p></div>
1268
<div class="ulist"><ul>
1269
<li>
1270
<p>
1271
references to cached compilation results (object file, dependency file, etc)
1272
that were produced by previous compilations that matched the hash
1273
</p>
1274
</li>
1275
<li>
1276
<p>
1277
paths to the include files that were read at the time the compilation results
1278
were stored in the cache
1279
</p>
1280
</li>
1281
<li>
1282
<p>
1283
hash sums of the include files at the time the compilation results were
1284
stored in the cache
1285
</p>
1286
</li>
1287
</ul></div>
1288
<div class="paragraph"><p>The current contents of the include files are then hashed and compared to the
1289
information in the manifest. If there is a match, ccache knows the result of
1290
the compilation. If there is no match, ccache falls back to running the
1291
preprocessor. The output from the preprocessor is parsed to find the include
1292
files that were read. The paths and hash sums of those include files are then
1293
stored in the manifest along with information about the produced compilation
1294
result.</p></div>
1295
<div class="paragraph"><p>The direct mode will be disabled if any of the following holds:</p></div>
1296
<div class="ulist"><ul>
1297
<li>
1298
<p>
1299
the environment variable <strong>CCACHE_NODIRECT</strong> is set
1300
</p>
1301
</li>
1302
<li>
1303
<p>
1304
a modification time of one of the include files is too new (needed to avoid a
1305
race condition)
1306
</p>
1307
</li>
1308
<li>
1309
<p>
1310
the unifier is enabled (the environment variable <strong>CCACHE_UNIFY</strong> is set)
1311
</p>
1312
</li>
1313
<li>
1314
<p>
1315
a compiler option not supported by the direct mode is used:
1316
</p>
1317
<div class="ulist"><ul>
1318
<li>
1319
<p>
1320
a <strong>-Wp,<em>X</em></strong> compiler option other than <strong>-Wp,-MD,<em>path</em></strong> and
1321
<strong>-Wp,-MMD,<em>path</em></strong>
1322
</p>
1323
</li>
1324
<li>
1325
<p>
1326
<strong>-Xpreprocessor</strong>
1327
</p>
1328
</li>
1329
</ul></div>
1330
</li>
1331
<li>
1332
<p>
1333
the string “__TIME__” is present outside comments and string literals in
1334
the source code
1335
</p>
1336
</li>
1337
</ul></div>
1338
<h3 id="_the_preprocessor_mode">The preprocessor mode</h3><div style="clear:left"></div>
1339
<div class="paragraph"><p>In the preprocessor mode, the hash is formed of the common information and:</p></div>
1340
<div class="ulist"><ul>
1341
<li>
1342
<p>
1343
the preprocessor output from running the compiler with <strong>-E</strong>
1344
</p>
1345
</li>
1346
<li>
1347
<p>
1348
the command line options except options that affect include files (<strong>-I</strong>,
1349
<strong>-include</strong>, <strong>-D</strong>, etc; the theory is that these options will change the
1350
preprocessor output if they have any effect at all)
1351
</p>
1352
</li>
1353
<li>
1354
<p>
1355
any standard error output generated by the preprocessor
1356
</p>
1357
</li>
1358
</ul></div>
1359
<div class="paragraph"><p>Based on the hash, the cached compilation result can be looked up directly in
1360
the cache.</p></div>
1361
</div>
1362
<h2 id="_compiling_in_different_directories">Compiling in different directories</h2>
1363
<div class="sectionbody">
1364
<div class="paragraph"><p>Some information included in the hash that identifies a unique compilation may
1365
contain absolute paths:</p></div>
1366
<div class="ulist"><ul>
1367
<li>
1368
<p>
1369
The preprocessed source code may contain absolute paths to include files if
1370
the compiler option <strong>-g</strong> is used or if absolute paths are given to <strong>-I</strong> and
1371
similar compiler options.
1372
</p>
1373
</li>
1374
<li>
1375
<p>
1376
Paths specified by compiler options (such as <strong>-I</strong>, <strong>-MF</strong>, etc) may be
1377
absolute.
1378
</p>
1379
</li>
1380
<li>
1381
<p>
1382
The source code file path may be absolute, and that path may substituted for
1383
<strong>__FILE__</strong> macros in the source code or included in warnings emitted to
1384
standard error by the preprocessor.
1385
</p>
1386
</li>
1387
</ul></div>
1388
<div class="paragraph"><p>This means that if you compile the same code in different locations, you can’t
1389
share compilation results between the different build directories since you get
1390
cache misses because of the absolute build directory paths that are part of the
1391
hash. To mitigate this problem, you can specify a “base directory” by setting
1392
the <strong>CCACHE_BASEDIR</strong> variable to an absolute path to the directory. ccache will
1393
then rewrite absolute paths that are under the base directory (i.e., paths that
1394
have the base directory as a prefix) to relative paths when constructing the
1395
hash. A typical path to use as the base directory is your home directory or
1396
another directory that is a parent of your build directories. (Don’t use <tt>/</tt> as
1397
the base directory since that will make ccache also rewrite paths to system
1398
header files, which doesn’t gain anything.)</p></div>
1399
<div class="paragraph"><p>The drawbacks of using <strong>CCACHE_BASEDIR</strong> are:</p></div>
1400
<div class="ulist"><ul>
1401
<li>
1402
<p>
1403
If you specify an absolute path to the source code file, <strong>__FILE__</strong> macros
1404
will be expanded to a relative path instead.
1405
</p>
1406
</li>
1407
<li>
1408
<p>
1409
If you specify an absolute path to the source code file and compile with
1410
<strong>-g</strong>, the source code path stored in the object file may point to the wrong
1411
directory, which may prevent debuggers like GDB from finding the source code.
1412
Sometimes, a work-around is to change the directory explicitly with the
1413
“cd” command in GDB.
1414
</p>
1415
</li>
1416
</ul></div>
1417
</div>
1418
<h2 id="_precompiled_headers">Precompiled headers</h2>
1419
<div class="sectionbody">
1420
<div class="paragraph"><p>ccache has support for GCC’s precompiled headers. However, you have to do some
1421
things to make it work properly:</p></div>
1422
<div class="ulist"><ul>
1423
<li>
1424
<p>
1425
You must set <strong>CCACHE_SLOPPINESS</strong> to <strong>time_macros</strong>. The reason is that ccache
1426
can’t tell whether <strong>__TIME__</strong> or <strong>__DATE__</strong> is used when using a
1427
precompiled header.
1428
</p>
1429
</li>
1430
<li>
1431
<p>
1432
You must either:
1433
</p>
1434
<div class="ulist"><ul>
1435
<li>
1436
<p>
1437
use the <strong>-include</strong> compiler option to include the precompiled header
1438
(i.e., don’t use <strong>#include</strong> in the source code to include the header); or
1439
</p>
1440
</li>
1441
<li>
1442
<p>
1443
add the <strong>-fpch-preprocess</strong> compiler option when compiling.
1444
</p>
1445
</li>
1446
</ul></div>
1447
<div class="paragraph"><p>If you don’t do this, either the non-precompiled version of the header file
1448
will be used (if available) or ccache will fall back to running the real
1449
compiler and increase the statistics counter “preprocessor error” (if the
1450
non-precompiled header file is not available).</p></div>
1451
</li>
1452
</ul></div>
1453
</div>
1454
<h2 id="_sharing_a_cache">Sharing a cache</h2>
1455
<div class="sectionbody">
1456
<div class="paragraph"><p>A group of developers can increase the cache hit rate by sharing a cache
1457
directory. To share a cache without unpleasant side effects, the following
1458
conditions should to be met:</p></div>
1459
<div class="ulist"><ul>
1460
<li>
1461
<p>
1462
Use the same <strong>CCACHE_DIR</strong> environment variable setting.
1463
</p>
1464
</li>
1465
<li>
1466
<p>
1467
Unset the <strong>CCACHE_HARDLINK</strong> environment variable.
1468
</p>
1469
</li>
1470
<li>
1471
<p>
1472
Make sure everyone sets the <strong>CCACHE_UMASK</strong> environment variable to 002. This
1473
ensures that cached files are accessible to everyone in the group.
1474
</p>
1475
</li>
1476
<li>
1477
<p>
1478
Make sure that all users have write permission in the entire cache directory
1479
(and that you trust all users of the shared cache).
1480
</p>
1481
</li>
1482
<li>
1483
<p>
1484
Make sure that the setgid bit is set on all directories in the cache. This
1485
tells the filesystem to inherit group ownership for new directories. The
1486
command “find $CCACHE_DIR -type d | xargs chmod g+s” might be useful for
1487
this.
1488
</p>
1489
</li>
1490
</ul></div>
1491
<div class="paragraph"><p>The reason to avoid the hard link mode is that the hard links cause unwanted
1492
side effects, as all links to a cached file share the file’s modification
1493
timestamp. This results in false dependencies to be triggered by
1494
timestamp-based build systems whenever another user links to an existing file.
1495
Typically, users will see that their libraries and binaries are relinked
1496
without reason.</p></div>
1497
<div class="paragraph"><p>You may also want to make sure that the developers have <strong>CCACHE_BASEDIR</strong> set
1498
appropriately, as discussed in the previous section.</p></div>
1499
</div>
1500
<h2 id="_sharing_a_cache_on_nfs">Sharing a cache on NFS</h2>
1501
<div class="sectionbody">
1502
<div class="paragraph"><p>It is possible to put the cache directory on an NFS filesystem (or similar
1503
filesystems), but keep in mind that:</p></div>
1504
<div class="ulist"><ul>
1505
<li>
1506
<p>
1507
Having the cache on NFS may slow down compilation. Make sure to do some
1508
benchmarking to see if it’s worth it.
1509
</p>
1510
</li>
1511
<li>
1512
<p>
1513
ccache hasn’t been tested very thoroughly on NFS.
1514
</p>
1515
</li>
1516
</ul></div>
1517
<div class="paragraph"><p>A tip is to set <strong>CCACHE_TEMPDIR</strong> to a directory on the local host to avoid NFS
1518
traffic for temporary files.</p></div>
1519
</div>
1520
<h2 id="_using_ccache_with_other_compiler_wrappers">Using ccache with other compiler wrappers</h2>
1521
<div class="sectionbody">
1522
<div class="paragraph"><p>The recommended way of combining ccache with another compiler wrapper (such as
1523
“distcc”) is by using the <strong>CCACHE_PREFIX</strong> option. You just need to set the
1524
environment variable <strong>CCACHE_PREFIX</strong> to the name of the wrapper (e.g. <strong>distcc</strong>)
1525
and ccache will prefix the command line with the specified command when running
1526
the compiler.</p></div>
1527
<div class="paragraph"><p>Unless you set <strong>CCACHE_COMPILERCHECK</strong> to a suitable command (see the
1528
description of that configuration option), it is not recommended to use the
1529
form <strong>ccache anotherwrapper compiler args</strong> as the compilation command. It’s
1530
also not recommended to use the masquerading technique for the other compiler
1531
wrapper. The reason is that by default, ccache will in both cases hash the
1532
mtime and size of the other wrapper instead of the real compiler, which means
1533
that:</p></div>
1534
<div class="ulist"><ul>
1535
<li>
1536
<p>
1537
Compiler upgrades will not be detected properly.
1538
</p>
1539
</li>
1540
<li>
1541
<p>
1542
The cached results will not be shared between compilations with and without
1543
the other wrapper.
1544
</p>
1545
</li>
1546
</ul></div>
1547
<div class="paragraph"><p>Another minor thing is that if <strong>CCACHE_PREFIX</strong> is not used, ccache will
1548
needlessly invoke the other wrapper when running the preprocessor.</p></div>
1549
</div>
1550
<h2 id="_bugs">Bugs</h2>
1551
<div class="sectionbody">
1552
<div class="ulist"><ul>
1553
<li>
1554
<p>
1555
ccache doesn’t handle the GNU Assembler’s <strong>.incbin</strong> directive correctly. This
1556
directive can be embedded in the source code inside an <strong><em>asm</em></strong> statement in
1557
order to include a file verbatim in the object file. If the included file is
1558
modified, ccache doesn’t pick up the change since the inclusion isn’t done by
1559
the preprocessor. A workaround of this problem is to set <strong>CCACHE_EXTRAFILES</strong>
1560
to the path of the included file.
1561
</p>
1562
</li>
1563
</ul></div>
1564
</div>
1565
<h2 id="_troubleshooting">Troubleshooting</h2>
1566
<div class="sectionbody">
1567
<h3 id="_general">General</h3><div style="clear:left"></div>
1568
<div class="paragraph"><p>A general tip for getting information about what ccache is doing is to enable
1569
debug logging by setting <strong>CCACHE_LOGFILE</strong>. The log contains executed commands,
1570
important decisions that ccache makes, read and written files, etc. Another way
1571
of keeping track of what is happening is to check the output of <strong>ccache -s</strong>.</p></div>
1572
<h3 id="_performance">Performance</h3><div style="clear:left"></div>
1573
<div class="paragraph"><p>ccache has been written to perform well out of the box, but sometimes you may
1574
have to do some adjustments of how you use the compiler and ccache in order to
1575
improve performance.</p></div>
1576
<div class="paragraph"><p>Since ccache works best when I/O is fast, put the cache directory on a fast
1577
storage device if possible. Having lots of free memory so that files in the
1578
cache directory stay in the disk cache is also preferrable.</p></div>
1579
<div class="paragraph"><p>A good way of monitoring how well ccache works is to run <strong>ccache -s</strong> before and
1580
after your build and then compare the statistics counters. Here are some common
1581
problems and what may be done to increase the hit rate:</p></div>
1582
<div class="ulist"><ul>
1583
<li>
1584
<p>
1585
If “cache hit (preprocessed)” has been incremented instead of “cache hit
1586
(direct)”, ccache has fallen back to preprocessor mode, which is generally
1587
slower. Some possible reasons are:
1588
</p>
1589
<div class="ulist"><ul>
1590
<li>
1591
<p>
1592
The source code has been modified in such a way that the preprocessor output
1593
is not affected.
1594
</p>
1595
</li>
1596
<li>
1597
<p>
1598
Compiler arguments that are hashed in the direct mode but not in the
1599
preprocessor mode have changed (<strong>-I</strong>, <strong>-include</strong>, <strong>-D</strong>, etc) and they didn’t
1600
affect the preprocessor output.
1601
</p>
1602
</li>
1603
<li>
1604
<p>
1605
The compiler option <strong>-Xpreprocessor</strong> or <strong>-Wp,<em>X</em></strong> (except <strong>-Wp,-MD,<em>path</em></strong>
1606
and <strong>Wp,-MMD,<em>path</em></strong>) is used.
1607
</p>
1608
</li>
1609
<li>
1610
<p>
1611
This was the first compilation with a new value of <strong>CCACHE_BASEDIR</strong>.
1612
</p>
1613
</li>
1614
<li>
1615
<p>
1616
A modification time of one of the include files is too new (created the same
1617
second as the compilation is being done). This check is made to avoid a race
1618
condition. To fix this, create the include file earlier in the build
1619
process, if possible, or set <strong>CCACHE_SLOPPINESS</strong> to <strong>include_file_mtime</strong> if
1620
you are willing to take the risk. (The race condition consists of these
1621
events: the preprocessor is run; an include file is modified by someone; the
1622
new include file is hashed by ccache; the real compiler is run on the
1623
preprocessor’s output, which contains data from the old header file; the
1624
wrong object file is stored in the cache.)
1625
</p>
1626
</li>
1627
<li>
1628
<p>
1629
The <strong>__TIME__</strong> preprocessor macro is (potentially) being used. ccache
1630
turns off direct mode if “__TIME__” is present in the source code
1631
outside comments and string literals. This is done as a safety measure since
1632
the string indicates that a <strong>__TIME__</strong> macro <em>may</em> affect the output. (To
1633
be sure, ccache would have to run the preprocessor, but the sole point of
1634
the direct mode is to avoid that.) If you know that <strong>__TIME__</strong> isn’t used
1635
in practise, or don’t care if ccache produces objects where <strong>__TIME__</strong> is
1636
expanded to something in the past, you can set <strong>CCACHE_SLOPPINESS</strong> to
1637
<strong>time_macros</strong>.
1638
</p>
1639
</li>
1640
<li>
1641
<p>
1642
The <strong>__DATE__</strong> preprocessor macro is (potentially) being used and the
1643
date has changed. This is similar to how <strong>__TIME__</strong> is handled. If
1644
“__DATE__” is present in the source code outside comments and string
1645
literals, ccache hashes the current date in order to be able to produce the
1646
correct object file if the <strong>__DATE__</strong> macro affects the output. If you
1647
know that <strong>__DATE__</strong> isn’t used in practise, or don’t care if ccache
1648
produces objects where <strong>__DATE__</strong> is expanded to something in the past,
1649
you can set <strong>CCACHE_SLOPPINESS</strong> to <strong>time_macros</strong>.
1650
</p>
1651
</li>
1652
<li>
1653
<p>
1654
The <strong>__FILE__</strong> preprocessor macro is (potentially) being used and the
1655
file path has changed. If “__FILE__” is present in the source code
1656
outside comments and string literals, ccache hashes the current input file
1657
path in order to be able to produce the correct object file if the
1658
<strong>__FILE__</strong> macro affects the output. If you know that <strong>__FILE__</strong> isn’t
1659
used in practise, or don’t care if ccache produces objects where
1660
<strong>__FILE__</strong> is expanded to the wrong path, you can set <strong>CCACHE_SLOPPINESS</strong>
1661
to <strong>file_macro</strong>.
1662
</p>
1663
</li>
1664
</ul></div>
1665
</li>
1666
<li>
1667
<p>
1668
If “cache miss” has been incremented even though the same code has been
1669
compiled and cached before, ccache has either detected that something has
1670
changed anyway or a cleanup has been performed (either explicitly or
1671
implicitly when a cache limit has been reached). Some perhaps unobvious
1672
things that may result in a cache miss are usage of <strong>__TIME__</strong> or
1673
<strong>__DATE__</strong> macros, or use of automatically generated code that contains a
1674
timestamp, build counter or other volatile information.
1675
</p>
1676
</li>
1677
<li>
1678
<p>
1679
If “multiple source files” has been incremented, it’s an indication that
1680
the compiler has been invoked on several source code files at once. ccache
1681
doesn’t support that. Compile the source code files separately if possible.
1682
</p>
1683
</li>
1684
<li>
1685
<p>
1686
If “unsupported compiler option” has been incremented, enable debug logging
1687
and check which option was rejected.
1688
</p>
1689
</li>
1690
<li>
1691
<p>
1692
If “preprocessor error” has been incremented, one possible reason is that
1693
precompiled headers are being used. See <a href="#_precompiled_headers">PRECOMPILED HEADERS</a> for how to remedy this.
1694
</p>
1695
</li>
1696
<li>
1697
<p>
1698
If “can’t use precompiled header” has been incremented, see
1699
<a href="#_precompiled_headers">PRECOMPILED HEADERS</a>.
1700
</p>
1701
</li>
1702
</ul></div>
1703
<h3 id="_errors_when_compiling_with_ccache">Errors when compiling with ccache</h3><div style="clear:left"></div>
1704
<div class="paragraph"><p>If compilation doesn’t work with ccache, but it works without it, one possible
1705
reason is that the compiler can’t compile preprocessed output correctly. A
1706
workaround that may work is to set <strong>CCACHE_CPP2</strong>. This will make cache misses
1707
slower, though, so it is better to find and fix the root cause.</p></div>
1708
<h3 id="_corrupt_object_files">Corrupt object files</h3><div style="clear:left"></div>
1709
<div class="paragraph"><p>It should be noted that ccache is susceptible to general storage problems. If a
1710
bad object file sneaks into the cache for some reason, it will of course stay
1711
bad. Some possible reasons for erroneous object files are bad hardware (disk
1712
drive, disk controller, memory, etc), buggy drivers or file systems, a bad
1713
<strong>CCACHE_PREFIX</strong> command or compiler wrapper. If this happens, you can either
1714
find out which object file is broken by reading the debug log and then delete
1715
the bad object file from the cache, or you can simply clear the whole cache
1716
with <strong>ccache -C</strong> if you don’t mind losing other cached results.</p></div>
1717
<div class="paragraph"><p>There are no reported issues about ccache producing broken object files
1718
reproducibly. That doesn’t mean it can’t happen, so if you find a repeatable
1719
case, please report it.</p></div>
1720
</div>
1721
<h2 id="_more_information">More information</h2>
1722
<div class="sectionbody">
1723
<div class="paragraph"><p>Credits, mailing list information, bug reporting instructions, source code,
1724
etc, can be found on ccache’s web site: <a href="http://ccache.samba.org">http://ccache.samba.org</a>.</p></div>
1725
</div>
1726
<h2 id="_author">Author</h2>
1727
<div class="sectionbody">
1728
<div class="paragraph"><p>ccache was originally written by Andrew Tridgell and is currently developed and
1729
maintained by Joel Rosdahl. See AUTHORS.txt or AUTHORS.html and
1730
<a href="http://ccache.samba.org/credits.html">http://ccache.samba.org/credits.html</a> for a list of contributors.</p></div>
1731
</div>
1732
</div>
1733
<div id="footnotes"><hr /></div>
1734
<div id="footer">
1735
<div id="footer-text">
1736
Version 3.1.3<br />
1737
Last updated 2010-11-14 11:05:10 CEST
1738
</div>
1739
</div>
1740
</body>
1741
</html>
Loggerhead is a web-based interface for Breezy
Version: 2.0.1