1CCACHE(1)                        ccache Manual                       CCACHE(1)
2
3
4

NAME

6       ccache - a fast C/C++ compiler cache
7

SYNOPSIS

9       ccache [options]
10       ccache compiler [compiler options]
11       compiler [compiler options]                   (via symbolic link)
12

DESCRIPTION

14       ccache is a compiler cache. It speeds up recompilation by caching the
15       result of previous compilations and detecting when the same compilation
16       is being done again. Supported languages are C, C++, Objective-C and
17       Objective-C++.
18
19       ccache has been carefully written to always produce exactly the same
20       compiler output that you would get without the cache. The only way you
21       should be able to tell that you are using ccache is the speed.
22       Currently known exceptions to this goal are listed under CAVEATS. If
23       you ever discover an undocumented case where ccache changes the output
24       of your compiler, please let us know.
25
26   Features
27       ·   Keeps statistics on hits/misses.
28
29       ·   Automatic cache size management.
30
31       ·   Can cache compilations that generate warnings.
32
33       ·   Easy installation.
34
35       ·   Low overhead.
36
37       ·   Optionally compresses files in the cache to reduce disk space.
38
39   Limitations
40       ·   Only knows how to cache the compilation of a single
41           C/C++/Objective-C/Objective-C++ file. Other types of compilations
42           (multi-file compilation, linking, etc) will silently fall back to
43           running the real compiler.
44
45       ·   Only works with GCC and compilers that behave similar enough.
46
47       ·   Some compiler flags are not supported. If such a flag is detected,
48           ccache will silently fall back to running the real compiler.
49

RUN MODES

51       There are two ways to use ccache. You can either prefix your
52       compilation commands with ccache or you can let ccache masquerade as
53       the compiler by creating a symbolic link (named as the compiler) to
54       ccache. The first method is most convenient if you just want to try out
55       ccache or wish to use it for some specific projects. The second method
56       is most useful for when you wish to use ccache for all your
57       compilations.
58
59       To use the first method, just make sure that ccache is in your PATH.
60
61       To use the symlinks method, do something like this:
62
63           cp ccache /usr/local/bin/
64           ln -s ccache /usr/local/bin/gcc
65           ln -s ccache /usr/local/bin/g++
66           ln -s ccache /usr/local/bin/cc
67           ln -s ccache /usr/local/bin/c++
68
69       And so forth. This will work as long as the directory with symlinks
70       comes before the path to the compiler (which is usually in /usr/bin).
71       After installing you may wish to run “which gcc” to make sure that the
72       correct link is being used.
73
74           Warning
75           The technique of letting ccache masquerade as the compiler works
76           well, but currently doesn’t interact well with other tools that do
77           the same thing. See USING CCACHE WITH OTHER COMPILER WRAPPERS.
78
79           Warning
80           Do not use a hard link, use a symbolic link. A hard link will cause
81           “interesting” problems.
82

OPTIONS

84       These options only apply when you invoke ccache as “ccache”. When
85       invoked as a compiler (via a symlink as described in the previous
86       section), the normal compiler options apply and you should refer to the
87       compiler’s documentation.
88
89       -c, --cleanup
90           Clean up the cache by removing old cached files until the specified
91           file number and cache size limits are not exceeded. This also
92           recalculates the cache file count and size totals. Normally, there
93           is no need to initiate cleanup manually as ccache keeps the cache
94           below the specified limits at runtime and keeps statistics up to
95           date on each compilation. Forcing a cleanup is mostly useful if you
96           manually modify the cache contents or believe that the cache size
97           statistics may be inaccurate.
98
99       -C, --clear
100           Clear the entire cache, removing all cached files, but keeping the
101           configuration file.
102
103       -F, --max-files=N
104           Set the maximum number of files allowed in the cache. Use 0 for no
105           limit. The value is stored in a configuration file in the cache
106           directory and applies to all future compilations.
107
108       -h, --help
109           Print an options summary page.
110
111       -M, --max-size=SIZE
112           Set the maximum size of the files stored in the cache.  SIZE should
113           be a number followed by an optional suffix: k, M, G, T (decimal),
114           Ki, Mi, Gi or Ti (binary). The default suffix is G. Use 0 for no
115           limit. The value is stored in a configuration file in the cache
116           directory and applies to all future compilations.
117
118       -o, --set-config=KEY=VALUE
119           Set configuration KEY to VALUE. See CONFIGURATION for more
120           information.
121
122       -p, --print-config
123           Print current configuration options and from where they originate
124           (environment variable, configuration file or compile-time default).
125
126       -s, --show-stats
127           Print the current statistics summary for the cache.
128
129       -V, --version
130           Print version and copyright information.
131
132       -z, --zero-stats
133           Zero the cache statistics (but not the configuration options).
134

EXTRA OPTIONS

136       When run as a compiler, ccache usually just takes the same command line
137       options as the compiler you are using. The only exception to this is
138       the option --ccache-skip. That option can be used to tell ccache to
139       avoid interpreting the next option in any way and to pass it along to
140       the compiler as-is.
141
142           Note
143           --ccache-skip currently only tells ccache not to interpret the next
144           option as a special compiler option — the option will still be
145           included in the direct mode hash.
146
147       The reason this can be important is that ccache does need to parse the
148       command line and determine what is an input filename and what is a
149       compiler option, as it needs the input filename to determine the name
150       of the resulting object file (among other things). The heuristic ccache
151       uses when parsing the command line is that any argument that exists as
152       a file is treated as an input file name. By using --ccache-skip you can
153       force an option to not be treated as an input file name and instead be
154       passed along to the compiler as a command line option.
155
156       Another case where --ccache-skip can be useful is if ccache interprets
157       an option specially but shouldn’t, since the option has another meaning
158       for your compiler than what ccache thinks.
159

CONFIGURATION

