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 uses hard links where possible to avoid copies.
47 * Optionally compresses files in the cache to reduce disk space.
53 * Only knows how to cache the compilation of a single
54 C/C\+\+/Objective-C/Objective-C++ file. Other types of compilations
55 (multi-file compilation, linking, etc) will silently fall back to running the
57 * Only works with GCC and compilers that behave similar enough.
58 * Some compiler flags are not supported. If such a flag is detected, ccache
59 will silently fall back to running the real compiler.
65 There are two ways to use ccache. You can either prefix your compilation
66 commands with *ccache* or you can let ccache masquerade as the compiler by
67 creating a symbolic link (named as the compiler) to ccache. The first method is
68 most convenient if you just want to try out ccache or wish to use it for some
69 specific projects. The second method is most useful for when you wish to use
70 ccache for all your compilations.
72 To use the first method, just make sure that *ccache* is in your *PATH*.
74 To use the symlinks method, do something like this:
76 -------------------------------------------------------------------------------
77 cp ccache /usr/local/bin/
78 ln -s ccache /usr/local/bin/gcc
79 ln -s ccache /usr/local/bin/g++
80 ln -s ccache /usr/local/bin/cc
81 ln -s ccache /usr/local/bin/c++
82 -------------------------------------------------------------------------------
84 And so forth. This will work as long as the directory with symlinks comes
85 before the path to the compiler (which is usually in +/usr/bin+). After
86 installing you may wish to run ``which gcc'' to make sure that the correct link
89 WARNING: The technique of letting ccache masquerade as the compiler works well,
90 but currently doesn't interact well with other tools that do the same thing.
91 See <<_using_ccache_with_other_compiler_wrappers,USING CCACHE WITH OTHER
94 WARNING: Do not use a hard link, use a symbolic link. A hard link will cause
95 ``interesting'' problems.
100 These options only apply when you invoke ccache as ``ccache''. When invoked as
101 a compiler (via a symlink as described in the previous section), the normal
102 compiler options apply and you should refer to the compiler's documentation.
106 Clean up the cache by removing old cached files until the specified file
107 number and cache size limits are not exceeded. This also recalculates the
108 cache file count and size totals. Normally, there is no need to initiate
109 cleanup manually as ccache keeps the cache below the specified limits at
110 runtime and keeps statistics up to date on each compilation. Forcing a
111 cleanup is mostly useful if you manually modify the cache contents or
112 believe that the cache size statistics may be inaccurate.
116 Clear the entire cache, removing all cached files, but keeping the
119 *-F, --max-files*='N'::
121 Set the maximum number of files allowed in the cache. Use 0 for no limit.
122 The value is stored in a configuration file in the cache directory and
123 applies to all future compilations.
127 Print an options summary page.
129 *-M, --max-size*='SIZE'::
131 Set the maximum size of the files stored in the cache. 'SIZE' should be a
132 number followed by an optional suffix: k, M, G, T (decimal), Ki, Mi, Gi or
133 Ti (binary). The default suffix is G. Use 0 for no limit. The value is
134 stored in a configuration file in the cache directory and applies to all
137 *-o, --set-config*='KEY=VALUE'::
139 Set configuration 'KEY' to 'VALUE'. See <<_configuration,CONFIGURATION>>
140 for more information.
142 *-p, --print-config*::
144 Print current configuration options and from where they originate
145 (environment variable, configuration file or compile-time default).
149 Print the current statistics summary for the cache.
153 Print version and copyright information.
157 Zero the cache statistics (but not the configuration options).
163 When run as a compiler, ccache usually just takes the same command line options
164 as the compiler you are using. The only exception to this is the option
165 *--ccache-skip*. That option can be used to tell ccache to avoid interpreting
166 the next option in any way and to pass it along to the compiler as-is.
168 NOTE: *--ccache-skip* currently only tells ccache not to interpret the next
169 option as a special compiler option -- the option will still be included in the
172 The reason this can be important is that ccache does need to parse the command
173 line and determine what is an input filename and what is a compiler option, as
174 it needs the input filename to determine the name of the resulting object file
175 (among other things). The heuristic ccache uses when parsing the command line
176 is that any argument that exists as a file is treated as an input file name. By
177 using *--ccache-skip* you can force an option to not be treated as an input
178 file name and instead be passed along to the compiler as a command line option.
180 Another case where *--ccache-skip* can be useful is if ccache interprets an
181 option specially but shouldn't, since the option has another meaning for your
182 compiler than what ccache thinks.
188 ccache's default behavior can be overridden by configuration file settings,
189 which in turn can be overridden by environment variables with names starting
190 with *CCACHE_*. ccache normally reads configuration from two files: first a
191 system-level configuration file and secondly a cache-specific configuration
192 file. The priority of configuration settings is as follows (where 1 is
195 1. Environment variables.
196 2. The cache-specific configuration file *<ccachedir>/ccache.conf* (typically
197 *$HOME/.ccache/ccache.conf*).
198 3. The system-wide configuration file *<sysconfdir>/ccache.conf* (typically
199 */etc/ccache.conf* or */usr/local/etc/ccache.conf*).
200 4. Compile-time defaults.
202 As a special case, if the environment variable *CCACHE_CONFIGPATH* is set,
203 ccache reads configuration from the specified path instead of the default
207 Configuration file syntax
208 ~~~~~~~~~~~~~~~~~~~~~~~~~
210 Configuration files are in a simple ``key = value'' format, one setting per
211 line. Lines starting with a hash sign are comments. Blank lines are ignored, as
212 is whitespace surrounding keys and values. Example:
214 -------------------------------------------------------------------------------
215 # Set maximum cache size to 10 GB:
217 -------------------------------------------------------------------------------
222 Some settings are boolean values (i.e. truth values). In a configuration file,
223 such values must be set to the string *true* or *false*. For the corresponding
224 environment variables, the semantics are a bit different: a set environment
225 variable means ``true'' regardless of the value (even if set to the empty
226 string), and an unset environment variable means ``false''. Each boolean
227 environment variable also has a negated form starting with *CCACHE_NO*. For
228 example, *CCACHE_COMPRESS* can be set to force compression and
229 *CCACHE_NOCOMPRESS* can be set to force no compression.
232 Configuration settings
233 ~~~~~~~~~~~~~~~~~~~~~~
235 Below is a list of available configuration settings. The corresponding
236 environment variable name is indicated in parentheses after each configuration
239 *base_dir* (*CCACHE_BASEDIR*)::
241 This setting should be an absolute path to a directory. ccache then
242 rewrites absolute paths into relative paths before computing the hash that
243 identifies the compilation, but only for paths under the specified
244 directory. If set to the empty string (which is the default), no rewriting
245 is done. A typical path to use as the base directory is your home directory
246 or another directory that is a parent of your build directories. Don't use
247 +/+ as the base directory since that will make ccache also rewrite paths to
248 system header files, which doesn't gain anything.
250 See also the discussion under <<_compiling_in_different_directories,COMPILING
251 IN DIFFERENT DIRECTORIES>>.
253 *cache_dir* (*CCACHE_DIR*)::
255 This setting specifies where ccache will keep its cached compiler outputs.
256 It will only take effect if set in the system-wide configuration file or as
257 an environment variable. The default is *$HOME/.ccache*.
259 *cache_dir_levels* (*CCACHE_NLEVELS*)::
261 This setting allows you to choose the number of directory levels in the
262 cache directory. The default is 2. The minimum is 1 and the maximum is 8.
264 *compiler* (*CCACHE_CC*)::
266 This setting can be used to force the name of the compiler to use. If set
267 to the empty string (which is the default), ccache works it out from the
270 *compiler_check* (*CCACHE_COMPILERCHECK*)::
272 By default, ccache includes the modification time (``mtime'') and size of
273 the compiler in the hash to ensure that results retrieved from the cache
274 are accurate. This setting can be used to select another strategy. Possible
279 Hash the content of the compiler binary. This makes ccache very slightly
280 slower compared to the *mtime* setting, but makes it cope better with
281 compiler upgrades during a build bootstrapping process.
283 Hash the compiler's mtime and size, which is fast. This is the default.
285 Don't hash anything. This may be good for situations where you can safely
286 use the cached results even though the compiler's mtime or size has changed
287 (e.g. if the compiler is built as part of your build system and the
288 compiler's source has not changed, or if the compiler only has changes that
289 don't affect code generation). You should only use the *none* setting if
290 you know what you are doing.
292 Use *value* as the string to calculate hash from. This can be the compiler
293 revision number you retrieved earlier and set here via environment variable.
295 Hash the standard output and standard error output of the specified
296 command. The string will be split on whitespace to find out the command and
297 arguments to run. No other interpretation of the command string will be
298 done, except that the special word *%compiler%* will be replaced with the
299 path to the compiler. Several commands can be specified with semicolon as
309 %compiler% -dumpmachine; %compiler% -dumpversion
312 You should make sure that the specified command is as fast as possible since it
313 will be run once for each ccache invocation.
315 Identifying the compiler using a command is useful if you want to avoid cache
316 misses when the compiler has been rebuilt but not changed.
318 Another case is when the compiler (as seen by ccache) actually isn't the real
319 compiler but another compiler wrapper -- in that case, the default *mtime*
320 method will hash the mtime and size of the other compiler wrapper, which means
321 that ccache won't be able to detect a compiler upgrade. Using a suitable
322 command to identify the compiler is thus safer, but it's also slower, so you
323 should consider continue using the *mtime* method in combination with
324 the *prefix_command* setting if possible. See
325 <<_using_ccache_with_other_compiler_wrappers,USING CCACHE WITH OTHER COMPILER
330 *compression* (*CCACHE_COMPRESS* or *CCACHE_NOCOMPRESS*, see <<_boolean_values,Boolean values>> above)::
332 If true, ccache will compress object files and other compiler output it
333 puts in the cache. However, this setting has no effect on how files are
334 retrieved from the cache; compressed and uncompressed results will still be
335 usable regardless of this setting. The default is false.
337 *compression_level* (*CCACHE_COMPRESSLEVEL*)::
339 This setting determines the level at which ccache will compress object
340 files. It only has effect if *compression* is enabled. The value defaults
341 to 6, and must be no lower than 1 (fastest, worst compression) and no
342 higher than 9 (slowest, best compression).
344 *cpp_extension* (*CCACHE_EXTENSION*)::
346 This setting can be used to force a certain extension for the intermediate
347 preprocessed file. The default is to automatically determine the extension
348 to use for intermediate preprocessor files based on the type of file being
349 compiled, but that sometimes doesn't work. For example, when using the
350 ``aCC'' compiler on HP-UX, set the cpp extension to *i*.
352 *direct_mode* (*CCACHE_DIRECT* or *CCACHE_NODIRECT*, see <<_boolean_values,Boolean values>> above)::
354 If true, the direct mode will be used. The default is true. See
355 <<_the_direct_mode,THE DIRECT MODE>>.
357 *disable* (*CCACHE_DISABLE* or *CCACHE_NODISABLE*, see <<_boolean_values,Boolean values>> above)::
359 When true, ccache will just call the real compiler, bypassing the cache
360 completely. The default is false.
362 *extra_files_to_hash* (*CCACHE_EXTRAFILES*)::
364 This setting is a list of paths to files that ccache will include in the
365 the hash sum that identifies the build. The list separator is semicolon on
366 Windows systems and colon on other systems.
368 *hard_link* (*CCACHE_HARDLINK* or *CCACHE_NOHARDLINK*, see <<_boolean_values,Boolean values>> above)::
370 If true, ccache will attempt to use hard links from the cache directory
371 when creating the compiler output rather than using a file copy. Using hard
372 links may be slightly faster in some situations, but can confuse programs
373 like ``make'' that rely on modification times. Another thing to keep in
374 mind is that if the resulting object file is modified in any way, this
375 corrupts the cached object file as well. Hard links are never made for
376 compressed cache files. This means that you should not enable compression
377 if you want to use hard links. The default is false.
379 *hash_dir* (*CCACHE_HASHDIR* or *CCACHE_NOHASHDIR*, see <<_boolean_values,Boolean values>> above)::
381 If true (which is the default), ccache will include the current working
382 directory (CWD) in the hash that is used to distinguish two compilations
383 when generating debug info (compiler option *-g* with variations).
384 Exception: The CWD will not be included in the hash if *base_dir* is set
385 (and matches the CWD) and the compiler option *-fdebug-prefix-map* is used.
386 See also the discussion under
387 <<_compiling_in_different_directories,COMPILING IN DIFFERENT DIRECTORIES>>.
389 The reason for including the CWD in the hash by default is to prevent a problem
390 with the storage of the current working directory in the debug info of an
391 object file, which can lead ccache to return a cached object file that has the
392 working directory in the debug info set incorrectly.
394 You can disable this setting to get cache hits when compiling the same source
395 code in different directories if you don't mind that CWD in the debug info
398 *ignore_headers_in_manifest* (*CCACHE_IGNOREHEADERS*)::
400 This setting is a list of paths to files (or directories with headers) that
401 ccache will *not* include in the manifest list that makes up the direct
402 mode. Note that this can cause stale cache hits if those headers do indeed
403 change. The list separator is semicolon on Windows systems and colon on
406 *keep_comments_cpp* (*CCACHE_COMMENTS* or *CCACHE_NOCOMMENTS*, see <<_boolean_values,Boolean values>> above)::
408 If true, ccache will not discard the comments before hashing preprocessor
409 output. This can be used to check documentation with *-Wdocumentation*.
411 *limit_multiple* (*CCACHE_LIMIT_MULTIPLE*)::
413 Sets the limit when cleaning up. Files are deleted (in LRU order) until the
414 levels are below the limit. The default is 0.8 (= 80%). See
415 <<_automatic_cleanup,AUTOMATIC CLEANUP>> for more information.
417 *log_file* (*CCACHE_LOGFILE*)::
419 If set to a file path, ccache will write information on what it is doing to
420 the specified file. This is useful for tracking down problems.
422 *max_files* (*CCACHE_MAXFILES*)::
424 This option specifies the maximum number of files to keep in the cache. Use
425 0 for no limit (which is the default). See also
426 <<_cache_size_management,CACHE SIZE MANAGEMENT>>.
428 *max_size* (*CCACHE_MAXSIZE*)::
430 This option specifies the maximum size of the cache. Use 0 for no limit.
431 The default value is 5G. Available suffixes: k, M, G, T (decimal) and Ki,
432 Mi, Gi, Ti (binary). The default suffix is "G". See also
433 <<_cache_size_management,CACHE SIZE MANAGEMENT>>.
435 *path* (*CCACHE_PATH*)::
437 If set, ccache will search directories in this list when looking for the
438 real compiler. The list separator is semicolon on Windows systems and colon
439 on other systems. If not set, ccache will look for the first executable
440 matching the compiler name in the normal *PATH* that isn't a symbolic link
443 *prefix_command* (*CCACHE_PREFIX*)::
445 This option adds a list of prefixes (separated by space) to the command
446 line that ccache uses when invoking the compiler. See also
447 <<_using_ccache_with_other_compiler_wrappers,USING CCACHE WITH OTHER
450 *prefix_command_cpp* (*CCACHE_PREFIX_CPP*)::
452 This option adds a list of prefixes (separated by space) to the command
453 line that ccache uses when invoking the preprocessor.
455 *read_only* (*CCACHE_READONLY* or *CCACHE_NOREADONLY*, see <<_boolean_values,Boolean values>> above)::
457 If true, ccache will attempt to use existing cached object files, but it
458 will not to try to add anything new to the cache. If you are using this
459 because your ccache directory is read-only, then you need to set
460 *temporary_dir* as otherwise ccache will fail to create temporary files.
462 *read_only_direct* (*CCACHE_READONLY_DIRECT* or *CCACHE_NOREADONLY_DIRECT*, see <<_boolean_values,Boolean values>> above)::
464 Just like *read_only* except that ccache will only try to retrieve results
465 from the cache using the direct mode, not the preprocessor mode. See
466 documentation for *read_only* regarding using a read-only ccache directory.
468 *recache* (*CCACHE_RECACHE* or *CCACHE_NORECACHE*, see <<_boolean_values,Boolean values>> above)::
470 If true, ccache will not use any previously stored result. New results will
471 still be cached, possibly overwriting any pre-existing results.
473 *run_second_cpp* (*CCACHE_CPP2* or *CCACHE_NOCPP2*, see <<_boolean_values,Boolean values>> above)::
475 If true, ccache will first run the preprocessor to preprocess the source
476 code (see <<_the_preprocessor_mode,THE PREPROCESSOR MODE>>) and then on a
477 cache miss run the compiler on the source code to get hold of the object
478 file. This is the default.
480 If false, ccache will first run preprocessor to preprocess the source code and
481 then on a cache miss run the compiler on the _preprocessed source code_ instead
482 of the original source code. This makes cache misses slightly faster since the
483 source code only has to be preprocessed once. The downside is that some
484 compilers won't produce the same result (for instance diagnostics warnings)
485 when compiling preprocessed source code.
487 *sloppiness* (*CCACHE_SLOPPINESS*)::
489 By default, ccache tries to give as few false cache hits as possible.
490 However, in certain situations it's possible that you know things that
491 ccache can't take for granted. This setting makes it possible to tell
492 ccache to relax some checks in order to increase the hit rate. The value
493 should be a comma-separated string with options. Available options are:
497 Ignore *\_\_FILE__* being present in the source.
498 *file_stat_matches*::
499 ccache normally examines a file's contents to determine whether it matches
500 the cached version. With this option set, ccache will consider a file as
501 matching its cached version if the mtimes and ctimes match.
502 *include_file_ctime*::
503 By default, ccache also will not cache a file if it includes a header whose
504 ctime is too new. This option disables that check.
505 *include_file_mtime*::
506 By default, ccache will not cache a file if it includes a header whose
507 mtime is too new. This option disables that check.
508 *no_system_headers*::
509 By default, ccache will also include all system headers in the manifest.
510 With this option set, ccache will only include system headers in the hash
511 but not add the system header files to the list of include files.
513 Be sloppy about **#define**s when precompiling a header file. See
514 <<_precompiled_headers,PRECOMPILED HEADERS>> for more information.
516 Ignore *\_\_DATE\__* and *\_\_TIME__* being present in the source code.
519 See the discussion under <<_troubleshooting,TROUBLESHOOTING>> for more
522 *stats* (*CCACHE_STATS* or *CCACHE_NOSTATS*, see <<_boolean_values,Boolean values>> above)::
524 If true, ccache will update the statistics counters on each compilation.
527 *temporary_dir* (*CCACHE_TEMPDIR*)::
529 This setting specifies where ccache will put temporary files. The default
530 is *<cache_dir>/tmp*.
532 NOTE: In previous versions of ccache, *CCACHE_TEMPDIR* had to be on the same
533 filesystem as the *CCACHE_DIR* path, but this requirement has been
536 *umask* (*CCACHE_UMASK*)::
538 This setting specifies the umask for ccache and all child processes (such
539 as the compiler). This is mostly useful when you wish to share your cache
540 with other users. Note that this also affects the file permissions set on
541 the object files created from your compilations.
543 *unify* (*CCACHE_UNIFY* or *CCACHE_NOUNIFY*, see <<_boolean_values,Boolean values>> above)::
545 If true, ccache will use a C/C++ unifier when hashing the preprocessor
546 output if the *-g* option is not used. The unifier is slower than a normal
547 hash, so setting this environment variable loses a little bit of speed, but
548 it means that ccache can take advantage of not recompiling when the changes
549 to the source code consist of reformatting only. Note that enabling the
550 unifier changes the hash, so cached compilations produced when the unifier
551 is enabled cannot be reused when the unifier is disabled, and vice versa.
552 Enabling the unifier may result in incorrect line number information in
553 compiler warning messages and expansions of the *\_\_LINE__* macro. Also
554 note that enabling the unifier implies turning off the direct mode.
557 Cache size management
558 ---------------------
560 By default, ccache has a 5 GB limit on the total size of files in the cache and
561 no limit on the number of files. You can set different limits using the
562 *-M*/*--max-size* and *-F*/*--max-files* options. Use *ccache -s/--show-stats*
563 to see the cache size and the currently configured limits (in addition to other
566 Cleanup can be triggered in two different ways: automatic and manual.
572 ccache maintains counters for various statistics about the cache, including the
573 size and number of all cached files. In order to improve performance and reduce
574 issues with concurrent ccache invocations, there is one statistics file for
575 each of the sixteen subdirectories in the cache.
577 After a new compilation result has been written to the cache, ccache will
578 update the size and file number statistics for the subdirectory (one of
579 sixteen) to which the result was written. Then, if the size counter for said
580 subdirectory is greater than *max_size / 16* or the file number counter is
581 greater than *max_files / 16*, automatic cleanup is triggered.
583 When automatic cleanup is triggered for a subdirectory in the cache, ccache
586 1. Count all files in the subdirectory and compute their aggregated size.
587 2. Remove files in LRU (least recently used) order until the size is at most
588 *limit_multiple * max_size / 16* and the number of files is at most
589 *limit_multiple * max_files / 16*, where *limit_multiple*, *max_size* and
590 *max_files* are configuration settings.
591 3. Set the size and file number counters to match the files that were kept.
593 The reason for removing more files than just those needed to not exceed the max
594 limits is that a cleanup is a fairly slow operation, so it would not be a good
595 idea to trigger it often, like after each cache miss.
601 You can run *ccache -c/--cleanup* to force cleanup of the whole cache, i.e. all
602 of the sixteen subdirectories. This will recalculate the statistics counters
603 and make sure that the *max_size* and *max_files* settings are not exceeded.
604 Note that *limit_multiple* is not taken into account for manual cleanup.
610 ccache can optionally compress all files it puts into the cache using the
611 compression library zlib. While this may involve a tiny performance slowdown,
612 it increases the number of files that fit in the cache. You can turn on
613 compression with the *compression* configuration setting and you can also tweak
614 the compression level with *compression_level*.
620 *ccache -s/--show-stats* can show the following statistics:
622 [options="header",cols="30%,70%"]
623 |==============================================================================
625 | autoconf compile/link |
626 Uncachable compilation or linking by an autoconf test.
628 | bad compiler arguments |
629 Malformed compiler argument, e.g. missing a value for an option that requires
630 an argument or failure to read a file specified by an option argument.
632 | cache file missing |
633 A file was unexpectedly missing from the cache. This only happens in rare
634 situations, e.g. if one ccache instance is about to get a file from the cache
635 while another instance removed the file as part of cache cleanup.
637 | cache hit (direct) |
638 A result was successfully found using <<_the_direct_mode,the direct mode>>.
640 | cache hit (preprocessed) |
641 A result was successfully found using <<_the_preprocessor_mode,the preprocessor
648 Current size of the cache.
651 The compiler was called for linking, not compiling.
653 | called for preprocessing |
654 The compiler was called for preprocessing, not compiling.
656 | can't use precompiled header |
657 Preconditions for using <<_precompiled_headers,precompiled headers>> were not
660 | ccache internal error |
661 Unexpected failure, e.g. due to problems reading/writing the cache.
663 | cleanups performed |
664 Number of cleanups performed, either implicitly due to the cache size limit
665 being reached or due to explicit *ccache -c/--cleanup* calls.
668 The compilation failed. No result stored in the cache.
670 | compiler check failed |
671 A compiler check program specified by *compiler_check* (*CCACHE_COMPILERCHECK*)
674 | compiler produced empty output |
675 The compiler's output file (typically an object file) was empty after
678 | compiler produced no output |
679 The compiler's output file (typically an object file) was missing after
682 | compiler produced stdout |
683 The compiler wrote data to standard output. This is something that compilers
684 normally never do, so ccache is not designed to store such output in the cache.
686 | couldn't find the compiler |
687 The compiler to execute could not be found.
689 | error hashing extra file |
690 Failure reading a file specified by *extra_files_to_hash*
691 (*CCACHE_EXTRAFILES*).
694 Current number of files in the cache.
696 | multiple source files |
697 The compiler was called to compile multiple source files in one go. This is not
701 No input file was specified to the compiler.
703 | output to a non-regular file |
704 The output path specified with *-o* is not a file (e.g. a directory or a device
708 The compiler was instructed to write its output to standard output using *-o
709 -*. This is not supported by ccache.
711 | preprocessor error |
712 Preprocessing the source code using the compiler's *-E* option failed.
714 | unsupported code directive |
715 Code like the assembler ``.incbin'' directive was found. This is not supported
718 | unsupported compiler option |
719 A compiler option not supported by ccache was found.
721 | unsupported source language |
722 A source language e.g. specified with *-x* was unsupported by ccache.
724 |==============================================================================
730 The basic idea is to detect when you are compiling exactly the same code a
731 second time and reuse the previously produced output. The detection is done by
732 hashing different kinds of information that should be unique for the
733 compilation and then using the hash sum to identify the cached output. ccache
734 uses MD4, a very fast cryptographic hash algorithm, for the hashing. (MD4 is
735 nowadays too weak to be useful in cryptographic contexts, but it should be safe
736 enough to be used to identify recompilations.) On a cache hit, ccache is able
737 to supply all of the correct compiler outputs (including all warnings,
738 dependency file, etc) from the cache.
740 ccache has two ways of doing the detection:
742 * the *direct mode*, where ccache hashes the source code and include files
744 * the *preprocessor mode*, where ccache runs the preprocessor on the source
745 code and hashes the result
747 The direct mode is generally faster since running the preprocessor has some
751 Common hashed information
752 ~~~~~~~~~~~~~~~~~~~~~~~~~
754 For both modes, the following information is included in the hash:
756 * the extension used by the compiler for a file with preprocessor output
757 (normally *.i* for C code and *.ii* for C++ code)
758 * the compiler's size and modification time (or other compiler-specific
759 information specified by the *compiler_check* setting)
760 * the name of the compiler
761 * the current directory (if the *hash_dir* setting is enabled)
762 * contents of files specified by the *extra_files_to_hash* setting (if any)
768 In the direct mode, the hash is formed of the common information and:
770 * the input source file
771 * the command line options
773 Based on the hash, a data structure called ``manifest'' is looked up in the
774 cache. The manifest contains:
776 * references to cached compilation results (object file, dependency file, etc)
777 that were produced by previous compilations that matched the hash
778 * paths to the include files that were read at the time the compilation results
779 were stored in the cache
780 * hash sums of the include files at the time the compilation results were
783 The current contents of the include files are then hashed and compared to the
784 information in the manifest. If there is a match, ccache knows the result of
785 the compilation. If there is no match, ccache falls back to running the
786 preprocessor. The output from the preprocessor is parsed to find the include
787 files that were read. The paths and hash sums of those include files are then
788 stored in the manifest along with information about the produced compilation
791 There is a catch with the direct mode: header files that were used by the
792 compiler are recorded, but header files that were *not* used, but would have
793 been used if they existed, are not. So, when ccache checks if a result can be
794 taken from the cache, it currently can't check if the existence of a new header
795 file should invalidate the result. In practice, the direct mode is safe to use
796 in the absolute majority of cases.
798 The direct mode will be disabled if any of the following holds:
800 * the configuration setting *direct_mode* is false
801 * a modification time of one of the include files is too new (needed to avoid a
803 * the unifier is enabled (the configuration setting *unify* is true)
804 * a compiler option not supported by the direct mode is used:
805 ** a *-Wp,_X_* compiler option other than *-Wp,-MD,_path_*,
806 *-Wp,-MMD,_path_* and *-Wp,-D_define_*
808 * the string ``\_\_TIME__'' is present in the source code
811 The preprocessor mode
812 ~~~~~~~~~~~~~~~~~~~~~
814 In the preprocessor mode, the hash is formed of the common information and:
816 * the preprocessor output from running the compiler with *-E*
817 * the command line options except options that affect include files (*-I*,
818 *-include*, *-D*, etc; the theory is that these options will change the
819 preprocessor output if they have any effect at all)
820 * any standard error output generated by the preprocessor
822 Based on the hash, the cached compilation result can be looked up directly in
826 Compiling in different directories
827 ----------------------------------
829 Some information included in the hash that identifies a unique compilation can
830 contain absolute paths:
832 * The preprocessed source code may contain absolute paths to include files if
833 the compiler option *-g* is used or if absolute paths are given to *-I* and
834 similar compiler options.
835 * Paths specified by compiler options (such as *-I*, *-MF*, etc) on the command
836 line may be absolute.
837 * The source code file path may be absolute, and that path may substituted for
838 *\_\_FILE__* macros in the source code or included in warnings emitted to
839 standard error by the preprocessor.
841 This means that if you compile the same code in different locations, you can't
842 share compilation results between the different build directories since you get
843 cache misses because of the absolute build directory paths that are part of the
846 Here's what can be done to enable cache hits between different build
849 * If you build with *-g* (or similar) to add debug information to the object
850 file, you must either:
853 ** use the *-fdebug-prefix-map=_old_=_new_* option for relocating debug info to
854 a common prefix (e.g. *-fdebug-prefix-map=$PWD=.*); or
855 ** set *hash_dir = false*.
857 * If you use absolute paths anywhere on the command line (e.g. the source code
858 file path or an argument to compiler options like *-I* and *-MF*), you must
859 to set *base_dir* to an absolute path to a ``base directory''. ccache will
860 then rewrite absolute paths under that directory to relative before computing
867 ccache has support for GCC's precompiled headers. However, you have to do some
868 things to make it work properly:
870 * You must set *sloppiness* to *pch_defines,time_macros*. The reason is that
871 ccache can't tell whether *\_\_TIME\__* or *\_\_DATE__* is used when using a
872 precompiled header. Further, it can't detect changes in **#define**s in the
873 source code because of how preprocessing works in combination with
878 ** use the *-include* compiler option to include the precompiled header
879 (i.e., don't use *#include* in the source code to include the header); or
880 ** (for the Clang compiler) use the *-include-pch* compiler option to include
881 the PCH file generated from the precompiled header; or
882 ** add the *-fpch-preprocess* compiler option when compiling.
884 If you don't do this, either the non-precompiled version of the header file
885 will be used (if available) or ccache will fall back to running the real
886 compiler and increase the statistics counter ``preprocessor error'' (if the
887 non-precompiled header file is not available).
894 A group of developers can increase the cache hit rate by sharing a cache
895 directory. To share a cache without unpleasant side effects, the following
896 conditions should to be met:
898 * Use the same cache directory.
899 * Make sure that the configuration setting *hard_link* is false (which is the
901 * Make sure that all users are in the same group.
902 * Set the configuration setting *umask* to 002. This ensures that cached files
903 are accessible to everyone in the group.
904 * Make sure that all users have write permission in the entire cache directory
905 (and that you trust all users of the shared cache).
906 * Make sure that the setgid bit is set on all directories in the cache. This
907 tells the filesystem to inherit group ownership for new directories. The
908 following command might be useful for this:
912 find $CCACHE_DIR -type d | xargs chmod g+s
916 The reason to avoid the hard link mode is that the hard links cause unwanted
917 side effects, as all links to a cached file share the file's modification
918 timestamp. This results in false dependencies to be triggered by
919 timestamp-based build systems whenever another user links to an existing file.
920 Typically, users will see that their libraries and binaries are relinked
923 You may also want to make sure that a base directory is set appropriately, as
924 discussed in a previous section.
927 Sharing a cache on NFS
928 ----------------------
930 It is possible to put the cache directory on an NFS filesystem (or similar
931 filesystems), but keep in mind that:
933 * Having the cache on NFS may slow down compilation. Make sure to do some
934 benchmarking to see if it's worth it.
935 * ccache hasn't been tested very thoroughly on NFS.
937 A tip is to set *temporary_dir* to a directory on the local host to avoid NFS
938 traffic for temporary files.
941 Using ccache with other compiler wrappers
942 -----------------------------------------
944 The recommended way of combining ccache with another compiler wrapper (such as
945 ``distcc'') is by letting ccache execute the compiler wrapper. This is
946 accomplished by defining the configuration setting *prefix_command*, for
947 example by setting the environment variable *CCACHE_PREFIX* to the name of the
948 wrapper (e.g. *distcc*). ccache will then prefix the command line with the
949 specified command when running the compiler. To specify several prefix
950 commands, set *prefix_command* to a colon-separated list of commands.
952 Unless you set *compiler_check* to a suitable command (see the description of
953 that configuration option), it is not recommended to use the form *ccache
954 anotherwrapper compiler args* as the compilation command. It's also not
955 recommended to use the masquerading technique for the other compiler wrapper.
956 The reason is that by default, ccache will in both cases hash the mtime and
957 size of the other wrapper instead of the real compiler, which means that:
959 * Compiler upgrades will not be detected properly.
960 * The cached results will not be shared between compilations with and without
963 Another minor thing is that if *prefix_command* is used, ccache will not invoke
964 the other wrapper when running the preprocessor, which increases performance.
965 You can use the *prefix_command_cpp* configuration setting if you also want to
966 invoke the other wrapper when doing preprocessing (normally by adding *-E*).
972 * The direct mode fails to pick up new header files in some rare scenarios. See
973 <<_the_direct_mode,THE DIRECT MODE>> above.
982 A general tip for getting information about what ccache is doing is to enable
983 debug logging by setting *log_file*. The log contains executed commands,
984 important decisions that ccache makes, read and written files, etc. Another way
985 of keeping track of what is happening is to check the output of *ccache -s*.
991 ccache has been written to perform well out of the box, but sometimes you may
992 have to do some adjustments of how you use the compiler and ccache in order to
995 Since ccache works best when I/O is fast, put the cache directory on a fast
996 storage device if possible. Having lots of free memory so that files in the
997 cache directory stay in the disk cache is also preferable.
999 A good way of monitoring how well ccache works is to run *ccache -s* before and
1000 after your build and then compare the statistics counters. Here are some common
1001 problems and what may be done to increase the hit rate:
1003 * If ``cache hit (preprocessed)'' has been incremented instead of ``cache hit
1004 (direct)'', ccache has fallen back to preprocessor mode, which is generally
1005 slower. Some possible reasons are:
1006 ** The source code has been modified in such a way that the preprocessor output
1008 ** Compiler arguments that are hashed in the direct mode but not in the
1009 preprocessor mode have changed (*-I*, *-include*, *-D*, etc) and they didn't
1010 affect the preprocessor output.
1011 ** The compiler option *-Xpreprocessor* or *-Wp,_X_* (except *-Wp,-MD,_path_*,
1012 *-Wp,-MMD,_path_*, and *-Wp,-D_define_*) is used.
1013 ** This was the first compilation with a new value of the base directory
1015 ** A modification time of one of the include files is too new (created the same
1016 second as the compilation is being done). This check is made to avoid a race
1017 condition. To fix this, create the include file earlier in the build
1018 process, if possible, or set *sloppiness* to *include_file_mtime* if you are
1019 willing to take the risk. (The race condition consists of these events: the
1020 preprocessor is run; an include file is modified by someone; the new include
1021 file is hashed by ccache; the real compiler is run on the preprocessor's
1022 output, which contains data from the old header file; the wrong object file
1023 is stored in the cache.)
1024 ** The *\_\_TIME\__* preprocessor macro is (potentially) being used. ccache
1025 turns off direct mode if ``\_\_TIME\__'' is present in the source code. This
1026 is done as a safety measure since the string indicates that a *\_\_TIME\__*
1027 macro _may_ affect the output. (To be sure, ccache would have to run the
1028 preprocessor, but the sole point of the direct mode is to avoid that.) If
1029 you know that *\_\_TIME\__* isn't used in practise, or don't care if ccache
1030 produces objects where *\_\_TIME__* is expanded to something in the past,
1031 you can set *sloppiness* to *time_macros*.
1032 ** The *\_\_DATE\__* preprocessor macro is (potentially) being used and the
1033 date has changed. This is similar to how *\_\_TIME\__* is handled. If
1034 ``\_\_DATE\__'' is present in the source code, ccache hashes the current
1035 date in order to be able to produce the correct object file if the
1036 *\_\_DATE\__* macro affects the output. If you know that *\_\_DATE\__* isn't
1037 used in practise, or don't care if ccache produces objects where
1038 *\_\_DATE__* is expanded to something in the past, you can set *sloppiness*
1040 ** The *\_\_FILE\__* preprocessor macro is (potentially) being used and the
1041 file path has changed. If ``\_\_FILE\__'' is present in the source code,
1042 ccache hashes the current input file path in order to be able to produce the
1043 correct object file if the *\_\_FILE\__* macro affects the output. If you
1044 know that *\_\_FILE\__* isn't used in practise, or don't care if ccache
1045 produces objects where *\_\_FILE__* is expanded to the wrong path, you can
1046 set *sloppiness* to *file_macro*.
1047 * If ``cache miss'' has been incremented even though the same code has been
1048 compiled and cached before, ccache has either detected that something has
1049 changed anyway or a cleanup has been performed (either explicitly or
1050 implicitly when a cache limit has been reached). Some perhaps unobvious
1051 things that may result in a cache miss are usage of *\_\_TIME\__* or
1052 *\_\_DATE__* macros, or use of automatically generated code that contains a
1053 timestamp, build counter or other volatile information.
1054 * If ``multiple source files'' has been incremented, it's an indication that
1055 the compiler has been invoked on several source code files at once. ccache
1056 doesn't support that. Compile the source code files separately if possible.
1057 * If ``unsupported compiler option'' has been incremented, enable debug logging
1058 and check which option was rejected.
1059 * If ``preprocessor error'' has been incremented, one possible reason is that
1060 precompiled headers are being used. See <<_precompiled_headers,PRECOMPILED
1061 HEADERS>> for how to remedy this.
1062 * If ``can't use precompiled header'' has been incremented, see
1063 <<_precompiled_headers,PRECOMPILED HEADERS>>.
1066 Corrupt object files
1067 ~~~~~~~~~~~~~~~~~~~~
1069 It should be noted that ccache is susceptible to general storage problems. If a
1070 bad object file sneaks into the cache for some reason, it will of course stay
1071 bad. Some possible reasons for erroneous object files are bad hardware (disk
1072 drive, disk controller, memory, etc), buggy drivers or file systems, a bad
1073 *prefix_command* or compiler wrapper. If this happens, the easiest way of
1076 1. Build so that the bad object file ends up in the build tree.
1077 2. Remove the bad object file from the build tree.
1078 3. Rebuild with *CCACHE_RECACHE* set.
1080 An alternative is to clear the whole cache with *ccache -C* if you don't mind
1081 losing other cached results.
1083 There are no reported issues about ccache producing broken object files
1084 reproducibly. That doesn't mean it can't happen, so if you find a repeatable
1085 case, please report it.
1091 Credits, mailing list information, bug reporting instructions, source code,
1092 etc, can be found on ccache's web site: <https://ccache.samba.org>.
1098 ccache was originally written by Andrew Tridgell and is currently developed and
1099 maintained by Joel Rosdahl. See AUTHORS.txt or AUTHORS.html and
1100 <https://ccache.samba.org/credits.html> for a list of contributors.