1 '\" t
2 .\" Title: ccache
3 .\" Author: [see the "AUTHOR(S)" section]
4 .\" Generator: Asciidoctor 2.0.16
5 .\" Date: 2021-09-11
6 .\" Manual: \ \&
7 .\" Source: Ccache 4.4.1
8 .\" Language: English
9 .\"
10 .TH "CCACHE" "1" "2021-09-11" "Ccache 4.4.1" "\ \&"
11 .ie \n(.g .ds Aq \(aq
12 .el .ds Aq '
13 .ss \n[.ss] 0
14 .nh
15 .ad l
16 .de URL
17 \fI\\$2\fP <\\$1>\\$3
18 ..
19 .als MTO URL
20 .if \n[.g] \{\
21 . mso www.tmac
22 . am URL
23 . ad l
24 . .
25 . am MTO
26 . ad l
27 . .
28 . LINKSTYLE blue R < >
29 .\}
30 .SH "NAME"
31 ccache \- a fast C/C++ compiler cache
32 .SH "SYNOPSIS"
33 .sp
34 .nf
35 \fBccache\fP [\fIoptions\fP]
36 \fBccache\fP \fIcompiler\fP [\fIcompiler options\fP]
37 \fIcompiler\fP [\fIcompiler options\fP] (via symbolic link)
38 .fi
39 .br
40 .SH "DESCRIPTION"
41 .sp
42 Ccache is a compiler cache. It speeds up recompilation by caching the result of
43 previous compilations and detecting when the same compilation is being done
44 again.
45 .sp
46 Ccache has been carefully written to always produce exactly the same compiler
47 output that you would get without the cache. The only way you should be able to
48 tell that you are using ccache is the speed. Currently known exceptions to this
49 goal are listed under \fICAVEATS\fP. If you discover an undocumented case where
50 ccache changes the output of your compiler, please let us know.
51 .SH "RUN MODES"
52 .sp
53 There are two ways to use ccache. You can either prefix your compilation
54 commands with \fBccache\fP or you can let ccache masquerade as the compiler by
55 creating a symbolic link (named as the compiler) to ccache. The first method is
56 most convenient if you just want to try out ccache or wish to use it for some
57 specific projects. The second method is most useful for when you wish to use
58 ccache for all your compilations.
59 .sp
60 To use the first method, just make sure that \fBccache\fP is in your \fBPATH\fP.
61 .sp
62 To use the symlinks method, do something like this:
63 .sp
64 .if n .RS 4
65 .nf
66 .fam C
67 cp ccache /usr/local/bin/
68 ln \-s ccache /usr/local/bin/gcc
69 ln \-s ccache /usr/local/bin/g++
70 ln \-s ccache /usr/local/bin/cc
71 ln \-s ccache /usr/local/bin/c++
72 .fam
73 .fi
74 .if n .RE
75 .sp
76 And so forth. This will work as long as the directory with symlinks comes
77 before the path to the compiler (which is usually in \fB/usr/bin\fP). After
78 installing you may wish to run \(lqwhich gcc\(rq to make sure that the correct link
79 is being used.
80 .if n .sp
81 .RS 4
82 .it 1 an-trap
83 .nr an-no-space-flag 1
84 .nr an-break-flag 1
85 .br
86 .ps +1
87 .B Warning
88 .ps -1
89 .br
90 .sp
91 The technique of letting ccache masquerade as the compiler works well,
92 but currently doesn\(cqt interact well with other tools that do the same thing. See
93 \fIUSING CCACHE WITH OTHER COMPILER WRAPPERS\fP.
94 .sp .5v
95 .RE
96 .if n .sp
97 .RS 4
98 .it 1 an-trap
99 .nr an-no-space-flag 1
100 .nr an-break-flag 1
101 .br
102 .ps +1
103 .B Warning
104 .ps -1
105 .br
106 .sp
107 Use a symbolic links for masquerading, not hard links.
108 .sp .5v
109 .RE
110 .SH "COMMAND LINE OPTIONS"
111 .sp
112 These command line options only apply when you invoke ccache as \(lqccache\(rq.
113 When invoked as a compiler (via a symlink as described in the previous
114 section), the normal compiler options apply and you should refer to the
115 compiler\(cqs documentation.
116 .SS "Common options"
117 .sp
118 \fB\-c\fP, \fB\-\-cleanup\fP
119 .RS 4
120 Clean up the cache by removing old cached files until the specified file
121 number and cache size limits are not exceeded. This also recalculates the
122 cache file count and size totals. Normally, there is no need to initiate
123 cleanup manually as ccache keeps the cache below the specified limits at
124 runtime and keeps statistics up to date on each compilation. Forcing a
125 cleanup is mostly useful if you manually modify the cache contents or
126 believe that the cache size statistics may be inaccurate.
127 .RE
128 .sp
129 \fB\-C\fP, \fB\-\-clear\fP
130 .RS 4
131 Clear the entire cache, removing all cached files, but keeping the
132 configuration file.
133 .RE
134 .sp
135 \fB\-\-config\-path\fP \fIPATH\fP
136 .RS 4
137 Let the command line options operate on configuration file \fIPATH\fP instead of
138 the default. Using this option has the same effect as setting the
139 environment variable \fBCCACHE_CONFIGPATH\fP temporarily.
140 .RE
141 .sp
142 \fB\-d\fP, \fB\-\-dir\fP \fIPATH\fP
143 .RS 4
144 Let the command line options operate on cache directory \fIPATH\fP instead of
145 the default. For example, to show statistics for a cache directory at
146 \fB/shared/ccache\fP you can run \fBccache \-d /shared/ccache \-s\fP. Using this option
147 has the same effect as setting the environment variable \fBCCACHE_DIR\fP
148 temporarily.
149 .RE
150 .sp
151 \fB\-\-evict\-older\-than\fP \fIAGE\fP
152 .RS 4
153 Remove files older than \fIAGE\fP from the cache. \fIAGE\fP should be an unsigned
154 integer with a \fBd\fP (days) or \fBs\fP (seconds) suffix.
155 .RE
156 .sp
157 \fB\-h\fP, \fB\-\-help\fP
158 .RS 4
159 Print a summary of command line options.
160 .RE
161 .sp
162 \fB\-F\fP \fINUM\fP, \fB\-\-max\-files\fP \fINUM\fP
163 .RS 4
164 Set the maximum number of files allowed in the cache to \fINUM\fP. Use 0 for no
165 limit. The value is stored in a configuration file in the cache directory
166 and applies to all future compilations.
167 .RE
168 .sp
169 \fB\-M\fP \fISIZE\fP, \fB\-\-max\-size\fP \fISIZE\fP
170 .RS 4
171 Set the maximum size of the files stored in the cache. \fISIZE\fP should be a
172 number followed by an optional suffix: k, M, G, T (decimal), Ki, Mi, Gi or
173 Ti (binary). The default suffix is G. Use 0 for no limit. The value is
174 stored in a configuration file in the cache directory and applies to all
175 future compilations.
176 .RE
177 .sp
178 \fB\-X\fP \fILEVEL\fP, \fB\-\-recompress\fP \fILEVEL\fP
179 .RS 4
180 Recompress the cache to level \fILEVEL\fP using the Zstandard algorithm. The
181 level can be an integer, with the same semantics as the
182 \fBcompression_level\fP configuration option), or
183 the special value \fBuncompressed\fP for no compression. See
184 \fICACHE COMPRESSION\fP for more information. This can potentionally take a
185 long time since all files in the cache need to be visited. Only files that
186 are currently compressed with a different level than \fILEVEL\fP will be
187 recompressed.
188 .RE
189 .sp
190 \fB\-o\fP \fIKEY=VALUE\fP, \fB\-\-set\-config\fP \fIKEY\fP=\fIVALUE\fP
191 .RS 4
192 Set configuration option \fIKEY\fP to \fIVALUE\fP. See \fICONFIGURATION\fP for more
193 information.
194 .RE
195 .sp
196 \fB\-x\fP, \fB\-\-show\-compression\fP
197 .RS 4
198 Print cache compression statistics. See \fICACHE COMPRESSION\fP for more
199 information. This can potentionally take a long time since all files in the
200 cache need to be visited.
201 .RE
202 .sp
203 \fB\-p\fP, \fB\-\-show\-config\fP
204 .RS 4
205 Print current configuration options and from where they originate
206 (environment variable, configuration file or compile\-time default) in
207 human\-readable format.
208 .RE
209 .sp
210 \fB\-\-show\-log\-stats\fP
211 .RS 4
212 Print statistics counters from the stats log in human\-readable format. See
213 \fBstats_log\fP. Use \fB\-v\fP/\fB\-\-verbose\fP once or twice for
214 more details.
215 .RE
216 .sp
217 \fB\-s\fP, \fB\-\-show\-stats\fP
218 .RS 4
219 Print a summary of configuration and statistics counters in human\-readable
220 format. Use \fB\-v\fP/\fB\-\-verbose\fP once or twice for more details.
221 .RE
222 .sp
223 \fB\-v\fP, \fB\-\-verbose\fP
224 .RS 4
225 Increase verbosity. The option can be given multiple times.
226 .RE
227 .sp
228 \fB\-V\fP, \fB\-\-version\fP
229 .RS 4
230 Print version and copyright information.
231 .RE
232 .sp
233 \fB\-z\fP, \fB\-\-zero\-stats\fP
234 .RS 4
235 Zero the cache statistics (but not the configuration options).
236 .RE
237 .SS "Options for secondary storage"
238 .sp
239 \fB\-\-trim\-dir\fP \fIPATH\fP
240 .RS 4
241 Remove old files from directory \fIPATH\fP until it is at most the size specified
242 by \fB\-\-trim\-max\-size\fP.
243 .if n .sp
244 .RS 4
245 .it 1 an-trap
246 .nr an-no-space-flag 1
247 .nr an-break-flag 1
248 .br
249 .ps +1
250 .B Warning
251 .ps -1
252 .br
253 .sp
254 Don\(cqt use this option to trim the primary cache. To trim the primary
255 cache directory to a certain size, use \fBCCACHE_MAXSIZE=\fISIZE\fP ccache \-c\fP.
256 .sp .5v
257 .RE
258 .RE
259 .sp
260 \fB\-\-trim\-max\-size\fP \fISIZE\fP
261 .RS 4
262 Specify the maximum size for \fB\-\-trim\-dir\fP. \fISIZE\fP should be a number followed
263 by an optional suffix: k, M, G, T (decimal), Ki, Mi, Gi or Ti (binary). The
264 default suffix is G.
265 .RE
266 .sp
267 \fB\-\-trim\-method\fP \fIMETHOD\fP
268 .RS 4
269 Specify the method to trim a directory with \fB\-\-trim\-dir\fP. Possible values
270 are:
271 .sp
272 \fBatime\fP
273 .RS 4
274 LRU (least recently used) using the file access timestamp. This is the
275 default.
276 .RE
277 .sp
278 \fBmtime\fP
279 .RS 4
280 LRU (least recently used) using the file modification timestamp.
281 .RE
282 .RE
283 .SS "Options for scripting or debugging"
284 .sp
285 \fB\-\-checksum\-file\fP \fIPATH\fP
286 .RS 4
287 Print the checksum (64 bit XXH3) of the file at \fIPATH\fP (\fB\-\fP for standard
288 input).
289 .RE
290 .sp
291 \fB\-\-dump\-manifest\fP \fIPATH\fP
292 .RS 4
293 Dump manifest file at \fIPATH\fP (\fB\-\fP for standard input) in text format to
294 standard output. This is only useful when debugging ccache and its behavior.
295 .RE
296 .sp
297 \fB\-\-dump\-result\fP \fIPATH\fP
298 .RS 4
299 Dump result file at \fIPATH\fP (\fB\-\fP for standard input) in text format to
300 standard output. This is only useful when debugging ccache and its behavior.
301 .RE
302 .sp
303 \fB\-\-extract\-result\fP \fIPATH\fP
304 .RS 4
305 Extract data stored in the result file at \fIPATH\fP (\fB\-\fP for standard input).
306 The data will be written to \fBccache\-result.*\fP files in to the current
307 working directory. This is only useful when debugging ccache and its
308 behavior.
309 .RE
310 .sp
311 \fB\-k\fP \fIKEY\fP, \fB\-\-get\-config\fP \fIKEY\fP
312 .RS 4
313 Print the value of configuration option \fIKEY\fP. See \fICONFIGURATION\fP for
314 more information.
315 .RE
316 .sp
317 \fB\-\-hash\-file\fP \fIPATH\fP
318 .RS 4
319 Print the hash (160 bit BLAKE3) of the file at \fIPATH\fP (\fB\-\fP for standard
320 input). This is only useful when debugging ccache and its behavior.
321 .RE
322 .sp
323 \fB\-\-print\-stats\fP
324 .RS 4
325 Print statistics counter IDs and corresponding values in machine\-parsable
326 (tab\-separated) format.
327 .RE
328 .SS "Extra options"
329 .sp
330 When run as a compiler, ccache usually just takes the same command line options
331 as the compiler you are using. The only exception to this is the option
332 \fB\-\-ccache\-skip\fP. That option can be used to tell ccache to avoid interpreting
333 the next option in any way and to pass it along to the compiler as\-is.
334 .if n .sp
335 .RS 4
336 .it 1 an-trap
337 .nr an-no-space-flag 1
338 .nr an-break-flag 1
339 .br
340 .ps +1
341 .B Note
342 .ps -1
343 .br
344 .sp
345 \fB\-\-ccache\-skip\fP currently only tells ccache not to interpret the next
346 option as a special compiler option \(em the option will still be included in the
347 direct mode hash.
348 .sp .5v
349 .RE
350 .sp
351 The reason this can be important is that ccache does need to parse the command
352 line and determine what is an input filename and what is a compiler option, as
353 it needs the input filename to determine the name of the resulting object file
354 (among other things). The heuristic ccache uses when parsing the command line
355 is that any argument that exists as a file is treated as an input file name. By
356 using \fB\-\-ccache\-skip\fP you can force an option to not be treated as an input
357 file name and instead be passed along to the compiler as a command line option.
358 .sp
359 Another case where \fB\-\-ccache\-skip\fP can be useful is if ccache interprets an
360 option specially but shouldn\(cqt, since the option has another meaning for your
361 compiler than what ccache thinks.
362 .SH "CONFIGURATION"
363 .sp
364 Ccache\(cqs default behavior can be overridden by options in configuration files,
365 which in turn can be overridden by environment variables with names starting
366 with \fBCCACHE_\fP. Ccache normally reads configuration from two files: first a
367 system\-level configuration file and secondly a cache\-specific configuration
368 file. The priorities of configuration options are as follows (where 1 is
369 highest):
370 .sp
371 .RS 4
372 .ie n \{\
373 \h'-04' 1.\h'+01'\c
374 .\}
375 .el \{\
376 . sp -1
377 . IP " 1." 4.2
378 .\}
379 Environment variables.
380 .RE
381 .sp
382 .RS 4
383 .ie n \{\
384 \h'-04' 2.\h'+01'\c
385 .\}
386 .el \{\
387 . sp -1
388 . IP " 2." 4.2
389 .\}
390 The primary (cache\-specific) configuration file (see below).
391 .RE
392 .sp
393 .RS 4
394 .ie n \{\
395 \h'-04' 3.\h'+01'\c
396 .\}
397 .el \{\
398 . sp -1
399 . IP " 3." 4.2
400 .\}
401 The secondary (system\-wide read\-only) configuration file
402 \fB<sysconfdir>/ccache.conf\fP (typically \fB/etc/ccache.conf\fP or
403 \fB/usr/local/etc/ccache.conf\fP).
404 .RE
405 .sp
406 .RS 4
407 .ie n \{\
408 \h'-04' 4.\h'+01'\c
409 .\}
410 .el \{\
411 . sp -1
412 . IP " 4." 4.2
413 .\}
414 Compile\-time defaults.
415 .RE
416 .sp
417 As a special case, if the the environment variable \fBCCACHE_CONFIGPATH\fP is set
418 it specifies the primary configuration file and the secondary (system\-wide)
419 configuration file won\(cqt be read.
420 .SS "Location of the primary configuration file"
421 .sp
422 The location of the primary (cache\-specific) configuration is determined like
423 this:
424 .sp
425 .RS 4
426 .ie n \{\
427 \h'-04' 1.\h'+01'\c
428 .\}
429 .el \{\
430 . sp -1
431 . IP " 1." 4.2
432 .\}
433 If \fBCCACHE_CONFIGPATH\fP is set, use that path.
434 .RE
435 .sp
436 .RS 4
437 .ie n \{\
438 \h'-04' 2.\h'+01'\c
439 .\}
440 .el \{\
441 . sp -1
442 . IP " 2." 4.2
443 .\}
444 Otherwise, if the environment variable \fBCCACHE_DIR\fP is set then use
445 \fB$CCACHE_DIR/ccache.conf\fP.
446 .RE
447 .sp
448 .RS 4
449 .ie n \{\
450 \h'-04' 3.\h'+01'\c
451 .\}
452 .el \{\
453 . sp -1
454 . IP " 3." 4.2
455 .\}
456 Otherwise, if \fBcache_dir\fP is set in the secondary
457 (system\-wide) configuration file then use \fB<cache_dir>/ccache.conf\fP.
458 .RE
459 .sp
460 .RS 4
461 .ie n \{\
462 \h'-04' 4.\h'+01'\c
463 .\}
464 .el \{\
465 . sp -1
466 . IP " 4." 4.2
467 .\}
468 Otherwise, if there is a legacy \fB$HOME/.ccache\fP directory then use
469 \fB$HOME/.ccache/ccache.conf\fP.
470 .RE
471 .sp
472 .RS 4
473 .ie n \{\
474 \h'-04' 5.\h'+01'\c
475 .\}
476 .el \{\
477 . sp -1
478 . IP " 5." 4.2
479 .\}
480 Otherwise, if \fBXDG_CONFIG_HOME\fP is set then use
481 \fB$XDG_CONFIG_HOME/ccache/ccache.conf\fP.
482 .RE
483 .sp
484 .RS 4
485 .ie n \{\
486 \h'-04' 6.\h'+01'\c
487 .\}
488 .el \{\
489 . sp -1
490 . IP " 6." 4.2
491 .\}
492 Otherwise, use \fB%APPDATA%/ccache/ccache.conf\fP (Windows),
493 \fB$HOME/Library/Preferences/ccache/ccache.conf\fP (macOS) or
494 \fB$HOME/.config/ccache/ccache.conf\fP (other systems).
495 .RE
496 .SS "Configuration file syntax"
497 .sp
498 Configuration files are in a simple \(lqkey = value\(rq format, one option per
499 line. Lines starting with a hash sign are comments. Blank lines are ignored, as
500 is whitespace surrounding keys and values. Example:
501 .sp
502 .if n .RS 4
503 .nf
504 .fam C
505 # Set maximum cache size to 10 GB:
506 max_size = 10G
507 .fam
508 .fi
509 .if n .RE
510 .SS "Boolean values"
511 .sp
512 Some configuration options are boolean values (i.e. truth values). In a
513 configuration file, such values must be set to the string \fBtrue\fP or \fBfalse\fP.
514 For the corresponding environment variables, the semantics are a bit different:
515 .sp
516 .RS 4
517 .ie n \{\
518 \h'-04'\(bu\h'+03'\c
519 .\}
520 .el \{\
521 . sp -1
522 . IP \(bu 2.3
523 .\}
524 A set environment variable means \(lqtrue\(rq (even if set to the empty string).
525 .RE
526 .sp
527 .RS 4
528 .ie n \{\
529 \h'-04'\(bu\h'+03'\c
530 .\}
531 .el \{\
532 . sp -1
533 . IP \(bu 2.3
534 .\}
535 The following case\-insensitive negative values are considered an error
536 (instead of surprising the user): \fB0\fP, \fBfalse\fP, \fBdisable\fP and \fBno\fP.
537 .RE
538 .sp
539 .RS 4
540 .ie n \{\
541 \h'-04'\(bu\h'+03'\c
542 .\}
543 .el \{\
544 . sp -1
545 . IP \(bu 2.3
546 .\}
547 An unset environment variable means \(lqfalse\(rq.
548 .RE
549 .sp
550 Each boolean environment variable also has a negated form starting with
551 \fBCCACHE_NO\fP. For example, \fBCCACHE_COMPRESS\fP can be set to force compression and
552 \fBCCACHE_NOCOMPRESS\fP can be set to force no compression.
553 .SS "Configuration options"
554 .sp
555 Below is a list of available configuration options. The corresponding
556 environment variable name is indicated in parentheses after each configuration
557 option key.
558 .sp
559 \fBabsolute_paths_in_stderr\fP (\fBCCACHE_ABSSTDERR\fP)
560 .RS 4
561 This option specifies whether ccache should rewrite relative paths in the
562 compiler\(cqs standard error output to absolute paths. This can be useful if
563 you use \fBbase_dir\fP with a build system (e.g. CMake with
564 the "Unix Makefiles" generator) that executes the compiler in a different
565 working directory, which makes relative paths in compiler errors or
566 warnings incorrect. The default is false.
567 .RE
568 .sp
569 \fBbase_dir\fP (\fBCCACHE_BASEDIR\fP)
570 .RS 4
571 This option should be an absolute path to a directory. If set, ccache will
572 rewrite absolute paths into paths relative to the current working directory,
573 but only absolute paths that begin with \fBbase_dir\fP. Cache results can then
574 be shared for compilations in different directories even if the project uses
575 absolute paths in the compiler command line. See also the discussion under
576 \fICOMPILING IN DIFFERENT DIRECTORIES\fP. If set to the empty string (which
577 is the default), no rewriting is done.
578 .sp
579 A typical path to use as \fBbase_dir\fP is your home directory or another directory
580 that is a parent of your project directories. Don\(cqt use \fB/\fP as the base
581 directory since that will make ccache also rewrite paths to system header
582 files, which typically is contraproductive.
583 .sp
584 For example, say that Alice\(cqs current working directory is
585 \fB/home/alice/project1/build\fP and that she compiles like this:
586 .sp
587 .if n .RS 4
588 .nf
589 .fam C
590 ccache gcc \-I/usr/include/example \-I/home/alice/project2/include \-c /home/alice/project1/src/example.c
591 .fam
592 .fi
593 .if n .RE
594 .sp
595 Here is what ccache will actually execute for different \fBbase_dir\fP values:
596 .sp
597 .if n .RS 4
598 .nf
599 .fam C
600 # Current working directory: /home/alice/project1/build
601
602 # With base_dir = /:
603 gcc \-I../../../../usr/include/example \-I../../project2/include \-c ../src/example.c
604
605 # With base_dir = /home or /home/alice:
606 gcc \-I/usr/include/example \-I../../project2/include \-c ../src/example.c
607
608 # With base_dir = /home/alice/project1 or /home/alice/project1/src:
609 gcc \-I/usr/include/example \-I/home/alice/project2/include \-c ../src/example.c
610 .fam
611 .fi
612 .if n .RE
613 .sp
614 If Bob has put \fBproject1\fP and \fBproject2\fP in \fB/home/bob/stuff\fP and both users
615 have set \fBbase_dir\fP to \fB/home\fP or \fB/home/$USER\fP, then Bob will get a cache hit
616 (if they share ccache directory) since the actual command line will be
617 identical to that of Alice:
618 .sp
619 .if n .RS 4
620 .nf
621 .fam C
622 # Current working directory: /home/bob/stuff/project1/build
623
624 # With base_dir = /home or /home/bob:
625 gcc \-I/usr/include/example \-I../../project2/include \-c ../src/example.c
626 .fam
627 .fi
628 .if n .RE
629 .sp
630 Without \fBbase_dir\fP there will be a cache miss since the absolute paths will
631 differ. With \fBbase_dir\fP set to \fB/\fP there will be a cache miss since the
632 relative path to \fB/usr/include/example\fP will be different. With \fBbase_dir\fP set
633 to \fB/home/bob/stuff/project1\fP there will a cache miss since the path to
634 project2 will be a different absolute path.
635 .RE
636 .sp
637 \fBcache_dir\fP (\fBCCACHE_DIR\fP)
638 .RS 4
639 This option specifies where ccache will keep its cached compiler outputs.
640 The default is \fB$XDG_CACHE_HOME/ccache\fP if \fBXDG_CACHE_HOME\fP is set,
641 otherwise \fB$HOME/.cache/ccache\fP. Exception: If the legacy directory
642 \fB$HOME/.ccache\fP exists then that directory is the default.
643 .sp
644 See also \fILocation of the primary configuration file\fP.
645 .sp
646 If you want to use another \fBCCACHE_DIR\fP value temporarily for one ccache
647 invocation you can use the \fB\-d\fP/\fB\-\-dir\fP command line option instead.
648 .RE
649 .sp
650 \fBcompiler\fP (\fBCCACHE_COMPILER\fP or (deprecated) \fBCCACHE_CC\fP)
651 .RS 4
652 This option can be used to force the name of the compiler to use. If set to
653 the empty string (which is the default), ccache works it out from the
654 command line.
655 .RE
656 .sp
657 \fBcompiler_check\fP (\fBCCACHE_COMPILERCHECK\fP)
658 .RS 4
659 By default, ccache includes the modification time (\(lqmtime\(rq) and size of
660 the compiler in the hash to ensure that results retrieved from the cache
661 are accurate. This option can be used to select another strategy. Possible
662 values are:
663 .sp
664 \fBcontent\fP
665 .RS 4
666 Hash the content of the compiler binary. This makes ccache very slightly
667 slower compared to \fBmtime\fP, but makes it cope better with compiler upgrades
668 during a build bootstrapping process.
669 .RE
670 .sp
671 \fBmtime\fP
672 .RS 4
673 Hash the compiler\(cqs mtime and size, which is fast. This is the default.
674 .RE
675 .sp
676 \fBnone\fP
677 .RS 4
678 Don\(cqt hash anything. This may be good for situations where you can safely
679 use the cached results even though the compiler\(cqs mtime or size has changed
680 (e.g. if the compiler is built as part of your build system and the
681 compiler\(cqs source has not changed, or if the compiler only has changes that
682 don\(cqt affect code generation). You should only use \fBnone\fP if you know what
683 you are doing.
684 .RE
685 .sp
686 \fBstring:value\fP
687 .RS 4
688 Hash \fBvalue\fP. This can for instance be a compiler revision number or
689 another string that the build system generates to identify the compiler.
690 .RE
691 .sp
692 \fIa command string\fP
693 .RS 4
694 Hash the standard output and standard error output of the specified
695 command. The string will be split on whitespace to find out the command and
696 arguments to run. No other interpretation of the command string will be
697 done, except that the special word \fB%compiler%\fP will be replaced with the
698 path to the compiler. Several commands can be specified with semicolon as
699 separator. Examples:
700 .sp
701 .if n .RS 4
702 .nf
703 .fam C
704 %compiler% \-v
705 .fam
706 .fi
707 .if n .RE
708 .sp
709 .if n .RS 4
710 .nf
711 .fam C
712 %compiler% \-dumpmachine; %compiler% \-dumpversion
713 .fam
714 .fi
715 .if n .RE
716 .sp
717 You should make sure that the specified command is as fast as possible since it
718 will be run once for each ccache invocation.
719 .sp
720 Identifying the compiler using a command is useful if you want to avoid cache
721 misses when the compiler has been rebuilt but not changed.
722 .sp
723 Another case is when the compiler (as seen by ccache) actually isn\(cqt the real
724 compiler but another compiler wrapper \(em in that case, the default \fBmtime\fP
725 method will hash the mtime and size of the other compiler wrapper, which means
726 that ccache won\(cqt be able to detect a compiler upgrade. Using a suitable command
727 to identify the compiler is thus safer, but it\(cqs also slower, so you should
728 consider continue using the \fBmtime\fP method in combination with the
729 \fBprefix_command\fP option if possible. See
730 \fIUSING CCACHE WITH OTHER COMPILER WRAPPERS\fP.
731 .RE
732 .RE
733 .sp
734 \fBcompiler_type\fP (\fBCCACHE_COMPILERTYPE\fP)
735 .RS 4
736 Ccache normally guesses the compiler type based on the compiler name. The
737 \fBcompiler_type\fP option lets you force a compiler type. This can be useful
738 if the compiler has a non\-standard name but is actually one of the known
739 compiler types. Possible values are:
740 .sp
741 \fBauto\fP
742 .RS 4
743 Guess one of the types below based on the compiler name (following
744 symlinks). This is the default.
745 .RE
746 .sp
747 \fBclang\fP
748 .RS 4
749 Clang\-based compiler.
750 .RE
751 .sp
752 \fBgcc\fP
753 .RS 4
754 GCC\-based compiler.
755 .RE
756 .sp
757 \fBnvcc\fP
758 .RS 4
759 NVCC (CUDA) compiler.
760 .RE
761 .sp
762 \fBother\fP
763 .RS 4
764 Any compiler other than the known types.
765 .RE
766 .sp
767 \fBpump\fP
768 .RS 4
769 distcc\(cqs \(lqpump\(rq script.
770 .RE
771 .RE
772 .sp
773 \fBcompression\fP (\fBCCACHE_COMPRESS\fP or \fBCCACHE_NOCOMPRESS\fP, see \fIBoolean values\fP above)
774 .RS 4
775 If true, ccache will compress data it puts in the cache. However, this
776 option has no effect on how files are retrieved from the cache; compressed
777 and uncompressed results will still be usable regardless of this option.
778 The default is true.
779 .sp
780 Compression is done using the Zstandard algorithm. The algorithm is fast enough
781 that there should be little reason to turn off compression to gain performance.
782 One exception is if the cache is located on a compressed file system, in which
783 case the compression performed by ccache of course is redundant.
784 .sp
785 Compression will be disabled if file cloning (the
786 \fBfile_clone\fP option) or hard linking (the
787 \fBhard_link\fP option) is enabled.
788 .RE
789 .sp
790 \fBcompression_level\fP (\fBCCACHE_COMPRESSLEVEL\fP)
791 .RS 4
792 This option determines the level at which ccache will compress object files
793 using the real\-time compression algorithm Zstandard. It only has effect if
794 \fBcompression\fP is enabled (which it is by default).
795 Zstandard is extremely fast for decompression and very fast for compression
796 for lower compression levels. The default is 0.
797 .sp
798 Semantics of \fBcompression_level\fP:
799 .sp
800 \fB> 0\fP
801 .RS 4
802 A positive value corresponds to normal Zstandard compression levels. Lower
803 levels (e.g. \fB1\fP) mean faster compression but worse compression ratio.
804 Higher levels (e.g. \fB19\fP) mean slower compression but better compression
805 ratio. The maximum possible value depends on the libzstd version, but at
806 least up to 19 is available for all versions. Decompression speed is
807 essentially the same for all levels. As a rule of thumb, use level 5 or
808 lower since higher levels may slow down compilations noticeably. Higher
809 levels are however useful when recompressing the cache with command line
810 option \fB\-X\fP/\fB\-\-recompress\fP.
811 .RE
812 .sp
813 \fB< 0\fP
814 .RS 4
815 A negative value corresponds to Zstandard\(cqs \(lqultra\-fast\(rq compression
816 levels, which are even faster than level 1 but with less good compression
817 ratios. For instance, level \fB\-3\fP corresponds to \fB\-\-fast=3\fP for the \fBzstd\fP
818 command line tool. In practice, there is little use for levels lower than
819 \fB\-5\fP or so.
820 .RE
821 .sp
822 \fB0\fP (default)
823 .RS 4
824 The value \fB0\fP means that ccache will choose a suitable level, currently
825 \fB1\fP.
826 .RE
827 .sp
828 See the \c
829 .URL "http://zstd.net" "Zstandard documentation" ""
830 for more information.
831 .RE
832 .sp
833 \fBcpp_extension\fP (\fBCCACHE_EXTENSION\fP)
834 .RS 4
835 This option can be used to force a certain extension for the intermediate
836 preprocessed file. The default is to automatically determine the extension
837 to use for intermediate preprocessor files based on the type of file being
838 compiled, but that sometimes doesn\(cqt work. For example, when using the
839 \(lqaCC\(rq compiler on HP\-UX, set the cpp extension to \fBi\fP.
840 .RE
841 .sp
842 \fBdebug\fP (\fBCCACHE_DEBUG\fP or \fBCCACHE_NODEBUG\fP, see \fIBoolean values\fP above)
843 .RS 4
844 If true, enable the debug mode. The debug mode creates per\-object debug
845 files that are helpful when debugging unexpected cache misses. Note however
846 that ccache performance will be reduced slightly. See \fICACHE DEBUGGING\fP
847 for more information. The default is false.
848 .RE
849 .sp
850 \fBdebug_dir\fP (\fBCCACHE_DEBUGDIR\fP)
851 .RS 4
852 Specifies where to write per\-object debug files if the debug
853 mode is enabled. If set to the empty string, the files will be written
854 next to the object file. If set to a directory, the debug files will be
855 written with full absolute paths in that directory, creating it if needed.
856 The default is the empty string.
857 .sp
858 For example, if \fBdebug_dir\fP is set to \fB/example\fP, the current working directory
859 is \fB/home/user\fP and the object file is \fBbuild/output.o\fP then the debug log will
860 be written to \fB/example/home/user/build/output.o.ccache\-log\fP. See also
861 \fICACHE DEBUGGING\fP.
862 .RE
863 .sp
864 \fBdepend_mode\fP (\fBCCACHE_DEPEND\fP or \fBCCACHE_NODEPEND\fP, see \fIBoolean values\fP above)
865 .RS 4
866 If true, the depend mode will be used. The default is false. See
867 \fIThe depend mode\fP.
868 .RE
869 .sp
870 \fBdirect_mode\fP (\fBCCACHE_DIRECT\fP or \fBCCACHE_NODIRECT\fP, see \fIBoolean values\fP above)
871 .RS 4
872 If true, the direct mode will be used. The default is true. See
873 \fIThe direct mode\fP.
874 .RE
875 .sp
876 \fBdisable\fP (\fBCCACHE_DISABLE\fP or \fBCCACHE_NODISABLE\fP, see \fIBoolean values\fP above)
877 .RS 4
878 When true, ccache will just call the real compiler, bypassing the cache
879 completely. The default is false.
880 .RE
881 .sp
882 \fBextra_files_to_hash\fP (\fBCCACHE_EXTRAFILES\fP)
883 .RS 4
884 This option is a list of paths to files that ccache will include in the the
885 hash sum that identifies the build. The list separator is semicolon on
886 Windows systems and colon on other systems.
887 .RE
888 .sp
889 \fBfile_clone\fP (\fBCCACHE_FILECLONE\fP or \fBCCACHE_NOFILECLONE\fP, see \fIBoolean values\fP above)
890 .RS 4
891 If true, ccache will attempt to use file cloning (also known as \(lqcopy on
892 write\(rq, \(lqCoW\(rq or \(lqreflinks\(rq) to store and fetch cached compiler
893 results. \fBfile_clone\fP has priority over \fBhard_link\fP.
894 The default is false.
895 .sp
896 Files stored by cloning cannot be compressed, so the cache size will likely be
897 significantly larger if this option is enabled. However, performance may be
898 improved depending on the use case.
899 .sp
900 Unlike the \fBhard_link\fP option, \fBfile_clone\fP is completely
901 safe to use, but not all file systems support the feature. For such file
902 systems, ccache will fall back to use plain copying (or hard links if
903 \fBhard_link\fP is enabled).
904 .RE
905 .sp
906 \fBhard_link\fP (\fBCCACHE_HARDLINK\fP or \fBCCACHE_NOHARDLINK\fP, see \fIBoolean values\fP above)
907 .RS 4
908 If true, ccache will attempt to use hard links to store and fetch cached
909 object files. The default is false.
910 .sp
911 Files stored via hard links cannot be compressed, so the cache size will likely
912 be significantly larger if this option is enabled. However, performance may be
913 improved depending on the use case.
914 .if n .sp
915 .RS 4
916 .it 1 an-trap
917 .nr an-no-space-flag 1
918 .nr an-break-flag 1
919 .br
920 .ps +1
921 .B Warning
922 .ps -1
923 .br
924 .sp
925 Do not enable this option unless you are aware of these caveats:
926 .sp .5v
927 .RE
928 .sp
929 .RS 4
930 .ie n \{\
931 \h'-04'\(bu\h'+03'\c
932 .\}
933 .el \{\
934 . sp -1
935 . IP \(bu 2.3
936 .\}
937 If the resulting file is modified, the file in the cache will also be
938 modified since they share content, which corrupts the cache entry. As of
939 version 4.0, ccache makes stored and fetched object files read\-only as a
940 safety measure guard. Furthermore, a simple integrity check is made for
941 cached object files by verifying that their sizes are correct. This means
942 that mistakes like \fBstrip file.o\fP or \fBecho >file.o\fP will be detected even if
943 the object file is made writeable, but a modification that doesn\(cqt change the
944 file size will not.
945 .RE
946 .sp
947 .RS 4
948 .ie n \{\
949 \h'-04'\(bu\h'+03'\c
950 .\}
951 .el \{\
952 . sp -1
953 . IP \(bu 2.3
954 .\}
955 Programs that don\(cqt expect that files from two different identical
956 compilations are hard links to each other can fail.
957 .RE
958 .sp
959 .RS 4
960 .ie n \{\
961 \h'-04'\(bu\h'+03'\c
962 .\}
963 .el \{\
964 . sp -1
965 . IP \(bu 2.3
966 .\}
967 Programs that rely on modification times (like \fBmake\fP) can be confused if
968 several users (or one user with several build trees) use the same cache
969 directory. The reason for this is that the object files share i\-nodes and
970 therefore modification times. If \fBfile.o\fP is in build tree \fBA\fP (hard\-linked
971 from the cache) and \fBfile.o\fP then is produced by ccache in build tree \fBB\fP by
972 hard\-linking from the cache, the modification timestamp will be updated for
973 \fBfile.o\fP in build tree \fBA\fP as well. This can retrigger relinking in build tree
974 \fBA\fP even though nothing really has changed.
975 .RE
976 .RE
977 .sp
978 \fBhash_dir\fP (\fBCCACHE_HASHDIR\fP or \fBCCACHE_NOHASHDIR\fP, see \fIBoolean values\fP above)
979 .RS 4
980 If true (which is the default), ccache will include the current working
981 directory (CWD) in the hash that is used to distinguish two compilations
982 when generating debug info (compiler option \fB\-g\fP with variations).
983 Exception: The CWD will not be included in the hash if
984 \fBbase_dir\fP is set (and matches the CWD) and the
985 compiler option \fB\-fdebug\-prefix\-map\fP is used. See also the discussion under
986 \fICOMPILING IN DIFFERENT DIRECTORIES\fP.
987 .sp
988 The reason for including the CWD in the hash by default is to prevent a problem
989 with the storage of the current working directory in the debug info of an
990 object file, which can lead ccache to return a cached object file that has the
991 working directory in the debug info set incorrectly.
992 .sp
993 You can disable this option to get cache hits when compiling the same source
994 code in different directories if you don\(cqt mind that CWD in the debug info
995 might be incorrect.
996 .RE
997 .sp
998 \fBignore_headers_in_manifest\fP (\fBCCACHE_IGNOREHEADERS\fP)
999 .RS 4
1000 This option is a list of paths to files (or directories with headers) that
1001 ccache will \fBnot\fP include in the manifest list that makes up the direct
1002 mode. Note that this can cause stale cache hits if those headers do indeed
1003 change. The list separator is semicolon on Windows systems and colon on
1004 other systems.
1005 .RE
1006 .sp
1007 \fBignore_options\fP (\fBCCACHE_IGNOREOPTIONS\fP)
1008 .RS 4
1009 This option is a space\-delimited list of compiler options that ccache will
1010 exclude from the hash. Excluding a compiler option from the hash can be
1011 useful when you know it doesn\(cqt affect the result (but ccache doesn\(cqt know
1012 that), or when it does and you don\(cqt care. If a compiler option in the list
1013 is suffixed with an asterisk (\fB*\fP) it will be matched as a prefix. For
1014 example, \fB\-fmessage\-length=*\fP will match both \fB\-fmessage\-length=20\fP and
1015 \fB\-fmessage\-length=70\fP.
1016 .RE
1017 .sp
1018 \fBinode_cache\fP (\fBCCACHE_INODECACHE\fP or \fBCCACHE_NOINODECACHE\fP, see \fIBoolean values\fP above)
1019 .RS 4
1020 If true, enables caching of source file hashes based on device, inode and
1021 timestamps. This will reduce the time spent on hashing included files as
1022 the result can be resused between compilations.
1023 .sp
1024 The feature is still experimental and thus off by default. It is currently not
1025 available on Windows.
1026 .sp
1027 The feature requires \fBtemporary_dir\fP to be located on a local filesystem.
1028 .RE
1029 .sp
1030 \fBkeep_comments_cpp\fP (\fBCCACHE_COMMENTS\fP or \fBCCACHE_NOCOMMENTS\fP, see \fIBoolean values\fP above)
1031 .RS 4
1032 If true, ccache will not discard the comments before hashing preprocessor
1033 output. This can be used to check documentation with \fB\-Wdocumentation\fP.
1034 .RE
1035 .sp
1036 \fBlimit_multiple\fP (\fBCCACHE_LIMIT_MULTIPLE\fP)
1037 .RS 4
1038 Sets the limit when cleaning up. Files are deleted (in LRU order) until the
1039 levels are below the limit. The default is 0.8 (= 80%). See
1040 \fIAutomatic cleanup\fP for more information.
1041 .RE
1042 .sp
1043 \fBlog_file\fP (\fBCCACHE_LOGFILE\fP)
1044 .RS 4
1045 If set to a file path, ccache will write information on what it is doing to
1046 the specified file. This is useful for tracking down problems.
1047 .sp
1048 If set to \fBsyslog\fP, ccache will log using \fBsyslog()\fP instead of to a file. If
1049 you use rsyslogd, you can add something like this to \fB/etc/rsyslog.conf\fP or a
1050 file in \fB/etc/rsyslog.d\fP:
1051 .sp
1052 .if n .RS 4
1053 .nf
1054 .fam C
1055 # log ccache to file
1056 :programname, isequal, "ccache" /var/log/ccache
1057 # remove from syslog
1058 & ~
1059 .fam
1060 .fi
1061 .if n .RE
1062 .RE
1063 .sp
1064 \fBmax_files\fP (\fBCCACHE_MAXFILES\fP)
1065 .RS 4
1066 This option specifies the maximum number of files to keep in the cache. Use
1067 0 for no limit (which is the default). See also \fICACHE SIZE MANAGEMENT\fP.
1068 .RE
1069 .sp
1070 \fBmax_size\fP (\fBCCACHE_MAXSIZE\fP)
1071 .RS 4
1072 This option specifies the maximum size of the cache. Use 0 for no limit. The
1073 default value is 5G. Available suffixes: k, M, G, T (decimal) and Ki, Mi,
1074 Gi, Ti (binary). The default suffix is G. See also
1075 \fICACHE SIZE MANAGEMENT\fP.
1076 .RE
1077 .sp
1078 \fBpath\fP (\fBCCACHE_PATH\fP)
1079 .RS 4
1080 If set, ccache will search directories in this list when looking for the
1081 real compiler. The list separator is semicolon on Windows systems and colon
1082 on other systems. If not set, ccache will look for the first executable
1083 matching the compiler name in the normal \fBPATH\fP that isn\(cqt a symbolic link
1084 to ccache itself.
1085 .RE
1086 .sp
1087 \fBpch_external_checksum\fP (\fBCCACHE_PCH_EXTSUM\fP or \fBCCACHE_NOPCH_EXTSUM\fP, see \fIBoolean values\fP above)
1088 .RS 4
1089 When this option is set, and ccache finds a precompiled header file,
1090 ccache will look for a file with the extension \(lq.sum\(rq added
1091 (e.g. \(lqpre.h.gch.sum\(rq), and if found, it will hash this file instead
1092 of the precompiled header itself to work around the performance
1093 penalty of hashing very large files.
1094 .RE
1095 .sp
1096 \fBprefix_command\fP (\fBCCACHE_PREFIX\fP)
1097 .RS 4
1098 This option adds a list of prefixes (separated by space) to the command line
1099 that ccache uses when invoking the compiler. See also
1100 \fIUSING CCACHE WITH OTHER COMPILER WRAPPERS\fP.
1101 .RE
1102 .sp
1103 \fBprefix_command_cpp\fP (\fBCCACHE_PREFIX_CPP\fP)
1104 .RS 4
1105 This option adds a list of prefixes (separated by space) to the command
1106 line that ccache uses when invoking the preprocessor.
1107 .RE
1108 .sp
1109 \fBread_only\fP (\fBCCACHE_READONLY\fP or \fBCCACHE_NOREADONLY\fP, see \fIBoolean values\fP above)
1110 .RS 4
1111 If true, ccache will attempt to use existing cached results, but it will not
1112 add new results to any cache backend. Statistics counters will still be
1113 updated, though, unless the \fBstats\fP option is set to
1114 \fBfalse\fP.
1115 .sp
1116 If you are using this because your ccache directory is read\-only, you need to
1117 set \fBtemporary_dir\fP since ccache will fail to create
1118 temporary files otherwise. You may also want to set \fBstats\fP to
1119 \fBfalse\fP make ccache not even try to update stats files.
1120 .RE
1121 .sp
1122 \fBread_only_direct\fP (\fBCCACHE_READONLY_DIRECT\fP or \fBCCACHE_NOREADONLY_DIRECT\fP, see \fIBoolean values\fP above)
1123 .RS 4
1124 Just like \fBread_only\fP except that ccache will only try
1125 to retrieve results from the cache using the direct mode, not the
1126 preprocessor mode. See documentation for \fBread_only\fP
1127 regarding using a read\-only ccache directory.
1128 .RE
1129 .sp
1130 \fBrecache\fP (\fBCCACHE_RECACHE\fP or \fBCCACHE_NORECACHE\fP, see \fIBoolean values\fP above)
1131 .RS 4
1132 If true, ccache will not use any previously stored result. New results will
1133 still be cached, possibly overwriting any pre\-existing results.
1134 .RE
1135 .sp
1136 \fBreshare\fP (\fBCCACHE_RESHARE\fP or \fBCCACHE_NORESHARE\fP, see \fIBoolean values\fP above)
1137 .RS 4
1138 If true, ccache will write results to secondary storage even for primary
1139 storage cache hits. The default is false.
1140 .RE
1141 .sp
1142 \fBrun_second_cpp\fP (\fBCCACHE_CPP2\fP or \fBCCACHE_NOCPP2\fP, see \fIBoolean values\fP above)
1143 .RS 4
1144 If true, ccache will first run the preprocessor to preprocess the source
1145 code (see \fIThe preprocessor mode\fP) and then on a cache miss run the
1146 compiler on the source code to get hold of the object file. This is the
1147 default.
1148 .sp
1149 If false, ccache will first run preprocessor to preprocess the source code and
1150 then on a cache miss run the compiler on the \fIpreprocessed source code\fP instead
1151 of the original source code. This makes cache misses slightly faster since the
1152 source code only has to be preprocessed once. The downside is that some
1153 compilers won\(cqt produce the same result (for instance diagnostics warnings)
1154 when compiling preprocessed source code.
1155 .sp
1156 A solution to the above mentioned downside is to set \fBrun_second_cpp\fP to false
1157 and pass \fB\-fdirectives\-only\fP (for GCC) or \fB\-frewrite\-includes\fP (for Clang) to
1158 the compiler. This will cause the compiler to leave the macros and other
1159 preprocessor information, and only process the \fB#include\fP directives. When run
1160 in this way, the preprocessor arguments will be passed to the compiler since it
1161 still has to do \fIsome\fP preprocessing (like macros).
1162 .RE
1163 .sp
1164 \fBsecondary_storage\fP (\fBCCACHE_SECONDARY_STORAGE\fP)
1165 .RS 4
1166 This option specifies one or several storage backends (separated by space)
1167 to query after the primary cache storage. See
1168 \fISECONDARY STORAGE BACKENDS\fP for documentation of syntax and available
1169 backends.
1170 .sp
1171 Examples:
1172 .sp
1173 .RS 4
1174 .ie n \{\
1175 \h'-04'\(bu\h'+03'\c
1176 .\}
1177 .el \{\
1178 . sp -1
1179 . IP \(bu 2.3
1180 .\}
1181 \fBfile:/shared/nfs/directory\fP
1182 .RE
1183 .sp
1184 .RS 4
1185 .ie n \{\
1186 \h'-04'\(bu\h'+03'\c
1187 .\}
1188 .el \{\
1189 . sp -1
1190 . IP \(bu 2.3
1191 .\}
1192 \fBfile:///shared/nfs/one|read\-only file:///shared/nfs/two\fP
1193 .RE
1194 .sp
1195 .RS 4
1196 .ie n \{\
1197 \h'-04'\(bu\h'+03'\c
1198 .\}
1199 .el \{\
1200 . sp -1
1201 . IP \(bu 2.3
1202 .\}
1203 \fBhttp://example.com/cache\fP
1204 .RE
1205 .sp
1206 .RS 4
1207 .ie n \{\
1208 \h'-04'\(bu\h'+03'\c
1209 .\}
1210 .el \{\
1211 . sp -1
1212 . IP \(bu 2.3
1213 .\}
1214 \fBredis://example.com\fP
1215 .RE
1216 .RE
1217 .sp
1218 \fBsloppiness\fP (\fBCCACHE_SLOPPINESS\fP)
1219 .RS 4
1220 By default, ccache tries to give as few false cache hits as possible.
1221 However, in certain situations it\(cqs possible that you know things that
1222 ccache can\(cqt take for granted. This option makes it possible to tell
1223 ccache to relax some checks in order to increase the hit rate. The value
1224 should be a comma\-separated string with one or several of the following
1225 values:
1226 .sp
1227 \fBclang_index_store\fP
1228 .RS 4
1229 Ignore the Clang compiler option \fB\-index\-store\-path\fP and its argument when
1230 computing the manifest hash. This is useful if you use Xcode, which uses an
1231 index store path derived from the local project path. Note that the index
1232 store won\(cqt be updated correctly on cache hits if you enable this
1233 sloppiness.
1234 .RE
1235 .sp
1236 \fBfile_stat_matches\fP
1237 .RS 4
1238 Ccache normally examines a file\(cqs contents to determine whether it matches
1239 the cached version. With this sloppiness set, ccache will consider a file
1240 as matching its cached version if the mtimes and ctimes match.
1241 .RE
1242 .sp
1243 \fBfile_stat_matches_ctime\fP
1244 .RS 4
1245 Ignore ctimes when \fBfile_stat_matches\fP is enabled. This can be useful when
1246 backdating files\*(Aq mtimes in a controlled way.
1247 .RE
1248 .sp
1249 \fBinclude_file_ctime\fP
1250 .RS 4
1251 By default, ccache will not cache a file if it includes a header whose ctime
1252 is too new. This sloppiness disables that check. See also
1253 \fIHANDLING OF NEWLY CREATED HEADER FILES\fP.
1254 .RE
1255 .sp
1256 \fBinclude_file_mtime\fP
1257 .RS 4
1258 By default, ccache will not cache a file if it includes a header whose mtime
1259 is too new. This sloppiness disables that check. See also
1260 \fIHANDLING OF NEWLY CREATED HEADER FILES\fP.
1261 .RE
1262 .sp
1263 \fBivfsoverlay\fP
1264 .RS 4
1265 Ignore the Clang compiler option \fB\-ivfsoverlay\fP and its argument. This is
1266 useful if you use Xcode, which uses a virtual file system (VFS) for things
1267 like combining Objective\-C and Swift code.
1268 .RE
1269 .sp
1270 \fBlocale\fP
1271 .RS 4
1272 Ccache includes the environment variables \fBLANG\fP, \fBLC_ALL\fP, \fBLC_CTYPE\fP and
1273 \fBLC_MESSAGES\fP in the hash by default since they may affect localization of
1274 compiler warning messages. Set this sloppiness to tell ccache not to do
1275 that.
1276 .RE
1277 .sp
1278 \fBpch_defines\fP
1279 .RS 4
1280 Be sloppy about \fB#define\fP directives when precompiling a header file. See
1281 \fIPRECOMPILED HEADERS\fP for more information.
1282 .RE
1283 .sp
1284 \fBmodules\fP
1285 .RS 4
1286 By default, ccache will not cache compilations if \fB\-fmodules\fP is used since
1287 it cannot hash the state of compiler\(cqs internal representation of relevant
1288 modules. This sloppiness allows caching in such a case. See
1289 \fIC++ MODULES\fP for more information.
1290 .RE
1291 .sp
1292 \fBsystem_headers\fP
1293 .RS 4
1294 By default, ccache will also include all system headers in the manifest.
1295 With this sloppiness set, ccache will only include system headers in the
1296 hash but not add the system header files to the list of include files.
1297 .RE
1298 .sp
1299 \fBtime_macros\fP
1300 .RS 4
1301 Ignore \fB__DATE__\fP, \fB__TIME__\fP and \fB__TIMESTAMP__\fP being present in the
1302 source code.
1303 .RE
1304 .sp
1305 See the discussion under \fITROUBLESHOOTING\fP for more information.
1306 .RE
1307 .sp
1308 \fBstats\fP (\fBCCACHE_STATS\fP or \fBCCACHE_NOSTATS\fP, see \fIBoolean values\fP above)
1309 .RS 4
1310 If true, ccache will update the statistics counters on each compilation.
1311 The default is true.
1312 .RE
1313 .sp
1314 \fBstats_log\fP (\fBCCACHE_STATSLOG\fP)
1315 .RS 4
1316 If set to a file path, ccache will write statistics counter updates to the
1317 specified file. This is useful for getting statistics for individual builds.
1318 To show a summary of the current stats log, use \fBccache \-\-show\-log\-stats\fP.
1319 .if n .sp
1320 .RS 4
1321 .it 1 an-trap
1322 .nr an-no-space-flag 1
1323 .nr an-break-flag 1
1324 .br
1325 .ps +1
1326 .B Note
1327 .ps -1
1328 .br
1329 .sp
1330 Lines in the stats log starting with a hash sign (\fB#\fP) are comments.
1331 .sp .5v
1332 .RE
1333 .RE
1334 .sp
1335 \fBtemporary_dir\fP (\fBCCACHE_TEMPDIR\fP)
1336 .RS 4
1337 This option specifies where ccache will put temporary files. The default is
1338 \fB/run/user/<UID>/ccache\-tmp\fP if \fB/run/user/<UID>\fP exists, otherwise
1339 \fB<cache_dir>/tmp\fP.
1340 .if n .sp
1341 .RS 4
1342 .it 1 an-trap
1343 .nr an-no-space-flag 1
1344 .nr an-break-flag 1
1345 .br
1346 .ps +1
1347 .B Note
1348 .ps -1
1349 .br
1350 .sp
1351 In previous versions of ccache, \fBCCACHE_TEMPDIR\fP had to be on the same
1352 filesystem as the \fBCCACHE_DIR\fP path, but this requirement has been relaxed.
1353 .sp .5v
1354 .RE
1355 .RE
1356 .sp
1357 \fBumask\fP (\fBCCACHE_UMASK\fP)
1358 .RS 4
1359 This option (an octal integer) specifies the umask for files and directories
1360 in the cache directory. This is mostly useful when you wish to share your
1361 cache with other users.
1362 .RE
1363 .SH "SECONDARY STORAGE BACKENDS"
1364 .sp
1365 The \fBsecondary_storage\fP option lets you configure
1366 ccache to use one or several other storage backends in addition to the primary
1367 cache storage located in \fBcache_dir\fP. Note that cache
1368 statistics counters will still be kept in the primary cache directory \(em secondary storage backends only store cache results and manifests.
1369 .sp
1370 A secondary storage backend is specified with a URL, optionally followed by a
1371 pipe (\fB|\fP) and a pipe\-separated list of attributes. An attribute is
1372 \fIkey\fP=\fIvalue\fP or just \fIkey\fP as a short form of \fIkey\fP=\fBtrue\fP. Attribute values
1373 must be \c
1374 .URL "https://en.wikipedia.org/wiki/Percent\-encoding" "percent\-encoded" ""
1375 if they
1376 contain percent, pipe or space characters.
1377 .SS "Attributes for all backends"
1378 .sp
1379 These optional attributes are available for all secondary storage backends:
1380 .sp
1381 .RS 4
1382 .ie n \{\
1383 \h'-04'\(bu\h'+03'\c
1384 .\}
1385 .el \{\
1386 . sp -1
1387 . IP \(bu 2.3
1388 .\}
1389 \fBread\-only\fP: If \fBtrue\fP, only read from this backend, don\(cqt write. The default
1390 is \fBfalse\fP.
1391 .RE
1392 .sp
1393 .RS 4
1394 .ie n \{\
1395 \h'-04'\(bu\h'+03'\c
1396 .\}
1397 .el \{\
1398 . sp -1
1399 . IP \(bu 2.3
1400 .\}
1401 \fBshards\fP: A comma\-separated list of names for sharding (partitioning) the
1402 cache entries using
1403 .URL "https://en.wikipedia.org/wiki/Rendezvous_hashing" "Rendezvous hashing" ","
1404 typically to spread the cache over a server cluster. When set, the storage URL
1405 must contain an asterisk (\fB*\fP), which will be replaced by one of the shard
1406 names to form a real URL. A shard name can optionally have an appended weight
1407 within parentheses to indicate how much of the key space should be associated
1408 with that shard. A shard with weight \fBw\fP will contain \fBw\fP/\fBS\fP of the cache,
1409 where \fBS\fP is the sum of all shard weights. A weight could for instance be set
1410 to represent the available memory for a memory cache on a specific server. The
1411 default weight is \fB1\fP.
1412 .sp
1413 Examples:
1414 .sp
1415 .RS 4
1416 .ie n \{\
1417 \h'-04'\(bu\h'+03'\c
1418 .\}
1419 .el \{\
1420 . sp -1
1421 . IP \(bu 2.3
1422 .\}
1423 \fBredis://cache\-*.example.com|shards=a(3),b(1),c(1.5)\fP will put 55% (3/5.5)
1424 of the cache on \fBredis://cache\-a.example.com\fP, 18% (1/5.5) on
1425 \fBredis://cache\-b.example.com\fP and 27% (1.5/5.5) on
1426 \fBredis://cache\-c.example.com\fP.
1427 .RE
1428 .sp
1429 .RS 4
1430 .ie n \{\
1431 \h'-04'\(bu\h'+03'\c
1432 .\}
1433 .el \{\
1434 . sp -1
1435 . IP \(bu 2.3
1436 .\}
1437 \fBhttp://example.com/*|shards=alpha,beta\fP will put 50% of the cache on
1438 \fBhttp://example.com/alpha\fP and 50% on \fBhttp://example.com/beta\fP.
1439 .RE
1440 .RE
1441 .sp
1442 .RS 4
1443 .ie n \{\
1444 \h'-04'\(bu\h'+03'\c
1445 .\}
1446 .el \{\
1447 . sp -1
1448 . IP \(bu 2.3
1449 .\}
1450 \fBshare\-hits\fP: If \fBtrue\fP, write hits for this backend to primary storage. The
1451 default is \fBtrue\fP.
1452 .RE
1453 .SS "Storage interaction"
1454 .sp
1455 The table below describes the interaction between primary and secondary storage
1456 on cache hits and misses:
1457 .TS
1458 allbox tab(:);
1459 lt lt lt.
1460 T{
1461 .sp
1462 \fBPrimary storage\fP
1463 T}:T{
1464 .sp
1465 \fBSecondary storage\fP
1466 T}:T{
1467 .sp
1468 \fBWhat happens\fP
1469 T}
1470 T{
1471 .sp
1472 miss
1473 T}:T{
1474 .sp
1475 miss
1476 T}:T{
1477 .sp
1478 Compile, write to primary, write to secondary[1]
1479 T}
1480 T{
1481 .sp
1482 miss
1483 T}:T{
1484 .sp
1485 hit
1486 T}:T{
1487 .sp
1488 Read from secondary, write to primary[2]
1489 T}
1490 T{
1491 .sp
1492 hit
1493 T}:T{
1494 .sp
1495 \-
1496 T}:T{
1497 .sp
1498 Read from primary, don\(cqt write to secondary[3]
1499 T}
1500 .TE
1501 .sp
1502 .sp
1503 [1] Unless secondary storage has attribute \fBread\-only=true\fP.
1504 .br
1505 [2] Unless secondary storage has attribute \fBshare\-hits=false\fP.
1506 .br
1507 [3] Unless primary storage is set to share its cache hits with the
1508 \fBreshare\fP option.
1509 .SS "File storage backend"
1510 .sp
1511 URL format: \fBfile:DIRECTORY\fP or \fBfile://DIRECTORY\fP
1512 .sp
1513 This backend stores data as separate files in a directory structure below
1514 \fBDIRECTORY\fP (an absolute path), similar (but not identical) to the primary cache
1515 storage. A typical use case for this backend would be sharing a cache on an NFS
1516 directory.
1517 .if n .sp
1518 .RS 4
1519 .it 1 an-trap
1520 .nr an-no-space-flag 1
1521 .nr an-break-flag 1
1522 .br
1523 .ps +1
1524 .B Important
1525 .ps -1
1526 .br
1527 .sp
1528 ccache will not perform any cleanup of the storage \(em that has to be
1529 done by other means, for instance by running \fBccache \-\-trim\-dir\fP periodically.
1530 .sp .5v
1531 .RE
1532 .sp
1533 Examples:
1534 .sp
1535 .RS 4
1536 .ie n \{\
1537 \h'-04'\(bu\h'+03'\c
1538 .\}
1539 .el \{\
1540 . sp -1
1541 . IP \(bu 2.3
1542 .\}
1543 \fBfile:/shared/nfs/directory\fP
1544 .RE
1545 .sp
1546 .RS 4
1547 .ie n \{\
1548 \h'-04'\(bu\h'+03'\c
1549 .\}
1550 .el \{\
1551 . sp -1
1552 . IP \(bu 2.3
1553 .\}
1554 \fBfile:///shared/nfs/directory|umask=002|update\-mtime=true\fP
1555 .RE
1556 .sp
1557 Optional attributes:
1558 .sp
1559 .RS 4
1560 .ie n \{\
1561 \h'-04'\(bu\h'+03'\c
1562 .\}
1563 .el \{\
1564 . sp -1
1565 . IP \(bu 2.3
1566 .\}
1567 \fBlayout\fP: How to store file under the cache directory. Available values:
1568 .sp
1569 .RS 4
1570 .ie n \{\
1571 \h'-04'\(bu\h'+03'\c
1572 .\}
1573 .el \{\
1574 . sp -1
1575 . IP \(bu 2.3
1576 .\}
1577 \fBflat\fP: Store all files directly under the cache directory.
1578 .RE
1579 .sp
1580 .RS 4
1581 .ie n \{\
1582 \h'-04'\(bu\h'+03'\c
1583 .\}
1584 .el \{\
1585 . sp -1
1586 . IP \(bu 2.3
1587 .\}
1588 \fBsubdirs\fP: Store files in 256 subdirectories of the cache directory.
1589 .RE
1590 .sp
1591 The default is \fBsubdirs\fP.
1592 .RE
1593 .sp
1594 .RS 4
1595 .ie n \{\
1596 \h'-04'\(bu\h'+03'\c
1597 .\}
1598 .el \{\
1599 . sp -1
1600 . IP \(bu 2.3
1601 .\}
1602 \fBumask\fP: This attribute (an octal integer) overrides the umask to use for
1603 files and directories in the cache directory.
1604 .RE
1605 .sp
1606 .RS 4
1607 .ie n \{\
1608 \h'-04'\(bu\h'+03'\c
1609 .\}
1610 .el \{\
1611 . sp -1
1612 . IP \(bu 2.3
1613 .\}
1614 \fBupdate\-mtime\fP: If \fBtrue\fP, update the modification time (mtime) of cache
1615 entries that are read. The default is \fBfalse\fP.
1616 .RE
1617 .SS "HTTP storage backend"
1618 .sp
1619 URL format: \fBhttp://HOST[:PORT][/PATH]\fP
1620 .sp
1621 This backend stores data in an HTTP\-compatible server. The required HTTP methods
1622 are \fBGET\fP, \fBPUT\fP and \fBDELETE\fP.
1623 .if n .sp
1624 .RS 4
1625 .it 1 an-trap
1626 .nr an-no-space-flag 1
1627 .nr an-break-flag 1
1628 .br
1629 .ps +1
1630 .B Important
1631 .ps -1
1632 .br
1633 .sp
1634 ccache will not perform any cleanup of the storage \(em that has to be
1635 done by other means, for instance by running \fBccache \-\-trim\-dir\fP periodically.
1636 .sp .5v
1637 .RE
1638 .if n .sp
1639 .RS 4
1640 .it 1 an-trap
1641 .nr an-no-space-flag 1
1642 .nr an-break-flag 1
1643 .br
1644 .ps +1
1645 .B Note
1646 .ps -1
1647 .br
1648 .sp
1649 HTTPS is not supported.
1650 .sp .5v
1651 .RE
1652 .if n .sp
1653 .RS 4
1654 .it 1 an-trap
1655 .nr an-no-space-flag 1
1656 .nr an-break-flag 1
1657 .br
1658 .ps +1
1659 .B Tip
1660 .ps -1
1661 .br
1662 .sp
1663 See \c
1664 .URL "https://ccache.dev/howto/http\-storage.html" "How to set up HTTP storage"
1665 for hints on how to set up an HTTP server for use with ccache.
1666 .sp .5v
1667 .RE
1668 .sp
1669 Examples:
1670 .sp
1671 .RS 4
1672 .ie n \{\
1673 \h'-04'\(bu\h'+03'\c
1674 .\}
1675 .el \{\
1676 . sp -1
1677 . IP \(bu 2.3
1678 .\}
1679 \fBhttp://localhost\fP
1680 .RE
1681 .sp
1682 .RS 4
1683 .ie n \{\
1684 \h'-04'\(bu\h'+03'\c
1685 .\}
1686 .el \{\
1687 . sp -1
1688 . IP \(bu 2.3
1689 .\}
1690 \fBhttp://someusername:p4ssw0rd@example.com/cache/\fP
1691 .RE
1692 .sp
1693 .RS 4
1694 .ie n \{\
1695 \h'-04'\(bu\h'+03'\c
1696 .\}
1697 .el \{\
1698 . sp -1
1699 . IP \(bu 2.3
1700 .\}
1701 \fBhttp://localhost:8080|layout=bazel|connect\-timeout=50\fP
1702 .RE
1703 .sp
1704 Optional attributes:
1705 .sp
1706 .RS 4
1707 .ie n \{\
1708 \h'-04'\(bu\h'+03'\c
1709 .\}
1710 .el \{\
1711 . sp -1
1712 . IP \(bu 2.3
1713 .\}
1714 \fBconnect\-timeout\fP: Timeout (in ms) for network connection. The default is 100.
1715 .RE
1716 .sp
1717 .RS 4
1718 .ie n \{\
1719 \h'-04'\(bu\h'+03'\c
1720 .\}
1721 .el \{\
1722 . sp -1
1723 . IP \(bu 2.3
1724 .\}
1725 \fBlayout\fP: How to map key names to the path part of the URL. Available values:
1726 .sp
1727 .RS 4
1728 .ie n \{\
1729 \h'-04'\(bu\h'+03'\c
1730 .\}
1731 .el \{\
1732 . sp -1
1733 . IP \(bu 2.3
1734 .\}
1735 \fBbazel\fP: Store values in a format compatible with the Bazel HTTP caching
1736 protocol. More specifically, the entries will be stored as 64 hex digits
1737 under the \fB/ac/\fP part of the cache.
1738 .if n .sp
1739 .RS 4
1740 .it 1 an-trap
1741 .nr an-no-space-flag 1
1742 .nr an-break-flag 1
1743 .br
1744 .ps +1
1745 .B Note
1746 .ps -1
1747 .br
1748 .sp
1749 You may have to disable verification of action cache values in the server
1750 for this to work since ccache entries are not valid action result metadata
1751 values.
1752 .sp .5v
1753 .RE
1754 .RE
1755 .sp
1756 .RS 4
1757 .ie n \{\
1758 \h'-04'\(bu\h'+03'\c
1759 .\}
1760 .el \{\
1761 . sp -1
1762 . IP \(bu 2.3
1763 .\}
1764 \fBflat\fP: Append the key directly to the path part of the URL (with a leading
1765 slash if needed).
1766 .RE
1767 .sp
1768 .RS 4
1769 .ie n \{\
1770 \h'-04'\(bu\h'+03'\c
1771 .\}
1772 .el \{\
1773 . sp -1
1774 . IP \(bu 2.3
1775 .\}
1776 \fBsubdirs\fP: Append the first two characters of the key to the URL (with a
1777 leading slash if needed), followed by a slash and the rest of the key. This
1778 divides the entries into 256 buckets.
1779 .RE
1780 .sp
1781 The default is \fBsubdirs\fP.
1782 .RE
1783 .sp
1784 .RS 4
1785 .ie n \{\
1786 \h'-04'\(bu\h'+03'\c
1787 .\}
1788 .el \{\
1789 . sp -1
1790 . IP \(bu 2.3
1791 .\}
1792 \fBoperation\-timeout\fP: Timeout (in ms) for HTTP requests. The default is 10000.
1793 .RE
1794 .SS "Redis storage backend"
1795 .sp
1796 URL format: \fBredis://[[USERNAME:]PASSWORD@]HOST[:PORT][/DBNUMBER]\fP
1797 .sp
1798 This backend stores data in a \c
1799 .URL "https://redis.io" "Redis" ""
1800 (or Redis\-compatible)
1801 server. There are implementations for both memory\-based and disk\-based storage.
1802 \fBPORT\fP defaults to \fB6379\fP and \fBDBNUMBER\fP defaults to \fB0\fP.
1803 .if n .sp
1804 .RS 4
1805 .it 1 an-trap
1806 .nr an-no-space-flag 1
1807 .nr an-break-flag 1
1808 .br
1809 .ps +1
1810 .B Note
1811 .ps -1
1812 .br
1813 .sp
1814 ccache will not perform any cleanup of the Redis storage, but you can
1815 .URL "https://redis.io/topics/lru\-cache" "configure LRU eviction" "."
1816 .sp .5v
1817 .RE
1818 .if n .sp
1819 .RS 4
1820 .it 1 an-trap
1821 .nr an-no-space-flag 1
1822 .nr an-break-flag 1
1823 .br
1824 .ps +1
1825 .B Tip
1826 .ps -1
1827 .br
1828 .sp
1829 See \c
1830 .URL "https://ccache.dev/howto/redis\-storage.html" "How to set up Redis
1831 storage" for hints on setting up a Redis server for use with ccache.
1832 .sp .5v
1833 .RE
1834 .if n .sp
1835 .RS 4
1836 .it 1 an-trap
1837 .nr an-no-space-flag 1
1838 .nr an-break-flag 1
1839 .br
1840 .ps +1
1841 .B Tip
1842 .ps -1
1843 .br
1844 .sp
1845 You can set up a cluster of Redis servers using the \fBshards\fP attribute
1846 described in \fISECONDARY STORAGE BACKENDS\fP.
1847 .sp .5v
1848 .RE
1849 .sp
1850 Examples:
1851 .sp
1852 .RS 4
1853 .ie n \{\
1854 \h'-04'\(bu\h'+03'\c
1855 .\}
1856 .el \{\
1857 . sp -1
1858 . IP \(bu 2.3
1859 .\}
1860 \fBredis://localhost\fP
1861 .RE
1862 .sp
1863 .RS 4
1864 .ie n \{\
1865 \h'-04'\(bu\h'+03'\c
1866 .\}
1867 .el \{\
1868 . sp -1
1869 . IP \(bu 2.3
1870 .\}
1871 \fBredis://p4ssw0rd@cache.example.com:6379/0|connect\-timeout=50\fP
1872 .RE
1873 .sp
1874 Optional attributes:
1875 .sp
1876 .RS 4
1877 .ie n \{\
1878 \h'-04'\(bu\h'+03'\c
1879 .\}
1880 .el \{\
1881 . sp -1
1882 . IP \(bu 2.3
1883 .\}
1884 \fBconnect\-timeout\fP: Timeout (in ms) for network connection. The default is 100.
1885 .RE
1886 .sp
1887 .RS 4
1888 .ie n \{\
1889 \h'-04'\(bu\h'+03'\c
1890 .\}
1891 .el \{\
1892 . sp -1
1893 . IP \(bu 2.3
1894 .\}
1895 \fBoperation\-timeout\fP: Timeout (in ms) for Redis commands. The default is 10000.
1896 .RE
1897 .SH "CACHE SIZE MANAGEMENT"
1898 .sp
1899 By default, ccache has a 5 GB limit on the total size of files in the cache and
1900 no limit on the number of files. You can set different limits using the command
1901 line options \fB\-M\fP/\fB\-\-max\-size\fP and \fB\-F\fP/\fB\-\-max\-files\fP. Use the
1902 \fB\-s\fP/\fB\-\-show\-stats\fP option to see the cache size and the currently configured
1903 limits (in addition to other various statistics).
1904 .sp
1905 Cleanup can be triggered in two different ways: automatic and manual.
1906 .SS "Automatic cleanup"
1907 .sp
1908 Ccache maintains counters for various statistics about the cache, including the
1909 size and number of all cached files. In order to improve performance and reduce
1910 issues with concurrent ccache invocations, there is one statistics file for
1911 each of the sixteen subdirectories in the cache.
1912 .sp
1913 After a new compilation result has been written to the cache, ccache will
1914 update the size and file number statistics for the subdirectory (one of
1915 sixteen) to which the result was written. Then, if the size counter for said
1916 subdirectory is greater than \fBmax_size / 16\fP or the file number counter is
1917 greater than \fBmax_files / 16\fP, automatic cleanup is triggered.
1918 .sp
1919 When automatic cleanup is triggered for a subdirectory in the cache, ccache
1920 will:
1921 .sp
1922 .RS 4
1923 .ie n \{\
1924 \h'-04' 1.\h'+01'\c
1925 .\}
1926 .el \{\
1927 . sp -1
1928 . IP " 1." 4.2
1929 .\}
1930 Count all files in the subdirectory and compute their aggregated size.
1931 .RE
1932 .sp
1933 .RS 4
1934 .ie n \{\
1935 \h'-04' 2.\h'+01'\c
1936 .\}
1937 .el \{\
1938 . sp -1
1939 . IP " 2." 4.2
1940 .\}
1941 Remove files in LRU (least recently used) order until the size is at most
1942 \fBlimit_multiple * max_size / 16\fP and the number of files is at most
1943 \fBlimit_multiple * max_files / 16\fP, where
1944 \fBlimit_multiple\fP, \fBmax_size\fP
1945 and \fBmax_files\fP are configuration options.
1946 .RE
1947 .sp
1948 .RS 4
1949 .ie n \{\
1950 \h'-04' 3.\h'+01'\c
1951 .\}
1952 .el \{\
1953 . sp -1
1954 . IP " 3." 4.2
1955 .\}
1956 Set the size and file number counters to match the files that were kept.
1957 .RE
1958 .sp
1959 The reason for removing more files than just those needed to not exceed the max
1960 limits is that a cleanup is a fairly slow operation, so it would not be a good
1961 idea to trigger it often, like after each cache miss.
1962 .SS "Manual cleanup"
1963 .sp
1964 You can run \fBccache \-c/\-\-cleanup\fP to force cleanup of the whole cache, i.e. all
1965 of the sixteen subdirectories. This will recalculate the statistics counters
1966 and make sure that the configuration options \fBmax_size\fP and
1967 \fBmax_files\fP are not exceeded. Note that
1968 \fBlimit_multiple\fP is not taken into account for manual
1969 cleanup.
1970 .SH "CACHE COMPRESSION"
1971 .sp
1972 Ccache will by default compress all data it puts into the cache using the
1973 compression algorithm \c
1974 .URL "http://zstd.net" "Zstandard" ""
1975 (zstd) using compression level
1976 1. The algorithm is fast enough that there should be little reason to turn off
1977 compression to gain performance. One exception is if the cache is located on a
1978 compressed file system, in which case the compression performed by ccache of
1979 course is redundant. See the documentation for the configuration options
1980 \fBcompression\fP and
1981 \fBcompression_level\fP for more information.
1982 .sp
1983 You can use the command line option \fB\-x\fP/\fB\-\-show\-compression\fP to print
1984 information related to compression. Example:
1985 .sp
1986 .if n .RS 4
1987 .nf
1988 .fam C
1989 Total data: 14.8 GB (16.0 GB disk blocks)
1990 Compressed data: 11.3 GB (30.6% of original size)
1991 Original size: 36.9 GB
1992 Compression ratio: 3.267 x (69.4% space savings)
1993 Incompressible data: 3.5 GB
1994 .fam
1995 .fi
1996 .if n .RE
1997 .sp
1998 Notes:
1999 .sp
2000 .RS 4
2001 .ie n \{\
2002 \h'-04'\(bu\h'+03'\c
2003 .\}
2004 .el \{\
2005 . sp -1
2006 . IP \(bu 2.3
2007 .\}
2008 The \(lqdisk blocks\(rq size is the cache size when taking disk block size into
2009 account. This value should match the \(lqCache size\(rq value from \(lqccache
2010 \-\-show\-stats\(rq. The other size numbers refer to actual content sizes.
2011 .RE
2012 .sp
2013 .RS 4
2014 .ie n \{\
2015 \h'-04'\(bu\h'+03'\c
2016 .\}
2017 .el \{\
2018 . sp -1
2019 . IP \(bu 2.3
2020 .\}
2021 \(lqCompressed data\(rq refers to result and manifest files stored in the cache.
2022 .RE
2023 .sp
2024 .RS 4
2025 .ie n \{\
2026 \h'-04'\(bu\h'+03'\c
2027 .\}
2028 .el \{\
2029 . sp -1
2030 . IP \(bu 2.3
2031 .\}
2032 \(lqIncompressible data\(rq refers to files that are always stored uncompressed
2033 (triggered by enabling \fBfile_clone\fP or
2034 \fBhard_link\fP) or unknown files (for instance files
2035 created by older ccache versions).
2036 .RE
2037 .sp
2038 .RS 4
2039 .ie n \{\
2040 \h'-04'\(bu\h'+03'\c
2041 .\}
2042 .el \{\
2043 . sp -1
2044 . IP \(bu 2.3
2045 .\}
2046 The compression ratio is affected by
2047 \fBcompression_level\fP.
2048 .RE
2049 .sp
2050 The cache data can also be recompressed to another compression level (or made
2051 uncompressed) with the command line option \fB\-X\fP/\fB\-\-recompress\fP. If you choose to
2052 disable compression by default or to use a low compression level, you can
2053 (re)compress newly cached data with a higher compression level after the build
2054 or at another time when there are more CPU cycles available, for instance every
2055 night. Full recompression potentially takes a lot of time, but only files that
2056 are currently compressed with a different level than the target level will be
2057 recompressed.
2058 .SH "CACHE STATISTICS"
2059 .sp
2060 \fBccache \-\-show\-stats\fP shows a summary of statistics, including cache size,
2061 cleanups (number of performed cleanups, either implicitly due to a cache size
2062 limit being reached or due to explicit \fBccache \-c\fP calls), overall hit rate, hit
2063 rate for direct/preprocessed modes
2064 and hit rate for primary and secondary storage.
2065 .sp
2066 The summary also includes counters called \(lqErrors\(rq and \(lqUncacheable\(rq, which
2067 are sums of more detailed counters. To see those detailed counters, use the
2068 \fB\-v\fP/\fB\-\-verbose\fP flag. The verbose mode can show the following counters:
2069 .TS
2070 allbox tab(:);
2071 lt lt.
2072 T{
2073 .sp
2074 \fBCounter\fP
2075 T}:T{
2076 .sp
2077 \fBDescription\fP
2078 T}
2079 T{
2080 .sp
2081 Autoconf compile/link
2082 T}:T{
2083 .sp
2084 Uncacheable compilation or linking by an Autoconf test.
2085 T}
2086 T{
2087 .sp
2088 Bad compiler arguments
2089 T}:T{
2090 .sp
2091 Malformed compiler argument, e.g. missing a value for a compiler option that
2092 requires an argument or failure to read a file specified by a compiler option
2093 argument.
2094 T}
2095 T{
2096 .sp
2097 Called for linking
2098 T}:T{
2099 .sp
2100 The compiler was called for linking, not compiling. Ccache only supports
2101 compilation of a single file, i.e. calling the compiler with the \fB\-c\fP option to
2102 produce a single object file from a single source file.
2103 T}
2104 T{
2105 .sp
2106 Called for preprocessing
2107 T}:T{
2108 .sp
2109 The compiler was called for preprocessing, not compiling.
2110 T}
2111 T{
2112 .sp
2113 Could not use modules
2114 T}:T{
2115 .sp
2116 Preconditions for using C++ MODULES were not fulfilled.
2117 T}
2118 T{
2119 .sp
2120 Could not use precompiled header
2121 T}:T{
2122 .sp
2123 Preconditions for using precompiled headers were not
2124 fulfilled.
2125 T}
2126 T{
2127 .sp
2128 Could not write to output file
2129 T}:T{
2130 .sp
2131 The output path specified with \fB\-o\fP is not a file (e.g. a directory or a device
2132 node).
2133 T}
2134 T{
2135 .sp
2136 Compilation failed
2137 T}:T{
2138 .sp
2139 The compilation failed. No result stored in the cache.
2140 T}
2141 T{
2142 .sp
2143 Compiler check failed
2144 T}:T{
2145 .sp
2146 A compiler check program specified by
2147 \fBcompiler_check\fP (\fBCCACHE_COMPILERCHECK\fP) failed.
2148 T}
2149 T{
2150 .sp
2151 Compiler produced empty output
2152 T}:T{
2153 .sp
2154 The compiler\(cqs output file (typically an object file) was empty after
2155 compilation.
2156 T}
2157 T{
2158 .sp
2159 Compiler produced no output
2160 T}:T{
2161 .sp
2162 The compiler\(cqs output file (typically an object file) was missing after
2163 compilation.
2164 T}
2165 T{
2166 .sp
2167 Compiler produced stdout
2168 T}:T{
2169 .sp
2170 The compiler wrote data to standard output. This is something that compilers
2171 normally never do, so ccache is not designed to store such output in the cache.
2172 T}
2173 T{
2174 .sp
2175 Could not find the compiler
2176 T}:T{
2177 .sp
2178 The compiler to execute could not be found.
2179 T}
2180 T{
2181 .sp
2182 Error hashing extra file
2183 T}:T{
2184 .sp
2185 Failure reading a file specified by
2186 \fBextra_files_to_hash\fP (\fBCCACHE_EXTRAFILES\fP).
2187 T}
2188 T{
2189 .sp
2190 Forced recache
2191 T}:T{
2192 .sp
2193 \fBCCACHE_RECACHE\fP was used to overwrite an existing result.
2194 T}
2195 T{
2196 .sp
2197 Internal error
2198 T}:T{
2199 .sp
2200 Unexpected failure, e.g. due to problems reading/writing the cache.
2201 T}
2202 T{
2203 .sp
2204 Missing cache file
2205 T}:T{
2206 .sp
2207 A file was unexpectedly missing from the cache. This only happens in rare
2208 situations, e.g. if one ccache instance is about to get a file from the cache
2209 while another instance removed the file as part of cache cleanup.
2210 T}
2211 T{
2212 .sp
2213 Multiple source files
2214 T}:T{
2215 .sp
2216 The compiler was called to compile multiple source files in one go. This is not
2217 supported by ccache.
2218 T}
2219 T{
2220 .sp
2221 No input file
2222 T}:T{
2223 .sp
2224 No input file was specified to the compiler.
2225 T}
2226 T{
2227 .sp
2228 Output to stdout
2229 T}:T{
2230 .sp
2231 The compiler was instructed to write its output to standard output using \fB\-o \-\fP.
2232 This is not supported by ccache.
2233 T}
2234 T{
2235 .sp
2236 Preprocessing failed
2237 T}:T{
2238 .sp
2239 Preprocessing the source code using the compiler\(cqs \fB\-E\fP option failed.
2240 T}
2241 T{
2242 .sp
2243 Unsupported code directive
2244 T}:T{
2245 .sp
2246 Code like the assembler \fB.incbin\fP directive was found. This is not supported
2247 by ccache.
2248 T}
2249 T{
2250 .sp
2251 Unsupported compiler option
2252 T}:T{
2253 .sp
2254 A compiler option not supported by ccache was found.
2255 T}
2256 T{
2257 .sp
2258 Unsupported source language
2259 T}:T{
2260 .sp
2261 A source language e.g. specified with \fB\-x\fP was unsupported by ccache.
2262 T}
2263 .TE
2264 .sp
2265 .SH "HOW CCACHE WORKS"
2266 .sp
2267 The basic idea is to detect when you are compiling exactly the same code a
2268 second time and reuse the previously produced output. The detection is done by
2269 hashing different kinds of information that should be unique for the
2270 compilation and then using the hash sum to identify the cached output. Ccache
2271 uses BLAKE3, a very fast cryptographic hash algorithm, for the hashing. On a
2272 cache hit, ccache is able to supply all of the correct compiler outputs
2273 (including all warnings, dependency file, etc) from the cache. Data stored in
2274 the cache is checksummed with XXH3, an extremely fast non\-cryptographic
2275 algorithm, to detect corruption.
2276 .sp
2277 Ccache has two ways of gathering information used to look up results in the
2278 cache:
2279 .sp
2280 .RS 4
2281 .ie n \{\
2282 \h'-04'\(bu\h'+03'\c
2283 .\}
2284 .el \{\
2285 . sp -1
2286 . IP \(bu 2.3
2287 .\}
2288 the \fBpreprocessor mode\fP, where ccache runs the preprocessor on the source
2289 code and hashes the result
2290 .RE
2291 .sp
2292 .RS 4
2293 .ie n \{\
2294 \h'-04'\(bu\h'+03'\c
2295 .\}
2296 .el \{\
2297 . sp -1
2298 . IP \(bu 2.3
2299 .\}
2300 the \fBdirect mode\fP, where ccache hashes the source code and include files
2301 directly
2302 .RE
2303 .sp
2304 The direct mode is generally faster since running the preprocessor has some
2305 overhead.
2306 .sp
2307 If no previous result is detected (i.e., there is a cache miss) using the direct
2308 mode, ccache will fall back to the preprocessor mode unless the \fBdepend mode\fP is
2309 enabled. In the depend mode, ccache never runs the preprocessor, not even on
2310 cache misses. Read more in \fIThe depend mode\fP below.
2311 .SS "Common hashed information"
2312 .sp
2313 The following information is always included in the hash:
2314 .sp
2315 .RS 4
2316 .ie n \{\
2317 \h'-04'\(bu\h'+03'\c
2318 .\}
2319 .el \{\
2320 . sp -1
2321 . IP \(bu 2.3
2322 .\}
2323 the extension used by the compiler for a file with preprocessor output
2324 (normally \fB.i\fP for C code and \fB.ii\fP for C++ code)
2325 .RE
2326 .sp
2327 .RS 4
2328 .ie n \{\
2329 \h'-04'\(bu\h'+03'\c
2330 .\}
2331 .el \{\
2332 . sp -1
2333 . IP \(bu 2.3
2334 .\}
2335 the compiler\(cqs size and modification time (or other compiler\-specific
2336 information specified by \fBcompiler_check\fP)
2337 .RE
2338 .sp
2339 .RS 4
2340 .ie n \{\
2341 \h'-04'\(bu\h'+03'\c
2342 .\}
2343 .el \{\
2344 . sp -1
2345 . IP \(bu 2.3
2346 .\}
2347 the name of the compiler
2348 .RE
2349 .sp
2350 .RS 4
2351 .ie n \{\
2352 \h'-04'\(bu\h'+03'\c
2353 .\}
2354 .el \{\
2355 . sp -1
2356 . IP \(bu 2.3
2357 .\}
2358 the current directory (if \fBhash_dir\fP is enabled)
2359 .RE
2360 .sp
2361 .RS 4
2362 .ie n \{\
2363 \h'-04'\(bu\h'+03'\c
2364 .\}
2365 .el \{\
2366 . sp -1
2367 . IP \(bu 2.3
2368 .\}
2369 contents of files specified by
2370 \fBextra_files_to_hash\fP (if any)
2371 .RE
2372 .SS "The preprocessor mode"
2373 .sp
2374 In the preprocessor mode, the hash is formed of the common information and:
2375 .sp
2376 .RS 4
2377 .ie n \{\
2378 \h'-04'\(bu\h'+03'\c
2379 .\}
2380 .el \{\
2381 . sp -1
2382 . IP \(bu 2.3
2383 .\}
2384 the preprocessor output from running the compiler with \fB\-E\fP
2385 .RE
2386 .sp
2387 .RS 4
2388 .ie n \{\
2389 \h'-04'\(bu\h'+03'\c
2390 .\}
2391 .el \{\
2392 . sp -1
2393 . IP \(bu 2.3
2394 .\}
2395 the command line options except those that affect include files (\fB\-I\fP,
2396 \fB\-include\fP, \fB\-D\fP, etc; the theory is that these command line options will
2397 change the preprocessor output if they have any effect at all)
2398 .RE
2399 .sp
2400 .RS 4
2401 .ie n \{\
2402 \h'-04'\(bu\h'+03'\c
2403 .\}
2404 .el \{\
2405 . sp -1
2406 . IP \(bu 2.3
2407 .\}
2408 any standard error output generated by the preprocessor
2409 .RE
2410 .sp
2411 Based on the hash, the cached compilation result can be looked up directly in
2412 the cache.
2413 .SS "The direct mode"
2414 .sp
2415 In the direct mode, the hash is formed of the common information and:
2416 .sp
2417 .RS 4
2418 .ie n \{\
2419 \h'-04'\(bu\h'+03'\c
2420 .\}
2421 .el \{\
2422 . sp -1
2423 . IP \(bu 2.3
2424 .\}
2425 the input source file
2426 .RE
2427 .sp
2428 .RS 4
2429 .ie n \{\
2430 \h'-04'\(bu\h'+03'\c
2431 .\}
2432 .el \{\
2433 . sp -1
2434 . IP \(bu 2.3
2435 .\}
2436 the compiler options
2437 .RE
2438 .sp
2439 Based on the hash, a data structure called \(lqmanifest\(rq is looked up in the
2440 cache. The manifest contains:
2441 .sp
2442 .RS 4
2443 .ie n \{\
2444 \h'-04'\(bu\h'+03'\c
2445 .\}
2446 .el \{\
2447 . sp -1
2448 . IP \(bu 2.3
2449 .\}
2450 references to cached compilation results (object file, dependency file, etc)
2451 that were produced by previous compilations that matched the hash
2452 .RE
2453 .sp
2454 .RS 4
2455 .ie n \{\
2456 \h'-04'\(bu\h'+03'\c
2457 .\}
2458 .el \{\
2459 . sp -1
2460 . IP \(bu 2.3
2461 .\}
2462 paths to the include files that were read at the time the compilation results
2463 were stored in the cache
2464 .RE
2465 .sp
2466 .RS 4
2467 .ie n \{\
2468 \h'-04'\(bu\h'+03'\c
2469 .\}
2470 .el \{\
2471 . sp -1
2472 . IP \(bu 2.3
2473 .\}
2474 hash sums of the include files at the time the compilation results were
2475 stored in the cache
2476 .RE
2477 .sp
2478 The current contents of the include files are then hashed and compared to the
2479 information in the manifest. If there is a match, ccache knows the result of
2480 the compilation. If there is no match, ccache falls back to running the
2481 preprocessor. The output from the preprocessor is parsed to find the include
2482 files that were read. The paths and hash sums of those include files are then
2483 stored in the manifest along with information about the produced compilation
2484 result.
2485 .sp
2486 There is a catch with the direct mode: header files that were used by the
2487 compiler are recorded, but header files that were \fBnot\fP used, but would have
2488 been used if they existed, are not. So, when ccache checks if a result can be
2489 taken from the cache, it currently can\(cqt check if the existence of a new header
2490 file should invalidate the result. In practice, the direct mode is safe to use
2491 in the absolute majority of cases.
2492 .sp
2493 The direct mode will be disabled if any of the following holds:
2494 .sp
2495 .RS 4
2496 .ie n \{\
2497 \h'-04'\(bu\h'+03'\c
2498 .\}
2499 .el \{\
2500 . sp -1
2501 . IP \(bu 2.3
2502 .\}
2503 \fBdirect_mode\fP is false
2504 .RE
2505 .sp
2506 .RS 4
2507 .ie n \{\
2508 \h'-04'\(bu\h'+03'\c
2509 .\}
2510 .el \{\
2511 . sp -1
2512 . IP \(bu 2.3
2513 .\}
2514 a modification time of one of the include files is too new (needed to avoid a
2515 race condition)
2516 .RE
2517 .sp
2518 .RS 4
2519 .ie n \{\
2520 \h'-04'\(bu\h'+03'\c
2521 .\}
2522 .el \{\
2523 . sp -1
2524 . IP \(bu 2.3
2525 .\}
2526 a compiler option not supported by the direct mode is used:
2527 .sp
2528 .RS 4
2529 .ie n \{\
2530 \h'-04'\(bu\h'+03'\c
2531 .\}
2532 .el \{\
2533 . sp -1
2534 . IP \(bu 2.3
2535 .\}
2536 a \fB\-Wp,*\fP compiler option other than \fB\-Wp,\-MD,<path>\fP, \fB\-Wp,\-MMD,<path>\fP
2537 and \fB\-Wp,\-D<define>\fP
2538 .RE
2539 .sp
2540 .RS 4
2541 .ie n \{\
2542 \h'-04'\(bu\h'+03'\c
2543 .\}
2544 .el \{\
2545 . sp -1
2546 . IP \(bu 2.3
2547 .\}
2548 \fB\-Xpreprocessor\fP
2549 .RE
2550 .RE
2551 .sp
2552 .RS 4
2553 .ie n \{\
2554 \h'-04'\(bu\h'+03'\c
2555 .\}
2556 .el \{\
2557 . sp -1
2558 . IP \(bu 2.3
2559 .\}
2560 the string \fB__TIME__\fP is present in the source code
2561 .RE
2562 .SS "The depend mode"
2563 .sp
2564 If the depend mode is enabled, ccache will not use the preprocessor at all. The
2565 hash used to identify results in the cache will be based on the direct mode
2566 hash described above plus information about include files read from the
2567 dependency file generated by the compiler with \fB\-MD\fP or \fB\-MMD\fP.
2568 .sp
2569 Advantages:
2570 .sp
2571 .RS 4
2572 .ie n \{\
2573 \h'-04'\(bu\h'+03'\c
2574 .\}
2575 .el \{\
2576 . sp -1
2577 . IP \(bu 2.3
2578 .\}
2579 The ccache overhead of a cache miss will be much smaller.
2580 .RE
2581 .sp
2582 .RS 4
2583 .ie n \{\
2584 \h'-04'\(bu\h'+03'\c
2585 .\}
2586 .el \{\
2587 . sp -1
2588 . IP \(bu 2.3
2589 .\}
2590 Not running the preprocessor at all can be good if compilation is performed
2591 remotely, for instance when using distcc or similar; ccache then won\(cqt make
2592 potentially costly preprocessor calls on the local machine.
2593 .RE
2594 .sp
2595 Disadvantages:
2596 .sp
2597 .RS 4
2598 .ie n \{\
2599 \h'-04'\(bu\h'+03'\c
2600 .\}
2601 .el \{\
2602 . sp -1
2603 . IP \(bu 2.3
2604 .\}
2605 The cache hit rate will likely be lower since any change to compiler options
2606 or source code will make the hash different. Compare this with the default
2607 setup where ccache will fall back to the preprocessor mode, which is tolerant
2608 to some types of changes of compiler options and source code changes.
2609 .RE
2610 .sp
2611 .RS 4
2612 .ie n \{\
2613 \h'-04'\(bu\h'+03'\c
2614 .\}
2615 .el \{\
2616 . sp -1
2617 . IP \(bu 2.3
2618 .\}
2619 If \-MD is used, the manifest entries will include system header files as
2620 well, thus slowing down cache hits slightly, just as using \-MD slows down
2621 make.
2622 .RE
2623 .sp
2624 .RS 4
2625 .ie n \{\
2626 \h'-04'\(bu\h'+03'\c
2627 .\}
2628 .el \{\
2629 . sp -1
2630 . IP \(bu 2.3
2631 .\}
2632 If \-MMD is used, the manifest entries will not include system header files,
2633 which means ccache will ignore changes in them.
2634 .RE
2635 .sp
2636 The depend mode will be disabled if any of the following holds:
2637 .sp
2638 .RS 4
2639 .ie n \{\
2640 \h'-04'\(bu\h'+03'\c
2641 .\}
2642 .el \{\
2643 . sp -1
2644 . IP \(bu 2.3
2645 .\}
2646 \fBdepend_mode\fP is false.
2647 .RE
2648 .sp
2649 .RS 4
2650 .ie n \{\
2651 \h'-04'\(bu\h'+03'\c
2652 .\}
2653 .el \{\
2654 . sp -1
2655 . IP \(bu 2.3
2656 .\}
2657 \fBrun_second_cpp\fP is false.
2658 .RE
2659 .sp
2660 .RS 4
2661 .ie n \{\
2662 \h'-04'\(bu\h'+03'\c
2663 .\}
2664 .el \{\
2665 . sp -1
2666 . IP \(bu 2.3
2667 .\}
2668 The compiler is not generating dependencies using \fB\-MD\fP or \fB\-MMD\fP.
2669 .RE
2670 .SH "HANDLING OF NEWLY CREATED HEADER FILES"
2671 .sp
2672 If modification time (mtime) or status change time (ctime) of one of the include
2673 files is the same second as the time compilation is being done, ccache disables
2674 the direct mode (or, in the case of a precompiled
2675 header, disables caching completely). This done as a safety measure to avoid a
2676 race condition (see below).
2677 .sp
2678 To be able to use a newly created header files in direct mode (or use a newly
2679 precompiled header), either:
2680 .sp
2681 .RS 4
2682 .ie n \{\
2683 \h'-04'\(bu\h'+03'\c
2684 .\}
2685 .el \{\
2686 . sp -1
2687 . IP \(bu 2.3
2688 .\}
2689 create the include file earlier in the build process, or
2690 .RE
2691 .sp
2692 .RS 4
2693 .ie n \{\
2694 \h'-04'\(bu\h'+03'\c
2695 .\}
2696 .el \{\
2697 . sp -1
2698 . IP \(bu 2.3
2699 .\}
2700 set \fBsloppiness\fP to
2701 \fBinclude_file_ctime,include_file_mtime\fP if you are willing to take the risk,
2702 for instance if you know that your build system is robust enough not to
2703 trigger the race condition.
2704 .RE
2705 .sp
2706 For reference, the race condition mentioned above consists of these events:
2707 .sp
2708 .RS 4
2709 .ie n \{\
2710 \h'-04' 1.\h'+01'\c
2711 .\}
2712 .el \{\
2713 . sp -1
2714 . IP " 1." 4.2
2715 .\}
2716 The preprocessor is run.
2717 .RE
2718 .sp
2719 .RS 4
2720 .ie n \{\
2721 \h'-04' 2.\h'+01'\c
2722 .\}
2723 .el \{\
2724 . sp -1
2725 . IP " 2." 4.2
2726 .\}
2727 An include file is modified by someone.
2728 .RE
2729 .sp
2730 .RS 4
2731 .ie n \{\
2732 \h'-04' 3.\h'+01'\c
2733 .\}
2734 .el \{\
2735 . sp -1
2736 . IP " 3." 4.2
2737 .\}
2738 The new include file is hashed by ccache.
2739 .RE
2740 .sp
2741 .RS 4
2742 .ie n \{\
2743 \h'-04' 4.\h'+01'\c
2744 .\}
2745 .el \{\
2746 . sp -1
2747 . IP " 4." 4.2
2748 .\}
2749 The real compiler is run on the preprocessor\(cqs output, which contains data
2750 from the old header file.
2751 .RE
2752 .sp
2753 .RS 4
2754 .ie n \{\
2755 \h'-04' 5.\h'+01'\c
2756 .\}
2757 .el \{\
2758 . sp -1
2759 . IP " 5." 4.2
2760 .\}
2761 The wrong object file is stored in the cache.
2762 .RE
2763 .SH "CACHE DEBUGGING"
2764 .sp
2765 To find out what information ccache actually is hashing, you can enable the
2766 debug mode via the configuration option \fBdebug\fP or by setting
2767 \fBCCACHE_DEBUG\fP in the environment. This can be useful if you are investigating
2768 why you don\(cqt get cache hits. Note that performance will be reduced slightly.
2769 .sp
2770 When the debug mode is enabled, ccache will create up to five additional files
2771 next to the object file:
2772 .TS
2773 allbox tab(:);
2774 lt lt.
2775 T{
2776 .sp
2777 \fBFilename\fP
2778 T}:T{
2779 .sp
2780 \fBDescription\fP
2781 T}
2782 T{
2783 .sp
2784 \fB<objectfile>.ccache\-input\-c\fP
2785 T}:T{
2786 .sp
2787 Binary input hashed by both the direct mode and the preprocessor mode.
2788 T}
2789 T{
2790 .sp
2791 \fB<objectfile>.ccache\-input\-d\fP
2792 T}:T{
2793 .sp
2794 Binary input only hashed by the direct mode.
2795 T}
2796 T{
2797 .sp
2798 \fB<objectfile>.ccache\-input\-p\fP
2799 T}:T{
2800 .sp
2801 Binary input only hashed by the preprocessor mode.
2802 T}
2803 T{
2804 .sp
2805 \fB<objectfile>.ccache\-input\-text\fP
2806 T}:T{
2807 .sp
2808 Human\-readable combined diffable text version of the three files above.
2809 T}
2810 T{
2811 .sp
2812 \fB<objectfile>.ccache\-log\fP
2813 T}:T{
2814 .sp
2815 Log for this object file.
2816 T}
2817 .TE
2818 .sp
2819 .sp
2820 If \fBconfig_dir\fP (environment variable \fBCCACHE_DEBUGDIR\fP) is
2821 set, the files above will be written to that directory with full absolute paths
2822 instead of next to the object file.
2823 .sp
2824 In the direct mode, ccache uses the 160 bit BLAKE3 hash of the
2825 \(lqccache\-input\-c\(rq + \(lqccache\-input\-d\(rq data (where \fB+\fP means concatenation),
2826 while the \(lqccache\-input\-c\(rq + \(lqccache\-input\-p\(rq data is used in the
2827 preprocessor mode.
2828 .sp
2829 The \(lqccache\-input\-text\(rq file is a combined text version of the three binary
2830 input files. It has three sections (\(lqCOMMON\(rq, \(lqDIRECT MODE\(rq and
2831 \(lqPREPROCESSOR MODE\(rq), which is turn contain annotations that say what kind of
2832 data comes next.
2833 .sp
2834 To debug why you don\(cqt get an expected cache hit for an object file, you can do
2835 something like this:
2836 .sp
2837 .RS 4
2838 .ie n \{\
2839 \h'-04' 1.\h'+01'\c
2840 .\}
2841 .el \{\
2842 . sp -1
2843 . IP " 1." 4.2
2844 .\}
2845 Build with debug mode enabled.
2846 .RE
2847 .sp
2848 .RS 4
2849 .ie n \{\
2850 \h'-04' 2.\h'+01'\c
2851 .\}
2852 .el \{\
2853 . sp -1
2854 . IP " 2." 4.2
2855 .\}
2856 Save the \fB<objectfile>.ccache\-*\fP files.
2857 .RE
2858 .sp
2859 .RS 4
2860 .ie n \{\
2861 \h'-04' 3.\h'+01'\c
2862 .\}
2863 .el \{\
2864 . sp -1
2865 . IP " 3." 4.2
2866 .\}
2867 Build again with debug mode enabled.
2868 .RE
2869 .sp
2870 .RS 4
2871 .ie n \{\
2872 \h'-04' 4.\h'+01'\c
2873 .\}
2874 .el \{\
2875 . sp -1
2876 . IP " 4." 4.2
2877 .\}
2878 Compare \fB<objectfile>.ccache\-input\-text\fP for the two builds. This together
2879 with the \fB<objectfile>.ccache\-log\fP files should give you some clues about
2880 what is happening.
2881 .RE
2882 .SH "COMPILING IN DIFFERENT DIRECTORIES"
2883 .sp
2884 Some information included in the hash that identifies a unique compilation can
2885 contain absolute paths:
2886 .sp
2887 .RS 4
2888 .ie n \{\
2889 \h'-04'\(bu\h'+03'\c
2890 .\}
2891 .el \{\
2892 . sp -1
2893 . IP \(bu 2.3
2894 .\}
2895 The preprocessed source code may contain absolute paths to include files if
2896 the compiler option \fB\-g\fP is used or if absolute paths are given to \fB\-I\fP and
2897 similar compiler options.
2898 .RE
2899 .sp
2900 .RS 4
2901 .ie n \{\
2902 \h'-04'\(bu\h'+03'\c
2903 .\}
2904 .el \{\
2905 . sp -1
2906 . IP \(bu 2.3
2907 .\}
2908 Paths specified by compiler options (such as \fB\-I\fP, \fB\-MF\fP, etc) on the command
2909 line may be absolute.
2910 .RE
2911 .sp
2912 .RS 4
2913 .ie n \{\
2914 \h'-04'\(bu\h'+03'\c
2915 .\}
2916 .el \{\
2917 . sp -1
2918 . IP \(bu 2.3
2919 .\}
2920 The source code file path may be absolute, and that path may substituted for
2921 \fB__FILE__\fP macros in the source code or included in warnings emitted to
2922 standard error by the preprocessor.
2923 .RE
2924 .sp
2925 This means that if you compile the same code in different locations, you can\(cqt
2926 share compilation results between the different build directories since you get
2927 cache misses because of the absolute build directory paths that are part of the
2928 hash.
2929 .sp
2930 Here\(cqs what can be done to enable cache hits between different build
2931 directories:
2932 .sp
2933 .RS 4
2934 .ie n \{\
2935 \h'-04'\(bu\h'+03'\c
2936 .\}
2937 .el \{\
2938 . sp -1
2939 . IP \(bu 2.3
2940 .\}
2941 If you build with \fB\-g\fP (or similar) to add debug information to the object
2942 file, you must either:
2943 .sp
2944 .RS 4
2945 .ie n \{\
2946 \h'-04'\(bu\h'+03'\c
2947 .\}
2948 .el \{\
2949 . sp -1
2950 . IP \(bu 2.3
2951 .\}
2952 use the compiler option \fB\-fdebug\-prefix\-map=<old>=<new>\fP for relocating
2953 debug info to a common prefix (e.g. \fB\-fdebug\-prefix\-map=$PWD=.\fP); or
2954 .RE
2955 .sp
2956 .RS 4
2957 .ie n \{\
2958 \h'-04'\(bu\h'+03'\c
2959 .\}
2960 .el \{\
2961 . sp -1
2962 . IP \(bu 2.3
2963 .\}
2964 set \fBhash_dir = false\fP.
2965 .RE
2966 .RE
2967 .sp
2968 .RS 4
2969 .ie n \{\
2970 \h'-04'\(bu\h'+03'\c
2971 .\}
2972 .el \{\
2973 . sp -1
2974 . IP \(bu 2.3
2975 .\}
2976 If you use absolute paths anywhere on the command line (e.g. the source code
2977 file path or an argument to compiler options like \fB\-I\fP and \fB\-MF\fP), you must
2978 set \fBbase_dir\fP to an absolute path to a \(lqbase
2979 directory\(rq. Ccache will then rewrite absolute paths under that directory to
2980 relative before computing the hash.
2981 .RE
2982 .SH "PRECOMPILED HEADERS"
2983 .sp
2984 Ccache has support for GCC\(cqs precompiled headers. However, you have to do some
2985 things to make it work properly:
2986 .sp
2987 .RS 4
2988 .ie n \{\
2989 \h'-04'\(bu\h'+03'\c
2990 .\}
2991 .el \{\
2992 . sp -1
2993 . IP \(bu 2.3
2994 .\}
2995 You must set \fBsloppiness\fP to \fBpch_defines,time_macros\fP.
2996 The reason is that ccache can\(cqt tell whether \fB__TIME__\fP, \fB__DATE__\fP or
2997 \fB__TIMESTAMP__\fP is used when using a precompiled header. Further, it can\(cqt
2998 detect changes in \fB#define\fPs in the source code because of how preprocessing
2999 works in combination with precompiled headers.
3000 .RE
3001 .sp
3002 .RS 4
3003 .ie n \{\
3004 \h'-04'\(bu\h'+03'\c
3005 .\}
3006 .el \{\
3007 . sp -1
3008 . IP \(bu 2.3
3009 .\}
3010 You may also want to include \fBinclude_file_mtime,include_file_ctime\fP in
3011 \fBsloppiness\fP. See
3012 \fIHANDLING OF NEWLY CREATED HEADER FILES\fP.
3013 .RE
3014 .sp
3015 .RS 4
3016 .ie n \{\
3017 \h'-04'\(bu\h'+03'\c
3018 .\}
3019 .el \{\
3020 . sp -1
3021 . IP \(bu 2.3
3022 .\}
3023 You must either:
3024 .sp
3025 .RS 4
3026 .ie n \{\
3027 \h'-04'\(bu\h'+03'\c
3028 .\}
3029 .el \{\
3030 . sp -1
3031 . IP \(bu 2.3
3032 .\}
3033 use the compiler option \fB\-include\fP to include the precompiled header (i.e.,
3034 don\(cqt use \fB#include\fP in the source code to include the header; the filename
3035 itself must be sufficient to find the header, i.e. \fB\-I\fP paths are not
3036 searched); or
3037 .RE
3038 .sp
3039 .RS 4
3040 .ie n \{\
3041 \h'-04'\(bu\h'+03'\c
3042 .\}
3043 .el \{\
3044 . sp -1
3045 . IP \(bu 2.3
3046 .\}
3047 (for the Clang compiler) use the compiler option \fB\-include\-pch\fP to include
3048 the PCH file generated from the precompiled header; or
3049 .RE
3050 .sp
3051 .RS 4
3052 .ie n \{\
3053 \h'-04'\(bu\h'+03'\c
3054 .\}
3055 .el \{\
3056 . sp -1
3057 . IP \(bu 2.3
3058 .\}
3059 (for the GCC compiler) add the compiler option \fB\-fpch\-preprocess\fP when
3060 compiling.
3061 .RE
3062 .sp
3063 If you don\(cqt do this, either the non\-precompiled version of the header file will
3064 be used (if available) or ccache will fall back to running the real compiler and
3065 increase the statistics counter \(lqPreprocessing failed\(rq (if the non\-precompiled
3066 header file is not available).
3067 .RE
3068 .SH "C++ MODULES"
3069 .sp
3070 Ccache has support for Clang\(cqs \fB\-fmodules\fP option. In practice ccache only
3071 additionally hashes \fBmodule.modulemap\fP files; it does not know how Clang
3072 handles its cached binary form of modules so those are ignored. This should not
3073 matter in practice: as long as everything else (including \fBmodule.modulemap\fP
3074 files) is the same the cached result should work. Still, you must set
3075 \fBsloppiness\fP to \fBmodules\fP to allow caching.
3076 .sp
3077 You must use both \fBdirect mode\fP and
3078 \fBdepend mode\fP. When using
3079 the preprocessor mode Clang does not provide enough
3080 information to allow hashing of \fBmodule.modulemap\fP files.
3081 .SH "SHARING A CACHE"
3082 .sp
3083 A group of developers can increase the cache hit rate by sharing a cache
3084 directory. To share a cache without unpleasant side effects, the following
3085 conditions should to be met:
3086 .sp
3087 .RS 4
3088 .ie n \{\
3089 \h'-04'\(bu\h'+03'\c
3090 .\}
3091 .el \{\
3092 . sp -1
3093 . IP \(bu 2.3
3094 .\}
3095 Use the same cache directory.
3096 .RE
3097 .sp
3098 .RS 4
3099 .ie n \{\
3100 \h'-04'\(bu\h'+03'\c
3101 .\}
3102 .el \{\
3103 . sp -1
3104 . IP \(bu 2.3
3105 .\}
3106 Make sure that the configuration option \fBhard_link\fP is
3107 false (which is the default).
3108 .RE
3109 .sp
3110 .RS 4
3111 .ie n \{\
3112 \h'-04'\(bu\h'+03'\c
3113 .\}
3114 .el \{\
3115 . sp -1
3116 . IP \(bu 2.3
3117 .\}
3118 Make sure that all users are in the same group.
3119 .RE
3120 .sp
3121 .RS 4
3122 .ie n \{\
3123 \h'-04'\(bu\h'+03'\c
3124 .\}
3125 .el \{\
3126 . sp -1
3127 . IP \(bu 2.3
3128 .\}
3129 Set the configuration option \fBumask\fP to \fB002\fP. This ensures
3130 that cached files are accessible to everyone in the group.
3131 .RE
3132 .sp
3133 .RS 4
3134 .ie n \{\
3135 \h'-04'\(bu\h'+03'\c
3136 .\}
3137 .el \{\
3138 . sp -1
3139 . IP \(bu 2.3
3140 .\}
3141 Make sure that all users have write permission in the entire cache directory
3142 (and that you trust all users of the shared cache).
3143 .RE
3144 .sp
3145 .RS 4
3146 .ie n \{\
3147 \h'-04'\(bu\h'+03'\c
3148 .\}
3149 .el \{\
3150 . sp -1
3151 . IP \(bu 2.3
3152 .\}
3153 Make sure that the setgid bit is set on all directories in the cache. This
3154 tells the filesystem to inherit group ownership for new directories. The
3155 following command might be useful for this:
3156 .sp
3157 .if n .RS 4
3158 .nf
3159 .fam C
3160 find $CCACHE_DIR \-type d | xargs chmod g+s
3161 .fam
3162 .fi
3163 .if n .RE
3164 .RE
3165 .sp
3166 The reason to avoid the hard link mode is that the hard links cause unwanted
3167 side effects, as all links to a cached file share the file\(cqs modification
3168 timestamp. This results in false dependencies to be triggered by
3169 timestamp\-based build systems whenever another user links to an existing file.
3170 Typically, users will see that their libraries and binaries are relinked
3171 without reason.
3172 .sp
3173 You may also want to make sure that a base directory is set appropriately, as
3174 discussed in a previous section.
3175 .SH "SHARING A CACHE ON NFS"
3176 .sp
3177 It is possible to put the cache directory on an NFS filesystem (or similar
3178 filesystems), but keep in mind that:
3179 .sp
3180 .RS 4
3181 .ie n \{\
3182 \h'-04'\(bu\h'+03'\c
3183 .\}
3184 .el \{\
3185 . sp -1
3186 . IP \(bu 2.3
3187 .\}
3188 Having the cache on NFS may slow down compilation. Make sure to do some
3189 benchmarking to see if it\(cqs worth it.
3190 .RE
3191 .sp
3192 .RS 4
3193 .ie n \{\
3194 \h'-04'\(bu\h'+03'\c
3195 .\}
3196 .el \{\
3197 . sp -1
3198 . IP \(bu 2.3
3199 .\}
3200 Ccache hasn\(cqt been tested very thoroughly on NFS.
3201 .RE
3202 .sp
3203 A tip is to set \fBtemporary_dir\fP to a directory on the
3204 local host to avoid NFS traffic for temporary files.
3205 .sp
3206 It is recommended to use the same operating system version when using a shared
3207 cache. If operating system versions are different then system include files
3208 will likely be different and there will be few or no cache hits between the
3209 systems. One way of improving cache hit rate in that case is to set
3210 \fBsloppiness\fP to \fBsystem_headers\fP to ignore system
3211 headers.
3212 .sp
3213 An alternative to putting the main cache directory on NFS is to set up a
3214 secondary storage file cache.
3215 .SH "USING CCACHE WITH OTHER COMPILER WRAPPERS"
3216 .sp
3217 The recommended way of combining ccache with another compiler wrapper (such as
3218 \(lqdistcc\(rq) is by letting ccache execute the compiler wrapper. This is
3219 accomplished by defining \fBprefix_command\fP, for
3220 example by setting the environment variable \fBCCACHE_PREFIX\fP to the name of the
3221 wrapper (e.g. \fBdistcc\fP). Ccache will then prefix the command line with the
3222 specified command when running the compiler. To specify several prefix
3223 commands, set \fBprefix_command\fP to a colon\-separated
3224 list of commands.
3225 .sp
3226 Unless you set \fBcompiler_check\fP to a suitable command
3227 (see the description of that configuration option), it is not recommended to use
3228 the form \fBccache anotherwrapper compiler args\fP as the compilation command. It\(cqs
3229 also not recommended to use the masquerading technique for the other compiler
3230 wrapper. The reason is that by default, ccache will in both cases hash the mtime
3231 and size of the other wrapper instead of the real compiler, which means that:
3232 .sp
3233 .RS 4
3234 .ie n \{\
3235 \h'-04'\(bu\h'+03'\c
3236 .\}
3237 .el \{\
3238 . sp -1
3239 . IP \(bu 2.3
3240 .\}
3241 Compiler upgrades will not be detected properly.
3242 .RE
3243 .sp
3244 .RS 4
3245 .ie n \{\
3246 \h'-04'\(bu\h'+03'\c
3247 .\}
3248 .el \{\
3249 . sp -1
3250 . IP \(bu 2.3
3251 .\}
3252 The cached results will not be shared between compilations with and without
3253 the other wrapper.
3254 .RE
3255 .sp
3256 Another minor thing is that if \fBprefix_command\fP is
3257 used, ccache will not invoke the other wrapper when running the preprocessor,
3258 which increases performance. You can use
3259 \fBprefix_command_cpp\fP if you also want to invoke
3260 the other wrapper when doing preprocessing (normally by adding \fB\-E\fP).
3261 .SH "CAVEATS"
3262 .sp
3263 .RS 4
3264 .ie n \{\
3265 \h'-04'\(bu\h'+03'\c
3266 .\}
3267 .el \{\
3268 . sp -1
3269 . IP \(bu 2.3
3270 .\}
3271 The direct mode fails to pick up new header files in some rare scenarios. See
3272 \fIThe direct mode\fP above.
3273 .RE
3274 .SH "TROUBLESHOOTING"
3275 .SS "General"
3276 .sp
3277 A general tip for getting information about what ccache is doing is to enable
3278 debug logging by setting the configuration option \fBdebug\fP (or
3279 the environment variable \fBCCACHE_DEBUG\fP); see \fICACHE DEBUGGING\fP
3280 for more information. Another way of keeping track of what is
3281 happening is to check the output of \fBccache \-s\fP.
3282 .SS "Performance"
3283 .sp
3284 Ccache has been written to perform well out of the box, but sometimes you may
3285 have to do some adjustments of how you use the compiler and ccache in order to
3286 improve performance.
3287 .sp
3288 Since ccache works best when I/O is fast, put the cache directory on a fast
3289 storage device if possible. Having lots of free memory so that files in the
3290 cache directory stay in the disk cache is also preferable.
3291 .sp
3292 A good way of monitoring how well ccache works is to run \fBccache \-s\fP before and
3293 after your build and then compare the statistics counters. Here are some common
3294 problems and what may be done to increase the hit rate:
3295 .sp
3296 .RS 4
3297 .ie n \{\
3298 \h'-04'\(bu\h'+03'\c
3299 .\}
3300 .el \{\
3301 . sp -1
3302 . IP \(bu 2.3
3303 .\}
3304 If the counter for preprocessed cache hits has been incremented instead of the
3305 one for direct cache hits, ccache has fallen back to preprocessor mode, which
3306 is generally slower. Some possible reasons are:
3307 .sp
3308 .RS 4
3309 .ie n \{\
3310 \h'-04'\(bu\h'+03'\c
3311 .\}
3312 .el \{\
3313 . sp -1
3314 . IP \(bu 2.3
3315 .\}
3316 The source code has been modified in such a way that the preprocessor output
3317 is not affected.
3318 .RE
3319 .sp
3320 .RS 4
3321 .ie n \{\
3322 \h'-04'\(bu\h'+03'\c
3323 .\}
3324 .el \{\
3325 . sp -1
3326 . IP \(bu 2.3
3327 .\}
3328 Compiler arguments that are hashed in the direct mode but not in the
3329 preprocessor mode have changed (\fB\-I\fP, \fB\-include\fP, \fB\-D\fP, etc) and they didn\(cqt
3330 affect the preprocessor output.
3331 .RE
3332 .sp
3333 .RS 4
3334 .ie n \{\
3335 \h'-04'\(bu\h'+03'\c
3336 .\}
3337 .el \{\
3338 . sp -1
3339 . IP \(bu 2.3
3340 .\}
3341 The compiler option \fB\-Xpreprocessor\fP or \fB\-Wp,*\fP (except \fB\-Wp,\-MD,<path>\fP,
3342 \fB\-Wp,\-MMD,<path>\fP, and \fB\-Wp,\-D<define>\fP) is used.
3343 .RE
3344 .sp
3345 .RS 4
3346 .ie n \{\
3347 \h'-04'\(bu\h'+03'\c
3348 .\}
3349 .el \{\
3350 . sp -1
3351 . IP \(bu 2.3
3352 .\}
3353 This was the first compilation with a new value of the
3354 base directory.
3355 .RE
3356 .sp
3357 .RS 4
3358 .ie n \{\
3359 \h'-04'\(bu\h'+03'\c
3360 .\}
3361 .el \{\
3362 . sp -1
3363 . IP \(bu 2.3
3364 .\}
3365 A modification or status change time of one of the include files is too new
3366 (created the same second as the compilation is being done). See
3367 \fIHANDLING OF NEWLY CREATED HEADER FILES\fP.
3368 .RE
3369 .sp
3370 .RS 4
3371 .ie n \{\
3372 \h'-04'\(bu\h'+03'\c
3373 .\}
3374 .el \{\
3375 . sp -1
3376 . IP \(bu 2.3
3377 .\}
3378 The \fB__TIME__\fP preprocessor macro is (potentially) being used. Ccache turns
3379 off direct mode if \fB__TIME__\fP is present in the source code. This is done
3380 as a safety measure since the string indicates that a \fB__TIME__\fP macro
3381 \fImay\fP affect the output. (To be sure, ccache would have to run the
3382 preprocessor, but the sole point of the direct mode is to avoid that.) If you
3383 know that \fB__TIME__\fP isn\(cqt used in practise, or don\(cqt care if ccache
3384 produces objects where \fB__TIME__\fP is expanded to something in the past, you
3385 can set \fBsloppiness\fP to \fBtime_macros\fP.
3386 .RE
3387 .sp
3388 .RS 4
3389 .ie n \{\
3390 \h'-04'\(bu\h'+03'\c
3391 .\}
3392 .el \{\
3393 . sp -1
3394 . IP \(bu 2.3
3395 .\}
3396 The \fB__DATE__\fP preprocessor macro is (potentially) being used and the date
3397 has changed. This is similar to how \fB__TIME__\fP is handled. If \fB__DATE__\fP
3398 is present in the source code, ccache hashes the current date in order to be
3399 able to produce the correct object file if the \fB__DATE__\fP macro affects the
3400 output. If you know that \fB__DATE__\fP isn\(cqt used in practise, or don\(cqt care
3401 if ccache produces objects where \fB__DATE__\fP is expanded to something in the
3402 past, you can set \fBsloppiness\fP to \fBtime_macros\fP.
3403 .RE
3404 .sp
3405 .RS 4
3406 .ie n \{\
3407 \h'-04'\(bu\h'+03'\c
3408 .\}
3409 .el \{\
3410 . sp -1
3411 . IP \(bu 2.3
3412 .\}
3413 The \fB__TIMESTAMP__\fP preprocessor macro is (potentially) being used and the
3414 source file\(cqs modification time has changed. This is similar to how
3415 \fB__TIME__\fP is handled. If \fB__TIMESTAMP__\fP is present in the source code,
3416 ccache hashes the string representation of the source file\(cqs modification
3417 time in order to be able to produce the correct object file if the
3418 \fB__TIMESTAMP__\fP macro affects the output. If you know that
3419 \fB__TIMESTAMP__\fP isn\(cqt used in practise, or don\(cqt care if ccache produces
3420 objects where \fB__TIMESTAMP__\fP is expanded to something in the past, you can
3421 set \fBsloppiness\fP to \fBtime_macros\fP.
3422 .RE
3423 .sp
3424 .RS 4
3425 .ie n \{\
3426 \h'-04'\(bu\h'+03'\c
3427 .\}
3428 .el \{\
3429 . sp -1
3430 . IP \(bu 2.3
3431 .\}
3432 The input file path has changed. Ccache includes the input file path in the
3433 direct mode hash to be able to take relative include files into account and
3434 to produce a correct object file if the source code includes a \fB__FILE__\fP
3435 macro.
3436 .RE
3437 .RE
3438 .sp
3439 .RS 4
3440 .ie n \{\
3441 \h'-04'\(bu\h'+03'\c
3442 .\}
3443 .el \{\
3444 . sp -1
3445 . IP \(bu 2.3
3446 .\}
3447 If a cache hit counter was not incremented even though the same code has been
3448 compiled and cached before, ccache has either detected that something has
3449 changed anyway or a cleanup has been performed (either explicitly or
3450 implicitly when a cache limit has been reached). Some perhaps unobvious things
3451 that may result in a cache miss are usage of \fB__TIME__\fP, \fB__DATE__\fP or
3452 \fB__TIMESTAMP__\fP macros, or use of automatically generated code that contains
3453 a timestamp, build counter or other volatile information.
3454 .RE
3455 .sp
3456 .RS 4
3457 .ie n \{\
3458 \h'-04'\(bu\h'+03'\c
3459 .\}
3460 .el \{\
3461 . sp -1
3462 . IP \(bu 2.3
3463 .\}
3464 If \(lqMultiple source files\(rq has been incremented, it\(cqs an indication that the
3465 compiler has been invoked on several source code files at once. Ccache doesn\(cqt
3466 support that. Compile the source code files separately if possible.
3467 .RE
3468 .sp
3469 .RS 4
3470 .ie n \{\
3471 \h'-04'\(bu\h'+03'\c
3472 .\}
3473 .el \{\
3474 . sp -1
3475 . IP \(bu 2.3
3476 .\}
3477 If \(lqUnsupported compiler option\(rq has been incremented, enable debug logging
3478 and check which compiler option was rejected.
3479 .RE
3480 .sp
3481 .RS 4
3482 .ie n \{\
3483 \h'-04'\(bu\h'+03'\c
3484 .\}
3485 .el \{\
3486 . sp -1
3487 . IP \(bu 2.3
3488 .\}
3489 If \(lqPreprocessing failed\(rq has been incremented, one possible reason is that
3490 precompiled headers are being used. See \fIPRECOMPILED HEADERS\fP for how to
3491 remedy this.
3492 .RE
3493 .sp
3494 .RS 4
3495 .ie n \{\
3496 \h'-04'\(bu\h'+03'\c
3497 .\}
3498 .el \{\
3499 . sp -1
3500 . IP \(bu 2.3
3501 .\}
3502 If \(lqCould not use precompiled header\(rq has been incremented, see
3503 \fIPRECOMPILED HEADERS\fP.
3504 .RE
3505 .sp
3506 .RS 4
3507 .ie n \{\
3508 \h'-04'\(bu\h'+03'\c
3509 .\}
3510 .el \{\
3511 . sp -1
3512 . IP \(bu 2.3
3513 .\}
3514 If \(lqCould not use modules\(rq has been incremented, see \fIC++ MODULES\fP.
3515 .RE
3516 .SS "Corrupt object files"
3517 .sp
3518 It should be noted that ccache is susceptible to general storage problems. If a
3519 bad object file sneaks into the cache for some reason, it will of course stay
3520 bad. Some possible reasons for erroneous object files are bad hardware (disk
3521 drive, disk controller, memory, etc), buggy drivers or file systems, a bad
3522 \fBprefix_command\fP or compiler wrapper. If this
3523 happens, the easiest way of fixing it is this:
3524 .sp
3525 .RS 4
3526 .ie n \{\
3527 \h'-04' 1.\h'+01'\c
3528 .\}
3529 .el \{\
3530 . sp -1
3531 . IP " 1." 4.2
3532 .\}
3533 Build so that the bad object file ends up in the build tree.
3534 .RE
3535 .sp
3536 .RS 4
3537 .ie n \{\
3538 \h'-04' 2.\h'+01'\c
3539 .\}
3540 .el \{\
3541 . sp -1
3542 . IP " 2." 4.2
3543 .\}
3544 Remove the bad object file from the build tree.
3545 .RE
3546 .sp
3547 .RS 4
3548 .ie n \{\
3549 \h'-04' 3.\h'+01'\c
3550 .\}
3551 .el \{\
3552 . sp -1
3553 . IP " 3." 4.2
3554 .\}
3555 Rebuild with \fBCCACHE_RECACHE\fP set.
3556 .RE
3557 .sp
3558 An alternative is to clear the whole cache with \fBccache \-C\fP if you don\(cqt mind
3559 losing other cached results.
3560 .sp
3561 There are no reported issues about ccache producing broken object files
3562 reproducibly. That doesn\(cqt mean it can\(cqt happen, so if you find a repeatable
3563 case, please report it.
3564 .SH "MORE INFORMATION"
3565 .sp
3566 Credits, mailing list information, bug reporting instructions, source code,
3567 etc, can be found on ccache\(cqs web site: \c
3568 .URL "https://ccache.dev" "" "."
3569 .SH "AUTHOR"
3570 .sp
3571 Ccache was originally written by Andrew Tridgell and is currently developed and
3572 maintained by Joel Rosdahl. See AUTHORS.txt or AUTHORS.html and
3573 .URL "https://ccache.dev/credits.html" "" ""
3574 for a list of contributors.
|