161       ccache’s default behavior can be overridden by configuration file
162       settings, which in turn can be overridden by environment variables with
163       names starting with CCACHE_. ccache normally reads configuration from
164       two files: first a system-level configuration file and secondly a
165       cache-specific configuration file. The priority of configuration
166       settings is as follows (where 1 is highest):
167
168        1. Environment variables.
169
170        2. The cache-specific configuration file <ccachedir>/ccache.conf
171           (typically $HOME/.ccache/ccache.conf).
172
173        3. The system-wide configuration file <sysconfdir>/ccache.conf
174           (typically /etc/ccache.conf or /usr/local/etc/ccache.conf).
175
176        4. Compile-time defaults.
177
178       As a special case, if the environment variable CCACHE_CONFIGPATH is
179       set, ccache reads configuration from the specified path instead of the
180       default paths.
181
182   Configuration file syntax
183       Configuration files are in a simple “key = value” format, one setting
184       per line. Lines starting with a hash sign are comments. Blank lines are
185       ignored, as is whitespace surrounding keys and values. Example:
186
187           # Set maximum cache size to 10 GB:
188           max_size = 10G
189
190   Boolean values
191       Some settings are boolean values (i.e. truth values). In a
192       configuration file, such values must be set to the string true or
193       false. For the corresponding environment variables, the semantics are a
194       bit different: a set environment variable means “true” (even if set to
195       the empty string), the following case-insensitive negative values are
196       considered an error (rather than surprising the user): 0, false,
197       disable and no, and an unset environment variable means “false”. Each
198       boolean environment variable also has a negated form starting with
199       CCACHE_NO. For example, CCACHE_COMPRESS can be set to force compression
200       and CCACHE_NOCOMPRESS can be set to force no compression.
201
202   Configuration settings
203       Below is a list of available configuration settings. The corresponding
204       environment variable name is indicated in parentheses after each
205       configuration setting key.
206
207       base_dir (CCACHE_BASEDIR)
208           This setting should be an absolute path to a directory. ccache then
209           rewrites absolute paths into relative paths before computing the
210           hash that identifies the compilation, but only for paths under the
211           specified directory. If set to the empty string (which is the
212           default), no rewriting is done. A typical path to use as the base
213           directory is your home directory or another directory that is a
214           parent of your build directories. Don’t use / as the base directory
215           since that will make ccache also rewrite paths to system header
216           files, which doesn’t gain anything.
217
218           See also the discussion under COMPILING IN DIFFERENT DIRECTORIES.
219
220       cache_dir (CCACHE_DIR)
221           This setting specifies where ccache will keep its cached compiler
222           outputs. It will only take effect if set in the system-wide
223           configuration file or as an environment variable. The default is
224           $HOME/.ccache.
225
226       cache_dir_levels (CCACHE_NLEVELS)
227           This setting allows you to choose the number of directory levels in
228           the cache directory. The default is 2. The minimum is 1 and the
229           maximum is 8.
230
231       compiler (CCACHE_CC)
232           This setting can be used to force the name of the compiler to use.
233           If set to the empty string (which is the default), ccache works it
234           out from the command line.
235
236       compiler_check (CCACHE_COMPILERCHECK)
237           By default, ccache includes the modification time (“mtime”) and
238           size of the compiler in the hash to ensure that results retrieved
239           from the cache are accurate. This setting can be used to select
240           another strategy. Possible values are:
241
242           content
243               Hash the content of the compiler binary. This makes ccache very
244               slightly slower compared to the mtime setting, but makes it
245               cope better with compiler upgrades during a build bootstrapping
246               process.
247
248           mtime
249               Hash the compiler’s mtime and size, which is fast. This is the
250               default.
251
252           none
253               Don’t hash anything. This may be good for situations where you
254               can safely use the cached results even though the compiler’s
255               mtime or size has changed (e.g. if the compiler is built as
256               part of your build system and the compiler’s source has not
257               changed, or if the compiler only has changes that don’t affect
258               code generation). You should only use the none setting if you
259               know what you are doing.
260
261           string:value
262               Use value as the string to calculate hash from. This can be the
263               compiler revision number you retrieved earlier and set here via
264               environment variable.
265
266           a command string
267               Hash the standard output and standard error output of the
268               specified command. The string will be split on whitespace to
269               find out the command and arguments to run. No other
270               interpretation of the command string will be done, except that
271               the special word %compiler% will be replaced with the path to
272               the compiler. Several commands can be specified with semicolon
273               as separator. Examples:
274
275                   %compiler% -v
276
277                   %compiler% -dumpmachine; %compiler% -dumpversion
278
279               You should make sure that the specified command is as fast as
280               possible since it will be run once for each ccache invocation.
281
282               Identifying the compiler using a command is useful if you want
283               to avoid cache misses when the compiler has been rebuilt but
284               not changed.
285
286               Another case is when the compiler (as seen by ccache) actually
287               isn’t the real compiler but another compiler wrapper — in that
288               case, the default mtime method will hash the mtime and size of
289               the other compiler wrapper, which means that ccache won’t be
290               able to detect a compiler upgrade. Using a suitable command to
291               identify the compiler is thus safer, but it’s also slower, so
292               you should consider continue using the mtime method in
293               combination with the prefix_command setting if possible. See
294               USING CCACHE WITH OTHER COMPILER WRAPPERS.
295
296       compression (CCACHE_COMPRESS or CCACHE_NOCOMPRESS, see Boolean values
297       above)
298           If true, ccache will compress object files and other compiler
299           output it puts in the cache. However, this setting has no effect on
300           how files are retrieved from the cache; compressed and uncompressed
301           results will still be usable regardless of this setting. The
302           default is false.
303
304       compression_level (CCACHE_COMPRESSLEVEL)
305           This setting determines the level at which ccache will compress
306           object files. It only has effect if compression is enabled. The
307           value defaults to 6, and must be no lower than 1 (fastest, worst
308           compression) and no higher than 9 (slowest, best compression).
309
310       cpp_extension (CCACHE_EXTENSION)
311           This setting can be used to force a certain extension for the
312           intermediate preprocessed file. The default is to automatically
313           determine the extension to use for intermediate preprocessor files
314           based on the type of file being compiled, but that sometimes
315           doesn’t work. For example, when using the “aCC” compiler on HP-UX,
316           set the cpp extension to i.
317
318       direct_mode (CCACHE_DIRECT or CCACHE_NODIRECT, see Boolean values
319       above)
320           If true, the direct mode will be used. The default is true. See THE
321           DIRECT MODE.
322
323       disable (CCACHE_DISABLE or CCACHE_NODISABLE, see Boolean values above)
324           When true, ccache will just call the real compiler, bypassing the
325           cache completely. The default is false.
326
327       extra_files_to_hash (CCACHE_EXTRAFILES)
328           This setting is a list of paths to files that ccache will include
329           in the the hash sum that identifies the build. The list separator
330           is semicolon on Windows systems and colon on other systems.
331
332       hard_link (CCACHE_HARDLINK or CCACHE_NOHARDLINK, see Boolean values
333       above)
334           If true, ccache will attempt to use hard links from the cache
335           directory when creating the compiler output rather than using a
336           file copy. Hard links are never made for compressed cache files.
337           This means that you should not enable compression if you want to
338           use hard links. The default is false.
339
340               Warning
341               Do not enable this option unless you are aware of the
342               consequences. Using hard links may be slightly faster in some
343               situations, but there are several pitfalls since the resulting
344               object file will share i-node with the cached object file:
345
346            1. If the resulting object file is modified in any way, the cached
347               object file will be modified as well. For instance, if you run
348               strip object.o or echo >object.o, you will corrupt the cache.
349
350            2. Programs that rely on modification times (like “make”) can be
351               confused since ccache updates the cached files' modification
352               times as part of the automatic cache size management. This will
353               affect object files in the build tree as well, which can
354               retrigger the linking step even though nothing really has
355               changed.
356
357       hash_dir (CCACHE_HASHDIR or CCACHE_NOHASHDIR, see Boolean values above)
358           If true (which is the default), ccache will include the current
359           working directory (CWD) in the hash that is used to distinguish two
360           compilations when generating debug info (compiler option -g with
361           variations). Exception: The CWD will not be included in the hash if
362           base_dir is set (and matches the CWD) and the compiler option
363           -fdebug-prefix-map is used. See also the discussion under COMPILING
364           IN DIFFERENT DIRECTORIES.
365
366           The reason for including the CWD in the hash by default is to
367           prevent a problem with the storage of the current working directory
368           in the debug info of an object file, which can lead ccache to
369           return a cached object file that has the working directory in the
370           debug info set incorrectly.
371
372           You can disable this setting to get cache hits when compiling the
373           same source code in different directories if you don’t mind that
374           CWD in the debug info might be incorrect.
375
376       ignore_headers_in_manifest (CCACHE_IGNOREHEADERS)
377           This setting is a list of paths to files (or directories with
378           headers) that ccache will not include in the manifest list that
379           makes up the direct mode. Note that this can cause stale cache hits
380           if those headers do indeed change. The list separator is semicolon
381           on Windows systems and colon on other systems.
382
383       keep_comments_cpp (CCACHE_COMMENTS or CCACHE_NOCOMMENTS, see Boolean
384       values above)
385           If true, ccache will not discard the comments before hashing
386           preprocessor output. This can be used to check documentation with
387           -Wdocumentation.
388
389       limit_multiple (CCACHE_LIMIT_MULTIPLE)
390           Sets the limit when cleaning up. Files are deleted (in LRU order)
391           until the levels are below the limit. The default is 0.8 (= 80%).
392           See AUTOMATIC CLEANUP for more information.
393
394       log_file (CCACHE_LOGFILE)
395           If set to a file path, ccache will write information on what it is
396           doing to the specified file. This is useful for tracking down
397           problems.
398
399       max_files (CCACHE_MAXFILES)
400           This option specifies the maximum number of files to keep in the
401           cache. Use 0 for no limit (which is the default). See also CACHE
402           SIZE MANAGEMENT.
403
404       max_size (CCACHE_MAXSIZE)
405           This option specifies the maximum size of the cache. Use 0 for no
406           limit. The default value is 5G. Available suffixes: k, M, G, T
407           (decimal) and Ki, Mi, Gi, Ti (binary). The default suffix is G. See
408           also CACHE SIZE MANAGEMENT.
409
410       path (CCACHE_PATH)
411           If set, ccache will search directories in this list when looking
412           for the real compiler. The list separator is semicolon on Windows
413           systems and colon on other systems. If not set, ccache will look
414           for the first executable matching the compiler name in the normal
415           PATH that isn’t a symbolic link to ccache itself.
416
417       prefix_command (CCACHE_PREFIX)
418           This option adds a list of prefixes (separated by space) to the
419           command line that ccache uses when invoking the compiler. See also
420           USING CCACHE WITH OTHER COMPILER WRAPPERS.
421
422       prefix_command_cpp (CCACHE_PREFIX_CPP)
423           This option adds a list of prefixes (separated by space) to the
424           command line that ccache uses when invoking the preprocessor.
425
426       read_only (CCACHE_READONLY or CCACHE_NOREADONLY, see Boolean values
427       above)
428           If true, ccache will attempt to use existing cached object files,
429           but it will not to try to add anything new to the cache. If you are
430           using this because your ccache directory is read-only, then you
431           need to set temporary_dir as otherwise ccache will fail to create
432           temporary files.
433
434       read_only_direct (CCACHE_READONLY_DIRECT or CCACHE_NOREADONLY_DIRECT,
435       see Boolean values above)
436           Just like read_only except that ccache will only try to retrieve
437           results from the cache using the direct mode, not the preprocessor
438           mode. See documentation for read_only regarding using a read-only
439           ccache directory.
440
441       recache (CCACHE_RECACHE or CCACHE_NORECACHE, see Boolean values above)
442           If true, ccache will not use any previously stored result. New
443           results will still be cached, possibly overwriting any pre-existing
444           results.
445
446       run_second_cpp (CCACHE_CPP2 or CCACHE_NOCPP2, see Boolean values above)
447           If true, ccache will first run the preprocessor to preprocess the
448           source code (see THE PREPROCESSOR MODE) and then on a cache miss
449           run the compiler on the source code to get hold of the object file.
450           This is the default.
451
452           If false, ccache will first run preprocessor to preprocess the
453           source code and then on a cache miss run the compiler on the
454           preprocessed source code instead of the original source code. This
455           makes cache misses slightly faster since the source code only has
456           to be preprocessed once. The downside is that some compilers won’t
457           produce the same result (for instance diagnostics warnings) when
458           compiling preprocessed source code.
459
460           A solution to the above mentioned downside is to set run_second_cpp
461           to false and pass -fdirectives-only (for GCC) or -frewrite-includes
462           (for Clang) to the compiler. This will cause the compiler to leave
463           the macros and other preprocessor information, and only process the
464           #include directives. When run in this way, the preprocessor
465           arguments will be passed to the compiler since it still has to do
466           some preprocessing (like macros).
467
468       sloppiness (CCACHE_SLOPPINESS)
469           By default, ccache tries to give as few false cache hits as
470           possible. However, in certain situations it’s possible that you
471           know things that ccache can’t take for granted. This setting makes
472           it possible to tell ccache to relax some checks in order to
473           increase the hit rate. The value should be a comma-separated string
474           with options. Available options are:
475
476           file_macro
477               Ignore __FILE__ being present in the source.
478
479           file_stat_matches
480               ccache normally examines a file’s contents to determine whether
481               it matches the cached version. With this option set, ccache
482               will consider a file as matching its cached version if the
483               mtimes and ctimes match.
484
485           include_file_ctime
486               By default, ccache also will not cache a file if it includes a
487               header whose ctime is too new. This option disables that check.
488
489           include_file_mtime
490               By default, ccache will not cache a file if it includes a
491               header whose mtime is too new. This option disables that check.
492
493           no_system_headers
494               By default, ccache will also include all system headers in the
495               manifest. With this option set, ccache will only include system
496               headers in the hash but not add the system header files to the
497               list of include files.
498
499           pch_defines
500               Be sloppy about #defines when precompiling a header file. See
501               PRECOMPILED HEADERS for more information.
502
503           time_macros
504               Ignore __DATE__ and __TIME__ being present in the source code.
505
506           See the discussion under TROUBLESHOOTING for more information.
507
508       stats (CCACHE_STATS or CCACHE_NOSTATS, see Boolean values above)
509           If true, ccache will update the statistics counters on each
510           compilation. The default is true.
511
512       temporary_dir (CCACHE_TEMPDIR)
513           This setting specifies where ccache will put temporary files. The
514           default is <cache_dir>/tmp.
515
516               Note
517               In previous versions of ccache, CCACHE_TEMPDIR had to be on the
518               same filesystem as the CCACHE_DIR path, but this requirement
519               has been relaxed.)
520
521       umask (CCACHE_UMASK)
522           This setting specifies the umask for ccache and all child processes
523           (such as the compiler). This is mostly useful when you wish to
524           share your cache with other users. Note that this also affects the
525           file permissions set on the object files created from your
526           compilations.
527
528       unify (CCACHE_UNIFY or CCACHE_NOUNIFY, see Boolean values above)
529           If true, ccache will use a C/C++ unifier when hashing the
530           preprocessor output if the -g option is not used. The unifier is
531           slower than a normal hash, so setting this environment variable
532           loses a little bit of speed, but it means that ccache can take
533           advantage of not recompiling when the changes to the source code
534           consist of reformatting only. Note that enabling the unifier
535           changes the hash, so cached compilations produced when the unifier
536           is enabled cannot be reused when the unifier is disabled, and vice
537           versa. Enabling the unifier may result in incorrect line number
538           information in compiler warning messages and expansions of the
539           __LINE__ macro.
540

