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, it's not needed 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.
117 *-F, --max-files*='N'::
119 Set the maximum number of files allowed in the cache. The value is stored
120 inside the cache directory and applies to all future compilations. Due to
121 the way the value is stored the actual value used is always rounded down to
122 the nearest multiple of 16.
126 Print an options summary page.
128 *-M, --max-size*='SIZE'::
130 Set the maximum size of the files stored in the cache. You can specify a
131 value in gigabytes, megabytes or kilobytes by appending a G, M or K to the
132 value. The default is gigabytes. The actual value stored is rounded down to
133 the nearest multiple of 16 kilobytes.
137 Print the current statistics summary for the cache.
141 Print version and copyright information.
145 Zero the cache statistics (but not the configured limits).
151 When run as a compiler, ccache usually just takes the same command line options
152 as the compiler you are using. The only exception to this is the option
153 *--ccache-skip*. That option can be used to tell ccache to avoid interpreting
154 the next option in any way and to pass it along to the compiler as-is.
156 The reason this can be important is that ccache does need to parse the command
157 line and determine what is an input filename and what is a compiler option, as
158 it needs the input filename to determine the name of the resulting object file
159 (among other things). The heuristic ccache uses when parsing the command line
160 is that any argument that exists as a file is treated as an input file name. By
161 using *--ccache-skip* you can force an option to not be treated as an input
162 file name and instead be passed along to the compiler as a command line option.
164 Another case where *--ccache-skip* can be useful is if ccache interprets an
165 option specially but shouldn't, since the option has another meaning for your
166 compiler than what ccache thinks.
169 Environment variables
170 ---------------------
172 ccache uses a number of environment variables to control operation. In most
173 cases you won't need any of these as the defaults will be fine.
177 If you set the environment variable *CCACHE_BASEDIR* to an absolute path to
178 a directory, ccache rewrites absolute paths into relative paths before
179 computing the hash that identifies the compilation, but only for paths
180 under the specified directory. See the discussion under
181 <<_compiling_in_different_directories,COMPILING IN DIFFERENT DIRECTORIES>>.
185 You can optionally set *CCACHE_CC* to force the name of the compiler to
186 use. If you don't do this then ccache works it out from the command line.
188 *CCACHE_COMPILERCHECK*::
190 By default, ccache includes the modification time (``mtime'') and size of
191 the compiler in the hash to ensure that results retrieved from the cache
192 are accurate. The *CCACHE_COMPILERCHECK* environment variable can be used
193 to select another strategy. Possible values are:
197 Hash the content of the compiler binary. This makes ccache very slightly
198 slower compared to the *mtime* setting, but makes it cope better with
199 compiler upgrades during a build bootstrapping process.
201 Hash the compiler's mtime and size, which is fast. This is the default.
203 Don't hash anything. This may be good for situations where you can safely
204 use the cached results even though the compiler's mtime or size has changed
205 (e.g. if the compiler is built as part of your build system and the
206 compiler's source has not changed, or if the compiler only has changes that
207 don't affect code generation). You should only use the *none* setting if
208 you know what you are doing.
210 Hash the standard output and standard error output of the specified
211 command. The string will be split on whitespace to find out the command and
212 arguments to run. No other interpretation of the command string will be
213 done, except that the special word ``%compiler%'' will be replaced with the
214 path to the compiler. Several commands can be specified with semicolon as
219 * +%compiler% -dumpmachine; %compiler% -dumpversion+
221 You should make sure that the specified command is as fast as possible since it
222 will be run once for each ccache invocation.
224 Identifying the compiler using a command is useful if you want to avoid cache
225 misses when the compiler has been rebuilt but not changed.
227 Another case is when the compiler (as seen by ccache) actually isn't the real
228 compiler but another compiler wrapper -- in that case, the default *mtime*
229 method will hash the mtime and size of the other compiler wrapper, which means
230 that ccache won't be able to detect a compiler upgrade. Using a suitable
231 command to identify the compiler is thus safer, but it's also slower, so you
232 should consider continue using the *mtime* method in combination with
233 *CCACHE_PREFIX* if possible. See
234 <<_using_ccache_with_other_compiler_wrappers,USING CCACHE WITH OTHER COMPILER
241 If you set the environment variable *CCACHE_COMPRESS* then ccache will
242 compress object files and other compiler output it puts in the cache.
243 However, this setting has no effect on how files are retrieved from the
244 cache; compressed and uncompressed results will still be usable regardless
249 If you set the environment variable *CCACHE_CPP2* then ccache will not use
250 the optimisation of avoiding the second call to the preprocessor by
251 compiling the preprocessed output that was used for finding the hash in the
252 case of a cache miss. This is primarily a debugging option, although it is
253 possible that some unusual compilers will have problems with the
254 intermediate filename extensions used in this optimisation, in which case
255 this option could allow ccache to be used anyway.
257 *CCACHE_DETECT_SHEBANG*::
259 The *CCACHE_DETECT_SHEBANG* environment variable only has meaning on
260 Windows. It instructs ccache to open the executable file to detect the
261 *#!/bin/sh* string, in which case ccache will search for *sh.exe* in
262 *PATH* and use that to launch the executable.
266 The *CCACHE_DIR* environment variable specifies where ccache will keep its
267 cached compiler output. The default is *$HOME/.ccache*.
271 If you set the environment variable *CCACHE_DISABLE* then ccache will just
272 call the real compiler, bypassing the cache completely.
276 ccache tries to automatically determine the extension to use for
277 intermediate preprocessor files based on the type of file being compiled.
278 Unfortunately this sometimes doesn't work, for example when using the
279 ``aCC'' compiler on HP-UX. On systems like this you can use the
280 *CCACHE_EXTENSION* option to override the default. On HP-UX set this
281 environment variable to *i* if you use the ``aCC'' compiler.
283 *CCACHE_EXTRAFILES*::
285 If you set the environment variable *CCACHE_EXTRAFILES* to a list of paths
286 then ccache will include the contents of those files when calculating the
287 hash sum. The list separator is semicolon in Windows systems and colon on
292 If you set the environment variable *CCACHE_HARDLINK* then ccache will
293 attempt to use hard links from the cache directory when creating the
294 compiler output rather than using a file copy. Using hard links may be
295 slightly faster in some situations, but can confuse programs like ``make''
296 that rely on modification times. Another thing to keep in mind is that if
297 the resulting object file is modified in any way, this corrupts the cached
298 object file as well. Hard links are never made for compressed cache files.
299 This means that you should not set the *CCACHE_COMPRESS* variable if you
300 want to use hard links.
304 This tells ccache to hash the current working directory when calculating
305 the hash that is used to distinguish two compilations. This prevents a
306 problem with the storage of the current working directory in the debug info
307 of a object file, which can lead ccache to give a cached object file that
308 has the working directory in the debug info set incorrectly. This option is
309 off by default as the incorrect setting of this debug info rarely causes
310 problems. If you strike problems with GDB not using the correct directory
311 then enable this option.
315 If you set the *CCACHE_LOGFILE* environment variable then ccache will write
316 information on what it is doing to the specified file. This is useful for
317 tracking down problems.
321 The environment variable *CCACHE_NLEVELS* allows you to choose the number
322 of levels of hash in the cache directory. The default is 2. The minimum is
323 1 and the maximum is 8.
327 If you set the environment variable *CCACHE_NODIRECT* then ccache will not
332 If you set the environment variable *CCACHE_NOSTATS* then ccache will not
333 update the statistics files on each compilation.
337 You can optionally set *CCACHE_PATH* to a colon-separated path where ccache
338 will look for the real compilers. If you don't do this then ccache will
339 look for the first executable matching the compiler name in the normal
340 *PATH* that isn't a symbolic link to ccache itself.
344 This option adds a prefix to the command line that ccache runs when
345 invoking the compiler. Also see the section below on using ccache with
350 The *CCACHE_READONLY* environment variable tells ccache to attempt to use
351 existing cached object files, but not to try to add anything new to the
352 cache. If you are using this because your *CCACHE_DIR* is read-only, then
353 you may find that you also need to set *CCACHE_TEMPDIR* as otherwise ccache
354 will fail to create temporary files.
358 This forces ccache to not use any cached results, even if it finds them.
359 New results are still cached, but existing cache entries are ignored.
361 *CCACHE_SLOPPINESS*::
363 By default, ccache tries to give as few false cache hits as possible.
364 However, in certain situations it's possible that you know things that
365 ccache can't take for granted. The *CCACHE_SLOPPINESS* environment variable
366 makes it possible to tell ccache to relax some checks in order to increase
367 the hit rate. The value should be a comma-separated string with options.
368 Available options are:
372 Ignore *\_\_FILE__* being present in the source.
373 *include_file_mtime*::
374 Don't check the modification time of include files in the direct mode.
376 Ignore *\_\_DATE\__* and *\_\_TIME__* being present in the source code.
379 See the discussion under <<_troubleshooting,TROUBLESHOOTING>> for more
384 The *CCACHE_TEMPDIR* environment variable specifies where ccache will put
385 temporary files. The default is *$CCACHE_DIR/tmp*.
387 NOTE: In previous versions of ccache, *CCACHE_TEMPDIR* had to be on the same
388 filesystem as the *CCACHE_DIR* path, but this requirement has been
393 This sets the umask for ccache and all child processes (such as the
394 compiler). This is mostly useful when you wish to share your cache with
395 other users. Note that this also affects the file permissions set on the
396 object files created from your compilations.
400 If you set the environment variable *CCACHE_UNIFY* then ccache will use a
401 C/C++ unifier when hashing the preprocessor output if the *-g* option is
402 not used. The unifier is slower than a normal hash, so setting this
403 environment variable loses a little bit of speed, but it means that ccache
404 can take advantage of not recompiling when the changes to the source code
405 consist of reformatting only. Note that using *CCACHE_UNIFY* changes the
406 hash, so cached compilations with *CCACHE_UNIFY* set cannot be used when
407 *CCACHE_UNIFY* is not set and vice versa. The reason the unifier is off by
408 default is that it can give incorrect line number information in compiler
409 warning messages. Also note that enabling the unifier implies turning off
413 Cache size management
414 ---------------------
416 By default ccache has a one gigabyte limit on the total size of files in the
417 cache and no maximum number of files. You can set different limits using the
418 *-M*/*--max-size* and *-F*/*--max-files* options. Use *ccache -s/--show-stats*
419 to see the cache size and the currently configured limits (in addition to other
426 ccache can optionally compress all files it puts into the cache using the
427 compression library zlib. While this involves a negligible performance
428 slowdown, it significantly increases the number of files that fit in the cache.
429 You can turn on compression by setting the *CCACHE_COMPRESS* environment
436 The basic idea is to detect when you are compiling exactly the same code a
437 second time and reuse the previously produced output. The detection is done by
438 hashing different kinds of information that should be unique for the
439 compilation and then using the hash sum to identify the cached output. ccache
440 uses MD4, a very fast cryptographic hash algorithm, for the hashing. (MD4 is
441 nowadays too weak to be useful in cryptographic contexts, but it should be safe
442 enough to be used to identify recompilations.) On a cache hit, ccache is able
443 to supply all of the correct compiler outputs (including all warnings,
444 dependency file, etc) from the cache.
446 ccache has two ways of doing the detection:
448 * the *direct mode*, where ccache hashes the source code and include files
450 * the *preprocessor mode*, where ccache runs the preprocessor on the source
451 code and hashes the result
453 The direct mode is generally faster since running the preprocessor has some
457 Common hashed information
458 ~~~~~~~~~~~~~~~~~~~~~~~~~
460 For both modes, the following information is included in the hash:
462 * the extension used by the compiler for a file with preprocessor output
463 (normally *.i* for C code and *.ii* for C++ code)
464 * the compiler's size and modification time (or other compiler-specific
465 information specified by *CCACHE_COMPILERCHECK*)
466 * the name of the compiler
467 * the current directory (if *CCACHE_HASHDIR* is set)
468 * contents of files specified by *CCACHE_EXTRAFILES* (if any)
474 In the direct mode, the hash is formed of the common information and:
476 * the input source file
477 * the command line options
479 Based on the hash, a data structure called ``manifest'' is looked up in the
480 cache. The manifest contains:
482 * references to cached compilation results (object file, dependency file, etc)
483 that were produced by previous compilations that matched the hash
484 * paths to the include files that were read at the time the compilation results
485 were stored in the cache
486 * hash sums of the include files at the time the compilation results were
489 The current contents of the include files are then hashed and compared to the
490 information in the manifest. If there is a match, ccache knows the result of
491 the compilation. If there is no match, ccache falls back to running the
492 preprocessor. The output from the preprocessor is parsed to find the include
493 files that were read. The paths and hash sums of those include files are then
494 stored in the manifest along with information about the produced compilation
497 The direct mode will be disabled if any of the following holds:
499 * the environment variable *CCACHE_NODIRECT* is set
500 * a modification time of one of the include files is too new (needed to avoid a
502 * the unifier is enabled (the environment variable *CCACHE_UNIFY* is set)
503 * a compiler option not supported by the direct mode is used:
504 ** a *-Wp,_X_* compiler option other than *-Wp,-MD,_path_* and
507 * the string ``\_\_TIME__'' is present outside comments and string literals in
511 The preprocessor mode
512 ~~~~~~~~~~~~~~~~~~~~~
514 In the preprocessor mode, the hash is formed of the common information and:
516 * the preprocessor output from running the compiler with *-E*
517 * the command line options except options that affect include files (*-I*,
518 *-include*, *-D*, etc; the theory is that these options will change the
519 preprocessor output if they have any effect at all)
520 * any standard error output generated by the preprocessor
522 Based on the hash, the cached compilation result can be looked up directly in
526 Compiling in different directories
527 ----------------------------------
529 Some information included in the hash that identifies a unique compilation may
530 contain absolute paths:
532 * The preprocessed source code may contain absolute paths to include files if
533 the compiler option *-g* is used or if absolute paths are given to *-I* and
534 similar compiler options.
535 * Paths specified by compiler options (such as *-I*, *-MF*, etc) may be
537 * The source code file path may be absolute, and that path may substituted for
538 *\_\_FILE__* macros in the source code or included in warnings emitted to
539 standard error by the preprocessor.
541 This means that if you compile the same code in different locations, you can't
542 share compilation results between the different build directories since you get
543 cache misses because of the absolute build directory paths that are part of the
544 hash. To mitigate this problem, you can specify a ``base directory'' by setting
545 the *CCACHE_BASEDIR* variable to an absolute path to the directory. ccache will
546 then rewrite absolute paths that are under the base directory (i.e., paths that
547 have the base directory as a prefix) to relative paths when constructing the
548 hash. A typical path to use as the base directory is your home directory or
549 another directory that is a parent of your build directories. (Don't use +/+ as
550 the base directory since that will make ccache also rewrite paths to system
551 header files, which doesn't gain anything.)
553 The drawbacks of using *CCACHE_BASEDIR* are:
555 * If you specify an absolute path to the source code file, *\_\_FILE__* macros
556 will be expanded to a relative path instead.
557 * If you specify an absolute path to the source code file and compile with
558 *-g*, the source code path stored in the object file may point to the wrong
559 directory, which may prevent debuggers like GDB from finding the source code.
560 Sometimes, a work-around is to change the directory explicitly with the
561 ``cd'' command in GDB.
567 ccache has support for GCC's precompiled headers. However, you have to do some
568 things to make it work properly:
570 * You must set *CCACHE_SLOPPINESS* to *time_macros*. The reason is that ccache
571 can't tell whether *\_\_TIME\__* or *\_\_DATE__* is used when using a
576 ** use the *-include* compiler option to include the precompiled header
577 (i.e., don't use *#include* in the source code to include the header); or
578 ** add the *-fpch-preprocess* compiler option when compiling.
580 If you don't do this, either the non-precompiled version of the header file
581 will be used (if available) or ccache will fall back to running the real
582 compiler and increase the statistics counter ``preprocessor error'' (if the
583 non-precompiled header file is not available).
590 A group of developers can increase the cache hit rate by sharing a cache
591 directory. To share a cache without unpleasant side effects, the following
592 conditions should to be met:
594 * Use the same *CCACHE_DIR* environment variable setting.
595 * Unset the *CCACHE_HARDLINK* environment variable.
596 * Make sure everyone sets the *CCACHE_UMASK* environment variable to 002. This
597 ensures that cached files are accessible to everyone in the group.
598 * Make sure that all users have write permission in the entire cache directory
599 (and that you trust all users of the shared cache).
600 * Make sure that the setgid bit is set on all directories in the cache. This
601 tells the filesystem to inherit group ownership for new directories. The
602 command ``find $CCACHE_DIR -type d | xargs chmod g+s'' might be useful for
605 The reason to avoid the hard link mode is that the hard links cause unwanted
606 side effects, as all links to a cached file share the file's modification
607 timestamp. This results in false dependencies to be triggered by
608 timestamp-based build systems whenever another user links to an existing file.
609 Typically, users will see that their libraries and binaries are relinked
612 You may also want to make sure that the developers have *CCACHE_BASEDIR* set
613 appropriately, as discussed in the previous section.
616 Sharing a cache on NFS
617 ----------------------
619 It is possible to put the cache directory on an NFS filesystem (or similar
620 filesystems), but keep in mind that:
622 * Having the cache on NFS may slow down compilation. Make sure to do some
623 benchmarking to see if it's worth it.
624 * ccache hasn't been tested very thoroughly on NFS.
626 A tip is to set *CCACHE_TEMPDIR* to a directory on the local host to avoid NFS
627 traffic for temporary files.
630 Using ccache with other compiler wrappers
631 -----------------------------------------
633 The recommended way of combining ccache with another compiler wrapper (such as
634 ``distcc'') is by using the *CCACHE_PREFIX* option. You just need to set the
635 environment variable *CCACHE_PREFIX* to the name of the wrapper (e.g. *distcc*)
636 and ccache will prefix the command line with the specified command when running
639 Unless you set *CCACHE_COMPILERCHECK* to a suitable command (see the
640 description of that configuration option), it is not recommended to use the
641 form *ccache anotherwrapper compiler args* as the compilation command. It's
642 also not recommended to use the masquerading technique for the other compiler
643 wrapper. The reason is that by default, ccache will in both cases hash the
644 mtime and size of the other wrapper instead of the real compiler, which means
647 * Compiler upgrades will not be detected properly.
648 * The cached results will not be shared between compilations with and without
651 Another minor thing is that if *CCACHE_PREFIX* is not used, ccache will
652 needlessly invoke the other wrapper when running the preprocessor.
658 * ccache doesn't handle the GNU Assembler's *.incbin* directive correctly. This
659 directive can be embedded in the source code inside an *__asm__* statement in
660 order to include a file verbatim in the object file. If the included file is
661 modified, ccache doesn't pick up the change since the inclusion isn't done by
662 the preprocessor. A workaround of this problem is to set *CCACHE_EXTRAFILES*
663 to the path of the included file.
673 A general tip for getting information about what ccache is doing is to enable
674 debug logging by setting *CCACHE_LOGFILE*. The log contains executed commands,
675 important decisions that ccache makes, read and written files, etc. Another way
676 of keeping track of what is happening is to check the output of *ccache -s*.
682 ccache has been written to perform well out of the box, but sometimes you may
683 have to do some adjustments of how you use the compiler and ccache in order to
686 Since ccache works best when I/O is fast, put the cache directory on a fast
687 storage device if possible. Having lots of free memory so that files in the
688 cache directory stay in the disk cache is also preferrable.
690 A good way of monitoring how well ccache works is to run *ccache -s* before and
691 after your build and then compare the statistics counters. Here are some common
692 problems and what may be done to increase the hit rate:
694 * If ``cache hit (preprocessed)'' has been incremented instead of ``cache hit
695 (direct)'', ccache has fallen back to preprocessor mode, which is generally
696 slower. Some possible reasons are:
697 ** The source code has been modified in such a way that the preprocessor output
699 ** Compiler arguments that are hashed in the direct mode but not in the
700 preprocessor mode have changed (*-I*, *-include*, *-D*, etc) and they didn't
701 affect the preprocessor output.
702 ** The compiler option *-Xpreprocessor* or *-Wp,_X_* (except *-Wp,-MD,_path_*
703 and *Wp,-MMD,_path_*) is used.
704 ** This was the first compilation with a new value of *CCACHE_BASEDIR*.
705 ** A modification time of one of the include files is too new (created the same
706 second as the compilation is being done). This check is made to avoid a race
707 condition. To fix this, create the include file earlier in the build
708 process, if possible, or set *CCACHE_SLOPPINESS* to *include_file_mtime* if
709 you are willing to take the risk. (The race condition consists of these
710 events: the preprocessor is run; an include file is modified by someone; the
711 new include file is hashed by ccache; the real compiler is run on the
712 preprocessor's output, which contains data from the old header file; the
713 wrong object file is stored in the cache.)
714 ** The *\_\_TIME\__* preprocessor macro is (potentially) being used. ccache
715 turns off direct mode if ``\_\_TIME\__'' is present in the source code
716 outside comments and string literals. This is done as a safety measure since
717 the string indicates that a *\_\_TIME\__* macro _may_ affect the output. (To
718 be sure, ccache would have to run the preprocessor, but the sole point of
719 the direct mode is to avoid that.) If you know that *\_\_TIME\__* isn't used
720 in practise, or don't care if ccache produces objects where *\_\_TIME__* is
721 expanded to something in the past, you can set *CCACHE_SLOPPINESS* to
723 ** The *\_\_DATE\__* preprocessor macro is (potentially) being used and the
724 date has changed. This is similar to how *\_\_TIME\__* is handled. If
725 ``\_\_DATE\__'' is present in the source code outside comments and string
726 literals, ccache hashes the current date in order to be able to produce the
727 correct object file if the *\_\_DATE\__* macro affects the output. If you
728 know that *\_\_DATE\__* isn't used in practise, or don't care if ccache
729 produces objects where *\_\_DATE__* is expanded to something in the past,
730 you can set *CCACHE_SLOPPINESS* to *time_macros*.
731 ** The *\_\_FILE\__* preprocessor macro is (potentially) being used and the
732 file path has changed. If ``\_\_FILE\__'' is present in the source code
733 outside comments and string literals, ccache hashes the current input file
734 path in order to be able to produce the correct object file if the
735 *\_\_FILE\__* macro affects the output. If you know that *\_\_FILE\__* isn't
736 used in practise, or don't care if ccache produces objects where
737 *\_\_FILE__* is expanded to the wrong path, you can set *CCACHE_SLOPPINESS*
739 * If ``cache miss'' has been incremented even though the same code has been
740 compiled and cached before, ccache has either detected that something has
741 changed anyway or a cleanup has been performed (either explicitly or
742 implicitly when a cache limit has been reached). Some perhaps unobvious
743 things that may result in a cache miss are usage of *\_\_TIME\__* or
744 *\_\_DATE__* macros, or use of automatically generated code that contains a
745 timestamp, build counter or other volatile information.
746 * If ``multiple source files'' has been incremented, it's an indication that
747 the compiler has been invoked on several source code files at once. ccache
748 doesn't support that. Compile the source code files separately if possible.
749 * If ``unsupported compiler option'' has been incremented, enable debug logging
750 and check which option was rejected.
751 * If ``preprocessor error'' has been incremented, one possible reason is that
752 precompiled headers are being used. See <<_precompiled_headers,PRECOMPILED
753 HEADERS>> for how to remedy this.
754 * If ``can't use precompiled header'' has been incremented, see
755 <<_precompiled_headers,PRECOMPILED HEADERS>>.
758 Errors when compiling with ccache
759 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
761 If compilation doesn't work with ccache, but it works without it, one possible
762 reason is that the compiler can't compile preprocessed output correctly. A
763 workaround that may work is to set *CCACHE_CPP2*. This will make cache misses
764 slower, though, so it is better to find and fix the root cause.
770 It should be noted that ccache is susceptible to general storage problems. If a
771 bad object file sneaks into the cache for some reason, it will of course stay
772 bad. Some possible reasons for erroneous object files are bad hardware (disk
773 drive, disk controller, memory, etc), buggy drivers or file systems, a bad
774 *CCACHE_PREFIX* command or compiler wrapper. If this happens, you can either
775 find out which object file is broken by reading the debug log and then delete
776 the bad object file from the cache, or you can simply clear the whole cache
777 with *ccache -C* if you don't mind losing other cached results.
779 There are no reported issues about ccache producing broken object files
780 reproducibly. That doesn't mean it can't happen, so if you find a repeatable
781 case, please report it.
787 Credits, mailing list information, bug reporting instructions, source code,
788 etc, can be found on ccache's web site: <http://ccache.samba.org>.
794 ccache was originally written by Andrew Tridgell and is currently developed and
795 maintained by Joel Rosdahl. See AUTHORS.txt or AUTHORS.html and
796 <http://ccache.samba.org/credits.html> for a list of contributors.
projects / platform / upstream / ccache.git / blob