4 :man version: {revnumber}
5 :man manual: ccache Manual
11 ccache - a fast C/C++ compiler cache
19 *ccache* 'compiler' ['compiler options']
20 'compiler' ['compiler options'] (via symbolic link)
26 ccache is a compiler cache. It speeds up recompilation by caching the result of
27 previous compilations and detecting when the same compilation is being done
28 again. Supported languages are C, C\+\+, Objective-C and Objective-C++.
30 ccache has been carefully written to always produce exactly the same compiler
31 output that you would get without the cache. The only way you should be able to
32 tell that you are using ccache is the speed. Currently known exceptions to this
33 goal are listed under <<_caveats,CAVEATS>>. If you ever discover an
34 undocumented case where ccache changes the output of your compiler, please let
41 * Keeps statistics on hits/misses.
42 * Automatic cache size management.
43 * Can cache compilations that generate warnings.
46 * Optionally compresses files in the cache to reduce disk space.
52 * Only knows how to cache the compilation of a single
53 C/C\+\+/Objective-C/Objective-C++ file. Other types of compilations
54 (multi-file compilation, linking, etc) will silently fall back to running the
56 * Only works with GCC and compilers that behave similar enough.
57 * Some compiler flags are not supported. If such a flag is detected, ccache
58 will silently fall back to running the real compiler.
64 There are two ways to use ccache. You can either prefix your compilation
65 commands with *ccache* or you can let ccache masquerade as the compiler by
66 creating a symbolic link (named as the compiler) to ccache. The first method is
67 most convenient if you just want to try out ccache or wish to use it for some
68 specific projects. The second method is most useful for when you wish to use
69 ccache for all your compilations.
71 To use the first method, just make sure that *ccache* is in your *PATH*.
73 To use the symlinks method, do something like this:
75 -------------------------------------------------------------------------------
76 cp ccache /usr/local/bin/
77 ln -s ccache /usr/local/bin/gcc
78 ln -s ccache /usr/local/bin/g++
79 ln -s ccache /usr/local/bin/cc
80 ln -s ccache /usr/local/bin/c++
81 -------------------------------------------------------------------------------
83 And so forth. This will work as long as the directory with symlinks comes
84 before the path to the compiler (which is usually in +/usr/bin+). After
85 installing you may wish to run ``which gcc'' to make sure that the correct link
88 WARNING: The technique of letting ccache masquerade as the compiler works well,
89 but currently doesn't interact well with other tools that do the same thing.
90 See <<_using_ccache_with_other_compiler_wrappers,USING CCACHE WITH OTHER
93 WARNING: Do not use a hard link, use a symbolic link. A hard link will cause
94 ``interesting'' problems.
99 These options only apply when you invoke ccache as ``ccache''. When invoked as
100 a compiler (via a symlink as described in the previous section), the normal
101 compiler options apply and you should refer to the compiler's documentation.
105 Clean up the cache by removing old cached files until the specified file
106 number and cache size limits are not exceeded. This also recalculates the
107 cache file count and size totals. Normally, there is no need to initiate
108 cleanup manually as ccache keeps the cache below the specified limits at
109 runtime and keeps statistics up to date on each compilation. Forcing a
110 cleanup is mostly useful if you manually modify the cache contents or
111 believe that the cache size statistics may be inaccurate.
115 Clear the entire cache, removing all cached files, but keeping the
118 *-F, --max-files*='N'::
120 Set the maximum number of files allowed in the cache. Use 0 for no limit.
121 The value is stored in a configuration file in the cache directory and
122 applies to all future compilations.
126 Print an options summary page.
128 *-M, --max-size*='SIZE'::
130 Set the maximum size of the files stored in the cache. 'SIZE' should be a
131 number followed by an optional suffix: k, M, G, T (decimal), Ki, Mi, Gi or
132 Ti (binary). The default suffix is G. Use 0 for no limit. The value is
133 stored in a configuration file in the cache directory and applies to all
136 *-o, --set-config*='KEY=VALUE'::
138 Set configuration 'KEY' to 'VALUE'. See <<_configuration,CONFIGURATION>>
139 for more information.
141 *-p, --print-config*::
143 Print current configuration options and from where they originate
144 (environment variable, configuration file or compile-time default).
148 Print the current statistics summary for the cache.
152 Print version and copyright information.
156 Zero the cache statistics (but not the configuration options).
162 When run as a compiler, ccache usually just takes the same command line options
163 as the compiler you are using. The only exception to this is the option
164 *--ccache-skip*. That option can be used to tell ccache to avoid interpreting
165 the next option in any way and to pass it along to the compiler as-is.
167 NOTE: *--ccache-skip* currently only tells ccache not to interpret the next
168 option as a special compiler option -- the option will still be included in the
171 The reason this can be important is that ccache does need to parse the command
172 line and determine what is an input filename and what is a compiler option, as
173 it needs the input filename to determine the name of the resulting object file
174 (among other things). The heuristic ccache uses when parsing the command line
175 is that any argument that exists as a file is treated as an input file name. By
176 using *--ccache-skip* you can force an option to not be treated as an input
177 file name and instead be passed along to the compiler as a command line option.
179 Another case where *--ccache-skip* can be useful is if ccache interprets an
180 option specially but shouldn't, since the option has another meaning for your
181 compiler than what ccache thinks.
187 ccache's default behavior can be overridden by configuration file settings,
188 which in turn can be overridden by environment variables with names starting
189 with *CCACHE_*. ccache normally reads configuration from two files: first a
190 system-level configuration file and secondly a cache-specific configuration
191 file. The priority of configuration settings is as follows (where 1 is
194 1. Environment variables.
195 2. The cache-specific configuration file *<ccachedir>/ccache.conf* (typically
196 *$HOME/.ccache/ccache.conf*).
197 3. The system-wide configuration file *<sysconfdir>/ccache.conf* (typically
198 */etc/ccache.conf* or */usr/local/etc/ccache.conf*).
199 4. Compile-time defaults.
201 As a special case, if the environment variable *CCACHE_CONFIGPATH* is set,
202 ccache reads configuration from the specified path instead of the default
206 Configuration file syntax
207 ~~~~~~~~~~~~~~~~~~~~~~~~~
209 Configuration files are in a simple ``key = value'' format, one setting per
210 line. Lines starting with a hash sign are comments. Blank lines are ignored, as
211 is whitespace surrounding keys and values. Example:
213 -------------------------------------------------------------------------------
214 # Set maximum cache size to 10 GB:
216 -------------------------------------------------------------------------------
221 Some settings are boolean values (i.e. truth values). In a configuration file,
222 such values must be set to the string *true* or *false*. For the corresponding
223 environment variables, the semantics are a bit different: a set environment
224 variable means ``true'' (even if set to the empty string), the following
225 case-insensitive negative values are considered an error (rather than
226 surprising the user): *0*, *false*, *disable* and *no*, and an unset
227 environment variable means ``false''. Each boolean environment variable also
228 has a negated form starting with *CCACHE_NO*. For example, *CCACHE_COMPRESS*
229 can be set to force compression and *CCACHE_NOCOMPRESS* can be set to force no
233 Configuration settings
234 ~~~~~~~~~~~~~~~~~~~~~~
236 Below is a list of available configuration settings. The corresponding
237 environment variable name is indicated in parentheses after each configuration
240 *base_dir* (*CCACHE_BASEDIR*)::
242 This setting should be an absolute path to a directory. ccache then
243 rewrites absolute paths into relative paths before computing the hash that
244 identifies the compilation, but only for paths under the specified
245 directory. If set to the empty string (which is the default), no rewriting
246 is done. A typical path to use as the base directory is your home directory
247 or another directory that is a parent of your build directories. Don't use
248 +/+ as the base directory since that will make ccache also rewrite paths to
249 system header files, which doesn't gain anything.
251 See also the discussion under <<_compiling_in_different_directories,COMPILING
252 IN DIFFERENT DIRECTORIES>>.
254 *cache_dir* (*CCACHE_DIR*)::
256 This setting specifies where ccache will keep its cached compiler outputs.
257 It will only take effect if set in the system-wide configuration file or as
258 an environment variable. The default is *$HOME/.ccache*.
260 *cache_dir_levels* (*CCACHE_NLEVELS*)::
262 This setting allows you to choose the number of directory levels in the
263 cache directory. The default is 2. The minimum is 1 and the maximum is 8.
265 *compiler* (*CCACHE_CC*)::
267 This setting can be used to force the name of the compiler to use. If set
268 to the empty string (which is the default), ccache works it out from the
271 *compiler_check* (*CCACHE_COMPILERCHECK*)::
273 By default, ccache includes the modification time (``mtime'') and size of
274 the compiler in the hash to ensure that results retrieved from the cache
275 are accurate. This setting can be used to select another strategy. Possible
280 Hash the content of the compiler binary. This makes ccache very slightly
281 slower compared to the *mtime* setting, but makes it cope better with
282 compiler upgrades during a build bootstrapping process.
284 Hash the compiler's mtime and size, which is fast. This is the default.
286 Don't hash anything. This may be good for situations where you can safely
287 use the cached results even though the compiler's mtime or size has changed
288 (e.g. if the compiler is built as part of your build system and the
289 compiler's source has not changed, or if the compiler only has changes that
290 don't affect code generation). You should only use the *none* setting if
291 you know what you are doing.
293 Use *value* as the string to calculate hash from. This can be the compiler
294 revision number you retrieved earlier and set here via environment variable.
296 Hash the standard output and standard error output of the specified
297 command. The string will be split on whitespace to find out the command and
298 arguments to run. No other interpretation of the command string will be
299 done, except that the special word *%compiler%* will be replaced with the
300 path to the compiler. Several commands can be specified with semicolon as
310 %compiler% -dumpmachine; %compiler% -dumpversion
313 You should make sure that the specified command is as fast as possible since it
314 will be run once for each ccache invocation.
316 Identifying the compiler using a command is useful if you want to avoid cache
317 misses when the compiler has been rebuilt but not changed.
319 Another case is when the compiler (as seen by ccache) actually isn't the real
320 compiler but another compiler wrapper -- in that case, the default *mtime*
321 method will hash the mtime and size of the other compiler wrapper, which means
322 that ccache won't be able to detect a compiler upgrade. Using a suitable
323 command to identify the compiler is thus safer, but it's also slower, so you
324 should consider continue using the *mtime* method in combination with
325 the *prefix_command* setting if possible. See
326 <<_using_ccache_with_other_compiler_wrappers,USING CCACHE WITH OTHER COMPILER
331 *compression* (*CCACHE_COMPRESS* or *CCACHE_NOCOMPRESS*, see <<_boolean_values,Boolean values>> above)::
333 If true, ccache will compress object files and other compiler output it
334 puts in the cache. However, this setting has no effect on how files are
335 retrieved from the cache; compressed and uncompressed results will still be
336 usable regardless of this setting. The default is false.
338 *compression_level* (*CCACHE_COMPRESSLEVEL*)::
340 This setting determines the level at which ccache will compress object
341 files. It only has effect if *compression* is enabled. The value defaults
342 to 6, and must be no lower than 1 (fastest, worst compression) and no
343 higher than 9 (slowest, best compression).
345 *cpp_extension* (*CCACHE_EXTENSION*)::
347 This setting can be used to force a certain extension for the intermediate
348 preprocessed file. The default is to automatically determine the extension
349 to use for intermediate preprocessor files based on the type of file being
350 compiled, but that sometimes doesn't work. For example, when using the
351 ``aCC'' compiler on HP-UX, set the cpp extension to *i*.
353 *direct_mode* (*CCACHE_DIRECT* or *CCACHE_NODIRECT*, see <<_boolean_values,Boolean values>> above)::
355 If true, the direct mode will be used. The default is true. See
356 <<_the_direct_mode,THE DIRECT MODE>>.
358 *disable* (*CCACHE_DISABLE* or *CCACHE_NODISABLE*, see <<_boolean_values,Boolean values>> above)::
360 When true, ccache will just call the real compiler, bypassing the cache
361 completely. The default is false.
363 *extra_files_to_hash* (*CCACHE_EXTRAFILES*)::
365 This setting is a list of paths to files that ccache will include in the
366 the hash sum that identifies the build. The list separator is semicolon on
367 Windows systems and colon on other systems.
369 *hard_link* (*CCACHE_HARDLINK* or *CCACHE_NOHARDLINK*, see <<_boolean_values,Boolean values>> above)::
371 If true, ccache will attempt to use hard links from the cache directory
372 when creating the compiler output rather than using a file copy. Hard links
373 are never made for compressed cache files. This means that you should not
374 enable compression if you want to use hard links. The default is false.
376 WARNING: Do not enable this option unless you are aware of the consequences.
377 Using hard links may be slightly faster in some situations, but there are
378 several pitfalls since the resulting object file will share i-node with the
381 1. If the resulting object file is modified in any way, the cached object file
382 will be modified as well. For instance, if you run *strip object.o* or *echo
383 >object.o*, you will corrupt the cache.
384 2. Programs that rely on modification times (like ``make'') can be confused
385 since ccache updates the cached files' modification times as part of the
386 automatic cache size management. This will affect object files in the build
387 tree as well, which can retrigger the linking step even though nothing
390 *hash_dir* (*CCACHE_HASHDIR* or *CCACHE_NOHASHDIR*, see <<_boolean_values,Boolean values>> above)::
392 If true (which is the default), ccache will include the current working
393 directory (CWD) in the hash that is used to distinguish two compilations
394 when generating debug info (compiler option *-g* with variations).
395 Exception: The CWD will not be included in the hash if *base_dir* is set
396 (and matches the CWD) and the compiler option *-fdebug-prefix-map* is used.
397 See also the discussion under
398 <<_compiling_in_different_directories,COMPILING IN DIFFERENT DIRECTORIES>>.
400 The reason for including the CWD in the hash by default is to prevent a problem
401 with the storage of the current working directory in the debug info of an
402 object file, which can lead ccache to return a cached object file that has the
403 working directory in the debug info set incorrectly.
405 You can disable this setting to get cache hits when compiling the same source
406 code in different directories if you don't mind that CWD in the debug info
409 *ignore_headers_in_manifest* (*CCACHE_IGNOREHEADERS*)::
411 This setting is a list of paths to files (or directories with headers) that
412 ccache will *not* include in the manifest list that makes up the direct
413 mode. Note that this can cause stale cache hits if those headers do indeed
414 change. The list separator is semicolon on Windows systems and colon on
417 *keep_comments_cpp* (*CCACHE_COMMENTS* or *CCACHE_NOCOMMENTS*, see <<_boolean_values,Boolean values>> above)::
419 If true, ccache will not discard the comments before hashing preprocessor
420 output. This can be used to check documentation with *-Wdocumentation*.
422 *limit_multiple* (*CCACHE_LIMIT_MULTIPLE*)::
424 Sets the limit when cleaning up. Files are deleted (in LRU order) until the
425 levels are below the limit. The default is 0.8 (= 80%). See
426 <<_automatic_cleanup,AUTOMATIC CLEANUP>> for more information.
428 *log_file* (*CCACHE_LOGFILE*)::
430 If set to a file path, ccache will write information on what it is doing to
431 the specified file. This is useful for tracking down problems.
433 *max_files* (*CCACHE_MAXFILES*)::
435 This option specifies the maximum number of files to keep in the cache. Use
436 0 for no limit (which is the default). See also
437 <<_cache_size_management,CACHE SIZE MANAGEMENT>>.
439 *max_size* (*CCACHE_MAXSIZE*)::
441 This option specifies the maximum size of the cache. Use 0 for no limit.
442 The default value is 5G. Available suffixes: k, M, G, T (decimal) and Ki,
443 Mi, Gi, Ti (binary). The default suffix is "G". See also
444 <<_cache_size_management,CACHE SIZE MANAGEMENT>>.
446 *path* (*CCACHE_PATH*)::
448 If set, ccache will search directories in this list when looking for the
449 real compiler. The list separator is semicolon on Windows systems and colon
450 on other systems. If not set, ccache will look for the first executable
451 matching the compiler name in the normal *PATH* that isn't a symbolic link
454 *prefix_command* (*CCACHE_PREFIX*)::
456 This option adds a list of prefixes (separated by space) to the command
457 line that ccache uses when invoking the compiler. See also
458 <<_using_ccache_with_other_compiler_wrappers,USING CCACHE WITH OTHER
461 *prefix_command_cpp* (*CCACHE_PREFIX_CPP*)::
463 This option adds a list of prefixes (separated by space) to the command
464 line that ccache uses when invoking the preprocessor.
466 *read_only* (*CCACHE_READONLY* or *CCACHE_NOREADONLY*, see <<_boolean_values,Boolean values>> above)::
468 If true, ccache will attempt to use existing cached object files, but it
469 will not to try to add anything new to the cache. If you are using this
470 because your ccache directory is read-only, then you need to set
471 *temporary_dir* as otherwise ccache will fail to create temporary files.
473 *read_only_direct* (*CCACHE_READONLY_DIRECT* or *CCACHE_NOREADONLY_DIRECT*, see <<_boolean_values,Boolean values>> above)::
475 Just like *read_only* except that ccache will only try to retrieve results
476 from the cache using the direct mode, not the preprocessor mode. See
477 documentation for *read_only* regarding using a read-only ccache directory.
479 *recache* (*CCACHE_RECACHE* or *CCACHE_NORECACHE*, see <<_boolean_values,Boolean values>> above)::
481 If true, ccache will not use any previously stored result. New results will
482 still be cached, possibly overwriting any pre-existing results.
484 *run_second_cpp* (*CCACHE_CPP2* or *CCACHE_NOCPP2*, see <<_boolean_values,Boolean values>> above)::
486 If true, ccache will first run the preprocessor to preprocess the source
487 code (see <<_the_preprocessor_mode,THE PREPROCESSOR MODE>>) and then on a
488 cache miss run the compiler on the source code to get hold of the object
489 file. This is the default.
491 If false, ccache will first run preprocessor to preprocess the source code and
492 then on a cache miss run the compiler on the _preprocessed source code_ instead
493 of the original source code. This makes cache misses slightly faster since the
494 source code only has to be preprocessed once. The downside is that some
495 compilers won't produce the same result (for instance diagnostics warnings)
496 when compiling preprocessed source code.
498 A solution to the above mentioned downside is to set *run_second_cpp* to false
499 and pass *-fdirectives-only* (for GCC) or *-frewrite-includes* (for Clang) to
500 the compiler. This will cause the compiler to leave the macros and other
501 preprocessor information, and only process the *#include* directives. When run
502 in this way, the preprocessor arguments will be passed to the compiler since it
503 still has to do _some_ preprocessing (like macros).
505 *sloppiness* (*CCACHE_SLOPPINESS*)::
507 By default, ccache tries to give as few false cache hits as possible.
508 However, in certain situations it's possible that you know things that
509 ccache can't take for granted. This setting makes it possible to tell
510 ccache to relax some checks in order to increase the hit rate. The value
511 should be a comma-separated string with options. Available options are:
515 Ignore *\_\_FILE__* being present in the source.
516 *file_stat_matches*::
517 ccache normally examines a file's contents to determine whether it matches
518 the cached version. With this option set, ccache will consider a file as
519 matching its cached version if the mtimes and ctimes match.
520 *include_file_ctime*::
521 By default, ccache also will not cache a file if it includes a header whose
522 ctime is too new. This option disables that check.
523 *include_file_mtime*::
524 By default, ccache will not cache a file if it includes a header whose
525 mtime is too new. This option disables that check.
526 *no_system_headers*::
527 By default, ccache will also include all system headers in the manifest.
528 With this option set, ccache will only include system headers in the hash
529 but not add the system header files to the list of include files.
531 Be sloppy about **#define**s when precompiling a header file. See
532 <<_precompiled_headers,PRECOMPILED HEADERS>> for more information.
534 Ignore *\_\_DATE\__* and *\_\_TIME__* being present in the source code.
537 See the discussion under <<_troubleshooting,TROUBLESHOOTING>> for more
540 *stats* (*CCACHE_STATS* or *CCACHE_NOSTATS*, see <<_boolean_values,Boolean values>> above)::
542 If true, ccache will update the statistics counters on each compilation.
545 *temporary_dir* (*CCACHE_TEMPDIR*)::
547 This setting specifies where ccache will put temporary files. The default
548 is *<cache_dir>/tmp*.
550 NOTE: In previous versions of ccache, *CCACHE_TEMPDIR* had to be on the same
551 filesystem as the *CCACHE_DIR* path, but this requirement has been
554 *umask* (*CCACHE_UMASK*)::
556 This setting specifies the umask for ccache and all child processes (such
557 as the compiler). This is mostly useful when you wish to share your cache
558 with other users. Note that this also affects the file permissions set on
559 the object files created from your compilations.
561 *unify* (*CCACHE_UNIFY* or *CCACHE_NOUNIFY*, see <<_boolean_values,Boolean values>> above)::
563 If true, ccache will use a C/C++ unifier when hashing the preprocessor
564 output if the *-g* option is not used. The unifier is slower than a normal
565 hash, so setting this environment variable loses a little bit of speed, but
566 it means that ccache can take advantage of not recompiling when the changes
567 to the source code consist of reformatting only. Note that enabling the
568 unifier changes the hash, so cached compilations produced when the unifier
569 is enabled cannot be reused when the unifier is disabled, and vice versa.
570 Enabling the unifier may result in incorrect line number information in
571 compiler warning messages and expansions of the *\_\_LINE__* macro.
574 Cache size management
575 ---------------------
577 By default, ccache has a 5 GB limit on the total size of files in the cache and
578 no limit on the number of files. You can set different limits using the
579 *-M*/*--max-size* and *-F*/*--max-files* options. Use *ccache -s/--show-stats*
580 to see the cache size and the currently configured limits (in addition to other
583 Cleanup can be triggered in two different ways: automatic and manual.
589 ccache maintains counters for various statistics about the cache, including the
590 size and number of all cached files. In order to improve performance and reduce
591 issues with concurrent ccache invocations, there is one statistics file for
592 each of the sixteen subdirectories in the cache.
594 After a new compilation result has been written to the cache, ccache will
595 update the size and file number statistics for the subdirectory (one of
596 sixteen) to which the result was written. Then, if the size counter for said
597 subdirectory is greater than *max_size / 16* or the file number counter is
598 greater than *max_files / 16*, automatic cleanup is triggered.
600 When automatic cleanup is triggered for a subdirectory in the cache, ccache
603 1. Count all files in the subdirectory and compute their aggregated size.
604 2. Remove files in LRU (least recently used) order until the size is at most
605 *limit_multiple * max_size / 16* and the number of files is at most
606 *limit_multiple * max_files / 16*, where *limit_multiple*, *max_size* and
607 *max_files* are configuration settings.
608 3. Set the size and file number counters to match the files that were kept.
610 The reason for removing more files than just those needed to not exceed the max
611 limits is that a cleanup is a fairly slow operation, so it would not be a good
612 idea to trigger it often, like after each cache miss.
618 You can run *ccache -c/--cleanup* to force cleanup of the whole cache, i.e. all
619 of the sixteen subdirectories. This will recalculate the statistics counters
620 and make sure that the *max_size* and *max_files* settings are not exceeded.
621 Note that *limit_multiple* is not taken into account for manual cleanup.
627 ccache can optionally compress all files it puts into the cache using the
628 compression library zlib. While this may involve a tiny performance slowdown,
629 it increases the number of files that fit in the cache. You can turn on
630 compression with the *compression* configuration setting and you can also tweak
631 the compression level with *compression_level*.
637 *ccache -s/--show-stats* can show the following statistics:
639 [options="header",cols="30%,70%"]
640 |==============================================================================
642 | autoconf compile/link |
643 Uncachable compilation or linking by an autoconf test.
645 | bad compiler arguments |
646 Malformed compiler argument, e.g. missing a value for an option that requires
647 an argument or failure to read a file specified by an option argument.
649 | cache file missing |
650 A file was unexpectedly missing from the cache. This only happens in rare
651 situations, e.g. if one ccache instance is about to get a file from the cache
652 while another instance removed the file as part of cache cleanup.
654 | cache hit (direct) |
655 A result was successfully found using <<_the_direct_mode,the direct mode>>.
657 | cache hit (preprocessed) |
658 A result was successfully found using <<_the_preprocessor_mode,the preprocessor
665 Current size of the cache.
668 The compiler was called for linking, not compiling.
670 | called for preprocessing |
671 The compiler was called for preprocessing, not compiling.
673 | can't use precompiled header |
674 Preconditions for using <<_precompiled_headers,precompiled headers>> were not
677 | ccache internal error |
678 Unexpected failure, e.g. due to problems reading/writing the cache.
680 | cleanups performed |
681 Number of cleanups performed, either implicitly due to the cache size limit
682 being reached or due to explicit *ccache -c/--cleanup* calls.
685 The compilation failed. No result stored in the cache.
687 | compiler check failed |
688 A compiler check program specified by *compiler_check* (*CCACHE_COMPILERCHECK*)
691 | compiler produced empty output |
692 The compiler's output file (typically an object file) was empty after
695 | compiler produced no output |
696 The compiler's output file (typically an object file) was missing after
699 | compiler produced stdout |
700 The compiler wrote data to standard output. This is something that compilers
701 normally never do, so ccache is not designed to store such output in the cache.
703 | couldn't find the compiler |
704 The compiler to execute could not be found.
706 | error hashing extra file |
707 Failure reading a file specified by *extra_files_to_hash*
708 (*CCACHE_EXTRAFILES*).
711 Current number of files in the cache.
713 | multiple source files |
714 The compiler was called to compile multiple source files in one go. This is not
718 No input file was specified to the compiler.
720 | output to a non-regular file |
721 The output path specified with *-o* is not a file (e.g. a directory or a device
725 The compiler was instructed to write its output to standard output using *-o
726 -*. This is not supported by ccache.
728 | preprocessor error |
729 Preprocessing the source code using the compiler's *-E* option failed.
731 | unsupported code directive |
732 Code like the assembler ``.incbin'' directive was found. This is not supported
735 | unsupported compiler option |
736 A compiler option not supported by ccache was found.
738 | unsupported source language |
739 A source language e.g. specified with *-x* was unsupported by ccache.
741 |==============================================================================
747 The basic idea is to detect when you are compiling exactly the same code a
748 second time and reuse the previously produced output. The detection is done by
749 hashing different kinds of information that should be unique for the
750 compilation and then using the hash sum to identify the cached output. ccache
751 uses MD4, a very fast cryptographic hash algorithm, for the hashing. (MD4 is
752 nowadays too weak to be useful in cryptographic contexts, but it should be safe
753 enough to be used to identify recompilations.) On a cache hit, ccache is able
754 to supply all of the correct compiler outputs (including all warnings,
755 dependency file, etc) from the cache.
757 ccache has two ways of doing the detection:
759 * the *direct mode*, where ccache hashes the source code and include files
761 * the *preprocessor mode*, where ccache runs the preprocessor on the source
762 code and hashes the result
764 The direct mode is generally faster since running the preprocessor has some
768 Common hashed information
769 ~~~~~~~~~~~~~~~~~~~~~~~~~
771 For both modes, the following information is included in the hash:
773 * the extension used by the compiler for a file with preprocessor output
774 (normally *.i* for C code and *.ii* for C++ code)
775 * the compiler's size and modification time (or other compiler-specific
776 information specified by the *compiler_check* setting)
777 * the name of the compiler
778 * the current directory (if the *hash_dir* setting is enabled)
779 * contents of files specified by the *extra_files_to_hash* setting (if any)
785 In the direct mode, the hash is formed of the common information and:
787 * the input source file
788 * the command line options
790 Based on the hash, a data structure called ``manifest'' is looked up in the
791 cache. The manifest contains:
793 * references to cached compilation results (object file, dependency file, etc)
794 that were produced by previous compilations that matched the hash
795 * paths to the include files that were read at the time the compilation results
796 were stored in the cache
797 * hash sums of the include files at the time the compilation results were
800 The current contents of the include files are then hashed and compared to the
801 information in the manifest. If there is a match, ccache knows the result of
802 the compilation. If there is no match, ccache falls back to running the
803 preprocessor. The output from the preprocessor is parsed to find the include
804 files that were read. The paths and hash sums of those include files are then
805 stored in the manifest along with information about the produced compilation
808 There is a catch with the direct mode: header files that were used by the
809 compiler are recorded, but header files that were *not* used, but would have
810 been used if they existed, are not. So, when ccache checks if a result can be
811 taken from the cache, it currently can't check if the existence of a new header
812 file should invalidate the result. In practice, the direct mode is safe to use
813 in the absolute majority of cases.
815 The direct mode will be disabled if any of the following holds:
817 * the configuration setting *direct_mode* is false
818 * a modification time of one of the include files is too new (needed to avoid a
820 * a compiler option not supported by the direct mode is used:
821 ** a *-Wp,_X_* compiler option other than *-Wp,-MD,_path_*,
822 *-Wp,-MMD,_path_* and *-Wp,-D_define_*
824 * the string ``\_\_TIME__'' is present in the source code
827 The preprocessor mode
828 ~~~~~~~~~~~~~~~~~~~~~
830 In the preprocessor mode, the hash is formed of the common information and:
832 * the preprocessor output from running the compiler with *-E*
833 * the command line options except options that affect include files (*-I*,
834 *-include*, *-D*, etc; the theory is that these options will change the
835 preprocessor output if they have any effect at all)
836 * any standard error output generated by the preprocessor
838 Based on the hash, the cached compilation result can be looked up directly in
842 Compiling in different directories
843 ----------------------------------
845 Some information included in the hash that identifies a unique compilation can
846 contain absolute paths:
848 * The preprocessed source code may contain absolute paths to include files if
849 the compiler option *-g* is used or if absolute paths are given to *-I* and
850 similar compiler options.
851 * Paths specified by compiler options (such as *-I*, *-MF*, etc) on the command
852 line may be absolute.
853 * The source code file path may be absolute, and that path may substituted for
854 *\_\_FILE__* macros in the source code or included in warnings emitted to
855 standard error by the preprocessor.
857 This means that if you compile the same code in different locations, you can't
858 share compilation results between the different build directories since you get
859 cache misses because of the absolute build directory paths that are part of the
862 Here's what can be done to enable cache hits between different build
865 * If you build with *-g* (or similar) to add debug information to the object
866 file, you must either:
869 ** use the *-fdebug-prefix-map=_old_=_new_* option for relocating debug info to
870 a common prefix (e.g. *-fdebug-prefix-map=$PWD=.*); or
871 ** set *hash_dir = false*.
873 * If you use absolute paths anywhere on the command line (e.g. the source code
874 file path or an argument to compiler options like *-I* and *-MF*), you must
875 to set *base_dir* to an absolute path to a ``base directory''. ccache will
876 then rewrite absolute paths under that directory to relative before computing
883 ccache has support for GCC's precompiled headers. However, you have to do some
884 things to make it work properly:
886 * You must set *sloppiness* to *pch_defines,time_macros*. The reason is that
887 ccache can't tell whether *\_\_TIME\__* or *\_\_DATE__* is used when using a
888 precompiled header. Further, it can't detect changes in **#define**s in the
889 source code because of how preprocessing works in combination with
894 ** use the *-include* compiler option to include the precompiled header
895 (i.e., don't use *#include* in the source code to include the header); or
896 ** (for the Clang compiler) use the *-include-pch* compiler option to include
897 the PCH file generated from the precompiled header; or
898 ** add the *-fpch-preprocess* compiler option when compiling.
900 If you don't do this, either the non-precompiled version of the header file
901 will be used (if available) or ccache will fall back to running the real
902 compiler and increase the statistics counter ``preprocessor error'' (if the
903 non-precompiled header file is not available).
910 A group of developers can increase the cache hit rate by sharing a cache
911 directory. To share a cache without unpleasant side effects, the following
912 conditions should to be met:
914 * Use the same cache directory.
915 * Make sure that the configuration setting *hard_link* is false (which is the
917 * Make sure that all users are in the same group.
918 * Set the configuration setting *umask* to 002. This ensures that cached files
919 are accessible to everyone in the group.
920 * Make sure that all users have write permission in the entire cache directory
921 (and that you trust all users of the shared cache).
922 * Make sure that the setgid bit is set on all directories in the cache. This
923 tells the filesystem to inherit group ownership for new directories. The
924 following command might be useful for this:
928 find $CCACHE_DIR -type d | xargs chmod g+s
932 The reason to avoid the hard link mode is that the hard links cause unwanted
933 side effects, as all links to a cached file share the file's modification
934 timestamp. This results in false dependencies to be triggered by
935 timestamp-based build systems whenever another user links to an existing file.
936 Typically, users will see that their libraries and binaries are relinked
939 You may also want to make sure that a base directory is set appropriately, as
940 discussed in a previous section.
943 Sharing a cache on NFS
944 ----------------------
946 It is possible to put the cache directory on an NFS filesystem (or similar
947 filesystems), but keep in mind that:
949 * Having the cache on NFS may slow down compilation. Make sure to do some
950 benchmarking to see if it's worth it.
951 * ccache hasn't been tested very thoroughly on NFS.
953 A tip is to set *temporary_dir* to a directory on the local host to avoid NFS
954 traffic for temporary files.
957 Using ccache with other compiler wrappers
958 -----------------------------------------
960 The recommended way of combining ccache with another compiler wrapper (such as
961 ``distcc'') is by letting ccache execute the compiler wrapper. This is
962 accomplished by defining the configuration setting *prefix_command*, for
963 example by setting the environment variable *CCACHE_PREFIX* to the name of the
964 wrapper (e.g. *distcc*). ccache will then prefix the command line with the
965 specified command when running the compiler. To specify several prefix
966 commands, set *prefix_command* to a colon-separated list of commands.
968 Unless you set *compiler_check* to a suitable command (see the description of
969 that configuration option), it is not recommended to use the form *ccache
970 anotherwrapper compiler args* as the compilation command. It's also not
971 recommended to use the masquerading technique for the other compiler wrapper.
972 The reason is that by default, ccache will in both cases hash the mtime and
973 size of the other wrapper instead of the real compiler, which means that:
975 * Compiler upgrades will not be detected properly.
976 * The cached results will not be shared between compilations with and without
979 Another minor thing is that if *prefix_command* is used, ccache will not invoke
980 the other wrapper when running the preprocessor, which increases performance.
981 You can use the *prefix_command_cpp* configuration setting if you also want to
982 invoke the other wrapper when doing preprocessing (normally by adding *-E*).
988 * The direct mode fails to pick up new header files in some rare scenarios. See
989 <<_the_direct_mode,THE DIRECT MODE>> above.
990 * When run via ccache, warning messages produced by GCC 4.9 and newer will only
991 be colored when the environment variable *GCC_COLORS* is set. An alternative
992 to setting *GCC_COLORS* is to pass `-fdiagnostics-color` explicitly when
993 compiling (but then color codes will also be present when redirecting stderr
995 * If ccache guesses that the compiler may emit colored warnings, then a
996 compilation with stderr referring to a TTY will be considered different from
997 a compilation with a redirected stderr, thus not sharing cache entries. This
998 happens for clang by default and for GCC when *GCC_COLORS* is set as
999 mentioned above. If you want to share cache hits, you can pass
1000 `-f[no-]diagnostics-color` (GCC) or `-f[no-]color-diagnostics` (clang)
1001 explicitly when compiling (but then color codes will be either on or off for
1002 both the TTY and the redirected case).
1011 A general tip for getting information about what ccache is doing is to enable
1012 debug logging by setting *log_file*. The log contains executed commands,
1013 important decisions that ccache makes, read and written files, etc. Another way
1014 of keeping track of what is happening is to check the output of *ccache -s*.
1020 ccache has been written to perform well out of the box, but sometimes you may
1021 have to do some adjustments of how you use the compiler and ccache in order to
1022 improve performance.
1024 Since ccache works best when I/O is fast, put the cache directory on a fast
1025 storage device if possible. Having lots of free memory so that files in the
1026 cache directory stay in the disk cache is also preferable.
1028 A good way of monitoring how well ccache works is to run *ccache -s* before and
1029 after your build and then compare the statistics counters. Here are some common
1030 problems and what may be done to increase the hit rate:
1032 * If ``cache hit (preprocessed)'' has been incremented instead of ``cache hit
1033 (direct)'', ccache has fallen back to preprocessor mode, which is generally
1034 slower. Some possible reasons are:
1035 ** The source code has been modified in such a way that the preprocessor output
1037 ** Compiler arguments that are hashed in the direct mode but not in the
1038 preprocessor mode have changed (*-I*, *-include*, *-D*, etc) and they didn't
1039 affect the preprocessor output.
1040 ** The compiler option *-Xpreprocessor* or *-Wp,_X_* (except *-Wp,-MD,_path_*,
1041 *-Wp,-MMD,_path_*, and *-Wp,-D_define_*) is used.
1042 ** This was the first compilation with a new value of the base directory
1044 ** A modification time of one of the include files is too new (created the same
1045 second as the compilation is being done). This check is made to avoid a race
1046 condition. To fix this, create the include file earlier in the build
1047 process, if possible, or set *sloppiness* to *include_file_mtime* if you are
1048 willing to take the risk. (The race condition consists of these events: the
1049 preprocessor is run; an include file is modified by someone; the new include
1050 file is hashed by ccache; the real compiler is run on the preprocessor's
1051 output, which contains data from the old header file; the wrong object file
1052 is stored in the cache.)
1053 ** The *\_\_TIME\__* preprocessor macro is (potentially) being used. ccache
1054 turns off direct mode if ``\_\_TIME\__'' is present in the source code. This
1055 is done as a safety measure since the string indicates that a *\_\_TIME\__*
1056 macro _may_ affect the output. (To be sure, ccache would have to run the
1057 preprocessor, but the sole point of the direct mode is to avoid that.) If
1058 you know that *\_\_TIME\__* isn't used in practise, or don't care if ccache
1059 produces objects where *\_\_TIME__* is expanded to something in the past,
1060 you can set *sloppiness* to *time_macros*.
1061 ** The *\_\_DATE\__* preprocessor macro is (potentially) being used and the
1062 date has changed. This is similar to how *\_\_TIME\__* is handled. If
1063 ``\_\_DATE\__'' is present in the source code, ccache hashes the current
1064 date in order to be able to produce the correct object file if the
1065 *\_\_DATE\__* macro affects the output. If you know that *\_\_DATE\__* isn't
1066 used in practise, or don't care if ccache produces objects where
1067 *\_\_DATE__* is expanded to something in the past, you can set *sloppiness*
1069 ** The *\_\_FILE\__* preprocessor macro is (potentially) being used and the
1070 file path has changed. If ``\_\_FILE\__'' is present in the source code,
1071 ccache hashes the current input file path in order to be able to produce the
1072 correct object file if the *\_\_FILE\__* macro affects the output. If you
1073 know that *\_\_FILE\__* isn't used in practise, or don't care if ccache
1074 produces objects where *\_\_FILE__* is expanded to the wrong path, you can
1075 set *sloppiness* to *file_macro*.
1076 * If ``cache miss'' has been incremented even though the same code has been
1077 compiled and cached before, ccache has either detected that something has
1078 changed anyway or a cleanup has been performed (either explicitly or
1079 implicitly when a cache limit has been reached). Some perhaps unobvious
1080 things that may result in a cache miss are usage of *\_\_TIME\__* or
1081 *\_\_DATE__* macros, or use of automatically generated code that contains a
1082 timestamp, build counter or other volatile information.
1083 * If ``multiple source files'' has been incremented, it's an indication that
1084 the compiler has been invoked on several source code files at once. ccache
1085 doesn't support that. Compile the source code files separately if possible.
1086 * If ``unsupported compiler option'' has been incremented, enable debug logging
1087 and check which option was rejected.
1088 * If ``preprocessor error'' has been incremented, one possible reason is that
1089 precompiled headers are being used. See <<_precompiled_headers,PRECOMPILED
1090 HEADERS>> for how to remedy this.
1091 * If ``can't use precompiled header'' has been incremented, see
1092 <<_precompiled_headers,PRECOMPILED HEADERS>>.
1095 Corrupt object files
1096 ~~~~~~~~~~~~~~~~~~~~
1098 It should be noted that ccache is susceptible to general storage problems. If a
1099 bad object file sneaks into the cache for some reason, it will of course stay
1100 bad. Some possible reasons for erroneous object files are bad hardware (disk
1101 drive, disk controller, memory, etc), buggy drivers or file systems, a bad
1102 *prefix_command* or compiler wrapper. If this happens, the easiest way of
1105 1. Build so that the bad object file ends up in the build tree.
1106 2. Remove the bad object file from the build tree.
1107 3. Rebuild with *CCACHE_RECACHE* set.
1109 An alternative is to clear the whole cache with *ccache -C* if you don't mind
1110 losing other cached results.
1112 There are no reported issues about ccache producing broken object files
1113 reproducibly. That doesn't mean it can't happen, so if you find a repeatable
1114 case, please report it.
1120 Credits, mailing list information, bug reporting instructions, source code,
1121 etc, can be found on ccache's web site: <https://ccache.samba.org>.
1127 ccache was originally written by Andrew Tridgell and is currently developed and
1128 maintained by Joel Rosdahl. See AUTHORS.txt or AUTHORS.html and
1129 <https://ccache.samba.org/credits.html> for a list of contributors.