CACHE SIZE MANAGEMENT

542       By default, ccache has a 5 GB limit on the total size of files in the
543       cache and no limit on the number of files. You can set different limits
544       using the -M/--max-size and -F/--max-files options. Use ccache
545       -s/--show-stats to see the cache size and the currently configured
546       limits (in addition to other various statistics).
547
548       Cleanup can be triggered in two different ways: automatic and manual.
549
550   Automatic cleanup
551       ccache maintains counters for various statistics about the cache,
552       including the size and number of all cached files. In order to improve
553       performance and reduce issues with concurrent ccache invocations, there
554       is one statistics file for each of the sixteen subdirectories in the
555       cache.
556
557       After a new compilation result has been written to the cache, ccache
558       will update the size and file number statistics for the subdirectory
559       (one of sixteen) to which the result was written. Then, if the size
560       counter for said subdirectory is greater than max_size / 16 or the file
561       number counter is greater than max_files / 16, automatic cleanup is
562       triggered.
563
564       When automatic cleanup is triggered for a subdirectory in the cache,
565       ccache will:
566
567        1. Count all files in the subdirectory and compute their aggregated
568           size.
569
570        2. Remove files in LRU (least recently used) order until the size is
571           at most limit_multiple * max_size / 16 and the number of files is
572           at most limit_multiple * max_files / 16, where limit_multiple,
573           max_size and max_files are configuration settings.
574
575        3. Set the size and file number counters to match the files that were
576           kept.
577
578       The reason for removing more files than just those needed to not exceed
579       the max limits is that a cleanup is a fairly slow operation, so it
580       would not be a good idea to trigger it often, like after each cache
581       miss.
582
583   Manual cleanup
584       You can run ccache -c/--cleanup to force cleanup of the whole cache,
585       i.e. all of the sixteen subdirectories. This will recalculate the
586       statistics counters and make sure that the max_size and max_files
587       settings are not exceeded. Note that limit_multiple is not taken into
588       account for manual cleanup.
589

