]>
Commit | Line | Data |
---|---|---|
63239e95 JR |
1 | = ccache(1) |
2 | :mansource: Ccache {revnumber} | |
46e577ed | 3 | |
1d63b123 | 4 | == Name |
46e577ed | 5 | |
223e706f | 6 | ccache - a fast C/C++ compiler cache |
46e577ed JR |
7 | |
8 | ||
1d63b123 | 9 | == Synopsis |
46e577ed JR |
10 | |
11 | [verse] | |
e1a53fd0 JR |
12 | *ccache* [_ccache options_] |
13 | *ccache* [_KEY_=_VALUE_ ...] _compiler_ [_compiler options_] | |
14 | _compiler_ [_compiler options_] | |
15 | ||
16 | The first form takes options described in <<Command line options>> below. The | |
17 | second form invokes the compiler, optionally using <<Configuration,configuration | |
18 | options>> as _KEY_=_VALUE_ arguments. In the third form, ccache is masquerading | |
19 | as the compiler as described in <<Run modes>>. | |
46e577ed JR |
20 | |
21 | ||
1d63b123 | 22 | == Description |
46e577ed | 23 | |
a684bb35 | 24 | Ccache is a compiler cache. It speeds up recompilation by caching the result of |
4e907973 | 25 | previous compilations and detecting when the same compilation is being done |
b68617b3 | 26 | again. |
46e577ed | 27 | |
a684bb35 | 28 | Ccache has been carefully written to always produce exactly the same compiler |
614f764d JR |
29 | output that you would get without the cache. The only way you should be able to |
30 | tell that you are using ccache is the speed. Currently known exceptions to this | |
abff8ec1 | 31 | goal are listed under _<<Caveats>>_. If you discover an undocumented case where |
44766b29 | 32 | ccache changes the output of your compiler, please let us know. |
46e577ed JR |
33 | |
34 | ||
1d63b123 | 35 | == Run modes |
46e577ed | 36 | |
451d92c8 | 37 | There are two different ways to use ccache to cache a compilation: |
46e577ed | 38 | |
451d92c8 JR |
39 | 1. Prefix your compilation command with `ccache`. This method is most convenient |
40 | if you just want to try out ccache or wish to use it for some specific | |
41 | projects. Example: | |
42 | + | |
43 | ------------------------------------------------------------------------------- | |
44 | ccache gcc -c example.c | |
45 | ------------------------------------------------------------------------------- | |
46 | + | |
47 | 2. Let ccache masquerade as the compiler. This method is most useful when you | |
48 | wish to use ccache for all your compilations. To do this, create a symbolic | |
49 | link to ccache named as the compiler. For example, here is set up ccache to | |
50 | masquerade as `gcc` and `g++`: | |
51 | + | |
4aaa6a15 JR |
52 | ------------------------------------------------------------------------------- |
53 | cp ccache /usr/local/bin/ | |
54 | ln -s ccache /usr/local/bin/gcc | |
55 | ln -s ccache /usr/local/bin/g++ | |
4aaa6a15 | 56 | ------------------------------------------------------------------------------- |
451d92c8 JR |
57 | + |
58 | On platforms that don't support symbolic links you can simply copy ccache to the | |
59 | compiler name instead for a similar effect: | |
60 | + | |
61 | ------------------------------------------------------------------------------- | |
62 | cp ccache /usr/local/bin/gcc | |
63 | cp ccache /usr/local/bin/g++ | |
64 | ------------------------------------------------------------------------------- | |
65 | + | |
66 | And so forth. This will work as long as the directory with symbolic links or | |
67 | ccache copies comes before the directory with the compiler (typically | |
68 | `/usr/bin`) in `PATH`. | |
69 | + | |
15edf502 | 70 | WARNING: The technique of letting ccache masquerade as the compiler works well, |
44766b29 JR |
71 | but currently doesn't interact well with other tools that do the same thing. See |
72 | _<<Using ccache with other compiler wrappers>>_. | |
46e577ed | 73 | |
54480f02 | 74 | |
1d63b123 | 75 | == Command line options |
46e577ed | 76 | |
451d92c8 JR |
77 | These command line options only apply when you invoke ccache as "`ccache`". When |
78 | ccache masquerades as a compiler (as described in the previous section), the | |
79 | normal compiler options apply and you should refer to the compiler's | |
80 | documentation. | |
46e577ed | 81 | |
e24bd806 | 82 | |
1d63b123 | 83 | === Common options |
e24bd806 | 84 | |
63239e95 | 85 | *-c*, *--cleanup*:: |
46e577ed | 86 | |
33cebe20 JR |
87 | Clean up the cache by removing not recently used cached files until the |
88 | specified file number and cache size limits are not exceeded. This also | |
89 | recalculates the cache file count and size totals. Normally, there is no | |
90 | need to initiate cleanup manually as ccache keeps the cache below the | |
91 | specified limits at runtime and keeps statistics up to date on each | |
92 | compilation. Forcing a cleanup is mostly useful if you have modified the | |
93 | cache contents manually or believe that the cache size statistics may be | |
94 | inaccurate. | |
46e577ed | 95 | |
63239e95 | 96 | *-C*, *--clear*:: |
46e577ed | 97 | |
7c5a69e5 JR |
98 | Clear the entire cache, removing all cached files, but keeping the |
99 | configuration file. | |
46e577ed | 100 | |
63239e95 | 101 | *--config-path* _PATH_:: |
0d747803 | 102 | |
513c83fa | 103 | Let the command line options operate on configuration file _PATH_ instead of |
c83c3ccd JR |
104 | the default. Using this option has the same effect as setting (overriding) |
105 | the environment variable `CCACHE_CONFIGPATH` temporarily. | |
0d747803 | 106 | |
a239db94 | 107 | *-d*, *--dir* _PATH_:: |
f108509f | 108 | |
513c83fa JR |
109 | Let the command line options operate on cache directory _PATH_ instead of |
110 | the default. For example, to show statistics for a cache directory at | |
a239db94 JR |
111 | `/shared/ccache` you can run `ccache -d /shared/ccache -s`. Using this option |
112 | has the same effect as setting the environment variable `CCACHE_DIR` | |
513c83fa | 113 | temporarily. |
f108509f | 114 | |
9217417c JR |
115 | *--evict-namespace* _NAMESPACE_:: |
116 | ||
0e1f1f7c JR |
117 | Remove files created in the given <<config_namespace,*namespace*>> from the |
118 | cache. | |
9217417c | 119 | |
63239e95 | 120 | *--evict-older-than* _AGE_:: |
e04ee56c | 121 | |
33cebe20 JR |
122 | Remove files used less recently than _AGE_ from the cache. _AGE_ should be |
123 | an unsigned integer with a `d` (days) or `s` (seconds) suffix. If combined | |
124 | with `--evict-namespace`, only remove files within that namespace. | |
87ae5e39 | 125 | |
63239e95 | 126 | *-h*, *--help*:: |
9f59f7bb | 127 | |
74e3218a | 128 | Print a summary of command line options. |
9f59f7bb | 129 | |
63239e95 | 130 | *-F* _NUM_, *--max-files* _NUM_:: |
46e577ed | 131 | |
a44ef184 JR |
132 | Set the maximum number of files allowed in the cache to _NUM_. Use 0 for no |
133 | limit. The value is stored in a configuration file in the cache directory | |
134 | and applies to all future compilations. | |
46e577ed | 135 | |
63239e95 | 136 | *-M* _SIZE_, *--max-size* _SIZE_:: |
46e577ed | 137 | |
9f440b6c | 138 | Set the maximum size of the files stored in the cache. _SIZE_ should be a |
ac98dee7 JR |
139 | number followed by an optional suffix: kB, MB, GB, TB (decimal), KiB, MiB, |
140 | GiB or TiB (binary). The default suffix is GiB. Use 0 for no limit. The | |
141 | value is stored in a configuration file in the cache directory and applies | |
142 | to all future compilations. | |
99396f88 | 143 | |
63239e95 | 144 | *-X* _LEVEL_, *--recompress* _LEVEL_:: |
cb742851 | 145 | |
fa21e965 JR |
146 | Recompress the cache to level _LEVEL_ using the Zstandard algorithm. The |
147 | level can be an integer, with the same semantics as the | |
c4596d54 | 148 | <<config_compression_level,*compression_level*>> configuration option, or |
5d47a49c JR |
149 | the special value *uncompressed* for no compression. See _<<Cache |
150 | compression>>_ for more information. This can potentially take a long time | |
151 | since all files in the cache need to be visited. Only files that are | |
152 | currently compressed with a different level than _LEVEL_ will be | |
44766b29 | 153 | recompressed. |
cb742851 | 154 | |
f7c1ca19 JR |
155 | *--recompress-threads* _THREADS_:: |
156 | ||
157 | Use up to _THREADS_ threads when recompressing the cache. The default is to | |
158 | use one thread per CPU. | |
159 | ||
63239e95 | 160 | *-o* _KEY=VALUE_, *--set-config* _KEY_=_VALUE_:: |
9f59f7bb | 161 | |
44766b29 JR |
162 | Set configuration option _KEY_ to _VALUE_. See _<<Configuration>>_ for more |
163 | information. | |
9f59f7bb | 164 | |
63239e95 | 165 | *-x*, *--show-compression*:: |
52e0e928 | 166 | |
44766b29 | 167 | Print cache compression statistics. See _<<Cache compression>>_ for more |
b8d068c0 | 168 | information. This can potentially take a long time since all files in the |
44766b29 | 169 | cache need to be visited. |
52e0e928 | 170 | |
63239e95 | 171 | *-p*, *--show-config*:: |
d8e2ab9a | 172 | |
e24bd806 JR |
173 | Print current configuration options and from where they originate |
174 | (environment variable, configuration file or compile-time default) in | |
175 | human-readable format. | |
d8e2ab9a | 176 | |
63239e95 | 177 | *--show-log-stats*:: |
fe22a1de | 178 | |
44766b29 | 179 | Print statistics counters from the stats log in human-readable format. See |
8892814e JR |
180 | <<config_stats_log,*stats_log*>>. Use `-v`/`--verbose` once or twice for |
181 | more details. | |
fe22a1de | 182 | |
63239e95 | 183 | *-s*, *--show-stats*:: |
46e577ed | 184 | |
331a1c38 | 185 | Print a summary of configuration and statistics counters in human-readable |
8892814e JR |
186 | format. Use `-v`/`--verbose` once or twice for more details. |
187 | ||
188 | *-v*, *--verbose*:: | |
189 | ||
190 | Increase verbosity. The option can be given multiple times. | |
46e577ed | 191 | |
63239e95 | 192 | *-V*, *--version*:: |
46e577ed JR |
193 | |
194 | Print version and copyright information. | |
195 | ||
63239e95 | 196 | *-z*, *--zero-stats*:: |
46e577ed | 197 | |
99396f88 | 198 | Zero the cache statistics (but not the configuration options). |
46e577ed JR |
199 | |
200 | ||
0cd6f70b | 201 | === Options for remote file-based storage |
a358033b JR |
202 | |
203 | *--trim-dir* _PATH_:: | |
204 | ||
33cebe20 JR |
205 | Remove not recently used files from directory _PATH_ until it is at most the |
206 | size specified by `--trim-max-size`. | |
a358033b | 207 | + |
0cd6f70b JR |
208 | WARNING: Don't use this option to trim the local cache. To trim the local cache |
209 | directory to a certain size, use `CCACHE_MAXSIZE=_SIZE_ ccache -c`. | |
a358033b JR |
210 | |
211 | *--trim-max-size* _SIZE_:: | |
212 | ||
563cc8eb | 213 | Specify the maximum size for `--trim-dir`. _SIZE_ should be a number |
ac98dee7 | 214 | followed by an optional suffix: kB, MB, GB, TB (decimal), KiB, MiB, GiB or |
5bdd6f38 | 215 | TiB (binary). The default suffix is GiB. Use 0 for no limit. |
a358033b JR |
216 | |
217 | *--trim-method* _METHOD_:: | |
218 | ||
219 | Specify the method to trim a directory with `--trim-dir`. Possible values | |
220 | are: | |
221 | + | |
222 | -- | |
223 | *atime*:: | |
224 | LRU (least recently used) using the file access timestamp. This is the | |
225 | default. | |
226 | *mtime*:: | |
227 | LRU (least recently used) using the file modification timestamp. | |
228 | -- | |
229 | ||
5d47a49c JR |
230 | *--trim-recompress* _LEVEL_:: |
231 | ||
232 | Recompress to level _LEVEL_ using the Zstandard algorithm when using | |
233 | `--trim-dir`. The level can be an integer, with the same semantics as the | |
b8d068c0 | 234 | <<config_compression_level,*compression_level*>> configuration option, or |
5d47a49c | 235 | the special value *uncompressed* for no compression. See _<<Cache |
b8d068c0 | 236 | compression>>_ for more information. This can potentially take a long time |
5d47a49c JR |
237 | since all files in the cache need to be visited. Only files that are |
238 | currently compressed with a different level than _LEVEL_ will be | |
239 | recompressed. | |
240 | ||
241 | *--trim-recompress-threads* _THREADS_:: | |
242 | ||
243 | Recompress using up to _THREADS_ threads with `--trim-recompress`. The | |
244 | default is to use one thread per CPU. | |
245 | ||
246 | ||
1d63b123 | 247 | === Options for scripting or debugging |
e24bd806 | 248 | |
63239e95 | 249 | *--checksum-file* _PATH_:: |
6b865444 | 250 | |
b8f54279 | 251 | Print the checksum (128 bit XXH3) of the file at _PATH_ (`-` for standard |
00d679a7 | 252 | input). |
6b865444 | 253 | |
63239e95 | 254 | *--extract-result* _PATH_:: |
d97b6dde | 255 | |
00d679a7 | 256 | Extract data stored in the result file at _PATH_ (`-` for standard input). |
63239e95 | 257 | The data will be written to `ccache-result.*` files in to the current |
02dac1f1 | 258 | working directory. This option is only useful when debugging ccache and its |
00d679a7 | 259 | behavior. |
fb92555b | 260 | |
63239e95 | 261 | *-k* _KEY_, *--get-config* _KEY_:: |
e24bd806 | 262 | |
44766b29 JR |
263 | Print the value of configuration option _KEY_. See _<<Configuration>>_ for |
264 | more information. | |
e24bd806 | 265 | |
63239e95 | 266 | *--hash-file* _PATH_:: |
e24bd806 | 267 | |
00d679a7 JR |
268 | Print the hash (160 bit BLAKE3) of the file at _PATH_ (`-` for standard |
269 | input). This is only useful when debugging ccache and its behavior. | |
e24bd806 | 270 | |
02dac1f1 JR |
271 | *--inspect* _PATH_:: |
272 | ||
273 | Print the content of a result or manifest file at _PATH_ (`-` for standard | |
274 | input) to standard output in human-readable format. File content embedded in | |
275 | a result file will however not be printed; use `--extract-result` to extract | |
276 | the file content. This option is only useful when debugging ccache and its | |
277 | behavior. | |
278 | ||
63239e95 | 279 | *--print-stats*:: |
e24bd806 | 280 | |
fa48770d | 281 | Print statistics counter IDs and corresponding values in machine-parsable |
e24bd806 JR |
282 | (tab-separated) format. |
283 | ||
284 | ||
285 | ||
1d63b123 | 286 | === Extra options |
46e577ed JR |
287 | |
288 | When run as a compiler, ccache usually just takes the same command line options | |
289 | as the compiler you are using. The only exception to this is the option | |
63239e95 | 290 | `--ccache-skip`. That option can be used to tell ccache to avoid interpreting |
25b70699 PP |
291 | the next option in any way and to pass it along to the compiler as-is. |
292 | ||
63239e95 | 293 | NOTE: `--ccache-skip` currently only tells ccache not to interpret the next |
0a212624 JR |
294 | option as a special compiler option -- the option will still be included in the |
295 | direct mode hash. | |
46e577ed JR |
296 | |
297 | The reason this can be important is that ccache does need to parse the command | |
298 | line and determine what is an input filename and what is a compiler option, as | |
299 | it needs the input filename to determine the name of the resulting object file | |
300 | (among other things). The heuristic ccache uses when parsing the command line | |
4e907973 | 301 | is that any argument that exists as a file is treated as an input file name. By |
63239e95 | 302 | using `--ccache-skip` you can force an option to not be treated as an input |
4e907973 | 303 | file name and instead be passed along to the compiler as a command line option. |
46e577ed | 304 | |
63239e95 | 305 | Another case where `--ccache-skip` can be useful is if ccache interprets an |
8177355f JR |
306 | option specially but shouldn't, since the option has another meaning for your |
307 | compiler than what ccache thinks. | |
308 | ||
2737d79e JR |
309 | See also <<config_ignore_options,*ignore_options*>>. |
310 | ||
46e577ed | 311 | |
1d63b123 | 312 | == Configuration |
99396f88 | 313 | |
63239e95 | 314 | Ccache's default behavior can be overridden by options in configuration files, |
99396f88 | 315 | which in turn can be overridden by environment variables with names starting |
63239e95 | 316 | with `CCACHE_`. Ccache normally reads configuration from two files: first a |
99396f88 | 317 | system-level configuration file and secondly a cache-specific configuration |
41b3e6c5 | 318 | file. The priorities of configuration options are as follows (where 1 is |
99396f88 JR |
319 | highest): |
320 | ||
e1a53fd0 JR |
321 | 1. Command line settings in _KEY_=_VALUE_ form. Example: |
322 | + | |
323 | ------------------------------------------------------------------------------- | |
324 | ccache debug=true compiler_check="%compiler% --version" gcc -c example.c | |
325 | ------------------------------------------------------------------------------- | |
326 | 2. Environment variables. | |
327 | 3. The cache-specific configuration file (see below). | |
328 | 4. The system (read-only) configuration file `<sysconfdir>/ccache.conf` | |
a2e7f910 | 329 | (typically `/etc/ccache.conf` or `/usr/local/etc/ccache.conf`). |
e1a53fd0 | 330 | 5. Compile-time defaults. |
99396f88 | 331 | |
a2e7f910 JR |
332 | As a special case, if the environment variable `CCACHE_CONFIGPATH` is set it |
333 | specifies the configuration file, and the system configuration file won't be | |
334 | read. | |
d0dea008 JR |
335 | |
336 | ||
a2e7f910 | 337 | === Location of the configuration file |
d0dea008 | 338 | |
a2e7f910 JR |
339 | The location of the cache-specific configuration file is determined like this on |
340 | non-Windows systems: | |
d0dea008 | 341 | |
63239e95 JR |
342 | 1. If `CCACHE_CONFIGPATH` is set, use that path. |
343 | 2. Otherwise, if the environment variable `CCACHE_DIR` is set then use | |
344 | `$CCACHE_DIR/ccache.conf`. | |
a2e7f910 JR |
345 | 3. Otherwise, if <<config_cache_dir,*cache_dir*>> is set in the system |
346 | configuration file then use `<cache_dir>/ccache.conf`. | |
63239e95 JR |
347 | 4. Otherwise, if there is a legacy `$HOME/.ccache` directory then use |
348 | `$HOME/.ccache/ccache.conf`. | |
349 | 5. Otherwise, if `XDG_CONFIG_HOME` is set then use | |
350 | `$XDG_CONFIG_HOME/ccache/ccache.conf`. | |
af6a7aec | 351 | 6. Otherwise, use |
63239e95 JR |
352 | `$HOME/Library/Preferences/ccache/ccache.conf` (macOS) or |
353 | `$HOME/.config/ccache/ccache.conf` (other systems). | |
99396f88 | 354 | |
af6a7aec RK |
355 | On Windows, this is the method used to find the configuration file: |
356 | ||
357 | 1. If `CCACHE_CONFIGPATH` is set, use that path. | |
358 | 2. Otherwise, if the environment variable `CCACHE_DIR` is set then use | |
359 | `%CCACHE_DIR%/ccache.conf`. | |
a2e7f910 JR |
360 | 3. Otherwise, if <<config_cache_dir,*cache_dir*>> is set in the system |
361 | configuration file then use `<cache_dir>\ccache.conf`. The | |
af6a7aec | 362 | system-wide configuration on Windows is |
29c7a5b7 | 363 | `%ALLUSERSPROFILE%\ccache\ccache.conf` by default. The `ALLUSERSPROFILE` |
af6a7aec RK |
364 | environment variable is usually `C:\ProgramData`. |
365 | 4. Otherwise, if there is a legacy `%USERPROFILE%\.ccache` directory then use | |
366 | `%USERPROFILE%\.ccache\ccache.conf`. | |
29c7a5b7 JR |
367 | 5. Otherwise, use `%LOCALAPPDATA%\ccache\ccache.conf` if it exists. |
368 | 6. Otherwise, use `%APPDATA%\ccache\ccache.conf`. | |
af6a7aec RK |
369 | |
370 | See also the <<config_cache_dir,*cache_dir*>> configuration option for how the | |
371 | cache directory location is determined. | |
99396f88 | 372 | |
29c7a5b7 | 373 | |
c92b683b JR |
374 | === Configuration value syntax |
375 | ||
376 | All configuration values support expansion of environment variables. The syntax | |
377 | is similar to POSIX shell syntax: `$VAR` or `${VAR}`. Both variants will expand | |
378 | to the value of the environment variable `VAR`. | |
379 | ||
380 | Two consecutive dollar signs (`$$`) will expand to a single dollar sign (`$`). | |
381 | ||
382 | ||
1d63b123 | 383 | === Configuration file syntax |
99396f88 | 384 | |
63239e95 | 385 | Configuration files are in a simple "`key = value`" format, one option per |
7c5a69e5 JR |
386 | line. Lines starting with a hash sign are comments. Blank lines are ignored, as |
387 | is whitespace surrounding keys and values. Example: | |
99396f88 JR |
388 | |
389 | ------------------------------------------------------------------------------- | |
390 | # Set maximum cache size to 10 GB: | |
391 | max_size = 10G | |
392 | ------------------------------------------------------------------------------- | |
393 | ||
1d63b123 | 394 | === Boolean values |
99396f88 | 395 | |
74e3218a JR |
396 | Some configuration options are boolean values (i.e. truth values). In a |
397 | configuration file, such values must be set to the string *true* or *false*. | |
398 | For the corresponding environment variables, the semantics are a bit different: | |
399 | ||
63239e95 | 400 | * A set environment variable means "`true`" (even if set to the empty string). |
74e3218a JR |
401 | * The following case-insensitive negative values are considered an error |
402 | (instead of surprising the user): *0*, *false*, *disable* and *no*. | |
63239e95 | 403 | * An unset environment variable means "`false`". |
46e577ed | 404 | |
74e3218a | 405 | Each boolean environment variable also has a negated form starting with |
63239e95 JR |
406 | `CCACHE_NO`. For example, `CCACHE_COMPRESS` can be set to force compression and |
407 | `CCACHE_NOCOMPRESS` can be set to force no compression. | |
46e577ed | 408 | |
74e3218a | 409 | |
1d63b123 | 410 | === Configuration options |
46e577ed | 411 | |
74e3218a | 412 | Below is a list of available configuration options. The corresponding |
99396f88 | 413 | environment variable name is indicated in parentheses after each configuration |
74e3218a | 414 | option key. |
99396f88 | 415 | |
77035ead JR |
416 | [#config_absolute_paths_in_stderr] |
417 | *absolute_paths_in_stderr* (*CCACHE_ABSSTDERR*):: | |
377b8595 | 418 | |
74e3218a | 419 | This option specifies whether ccache should rewrite relative paths in the |
377b8595 JR |
420 | compiler's standard error output to absolute paths. This can be useful if |
421 | you use <<config_base_dir,*base_dir*>> with a build system (e.g. CMake with | |
422 | the "Unix Makefiles" generator) that executes the compiler in a different | |
423 | working directory, which makes relative paths in compiler errors or | |
424 | warnings incorrect. The default is false. | |
425 | ||
77035ead JR |
426 | [#config_base_dir] |
427 | *base_dir* (*CCACHE_BASEDIR*):: | |
99396f88 | 428 | |
74e3218a | 429 | This option should be an absolute path to a directory. If set, ccache will |
44766b29 JR |
430 | rewrite absolute paths into paths relative to the current working directory, |
431 | but only absolute paths that begin with *base_dir*. Cache results can then | |
432 | be shared for compilations in different directories even if the project uses | |
433 | absolute paths in the compiler command line. See also the discussion under | |
434 | _<<Compiling in different directories>>_. If set to the empty string (which | |
435 | is the default), no rewriting is done. | |
51d169e4 | 436 | + |
93dc54a0 JR |
437 | A typical path to use as *base_dir* is your home directory or another directory |
438 | that is a parent of your project directories. Don't use `/` as the base | |
439 | directory since that will make ccache also rewrite paths to system header | |
df94fa94 | 440 | files, which typically is counterproductive. |
377b8595 | 441 | + |
93dc54a0 JR |
442 | For example, say that Alice's current working directory is |
443 | `/home/alice/project1/build` and that she compiles like this: | |
444 | + | |
445 | ------------------------------------------------------------------------------- | |
446 | ccache gcc -I/usr/include/example -I/home/alice/project2/include -c /home/alice/project1/src/example.c | |
447 | ------------------------------------------------------------------------------- | |
448 | + | |
74e3218a | 449 | Here is what ccache will actually execute for different *base_dir* values: |
93dc54a0 JR |
450 | + |
451 | ------------------------------------------------------------------------------- | |
452 | # Current working directory: /home/alice/project1/build | |
453 | ||
454 | # With base_dir = /: | |
455 | gcc -I../../../../usr/include/example -I../../project2/include -c ../src/example.c | |
456 | ||
457 | # With base_dir = /home or /home/alice: | |
458 | gcc -I/usr/include/example -I../../project2/include -c ../src/example.c | |
459 | ||
460 | # With base_dir = /home/alice/project1 or /home/alice/project1/src: | |
461 | gcc -I/usr/include/example -I/home/alice/project2/include -c ../src/example.c | |
462 | ------------------------------------------------------------------------------- | |
463 | + | |
464 | If Bob has put `project1` and `project2` in `/home/bob/stuff` and both users | |
465 | have set *base_dir* to `/home` or `/home/$USER`, then Bob will get a cache hit | |
466 | (if they share ccache directory) since the actual command line will be | |
df94fa94 | 467 | identical to Alice's command line: |
93dc54a0 JR |
468 | + |
469 | ------------------------------------------------------------------------------- | |
470 | # Current working directory: /home/bob/stuff/project1/build | |
471 | ||
472 | # With base_dir = /home or /home/bob: | |
473 | gcc -I/usr/include/example -I../../project2/include -c ../src/example.c | |
474 | ------------------------------------------------------------------------------- | |
475 | + | |
476 | Without *base_dir* there will be a cache miss since the absolute paths will | |
477 | differ. With *base_dir* set to `/` there will be a cache miss since the | |
478 | relative path to `/usr/include/example` will be different. With *base_dir* set | |
479 | to `/home/bob/stuff/project1` there will a cache miss since the path to | |
480 | project2 will be a different absolute path. | |
e15af963 JR |
481 | + |
482 | WARNING: Rewriting absolute paths to relative is kind of a brittle hack. It | |
483 | works OK in many cases, but there might be cases where things break. One known | |
484 | issue is that absolute paths are not reproduced in dependency files, which can | |
485 | mess up dependency detection in tools like Make and Ninja. If possible, use | |
486 | relative paths in the first place instead instead of using *base_dir*. | |
46e577ed | 487 | |
77035ead JR |
488 | [#config_cache_dir] |
489 | *cache_dir* (*CCACHE_DIR*):: | |
99396f88 | 490 | |
29c7a5b7 | 491 | This option specifies where ccache will keep its cached compiler outputs. |
af6a7aec | 492 | + |
29c7a5b7 JR |
493 | On non-Windows systems, the default is `$HOME/.ccache` if such a directory |
494 | exists, otherwise `$XDG_CACHE_HOME/ccache` if `XDG_CACHE_HOME` is set, otherwise | |
495 | `$HOME/Library/Caches/ccache` (macOS) or `$HOME/.config/ccache` (other systems). | |
af6a7aec | 496 | + |
29c7a5b7 JR |
497 | On Windows, the default is `%USERPROFILE%\.ccache` if such a directory exists, |
498 | otherwise `%LOCALAPPDATA%\ccache`. | |
af6a7aec | 499 | + |
29c7a5b7 JR |
500 | WARNING: Previous ccache versions defaulted to storing the cache in |
501 | `%APPDATA%\ccache` on Windows. This can result in large network file transfers | |
502 | of the cache in domain environments and similar problems. Please check this | |
503 | directory for cache directories and either delete them or the whole directory, | |
504 | or move them to the `%LOCALAPPDATA%\ccache` directory. | |
a0c3aa52 | 505 | + |
a2e7f910 | 506 | See also _<<Location of the configuration file>>_. |
fcab8b21 | 507 | |
77035ead JR |
508 | [#config_compiler] |
509 | *compiler* (*CCACHE_COMPILER* or (deprecated) *CCACHE_CC*):: | |
99396f88 | 510 | |
74e3218a JR |
511 | This option can be used to force the name of the compiler to use. If set to |
512 | the empty string (which is the default), ccache works it out from the | |
99396f88 JR |
513 | command line. |
514 | ||
77035ead JR |
515 | [#config_compiler_check] |
516 | *compiler_check* (*CCACHE_COMPILERCHECK*):: | |
46e577ed | 517 | |
63239e95 | 518 | By default, ccache includes the modification time ("`mtime`") and size of |
bb956e3c | 519 | the compiler in the hash to ensure that results retrieved from the cache |
49ae7f09 | 520 | are accurate. If compiler plugins are used, these plugins will also be |
3a2f9708 PG |
521 | added to the hash. This option can be used to select another strategy. |
522 | Possible values are: | |
d7d80b8a JR |
523 | + |
524 | -- | |
525 | *content*:: | |
bb956e3c | 526 | Hash the content of the compiler binary. This makes ccache very slightly |
74e3218a JR |
527 | slower compared to *mtime*, but makes it cope better with compiler upgrades |
528 | during a build bootstrapping process. | |
d7d80b8a | 529 | *mtime*:: |
bb956e3c | 530 | Hash the compiler's mtime and size, which is fast. This is the default. |
d7d80b8a | 531 | *none*:: |
bb956e3c JR |
532 | Don't hash anything. This may be good for situations where you can safely |
533 | use the cached results even though the compiler's mtime or size has changed | |
534 | (e.g. if the compiler is built as part of your build system and the | |
535 | compiler's source has not changed, or if the compiler only has changes that | |
74e3218a JR |
536 | don't affect code generation). You should only use *none* if you know what |
537 | you are doing. | |
2290424b | 538 | *string:value*:: |
c3174ada JR |
539 | Hash *value*. This can for instance be a compiler revision number or |
540 | another string that the build system generates to identify the compiler. | |
18cc772a JR |
541 | _a command string_:: |
542 | Hash the standard output and standard error output of the specified | |
80342192 JR |
543 | command. The string will be split on whitespace to find out the command and |
544 | arguments to run. No other interpretation of the command string will be | |
99396f88 | 545 | done, except that the special word *%compiler%* will be replaced with the |
80342192 JR |
546 | path to the compiler. Several commands can be specified with semicolon as |
547 | separator. Examples: | |
18cc772a | 548 | + |
25b70699 PP |
549 | ---- |
550 | %compiler% -v | |
551 | ---- | |
63239e95 | 552 | + |
25b70699 PP |
553 | ---- |
554 | %compiler% -dumpmachine; %compiler% -dumpversion | |
555 | ---- | |
63239e95 | 556 | + |
18cc772a JR |
557 | You should make sure that the specified command is as fast as possible since it |
558 | will be run once for each ccache invocation. | |
63239e95 | 559 | + |
18cc772a JR |
560 | Identifying the compiler using a command is useful if you want to avoid cache |
561 | misses when the compiler has been rebuilt but not changed. | |
63239e95 | 562 | + |
18cc772a JR |
563 | Another case is when the compiler (as seen by ccache) actually isn't the real |
564 | compiler but another compiler wrapper -- in that case, the default *mtime* | |
565 | method will hash the mtime and size of the other compiler wrapper, which means | |
44766b29 JR |
566 | that ccache won't be able to detect a compiler upgrade. Using a suitable command |
567 | to identify the compiler is thus safer, but it's also slower, so you should | |
568 | consider continue using the *mtime* method in combination with the | |
fa48770d | 569 | *prefix_command* option if possible. See |
395c1c7f | 570 | _<<Using ccache with other compiler wrappers>>_. |
18cc772a | 571 | -- |
46e577ed | 572 | |
77035ead JR |
573 | [#config_compiler_type] |
574 | *compiler_type* (*CCACHE_COMPILERTYPE*):: | |
e2ab1352 JR |
575 | |
576 | Ccache normally guesses the compiler type based on the compiler name. The | |
577 | *compiler_type* option lets you force a compiler type. This can be useful | |
578 | if the compiler has a non-standard name but is actually one of the known | |
579 | compiler types. Possible values are: | |
580 | + | |
581 | -- | |
582 | *auto*:: | |
583 | Guess one of the types below based on the compiler name (following | |
584 | symlinks). This is the default. | |
585 | *clang*:: | |
586 | Clang-based compiler. | |
c845deb9 JR |
587 | *clang-cl*:: |
588 | clang-cl. | |
e2ab1352 JR |
589 | *gcc*:: |
590 | GCC-based compiler. | |
6c2f9ee7 DR |
591 | *icl*:: |
592 | Intel compiler on Windows. | |
1672be83 JR |
593 | *msvc*:: |
594 | Microsoft Visual C++ (MSVC). | |
e2ab1352 JR |
595 | *nvcc*:: |
596 | NVCC (CUDA) compiler. | |
5e53d17a | 597 | *other*:: |
e2ab1352 | 598 | Any compiler other than the known types. |
e2ab1352 JR |
599 | -- |
600 | ||
77035ead JR |
601 | [#config_compression] |
602 | *compression* (*CCACHE_COMPRESS* or *CCACHE_NOCOMPRESS*, see _<<Boolean values>>_ above):: | |
46e577ed | 603 | |
62a6313e | 604 | If true, ccache will compress data it puts in the cache. However, this |
74e3218a JR |
605 | option has no effect on how files are retrieved from the cache; compressed |
606 | and uncompressed results will still be usable regardless of this option. | |
62a6313e JR |
607 | The default is true. |
608 | + | |
609 | Compression is done using the Zstandard algorithm. The algorithm is fast enough | |
610 | that there should be little reason to turn off compression to gain performance. | |
611 | One exception is if the cache is located on a compressed file system, in which | |
612 | case the compression performed by ccache of course is redundant. | |
a46fd5b8 | 613 | + |
9a817f74 | 614 | Compression will be disabled if file cloning (the |
74e3218a JR |
615 | <<config_file_clone,*file_clone*>> option) or hard linking (the |
616 | <<config_hard_link,*hard_link*>> option) is enabled. | |
46e577ed | 617 | |
77035ead JR |
618 | [#config_compression_level] |
619 | *compression_level* (*CCACHE_COMPRESSLEVEL*):: | |
46e577ed | 620 | |
74e3218a JR |
621 | This option determines the level at which ccache will compress object files |
622 | using the real-time compression algorithm Zstandard. It only has effect if | |
623 | <<config_compression,*compression*>> is enabled (which it is by default). | |
624 | Zstandard is extremely fast for decompression and very fast for compression | |
625 | for lower compression levels. The default is 0. | |
62a6313e JR |
626 | + |
627 | Semantics of *compression_level*: | |
628 | + | |
629 | -- | |
630 | *> 0*:: | |
631 | A positive value corresponds to normal Zstandard compression levels. Lower | |
632 | levels (e.g. *1*) mean faster compression but worse compression ratio. | |
74e3218a | 633 | Higher levels (e.g. *19*) mean slower compression but better compression |
fa21e965 JR |
634 | ratio. The maximum possible value depends on the libzstd version, but at |
635 | least up to 19 is available for all versions. Decompression speed is | |
636 | essentially the same for all levels. As a rule of thumb, use level 5 or | |
637 | lower since higher levels may slow down compilations noticeably. Higher | |
638 | levels are however useful when recompressing the cache with command line | |
63239e95 | 639 | option `-X`/`--recompress`. |
62a6313e | 640 | *< 0*:: |
63239e95 | 641 | A negative value corresponds to Zstandard's "`ultra-fast`" compression |
74e3218a | 642 | levels, which are even faster than level 1 but with less good compression |
63239e95 | 643 | ratios. For instance, level *-3* corresponds to `--fast=3` for the `zstd` |
fa21e965 JR |
644 | command line tool. In practice, there is little use for levels lower than |
645 | *-5* or so. | |
62a6313e JR |
646 | *0* (default):: |
647 | The value *0* means that ccache will choose a suitable level, currently | |
004da599 | 648 | *1*. |
62a6313e | 649 | -- |
fa21e965 JR |
650 | + |
651 | See the http://zstd.net[Zstandard documentation] for more information. | |
46e577ed | 652 | |
77035ead JR |
653 | [#config_cpp_extension] |
654 | *cpp_extension* (*CCACHE_EXTENSION*):: | |
46e577ed | 655 | |
74e3218a | 656 | This option can be used to force a certain extension for the intermediate |
99396f88 JR |
657 | preprocessed file. The default is to automatically determine the extension |
658 | to use for intermediate preprocessor files based on the type of file being | |
659 | compiled, but that sometimes doesn't work. For example, when using the | |
63239e95 | 660 | "`aCC`" compiler on HP-UX, set the cpp extension to *i*. |
46e577ed | 661 | |
77035ead JR |
662 | [#config_debug] |
663 | *debug* (*CCACHE_DEBUG* or *CCACHE_NODEBUG*, see _<<Boolean values>>_ above):: | |
d2570473 | 664 | |
e3dbefeb JR |
665 | If true, enable the debug mode. The debug mode creates per-object debug |
666 | files that are helpful when debugging unexpected cache misses. Note however | |
44766b29 JR |
667 | that ccache performance will be reduced slightly. See _<<Cache debugging>>_ |
668 | for more information. The default is false. | |
d2570473 | 669 | |
77035ead JR |
670 | [#config_debug_dir] |
671 | *debug_dir* (*CCACHE_DEBUGDIR*):: | |
a181d44d | 672 | |
63239e95 JR |
673 | Specifies where to write per-object debug files if the <<config_debug,debug |
674 | mode>> is enabled. If set to the empty string, the files will be written | |
a181d44d JR |
675 | next to the object file. If set to a directory, the debug files will be |
676 | written with full absolute paths in that directory, creating it if needed. | |
677 | The default is the empty string. | |
4bec396a | 678 | + |
5437d4a4 JR |
679 | For example, if *debug_dir* is set to `/example`, the current working directory |
680 | is `/home/user` and the object file is `build/output.o` then the debug log will | |
681 | be written to `/example/home/user/build/output.o.ccache-log`. See also | |
395c1c7f | 682 | _<<Cache debugging>>_. |
a181d44d | 683 | |
f8faf9b4 | 684 | [#config_debug_level] |
685 | *debug_level* (*CCACHE_DEBUGLEVEL*):: | |
686 | ||
8c2e9f5d JR |
687 | Specifies the amount of information that is written when the |
688 | <<config_debug,debug mode>> is enabled. See _<<Cache debugging>>_ for more | |
689 | information. The default is 2. | |
f8faf9b4 | 690 | |
77035ead JR |
691 | [#config_depend_mode] |
692 | *depend_mode* (*CCACHE_DEPEND* or *CCACHE_NODEPEND*, see _<<Boolean values>>_ above):: | |
60ced47f AB |
693 | |
694 | If true, the depend mode will be used. The default is false. See | |
395c1c7f | 695 | _<<The depend mode>>_. |
60ced47f | 696 | |
77035ead JR |
697 | [#config_direct_mode] |
698 | *direct_mode* (*CCACHE_DIRECT* or *CCACHE_NODIRECT*, see _<<Boolean values>>_ above):: | |
46e577ed | 699 | |
3f0569b3 | 700 | If true, the direct mode will be used. The default is true. See |
395c1c7f | 701 | _<<The direct mode>>_. |
46e577ed | 702 | |
77035ead JR |
703 | [#config_disable] |
704 | *disable* (*CCACHE_DISABLE* or *CCACHE_NODISABLE*, see _<<Boolean values>>_ above):: | |
609fb341 | 705 | |
99396f88 JR |
706 | When true, ccache will just call the real compiler, bypassing the cache |
707 | completely. The default is false. | |
b3c3e799 JR |
708 | + |
709 | It is also possible to disable ccache for a specific source code file by adding | |
710 | the string `ccache:disable` in a comment in the first 4096 bytes of the file. | |
609fb341 | 711 | |
77035ead JR |
712 | [#config_extra_files_to_hash] |
713 | *extra_files_to_hash* (*CCACHE_EXTRAFILES*):: | |
46e577ed | 714 | |
74e3218a JR |
715 | This option is a list of paths to files that ccache will include in the the |
716 | hash sum that identifies the build. The list separator is semicolon on | |
99396f88 | 717 | Windows systems and colon on other systems. |
46e577ed | 718 | |
77035ead JR |
719 | [#config_file_clone] |
720 | *file_clone* (*CCACHE_FILECLONE* or *CCACHE_NOFILECLONE*, see _<<Boolean values>>_ above):: | |
3cc4bcd0 | 721 | |
63239e95 JR |
722 | If true, ccache will attempt to use file cloning (also known as "`copy on |
723 | write`", "`CoW`" or "`reflinks`") to store and fetch cached compiler | |
724 | results. *file_clone* has priority over <<config_hard_link,*hard_link*>>. | |
725 | The default is false. | |
3cc4bcd0 JR |
726 | + |
727 | Files stored by cloning cannot be compressed, so the cache size will likely be | |
728 | significantly larger if this option is enabled. However, performance may be | |
729 | improved depending on the use case. | |
730 | + | |
74e3218a | 731 | Unlike the <<config_hard_link,*hard_link*>> option, *file_clone* is completely |
9a817f74 JR |
732 | safe to use, but not all file systems support the feature. For such file |
733 | systems, ccache will fall back to use plain copying (or hard links if | |
734 | <<config_hard_link,*hard_link*>> is enabled). | |
3cc4bcd0 | 735 | |
77035ead JR |
736 | [#config_hard_link] |
737 | *hard_link* (*CCACHE_HARDLINK* or *CCACHE_NOHARDLINK*, see _<<Boolean values>>_ above):: | |
a46fd5b8 | 738 | |
3cc4bcd0 | 739 | If true, ccache will attempt to use hard links to store and fetch cached |
1ceb211a | 740 | object files. The default is false. |
a46fd5b8 JR |
741 | + |
742 | Files stored via hard links cannot be compressed, so the cache size will likely | |
743 | be significantly larger if this option is enabled. However, performance may be | |
744 | improved depending on the use case. | |
745 | + | |
746 | WARNING: Do not enable this option unless you are aware of these caveats: | |
747 | + | |
748 | * If the resulting file is modified, the file in the cache will also be | |
749 | modified since they share content, which corrupts the cache entry. As of | |
5e6a570c | 750 | version 4.0, ccache makes stored and fetched object files read-only as a |
49ae7f09 JR |
751 | safety measure. Furthermore, a simple integrity check is made for cached |
752 | object files by verifying that their sizes are correct. This means that | |
753 | mistakes like `strip file.o` or `echo >file.o` will be detected even if the | |
4929868a | 754 | object file is made writable, but a modification that doesn't change the file |
49ae7f09 | 755 | size will not. |
a46fd5b8 JR |
756 | * Programs that don't expect that files from two different identical |
757 | compilations are hard links to each other can fail. | |
63239e95 | 758 | * Programs that rely on modification times (like `make`) can be confused if |
a46fd5b8 JR |
759 | several users (or one user with several build trees) use the same cache |
760 | directory. The reason for this is that the object files share i-nodes and | |
63239e95 JR |
761 | therefore modification times. If `file.o` is in build tree *A* (hard-linked |
762 | from the cache) and `file.o` then is produced by ccache in build tree *B* by | |
a46fd5b8 | 763 | hard-linking from the cache, the modification timestamp will be updated for |
63239e95 JR |
764 | `file.o` in build tree *A* as well. This can retrigger relinking in build tree |
765 | *A* even though nothing really has changed. | |
a46fd5b8 | 766 | |
77035ead JR |
767 | [#config_hash_dir] |
768 | *hash_dir* (*CCACHE_HASHDIR* or *CCACHE_NOHASHDIR*, see _<<Boolean values>>_ above):: | |
46e577ed | 769 | |
6d9cb3df JR |
770 | If true (which is the default), ccache will include the current working |
771 | directory (CWD) in the hash that is used to distinguish two compilations | |
63239e95 | 772 | when generating debug info (compiler option `-g` with variations). |
9a817f74 JR |
773 | Exception: The CWD will not be included in the hash if |
774 | <<config_base_dir,*base_dir*>> is set (and matches the CWD) and the | |
63239e95 | 775 | compiler option `-fdebug-prefix-map` is used. See also the discussion under |
395c1c7f | 776 | _<<Compiling in different directories>>_. |
25b70699 | 777 | + |
0a212624 JR |
778 | The reason for including the CWD in the hash by default is to prevent a problem |
779 | with the storage of the current working directory in the debug info of an | |
780 | object file, which can lead ccache to return a cached object file that has the | |
781 | working directory in the debug info set incorrectly. | |
25b70699 | 782 | + |
74e3218a | 783 | You can disable this option to get cache hits when compiling the same source |
0a212624 JR |
784 | code in different directories if you don't mind that CWD in the debug info |
785 | might be incorrect. | |
46e577ed | 786 | |
77035ead JR |
787 | [#config_ignore_headers_in_manifest] |
788 | *ignore_headers_in_manifest* (*CCACHE_IGNOREHEADERS*):: | |
316cdda7 | 789 | |
74e3218a | 790 | This option is a list of paths to files (or directories with headers) that |
fdf11ff3 JR |
791 | ccache will *not* include in the manifest list that makes up the direct |
792 | mode. Note that this can cause stale cache hits if those headers do indeed | |
793 | change. The list separator is semicolon on Windows systems and colon on | |
794 | other systems. | |
316cdda7 | 795 | |
77035ead JR |
796 | [#config_ignore_options] |
797 | *ignore_options* (*CCACHE_IGNOREOPTIONS*):: | |
231fef47 | 798 | |
74e3218a | 799 | This option is a space-delimited list of compiler options that ccache will |
2737d79e JR |
800 | ignore. Entries in the list can optionally end with an asterisk (`*`) to |
801 | matching any option suffix. For example, `+-fmessage-length=*+` will match | |
802 | both `-fmessage-length=20` and `-fmessage-length=70`. A matching compiler | |
803 | option will neither be interpreted specially nor be part of the input hash. | |
804 | Ignoring a compiler option from the hash can be useful when you know it | |
805 | doesn't affect the result (and ccache doesn't know that), or when it does | |
806 | and you don't care. See also _<<Extra options>>_. | |
231fef47 | 807 | |
77035ead JR |
808 | [#config_inode_cache] |
809 | *inode_cache* (*CCACHE_INODECACHE* or *CCACHE_NOINODECACHE*, see _<<Boolean values>>_ above):: | |
213d9883 | 810 | |
bf935e13 JR |
811 | If true, ccache will cache source file hashes based on device, inode and |
812 | timestamps. This reduces the time spent on hashing include files since the | |
86bfec0d | 813 | result can be reused between compilations. The default is true. The feature |
bf935e13 JR |
814 | requires <<config_temporary_dir,*temporary_dir*>> to be located on a local |
815 | filesystem of a supported type. | |
213d9883 | 816 | + |
bf935e13 | 817 | NOTE: The inode cache feature is currently not available on Windows. |
213d9883 | 818 | |
77035ead JR |
819 | [#config_keep_comments_cpp] |
820 | *keep_comments_cpp* (*CCACHE_COMMENTS* or *CCACHE_NOCOMMENTS*, see _<<Boolean values>>_ above):: | |
acc96bc6 AB |
821 | |
822 | If true, ccache will not discard the comments before hashing preprocessor | |
157a18f2 JR |
823 | output. The default is false. This can be used to check documentation with |
824 | `-Wdocumentation`. | |
acc96bc6 | 825 | |
77035ead JR |
826 | [#config_log_file] |
827 | *log_file* (*CCACHE_LOGFILE*):: | |
46e577ed | 828 | |
99396f88 JR |
829 | If set to a file path, ccache will write information on what it is doing to |
830 | the specified file. This is useful for tracking down problems. | |
85ed7f1e | 831 | + |
866372c9 JR |
832 | If set to *syslog*, ccache will log using `syslog()` instead of to a file. If |
833 | you use rsyslogd, you can add something like this to `/etc/rsyslog.conf` or a | |
834 | file in `/etc/rsyslog.d`: | |
85ed7f1e AB |
835 | + |
836 | ------------------------------------------------------------------------------- | |
837 | # log ccache to file | |
838 | :programname, isequal, "ccache" /var/log/ccache | |
839 | # remove from syslog | |
840 | & ~ | |
841 | ------------------------------------------------------------------------------- | |
46e577ed | 842 | |
77035ead JR |
843 | [#config_max_files] |
844 | *max_files* (*CCACHE_MAXFILES*):: | |
380d473f JR |
845 | |
846 | This option specifies the maximum number of files to keep in the cache. Use | |
44766b29 | 847 | 0 for no limit (which is the default). See also _<<Cache size management>>_. |
380d473f | 848 | |
77035ead JR |
849 | [#config_max_size] |
850 | *max_size* (*CCACHE_MAXSIZE*):: | |
380d473f | 851 | |
44766b29 JR |
852 | This option specifies the maximum size of the cache. Use 0 for no limit. The |
853 | default value is 5G. Available suffixes: k, M, G, T (decimal) and Ki, Mi, | |
854 | Gi, Ti (binary). The default suffix is G. See also | |
395c1c7f | 855 | _<<Cache size management>>_. |
380d473f | 856 | |
b1348e5f OS |
857 | [#config_msvc_dep_prefix] |
858 | *msvc_dep_prefix* (*CCACHE_MSVC_DEP_PREFIX*):: | |
859 | ||
860 | This option specifies the prefix of included files output for MSVC compiler. | |
7d679310 JR |
861 | The default prefix is "`Note: including file:`". If you use a localized |
862 | compiler, this should be set accordingly. | |
b1348e5f | 863 | |
9217417c JR |
864 | [#config_namespace] |
865 | *namespace* (*CCACHE_NAMESPACE*):: | |
866 | ||
867 | If set, the namespace string will be added to the hashed data for each | |
868 | compilation. This will make the associated cache entries logically separate | |
869 | from cache entries with other namespaces, but they will still share the same | |
0cd6f70b JR |
870 | storage space. Cache entries can also be selectively removed from the local |
871 | cache with the command line option `--evict-namespace`, potentially in | |
872 | combination with `--evict-older-than`. | |
46d52d4c | 873 | + |
0cd6f70b | 874 | For instance, if you use the same local cache for several disparate projects, |
9217417c | 875 | you can use a unique namespace string for each one. This allows you to remove |
46d52d4c | 876 | cache entries that belong to a certain project if you stop working with that |
9217417c JR |
877 | project. |
878 | ||
77035ead JR |
879 | [#config_path] |
880 | *path* (*CCACHE_PATH*):: | |
46e577ed | 881 | |
99396f88 JR |
882 | If set, ccache will search directories in this list when looking for the |
883 | real compiler. The list separator is semicolon on Windows systems and colon | |
884 | on other systems. If not set, ccache will look for the first executable | |
63239e95 | 885 | matching the compiler name in the normal `PATH` that isn't a symbolic link |
99396f88 | 886 | to ccache itself. |
46e577ed | 887 | |
77035ead JR |
888 | [#config_pch_external_checksum] |
889 | *pch_external_checksum* (*CCACHE_PCH_EXTSUM* or *CCACHE_NOPCH_EXTSUM*, see _<<Boolean values>>_ above):: | |
27cac6ff GK |
890 | |
891 | When this option is set, and ccache finds a precompiled header file, | |
63239e95 JR |
892 | ccache will look for a file with the extension "`.sum`" added |
893 | (e.g. "`pre.h.gch.sum`"), and if found, it will hash this file instead | |
8f0b477b GK |
894 | of the precompiled header itself to work around the performance |
895 | penalty of hashing very large files. | |
27cac6ff | 896 | |
77035ead JR |
897 | [#config_prefix_command] |
898 | *prefix_command* (*CCACHE_PREFIX*):: | |
46e577ed | 899 | |
44766b29 JR |
900 | This option adds a list of prefixes (separated by space) to the command line |
901 | that ccache uses when invoking the compiler. See also | |
395c1c7f | 902 | _<<Using ccache with other compiler wrappers>>_. |
46e577ed | 903 | |
77035ead JR |
904 | [#config_prefix_command_cpp] |
905 | *prefix_command_cpp* (*CCACHE_PREFIX_CPP*):: | |
3fbd2004 AB |
906 | |
907 | This option adds a list of prefixes (separated by space) to the command | |
908 | line that ccache uses when invoking the preprocessor. | |
909 | ||
77035ead JR |
910 | [#config_read_only] |
911 | *read_only* (*CCACHE_READONLY* or *CCACHE_NOREADONLY*, see _<<Boolean values>>_ above):: | |
46e577ed | 912 | |
6b8db0e2 | 913 | If true, ccache will attempt to use existing cached results, but it will not |
2b3368cf JR |
914 | add new results to any cache backend. Statistics counters will still be |
915 | updated, though, unless the <<config_stats,*stats*>> option is set to | |
916 | *false*. | |
6b8db0e2 JR |
917 | + |
918 | If you are using this because your ccache directory is read-only, you need to | |
919 | set <<config_temporary_dir,*temporary_dir*>> since ccache will fail to create | |
920 | temporary files otherwise. You may also want to set <<config_stats,*stats*>> to | |
921 | *false* make ccache not even try to update stats files. | |
46e577ed | 922 | |
77035ead JR |
923 | [#config_read_only_direct] |
924 | *read_only_direct* (*CCACHE_READONLY_DIRECT* or *CCACHE_NOREADONLY_DIRECT*, see _<<Boolean values>>_ above):: | |
c6bd92b5 | 925 | |
9a817f74 JR |
926 | Just like <<config_read_only,*read_only*>> except that ccache will only try |
927 | to retrieve results from the cache using the direct mode, not the | |
928 | preprocessor mode. See documentation for <<config_read_only,*read_only*>> | |
929 | regarding using a read-only ccache directory. | |
c6bd92b5 | 930 | |
77035ead JR |
931 | [#config_recache] |
932 | *recache* (*CCACHE_RECACHE* or *CCACHE_NORECACHE*, see _<<Boolean values>>_ above):: | |
46e577ed | 933 | |
99396f88 JR |
934 | If true, ccache will not use any previously stored result. New results will |
935 | still be cached, possibly overwriting any pre-existing results. | |
46e577ed | 936 | |
d5782080 JR |
937 | [#config_remote_only] |
938 | *remote_only* (*CCACHE_REMOTE_ONLY* or *CCACHE_NOREMOTE_ONLY*, see _<<Boolean values>>_ above):: | |
939 | ||
940 | If true, ccache will only use <<config_remote_storage,remote storage>>. The | |
941 | default is false. Note that cache statistics counters will still be kept in | |
d1ce89cf JR |
942 | the local cache directory unless <<config_stats,*stats*>> is false. See also |
943 | _<<Storage interaction>>_. | |
d5782080 | 944 | |
0cd6f70b JR |
945 | [#config_remote_storage] |
946 | *remote_storage* (*CCACHE_REMOTE_STORAGE*):: | |
947 | ||
948 | This option specifies one or several storage backends (separated by space) | |
d5782080 | 949 | to query after checking the local cache (unless |
320e2ea6 JR |
950 | <<config_remote_only,*remote_only*>> is true). See |
951 | _<<Remote storage backends>>_ for documentation of syntax and available | |
952 | backends. | |
0cd6f70b JR |
953 | + |
954 | Examples: | |
955 | + | |
956 | * `+file:/shared/nfs/directory+` | |
957 | * `+file:///shared/nfs/one|read-only file:///shared/nfs/two+` | |
f0026966 | 958 | * `+file:///Z:/example/windows/folder+` |
0cd6f70b JR |
959 | * `+http://example.com/cache+` |
960 | * `+redis://example.com+` | |
961 | + | |
962 | NOTE: In previous ccache versions this option was called *secondary_storage* | |
963 | (*CCACHE_SECONDARY_STORAGE*), which can still be used as an alias. | |
964 | ||
9af44de3 JR |
965 | [#config_reshare] |
966 | *reshare* (*CCACHE_RESHARE* or *CCACHE_NORESHARE*, see _<<Boolean values>>_ above):: | |
967 | ||
0cd6f70b JR |
968 | If true, ccache will write results to remote storage even for local storage |
969 | cache hits. The default is false. | |
9af44de3 | 970 | |
77035ead JR |
971 | [#config_run_second_cpp] |
972 | *run_second_cpp* (*CCACHE_CPP2* or *CCACHE_NOCPP2*, see _<<Boolean values>>_ above):: | |
46e577ed | 973 | |
eb3148ca | 974 | If true, ccache will first run the preprocessor to preprocess the source |
44766b29 JR |
975 | code (see _<<The preprocessor mode>>_) and then on a cache miss run the |
976 | compiler on the source code to get hold of the object file. This is the | |
977 | default. | |
984f4e18 JR |
978 | + |
979 | If false, ccache will first run preprocessor to preprocess the source code and | |
980 | then on a cache miss run the compiler on the _preprocessed source code_ instead | |
981 | of the original source code. This makes cache misses slightly faster since the | |
982 | source code only has to be preprocessed once. The downside is that some | |
983 | compilers won't produce the same result (for instance diagnostics warnings) | |
984 | when compiling preprocessed source code. | |
87592156 | 985 | + |
79f26d97 | 986 | A solution to the above mentioned downside is to set *run_second_cpp* to false |
63239e95 | 987 | and pass `-fdirectives-only` (for GCC) or `-frewrite-includes` (for Clang) to |
79f26d97 JR |
988 | the compiler. This will cause the compiler to leave the macros and other |
989 | preprocessor information, and only process the *#include* directives. When run | |
990 | in this way, the preprocessor arguments will be passed to the compiler since it | |
991 | still has to do _some_ preprocessing (like macros). | |
543a919a LL |
992 | + |
993 | This option is ignored with MSVC, as there is no way to make it compile without | |
994 | preprocessing first. | |
46e577ed | 995 | |
77035ead JR |
996 | [#config_sloppiness] |
997 | *sloppiness* (*CCACHE_SLOPPINESS*):: | |
eb5d9bd3 JR |
998 | |
999 | By default, ccache tries to give as few false cache hits as possible. | |
1000 | However, in certain situations it's possible that you know things that | |
74e3218a | 1001 | ccache can't take for granted. This option makes it possible to tell |
99396f88 | 1002 | ccache to relax some checks in order to increase the hit rate. The value |
74e3218a JR |
1003 | should be a comma-separated string with one or several of the following |
1004 | values: | |
d7d80b8a JR |
1005 | + |
1006 | -- | |
8081d5ec | 1007 | *clang_index_store*:: |
63239e95 | 1008 | Ignore the Clang compiler option `-index-store-path` and its argument when |
8081d5ec JR |
1009 | computing the manifest hash. This is useful if you use Xcode, which uses an |
1010 | index store path derived from the local project path. Note that the index | |
74e3218a JR |
1011 | store won't be updated correctly on cache hits if you enable this |
1012 | sloppiness. | |
c0b40b8b | 1013 | *file_stat_matches*:: |
a684bb35 | 1014 | Ccache normally examines a file's contents to determine whether it matches |
74e3218a JR |
1015 | the cached version. With this sloppiness set, ccache will consider a file |
1016 | as matching its cached version if the mtimes and ctimes match. | |
f7085d62 | 1017 | *file_stat_matches_ctime*:: |
da4a536f JR |
1018 | Ignore ctimes when *file_stat_matches* is enabled. This can be useful when |
1019 | backdating files' mtimes in a controlled way. | |
492f3e4a JR |
1020 | *gcno_cwd*:: |
1021 | By default, ccache will include the current working directory in the hash | |
1022 | when producing a `.gcno` file (when compiling with `-ftest-coverage` or | |
1023 | `--coverage`). This is because GCC 9+ includes the current working directory | |
1024 | in the `.gcno` file. The *gcno_cwd* sloppiness makes ccache not hash the | |
1025 | current working directory so that you can get cache hits when compiling in | |
1026 | different directories, with the tradeoff of potentially getting an incorrect | |
195011ad JR |
1027 | directory in the `.gcno` file. *gcno_cwd* also disables hashing of the |
1028 | current working directory if `-fprofile-abs-path` is used. | |
290a8b44 | 1029 | *include_file_ctime*:: |
d75dbe26 JR |
1030 | By default, ccache will disable caching if a source code file has a status |
1031 | change time (ctime) after the start of the ccache invocation. This | |
1032 | sloppiness disables that check. See also _<<Handling of newly created source | |
1033 | files>>_. | |
d7d80b8a | 1034 | *include_file_mtime*:: |
d75dbe26 JR |
1035 | By default, ccache will disable caching if a source code file has a |
1036 | modification time (mtime) after the start of the ccache invocation. This | |
1037 | sloppiness disables that check. See also _<<Handling of newly created source | |
1038 | files>>_. | |
f76a3c8a | 1039 | *ivfsoverlay*:: |
63239e95 | 1040 | Ignore the Clang compiler option `-ivfsoverlay` and its argument. This is |
f76a3c8a JR |
1041 | useful if you use Xcode, which uses a virtual file system (VFS) for things |
1042 | like combining Objective-C and Swift code. | |
1e800ef2 | 1043 | *locale*:: |
63239e95 JR |
1044 | Ccache includes the environment variables `LANG`, `LC_ALL`, `LC_CTYPE` and |
1045 | `LC_MESSAGES` in the hash by default since they may affect localization of | |
74e3218a JR |
1046 | compiler warning messages. Set this sloppiness to tell ccache not to do |
1047 | that. | |
3eb2483f | 1048 | *modules*:: |
63239e95 | 1049 | By default, ccache will not cache compilations if `-fmodules` is used since |
3eb2483f | 1050 | it cannot hash the state of compiler's internal representation of relevant |
74e3218a | 1051 | modules. This sloppiness allows caching in such a case. See |
395c1c7f | 1052 | _<<C++ modules>>_ for more information. |
c20043d9 JR |
1053 | *pch_defines*:: |
1054 | Be sloppy about `#define` directives when precompiling a header file. See | |
1055 | _<<Precompiled headers>>_ for more information. | |
1056 | *random_seed*:: | |
1057 | Ignore the `-frandom-seed` option and its arguments when computing the input | |
1058 | hash. This is useful if your build system generates different seeds between | |
1059 | builds and you are OK with reusing cached results. | |
198aceec | 1060 | *system_headers*:: |
c7d98a0e JR |
1061 | Only check non-system headers in direct mode. |
1062 | This can be useful if e.g. your system headers tend to change but you know that | |
1063 | the changes don't matter. Notes: | |
1064 | + | |
1065 | * This sloppiness is only supported for GCC-like compilers, not MSVC. | |
1066 | * System headers are still taken into account for preprocessed lookup. | |
1067 | * You can get stale cache hits if the system headers do change in incompatible | |
1068 | ways. | |
1069 | * See also the | |
1070 | <<config_ignore_headers_in_manifest,*ignore_headers_in_manifest*>> setting. | |
d7d80b8a | 1071 | *time_macros*:: |
63239e95 | 1072 | Ignore `+__DATE__+`, `+__TIME__+` and `+__TIMESTAMP__+` being present in the |
cad24162 | 1073 | source code. |
d7d80b8a JR |
1074 | -- |
1075 | + | |
44766b29 | 1076 | See the discussion under _<<Troubleshooting>>_ for more information. |
eb5d9bd3 | 1077 | |
77035ead JR |
1078 | [#config_stats] |
1079 | *stats* (*CCACHE_STATS* or *CCACHE_NOSTATS*, see _<<Boolean values>>_ above):: | |
d7f24614 | 1080 | |
965f0453 JR |
1081 | If true, ccache will update the statistics counters on each compilation. The |
1082 | default is true. If false, _<<automatic cleanup>>_ will be disabled as well. | |
d7f24614 | 1083 | |
77035ead JR |
1084 | [#config_stats_log] |
1085 | *stats_log* (*CCACHE_STATSLOG*):: | |
fe22a1de AB |
1086 | |
1087 | If set to a file path, ccache will write statistics counter updates to the | |
1088 | specified file. This is useful for getting statistics for individual builds. | |
99fe3e04 | 1089 | To show a summary of the current stats log, use `ccache --show-log-stats`. |
fe22a1de AB |
1090 | + |
1091 | NOTE: Lines in the stats log starting with a hash sign (`#`) are comments. | |
1092 | ||
77035ead JR |
1093 | [#config_temporary_dir] |
1094 | *temporary_dir* (*CCACHE_TEMPDIR*):: | |
46e577ed | 1095 | |
74e3218a | 1096 | This option specifies where ccache will put temporary files. The default is |
876509ae JR |
1097 | `$XDG_RUNTIME_DIR/ccache-tmp` (typically `/run/user/<UID>/ccache-tmp`) if |
1098 | `XDG_RUNTIME_DIR` is set and the directory exists, otherwise | |
63239e95 | 1099 | `<cache_dir>/tmp`. |
112c7452 JR |
1100 | + |
1101 | NOTE: In previous versions of ccache, *CCACHE_TEMPDIR* had to be on the same | |
63239e95 | 1102 | filesystem as the `CCACHE_DIR` path, but this requirement has been relaxed. |
46e577ed | 1103 | |
77035ead JR |
1104 | [#config_umask] |
1105 | *umask* (*CCACHE_UMASK*):: | |
46e577ed | 1106 | |
a28c7ba5 JR |
1107 | This option (an octal integer) specifies the umask for files and directories |
1108 | in the cache directory. This is mostly useful when you wish to share your | |
1109 | cache with other users. | |
46e577ed | 1110 | |
46e577ed | 1111 | |
b3c3e799 JR |
1112 | === Disabling ccache |
1113 | ||
1114 | To disable ccache completely for all invocations, set <<config_disable,*disable | |
1115 | = true*>> (`CCACHE_DISABLE=1`). You can also disable ccache for a certain source | |
1116 | code file by adding the string `ccache:disable` in a comment in the first 4096 | |
1117 | bytes of the file. In the latter case the `Ccache disabled` statistics counter | |
1118 | will be increased. | |
1119 | ||
1120 | ||
0cd6f70b | 1121 | == Remote storage backends |
2b3368cf | 1122 | |
0cd6f70b | 1123 | The <<config_remote_storage,*remote_storage*>> option lets you configure ccache |
d5782080 JR |
1124 | to use one or several remote storage backends. By default, the local cache |
1125 | directory located in <<config_cache_dir,*cache_dir*>> will be queried first and | |
1126 | remote storage second, but <<config_remote_only,*remote_only*>> can be set to | |
1127 | true to disable local storage. Note that cache statistics counters will still be | |
1128 | kept in the local cache directory -- remote storage backends only store | |
1129 | compilation results and manifests. | |
2b3368cf | 1130 | |
0cd6f70b JR |
1131 | A remote storage backend is specified with a URL, optionally followed by a pipe |
1132 | (`|`) and a pipe-separated list of attributes. An attribute is _key_=_value_ or | |
1133 | just _key_ as a short form of _key_=*true*. Attribute values must be | |
1134 | https://en.wikipedia.org/wiki/Percent-encoding[percent-encoded] if they contain | |
1135 | percent, pipe or space characters. | |
2b3368cf | 1136 | |
43900aed JR |
1137 | === Attributes for all backends |
1138 | ||
0cd6f70b | 1139 | These optional attributes are available for all remote storage backends: |
2b3368cf JR |
1140 | |
1141 | * *read-only*: If *true*, only read from this backend, don't write. The default | |
1142 | is *false*. | |
4b8f8249 JR |
1143 | * *shards*: A comma-separated list of names for sharding (partitioning) the |
1144 | cache entries using | |
1145 | https://en.wikipedia.org/wiki/Rendezvous_hashing[Rendezvous hashing], | |
1146 | typically to spread the cache over a server cluster. When set, the storage URL | |
1147 | must contain an asterisk (`+*+`), which will be replaced by one of the shard | |
1148 | names to form a real URL. A shard name can optionally have an appended weight | |
1149 | within parentheses to indicate how much of the key space should be associated | |
1150 | with that shard. A shard with weight *w* will contain *w*/*S* of the cache, | |
1151 | where *S* is the sum of all shard weights. A weight could for instance be set | |
1152 | to represent the available memory for a memory cache on a specific server. The | |
1153 | default weight is *1*. | |
1154 | + | |
1155 | Examples: | |
1156 | + | |
1157 | -- | |
1158 | * `+redis://cache-*.example.com|shards=a(3),b(1),c(1.5)+` will put 55% (3/5.5) | |
1159 | of the cache on `+redis://cache-a.example.com+`, 18% (1/5.5) on | |
1160 | `+redis://cache-b.example.com+` and 27% (1.5/5.5) on | |
1161 | `+redis://cache-c.example.com+`. | |
1162 | * `+http://example.com/*|shards=alpha,beta+` will put 50% of the cache on | |
1163 | `+http://example.com/alpha+` and 50% on `+http://example.com/beta+`. | |
1164 | -- | |
2b3368cf | 1165 | |
43900aed JR |
1166 | |
1167 | === Storage interaction | |
1168 | ||
0cd6f70b | 1169 | The table below describes the interaction between local and remote storage on |
d5782080 JR |
1170 | cache hits and misses if <<config_remote_only,*remote_only*>> is false (which is |
1171 | the default): | |
43900aed JR |
1172 | |
1173 | [options="header",cols="20%,20%,60%"] | |
1174 | |============================================================================== | |
0cd6f70b | 1175 | | *Local storage* | *Remote storage* | *What happens* |
43900aed | 1176 | |
0cd6f70b JR |
1177 | | miss | miss | Compile, write to local, write to remote^[1]^ |
1178 | | miss | hit | Read from remote, write to local | |
1179 | | hit | - | Read from local, don't write to remote^[2]^ | |
43900aed JR |
1180 | |
1181 | |============================================================================== | |
1182 | ||
0cd6f70b JR |
1183 | ^[1]^ Unless remote storage has attribute `read-only=true`. + |
1184 | ^[2]^ Unless local storage is set to share its cache hits with the | |
43900aed JR |
1185 | <<config_reshare,*reshare*>> option. |
1186 | ||
d5782080 JR |
1187 | If <<config_remote_only,*remote_only*>> is true: |
1188 | ||
1189 | [options="header",cols="20%,20%,60%"] | |
1190 | |============================================================================== | |
1191 | | *Local storage* | *Remote storage* | *What happens* | |
1192 | ||
1193 | | - | miss | Compile, write to remote, don't write to local | |
1194 | | - | hit | Read from remote, don't write to local | |
1195 | ||
1196 | |============================================================================== | |
f8789e2f JR |
1197 | |
1198 | === File storage backend | |
1199 | ||
cc5c7837 | 1200 | URL format: `+file:DIRECTORY+` or `+file://[HOST]DIRECTORY+` |
f8789e2f JR |
1201 | |
1202 | This backend stores data as separate files in a directory structure below | |
0cd6f70b | 1203 | *DIRECTORY*, similar (but not identical) to the local cache storage. A typical |
cc5c7837 JR |
1204 | use case for this backend would be sharing a cache on an NFS directory. |
1205 | *DIRECTORY* must start with a slash. *HOST* can be the empty string or | |
1206 | localhost. On Windows, *HOST* can also be the name of a server hosting a shared | |
1207 | folder. | |
a358033b JR |
1208 | |
1209 | IMPORTANT: ccache will not perform any cleanup of the storage -- that has to be | |
1210 | done by other means, for instance by running `ccache --trim-dir` periodically. | |
f8789e2f JR |
1211 | |
1212 | Examples: | |
1213 | ||
63239e95 JR |
1214 | * `+file:/shared/nfs/directory+` |
1215 | * `+file:///shared/nfs/directory|umask=002|update-mtime=true+` | |
f0026966 | 1216 | * `+file:///Z:/example/windows/folder+` |
a25633df | 1217 | * `+file://example.com/shared/ccache%20folder+` |
f8789e2f JR |
1218 | |
1219 | Optional attributes: | |
1220 | ||
13c0ef12 JR |
1221 | * *layout*: How to store file under the cache directory. Available values: |
1222 | + | |
1223 | -- | |
1224 | * *flat*: Store all files directly under the cache directory. | |
1225 | * *subdirs*: Store files in 256 subdirectories of the cache directory. | |
1226 | -- | |
1227 | + | |
1228 | The default is *subdirs*. | |
f8789e2f JR |
1229 | * *umask*: This attribute (an octal integer) overrides the umask to use for |
1230 | files and directories in the cache directory. | |
1231 | * *update-mtime*: If *true*, update the modification time (mtime) of cache | |
1232 | entries that are read. The default is *false*. | |
1233 | ||
54480f02 | 1234 | |
a28ad9db GJ |
1235 | === HTTP storage backend |
1236 | ||
63239e95 | 1237 | URL format: `+http://HOST[:PORT][/PATH]+` |
a28ad9db | 1238 | |
ccb9e7ab JR |
1239 | This backend stores data in an HTTP-compatible server. The required HTTP methods |
1240 | are `GET`, `PUT` and `DELETE`. | |
a28ad9db | 1241 | |
a358033b JR |
1242 | IMPORTANT: ccache will not perform any cleanup of the storage -- that has to be |
1243 | done by other means, for instance by running `ccache --trim-dir` periodically. | |
a32fa2ad JR |
1244 | |
1245 | NOTE: HTTPS is not supported. | |
1246 | ||
1247 | TIP: See https://ccache.dev/howto/http-storage.html[How to set up HTTP storage] | |
1248 | for hints on how to set up an HTTP server for use with ccache. | |
a28ad9db GJ |
1249 | |
1250 | Examples: | |
1251 | ||
fc5945d4 JR |
1252 | * `+http://localhost+` |
1253 | * `+http://someusername:p4ssw0rd@example.com/cache/+` | |
1254 | * `+http://localhost:8080|layout=bazel|connect-timeout=50+` | |
a28ad9db | 1255 | |
28e77f33 GJ |
1256 | Optional attributes: |
1257 | ||
c6019a95 | 1258 | * *bearer-token*: Bearer token used to authorize the HTTP requests. |
28e77f33 | 1259 | * *connect-timeout*: Timeout (in ms) for network connection. The default is 100. |
a6231c54 | 1260 | * *keep-alive*: If *true*, keep the HTTP connection to the storage server open |
15fecbd7 | 1261 | to avoid reconnects. The default is *true*. |
fc5945d4 JR |
1262 | * *layout*: How to map key names to the path part of the URL. Available values: |
1263 | + | |
1264 | -- | |
1265 | * *bazel*: Store values in a format compatible with the Bazel HTTP caching | |
1266 | protocol. More specifically, the entries will be stored as 64 hex digits | |
1267 | under the `/ac/` part of the cache. | |
1268 | + | |
1269 | NOTE: You may have to disable verification of action cache values in the server | |
1270 | for this to work since ccache entries are not valid action result metadata | |
1271 | values. | |
21f1afba JR |
1272 | * *flat*: Append the key directly to the path part of the URL (with a leading |
1273 | slash if needed). | |
1274 | * *subdirs*: Append the first two characters of the key to the URL (with a | |
1275 | leading slash if needed), followed by a slash and the rest of the key. This | |
1276 | divides the entries into 256 buckets. | |
fc5945d4 JR |
1277 | -- |
1278 | + | |
21f1afba | 1279 | The default is *subdirs*. |
28e77f33 GJ |
1280 | * *operation-timeout*: Timeout (in ms) for HTTP requests. The default is 10000. |
1281 | ||
54480f02 | 1282 | |
1ef63482 AB |
1283 | === Redis storage backend |
1284 | ||
1b2ea8b8 JR |
1285 | URL formats: |
1286 | ||
1287 | `+redis://[[USERNAME:]PASSWORD@]HOST[:PORT][/DBNUMBER]+` + | |
1288 | `+redis+unix:SOCKET_PATH[?db=DBNUMBER]+` + | |
1289 | `+redis+unix://[[USERNAME:]PASSWORD@localhost]SOCKET_PATH[?db=DBNUMBER]+` | |
1ef63482 | 1290 | |
b1569ec8 JR |
1291 | This backend stores data in a https://redis.io[Redis] (or Redis-compatible) |
1292 | server. There are implementations for both memory-based and disk-based storage. | |
2de28734 | 1293 | *PORT* defaults to *6379* and *DBNUMBER* defaults to *0*. |
1ef63482 | 1294 | |
a32fa2ad | 1295 | NOTE: ccache will not perform any cleanup of the Redis storage, but you can |
b1569ec8 | 1296 | https://redis.io/topics/lru-cache[configure LRU eviction]. |
1ef63482 | 1297 | |
a32fa2ad JR |
1298 | TIP: See https://ccache.dev/howto/redis-storage.html[How to set up Redis |
1299 | storage] for hints on setting up a Redis server for use with ccache. | |
1300 | ||
4b8f8249 | 1301 | TIP: You can set up a cluster of Redis servers using the `shards` attribute |
0cd6f70b | 1302 | described in _<<Remote storage backends>>_. |
4b8f8249 | 1303 | |
1ef63482 AB |
1304 | Examples: |
1305 | ||
63239e95 JR |
1306 | * `+redis://localhost+` |
1307 | * `+redis://p4ssw0rd@cache.example.com:6379/0|connect-timeout=50+` | |
ac7e7cf6 AB |
1308 | * `+redis+unix:/run/redis.sock+` |
1309 | * `+redis+unix:///run/redis.sock+` | |
1b2ea8b8 | 1310 | * `+redis+unix://p4ssw0rd@localhost/run/redis.sock?db=0+` |
1ef63482 AB |
1311 | |
1312 | Optional attributes: | |
1313 | ||
b1569ec8 JR |
1314 | * *connect-timeout*: Timeout (in ms) for network connection. The default is 100. |
1315 | * *operation-timeout*: Timeout (in ms) for Redis commands. The default is 10000. | |
1ef63482 | 1316 | |
54480f02 | 1317 | |
1d63b123 | 1318 | == Cache size management |
46e577ed | 1319 | |
ab7407f7 | 1320 | By default, ccache has a 5 GB limit on the total size of files in the cache and |
74e3218a | 1321 | no limit on the number of files. You can set different limits using the command |
63239e95 JR |
1322 | line options `-M`/`--max-size` and `-F`/`--max-files`. Use the |
1323 | `-s`/`--show-stats` option to see the cache size and the currently configured | |
1324 | limits (in addition to other various statistics). | |
46e577ed | 1325 | |
8ec5a575 | 1326 | Cleanup can be triggered in two different ways: automatic and manual. |
ab7407f7 JR |
1327 | |
1328 | ||
1d63b123 | 1329 | === Automatic cleanup |
ab7407f7 | 1330 | |
defb83cc JR |
1331 | After a new compilation result has been written to the local cache, ccache will |
1332 | trigger an automatic cleanup if <<config_max_size,*max_size*>> or | |
1333 | <<config_max_files,*max_files*>> is exceeded. The cleanup removes cache entries | |
1334 | in LRU (least recently used) order based on the modification time (mtime) of | |
1335 | files in the cache. For this reason, ccache updates mtime of the cache files | |
1336 | read on a cache hit to mark them as recently used. | |
b1c37b33 | 1337 | |
ab7407f7 | 1338 | |
1d63b123 | 1339 | === Manual cleanup |
ab7407f7 | 1340 | |
defb83cc JR |
1341 | You can run `ccache -c/--cleanup` to force cleanup of the whole cache. This will |
1342 | recalculate the cache size information and also make sure that the cache size | |
1343 | does not exceed <<config_max_size,*max_size*>> and | |
1344 | <<config_max_files,*max_files*>>. | |
ab7407f7 | 1345 | |
46e577ed | 1346 | |
1d63b123 | 1347 | == Cache compression |
46e577ed | 1348 | |
a684bb35 | 1349 | Ccache will by default compress all data it puts into the cache using the |
fa21e965 JR |
1350 | compression algorithm http://zstd.net[Zstandard] (zstd) using compression level |
1351 | 1. The algorithm is fast enough that there should be little reason to turn off | |
1352 | compression to gain performance. One exception is if the cache is located on a | |
1353 | compressed file system, in which case the compression performed by ccache of | |
1354 | course is redundant. See the documentation for the configuration options | |
74e3218a JR |
1355 | <<config_compression,*compression*>> and |
1356 | <<config_compression_level,*compression_level*>> for more information. | |
46e577ed | 1357 | |
63239e95 | 1358 | You can use the command line option `-x`/`--show-compression` to print |
74e3218a | 1359 | information related to compression. Example: |
52e0e928 | 1360 | |
8884d0db | 1361 | ------------------------------------------------------------------------------- |
89c3f97d JR |
1362 | Total data: 14.8 GB (16.0 GB disk blocks) |
1363 | Compressed data: 11.3 GB (30.6% of original size) | |
1364 | Original size: 36.9 GB | |
1365 | Compression ratio: 3.267 x (69.4% space savings) | |
1366 | Incompressible data: 3.5 GB | |
8884d0db JR |
1367 | ------------------------------------------------------------------------------- |
1368 | ||
1369 | Notes: | |
1370 | ||
63239e95 | 1371 | * The "`disk blocks`" size is the cache size when taking disk block size into |
8892814e | 1372 | account. This value should match the "`Cache size`" value from "`ccache |
63239e95 JR |
1373 | --show-stats`". The other size numbers refer to actual content sizes. |
1374 | * "`Compressed data`" refers to result and manifest files stored in the cache. | |
1375 | * "`Incompressible data`" refers to files that are always stored uncompressed | |
74e3218a JR |
1376 | (triggered by enabling <<config_file_clone,*file_clone*>> or |
1377 | <<config_hard_link,*hard_link*>>) or unknown files (for instance files | |
1378 | created by older ccache versions). | |
1379 | * The compression ratio is affected by | |
1380 | <<config_compression_level,*compression_level*>>. | |
46e577ed | 1381 | |
d8e2ab9a | 1382 | The cache data can also be recompressed to another compression level (or made |
63239e95 | 1383 | uncompressed) with the command line option `-X`/`--recompress`. If you choose to |
74e3218a JR |
1384 | disable compression by default or to use a low compression level, you can |
1385 | (re)compress newly cached data with a higher compression level after the build | |
1386 | or at another time when there are more CPU cycles available, for instance every | |
1387 | night. Full recompression potentially takes a lot of time, but only files that | |
1388 | are currently compressed with a different level than the target level will be | |
d8e2ab9a JR |
1389 | recompressed. |
1390 | ||
1391 | ||
1d63b123 | 1392 | == Cache statistics |
ee624863 | 1393 | |
8892814e JR |
1394 | `ccache --show-stats` shows a summary of statistics, including cache size, |
1395 | cleanups (number of performed cleanups, either implicitly due to a cache size | |
1396 | limit being reached or due to explicit `ccache -c` calls), overall hit rate, hit | |
1397 | rate for <<The direct mode,direct>>/<<The preprocessor mode,preprocessed>> modes | |
0cd6f70b | 1398 | and hit rate for local and <<config_remote_storage,remote storage>>. |
8892814e JR |
1399 | |
1400 | The summary also includes counters called "`Errors`" and "`Uncacheable`", which | |
1401 | are sums of more detailed counters. To see those detailed counters, use the | |
1402 | `-v`/`--verbose` flag. The verbose mode can show the following counters: | |
ee624863 JR |
1403 | |
1404 | [options="header",cols="30%,70%"] | |
1405 | |============================================================================== | |
8892814e | 1406 | | *Counter* | *Description* |
63239e95 | 1407 | |
8892814e JR |
1408 | | Autoconf compile/link | |
1409 | Uncacheable compilation or linking by an Autoconf test. | |
ee624863 | 1410 | |
8892814e | 1411 | | Bad compiler arguments | |
74e3218a JR |
1412 | Malformed compiler argument, e.g. missing a value for a compiler option that |
1413 | requires an argument or failure to read a file specified by a compiler option | |
1414 | argument. | |
ee624863 | 1415 | |
8892814e | 1416 | | Called for linking | |
c35f2d94 | 1417 | The compiler was called for linking, not compiling. Ccache only supports |
63239e95 | 1418 | compilation of a single file, i.e. calling the compiler with the `-c` option to |
c35f2d94 | 1419 | produce a single object file from a single source file. |
ee624863 | 1420 | |
8892814e | 1421 | | Called for preprocessing | |
ee624863 JR |
1422 | The compiler was called for preprocessing, not compiling. |
1423 | ||
b3c3e799 JR |
1424 | | Ccache disabled | |
1425 | Ccache was disabled by a `ccache:disable` string in the source code file. | |
1426 | ||
8892814e | 1427 | | Could not use modules | |
395c1c7f | 1428 | Preconditions for using <<C++ modules>> were not fulfilled. |
3eb2483f | 1429 | |
8892814e JR |
1430 | | Could not use precompiled header | |
1431 | Preconditions for using <<Precompiled headers,precompiled headers>> were not | |
1432 | fulfilled. | |
ee624863 | 1433 | |
d75dbe26 JR |
1434 | | Could not read or parse input file | |
1435 | An input file could not be read or parsed (see the debug log for details). | |
1436 | ||
8892814e | 1437 | | Could not write to output file | |
e08af162 | 1438 | The output path specified with `-o` could not be written to. |
ee624863 | 1439 | |
8892814e | 1440 | | Compilation failed | |
ee624863 JR |
1441 | The compilation failed. No result stored in the cache. |
1442 | ||
8892814e | 1443 | | Compiler check failed | |
9a817f74 JR |
1444 | A compiler check program specified by |
1445 | <<config_compiler_check,*compiler_check*>> (*CCACHE_COMPILERCHECK*) failed. | |
ee624863 | 1446 | |
b53afeb5 JR |
1447 | | Compiler output file missing | |
1448 | One of the files expected to be produced by the compiler was missing after | |
ee624863 JR |
1449 | compilation. |
1450 | ||
b53afeb5 JR |
1451 | | Compiler produced empty output | |
1452 | The compiler's output file (typically an object file) was empty after | |
ee624863 JR |
1453 | compilation. |
1454 | ||
8892814e | 1455 | | Could not find the compiler | |
ee624863 JR |
1456 | The compiler to execute could not be found. |
1457 | ||
8892814e | 1458 | | Error hashing extra file | |
9a817f74 | 1459 | Failure reading a file specified by |
484320fd | 1460 | <<config_extra_files_to_hash,*extra_files_to_hash*>> (*CCACHE_EXTRAFILES*). |
ee624863 | 1461 | |
8892814e JR |
1462 | | Forced recache | |
1463 | <<config_recache,*CCACHE_RECACHE*>> was used to overwrite an existing result. | |
ee624863 | 1464 | |
d75dbe26 JR |
1465 | | Input file modified during compilation | |
1466 | An input file was modified during compilation. | |
1467 | ||
8892814e JR |
1468 | | Internal error | |
1469 | Unexpected failure, e.g. due to problems reading/writing the cache. | |
1470 | ||
1471 | | Missing cache file | | |
1472 | A file was unexpectedly missing from the cache. This only happens in rare | |
1473 | situations, e.g. if one ccache instance is about to get a file from the cache | |
1474 | while another instance removed the file as part of cache cleanup. | |
1475 | ||
1476 | | Multiple source files | | |
ee624863 JR |
1477 | The compiler was called to compile multiple source files in one go. This is not |
1478 | supported by ccache. | |
1479 | ||
8892814e | 1480 | | No input file | |
ee624863 JR |
1481 | No input file was specified to the compiler. |
1482 | ||
8892814e | 1483 | | Output to stdout | |
63239e95 JR |
1484 | The compiler was instructed to write its output to standard output using `-o -`. |
1485 | This is not supported by ccache. | |
ee624863 | 1486 | |
8892814e | 1487 | | Preprocessing failed | |
63239e95 | 1488 | Preprocessing the source code using the compiler's `-E` option failed. |
ee624863 | 1489 | |
8892814e | 1490 | | Unsupported code directive | |
63239e95 | 1491 | Code like the assembler `.incbin` directive was found. This is not supported |
ee624863 JR |
1492 | by ccache. |
1493 | ||
8892814e | 1494 | | Unsupported compiler option | |
ee624863 JR |
1495 | A compiler option not supported by ccache was found. |
1496 | ||
a2988ace JR |
1497 | | Unsupported environment variable | |
1498 | An environment variable not supported by ccache was set. | |
1499 | ||
8892814e | 1500 | | Unsupported source language | |
63239e95 | 1501 | A source language e.g. specified with `-x` was unsupported by ccache. |
ee624863 JR |
1502 | |
1503 | |============================================================================== | |
1504 | ||
1505 | ||
1d63b123 | 1506 | == How ccache works |
46e577ed JR |
1507 | |
1508 | The basic idea is to detect when you are compiling exactly the same code a | |
1509 | second time and reuse the previously produced output. The detection is done by | |
1510 | hashing different kinds of information that should be unique for the | |
a684bb35 | 1511 | compilation and then using the hash sum to identify the cached output. Ccache |
2a0dd8ef | 1512 | uses BLAKE3, a very fast cryptographic hash algorithm, for the hashing. On a |
6d76231f | 1513 | cache hit, ccache is able to supply all of the correct compiler outputs |
0a217f5e | 1514 | (including all warnings, dependency file, etc) from the cache. Data stored in |
5ca001a5 | 1515 | the cache is checksummed with XXH3, an extremely fast non-cryptographic |
0a217f5e | 1516 | algorithm, to detect corruption. |
46e577ed | 1517 | |
a684bb35 | 1518 | Ccache has two ways of gathering information used to look up results in the |
f8660b4e | 1519 | cache: |
46e577ed | 1520 | |
76b132d7 JR |
1521 | * the *preprocessor mode*, where ccache runs the preprocessor on the source |
1522 | code and hashes the result | |
faf7aacc JR |
1523 | * the *direct mode*, where ccache hashes the source code and include files |
1524 | directly | |
76b132d7 JR |
1525 | |
1526 | The direct mode is generally faster since running the preprocessor has some | |
1527 | overhead. | |
46e577ed | 1528 | |
44766b29 JR |
1529 | If no previous result is detected (i.e., there is a cache miss) using the direct |
1530 | mode, ccache will fall back to the preprocessor mode unless the *depend mode* is | |
1531 | enabled. In the depend mode, ccache never runs the preprocessor, not even on | |
1532 | cache misses. Read more in _<<The depend mode>>_ below. | |
f8660b4e | 1533 | |
46e577ed | 1534 | |
1d63b123 | 1535 | === Common hashed information |
18979c42 | 1536 | |
f8660b4e | 1537 | The following information is always included in the hash: |
18979c42 JR |
1538 | |
1539 | * the extension used by the compiler for a file with preprocessor output | |
63239e95 | 1540 | (normally `.i` for C code and `.ii` for C++ code) |
18979c42 | 1541 | * the compiler's size and modification time (or other compiler-specific |
74e3218a | 1542 | information specified by <<config_compiler_check,*compiler_check*>>) |
18979c42 | 1543 | * the name of the compiler |
74e3218a JR |
1544 | * the current directory (if <<config_hash_dir,*hash_dir*>> is enabled) |
1545 | * contents of files specified by | |
484320fd | 1546 | <<config_extra_files_to_hash,*extra_files_to_hash*>> (if any) |
18979c42 JR |
1547 | |
1548 | ||
1d63b123 | 1549 | === The preprocessor mode |
faf7aacc JR |
1550 | |
1551 | In the preprocessor mode, the hash is formed of the common information and: | |
1552 | ||
63239e95 JR |
1553 | * the preprocessor output from running the compiler with `-E` |
1554 | * the command line options except those that affect include files (`-I`, | |
1555 | `-include`, `-D`, etc; the theory is that these command line options will | |
74e3218a | 1556 | change the preprocessor output if they have any effect at all) |
faf7aacc JR |
1557 | * any standard error output generated by the preprocessor |
1558 | ||
1559 | Based on the hash, the cached compilation result can be looked up directly in | |
1560 | the cache. | |
1561 | ||
1562 | ||
1d63b123 | 1563 | === The direct mode |
46e577ed | 1564 | |
18979c42 | 1565 | In the direct mode, the hash is formed of the common information and: |
46e577ed | 1566 | |
246a65d4 | 1567 | * the input source file |
74e3218a | 1568 | * the compiler options |
46e577ed | 1569 | |
63239e95 | 1570 | Based on the hash, a data structure called "`manifest`" is looked up in the |
34c51f1c JR |
1571 | cache. The manifest contains: |
1572 | ||
1573 | * references to cached compilation results (object file, dependency file, etc) | |
1574 | that were produced by previous compilations that matched the hash | |
1575 | * paths to the include files that were read at the time the compilation results | |
1576 | were stored in the cache | |
1577 | * hash sums of the include files at the time the compilation results were | |
1578 | stored in the cache | |
1579 | ||
1580 | The current contents of the include files are then hashed and compared to the | |
1581 | information in the manifest. If there is a match, ccache knows the result of | |
1582 | the compilation. If there is no match, ccache falls back to running the | |
1583 | preprocessor. The output from the preprocessor is parsed to find the include | |
1584 | files that were read. The paths and hash sums of those include files are then | |
1585 | stored in the manifest along with information about the produced compilation | |
1586 | result. | |
46e577ed | 1587 | |
568ca993 JR |
1588 | There is a catch with the direct mode: header files that were used by the |
1589 | compiler are recorded, but header files that were *not* used, but would have | |
1590 | been used if they existed, are not. So, when ccache checks if a result can be | |
1591 | taken from the cache, it currently can't check if the existence of a new header | |
3f0569b3 JR |
1592 | file should invalidate the result. In practice, the direct mode is safe to use |
1593 | in the absolute majority of cases. | |
568ca993 | 1594 | |
46e577ed JR |
1595 | The direct mode will be disabled if any of the following holds: |
1596 | ||
74e3218a | 1597 | * <<config_direct_mode,*direct_mode*>> is false |
246a65d4 | 1598 | * a modification time of one of the include files is too new (needed to avoid a |
46e577ed | 1599 | race condition) |
ba303352 | 1600 | * a compiler option not supported by the direct mode is used: |
eb75cdaa JR |
1601 | ** a `-Wp,++*++` compiler option other than `-Wp,-MD,<path>`, `-Wp,-MMD,<path>`, |
1602 | `-Wp,-D<macro[=defn]>` or `-Wp,-U<macro>` | |
63239e95 JR |
1603 | ** `-Xpreprocessor` |
1604 | * the string `+__TIME__+` is present in the source code | |
46e577ed JR |
1605 | |
1606 | ||
1d63b123 | 1607 | === The depend mode |
60ced47f | 1608 | |
f8660b4e JR |
1609 | If the depend mode is enabled, ccache will not use the preprocessor at all. The |
1610 | hash used to identify results in the cache will be based on the direct mode | |
1611 | hash described above plus information about include files read from the | |
7d679310 | 1612 | dependency list generated by MSVC with `/showIncludes`, or the dependency file |
b1348e5f | 1613 | generated by other compilers with `-MD` or `-MMD`. |
60ced47f | 1614 | |
f8660b4e | 1615 | Advantages: |
60ced47f | 1616 | |
f8660b4e JR |
1617 | * The ccache overhead of a cache miss will be much smaller. |
1618 | * Not running the preprocessor at all can be good if compilation is performed | |
1619 | remotely, for instance when using distcc or similar; ccache then won't make | |
1620 | potentially costly preprocessor calls on the local machine. | |
60ced47f | 1621 | |
f8660b4e | 1622 | Disadvantages: |
60ced47f | 1623 | |
f8660b4e JR |
1624 | * The cache hit rate will likely be lower since any change to compiler options |
1625 | or source code will make the hash different. Compare this with the default | |
1626 | setup where ccache will fall back to the preprocessor mode, which is tolerant | |
1627 | to some types of changes of compiler options and source code changes. | |
f13b9a53 | 1628 | * If `-MD` is used, the manifest entries will include system header files as |
7d679310 JR |
1629 | well, thus slowing down cache hits slightly, just as using `-MD` slows down |
1630 | make. This is also the case for MSVC with `/showIncludes`. | |
1631 | * If `-MMD` is used, the manifest entries will not include system header files, | |
2f89ccfc | 1632 | which means ccache will ignore changes in them. |
60ced47f AB |
1633 | |
1634 | The depend mode will be disabled if any of the following holds: | |
1635 | ||
74e3218a JR |
1636 | * <<config_depend_mode,*depend_mode*>> is false. |
1637 | * <<config_run_second_cpp,*run_second_cpp*>> is false. | |
b1348e5f | 1638 | * The compiler is not generating dependencies using `-MD` or `-MMD` (for MSVC, |
7d679310 | 1639 | `/showIncludes` is added automatically if not specified by the user). |
f8660b4e | 1640 | |
2901c06d | 1641 | |
d75dbe26 | 1642 | == Handling of newly created source files |
5796e9b5 | 1643 | |
d75dbe26 JR |
1644 | If modification time (mtime) or status change time (ctime) of the source file or |
1645 | one of the include files is equal to (or newer than) the time that ccache was | |
1646 | invoked, ccache disables caching completely. This is done as a safety measure to | |
1647 | avoid a race condition (see below). In practice, this is only a problem when | |
1648 | using file systems with very low timestamp granularity. You can set | |
1649 | <<config_sloppiness,*sloppiness*>> to *include_file_ctime,include_file_mtime* to | |
1650 | opt out of the safety measure. | |
5796e9b5 JR |
1651 | |
1652 | For reference, the race condition mentioned above consists of these events: | |
1653 | ||
d75dbe26 JR |
1654 | 1. A source code file is read by ccache and added to the input hash. |
1655 | 2. The source code file is modified. | |
1656 | 3. The compiler is executed and reads the modified source code. | |
1657 | 4. Ccache stores the compiler output in the cache associated with the incorrect | |
1658 | key (based on the unmodified source code). | |
5796e9b5 JR |
1659 | |
1660 | ||
1d63b123 | 1661 | == Cache debugging |
e3dbefeb JR |
1662 | |
1663 | To find out what information ccache actually is hashing, you can enable the | |
74e3218a | 1664 | debug mode via the configuration option <<config_debug,*debug*>> or by setting |
63239e95 | 1665 | `CCACHE_DEBUG` in the environment. This can be useful if you are investigating |
9a817f74 | 1666 | why you don't get cache hits. Note that performance will be reduced slightly. |
e3dbefeb | 1667 | |
4c1a92a0 JR |
1668 | When the debug mode is enabled, ccache will create up to five additional files |
1669 | next to the object file: | |
e3dbefeb | 1670 | |
8c2e9f5d | 1671 | [options="header",cols="30%,10%,60%"] |
e3dbefeb | 1672 | |============================================================================== |
8c2e9f5d | 1673 | | *Filename* | *Debug level* | *Description* |
63239e95 | 1674 | |
8c2e9f5d | 1675 | | `<objectfile>.<timestamp>.ccache-input-c` | 2 | |
e3dbefeb JR |
1676 | Binary input hashed by both the direct mode and the preprocessor mode. |
1677 | ||
8c2e9f5d | 1678 | | `<objectfile>.<timestamp>.ccache-input-d` | 2 | |
e3dbefeb JR |
1679 | Binary input only hashed by the direct mode. |
1680 | ||
8c2e9f5d | 1681 | | `<objectfile>.<timestamp>.ccache-input-p` | 2 | |
e3dbefeb JR |
1682 | Binary input only hashed by the preprocessor mode. |
1683 | ||
8c2e9f5d | 1684 | | `<objectfile>.<timestamp>.ccache-input-text` | 2 | |
e3dbefeb JR |
1685 | Human-readable combined diffable text version of the three files above. |
1686 | ||
8c2e9f5d | 1687 | | `<objectfile>.<timestamp>.ccache-log` | 1 | |
e3dbefeb JR |
1688 | Log for this object file. |
1689 | ||
1690 | |============================================================================== | |
1691 | ||
8c2e9f5d | 1692 | The timestamp format is |
7c980edc JR |
1693 | `<year><month><day>_<hour><minute><second>_<microsecond>`. |
1694 | ||
8c2e9f5d JR |
1695 | |
1696 | If you only need the log file, set <<config_debug,*debug_level*>> (environment | |
1697 | variable `CCACHE_DEBUGLEVEL`) to 1. | |
f8faf9b4 | 1698 | |
a2d8fdf4 | 1699 | If <<config_debug_dir,*debug_dir*>> (environment variable `CCACHE_DEBUGDIR`) is |
a181d44d JR |
1700 | set, the files above will be written to that directory with full absolute paths |
1701 | instead of next to the object file. | |
1702 | ||
2a0dd8ef | 1703 | In the direct mode, ccache uses the 160 bit BLAKE3 hash of the |
63239e95 JR |
1704 | "`ccache-input-c`" + "`ccache-input-d`" data (where *+* means concatenation), |
1705 | while the "`ccache-input-c`" + "`ccache-input-p`" data is used in the | |
1706 | preprocessor mode. | |
e3dbefeb | 1707 | |
63239e95 JR |
1708 | The "`ccache-input-text`" file is a combined text version of the three binary |
1709 | input files. It has three sections ("`COMMON`", "`DIRECT MODE`" and | |
1710 | "`PREPROCESSOR MODE`"), which is turn contain annotations that say what kind of | |
e3dbefeb JR |
1711 | data comes next. |
1712 | ||
f6202db3 | 1713 | To debug why you don't get an expected cache hit for an object file, you can do |
e3dbefeb JR |
1714 | something like this: |
1715 | ||
7c980edc JR |
1716 | 1. Enable `debug` (`CCACHE_DEBUG`). |
1717 | 2. Build. | |
1718 | 3. Clean and build again. | |
1719 | 4. Compare the `<objectfile>.<timestamp>.ccache-input-text` files for the two | |
1720 | builds. This together with the `<objectfile>.<timestamp>.ccache-log` files | |
1721 | should give you some clues about what is happening. | |
e3dbefeb | 1722 | |
8c2e9f5d | 1723 | |
1d63b123 | 1724 | == Compiling in different directories |
2901c06d | 1725 | |
51d169e4 | 1726 | Some information included in the hash that identifies a unique compilation can |
2901c06d JR |
1727 | contain absolute paths: |
1728 | ||
1729 | * The preprocessed source code may contain absolute paths to include files if | |
63239e95 | 1730 | the compiler option `-g` is used or if absolute paths are given to `-I` and |
2901c06d | 1731 | similar compiler options. |
63239e95 | 1732 | * Paths specified by compiler options (such as `-I`, `-MF`, etc) on the command |
51d169e4 | 1733 | line may be absolute. |
3f26134a | 1734 | * The source code file path may be absolute, and that path may substituted for |
63239e95 | 1735 | `+__FILE__+` macros in the source code or included in warnings emitted to |
3f26134a | 1736 | standard error by the preprocessor. |
2901c06d JR |
1737 | |
1738 | This means that if you compile the same code in different locations, you can't | |
1739 | share compilation results between the different build directories since you get | |
1740 | cache misses because of the absolute build directory paths that are part of the | |
51d169e4 JR |
1741 | hash. |
1742 | ||
1743 | Here's what can be done to enable cache hits between different build | |
1744 | directories: | |
1745 | ||
63239e95 | 1746 | * If you build with `-g` (or similar) to add debug information to the object |
51d169e4 | 1747 | file, you must either: |
63239e95 JR |
1748 | ** use the compiler option `-fdebug-prefix-map=<old>=<new>` for relocating |
1749 | debug info to a common prefix (e.g. `-fdebug-prefix-map=$PWD=.`); or | |
51d169e4 | 1750 | ** set *hash_dir = false*. |
51d169e4 | 1751 | * If you use absolute paths anywhere on the command line (e.g. the source code |
63239e95 JR |
1752 | file path or an argument to compiler options like `-I` and `-MF`), you must |
1753 | set <<config_base_dir,*base_dir*>> to an absolute path to a "`base | |
1754 | directory`". Ccache will then rewrite absolute paths under that directory to | |
9a817f74 | 1755 | relative before computing the hash. |
46e577ed JR |
1756 | |
1757 | ||
1d63b123 | 1758 | == Precompiled headers |
d8927d46 | 1759 | |
682f58a0 JR |
1760 | Ccache has support for precompiled headers with GCC and Clang. However, you have |
1761 | to do some things to make it work properly: | |
7fd2b883 | 1762 | |
9a817f74 | 1763 | * You must set <<config_sloppiness,*sloppiness*>> to *pch_defines,time_macros*. |
63239e95 JR |
1764 | The reason is that ccache can't tell whether `+__TIME__+`, `+__DATE__+` or |
1765 | `+__TIMESTAMP__+` is used when using a precompiled header. Further, it can't | |
1766 | detect changes in ``#define``s in the source code because of how preprocessing | |
1767 | works in combination with precompiled headers. | |
5796e9b5 JR |
1768 | * You may also want to include *include_file_mtime,include_file_ctime* in |
1769 | <<config_sloppiness,*sloppiness*>>. See | |
d75dbe26 | 1770 | _<<Handling of newly created source files>>_. |
7fd2b883 JR |
1771 | * You must either: |
1772 | + | |
1773 | -- | |
63239e95 JR |
1774 | * use the compiler option `-include` to include the precompiled header (i.e., |
1775 | don't use `#include` in the source code to include the header; the filename | |
1776 | itself must be sufficient to find the header, i.e. `-I` paths are not | |
30fdd670 | 1777 | searched); or |
63239e95 | 1778 | * (for the Clang compiler) use the compiler option `-include-pch` to include |
8d9e955b | 1779 | the PCH file generated from the precompiled header; or |
63239e95 | 1780 | * (for the GCC compiler) add the compiler option `-fpch-preprocess` when |
30fdd670 | 1781 | compiling. |
63239e95 JR |
1782 | -- |
1783 | + | |
682f58a0 JR |
1784 | * If you use Clang, you must compile with `-fno-pch-timestamp`. |
1785 | ||
8892814e JR |
1786 | If you don't do this, either the non-precompiled version of the header file will |
1787 | be used (if available) or ccache will fall back to running the real compiler and | |
1788 | increase the statistics counter "`Preprocessing failed`" (if the non-precompiled | |
1789 | header file is not available). | |
d8927d46 JR |
1790 | |
1791 | ||
1d63b123 | 1792 | == C++ modules |
3eb2483f | 1793 | |
63239e95 JR |
1794 | Ccache has support for Clang's `-fmodules` option. In practice ccache only |
1795 | additionally hashes `module.modulemap` files; it does not know how Clang | |
74e3218a | 1796 | handles its cached binary form of modules so those are ignored. This should not |
63239e95 | 1797 | matter in practice: as long as everything else (including `module.modulemap` |
74e3218a JR |
1798 | files) is the same the cached result should work. Still, you must set |
1799 | <<config_sloppiness,*sloppiness*>> to *modules* to allow caching. | |
3eb2483f | 1800 | |
395c1c7f | 1801 | You must use both <<The direct mode,*direct mode*>> and |
44766b29 JR |
1802 | <<The depend mode,*depend mode*>>. When using |
1803 | <<The preprocessor mode,the preprocessor mode>> Clang does not provide enough | |
1804 | information to allow hashing of `module.modulemap` files. | |
3eb2483f LL |
1805 | |
1806 | ||
d1ce89cf | 1807 | == Sharing a local cache |
46e577ed | 1808 | |
d1ce89cf JR |
1809 | A group of developers can increase the cache hit rate by sharing a local cache |
1810 | directory. To share a local cache without unpleasant side effects, the following | |
46e577ed JR |
1811 | conditions should to be met: |
1812 | ||
99396f88 | 1813 | * Use the same cache directory. |
74e3218a | 1814 | * Make sure that the configuration option <<config_hard_link,*hard_link*>> is |
9a817f74 | 1815 | false (which is the default). |
99396f88 | 1816 | * Make sure that all users are in the same group. |
63239e95 | 1817 | * Set the configuration option <<config_umask,*umask*>> to *002*. This ensures |
9a817f74 | 1818 | that cached files are accessible to everyone in the group. |
46e577ed JR |
1819 | * Make sure that all users have write permission in the entire cache directory |
1820 | (and that you trust all users of the shared cache). | |
1821 | * Make sure that the setgid bit is set on all directories in the cache. This | |
1822 | tells the filesystem to inherit group ownership for new directories. The | |
25b70699 PP |
1823 | following command might be useful for this: |
1824 | + | |
25b70699 PP |
1825 | ---- |
1826 | find $CCACHE_DIR -type d | xargs chmod g+s | |
1827 | ---- | |
46e577ed | 1828 | |
a46fd5b8 JR |
1829 | The reason to avoid the hard link mode is that the hard links cause unwanted |
1830 | side effects, as all links to a cached file share the file's modification | |
1831 | timestamp. This results in false dependencies to be triggered by | |
1832 | timestamp-based build systems whenever another user links to an existing file. | |
1833 | Typically, users will see that their libraries and binaries are relinked | |
1834 | without reason. | |
1835 | ||
99396f88 JR |
1836 | You may also want to make sure that a base directory is set appropriately, as |
1837 | discussed in a previous section. | |
2901c06d JR |
1838 | |
1839 | ||
1d63b123 | 1840 | == Sharing a cache on NFS |
4ea12e1d JR |
1841 | |
1842 | It is possible to put the cache directory on an NFS filesystem (or similar | |
1843 | filesystems), but keep in mind that: | |
1844 | ||
1845 | * Having the cache on NFS may slow down compilation. Make sure to do some | |
1846 | benchmarking to see if it's worth it. | |
a684bb35 | 1847 | * Ccache hasn't been tested very thoroughly on NFS. |
4ea12e1d | 1848 | |
9a817f74 JR |
1849 | A tip is to set <<config_temporary_dir,*temporary_dir*>> to a directory on the |
1850 | local host to avoid NFS traffic for temporary files. | |
4ea12e1d | 1851 | |
293a9c8f JR |
1852 | It is recommended to use the same operating system version when using a shared |
1853 | cache. If operating system versions are different then system include files | |
1854 | will likely be different and there will be few or no cache hits between the | |
1855 | systems. One way of improving cache hit rate in that case is to set | |
1856 | <<config_sloppiness,*sloppiness*>> to *system_headers* to ignore system | |
1857 | headers. | |
1858 | ||
f8789e2f | 1859 | An alternative to putting the main cache directory on NFS is to set up a |
0cd6f70b | 1860 | <<config_remote_storage,remote storage>> file cache. |
f8789e2f | 1861 | |
4ea12e1d | 1862 | |
1d63b123 | 1863 | == Using ccache with other compiler wrappers |
2901c06d | 1864 | |
15edf502 | 1865 | The recommended way of combining ccache with another compiler wrapper (such as |
63239e95 | 1866 | "`distcc`") is by letting ccache execute the compiler wrapper. This is |
74e3218a | 1867 | accomplished by defining <<config_prefix_command,*prefix_command*>>, for |
63239e95 JR |
1868 | example by setting the environment variable `CCACHE_PREFIX` to the name of the |
1869 | wrapper (e.g. `distcc`). Ccache will then prefix the command line with the | |
74e3218a JR |
1870 | specified command when running the compiler. To specify several prefix |
1871 | commands, set <<config_prefix_command,*prefix_command*>> to a colon-separated | |
1872 | list of commands. | |
9a817f74 JR |
1873 | |
1874 | Unless you set <<config_compiler_check,*compiler_check*>> to a suitable command | |
63239e95 JR |
1875 | (see the description of that configuration option), it is not recommended to use |
1876 | the form `ccache anotherwrapper compiler args` as the compilation command. It's | |
1877 | also not recommended to use the masquerading technique for the other compiler | |
1878 | wrapper. The reason is that by default, ccache will in both cases hash the mtime | |
1879 | and size of the other wrapper instead of the real compiler, which means that: | |
2901c06d | 1880 | |
15edf502 JR |
1881 | * Compiler upgrades will not be detected properly. |
1882 | * The cached results will not be shared between compilations with and without | |
1883 | the other wrapper. | |
18cc772a | 1884 | |
9a817f74 JR |
1885 | Another minor thing is that if <<config_prefix_command,*prefix_command*>> is |
1886 | used, ccache will not invoke the other wrapper when running the preprocessor, | |
74e3218a JR |
1887 | which increases performance. You can use |
1888 | <<config_prefix_command_cpp,*prefix_command_cpp*>> if you also want to invoke | |
63239e95 | 1889 | the other wrapper when doing preprocessing (normally by adding `-E`). |
e7ce8336 | 1890 | |
46e577ed | 1891 | |
1d63b123 | 1892 | == Caveats |
614f764d | 1893 | |
3f0569b3 | 1894 | * The direct mode fails to pick up new header files in some rare scenarios. See |
395c1c7f | 1895 | _<<The direct mode>>_ above. |
614f764d | 1896 | |
a3787c4e | 1897 | |
1d63b123 | 1898 | == Troubleshooting |
a3787c4e | 1899 | |
1d63b123 | 1900 | === General |
a3787c4e JR |
1901 | |
1902 | A general tip for getting information about what ccache is doing is to enable | |
9a817f74 | 1903 | debug logging by setting the configuration option <<config_debug,*debug*>> (or |
395c1c7f OS |
1904 | the environment variable *CCACHE_DEBUG*); see _<<Cache debugging>>_ |
1905 | for more information. Another way of keeping track of what is | |
fa48770d | 1906 | happening is to check the output of *ccache -s*. |
a3787c4e JR |
1907 | |
1908 | ||
1d63b123 | 1909 | === Performance |
a3787c4e | 1910 | |
a684bb35 | 1911 | Ccache has been written to perform well out of the box, but sometimes you may |
a3787c4e JR |
1912 | have to do some adjustments of how you use the compiler and ccache in order to |
1913 | improve performance. | |
1914 | ||
1915 | Since ccache works best when I/O is fast, put the cache directory on a fast | |
1916 | storage device if possible. Having lots of free memory so that files in the | |
b0f4e626 | 1917 | cache directory stay in the disk cache is also preferable. |
a3787c4e | 1918 | |
63239e95 | 1919 | A good way of monitoring how well ccache works is to run `ccache -s` before and |
a3787c4e JR |
1920 | after your build and then compare the statistics counters. Here are some common |
1921 | problems and what may be done to increase the hit rate: | |
1922 | ||
8892814e JR |
1923 | * If the counter for preprocessed cache hits has been incremented instead of the |
1924 | one for direct cache hits, ccache has fallen back to preprocessor mode, which | |
1925 | is generally slower. Some possible reasons are: | |
2c1f49ca JR |
1926 | ** The source code has been modified in such a way that the preprocessor output |
1927 | is not affected. | |
816ec005 | 1928 | ** Compiler arguments that are hashed in the direct mode but not in the |
63239e95 | 1929 | preprocessor mode have changed (`-I`, `-include`, `-D`, etc) and they didn't |
816ec005 | 1930 | affect the preprocessor output. |
63239e95 JR |
1931 | ** The compiler option `-Xpreprocessor` or `-Wp,++*++` (except `-Wp,-MD,<path>`, |
1932 | `-Wp,-MMD,<path>`, and `-Wp,-D<define>`) is used. | |
74e3218a JR |
1933 | ** This was the first compilation with a new value of the |
1934 | <<config_base_dir,base directory>>. | |
d75dbe26 JR |
1935 | ** A modification or status change time of one of the include files is too new . |
1936 | See _<<Handling of newly created source files>>_. | |
63239e95 JR |
1937 | ** The `+__TIME__+` preprocessor macro is (potentially) being used. Ccache turns |
1938 | off direct mode if `+__TIME__+` is present in the source code. This is done | |
1939 | as a safety measure since the string indicates that a `+__TIME__+` macro | |
1940 | _may_ affect the output. (To be sure, ccache would have to run the | |
1941 | preprocessor, but the sole point of the direct mode is to avoid that.) If you | |
1942 | know that `+__TIME__+` isn't used in practise, or don't care if ccache | |
1943 | produces objects where `+__TIME__+` is expanded to something in the past, you | |
1944 | can set <<config_sloppiness,*sloppiness*>> to *time_macros*. | |
1945 | ** The `+__DATE__+` preprocessor macro is (potentially) being used and the date | |
1946 | has changed. This is similar to how `+__TIME__+` is handled. If `+__DATE__+` | |
1947 | is present in the source code, ccache hashes the current date in order to be | |
1948 | able to produce the correct object file if the `+__DATE__+` macro affects the | |
1949 | output. If you know that `+__DATE__+` isn't used in practise, or don't care | |
1950 | if ccache produces objects where `+__DATE__+` is expanded to something in the | |
9a817f74 | 1951 | past, you can set <<config_sloppiness,*sloppiness*>> to *time_macros*. |
63239e95 | 1952 | ** The `+__TIMESTAMP__+` preprocessor macro is (potentially) being used and the |
ffa82dd8 | 1953 | source file's modification time has changed. This is similar to how |
63239e95 | 1954 | `+__TIME__+` is handled. If `+__TIMESTAMP__+` is present in the source code, |
ffa82dd8 EF |
1955 | ccache hashes the string representation of the source file's modification |
1956 | time in order to be able to produce the correct object file if the | |
63239e95 JR |
1957 | `+__TIMESTAMP__+` macro affects the output. If you know that |
1958 | `+__TIMESTAMP__+` isn't used in practise, or don't care if ccache produces | |
1959 | objects where `+__TIMESTAMP__+` is expanded to something in the past, you can | |
1960 | set <<config_sloppiness,*sloppiness*>> to *time_macros*. | |
a684bb35 | 1961 | ** The input file path has changed. Ccache includes the input file path in the |
02bcef0d | 1962 | direct mode hash to be able to take relative include files into account and |
63239e95 | 1963 | to produce a correct object file if the source code includes a `+__FILE__+` |
02bcef0d | 1964 | macro. |
8892814e | 1965 | * If a cache hit counter was not incremented even though the same code has been |
f35a13cd JR |
1966 | compiled and cached before, ccache has either detected that something has |
1967 | changed anyway or a cleanup has been performed (either explicitly or | |
63239e95 JR |
1968 | implicitly when a cache limit has been reached). Some perhaps unobvious things |
1969 | that may result in a cache miss are usage of `+__TIME__+`, `+__DATE__+` or | |
1970 | `+__TIMESTAMP__+` macros, or use of automatically generated code that contains | |
ffa82dd8 | 1971 | a timestamp, build counter or other volatile information. |
8892814e JR |
1972 | * If "`Multiple source files`" has been incremented, it's an indication that the |
1973 | compiler has been invoked on several source code files at once. Ccache doesn't | |
1974 | support that. Compile the source code files separately if possible. | |
1975 | * If "`Unsupported compiler option`" has been incremented, enable debug logging | |
74e3218a | 1976 | and check which compiler option was rejected. |
8892814e | 1977 | * If "`Preprocessing failed`" has been incremented, one possible reason is that |
44766b29 JR |
1978 | precompiled headers are being used. See _<<Precompiled headers>>_ for how to |
1979 | remedy this. | |
8892814e | 1980 | * If "`Could not use precompiled header`" has been incremented, see |
395c1c7f | 1981 | _<<Precompiled headers>>_. |
8892814e | 1982 | * If "`Could not use modules`" has been incremented, see _<<C++ modules>>_. |
a3787c4e JR |
1983 | |
1984 | ||
1d63b123 | 1985 | === Corrupt object files |
39a7f839 JR |
1986 | |
1987 | It should be noted that ccache is susceptible to general storage problems. If a | |
1988 | bad object file sneaks into the cache for some reason, it will of course stay | |
1989 | bad. Some possible reasons for erroneous object files are bad hardware (disk | |
1990 | drive, disk controller, memory, etc), buggy drivers or file systems, a bad | |
9a817f74 JR |
1991 | <<config_prefix_command,*prefix_command*>> or compiler wrapper. If this |
1992 | happens, the easiest way of fixing it is this: | |
222ce68f JR |
1993 | |
1994 | 1. Build so that the bad object file ends up in the build tree. | |
1995 | 2. Remove the bad object file from the build tree. | |
63239e95 | 1996 | 3. Rebuild with `CCACHE_RECACHE` set. |
222ce68f | 1997 | |
63239e95 | 1998 | An alternative is to clear the whole cache with `ccache -C` if you don't mind |
222ce68f | 1999 | losing other cached results. |
39a7f839 JR |
2000 | |
2001 | There are no reported issues about ccache producing broken object files | |
2002 | reproducibly. That doesn't mean it can't happen, so if you find a repeatable | |
2003 | case, please report it. | |
a3787c4e JR |
2004 | |
2005 | ||
1d63b123 | 2006 | == More information |
46e577ed JR |
2007 | |
2008 | Credits, mailing list information, bug reporting instructions, source code, | |
0eac13a3 | 2009 | etc, can be found on ccache's web site: <https://ccache.dev>. |
46e577ed JR |
2010 | |
2011 | ||
1d63b123 | 2012 | == Author |
46e577ed | 2013 | |
a684bb35 | 2014 | Ccache was originally written by Andrew Tridgell and is currently developed and |
4aaa6a15 | 2015 | maintained by Joel Rosdahl. See AUTHORS.txt or AUTHORS.html and |
0eac13a3 | 2016 | <https://ccache.dev/credits.html> for a list of contributors. |