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 <<_bugs,BUGS>>. If you ever discover an undocumented case
34 where ccache changes the output of your compiler, please let us know.
40 * Keeps statistics on hits/misses.
41 * Automatic cache size management.
42 * Can cache compilations that generate warnings.
45 * Optionally uses hard links where possible to avoid copies.
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. *Note*:
166 *--ccache-skip* currently only tells ccache not to interpret the next option as
167 a special compiler option -- the option will still be included in the direct
170 The reason this can be important is that ccache does need to parse the command
171 line and determine what is an input filename and what is a compiler option, as
172 it needs the input filename to determine the name of the resulting object file
173 (among other things). The heuristic ccache uses when parsing the command line
174 is that any argument that exists as a file is treated as an input file name. By
175 using *--ccache-skip* you can force an option to not be treated as an input
176 file name and instead be passed along to the compiler as a command line option.
178 Another case where *--ccache-skip* can be useful is if ccache interprets an
179 option specially but shouldn't, since the option has another meaning for your
180 compiler than what ccache thinks.
186 ccache's default behavior can be overridden by configuration file settings,
187 which in turn can be overridden by environment variables with names starting
188 with *CCACHE_*. ccache normally reads configuration from two files: first a
189 system-level configuration file and secondly a cache-specific configuration
190 file. The priority of configuration settings is as follows (where 1 is
193 1. Environment variables.
194 2. The cache-specific configuration file *<ccachedir>/ccache.conf* (typically
195 *$HOME/.ccache/ccache.conf*).
196 3. The system-wide configuration file *<sysconfdir>/ccache.conf* (typically
197 */etc/ccache.conf* or */usr/local/etc/ccache.conf*).
198 4. Compile-time defaults.
200 As a special case, if the environment variable *CCACHE_CONFIGPATH* is set,
201 ccache reads configuration from the specified path instead of the default
205 Configuration file syntax
206 ~~~~~~~~~~~~~~~~~~~~~~~~~
208 Configuration files are in a simple ``key = value'' format, one setting per
209 line. Lines starting with a hash sign are comments. Blank lines are ignored, as
210 is whitespace surrounding keys and values. Example:
212 -------------------------------------------------------------------------------
213 # Set maximum cache size to 10 GB:
215 -------------------------------------------------------------------------------
220 Some settings are boolean values (i.e. truth values). In a configuration file,
221 such values must be set to the string *true* or *false*. For the corresponding
222 environment variables, the semantics are a bit different: a set environment
223 variable means ``true'' regardless of the value (even if set to the empty
224 string), and an unset environment variable means ``false''. Each boolean
225 environment variable also has a negated form starting with *CCACHE_NO*. For
226 example, *CCACHE_COMPRESS* can be set to force compression and
227 *CCACHE_NOCOMPRESS* can be set to force no compression.
230 Configuration settings
231 ~~~~~~~~~~~~~~~~~~~~~~
233 Below is a list of available configuration settings. The corresponding
234 environment variable name is indicated in parentheses after each configuration
235 setting key. Boolean options are indicated with ``[boolean]''
237 *base_dir* (*CCACHE_BASEDIR*)::
239 This setting should be an absolute path to a directory. ccache then
240 rewrites absolute paths into relative paths before computing the hash that
241 identifies the compilation, but only for paths under the specified
242 directory. If set to the empty string (which is the default), no rewriting
243 is done. See also the discussion under
244 <<_compiling_in_different_directories,COMPILING IN DIFFERENT DIRECTORIES>>.
246 *cache_dir* (*CCACHE_DIR*)::
248 This setting specifies where ccache will keep its cached compiler outputs.
249 It will only take effect if set in the system-wide configuration file or as
250 an environment variable. The default is *$HOME/.ccache*.
252 *cache_dir_levels* (*CCACHE_NLEVELS*)::
254 This setting allows you to choose the number of directory levels in the
255 cache directory. The default is 2. The minimum is 1 and the maximum is 8.
257 *compiler* (*CCACHE_CC*)::
259 This setting can be used to force the name of the compiler to use. If set
260 to the empty string (which is the default), ccache works it out from the
263 *compiler_check* (*CCACHE_COMPILERCHECK*)::
265 By default, ccache includes the modification time (``mtime'') and size of
266 the compiler in the hash to ensure that results retrieved from the cache
267 are accurate. This setting can be used to select another strategy. Possible
272 Hash the content of the compiler binary. This makes ccache very slightly
273 slower compared to the *mtime* setting, but makes it cope better with
274 compiler upgrades during a build bootstrapping process.
276 Hash the compiler's mtime and size, which is fast. This is the default.
278 Don't hash anything. This may be good for situations where you can safely
279 use the cached results even though the compiler's mtime or size has changed
280 (e.g. if the compiler is built as part of your build system and the
281 compiler's source has not changed, or if the compiler only has changes that
282 don't affect code generation). You should only use the *none* setting if
283 you know what you are doing.
285 Hash the standard output and standard error output of the specified
286 command. The string will be split on whitespace to find out the command and
287 arguments to run. No other interpretation of the command string will be
288 done, except that the special word *%compiler%* will be replaced with the
289 path to the compiler. Several commands can be specified with semicolon as
294 * +%compiler% -dumpmachine; %compiler% -dumpversion+
296 You should make sure that the specified command is as fast as possible since it
297 will be run once for each ccache invocation.
299 Identifying the compiler using a command is useful if you want to avoid cache
300 misses when the compiler has been rebuilt but not changed.
302 Another case is when the compiler (as seen by ccache) actually isn't the real
303 compiler but another compiler wrapper -- in that case, the default *mtime*
304 method will hash the mtime and size of the other compiler wrapper, which means
305 that ccache won't be able to detect a compiler upgrade. Using a suitable
306 command to identify the compiler is thus safer, but it's also slower, so you
307 should consider continue using the *mtime* method in combination with
308 the *prefix_command* setting if possible. See
309 <<_using_ccache_with_other_compiler_wrappers,USING CCACHE WITH OTHER COMPILER
314 *compression* (*CCACHE_COMPRESS*) [boolean]::
316 If true, ccache will compress object files and other compiler output it
317 puts in the cache. However, this setting has no effect on how files are
318 retrieved from the cache; compressed and uncompressed results will still be
319 usable regardless of this setting. The default is false.
321 *compression_level* (*CCACHE_COMPRESSLEVEL*)::
323 This setting determines the level at which ccache will compress object
324 files. It only has effect if *compression* is enabled. The value defaults
325 to 6, and must be no lower than 1 (fastest, worst compression) and no
326 higher than 9 (slowest, best compression).
328 *cpp_extension* (*CCACHE_EXTENSION*)::
330 This setting can be used to force a certain extension for the intermediate
331 preprocessed file. The default is to automatically determine the extension
332 to use for intermediate preprocessor files based on the type of file being
333 compiled, but that sometimes doesn't work. For example, when using the
334 ``aCC'' compiler on HP-UX, set the cpp extension to *i*.
336 *direct_mode* (*CCACHE_DIRECT*) [boolean]::
338 If true, the direct mode will be used. The default is true. See
339 <<_the_direct_mode,THE DIRECT MODE>>.
341 *disable* (*CCACHE_DISABLE*) [boolean]::
343 When true, ccache will just call the real compiler, bypassing the cache
344 completely. The default is false.
346 *extra_files_to_hash* (*CCACHE_EXTRAFILES*)::
348 This setting is a list of paths to files that ccache will include in the
349 the hash sum that idetifies the build. The list separator is semicolon on
350 Windows systems and colon on other systems.
352 *hard_link* (*CCACHE_HARDLINK*) [boolean]::
354 If true, ccache will attempt to use hard links from the cache directory
355 when creating the compiler output rather than using a file copy. Using hard
356 links may be slightly faster in some situations, but can confuse programs
357 like ``make'' that rely on modification times. Another thing to keep in
358 mind is that if the resulting object file is modified in any way, this
359 corrupts the cached object file as well. Hard links are never made for
360 compressed cache files. This means that you should not enable compression
361 if you want to use hard links. The default is false.
363 *hash_dir* (*CCACHE_HASHDIR*) [boolean]::
365 If true, ccache will include the current working directory in the hash that
366 is used to distinguish two compilations. This prevents a problem with the
367 storage of the current working directory in the debug info of a object
368 file, which can lead ccache to give a cached object file that has the
369 working directory in the debug info set incorrectly. This option is off by
370 default as the incorrect setting of this debug info rarely causes problems.
371 If you strike problems with GDB not using the correct directory then enable
374 *log_file* (*CCACHE_LOGFILE*)::
376 If set to a file path, ccache will write information on what it is doing to
377 the specified file. This is useful for tracking down problems.
379 *stats* (*CCACHE_STATS*) [boolean]::
381 If true, ccache will update the statistics counters on each compilation.
384 *path* (*CCACHE_PATH*)::
386 If set, ccache will search directories in this list when looking for the
387 real compiler. The list separator is semicolon on Windows systems and colon
388 on other systems. If not set, ccache will look for the first executable
389 matching the compiler name in the normal *PATH* that isn't a symbolic link
392 *prefix_command* (*CCACHE_PREFIX*)::
394 This option adds a list of prefixes (separated by space) to the command
395 line that ccache uses when invoking the compiler. See also
396 <<_using_ccache_with_other_compiler_wrappers,USING CCACHE WITH OTHER
399 *read_only* (*CCACHE_READONLY*) [boolean]::
401 If true, ccache will attempt to use existing cached object files, but it
402 will not to try to add anything new to the cache. If you are using this
403 because your ccache directory is read-only, then you need to set
404 *temporary_dir* as otherwise ccache will fail to create temporary files.
406 *read_only_direct* (*CCACHE_READONLY_DIRECT*) [boolean]::
408 Just like *read_only* except that ccache will only try to retrieve results
409 from the cache using the direct mode, not the preprocessor mode. See
410 documentation for *read_only* regarding using a read-only ccache directory.
412 *reache* (*CCACHE_RECACHE*) [boolean]::
414 If true, ccache will not use any previously stored result. New results will
415 still be cached, possibly overwriting any pre-existing results.
417 *run_second_cpp* (*CCACHE_CPP2*) [boolean]::
419 If true, ccache will not use the optimisation of avoiding the second call
420 to the preprocessor by compiling the preprocessed output that was used for
421 finding the hash in the case of a cache miss. This is primarily a debugging
422 option, although it is possible that some unusual compilers will have
423 problems with compiling the preprocessed output, in which case this option
424 could allow ccache to be used anyway.
426 *sloppiness* (*CCACHE_SLOPPINESS*)::
428 By default, ccache tries to give as few false cache hits as possible.
429 However, in certain situations it's possible that you know things that
430 ccache can't take for granted. This setting makes it possible to tell
431 ccache to relax some checks in order to increase the hit rate. The value
432 should be a comma-separated string with options. Available options are:
436 Ignore *\_\_FILE__* being present in the source.
437 *file_stat_matches*::
438 ccache normally examines a file's contents to determine whether it matches
439 the cached version. With this option set, ccache will consider a file as
440 matching its cached version if the sizes, mtimes and ctimes match.
441 *include_file_ctime*::
442 By default, ccache also will not cache a file if it includes a header whose
443 ctime is too new. This option disables that check.
444 *include_file_mtime*::
445 By default, ccache will not cache a file if it includes a header whose
446 mtime is too new. This option disables that check.
448 Be sloppy about #defines when precompiling a header file. See
449 <<_precompiled_headers,PRECOMPILED HEADERS>> for more information.
451 Ignore *\_\_DATE\__* and *\_\_TIME__* being present in the source code.
454 See the discussion under <<_troubleshooting,TROUBLESHOOTING>> for more
457 *temporary_dir* (*CCACHE_TEMPDIR*)::
459 This setting specifies where ccache will put temporary files. The default
460 is *<cache_dir>/tmp*.
462 NOTE: In previous versions of ccache, *CCACHE_TEMPDIR* had to be on the same
463 filesystem as the *CCACHE_DIR* path, but this requirement has been
466 *umask* (*CCACHE_UMASK*)::
468 This setting specifies the umask for ccache and all child processes (such
469 as the compiler). This is mostly useful when you wish to share your cache
470 with other users. Note that this also affects the file permissions set on
471 the object files created from your compilations.
473 *unify* (*CCACHE_UNIFY*) [boolean]::
475 If true, ccache will use a C/C++ unifier when hashing the preprocessor
476 output if the *-g* option is not used. The unifier is slower than a normal
477 hash, so setting this environment variable loses a little bit of speed, but
478 it means that ccache can take advantage of not recompiling when the changes
479 to the source code consist of reformatting only. Note that enabling the
480 unifier changes the hash, so cached compilations produced when the unifier
481 is enabled cannot be reused when the unifier is disabled, and vice versa.
482 Enabling the unifier may result in incorrect line number information in
483 compiler warning messages and expansions of the *\_\_LINE__* macro. Also
484 note that enabling the unifier implies turning off the direct mode.
487 Cache size management
488 ---------------------
490 By default, ccache has a five gigabyte limit on the total size of files in the
491 cache and no maximum number of files. You can set different limits using the
492 *-M*/*--max-size* and *-F*/*--max-files* options. Use *ccache -s/--show-stats*
493 to see the cache size and the currently configured limits (in addition to other
500 ccache can optionally compress all files it puts into the cache using the
501 compression library zlib. While this may involve a tiny performance slowdown,
502 it increases the number of files that fit in the cache. You can turn on
503 compression with the *compression* configuration setting and you can also tweak
504 the compression level with *compression_level*.
510 The basic idea is to detect when you are compiling exactly the same code a
511 second time and reuse the previously produced output. The detection is done by
512 hashing different kinds of information that should be unique for the
513 compilation and then using the hash sum to identify the cached output. ccache
514 uses MD4, a very fast cryptographic hash algorithm, for the hashing. (MD4 is
515 nowadays too weak to be useful in cryptographic contexts, but it should be safe
516 enough to be used to identify recompilations.) On a cache hit, ccache is able
517 to supply all of the correct compiler outputs (including all warnings,
518 dependency file, etc) from the cache.
520 ccache has two ways of doing the detection:
522 * the *direct mode*, where ccache hashes the source code and include files
524 * the *preprocessor mode*, where ccache runs the preprocessor on the source
525 code and hashes the result
527 The direct mode is generally faster since running the preprocessor has some
531 Common hashed information
532 ~~~~~~~~~~~~~~~~~~~~~~~~~
534 For both modes, the following information is included in the hash:
536 * the extension used by the compiler for a file with preprocessor output
537 (normally *.i* for C code and *.ii* for C++ code)
538 * the compiler's size and modification time (or other compiler-specific
539 information specified by the *compiler_check* setting)
540 * the name of the compiler
541 * the current directory (if the *hash_dir* setting is enabled)
542 * contents of files specified by the *extra_files_to_hash* setting (if any)
548 In the direct mode, the hash is formed of the common information and:
550 * the input source file
551 * the command line options
553 Based on the hash, a data structure called ``manifest'' is looked up in the
554 cache. The manifest contains:
556 * references to cached compilation results (object file, dependency file, etc)
557 that were produced by previous compilations that matched the hash
558 * paths to the include files that were read at the time the compilation results
559 were stored in the cache
560 * hash sums of the include files at the time the compilation results were
563 The current contents of the include files are then hashed and compared to the
564 information in the manifest. If there is a match, ccache knows the result of
565 the compilation. If there is no match, ccache falls back to running the
566 preprocessor. The output from the preprocessor is parsed to find the include
567 files that were read. The paths and hash sums of those include files are then
568 stored in the manifest along with information about the produced compilation
571 There is a catch with the direct mode: header files that were used by the
572 compiler are recorded, but header files that were *not* used, but would have
573 been used if they existed, are not. So, when ccache checks if a result can be
574 taken from the cache, it currently can't check if the existence of a new header
575 file should invalidate the result. In practice, the direct mode is safe to use
576 in the absolute majority of cases.
578 The direct mode will be disabled if any of the following holds:
580 * the configuration setting *direct_mode* is false
581 * a modification time of one of the include files is too new (needed to avoid a
583 * the unifier is enabled (the configuration setting *unify* is true)
584 * a compiler option not supported by the direct mode is used:
585 ** a *-Wp,_X_* compiler option other than *-Wp,-MD,_path_* and
588 * the string ``\_\_TIME__'' is present in the source code
591 The preprocessor mode
592 ~~~~~~~~~~~~~~~~~~~~~
594 In the preprocessor mode, the hash is formed of the common information and:
596 * the preprocessor output from running the compiler with *-E*
597 * the command line options except options that affect include files (*-I*,
598 *-include*, *-D*, etc; the theory is that these options will change the
599 preprocessor output if they have any effect at all)
600 * any standard error output generated by the preprocessor
602 Based on the hash, the cached compilation result can be looked up directly in
606 Compiling in different directories
607 ----------------------------------
609 Some information included in the hash that identifies a unique compilation may
610 contain absolute paths:
612 * The preprocessed source code may contain absolute paths to include files if
613 the compiler option *-g* is used or if absolute paths are given to *-I* and
614 similar compiler options.
615 * Paths specified by compiler options (such as *-I*, *-MF*, etc) may be
617 * The source code file path may be absolute, and that path may substituted for
618 *\_\_FILE__* macros in the source code or included in warnings emitted to
619 standard error by the preprocessor.
621 This means that if you compile the same code in different locations, you can't
622 share compilation results between the different build directories since you get
623 cache misses because of the absolute build directory paths that are part of the
624 hash. To mitigate this problem, you can specify a ``base directory'' in the
625 configuration setting *base_dir* to an absolute path to the directory. ccache
626 will then rewrite absolute paths that are under the base directory (i.e., paths
627 that have the base directory as a prefix) to relative paths when constructing
628 the hash. A typical path to use as the base directory is your home directory or
629 another directory that is a parent of your build directories. (Don't use +/+ as
630 the base directory since that will make ccache also rewrite paths to system
631 header files, which doesn't gain anything.)
633 The drawbacks of using a base directory are:
635 * If you specify an absolute path to the source code file, *\_\_FILE__* macros
636 will be expanded to a relative path instead.
637 * If you specify an absolute path to the source code file and compile with
638 *-g*, the source code path stored in the object file may point to the wrong
639 directory, which may prevent debuggers like GDB from finding the source code.
640 Sometimes, a work-around is to change the directory explicitly with the
641 ``cd'' command in GDB.
647 ccache has support for GCC's precompiled headers. However, you have to do some
648 things to make it work properly:
650 * You must set *sloppiness* to *pch_defines,time_macros*. The reason is that
651 ccache can't tell whether *\_\_TIME\__* or *\_\_DATE__* is used when using a
652 precompiled header. Further, it can't detect changes in #defines in the
653 source code because of how preprocessing works in combination with
658 ** use the *-include* compiler option to include the precompiled header
659 (i.e., don't use *#include* in the source code to include the header); or
660 ** (for the Clang compiler) use the *-include-pch* compiler option to include
661 the PCH file generated from the precompiled header; or
662 ** add the *-fpch-preprocess* compiler option when compiling.
664 If you don't do this, either the non-precompiled version of the header file
665 will be used (if available) or ccache will fall back to running the real
666 compiler and increase the statistics counter ``preprocessor error'' (if the
667 non-precompiled header file is not available).
674 A group of developers can increase the cache hit rate by sharing a cache
675 directory. To share a cache without unpleasant side effects, the following
676 conditions should to be met:
678 * Use the same cache directory.
679 * Make sure that the configuration setting *hard_link* is false (which is the
681 * Make sure that all users are in the same group.
682 * Set the configuration setting *umask* to 002. This ensures that cached files
683 are accessible to everyone in the group.
684 * Make sure that all users have write permission in the entire cache directory
685 (and that you trust all users of the shared cache).
686 * Make sure that the setgid bit is set on all directories in the cache. This
687 tells the filesystem to inherit group ownership for new directories. The
688 command ``find $CCACHE_DIR -type d | xargs chmod g+s'' might be useful for
691 The reason to avoid the hard link mode is that the hard links cause unwanted
692 side effects, as all links to a cached file share the file's modification
693 timestamp. This results in false dependencies to be triggered by
694 timestamp-based build systems whenever another user links to an existing file.
695 Typically, users will see that their libraries and binaries are relinked
698 You may also want to make sure that a base directory is set appropriately, as
699 discussed in a previous section.
702 Sharing a cache on NFS
703 ----------------------
705 It is possible to put the cache directory on an NFS filesystem (or similar
706 filesystems), but keep in mind that:
708 * Having the cache on NFS may slow down compilation. Make sure to do some
709 benchmarking to see if it's worth it.
710 * ccache hasn't been tested very thoroughly on NFS.
712 A tip is to set *temporary_dir* to a directory on the local host to avoid NFS
713 traffic for temporary files.
716 Using ccache with other compiler wrappers
717 -----------------------------------------
719 The recommended way of combining ccache with another compiler wrapper (such as
720 ``distcc'') is by letting ccache execute the compiler wrapper. This is
721 accomplished by defining the configuration setting *prefix_command*, for
722 example by setting the environment variable *CCACHE_PREFIX* to the name of the
723 wrapper (e.g. *distcc*). ccache will then prefix the command line with the
724 specified command when running the compiler. To specify several prefix
725 commands, set *prefix_command* to a colon-separated list of commands.
727 Unless you set *compiler_check* to a suitable command (see the description of
728 that configuration option), it is not recommended to use the form *ccache
729 anotherwrapper compiler args* as the compilation command. It's also not
730 recommended to use the masquerading technique for the other compiler wrapper.
731 The reason is that by default, ccache will in both cases hash the mtime and
732 size of the other wrapper instead of the real compiler, which means that:
734 * Compiler upgrades will not be detected properly.
735 * The cached results will not be shared between compilations with and without
738 Another minor thing is that if *prefix_command* is used, ccache will not invoke
739 the other wrapper when running the preprocessor, which increase performance.
745 * ccache doesn't handle the GNU Assembler's *.incbin* directive correctly. This
746 directive can be embedded in the source code inside an *__asm__* statement in
747 order to include a file verbatim in the object file. If the included file is
748 modified, ccache doesn't pick up the change since the inclusion isn't done by
749 the preprocessor. A workaround of this problem is to set
750 *extra_files_to_hash* to the path of the included file.
752 * The direct mode fails to pick up new header files in some rare scenarios. See
753 <<_the_direct_mode,THE DIRECT MODE>> above.
762 A general tip for getting information about what ccache is doing is to enable
763 debug logging by setting *log_file*. The log contains executed commands,
764 important decisions that ccache makes, read and written files, etc. Another way
765 of keeping track of what is happening is to check the output of *ccache -s*.
771 ccache has been written to perform well out of the box, but sometimes you may
772 have to do some adjustments of how you use the compiler and ccache in order to
775 Since ccache works best when I/O is fast, put the cache directory on a fast
776 storage device if possible. Having lots of free memory so that files in the
777 cache directory stay in the disk cache is also preferrable.
779 A good way of monitoring how well ccache works is to run *ccache -s* before and
780 after your build and then compare the statistics counters. Here are some common
781 problems and what may be done to increase the hit rate:
783 * If ``cache hit (preprocessed)'' has been incremented instead of ``cache hit
784 (direct)'', ccache has fallen back to preprocessor mode, which is generally
785 slower. Some possible reasons are:
786 ** The source code has been modified in such a way that the preprocessor output
788 ** Compiler arguments that are hashed in the direct mode but not in the
789 preprocessor mode have changed (*-I*, *-include*, *-D*, etc) and they didn't
790 affect the preprocessor output.
791 ** The compiler option *-Xpreprocessor* or *-Wp,_X_* (except *-Wp,-MD,_path_*
792 and *Wp,-MMD,_path_*) is used.
793 ** This was the first compilation with a new value of the base directory
795 ** A modification time of one of the include files is too new (created the same
796 second as the compilation is being done). This check is made to avoid a race
797 condition. To fix this, create the include file earlier in the build
798 process, if possible, or set *sloppiness* to *include_file_mtime* if you are
799 willing to take the risk. (The race condition consists of these events: the
800 preprocessor is run; an include file is modified by someone; the new include
801 file is hashed by ccache; the real compiler is run on the preprocessor's
802 output, which contains data from the old header file; the wrong object file
803 is stored in the cache.)
804 ** The *\_\_TIME\__* preprocessor macro is (potentially) being used. ccache
805 turns off direct mode if ``\_\_TIME\__'' is present in the source code
806 outside comments and string literals. This is done as a safety measure since
807 the string indicates that a *\_\_TIME\__* macro _may_ affect the output. (To
808 be sure, ccache would have to run the preprocessor, but the sole point of
809 the direct mode is to avoid that.) If you know that *\_\_TIME\__* isn't used
810 in practise, or don't care if ccache produces objects where *\_\_TIME__* is
811 expanded to something in the past, you can set *sloppiness* to
813 ** The *\_\_DATE\__* preprocessor macro is (potentially) being used and the
814 date has changed. This is similar to how *\_\_TIME\__* is handled. If
815 ``\_\_DATE\__'' is present in the source code outside comments and string
816 literals, ccache hashes the current date in order to be able to produce the
817 correct object file if the *\_\_DATE\__* macro affects the output. If you
818 know that *\_\_DATE\__* isn't used in practise, or don't care if ccache
819 produces objects where *\_\_DATE__* is expanded to something in the past,
820 you can set *sloppiness* to *time_macros*.
821 ** The *\_\_FILE\__* preprocessor macro is (potentially) being used and the
822 file path has changed. If ``\_\_FILE\__'' is present in the source code
823 outside comments and string literals, ccache hashes the current input file
824 path in order to be able to produce the correct object file if the
825 *\_\_FILE\__* macro affects the output. If you know that *\_\_FILE\__* isn't
826 used in practise, or don't care if ccache produces objects where
827 *\_\_FILE__* is expanded to the wrong path, you can set *sloppiness* to
829 * If ``cache miss'' has been incremented even though the same code has been
830 compiled and cached before, ccache has either detected that something has
831 changed anyway or a cleanup has been performed (either explicitly or
832 implicitly when a cache limit has been reached). Some perhaps unobvious
833 things that may result in a cache miss are usage of *\_\_TIME\__* or
834 *\_\_DATE__* macros, or use of automatically generated code that contains a
835 timestamp, build counter or other volatile information.
836 * If ``multiple source files'' has been incremented, it's an indication that
837 the compiler has been invoked on several source code files at once. ccache
838 doesn't support that. Compile the source code files separately if possible.
839 * If ``unsupported compiler option'' has been incremented, enable debug logging
840 and check which option was rejected.
841 * If ``preprocessor error'' has been incremented, one possible reason is that
842 precompiled headers are being used. See <<_precompiled_headers,PRECOMPILED
843 HEADERS>> for how to remedy this.
844 * If ``can't use precompiled header'' has been incremented, see
845 <<_precompiled_headers,PRECOMPILED HEADERS>>.
848 Errors when compiling with ccache
849 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
851 If compilation doesn't work with ccache, but it works without it, one possible
852 reason is that the compiler can't compile preprocessed output correctly. A
853 workaround that may work is to enable *run_second_cpp**. This will make cache
854 misses slower, though, so it is better to find and fix the root cause.
860 It should be noted that ccache is susceptible to general storage problems. If a
861 bad object file sneaks into the cache for some reason, it will of course stay
862 bad. Some possible reasons for erroneous object files are bad hardware (disk
863 drive, disk controller, memory, etc), buggy drivers or file systems, a bad
864 *prefix_command* or compiler wrapper. If this happens, the easiest way of
867 1. Build so that the bad object file ends up in the build tree.
868 2. Remove the bad object file from the build tree.
869 3. Rebuild with *CCACHE_RECACHE* set.
871 An alternative is to clear the whole cache with *ccache -C* if you don't mind
872 losing other cached results.
874 There are no reported issues about ccache producing broken object files
875 reproducibly. That doesn't mean it can't happen, so if you find a repeatable
876 case, please report it.
882 Credits, mailing list information, bug reporting instructions, source code,
883 etc, can be found on ccache's web site: <http://ccache.samba.org>.
889 ccache was originally written by Andrew Tridgell and is currently developed and
890 maintained by Joel Rosdahl. See AUTHORS.txt or AUTHORS.html and
891 <http://ccache.samba.org/credits.html> for a list of contributors.