CACHE COMPRESSION

591       ccache can optionally compress all files it puts into the cache using
592       the compression library zlib. While this may involve a tiny performance
593       slowdown, it increases the number of files that fit in the cache. You
594       can turn on compression with the compression configuration setting and
595       you can also tweak the compression level with compression_level.
596

CACHE STATISTICS

598       ccache -s/--show-stats can show the following statistics:
599
600       ┌───────────────────────────┬────────────────────────────┐
601Name                       Description                
602       ├───────────────────────────┼────────────────────────────┤
603       │                           │                            │
604       │autoconf compile/link      │ Uncachable compilation or  │
605       │                           │ linking by an autoconf     │
606       │                           │ test.                      │
607       ├───────────────────────────┼────────────────────────────┤
608       │                           │                            │
609       │bad compiler arguments     │ Malformed compiler         │
610       │                           │ argument, e.g. missing a   │
611       │                           │ value for an option that   │
612       │                           │ requires an argument or    │
613       │                           │ failure to read a file     │
614       │                           │ specified by an option     │
615       │                           │ argument.                  │
616       ├───────────────────────────┼────────────────────────────┤
617       │                           │                            │
618       │cache file missing         │ A file was unexpectedly    │
619       │                           │ missing from the cache.    │
620       │                           │ This only happens in rare  │
621       │                           │ situations, e.g. if one    │
622       │                           │ ccache instance is about   │
623       │                           │ to get a file from the     │
624       │                           │ cache while another        │
625       │                           │ instance removed the file  │
626       │                           │ as part of cache cleanup.  │
627       ├───────────────────────────┼────────────────────────────┤
628       │                           │                            │
629       │cache hit (direct)         │ A result was successfully  │
630       │                           │ found using the direct     │
631       │                           │ mode.                      │
632       ├───────────────────────────┼────────────────────────────┤
633       │                           │                            │
634       │cache hit (preprocessed)   │ A result was successfully  │
635       │                           │ found using the            │
636       │                           │ preprocessor mode.         │
637       ├───────────────────────────┼────────────────────────────┤
638       │                           │                            │
639       │cache miss                 │ No result was found.       │
640       ├───────────────────────────┼────────────────────────────┤
641       │                           │                            │
642       │cache size                 │ Current size of the cache. │
643       ├───────────────────────────┼────────────────────────────┤
644       │                           │                            │
645       │called for link            │ The compiler was called    │
646       │                           │ for linking, not           │
647       │                           │ compiling.                 │
648       ├───────────────────────────┼────────────────────────────┤
649       │                           │                            │
650       │called for preprocessing   │ The compiler was called    │
651       │                           │ for preprocessing, not     │
652       │                           │ compiling.                 │
653       ├───────────────────────────┼────────────────────────────┤
654       │                           │                            │
655       │can’t use precompiled      │ Preconditions for using    │
656       │header                     │ precompiled headers were   │
657       │                           │ not fulfilled.             │
658       ├───────────────────────────┼────────────────────────────┤
659       │                           │                            │
660       │ccache internal error      │ Unexpected failure, e.g.   │
661       │                           │ due to problems            │
662       │                           │ reading/writing the cache. │
663       ├───────────────────────────┼────────────────────────────┤
664       │                           │                            │
665       │cleanups performed         │ Number of cleanups         │
666       │                           │ performed, either          │
667       │                           │ implicitly due to the      │
668       │                           │ cache size limit being     │
669       │                           │ reached or due to explicit │
670       │                           │ ccache -c/--cleanup calls. │
671       ├───────────────────────────┼────────────────────────────┤
672       │                           │                            │
673       │compile failed             │ The compilation failed. No │
674       │                           │ result stored in the       │
675       │                           │ cache.                     │
676       ├───────────────────────────┼────────────────────────────┤
677       │                           │                            │
678       │compiler check failed      │ A compiler check program   │
679       │                           │ specified by               │
680       │                           │ compiler_check             
681       │                           │ (CCACHE_COMPILERCHECK)     │
682       │                           │ failed.                    │
683       ├───────────────────────────┼────────────────────────────┤
684       │                           │                            │
685       │compiler produced empty    │ The compiler’s output file │
686       │output                     │ (typically an object file) │
687       │                           │ was empty after            │
688       │                           │ compilation.               │
689       ├───────────────────────────┼────────────────────────────┤
690       │                           │                            │
691       │compiler produced no       │ The compiler’s output file │
692       │output                     │ (typically an object file) │
693       │                           │ was missing after          │
694       │                           │ compilation.               │
695       ├───────────────────────────┼────────────────────────────┤
696       │                           │                            │
697       │compiler produced stdout   │ The compiler wrote data to │
698       │                           │ standard output. This is   │
699       │                           │ something that compilers   │
700       │                           │ normally never do, so      │
701       │                           │ ccache is not designed to  │
702       │                           │ store such output in the   │
703       │                           │ cache.                     │
704       ├───────────────────────────┼────────────────────────────┤
705       │                           │                            │
706       │couldn’t find the compiler │ The compiler to execute    │
707       │                           │ could not be found.        │
708       ├───────────────────────────┼────────────────────────────┤
709       │                           │                            │
710       │error hashing extra file   │ Failure reading a file     │
711       │                           │ specified by               │
712       │                           │ extra_files_to_hash        
713       │                           │ (CCACHE_EXTRAFILES).       │
714       ├───────────────────────────┼────────────────────────────┤
715       │                           │                            │
716       │files in cache             │ Current number of files in │
717       │                           │ the cache.                 │
718       ├───────────────────────────┼────────────────────────────┤
719       │                           │                            │
720       │multiple source files      │ The compiler was called to │
721       │                           │ compile multiple source    │
722       │                           │ files in one go. This is   │
723       │                           │ not supported by ccache.   │
724       ├───────────────────────────┼────────────────────────────┤
725       │                           │                            │
726       │no input file              │ No input file was          │
727       │                           │ specified to the compiler. │
728       ├───────────────────────────┼────────────────────────────┤
729       │                           │                            │
730       │output to a non-regular    │ The output path specified  │
731       │file                       │ with -o is not a file      │
732       │                           │ (e.g. a directory or a     │
733       │                           │ device node).              │
734       ├───────────────────────────┼────────────────────────────┤
735       │                           │                            │
736       │output to stdout           │ The compiler was           │
737       │                           │ instructed to write its    │
738       │                           │ output to standard output  │
739       │                           │ using -o -. This is not    │
740       │                           │ supported by ccache.       │
741       ├───────────────────────────┼────────────────────────────┤
742       │                           │                            │
743       │preprocessor error         │ Preprocessing the source   │
744       │                           │ code using the compiler’s  │
745       │                           │ -E option failed.          │
746       ├───────────────────────────┼────────────────────────────┤
747       │                           │                            │
748       │unsupported code directive │ Code like the assembler    │
749       │                           │ .incbin directive was      │
750       │                           │ found. This is not         │
751       │                           │ supported by ccache.       │
752       ├───────────────────────────┼────────────────────────────┤
753       │                           │                            │
754       │unsupported compiler       │ A compiler option not      │
755       │option                     │ supported by ccache was    │
756       │                           │ found.                     │
757       ├───────────────────────────┼────────────────────────────┤
758       │                           │                            │
759       │unsupported source         │ A source language e.g.     │
760       │language                   │ specified with -x was      │
761       │                           │ unsupported by ccache.     │
762       └───────────────────────────┴────────────────────────────┘
763

