1CCACHE(1) ccache Manual CCACHE(1)
2
6 ccache - a fast C/C++ compiler cache
7
9 ccache [options]
10 ccache compiler [compiler options]
11 compiler [compiler options] (via symbolic link)
12
14 ccache is a compiler cache. It speeds up recompilation by caching the
15 result of previous compilations and detecting when the same compilation
16 is being done again. Supported languages are C, C++, Objective-C and
17 Objective-C++.
18 ccache has been carefully written to always produce exactly the same
20 compiler output that you would get without the cache. The only way you
21 should be able to tell that you are using ccache is the speed.
22 Currently known exceptions to this goal are listed under CAVEATS. If
23 you ever discover an undocumented case where ccache changes the output
24 of your compiler, please let us know.
25 Features
27 · Keeps statistics on hits/misses.
28 · Automatic cache size management.
30 · Can cache compilations that generate warnings.
32 · Easy installation.
34 · Low overhead.
36 · Optionally compresses files in the cache to reduce disk space.
38 Limitations
40 · Only knows how to cache the compilation of a single
41 C/C++/Objective-C/Objective-C++ file. Other types of compilations
42 (multi-file compilation, linking, etc) will silently fall back to
43 running the real compiler.
44 · Only works with GCC and compilers that behave similar enough.
46 · Some compiler flags are not supported. If such a flag is detected,
48 ccache will silently fall back to running the real compiler.
49
51 There are two ways to use ccache. You can either prefix your
52 compilation commands with ccache or you can let ccache masquerade as
53 the compiler by creating a symbolic link (named as the compiler) to
54 ccache. The first method is most convenient if you just want to try out
55 ccache or wish to use it for some specific projects. The second method
56 is most useful for when you wish to use ccache for all your
57 compilations.
58 To use the first method, just make sure that ccache is in your PATH.
60 To use the symlinks method, do something like this:
62 cp ccache /usr/local/bin/
64 ln -s ccache /usr/local/bin/gcc
65 ln -s ccache /usr/local/bin/g++
66 ln -s ccache /usr/local/bin/cc
67 ln -s ccache /usr/local/bin/c++
68 And so forth. This will work as long as the directory with symlinks
70 comes before the path to the compiler (which is usually in /usr/bin).
71 After installing you may wish to run “which gcc” to make sure that the
72 correct link is being used.
73 Warning
75 The technique of letting ccache masquerade as the compiler works
76 well, but currently doesn’t interact well with other tools that do
77 the same thing. See USING CCACHE WITH OTHER COMPILER WRAPPERS.
78 Warning
80 Do not use a hard link, use a symbolic link. A hard link will cause
81 “interesting” problems.
82
84 These options only apply when you invoke ccache as “ccache”. When
85 invoked as a compiler (via a symlink as described in the previous
86 section), the normal compiler options apply and you should refer to the
87 compiler’s documentation.
88 -c, --cleanup
90 Clean up the cache by removing old cached files until the specified
91 file number and cache size limits are not exceeded. This also
92 recalculates the cache file count and size totals. Normally, there
93 is no need to initiate cleanup manually as ccache keeps the cache
94 below the specified limits at runtime and keeps statistics up to
95 date on each compilation. Forcing a cleanup is mostly useful if you
96 manually modify the cache contents or believe that the cache size
97 statistics may be inaccurate.
98 -C, --clear
100 Clear the entire cache, removing all cached files, but keeping the
101 configuration file.
102 -F, --max-files=N
104 Set the maximum number of files allowed in the cache. Use 0 for no
105 limit. The value is stored in a configuration file in the cache
106 directory and applies to all future compilations.
107 -h, --help
109 Print an options summary page.
110 -M, --max-size=SIZE
112 Set the maximum size of the files stored in the cache. SIZE should
113 be a number followed by an optional suffix: k, M, G, T (decimal),
114 Ki, Mi, Gi or Ti (binary). The default suffix is G. Use 0 for no
115 limit. The value is stored in a configuration file in the cache
116 directory and applies to all future compilations.
117 -o, --set-config=KEY=VALUE
119 Set configuration KEY to VALUE. See CONFIGURATION for more
120 information.
121 -p, --print-config
123 Print current configuration options and from where they originate
124 (environment variable, configuration file or compile-time default).
125 -s, --show-stats
127 Print the current statistics summary for the cache.
128 -V, --version
130 Print version and copyright information.
131 -z, --zero-stats
133 Zero the cache statistics (but not the configuration options).
134
136 When run as a compiler, ccache usually just takes the same command line
137 options as the compiler you are using. The only exception to this is
138 the option --ccache-skip. That option can be used to tell ccache to
139 avoid interpreting the next option in any way and to pass it along to
140 the compiler as-is.
141 Note
143 --ccache-skip currently only tells ccache not to interpret the next
144 option as a special compiler option — the option will still be
145 included in the direct mode hash.
146 The reason this can be important is that ccache does need to parse the
148 command line and determine what is an input filename and what is a
149 compiler option, as it needs the input filename to determine the name
150 of the resulting object file (among other things). The heuristic ccache
151 uses when parsing the command line is that any argument that exists as
152 a file is treated as an input file name. By using --ccache-skip you can
153 force an option to not be treated as an input file name and instead be
154 passed along to the compiler as a command line option.
155 Another case where --ccache-skip can be useful is if ccache interprets
157 an option specially but shouldn’t, since the option has another meaning
158 for your compiler than what ccache thinks.
159
161 ccache’s default behavior can be overridden by configuration file
162 settings, which in turn can be overridden by environment variables with
163 names starting with CCACHE_. ccache normally reads configuration from
164 two files: first a system-level configuration file and secondly a
165 cache-specific configuration file. The priority of configuration
166 settings is as follows (where 1 is highest):
167 1. Environment variables.
169 2. The cache-specific configuration file <ccachedir>/ccache.conf
171 (typically $HOME/.ccache/ccache.conf).
172 3. The system-wide configuration file <sysconfdir>/ccache.conf
174 (typically /etc/ccache.conf or /usr/local/etc/ccache.conf).
175 4. Compile-time defaults.
177 As a special case, if the environment variable CCACHE_CONFIGPATH is
179 set, ccache reads configuration from the specified path instead of the
180 default paths.
181 Configuration file syntax
183 Configuration files are in a simple “key = value” format, one setting
184 per line. Lines starting with a hash sign are comments. Blank lines are
185 ignored, as is whitespace surrounding keys and values. Example:
186 # Set maximum cache size to 10 GB:
188 max_size = 10G
189 Boolean values
191 Some settings are boolean values (i.e. truth values). In a
192 configuration file, such values must be set to the string true or
193 false. For the corresponding environment variables, the semantics are a
194 bit different: a set environment variable means “true” (even if set to
195 the empty string), the following case-insensitive negative values are
196 considered an error (rather than surprising the user): 0, false,
197 disable and no, and an unset environment variable means “false”. Each
198 boolean environment variable also has a negated form starting with
199 CCACHE_NO. For example, CCACHE_COMPRESS can be set to force compression
200 and CCACHE_NOCOMPRESS can be set to force no compression.
201 Configuration settings
203 Below is a list of available configuration settings. The corresponding
204 environment variable name is indicated in parentheses after each
205 configuration setting key.
206 base_dir (CCACHE_BASEDIR)
208 This setting should be an absolute path to a directory. ccache then
209 rewrites absolute paths into relative paths before computing the
210 hash that identifies the compilation, but only for paths under the
211 specified directory. If set to the empty string (which is the
212 default), no rewriting is done. A typical path to use as the base
213 directory is your home directory or another directory that is a
214 parent of your build directories. Don’t use / as the base directory
215 since that will make ccache also rewrite paths to system header
216 files, which doesn’t gain anything.
217 See also the discussion under COMPILING IN DIFFERENT DIRECTORIES.
219 cache_dir (CCACHE_DIR)
221 This setting specifies where ccache will keep its cached compiler
222 outputs. It will only take effect if set in the system-wide
223 configuration file or as an environment variable. The default is
224 $HOME/.ccache.
225 cache_dir_levels (CCACHE_NLEVELS)
227 This setting allows you to choose the number of directory levels in
228 the cache directory. The default is 2. The minimum is 1 and the
229 maximum is 8.
230 compiler (CCACHE_CC)
232 This setting can be used to force the name of the compiler to use.
233 If set to the empty string (which is the default), ccache works it
234 out from the command line.
235 compiler_check (CCACHE_COMPILERCHECK)
237 By default, ccache includes the modification time (“mtime”) and
238 size of the compiler in the hash to ensure that results retrieved
239 from the cache are accurate. This setting can be used to select
240 another strategy. Possible values are:
241 content
243 Hash the content of the compiler binary. This makes ccache very
244 slightly slower compared to the mtime setting, but makes it
245 cope better with compiler upgrades during a build bootstrapping
246 process.
247 mtime
249 Hash the compiler’s mtime and size, which is fast. This is the
250 default.
251 none
253 Don’t hash anything. This may be good for situations where you
254 can safely use the cached results even though the compiler’s
255 mtime or size has changed (e.g. if the compiler is built as
256 part of your build system and the compiler’s source has not
257 changed, or if the compiler only has changes that don’t affect
258 code generation). You should only use the none setting if you
259 know what you are doing.
260 string:value
262 Use value as the string to calculate hash from. This can be the
263 compiler revision number you retrieved earlier and set here via
264 environment variable.
265 a command string
267 Hash the standard output and standard error output of the
268 specified command. The string will be split on whitespace to
269 find out the command and arguments to run. No other
270 interpretation of the command string will be done, except that
271 the special word %compiler% will be replaced with the path to
272 the compiler. Several commands can be specified with semicolon
273 as separator. Examples:
274 %compiler% -v
276 %compiler% -dumpmachine; %compiler% -dumpversion
278 You should make sure that the specified command is as fast as
280 possible since it will be run once for each ccache invocation.
281 Identifying the compiler using a command is useful if you want
283 to avoid cache misses when the compiler has been rebuilt but
284 not changed.
285 Another case is when the compiler (as seen by ccache) actually
287 isn’t the real compiler but another compiler wrapper — in that
288 case, the default mtime method will hash the mtime and size of
289 the other compiler wrapper, which means that ccache won’t be
290 able to detect a compiler upgrade. Using a suitable command to
291 identify the compiler is thus safer, but it’s also slower, so
292 you should consider continue using the mtime method in
293 combination with the prefix_command setting if possible. See
294 USING CCACHE WITH OTHER COMPILER WRAPPERS.
295 compression (CCACHE_COMPRESS or CCACHE_NOCOMPRESS, see Boolean values
297 above)
298 If true, ccache will compress object files and other compiler
299 output it puts in the cache. However, this setting has no effect on
300 how files are retrieved from the cache; compressed and uncompressed
301 results will still be usable regardless of this setting. The
302 default is false.
303 compression_level (CCACHE_COMPRESSLEVEL)
305 This setting determines the level at which ccache will compress
306 object files. It only has effect if compression is enabled. The
307 value defaults to 6, and must be no lower than 1 (fastest, worst
308 compression) and no higher than 9 (slowest, best compression).
309 cpp_extension (CCACHE_EXTENSION)
311 This setting can be used to force a certain extension for the
312 intermediate preprocessed file. The default is to automatically
313 determine the extension to use for intermediate preprocessor files
314 based on the type of file being compiled, but that sometimes
315 doesn’t work. For example, when using the “aCC” compiler on HP-UX,
316 set the cpp extension to i.
317 direct_mode (CCACHE_DIRECT or CCACHE_NODIRECT, see Boolean values
319 above)
320 If true, the direct mode will be used. The default is true. See THE
321 DIRECT MODE.
322 disable (CCACHE_DISABLE or CCACHE_NODISABLE, see Boolean values above)
324 When true, ccache will just call the real compiler, bypassing the
325 cache completely. The default is false.
326 extra_files_to_hash (CCACHE_EXTRAFILES)
328 This setting is a list of paths to files that ccache will include
329 in the the hash sum that identifies the build. The list separator
330 is semicolon on Windows systems and colon on other systems.
331 hard_link (CCACHE_HARDLINK or CCACHE_NOHARDLINK, see Boolean values
333 above)
334 If true, ccache will attempt to use hard links from the cache
335 directory when creating the compiler output rather than using a
336 file copy. Hard links are never made for compressed cache files.
337 This means that you should not enable compression if you want to
338 use hard links. The default is false.
339 Warning
341 Do not enable this option unless you are aware of the
342 consequences. Using hard links may be slightly faster in some
343 situations, but there are several pitfalls since the resulting
344 object file will share i-node with the cached object file:
345 1. If the resulting object file is modified in any way, the cached
347 object file will be modified as well. For instance, if you run
348 strip object.o or echo >object.o, you will corrupt the cache.
349 2. Programs that rely on modification times (like “make”) can be
351 confused since ccache updates the cached files' modification
352 times as part of the automatic cache size management. This will
353 affect object files in the build tree as well, which can
354 retrigger the linking step even though nothing really has
355 changed.
356 hash_dir (CCACHE_HASHDIR or CCACHE_NOHASHDIR, see Boolean values above)
358 If true (which is the default), ccache will include the current
359 working directory (CWD) in the hash that is used to distinguish two
360 compilations when generating debug info (compiler option -g with
361 variations). Exception: The CWD will not be included in the hash if
362 base_dir is set (and matches the CWD) and the compiler option
363 -fdebug-prefix-map is used. See also the discussion under COMPILING
364 IN DIFFERENT DIRECTORIES.
365 The reason for including the CWD in the hash by default is to
367 prevent a problem with the storage of the current working directory
368 in the debug info of an object file, which can lead ccache to
369 return a cached object file that has the working directory in the
370 debug info set incorrectly.
371 You can disable this setting to get cache hits when compiling the
373 same source code in different directories if you don’t mind that
374 CWD in the debug info might be incorrect.
375 ignore_headers_in_manifest (CCACHE_IGNOREHEADERS)
377 This setting is a list of paths to files (or directories with
378 headers) that ccache will not include in the manifest list that
379 makes up the direct mode. Note that this can cause stale cache hits
380 if those headers do indeed change. The list separator is semicolon
381 on Windows systems and colon on other systems.
382 keep_comments_cpp (CCACHE_COMMENTS or CCACHE_NOCOMMENTS, see Boolean
384 values above)
385 If true, ccache will not discard the comments before hashing
386 preprocessor output. This can be used to check documentation with
387 -Wdocumentation.
388 limit_multiple (CCACHE_LIMIT_MULTIPLE)
390 Sets the limit when cleaning up. Files are deleted (in LRU order)
391 until the levels are below the limit. The default is 0.8 (= 80%).
392 See AUTOMATIC CLEANUP for more information.
393 log_file (CCACHE_LOGFILE)
395 If set to a file path, ccache will write information on what it is
396 doing to the specified file. This is useful for tracking down
397 problems.
398 max_files (CCACHE_MAXFILES)
400 This option specifies the maximum number of files to keep in the
401 cache. Use 0 for no limit (which is the default). See also CACHE
402 SIZE MANAGEMENT.
403 max_size (CCACHE_MAXSIZE)
405 This option specifies the maximum size of the cache. Use 0 for no
406 limit. The default value is 5G. Available suffixes: k, M, G, T
407 (decimal) and Ki, Mi, Gi, Ti (binary). The default suffix is G. See
408 also CACHE SIZE MANAGEMENT.
409 path (CCACHE_PATH)
411 If set, ccache will search directories in this list when looking
412 for the real compiler. The list separator is semicolon on Windows
413 systems and colon on other systems. If not set, ccache will look
414 for the first executable matching the compiler name in the normal
415 PATH that isn’t a symbolic link to ccache itself.
416 prefix_command (CCACHE_PREFIX)
418 This option adds a list of prefixes (separated by space) to the
419 command line that ccache uses when invoking the compiler. See also
420 USING CCACHE WITH OTHER COMPILER WRAPPERS.
421 prefix_command_cpp (CCACHE_PREFIX_CPP)
423 This option adds a list of prefixes (separated by space) to the
424 command line that ccache uses when invoking the preprocessor.
425 read_only (CCACHE_READONLY or CCACHE_NOREADONLY, see Boolean values
427 above)
428 If true, ccache will attempt to use existing cached object files,
429 but it will not to try to add anything new to the cache. If you are
430 using this because your ccache directory is read-only, then you
431 need to set temporary_dir as otherwise ccache will fail to create
432 temporary files.
433 read_only_direct (CCACHE_READONLY_DIRECT or CCACHE_NOREADONLY_DIRECT,
435 see Boolean values above)
436 Just like read_only except that ccache will only try to retrieve
437 results from the cache using the direct mode, not the preprocessor
438 mode. See documentation for read_only regarding using a read-only
439 ccache directory.
440 recache (CCACHE_RECACHE or CCACHE_NORECACHE, see Boolean values above)
442 If true, ccache will not use any previously stored result. New
443 results will still be cached, possibly overwriting any pre-existing
444 results.
445 run_second_cpp (CCACHE_CPP2 or CCACHE_NOCPP2, see Boolean values above)
447 If true, ccache will first run the preprocessor to preprocess the
448 source code (see THE PREPROCESSOR MODE) and then on a cache miss
449 run the compiler on the source code to get hold of the object file.
450 This is the default.
451 If false, ccache will first run preprocessor to preprocess the
453 source code and then on a cache miss run the compiler on the
454 preprocessed source code instead of the original source code. This
455 makes cache misses slightly faster since the source code only has
456 to be preprocessed once. The downside is that some compilers won’t
457 produce the same result (for instance diagnostics warnings) when
458 compiling preprocessed source code.
459 A solution to the above mentioned downside is to set run_second_cpp
461 to false and pass -fdirectives-only (for GCC) or -frewrite-includes
462 (for Clang) to the compiler. This will cause the compiler to leave
463 the macros and other preprocessor information, and only process the
464 #include directives. When run in this way, the preprocessor
465 arguments will be passed to the compiler since it still has to do
466 some preprocessing (like macros).
467 sloppiness (CCACHE_SLOPPINESS)
469 By default, ccache tries to give as few false cache hits as
470 possible. However, in certain situations it’s possible that you
471 know things that ccache can’t take for granted. This setting makes
472 it possible to tell ccache to relax some checks in order to
473 increase the hit rate. The value should be a comma-separated string
474 with options. Available options are:
475 file_macro
477 Ignore __FILE__ being present in the source.
478 file_stat_matches
480 ccache normally examines a file’s contents to determine whether
481 it matches the cached version. With this option set, ccache
482 will consider a file as matching its cached version if the
483 mtimes and ctimes match.
484 include_file_ctime
486 By default, ccache also will not cache a file if it includes a
487 header whose ctime is too new. This option disables that check.
488 include_file_mtime
490 By default, ccache will not cache a file if it includes a
491 header whose mtime is too new. This option disables that check.
492 no_system_headers
494 By default, ccache will also include all system headers in the
495 manifest. With this option set, ccache will only include system
496 headers in the hash but not add the system header files to the
497 list of include files.
498 pch_defines
500 Be sloppy about #defines when precompiling a header file. See
501 PRECOMPILED HEADERS for more information.
502 time_macros
504 Ignore __DATE__ and __TIME__ being present in the source code.
505 See the discussion under TROUBLESHOOTING for more information.
507 stats (CCACHE_STATS or CCACHE_NOSTATS, see Boolean values above)
509 If true, ccache will update the statistics counters on each
510 compilation. The default is true.
511 temporary_dir (CCACHE_TEMPDIR)
513 This setting specifies where ccache will put temporary files. The
514 default is <cache_dir>/tmp.
515 Note
517 In previous versions of ccache, CCACHE_TEMPDIR had to be on the
518 same filesystem as the CCACHE_DIR path, but this requirement
519 has been relaxed.)
520 umask (CCACHE_UMASK)
522 This setting specifies the umask for ccache and all child processes
523 (such as the compiler). This is mostly useful when you wish to
524 share your cache with other users. Note that this also affects the
525 file permissions set on the object files created from your
526 compilations.
527 unify (CCACHE_UNIFY or CCACHE_NOUNIFY, see Boolean values above)
529 If true, ccache will use a C/C++ unifier when hashing the
530 preprocessor output if the -g option is not used. The unifier is
531 slower than a normal hash, so setting this environment variable
532 loses a little bit of speed, but it means that ccache can take
533 advantage of not recompiling when the changes to the source code
534 consist of reformatting only. Note that enabling the unifier
535 changes the hash, so cached compilations produced when the unifier
536 is enabled cannot be reused when the unifier is disabled, and vice
537 versa. Enabling the unifier may result in incorrect line number
538 information in compiler warning messages and expansions of the
539 __LINE__ macro.
540
542 By default, ccache has a 5 GB limit on the total size of files in the
543 cache and no limit on the number of files. You can set different limits
544 using the -M/--max-size and -F/--max-files options. Use ccache
545 -s/--show-stats to see the cache size and the currently configured
546 limits (in addition to other various statistics).
547 Cleanup can be triggered in two different ways: automatic and manual.
549 Automatic cleanup
551 ccache maintains counters for various statistics about the cache,
552 including the size and number of all cached files. In order to improve
553 performance and reduce issues with concurrent ccache invocations, there
554 is one statistics file for each of the sixteen subdirectories in the
555 cache.
556 After a new compilation result has been written to the cache, ccache
558 will update the size and file number statistics for the subdirectory
559 (one of sixteen) to which the result was written. Then, if the size
560 counter for said subdirectory is greater than max_size / 16 or the file
561 number counter is greater than max_files / 16, automatic cleanup is
562 triggered.
563 When automatic cleanup is triggered for a subdirectory in the cache,
565 ccache will:
566 1. Count all files in the subdirectory and compute their aggregated
568 size.
569 2. Remove files in LRU (least recently used) order until the size is
571 at most limit_multiple * max_size / 16 and the number of files is
572 at most limit_multiple * max_files / 16, where limit_multiple,
573 max_size and max_files are configuration settings.
574 3. Set the size and file number counters to match the files that were
576 kept.
577 The reason for removing more files than just those needed to not exceed
579 the max limits is that a cleanup is a fairly slow operation, so it
580 would not be a good idea to trigger it often, like after each cache
581 miss.
582 Manual cleanup
584 You can run ccache -c/--cleanup to force cleanup of the whole cache,
585 i.e. all of the sixteen subdirectories. This will recalculate the
586 statistics counters and make sure that the max_size and max_files
587 settings are not exceeded. Note that limit_multiple is not taken into
588 account for manual cleanup.
589
591 ccache can optionally compress all files it puts into the cache using
592 the compression library zlib. While this may involve a tiny performance
593 slowdown, it increases the number of files that fit in the cache. You
594 can turn on compression with the compression configuration setting and
595 you can also tweak the compression level with compression_level.
596
598 ccache -s/--show-stats can show the following statistics:
599 ┌───────────────────────────┬────────────────────────────┐
601 │Name │ Description │
602 ├───────────────────────────┼────────────────────────────┤
603 │ │ │
604 │autoconf compile/link │ Uncachable compilation or │
605 │ │ linking by an autoconf │
606 │ │ test. │
607 ├───────────────────────────┼────────────────────────────┤
608 │ │ │
609 │bad compiler arguments │ Malformed compiler │
610 │ │ argument, e.g. missing a │
611 │ │ value for an option that │
612 │ │ requires an argument or │
613 │ │ failure to read a file │
614 │ │ specified by an option │
615 │ │ argument. │
616 ├───────────────────────────┼────────────────────────────┤
617 │ │ │
618 │cache file missing │ A file was unexpectedly │
619 │ │ missing from the cache. │
620 │ │ This only happens in rare │
621 │ │ situations, e.g. if one │
622 │ │ ccache instance is about │
623 │ │ to get a file from the │
624 │ │ cache while another │
625 │ │ instance removed the file │
626 │ │ as part of cache cleanup. │
627 ├───────────────────────────┼────────────────────────────┤
628 │ │ │
629 │cache hit (direct) │ A result was successfully │
630 │ │ found using the direct │
631 │ │ mode. │
632 ├───────────────────────────┼────────────────────────────┤
633 │ │ │
634 │cache hit (preprocessed) │ A result was successfully │
635 │ │ found using the │
636 │ │ preprocessor mode. │
637 ├───────────────────────────┼────────────────────────────┤
638 │ │ │
639 │cache miss │ No result was found. │
640 ├───────────────────────────┼────────────────────────────┤
641 │ │ │
642 │cache size │ Current size of the cache. │
643 ├───────────────────────────┼────────────────────────────┤
644 │ │ │
645 │called for link │ The compiler was called │
646 │ │ for linking, not │
647 │ │ compiling. │
648 ├───────────────────────────┼────────────────────────────┤
649 │ │ │
650 │called for preprocessing │ The compiler was called │
651 │ │ for preprocessing, not │
652 │ │ compiling. │
653 ├───────────────────────────┼────────────────────────────┤
654 │ │ │
655 │can’t use precompiled │ Preconditions for using │
656 │header │ precompiled headers were │
657 │ │ not fulfilled. │
658 ├───────────────────────────┼────────────────────────────┤
659 │ │ │
660 │ccache internal error │ Unexpected failure, e.g. │
661 │ │ due to problems │
662 │ │ reading/writing the cache. │
663 ├───────────────────────────┼────────────────────────────┤
664 │ │ │
665 │cleanups performed │ Number of cleanups │
666 │ │ performed, either │
667 │ │ implicitly due to the │
668 │ │ cache size limit being │
669 │ │ reached or due to explicit │
670 │ │ ccache -c/--cleanup calls. │
671 ├───────────────────────────┼────────────────────────────┤
672 │ │ │
673 │compile failed │ The compilation failed. No │
674 │ │ result stored in the │
675 │ │ cache. │
676 ├───────────────────────────┼────────────────────────────┤
677 │ │ │
678 │compiler check failed │ A compiler check program │
679 │ │ specified by │
680 │ │ compiler_check │
681 │ │ (CCACHE_COMPILERCHECK) │
682 │ │ failed. │
683 ├───────────────────────────┼────────────────────────────┤
684 │ │ │
685 │compiler produced empty │ The compiler’s output file │
686 │output │ (typically an object file) │
687 │ │ was empty after │
688 │ │ compilation. │
689 ├───────────────────────────┼────────────────────────────┤
690 │ │ │
691 │compiler produced no │ The compiler’s output file │
692 │output │ (typically an object file) │
693 │ │ was missing after │
694 │ │ compilation. │
695 ├───────────────────────────┼────────────────────────────┤
696 │ │ │
697 │compiler produced stdout │ The compiler wrote data to │
698 │ │ standard output. This is │
699 │ │ something that compilers │
700 │ │ normally never do, so │
701 │ │ ccache is not designed to │
702 │ │ store such output in the │
703 │ │ cache. │
704 ├───────────────────────────┼────────────────────────────┤
705 │ │ │
706 │couldn’t find the compiler │ The compiler to execute │
707 │ │ could not be found. │
708 ├───────────────────────────┼────────────────────────────┤
709 │ │ │
710 │error hashing extra file │ Failure reading a file │
711 │ │ specified by │
712 │ │ extra_files_to_hash │
713 │ │ (CCACHE_EXTRAFILES). │
714 ├───────────────────────────┼────────────────────────────┤
715 │ │ │
716 │files in cache │ Current number of files in │
717 │ │ the cache. │
718 ├───────────────────────────┼────────────────────────────┤
719 │ │ │
720 │multiple source files │ The compiler was called to │
721 │ │ compile multiple source │
722 │ │ files in one go. This is │
723 │ │ not supported by ccache. │
724 ├───────────────────────────┼────────────────────────────┤
725 │ │ │
726 │no input file │ No input file was │
727 │ │ specified to the compiler. │
728 ├───────────────────────────┼────────────────────────────┤
729 │ │ │
730 │output to a non-regular │ The output path specified │
731 │file │ with -o is not a file │
732 │ │ (e.g. a directory or a │
733 │ │ device node). │
734 ├───────────────────────────┼────────────────────────────┤
735 │ │ │
736 │output to stdout │ The compiler was │
737 │ │ instructed to write its │
738 │ │ output to standard output │
739 │ │ using -o -. This is not │
740 │ │ supported by ccache. │
741 ├───────────────────────────┼────────────────────────────┤
742 │ │ │
743 │preprocessor error │ Preprocessing the source │
744 │ │ code using the compiler’s │
745 │ │ -E option failed. │
746 ├───────────────────────────┼────────────────────────────┤
747 │ │ │
748 │unsupported code directive │ Code like the assembler │
749 │ │ .incbin directive was │
750 │ │ found. This is not │
751 │ │ supported by ccache. │
752 ├───────────────────────────┼────────────────────────────┤
753 │ │ │
754 │unsupported compiler │ A compiler option not │
755 │option │ supported by ccache was │
756 │ │ found. │
757 ├───────────────────────────┼────────────────────────────┤
758 │ │ │
759 │unsupported source │ A source language e.g. │
760 │language │ specified with -x was │
761 │ │ unsupported by ccache. │
762 └───────────────────────────┴────────────────────────────┘
763
765 The basic idea is to detect when you are compiling exactly the same
766 code a second time and reuse the previously produced output. The
767 detection is done by hashing different kinds of information that should
768 be unique for the compilation and then using the hash sum to identify
769 the cached output. ccache uses MD4, a very fast cryptographic hash
770 algorithm, for the hashing. (MD4 is nowadays too weak to be useful in
771 cryptographic contexts, but it should be safe enough to be used to
772 identify recompilations.) On a cache hit, ccache is able to supply all
773 of the correct compiler outputs (including all warnings, dependency
774 file, etc) from the cache.
775 ccache has two ways of doing the detection:
777 · the direct mode, where ccache hashes the source code and include
779 files directly
780 · the preprocessor mode, where ccache runs the preprocessor on the
782 source code and hashes the result
783 The direct mode is generally faster since running the preprocessor has
785 some overhead.
786 Common hashed information
788 For both modes, the following information is included in the hash:
789 · the extension used by the compiler for a file with preprocessor
791 output (normally .i for C code and .ii for C++ code)
792 · the compiler’s size and modification time (or other
794 compiler-specific information specified by the compiler_check
795 setting)
796 · the name of the compiler
798 · the current directory (if the hash_dir setting is enabled)
800 · contents of files specified by the extra_files_to_hash setting (if
802 any)
803 The direct mode
805 In the direct mode, the hash is formed of the common information and:
806 · the input source file
808 · the command line options
810 Based on the hash, a data structure called “manifest” is looked up in
812 the cache. The manifest contains:
813 · references to cached compilation results (object file, dependency
815 file, etc) that were produced by previous compilations that matched
816 the hash
817 · paths to the include files that were read at the time the
819 compilation results were stored in the cache
820 · hash sums of the include files at the time the compilation results
822 were stored in the cache
823 The current contents of the include files are then hashed and compared
825 to the information in the manifest. If there is a match, ccache knows
826 the result of the compilation. If there is no match, ccache falls back
827 to running the preprocessor. The output from the preprocessor is parsed
828 to find the include files that were read. The paths and hash sums of
829 those include files are then stored in the manifest along with
830 information about the produced compilation result.
831 There is a catch with the direct mode: header files that were used by
833 the compiler are recorded, but header files that were not used, but
834 would have been used if they existed, are not. So, when ccache checks
835 if a result can be taken from the cache, it currently can’t check if
836 the existence of a new header file should invalidate the result. In
837 practice, the direct mode is safe to use in the absolute majority of
838 cases.
839 The direct mode will be disabled if any of the following holds:
841 · the configuration setting direct_mode is false
843 · a modification time of one of the include files is too new (needed
845 to avoid a race condition)
846 · a compiler option not supported by the direct mode is used:
848 · a -Wp,X compiler option other than -Wp,-MD,path, -Wp,-MMD,path
850 and -Wp,-D_define_
851 · -Xpreprocessor
853 · the string __TIME__ is present in the source code
855 The preprocessor mode
857 In the preprocessor mode, the hash is formed of the common information
858 and:
859 · the preprocessor output from running the compiler with -E
861 · the command line options except options that affect include files
863 (-I, -include, -D, etc; the theory is that these options will
864 change the preprocessor output if they have any effect at all)
865 · any standard error output generated by the preprocessor
867 Based on the hash, the cached compilation result can be looked up
869 directly in the cache.
870
872 Some information included in the hash that identifies a unique
873 compilation can contain absolute paths:
874 · The preprocessed source code may contain absolute paths to include
876 files if the compiler option -g is used or if absolute paths are
877 given to -I and similar compiler options.
878 · Paths specified by compiler options (such as -I, -MF, etc) on the
880 command line may be absolute.
881 · The source code file path may be absolute, and that path may
883 substituted for __FILE__ macros in the source code or included in
884 warnings emitted to standard error by the preprocessor.
885 This means that if you compile the same code in different locations,
887 you can’t share compilation results between the different build
888 directories since you get cache misses because of the absolute build
889 directory paths that are part of the hash.
890 Here’s what can be done to enable cache hits between different build
892 directories:
893 · If you build with -g (or similar) to add debug information to the
895 object file, you must either:
896 · use the -fdebug-prefix-map=old=new option for relocating debug
898 info to a common prefix (e.g. -fdebug-prefix-map=$PWD=.); or
899 · set hash_dir = false.
901 · If you use absolute paths anywhere on the command line (e.g. the
903 source code file path or an argument to compiler options like -I
904 and -MF), you must to set base_dir to an absolute path to a “base
905 directory”. ccache will then rewrite absolute paths under that
906 directory to relative before computing the hash.
907
909 ccache has support for GCC’s precompiled headers. However, you have to
910 do some things to make it work properly:
911 · You must set sloppiness to pch_defines,time_macros. The reason is
913 that ccache can’t tell whether __TIME__ or __DATE__ is used when
914 using a precompiled header. Further, it can’t detect changes in
915 #defines in the source code because of how preprocessing works in
916 combination with precompiled headers.
917 · You must either:
919 · use the -include compiler option to include the precompiled
921 header (i.e., don’t use #include in the source code to include
922 the header); or
923 · (for the Clang compiler) use the -include-pch compiler option
925 to include the PCH file generated from the precompiled header;
926 or
927 · add the -fpch-preprocess compiler option when compiling.
929 If you don’t do this, either the non-precompiled version of the
931 header file will be used (if available) or ccache will fall back to
932 running the real compiler and increase the statistics counter
933 “preprocessor error” (if the non-precompiled header file is not
934 available).
935
937 A group of developers can increase the cache hit rate by sharing a
938 cache directory. To share a cache without unpleasant side effects, the
939 following conditions should to be met:
940 · Use the same cache directory.
942 · Make sure that the configuration setting hard_link is false (which
944 is the default).
945 · Make sure that all users are in the same group.
947 · Set the configuration setting umask to 002. This ensures that
949 cached files are accessible to everyone in the group.
950 · Make sure that all users have write permission in the entire cache
952 directory (and that you trust all users of the shared cache).
953 · Make sure that the setgid bit is set on all directories in the
955 cache. This tells the filesystem to inherit group ownership for new
956 directories. The following command might be useful for this:
957 find $CCACHE_DIR -type d | xargs chmod g+s
959 The reason to avoid the hard link mode is that the hard links cause
961 unwanted side effects, as all links to a cached file share the file’s
962 modification timestamp. This results in false dependencies to be
963 triggered by timestamp-based build systems whenever another user links
964 to an existing file. Typically, users will see that their libraries and
965 binaries are relinked without reason.
966 You may also want to make sure that a base directory is set
968 appropriately, as discussed in a previous section.
969
971 It is possible to put the cache directory on an NFS filesystem (or
972 similar filesystems), but keep in mind that:
973 · Having the cache on NFS may slow down compilation. Make sure to do
975 some benchmarking to see if it’s worth it.
976 · ccache hasn’t been tested very thoroughly on NFS.
978 A tip is to set temporary_dir to a directory on the local host to avoid
980 NFS traffic for temporary files.
981
983 The recommended way of combining ccache with another compiler wrapper
984 (such as “distcc”) is by letting ccache execute the compiler wrapper.
985 This is accomplished by defining the configuration setting
986 prefix_command, for example by setting the environment variable
987 CCACHE_PREFIX to the name of the wrapper (e.g. distcc). ccache will
988 then prefix the command line with the specified command when running
989 the compiler. To specify several prefix commands, set prefix_command to
990 a colon-separated list of commands.
991 Unless you set compiler_check to a suitable command (see the
993 description of that configuration option), it is not recommended to use
994 the form ccache anotherwrapper compiler args as the compilation
995 command. It’s also not recommended to use the masquerading technique
996 for the other compiler wrapper. The reason is that by default, ccache
997 will in both cases hash the mtime and size of the other wrapper instead
998 of the real compiler, which means that:
999 · Compiler upgrades will not be detected properly.
1001 · The cached results will not be shared between compilations with and
1003 without the other wrapper.
1004 Another minor thing is that if prefix_command is used, ccache will not
1006 invoke the other wrapper when running the preprocessor, which increases
1007 performance. You can use the prefix_command_cpp configuration setting
1008 if you also want to invoke the other wrapper when doing preprocessing
1009 (normally by adding -E).
1010
1012 · The direct mode fails to pick up new header files in some rare
1013 scenarios. See THE DIRECT MODE above.
1014 · When run via ccache, warning messages produced by GCC 4.9 and newer
1016 will only be colored when the environment variable GCC_COLORS is
1017 set. An alternative to setting GCC_COLORS is to pass
1018 -fdiagnostics-color explicitly when compiling (but then color codes
1019 will also be present when redirecting stderr to a file).
1020 · If ccache guesses that the compiler may emit colored warnings, then
1022 a compilation with stderr referring to a TTY will be considered
1023 different from a compilation with a redirected stderr, thus not
1024 sharing cache entries. This happens for clang by default and for
1025 GCC when GCC_COLORS is set as mentioned above. If you want to share
1026 cache hits, you can pass -f[no-]diagnostics-color (GCC) or
1027 -f[no-]color-diagnostics (clang) explicitly when compiling (but
1028 then color codes will be either on or off for both the TTY and the
1029 redirected case).
1030
1032 General
1033 A general tip for getting information about what ccache is doing is to
1034 enable debug logging by setting log_file. The log contains executed
1035 commands, important decisions that ccache makes, read and written
1036 files, etc. Another way of keeping track of what is happening is to
1037 check the output of ccache -s.
1038 Performance
1040 ccache has been written to perform well out of the box, but sometimes
1041 you may have to do some adjustments of how you use the compiler and
1042 ccache in order to improve performance.
1043 Since ccache works best when I/O is fast, put the cache directory on a
1045 fast storage device if possible. Having lots of free memory so that
1046 files in the cache directory stay in the disk cache is also preferable.
1047 A good way of monitoring how well ccache works is to run ccache -s
1049 before and after your build and then compare the statistics counters.
1050 Here are some common problems and what may be done to increase the hit
1051 rate:
1052 · If “cache hit (preprocessed)” has been incremented instead of
1054 “cache hit (direct)”, ccache has fallen back to preprocessor mode,
1055 which is generally slower. Some possible reasons are:
1056 · The source code has been modified in such a way that the
1058 preprocessor output is not affected.
1059 · Compiler arguments that are hashed in the direct mode but not
1061 in the preprocessor mode have changed (-I, -include, -D, etc)
1062 and they didn’t affect the preprocessor output.
1063 · The compiler option -Xpreprocessor or -Wp,X (except
1065 -Wp,-MD,path, -Wp,-MMD,path, and -Wp,-D_define_) is used.
1066 · This was the first compilation with a new value of the base
1068 directory setting.
1069 · A modification time of one of the include files is too new
1071 (created the same second as the compilation is being done).
1072 This check is made to avoid a race condition. To fix this,
1073 create the include file earlier in the build process, if
1074 possible, or set sloppiness to include_file_mtime if you are
1075 willing to take the risk. (The race condition consists of these
1076 events: the preprocessor is run; an include file is modified by
1077 someone; the new include file is hashed by ccache; the real
1078 compiler is run on the preprocessor’s output, which contains
1079 data from the old header file; the wrong object file is stored
1080 in the cache.)
1081 · The __TIME__ preprocessor macro is (potentially) being used.
1083 ccache turns off direct mode if __TIME__ is present in the
1084 source code. This is done as a safety measure since the string
1085 indicates that a __TIME__ macro may affect the output. (To be
1086 sure, ccache would have to run the preprocessor, but the sole
1087 point of the direct mode is to avoid that.) If you know that
1088 __TIME__ isn’t used in practise, or don’t care if ccache
1089 produces objects where __TIME__ is expanded to something in the
1090 past, you can set sloppiness to time_macros.
1091 · The __DATE__ preprocessor macro is (potentially) being used and
1093 the date has changed. This is similar to how __TIME__ is
1094 handled. If __DATE__ is present in the source code, ccache
1095 hashes the current date in order to be able to produce the
1096 correct object file if the __DATE__ macro affects the output.
1097 If you know that __DATE__ isn’t used in practise, or don’t care
1098 if ccache produces objects where __DATE__ is expanded to
1099 something in the past, you can set sloppiness to time_macros.
1100 · The __FILE__ preprocessor macro is (potentially) being used and
1102 the file path has changed. If __FILE__ is present in the source
1103 code, ccache hashes the current input file path in order to be
1104 able to produce the correct object file if the __FILE__ macro
1105 affects the output. If you know that __FILE__ isn’t used in
1106 practise, or don’t care if ccache produces objects where
1107 __FILE__ is expanded to the wrong path, you can set sloppiness
1108 to file_macro.
1109 · If “cache miss” has been incremented even though the same code has
1111 been compiled and cached before, ccache has either detected that
1112 something has changed anyway or a cleanup has been performed
1113 (either explicitly or implicitly when a cache limit has been
1114 reached). Some perhaps unobvious things that may result in a cache
1115 miss are usage of __TIME__ or __DATE__ macros, or use of
1116 automatically generated code that contains a timestamp, build
1117 counter or other volatile information.
1118 · If “multiple source files” has been incremented, it’s an indication
1120 that the compiler has been invoked on several source code files at
1121 once. ccache doesn’t support that. Compile the source code files
1122 separately if possible.
1123 · If “unsupported compiler option” has been incremented, enable debug
1125 logging and check which option was rejected.
1126 · If “preprocessor error” has been incremented, one possible reason
1128 is that precompiled headers are being used. See PRECOMPILED HEADERS
1129 for how to remedy this.
1130 · If “can’t use precompiled header” has been incremented, see
1132 PRECOMPILED HEADERS.
1133 Corrupt object files
1135 It should be noted that ccache is susceptible to general storage
1136 problems. If a bad object file sneaks into the cache for some reason,
1137 it will of course stay bad. Some possible reasons for erroneous object
1138 files are bad hardware (disk drive, disk controller, memory, etc),
1139 buggy drivers or file systems, a bad prefix_command or compiler
1140 wrapper. If this happens, the easiest way of fixing it is this:
1141 1. Build so that the bad object file ends up in the build tree.
1143 2. Remove the bad object file from the build tree.
1145 3. Rebuild with CCACHE_RECACHE set.
1147 An alternative is to clear the whole cache with ccache -C if you don’t
1149 mind losing other cached results.
1150 There are no reported issues about ccache producing broken object files
1152 reproducibly. That doesn’t mean it can’t happen, so if you find a
1153 repeatable case, please report it.
1154
1156 Credits, mailing list information, bug reporting instructions, source
1157 code, etc, can be found on ccache’s web site: https://ccache.samba.org.
1158
1160 ccache was originally written by Andrew Tridgell and is currently
1161 developed and maintained by Joel Rosdahl. See AUTHORS.txt or
1162 AUTHORS.html and https://ccache.samba.org/credits.html for a list of
1163 contributors.
1164ccache 3.4.3 09/02/2018 CCACHE(1)