HOW CCACHE WORKS

765       The basic idea is to detect when you are compiling exactly the same
766       code a second time and reuse the previously produced output. The
767       detection is done by hashing different kinds of information that should
768       be unique for the compilation and then using the hash sum to identify
769       the cached output. ccache uses MD4, a very fast cryptographic hash
770       algorithm, for the hashing. (MD4 is nowadays too weak to be useful in
771       cryptographic contexts, but it should be safe enough to be used to
772       identify recompilations.) On a cache hit, ccache is able to supply all
773       of the correct compiler outputs (including all warnings, dependency
774       file, etc) from the cache.
775
776       ccache has two ways of doing the detection:
777
778       ·   the direct mode, where ccache hashes the source code and include
779           files directly
780
781       ·   the preprocessor mode, where ccache runs the preprocessor on the
782           source code and hashes the result
783
784       The direct mode is generally faster since running the preprocessor has
785       some overhead.
786
787   Common hashed information
788       For both modes, the following information is included in the hash:
789
790       ·   the extension used by the compiler for a file with preprocessor
791           output (normally .i for C code and .ii for C++ code)
792
793       ·   the compiler’s size and modification time (or other
794           compiler-specific information specified by the compiler_check
795           setting)
796
797       ·   the name of the compiler
798
799       ·   the current directory (if the hash_dir setting is enabled)
800
801       ·   contents of files specified by the extra_files_to_hash setting (if
802           any)
803
804   The direct mode
805       In the direct mode, the hash is formed of the common information and:
806
807       ·   the input source file
808
809       ·   the command line options
810
811       Based on the hash, a data structure called “manifest” is looked up in
812       the cache. The manifest contains:
813
814       ·   references to cached compilation results (object file, dependency
815           file, etc) that were produced by previous compilations that matched
816           the hash
817
818       ·   paths to the include files that were read at the time the
819           compilation results were stored in the cache
820
821       ·   hash sums of the include files at the time the compilation results
822           were stored in the cache
823
824       The current contents of the include files are then hashed and compared
825       to the information in the manifest. If there is a match, ccache knows
826       the result of the compilation. If there is no match, ccache falls back
827       to running the preprocessor. The output from the preprocessor is parsed
828       to find the include files that were read. The paths and hash sums of
829       those include files are then stored in the manifest along with
830       information about the produced compilation result.
831
832       There is a catch with the direct mode: header files that were used by
833       the compiler are recorded, but header files that were not used, but
834       would have been used if they existed, are not. So, when ccache checks
835       if a result can be taken from the cache, it currently can’t check if
836       the existence of a new header file should invalidate the result. In
837       practice, the direct mode is safe to use in the absolute majority of
838       cases.
839
840       The direct mode will be disabled if any of the following holds:
841
842       ·   the configuration setting direct_mode is false
843
844       ·   a modification time of one of the include files is too new (needed
845           to avoid a race condition)
846
847       ·   a compiler option not supported by the direct mode is used:
848
849           ·   a -Wp,X compiler option other than -Wp,-MD,path, -Wp,-MMD,path
850               and -Wp,-D_define_
851
852           ·   -Xpreprocessor
853
854       ·   the string __TIME__ is present in the source code
855
856   The preprocessor mode
857       In the preprocessor mode, the hash is formed of the common information
858       and:
859
860       ·   the preprocessor output from running the compiler with -E
861
862       ·   the command line options except options that affect include files
863           (-I, -include, -D, etc; the theory is that these options will
864           change the preprocessor output if they have any effect at all)
865
866       ·   any standard error output generated by the preprocessor
867
868       Based on the hash, the cached compilation result can be looked up
869       directly in the cache.
870

COMPILING IN DIFFERENT DIRECTORIES

872       Some information included in the hash that identifies a unique
873       compilation can contain absolute paths:
874
875       ·   The preprocessed source code may contain absolute paths to include
876           files if the compiler option -g is used or if absolute paths are
877           given to -I and similar compiler options.
878
879       ·   Paths specified by compiler options (such as -I, -MF, etc) on the
880           command line may be absolute.
881
882       ·   The source code file path may be absolute, and that path may
883           substituted for __FILE__ macros in the source code or included in
884           warnings emitted to standard error by the preprocessor.
885
886       This means that if you compile the same code in different locations,
887       you can’t share compilation results between the different build
888       directories since you get cache misses because of the absolute build
889       directory paths that are part of the hash.
890
891       Here’s what can be done to enable cache hits between different build
892       directories:
893
894       ·   If you build with -g (or similar) to add debug information to the
895           object file, you must either:
896
897           ·   use the -fdebug-prefix-map=old=new option for relocating debug
898               info to a common prefix (e.g.  -fdebug-prefix-map=$PWD=.); or
899
900           ·   set hash_dir = false.
901
902       ·   If you use absolute paths anywhere on the command line (e.g. the
903           source code file path or an argument to compiler options like -I
904           and -MF), you must to set base_dir to an absolute path to a “base
905           directory”. ccache will then rewrite absolute paths under that
906           directory to relative before computing the hash.
907

PRECOMPILED HEADERS

909       ccache has support for GCC’s precompiled headers. However, you have to
910       do some things to make it work properly:
911
912       ·   You must set sloppiness to pch_defines,time_macros. The reason is
913           that ccache can’t tell whether __TIME__ or __DATE__ is used when
914           using a precompiled header. Further, it can’t detect changes in
915           #defines in the source code because of how preprocessing works in
916           combination with precompiled headers.
917
918       ·   You must either:
919
920           ·   use the -include compiler option to include the precompiled
921               header (i.e., don’t use #include in the source code to include
922               the header); or
923
924           ·   (for the Clang compiler) use the -include-pch compiler option
925               to include the PCH file generated from the precompiled header;
926               or
927
928           ·   add the -fpch-preprocess compiler option when compiling.
929
930           If you don’t do this, either the non-precompiled version of the
931           header file will be used (if available) or ccache will fall back to
932           running the real compiler and increase the statistics counter
933           “preprocessor error” (if the non-precompiled header file is not
934           available).
935

SHARING A CACHE

937       A group of developers can increase the cache hit rate by sharing a
938       cache directory. To share a cache without unpleasant side effects, the
939       following conditions should to be met:
940
941       ·   Use the same cache directory.
942
943       ·   Make sure that the configuration setting hard_link is false (which
944           is the default).
945
946       ·   Make sure that all users are in the same group.
947
948       ·   Set the configuration setting umask to 002. This ensures that
949           cached files are accessible to everyone in the group.
950
951       ·   Make sure that all users have write permission in the entire cache
952           directory (and that you trust all users of the shared cache).
953
954       ·   Make sure that the setgid bit is set on all directories in the
955           cache. This tells the filesystem to inherit group ownership for new
956           directories. The following command might be useful for this:
957
958               find $CCACHE_DIR -type d | xargs chmod g+s
959
960       The reason to avoid the hard link mode is that the hard links cause
961       unwanted side effects, as all links to a cached file share the file’s
962       modification timestamp. This results in false dependencies to be
963       triggered by timestamp-based build systems whenever another user links
964       to an existing file. Typically, users will see that their libraries and
965       binaries are relinked without reason.
966
967       You may also want to make sure that a base directory is set
968       appropriately, as discussed in a previous section.
969

SHARING A CACHE ON NFS

971       It is possible to put the cache directory on an NFS filesystem (or
972       similar filesystems), but keep in mind that:
973
974       ·   Having the cache on NFS may slow down compilation. Make sure to do
975           some benchmarking to see if it’s worth it.
976
977       ·   ccache hasn’t been tested very thoroughly on NFS.
978
979       A tip is to set temporary_dir to a directory on the local host to avoid
980       NFS traffic for temporary files.
981

USING CCACHE WITH OTHER COMPILER WRAPPERS

983       The recommended way of combining ccache with another compiler wrapper
984       (such as “distcc”) is by letting ccache execute the compiler wrapper.
985       This is accomplished by defining the configuration setting
986       prefix_command, for example by setting the environment variable
987       CCACHE_PREFIX to the name of the wrapper (e.g. distcc). ccache will
988       then prefix the command line with the specified command when running
989       the compiler. To specify several prefix commands, set prefix_command to
990       a colon-separated list of commands.
991
992       Unless you set compiler_check to a suitable command (see the
993       description of that configuration option), it is not recommended to use
994       the form ccache anotherwrapper compiler args as the compilation
995       command. It’s also not recommended to use the masquerading technique
996       for the other compiler wrapper. The reason is that by default, ccache
997       will in both cases hash the mtime and size of the other wrapper instead
998       of the real compiler, which means that:
999
1000       ·   Compiler upgrades will not be detected properly.
1001
1002       ·   The cached results will not be shared between compilations with and
1003           without the other wrapper.
1004
1005       Another minor thing is that if prefix_command is used, ccache will not
1006       invoke the other wrapper when running the preprocessor, which increases
1007       performance. You can use the prefix_command_cpp configuration setting
1008       if you also want to invoke the other wrapper when doing preprocessing
1009       (normally by adding -E).
1010

CAVEATS

1012       ·   The direct mode fails to pick up new header files in some rare
1013           scenarios. See THE DIRECT MODE above.
1014
1015       ·   When run via ccache, warning messages produced by GCC 4.9 and newer
1016           will only be colored when the environment variable GCC_COLORS is
1017           set. An alternative to setting GCC_COLORS is to pass
1018           -fdiagnostics-color explicitly when compiling (but then color codes
1019           will also be present when redirecting stderr to a file).
1020
1021       ·   If ccache guesses that the compiler may emit colored warnings, then
1022           a compilation with stderr referring to a TTY will be considered
1023           different from a compilation with a redirected stderr, thus not
1024           sharing cache entries. This happens for clang by default and for
1025           GCC when GCC_COLORS is set as mentioned above. If you want to share
1026           cache hits, you can pass -f[no-]diagnostics-color (GCC) or
1027           -f[no-]color-diagnostics (clang) explicitly when compiling (but
1028           then color codes will be either on or off for both the TTY and the
1029           redirected case).
1030

TROUBLESHOOTING

1032   General
1033       A general tip for getting information about what ccache is doing is to
1034       enable debug logging by setting log_file. The log contains executed
1035       commands, important decisions that ccache makes, read and written
1036       files, etc. Another way of keeping track of what is happening is to
1037       check the output of ccache -s.
1038
1039   Performance
1040       ccache has been written to perform well out of the box, but sometimes
1041       you may have to do some adjustments of how you use the compiler and
1042       ccache in order to improve performance.
1043
1044       Since ccache works best when I/O is fast, put the cache directory on a
1045       fast storage device if possible. Having lots of free memory so that
1046       files in the cache directory stay in the disk cache is also preferable.
1047
1048       A good way of monitoring how well ccache works is to run ccache -s
1049       before and after your build and then compare the statistics counters.
1050       Here are some common problems and what may be done to increase the hit
1051       rate:
1052
1053       ·   If “cache hit (preprocessed)” has been incremented instead of
1054           “cache hit (direct)”, ccache has fallen back to preprocessor mode,
1055           which is generally slower. Some possible reasons are:
1056
1057           ·   The source code has been modified in such a way that the
1058               preprocessor output is not affected.
1059
1060           ·   Compiler arguments that are hashed in the direct mode but not
1061               in the preprocessor mode have changed (-I, -include, -D, etc)
1062               and they didn’t affect the preprocessor output.
1063
1064           ·   The compiler option -Xpreprocessor or -Wp,X (except
1065               -Wp,-MD,path, -Wp,-MMD,path, and -Wp,-D_define_) is used.
1066
1067           ·   This was the first compilation with a new value of the base
1068               directory setting.
1069
1070           ·   A modification time of one of the include files is too new
1071               (created the same second as the compilation is being done).
1072               This check is made to avoid a race condition. To fix this,
1073               create the include file earlier in the build process, if
1074               possible, or set sloppiness to include_file_mtime if you are
1075               willing to take the risk. (The race condition consists of these
1076               events: the preprocessor is run; an include file is modified by
1077               someone; the new include file is hashed by ccache; the real
1078               compiler is run on the preprocessor’s output, which contains
1079               data from the old header file; the wrong object file is stored
1080               in the cache.)
1081
1082           ·   The __TIME__ preprocessor macro is (potentially) being used.
1083               ccache turns off direct mode if __TIME__ is present in the
1084               source code. This is done as a safety measure since the string
1085               indicates that a __TIME__ macro may affect the output. (To be
1086               sure, ccache would have to run the preprocessor, but the sole
1087               point of the direct mode is to avoid that.) If you know that
1088               __TIME__ isn’t used in practise, or don’t care if ccache
1089               produces objects where __TIME__ is expanded to something in the
1090               past, you can set sloppiness to time_macros.
1091
1092           ·   The __DATE__ preprocessor macro is (potentially) being used and
1093               the date has changed. This is similar to how __TIME__ is
1094               handled. If __DATE__ is present in the source code, ccache
1095               hashes the current date in order to be able to produce the
1096               correct object file if the __DATE__ macro affects the output.
1097               If you know that __DATE__ isn’t used in practise, or don’t care
1098               if ccache produces objects where __DATE__ is expanded to
1099               something in the past, you can set sloppiness to time_macros.
1100
1101           ·   The __FILE__ preprocessor macro is (potentially) being used and
1102               the file path has changed. If __FILE__ is present in the source
1103               code, ccache hashes the current input file path in order to be
1104               able to produce the correct object file if the __FILE__ macro
1105               affects the output. If you know that __FILE__ isn’t used in
1106               practise, or don’t care if ccache produces objects where
1107               __FILE__ is expanded to the wrong path, you can set sloppiness
1108               to file_macro.
1109
1110       ·   If “cache miss” has been incremented even though the same code has
1111           been compiled and cached before, ccache has either detected that
1112           something has changed anyway or a cleanup has been performed
1113           (either explicitly or implicitly when a cache limit has been
1114           reached). Some perhaps unobvious things that may result in a cache
1115           miss are usage of __TIME__ or __DATE__ macros, or use of
1116           automatically generated code that contains a timestamp, build
1117           counter or other volatile information.
1118
1119       ·   If “multiple source files” has been incremented, it’s an indication
1120           that the compiler has been invoked on several source code files at
1121           once. ccache doesn’t support that. Compile the source code files
1122           separately if possible.
1123
1124       ·   If “unsupported compiler option” has been incremented, enable debug
1125           logging and check which option was rejected.
1126
1127       ·   If “preprocessor error” has been incremented, one possible reason
1128           is that precompiled headers are being used. See PRECOMPILED HEADERS
1129           for how to remedy this.
1130
1131       ·   If “can’t use precompiled header” has been incremented, see
1132           PRECOMPILED HEADERS.
1133
1134   Corrupt object files
1135       It should be noted that ccache is susceptible to general storage
1136       problems. If a bad object file sneaks into the cache for some reason,
1137       it will of course stay bad. Some possible reasons for erroneous object
1138       files are bad hardware (disk drive, disk controller, memory, etc),
1139       buggy drivers or file systems, a bad prefix_command or compiler
1140       wrapper. If this happens, the easiest way of fixing it is this:
1141
1142        1. Build so that the bad object file ends up in the build tree.
1143
1144        2. Remove the bad object file from the build tree.
1145
1146        3. Rebuild with CCACHE_RECACHE set.
1147
1148       An alternative is to clear the whole cache with ccache -C if you don’t
1149       mind losing other cached results.
1150
1151       There are no reported issues about ccache producing broken object files
1152       reproducibly. That doesn’t mean it can’t happen, so if you find a
1153       repeatable case, please report it.
1154

MORE INFORMATION

1156       Credits, mailing list information, bug reporting instructions, source
1157       code, etc, can be found on ccache’s web site: https://ccache.samba.org.
1158

AUTHOR

1160       ccache was originally written by Andrew Tridgell and is currently
1161       developed and maintained by Joel Rosdahl. See AUTHORS.txt or
1162       AUTHORS.html and https://ccache.samba.org/credits.html for a list of
1163       contributors.
1164
1165
1166
1167ccache 3.4.3                      09/02/2018                         CCACHE(1)
Impressum