# Name {#_name}

ccache - a fast C/C++ compiler cache

# Synopsis {#_synopsis}

> | **ccache** \[*ccache options*\]
> | **ccache** \[*KEY*=*VALUE* ...​\] *compiler* \[*compiler options*\]
> | *compiler* \[*compiler options*\]

The first form takes options described in [Command line
options](#_command_line_options) below. The second form invokes the
compiler, optionally using [configuration options](#_configuration) as
*KEY*=*VALUE* arguments. In the third form, ccache is masquerading as
the compiler as described in [Run modes](#_run_modes).

# Description {#_description}

Ccache is a compiler cache that speeds up recompilation by storing the
results of previous compilations and reusing them when the same
compilation is performed again.

Ccache is designed to produce exactly the same compiler output as a
normal compilation. The only difference you should notice is faster
build times. Any known exceptions to this behavior are documented in the
*[Caveats](#_caveats)* section. If you find a case where ccache produces
different output than expected, please report it to us.

# Run modes {#_run_modes}

There are two ways to use ccache to cache compilations:

1.  **Prefix method**: Add `ccache` before your compilation command.
    This is the simplest approach when you want to try ccache or use it
    for specific projects. Example:

        ccache gcc -c example.c

2.  **Masquerade method**: Make ccache appear as the compiler by
    creating a symbolic link to ccache with the compiler's name. This is
    useful when you want to use ccache for all compilations. To set up
    ccache to masquerade as `gcc` and `g++`:

        ln -s /usr/bin/ccache /usr/local/bin/gcc
        ln -s /usr/bin/ccache /usr/local/bin/g++

    To do this on a Debian system, it's easiest to just prepend
    `/usr/lib/ccache` to your `PATH`. `/usr/lib/ccache` contains
    symlinks for all compilers currently installed as Debian packages.

    On systems that don't support symbolic links, you can copy ccache
    instead:

        cp ccache /usr/local/bin/gcc
        cp ccache /usr/local/bin/g++

    This works as long as the directory containing the symbolic links or
    ccache copies appears before the real compiler directory (typically
    `/usr/bin`) in your `PATH`.

    :::: warning
    ::: title
    :::

    The masquerade method works well but may conflict with other tools
    that use the same technique. See *[Using ccache with other compiler
    wrappers](#_using_ccache_with_other_compiler_wrappers)* for more
    information.
    ::::

# Command line options {#_command_line_options}

These command line options apply only when you invoke ccache directly as
"ccache". When ccache masquerades as a compiler (as described in the
previous section), you should use the normal compiler options and refer
to your compiler's documentation.

## Common options {#_common_options}

**-c**, **--cleanup**

:   Clean up the cache by removing not recently used cached files until
    the specified file number and cache size limits are not exceeded.
    This also recalculates the cache file count and size totals.
    Normally, there is no need to initiate cleanup manually as ccache
    keeps the cache below the specified limits at runtime and keeps
    statistics up to date on each compilation. Forcing a cleanup is
    mostly useful if you have modified the cache contents manually or
    believe that the cache size statistics may be inaccurate.

**-C**, **--clear**

:   Clear the entire cache, removing all cached files, but keeping the
    configuration file.

**--config-path** *PATH*

:   Let the command line options operate on configuration file *PATH*
    instead of the default. Using this option has the same effect as
    setting (overriding) the environment variable `CCACHE_CONFIGPATH`
    temporarily.

**-d**, **--dir** *PATH*

:   Let the command line options operate on cache directory *PATH*
    instead of the default. For example, to show statistics for a cache
    directory at `/shared/ccache` you can run
    `ccache -d /shared/ccache -s`. Using this option has the same effect
    as setting the environment variable `CCACHE_DIR` temporarily.

**--evict-namespace** *NAMESPACE*

:   Remove files created in the given [**namespace**](#config_namespace)
    from the cache.

**--evict-older-than** *AGE*

:   Remove files used less recently than *AGE* from the cache. *AGE*
    should be an unsigned integer with a `d` (days) or `s` (seconds)
    suffix. If combined with `--evict-namespace`, only remove files
    within that namespace.

**-h**, **--help**

:   Print a summary of command line options.

**-F** *NUM*, **--max-files** *NUM*

:   Set the maximum number of files allowed in the cache to *NUM*. Use 0
    for no limit. The value is stored in a configuration file in the
    cache directory and applies to all future compilations.

**-M** *SIZE*, **--max-size** *SIZE*

:   Set the maximum size of the files stored in the cache. *SIZE* should
    be a number followed by an optional suffix: kB, MB, GB, TB
    (decimal), KiB, MiB, GiB or TiB (binary). The default suffix is GiB.
    Use 0 for no limit. The value is stored in a configuration file in
    the cache directory and applies to all future compilations.

**-X** *LEVEL*, **--recompress** *LEVEL*

:   Recompress the cache to level *LEVEL* using the Zstandard algorithm.
    The level can be an integer, with the same semantics as the
    [**compression_level**](#config_compression_level) configuration
    option, or the special value **uncompressed** for no compression.
    See *[Cache compression](#_cache_compression)* for more information.
    This can potentially take a long time since all files in the cache
    need to be visited. Only files that are currently compressed with a
    different level than *LEVEL* will be recompressed.

**-o** *KEY=VALUE*, **--set-config** *KEY*=*VALUE*

:   Set configuration option *KEY* to *VALUE* in the configuration file.
    See *[Configuration](#_configuration)* for more information.

**-x**, **--show-compression**

:   Print cache compression statistics. See *[Cache
    compression](#_cache_compression)* for more information. This can
    potentially take a long time since all files in the cache need to be
    visited.

**-p**, **--show-config**

:   Print current configuration options and from where they originate
    (environment variable, configuration file or compile-time default)
    in human-readable format.

**--show-log-stats**

:   Print statistics counters from the stats log in human-readable
    format. See [**stats_log**](#config_stats_log). Use `-v`/`--verbose`
    once or twice for more details.

**-s**, **--show-stats**

:   Print a summary of configuration and statistics counters in
    human-readable format. Use `-v`/`--verbose` once or twice for more
    details. See [Cache statistics](#_cache_statistics) for more
    information.

**--stop-storage-helpers**

:   Storage helpers normally stop after a period of client inactivity,
    but this option can be used to stop any running helpers immediately.

**--threads** *THREADS*

:   Use up to *THREADS* threads for threaded operations. The default is
    to use one thread per CPU.

**-v**, **--verbose**

:   Increase verbosity. The option can be given multiple times.

**-V**, **--version**

:   Print version and copyright information.

**-z**, **--zero-stats**

:   Zero the cache statistics (but not the configuration options).

## Options for remote file-based storage {#_options_for_remote_file_based_storage}

**--trim-dir** *PATH*

:   Remove not recently used files from directory *PATH* until it is at
    most the size specified by `--trim-max-size`.

    :::: warning
    ::: title
    :::

    Don't use this option to trim the local cache. To trim the local
    cache directory to a certain size, use
    `CCACHE_MAXSIZE=SIZE ccache -c`.
    ::::

**--trim-max-size** *SIZE*

:   Specify the maximum size for `--trim-dir`. *SIZE* should be a number
    followed by an optional suffix: kB, MB, GB, TB (decimal), KiB, MiB,
    GiB or TiB (binary). The default suffix is GiB. Use 0 for no limit.

**--trim-method** *METHOD*

:   Specify the method to trim a directory with `--trim-dir`. Possible
    values are:

    **atime**

    :   LRU (least recently used) using the file access timestamp. This
        is the default.

    **mtime**

    :   LRU (least recently used) using the file modification timestamp.

**--trim-recompress** *LEVEL*

:   Recompress to level *LEVEL* using the Zstandard algorithm when using
    `--trim-dir`. The level can be an integer, with the same semantics
    as the [**compression_level**](#config_compression_level)
    configuration option, or the special value **uncompressed** for no
    compression. See *[Cache compression](#_cache_compression)* for more
    information. This can potentially take a long time since all files
    in the cache need to be visited. Only files that are currently
    compressed with a different level than *LEVEL* will be recompressed.

## Options for scripting or debugging {#_options_for_scripting_or_debugging}

**--checksum-file** *PATH*

:   Print the checksum (128 bit XXH3) of the file at *PATH* (`-` for
    standard input).

**--extract-result** *PATH*

:   Extract data stored in the result file at *PATH* (`-` for standard
    input). The data will be written to `ccache-result.*` files in to
    the current working directory. This option is only useful when
    debugging ccache and its behavior.

**--format** *FORMAT*

:   Specify format for `--print-log-stats` and `--print-stats`. Possible
    values are:

    **tab**

    :   Tab separated. This is the default.

    **json**

    :   JSON formatted.

**-k** *KEY*, **--get-config** *KEY*

:   Print the value of configuration option *KEY*. See
    *[Configuration](#_configuration)* for more information.

**--hash-file** *PATH*

:   Print the hash (160 bit BLAKE3) of the file at *PATH* (`-` for
    standard input). This is only useful when debugging ccache and its
    behavior.

**--inspect** *PATH*

:   Print the content of a result or manifest file at *PATH* (`-` for
    standard input) to standard output in human-readable format. File
    content embedded in a result file will however not be printed; use
    `--extract-result` to extract the file content. This option is only
    useful when debugging ccache and its behavior.

**--print-log-stats**

:   Print statistics counters from the stats log in machine-parsable
    (tab-separated or JSON) format. See
    [**stats_log**](#config_stats_log) and `--format`.

**--print-stats**

:   Print statistics counter IDs and corresponding values in
    machine-parsable (tab-separated or JSON) format. See `--format`.

**--print-version**

:   Print version and don't do anything else.

## Extra options {#_extra_options}

When run as a compiler, ccache usually just takes the same command line
options as the compiler you are using. The only exception to this is the
option `--ccache-skip`. That option can be used to tell ccache to avoid
interpreting the next option in any way and to pass it along to the
compiler as-is.

:::: note
::: title
:::

`--ccache-skip` currently only tells ccache not to interpret the next
option as a special compiler option --- the option will still be
included in the direct mode hash.
::::

The reason this can be important is that ccache does need to parse the
command line and determine what is an input filename and what is a
compiler option, as it needs the input filename to determine the name of
the resulting object file (among other things). The heuristic ccache
uses when parsing the command line is that any argument that exists as a
file is treated as an input file name. By using `--ccache-skip` you can
force an option to not be treated as an input file name and instead be
passed along to the compiler as a command line option.

Another case where `--ccache-skip` can be useful is if ccache interprets
an option specially but shouldn't, since the option has another meaning
for your compiler than what ccache thinks.

See also [**ignore_options**](#config_ignore_options).

# Configuration {#_configuration}

You can customize ccache's behavior using configuration files and
environment variables. Configuration options are processed in the
following order of priority (highest first):

1.  Command line settings in *KEY*=*VALUE* form. Example:

        ccache debug=true compiler_check="%compiler% --version" gcc -c example.c

2.  Environment variables starting with `CCACHE_`.

3.  A [directory-specific configuration
    file](#_directory_specific_configuration_file).

4.  The [cache-specific configuration
    file](#_cache_specific_configuration_file).

5.  The system-wide configuration file `<sysconfdir>/ccache.conf`
    (typically `/etc/ccache.conf` or `/usr/local/etc/ccache.conf`).

6.  Compile-time defaults.

Exception: If the environment variable `CCACHE_CONFIGPATH` is set, it
specifies the only configuration file that will be read (environment
variables and command line settings still apply).

## Cache-specific configuration file {#_cache_specific_configuration_file}

The location of the cache-specific configuration file is determined like
this on non-Windows systems:

1.  If `CCACHE_CONFIGPATH` is set, use that path.

2.  Otherwise, if the environment variable `CCACHE_DIR` is set then use
    `$CCACHE_DIR/ccache.conf`.

3.  Otherwise, if [**cache_dir**](#config_cache_dir) is set in the
    system configuration file then use `<cache_dir>/ccache.conf`.

4.  Otherwise, if there is a legacy `$HOME/.ccache` directory then use
    `$HOME/.ccache/ccache.conf`.

5.  Otherwise, if `XDG_CONFIG_HOME` is set then use
    `$XDG_CONFIG_HOME/ccache/ccache.conf`.

6.  Otherwise, use `$HOME/Library/Preferences/ccache/ccache.conf`
    (macOS) or `$HOME/.config/ccache/ccache.conf` (other systems).

On Windows, this is the method used to find the configuration file:

1.  If `CCACHE_CONFIGPATH` is set, use that path.

2.  Otherwise, if the environment variable `CCACHE_DIR` is set then use
    `%CCACHE_DIR%/ccache.conf`.

3.  Otherwise, if [**cache_dir**](#config_cache_dir) is set in the
    system configuration file then use `<cache_dir>\ccache.conf`. The
    system-wide configuration on Windows is
    `%ALLUSERSPROFILE%\ccache\ccache.conf` by default. The
    `ALLUSERSPROFILE` environment variable is usually `C:\ProgramData`.

4.  Otherwise, if there is a legacy `%USERPROFILE%\.ccache` directory
    then use `%USERPROFILE%\.ccache\ccache.conf`.

5.  Otherwise, use `%LOCALAPPDATA%\ccache\ccache.conf` if it exists.

6.  Otherwise, use `%APPDATA%\ccache\ccache.conf`.

See also the [**cache_dir**](#config_cache_dir) configuration option for
how the cache directory location is determined.

## Directory-specific configuration file {#_directory_specific_configuration_file}

Ccache searches for a `ccache.conf` file (separate from the
cache-specific configuration file described above) in the current
working directory or any parent directory. The found file must be owned
by the effective user and must not be world-writable; otherwise ccache
will abort with an error. The search stops when reaching:

- a directory listed in a [\"ceiling directory\"](#config_ceiling_dirs)
  (by default the user's home directory)

- a directory that contains a [\"ceiling
  marker\"](#config_ceiling_markers) (by default `.git`)

- a directory owned by another user

- a file system boundary (mount point)

By default, the file cannot set \"unsafe options\", i.e. those that
affect which commands to execute, which files to write (except cache
entries) and which remote storage to use. It is possible to allow unsafe
options by adding an entry to [**safe_dirs**](#config_safe_dirs).

## Configuration value syntax {#_configuration_value_syntax}

All configuration values support expansion of environment variables. The
syntax is similar to POSIX shell syntax: `$VAR` or `${VAR}`. Both
variants will expand to the value of the environment variable `VAR`.

Two consecutive dollar signs (`$$`) will expand to a single dollar sign
(`$`).

## Configuration file syntax {#_configuration_file_syntax}

Configuration files are in a simple "key = value" format, one option per
line. Lines starting with a hash sign are comments. Blank lines are
ignored, as is whitespace surrounding keys and values. Example:

    # Set maximum cache size to 10 GB:
    max_size = 10GB

### Multi-line values {#_multi_line_values}

Values can span multiple lines using indentation-based continuation.
Lines that start with whitespace (spaces or tabs) are treated as
continuation lines and are joined to the previous value with a single
space. Comments and blank lines within a multi-line value are skipped.
For example:

    ignore_options =
      -Wall
      -Wextra
      # This is a comment within the value
      -pedantic
    # This ends the multi-line value
    compiler = gcc

This is equivalent to:

    ignore_options = -Wall -Wextra -pedantic
    compiler = gcc

Multi-line values are particularly useful for options that accept
multiple items.

## Boolean values {#_boolean_values}

Some configuration options are boolean values (i.e. truth values). In a
configuration file, such values must be set to the string **true** or
**false**. For the corresponding environment variables, the semantics
are a bit different:

- A set environment variable means "true" (even if set to the empty
  string).

- The following case-insensitive negative values are considered an error
  (instead of surprising the user): **0**, **false**, **disable** and
  **no**.

- An unset environment variable means "false".

Each boolean environment variable also has a negated form starting with
`CCACHE_NO`. For example, `CCACHE_COMPRESS` can be set to force
compression and `CCACHE_NOCOMPRESS` can be set to force no compression.

## Configuration options {#_configuration_options}

Below is a list of available configuration options. The corresponding
environment variable name is indicated in parentheses after each
configuration option key.

Options that define a list of paths have their entries separated by `;`
on Windows and `:` on other systems.

**absolute_paths_in_stderr** (**CCACHE_ABSSTDERR**)

:   This option specifies whether ccache should rewrite relative paths
    in the compiler's textual output (standard error and standard
    output) to absolute paths. This can be useful if you use
    [**base_dir**](#config_base_dir) with a build system (e.g. CMake
    with the \"Unix Makefiles\" generator) that executes the compiler in
    a different working directory, which makes relative paths in
    compiler errors or warnings incorrect. The default is false.

<!-- -->

**base_dir** (**CCACHE_BASEDIR**)

:   This option specifies a list of absolute paths. When set, ccache
    converts absolute paths to relative paths before hashing, but only
    for paths that start with one of the specified base directories.

    This enables cache sharing between compilations in different
    directories, even when the project uses absolute paths. See
    [Compiling in different
    directories](#_compiling_in_different_directories)\_ for more
    details. When empty (the default), no path rewriting occurs.

    Avoid using `/` as the base directory as this will also rewrite
    system header paths, which is usually counterproductive.

    Example scenario: Alice works in `/home/alice/project1/build` and
    compiles like this:

        ccache gcc -I/usr/include/example -I/home/alice/project2/include -c /home/alice/project1/src/example.c

    Here is what ccache will actually execute for different **base_dir**
    settings:

        # Current working directory: /home/alice/project1/build

        # With base_dir = /:
        gcc -I../../../../usr/include/example -I../../project2/include -c ../src/example.c

        # With base_dir = /home or /home/alice:
        gcc -I/usr/include/example -I../../project2/include -c ../src/example.c

        # With base_dir = /home/alice/project1 or /home/alice/project1/src:
        gcc -I/usr/include/example -I/home/alice/project2/include -c ../src/example.c

    If Bob stores the same projects in `/home/bob/stuff` and both users
    set **base_dir** to `/home` or `/home/$USER`, they will share cache
    hits because the rewritten command lines will be identical:

        # Current working directory: /home/bob/stuff/project1/build

        # With base_dir = /home or /home/bob:
        gcc -I/usr/include/example -I../../project2/include -c ../src/example.c

    Without **base_dir** there will be a cache miss since the absolute
    paths will differ. With **base_dir** set to `/` there will be a
    cache miss since the relative path to `/usr/include/example` will be
    different. With **base_dir** set to `/home/bob/stuff/project1` there
    will a cache miss since the path to project2 will be a different
    absolute path.

    :::: warning
    ::: title
    :::

    Rewriting absolute paths to relative is kind of a brittle hack. It
    works OK in many cases, but there might be cases where things break.
    One known issue is that absolute paths are not reproduced in
    dependency files, which can mess up dependency detection in tools
    like Make and Ninja. If possible, use relative paths in the first
    place instead of using **base_dir**.
    ::::

<!-- -->

**cache_dir** (**CCACHE_DIR**)

:   This option specifies where ccache will keep its cached compiler
    outputs.

    On non-Windows systems, the default is `$HOME/.ccache` if such a
    directory exists, otherwise `$XDG_CACHE_HOME/ccache` if
    `XDG_CACHE_HOME` is set, otherwise `$HOME/Library/Caches/ccache`
    (macOS) or `$HOME/.cache/ccache` (other systems).

    On Windows, the default is `%USERPROFILE%\.ccache` if such a
    directory exists, otherwise `%LOCALAPPDATA%\ccache`.

    :::: warning
    ::: title
    :::

    Previous ccache versions defaulted to storing the cache in
    `%APPDATA%\ccache` on Windows. This can result in large network file
    transfers of the cache in domain environments and similar problems.
    Please check this directory for cache directories and either delete
    them or the whole directory, or move them to the
    `%LOCALAPPDATA%\ccache` directory.
    ::::

    See also *[Cache-specific configuration
    file](#_cache_specific_configuration_file)*.

<!-- -->

**ceiling_dirs** (**CCACHE_CEILING_DIRS**)

:   This option specifies absolute directories where ccache will stop
    searching for a [directory-specific configuration
    file](#_directory_specific_configuration_file). You might want to
    set this if accessing files in parent directories is too slow, e.g.
    on network file systems. The default is to stop looking when
    reaching the user's home directory.

<!-- -->

**ceiling_markers** (**CCACHE_CEILING_MARKERS**)

:   This option specifies one or more file or directory names (separated
    by `;` on Windows, `:` on other systems). When searching for a
    [directory-specific configuration file](#Directory-specific
    configuration file), ccache will stop searching parent directories
    when it reaches a directory containing any of the specified names.
    The default is `.git`.

<!-- -->

**compiler** (**CCACHE_COMPILER** or (deprecated) **CCACHE_CC**)

:   This option can be used to force the name of the compiler to use. If
    set to the empty string (which is the default), ccache works it out
    from the command line.

<!-- -->

**compiler_check** (**CCACHE_COMPILERCHECK**)

:   By default, ccache includes the modification time ("mtime") and size
    of the compiler in the hash to ensure that results retrieved from
    the cache are accurate. If compiler plugins are used, these plugins
    will also be added to the hash. This option can be used to select
    another strategy. Possible values are:

    **content**

    :   Hash the content of the compiler binary. This makes ccache very
        slightly slower compared to **mtime**, but makes it cope better
        with compiler upgrades during a build bootstrapping process.

    **mtime**

    :   Hash the compiler's mtime and size, which is fast. This is the
        default.

    **none**

    :   Don't hash anything. This may be good for situations where you
        can safely use the cached results even though the compiler's
        mtime or size has changed (e.g. if the compiler is built as part
        of your build system and the compiler's source has not changed,
        or if the compiler only has changes that don't affect code
        generation). You should only use **none** if you know what you
        are doing.

    **string:value**

    :   Hash **value**. This can for instance be a compiler revision
        number or another string that the build system generates to
        identify the compiler.

    *a command string*

    :   Hash the standard output and standard error output of the
        specified command. The string will be split on whitespace to
        find out the command and arguments to run. No other
        interpretation of the command string will be done, except that
        the special word **%compiler%** will be replaced with the path
        to the compiler. Several commands can be specified with `;` as
        the separator. Examples:

            %compiler% -v

            %compiler% -dumpmachine; %compiler% -dumpversion

        You should make sure that the specified command is as fast as
        possible since it will be run once for each ccache invocation.

        Identifying the compiler using a command is useful if you want
        to avoid cache misses when the compiler has been rebuilt but not
        changed.

        Another case is when the compiler (as seen by ccache) actually
        isn't the real compiler but another compiler wrapper --- in that
        case, the default **mtime** method will hash the mtime and size
        of the other compiler wrapper, which means that ccache won't be
        able to detect a compiler upgrade. Using a suitable command to
        identify the compiler is thus safer, but it's also slower, so
        you should consider continue using the **mtime** method in
        combination with the **prefix_command** option if possible. See
        *[Using ccache with other compiler
        wrappers](#_using_ccache_with_other_compiler_wrappers)*.

<!-- -->

**compiler_type** (**CCACHE_COMPILERTYPE**)

:   Ccache normally guesses the compiler type based on the compiler
    name. The **compiler_type** option lets you force a compiler type.
    This can be useful if the compiler has a non-standard name but is
    actually one of the known compiler types. Possible values are:

    **auto**

    :   Guess one of the types below based on the compiler name
        (following symlinks). This is the default.

    **clang**

    :   Clang-based compiler.

    **clang-cl**

    :   clang-cl.

    **gcc**

    :   GCC-based compiler.

    **icl**

    :   Intel compiler on Windows.

    **icx**

    :   Intel LLVM-based compiler.

    **icx-cl**

    :   Intel LLVM-based MSVC-compatible compiler.

    **msvc**

    :   Microsoft Visual C++ (MSVC).

    **nvcc**

    :   NVCC (CUDA) compiler.

    **other**

    :   Any compiler other than the known types.

<!-- -->

**compression** (**CCACHE_COMPRESS** or **CCACHE_NOCOMPRESS**, see *[Boolean values](#_boolean_values)* above)

:   If true, ccache will compress data it puts in the cache. However,
    this option has no effect on how files are retrieved from the cache;
    compressed and uncompressed results will still be usable regardless
    of this option. The default is true.

    Compression is done using the Zstandard algorithm. The algorithm is
    fast enough that there should be little reason to turn off
    compression to gain performance. One exception is if the cache is
    located on a compressed file system, in which case the compression
    performed by ccache of course is redundant.

    Compression will be disabled if file cloning (the
    [**file_clone**](#config_file_clone) option) or hard linking (the
    [**hard_link**](#config_hard_link) option) is enabled.

<!-- -->

**compression_level** (**CCACHE_COMPRESSLEVEL**)

:   This option determines the level at which ccache will compress
    object files using the real-time compression algorithm Zstandard. It
    only has effect if [**compression**](#config_compression) is enabled
    (which it is by default). Zstandard is extremely fast for
    decompression and very fast for compression for lower compression
    levels. The default is 0.

    Semantics of **compression_level**:

    **\> 0**

    :   A positive value corresponds to normal Zstandard compression
        levels. Lower levels (e.g. **1**) mean faster compression but
        worse compression ratio. Higher levels (e.g. **19**) mean slower
        compression but better compression ratio. The maximum possible
        value depends on the libzstd version, but at least up to 19 is
        available for all versions. Decompression speed is essentially
        the same for all levels. As a rule of thumb, use level 5 or
        lower since higher levels may slow down compilations noticeably.
        Higher levels are however useful when recompressing the cache
        with command line option `-X`/`--recompress`.

    **\< 0**

    :   A negative value corresponds to Zstandard's "ultra-fast"
        compression levels, which are even faster than level 1 but with
        less good compression ratios. For instance, level **-3**
        corresponds to `--fast=3` for the `zstd` command line tool. In
        practice, there is little use for levels lower than **-5** or
        so.

    **0** (default)

    :   The value **0** means that ccache will choose a suitable level,
        currently **1**.

    See the [Zstandard documentation](https://facebook.github.io/zstd/)
    for more information.

<!-- -->

**cpp_extension** (**CCACHE_EXTENSION**)

:   This option can be used to force a certain extension for the
    intermediate preprocessed file. The default is to automatically
    determine the extension to use for intermediate preprocessor files
    based on the type of file being compiled, but that sometimes doesn't
    work. For example, when using the "aCC" compiler on HP-UX, set the
    cpp extension to **i**.

<!-- -->

**debug** (**CCACHE_DEBUG** or **CCACHE_NODEBUG**, see *[Boolean values](#_boolean_values)* above)

:   If true, enable the debug mode. The debug mode creates per-object
    debug files that are helpful when debugging unexpected cache misses.
    Note however that ccache performance will be reduced slightly. See
    *[Cache debugging](#_cache_debugging)* for more information. The
    default is false.

<!-- -->

**debug_dir** (**CCACHE_DEBUGDIR**)

:   Specifies where to write per-object debug files if the [debug
    mode](#config_debug) is enabled. If set to the empty string, the
    files will be written next to the object file. If set to a
    directory, the debug files will be written with full absolute paths
    in that directory, creating it if needed. The default is the empty
    string.

    For example, if **debug_dir** is set to `/example`, the current
    working directory is `/home/user` and the object file is
    `build/output.o` then the debug log will be written to
    `/example/home/user/build/output.o.ccache-log`. See also *[Cache
    debugging](#_cache_debugging)*.

<!-- -->

**debug_level** (**CCACHE_DEBUGLEVEL**)

:   Specifies the amount of information that is written when the [debug
    mode](#config_debug) is enabled. See *[Cache
    debugging](#_cache_debugging)* for more information. The default is
    2.

<!-- -->

**depend_mode** (**CCACHE_DEPEND** or **CCACHE_NODEPEND**, see *[Boolean values](#_boolean_values)* above)

:   If true, the depend mode will be used. The default is false. See
    *[The depend mode](#_the_depend_mode)*.

<!-- -->

**direct_mode** (**CCACHE_DIRECT** or **CCACHE_NODIRECT**, see *[Boolean values](#_boolean_values)* above)

:   If true, the direct mode will be used. The default is true. See
    *[The direct mode](#_the_direct_mode)*.

<!-- -->

**disable** (**CCACHE_DISABLE** or **CCACHE_NODISABLE**, see *[Boolean values](#_boolean_values)* above)

:   When true, ccache will just call the real compiler, bypassing the
    cache completely. The default is false.

    It is also possible to disable ccache for a specific source code
    file by adding the string `ccache:disable` in a comment in the first
    4096 bytes of the file.

<!-- -->

**extra_files_to_hash** (**CCACHE_EXTRAFILES**)

:   This option is a list of paths to files that ccache will include in
    the hash sum that identifies the build.

<!-- -->

**file_clone** (**CCACHE_FILECLONE** or **CCACHE_NOFILECLONE**, see *[Boolean values](#_boolean_values)* above)

:   If true, ccache will attempt to use file cloning (also known as
    "copy on write", "CoW" or "reflinks") to store and fetch cached
    compiler results. **file_clone** has priority over
    [**hard_link**](#config_hard_link). The default is false.

    Files stored by cloning cannot be compressed, so the cache size will
    likely be significantly larger if this option is enabled. However,
    performance may be improved depending on the use case.

    Unlike the [**hard_link**](#config_hard_link) option, **file_clone**
    is completely safe to use, but not all file systems support the
    feature. For such file systems, ccache will fall back to use plain
    copying (or hard links if [**hard_link**](#config_hard_link) is
    enabled).

<!-- -->

**hard_link** (**CCACHE_HARDLINK** or **CCACHE_NOHARDLINK**, see *[Boolean values](#_boolean_values)* above)

:   If true, ccache will attempt to use hard links to store and fetch
    cached object files. The default is false.

    Files stored via hard links cannot be compressed, so the cache size
    will likely be significantly larger if this option is enabled.
    However, performance may be improved depending on the use case.

    :::: warning
    ::: title
    :::

    Do not enable this option unless you are aware of these caveats:
    ::::

    - If the resulting file is modified, the file in the cache will also
      be modified since they share content, which corrupts the cache
      entry. As of version 4.0, ccache makes stored and fetched object
      files read-only as a safety measure. Furthermore, a simple
      integrity check is made for cached object files by verifying that
      their sizes are correct. This means that mistakes like
      `strip file.o` or `echo >file.o` will be detected even if the
      object file is made writable, but a modification that doesn't
      change the file size will not.

    - Programs that don't expect that files from two different identical
      compilations are hard links to each other can fail.

    - Programs that rely on modification times (like `make`) can be
      confused if several users (or one user with several build trees)
      use the same cache directory. The reason for this is that the
      object files share i-nodes and therefore modification times. If
      `file.o` is in build tree **A** (hard-linked from the cache) and
      `file.o` then is produced by ccache in build tree **B** by
      hard-linking from the cache, the modification timestamp will be
      updated for `file.o` in build tree **A** as well. This can
      retrigger relinking in build tree **A** even though nothing really
      has changed.

<!-- -->

**hash_dir** (**CCACHE_HASHDIR** or **CCACHE_NOHASHDIR**, see *[Boolean values](#_boolean_values)* above)

:   If true (which is the default), ccache will include the current
    working directory (CWD) in the hash that is used to distinguish two
    compilations when generating debug info (compiler option `-g` with
    variations). Exception: The CWD will not be included in the hash if
    the compiler options `-fdebug-prefix-map` or
    `-fdebug-compilation-dir` are used appropriately. See also the
    discussion under *[Compiling in different
    directories](#_compiling_in_different_directories)*.

    The reason for including the CWD in the hash by default is to
    prevent a problem with the storage of the current working directory
    in the debug info of an object file, which can lead ccache to return
    a cached object file that has the working directory in the debug
    info set incorrectly.

    You can disable this option to get cache hits when compiling the
    same source code in different directories if you don't mind that CWD
    in the debug info might be incorrect.

<!-- -->

**ignore_headers_in_manifest** (**CCACHE_IGNOREHEADERS**)

:   This option is a list of paths to files (or directories with
    headers) that ccache will **not** include in the manifest list that
    makes up the direct mode. Note that this can cause stale cache hits
    if those headers do indeed change.

<!-- -->

**ignore_options** (**CCACHE_IGNOREOPTIONS**)

:   This option is a space-delimited list of compiler options that
    ccache will ignore. Entries in the list can optionally end with an
    asterisk (`*`) to matching any option suffix. For example,
    `-fmessage-length=*` will match both `-fmessage-length=20` and
    `-fmessage-length=70`. A matching compiler option will neither be
    interpreted specially nor be part of the input hash. Ignoring a
    compiler option from the hash can be useful when you know it doesn't
    affect the result (and ccache doesn't know that), or when it does
    and you don't care. See also *[Extra options](#_extra_options)*.

<!-- -->

**inode_cache** (**CCACHE_INODECACHE** or **CCACHE_NOINODECACHE**, see *[Boolean values](#_boolean_values)* above)

:   If true, ccache will cache source file hashes based on device, inode
    and timestamps. This reduces the time spent on hashing include files
    since the result can be reused between compilations. The default is
    true. The feature requires
    [**temporary_dir**](#config_temporary_dir) to be located on a local
    filesystem of a supported type.

    :::: note
    ::: title
    :::

    Support for the inode cache feature on Windows is experimental. On
    Windows the default is false.
    ::::

<!-- -->

**keep_comments_cpp** (**CCACHE_COMMENTS** or **CCACHE_NOCOMMENTS**, see *[Boolean values](#_boolean_values)* above)

:   If true, ccache will not discard the comments before hashing
    preprocessor output. The default is false. This can be used to check
    documentation with `-Wdocumentation`.

<!-- -->

**libexec_dirs** (**CCACHE_LIBEXEC_DIRS**)

:   If set, ccache will look for helper programs in these directories
    instead of the default.

<!-- -->

**log_file** (**CCACHE_LOGFILE**)

:   If set to a file path, ccache will write information on what it is
    doing to the specified file. This is useful for tracking down
    problems.

    If set to **syslog**, ccache will log using `syslog()` instead of to
    a file. If you use rsyslogd, you can add something like this to
    `/etc/rsyslog.conf` or a file in `/etc/rsyslog.d`:

        # log ccache to file
        :programname, isequal, "ccache"         /var/log/ccache
        # remove from syslog
        & ~

<!-- -->

**max_files** (**CCACHE_MAXFILES**)

:   This option specifies the maximum number of files to keep in the
    cache. Use 0 for no limit (which is the default). See also *[Cache
    size management](#_cache_size_management)*.

<!-- -->

**max_size** (**CCACHE_MAXSIZE**)

:   This option specifies the maximum size of the cache. Use 0 for no
    limit. The default value is 5GiB. Available suffixes: kB, MB, GB, TB
    (decimal) and KiB, MiB, GiB, TiB (binary). The default suffix is
    GiB. See also *[Cache size management](#_cache_size_management)*.

<!-- -->

**msvc_dep_prefix** (**CCACHE_MSVC_DEP_PREFIX**)

:   This option specifies the prefix of included files output for MSVC
    compiler. The default prefix is "Note: including file:". If you use
    a localized compiler, this should be set accordingly.

<!-- -->

**msvc_utf8** (**CCACHE_MSVC_UTF8**)

:   This option adds `/utf-8` to the msvc command line when executing
    the preprocessor to ensure that filenames are not garbled for
    non-ascii characters. This implicitly enables `/validate-charset`
    and treats the source code as utf-8 which may cause compilation
    errors if comments in your code have characters in the \[128, 255\]
    range for a given Windows system codepage which results in an
    invalid utf-8 sequence. The default is true.

<!-- -->

**namespace** (**CCACHE_NAMESPACE**)

:   If set, the namespace string will be added to the hashed data for
    each compilation. This will make the associated cache entries
    logically separate from cache entries with other namespaces, but
    they will still share the same storage space. Cache entries can also
    be selectively removed from the local cache with the command line
    option `--evict-namespace`, potentially in combination with
    `--evict-older-than`.

    For instance, if you use the same local cache for several disparate
    projects, you can use a unique namespace string for each one. This
    allows you to remove cache entries that belong to a certain project
    if you stop working with that project.

<!-- -->

**path** (**CCACHE_PATH**)

:   If set, ccache will search directories in this list when looking for
    the real compiler. If not set, ccache will look for the first
    executable matching the compiler name in the normal `PATH` that
    isn't a symbolic link to ccache itself.

<!-- -->

**pch_external_checksum** (**CCACHE_PCH_EXTSUM** or **CCACHE_NOPCH_EXTSUM**, see *[Boolean values](#_boolean_values)* above)

:   When this option is set, and ccache finds a precompiled header file,
    ccache will look for a file with the extension ".sum" added (e.g.
    "pre.h.gch.sum"), and if found, it will hash this file instead of
    the precompiled header itself to work around the performance penalty
    of hashing very large files.

<!-- -->

**prefix_command** (**CCACHE_PREFIX**)

:   This option adds a list of prefixes (separated by space) to the
    command line that ccache uses when invoking the compiler. See also
    *[Using ccache with other compiler
    wrappers](#_using_ccache_with_other_compiler_wrappers)*.

<!-- -->

**prefix_command_cpp** (**CCACHE_PREFIX_CPP**)

:   This option adds a list of prefixes (separated by space) to the
    command line that ccache uses when invoking the preprocessor.

<!-- -->

**read_only** (**CCACHE_READONLY** or **CCACHE_NOREADONLY**, see *[Boolean values](#_boolean_values)* above)

:   If true, ccache will attempt to use existing cached results, but it
    will not add new results to any cache backend. Statistics counters
    will still be updated, though, unless the [**stats**](#config_stats)
    option is set to **false**.

    If you are using this because your ccache directory is read-only,
    you need to set [**temporary_dir**](#config_temporary_dir) since
    ccache will fail to create temporary files otherwise. You may also
    want to set [**stats**](#config_stats) to **false** make ccache not
    even try to update stats files.

<!-- -->

**read_only_direct** (**CCACHE_READONLY_DIRECT** or **CCACHE_NOREADONLY_DIRECT**, see *[Boolean values](#_boolean_values)* above)

:   Just like [**read_only**](#config_read_only) except that ccache will
    only try to retrieve results from the cache using the direct mode,
    not the preprocessor mode. See documentation for
    [**read_only**](#config_read_only) regarding using a read-only
    ccache directory.

<!-- -->

**recache** (**CCACHE_RECACHE** or **CCACHE_NORECACHE**, see *[Boolean values](#_boolean_values)* above)

:   If true, ccache will not use any previously stored result. New
    results will still be cached, possibly overwriting any pre-existing
    results.

<!-- -->

**remote_only** (**CCACHE_REMOTE_ONLY** or **CCACHE_NOREMOTE_ONLY**, see *[Boolean values](#_boolean_values)* above)

:   If true, ccache will only use [remote
    storage](#config_remote_storage). The default is false. Note that
    cache statistics counters will still be kept in the local cache
    directory unless [**stats**](#config_stats) is false. See also
    *[Storage interaction](#_storage_interaction)*.

<!-- -->

**remote_storage** (**CCACHE_REMOTE_STORAGE**)

:   This option specifies one or several storage backends (separated by
    whitespace) to query after checking the local cache (unless
    [**remote_only**](#config_remote_only) is true). See *[Remote
    storage backends](#_remote_storage_backends)* for documentation of
    syntax and available backends.

    Examples:

        remote_storage = file:/shared/nfs/directory+`
        remote_storage =
          file:///shared/nfs/one read-only
          file:///shared/nfs/two
        remote_storage = file:///Z:/example/windows/folder
        remote_storage = http://example.com/cache
        remote_storage = redis://example.com

    :::: note
    ::: title
    :::

    In previous ccache versions this option was called
    **secondary_storage** (**CCACHE_SECONDARY_STORAGE**), which can
    still be used as an alias.
    ::::

<!-- -->

**reshare** (**CCACHE_RESHARE** or **CCACHE_NORESHARE**, see *[Boolean values](#_boolean_values)* above)

:   If true, ccache will write results to remote storage even for local
    storage cache hits. The default is false.

<!-- -->

**response_file_format** (**CCACHE_RESPONSE_FILE_FORMAT**)

:   Ccache normally guesses the response file format based on the
    compiler type. The **response_file_format** option lets you force
    the response file quoting behavior. This can be useful if the
    compiler supports both POSIX and Windows response file quoting.
    Possible values are:

    **auto**

    :   Guess one of the formats below based on the compiler type. This
        is the default.

    **posix**

    :   POSIX quoting behavior.

    **windows**

    :   Windows quoting behavior.

<!-- -->

**safe_dirs** (**CCACHE_SAFE_DIRS**)

:   List of trusted directories for which directory-specific
    configuration files are allowed to set \"unsafe options\" (see
    [Directory-specific configuration
    file](#_directory_specific_configuration_file)). The default is
    empty.

    Allowed list values: `*` matches any directory. An absolute path
    ending with `/*` matches any subdirectory (at any depth) under that
    path. An absolute path not ending in `/*` matches only that
    directory.

<!-- -->

**sloppiness** (**CCACHE_SLOPPINESS**)

:   By default, ccache tries to give as few false cache hits as
    possible. However, in certain situations it's possible that you know
    things that ccache can't take for granted. This option makes it
    possible to tell ccache to relax some checks in order to increase
    the hit rate. Available values (separated by whitespace or comma):

    **clang_index_store**

    :   **Use case**: Xcode projects with varying index store paths.\
        **Effect**: Ignores the `-index-store-path` and
        `-index-unit-output-path` options when hashing.\
        **Trade-off**: Index won't update correctly on cache hits.

    **file_stat_matches**

    :   **Use case**: When file content checking is too slow.\
        **Effect**: Uses file timestamps instead of content for cache
        validation.\
        **Trade-off**: May miss content changes with identical
        timestamps.

    **file_stat_matches_ctime**

    :   **Use case**: When controlling file timestamps manually.\
        **Effect**: Ignores status change time when `file_stat_matches`
        is enabled.\
        **Trade-off**: May miss some file system changes.

    **gcno_cwd**

    :   **Use case**: Code coverage builds in different directories.\
        **Effect**: Ignores current directory when creating `.gcno`
        files (`-ftest-coverage`). Also disables hashing of the current
        working directory if `-fprofile-abs-path` is used.\
        **Trade-off**: Directory information in coverage files may be
        incorrect.

        :::: note
        ::: title
        :::

        No effect with `--coverage` (it implies `-fprofile-arcs`).
        ::::

    **incbin**

    :   **Use case**: Projects using assembly `.incbin` directives.\
        **Effect**: Allows caching files with `.incbin` directives.\
        **Trade-off**: Won't detect changes to included binary files.

    **include_file_ctime**

    :   **Use case**: Build systems that modify file timestamps
        frequently.\
        **Effect**: Ignores file status change time when checking for
        recent modifications.\
        **Trade-off**: May miss recent changes to source files.

    **include_file_mtime**

    :   **Use case**: Build systems that modify file timestamps
        frequently.\
        **Effect**: Ignores file modification time when checking for
        recent changes.\
        **Trade-off**: May miss recent modifications to source files.

    **ivfsoverlay**

    :   **Use case**: Xcode projects mixing Objective-C and Swift.\
        **Effect**: Ignores `-ivfsoverlay` virtual filesystem option.\
        **Trade-off**: May not detect VFS-related changes.

    **locale**

    :   **Use case**: Builds in environments with varying locale
        settings.\
        **Effect**: Ignores locale environment variables (`LANG`,
        `LC_ALL`, `LC_CTYPE`, `LC_MESSAGES`).\
        **Trade-off**: Compiler warning messages may vary between cached
        and fresh builds.

    **modules**

    :   **Use case**: Clang builds using `-fmodules`.\
        **Effect**: Allows caching when C++ modules are used.\
        **Trade-off**: May not detect changes in module internal state.

        See *[C++ modules](#_c_modules)* for details.

    **pch_defines**

    :   **Use case**: Projects with precompiled headers.\
        **Effect**: Relaxes checking of `#define` directives in
        precompiled headers.\
        **Trade-off**: May not detect some macro definition changes.

        See *[Precompiled headers](#_precompiled_headers)* for details.

    **random_seed**

    :   **Use case**: Builds with varying `-frandom-seed` values.\
        **Effect**: Ignores random seed values in compilation hash.\
        **Trade-off**: Builds may not be fully reproducible.

    **system_headers**

    :   **Use case**: Systems with frequently changing system headers.\
        **Effect**: Only tracks non-system headers in direct mode.\
        **Trade-off**: Won't detect system header changes that affect
        compilation.\
        **Limitations**: Only supported for GCC-like compilers (not
        MSVC). System headers are still checked in preprocessor mode.

        See also
        [**ignore_headers_in_manifest**](#config_ignore_headers_in_manifest).

    **time_macros**

    :   **Use case**: Code using time macros but values don't matter.\
        **Effect**: Ignores `__DATE__`, `__TIME__`, and `__TIMESTAMP__`
        in source.\
        **Trade-off**: Time values in output will be from cached
        compilation.

<!-- -->

**stats** (**CCACHE_STATS** or **CCACHE_NOSTATS**, see *[Boolean values](#_boolean_values)* above)

:   If true, ccache will update the statistics counters on each
    compilation. The default is true. If false, *[automatic
    cleanup](#_automatic_cleanup)* will be disabled as well.

<!-- -->

**stats_log** (**CCACHE_STATSLOG**)

:   If set to a file path, ccache will write statistics counter updates
    to the specified file. This is useful for getting statistics for
    individual builds. To show a summary of the current stats log, use
    `ccache --show-log-stats`.

    :::: note
    ::: title
    :::

    Lines in the stats log starting with a hash sign (`#`) are comments.
    ::::

<!-- -->

**temporary_dir** (**CCACHE_TEMPDIR**)

:   This option specifies where ccache will put temporary files. The
    default is `$XDG_RUNTIME_DIR/ccache-tmp` (typically
    `/run/user/<UID>/ccache-tmp`) if `XDG_RUNTIME_DIR` is set and the
    directory exists, otherwise `<cache_dir>/tmp`.

    :::: note
    ::: title
    :::

    In previous versions of ccache, **CCACHE_TEMPDIR** had to be on the
    same filesystem as the `CCACHE_DIR` path, but this requirement has
    been relaxed.
    ::::

<!-- -->

**umask** (**CCACHE_UMASK**)

:   This option (an octal integer) specifies the umask for files and
    directories in the cache directory. This is mostly useful when you
    wish to share your cache with other users.

## Disabling ccache {#_disabling_ccache}

To disable ccache completely for all invocations, set [**disable =
true**](#config_disable) (`CCACHE_DISABLE=1`). You can also disable
ccache for a certain source code file by adding the string
`ccache:disable` in a comment in the first 4096 bytes of the file. In
the latter case the `Ccache disabled` statistics counter will be
increased.

# Remote storage backends {#_remote_storage_backends}

The [**remote_storage**](#config_remote_storage) option lets you
configure ccache to use one or several remote storage backends. By
default, the local cache directory located in
[**cache_dir**](#config_cache_dir) will be queried first and remote
storage second, but [**remote_only**](#config_remote_only) can be set to
true to disable local storage. Note that cache statistics counters will
still be kept in the local cache directory --- remote storage backends
only store compilation results and manifests.

## Storage helper process {#_storage_helper_process}

ccache can spawn a long-lived local storage helper process (installed
separately) to handle communication with the remote storage. Storage
helpers keep remote connections up for efficiency and terminate after a
while on inactivity.

The storage helper program is called `ccache-storage-<scheme>`, where
`<scheme>` is the scheme part of a URL, e.g. `https`. The program can be
placed in these locations (in priority order):

1.  In a location specified by the **helper** property (see below).

2.  In a [libexec directory](#config_libexec_dirs).

3.  Next to the ccache executable.

4.  In `$PATH`.

If the program is not found, ccache falls back to one of the builtin
backends if available, otherwise ccache exits with an error.

## Configuration syntax {#_configuration_syntax}

A remote storage backend is specified by a URL and can be followed by a
whitespace-separated list of properties (`key=value`) and custom
attributes (`@key=value`). A missing `=value` is shorthand for setting
the value to **true**. Values must be
[percent-encoded](https://en.wikipedia.org/wiki/Percent-encoding) if
they contain `%`, `|` or whitespace characters. For compatibility with
older ccache versions, `|` characters are treated as spaces.

### Properties {#_properties}

- **data-timeout**: Timeout for send/receive data transfer. Resets
  whenever data is received or can be sent. Default: 10s.

- **helper**: Override which storage helper to spawn (either a filename
  or a full path). This is mainly useful when developing or testing new
  helpers.

- **idle-timeout**: Timeout for the helper process to wait before
  exiting after client inactivity (0s: stay up indefinitely). Default:
  10m.

- **read-only**: If **true**, only read from this backend, don't write.
  The default is **false**.

- **request-timeout**: Timeout for the whole request. Default: 1m.

- **shards**: A comma-separated list of names for sharding
  (partitioning) the cache entries using [Rendezvous
  hashing](https://en.wikipedia.org/wiki/Rendezvous_hashing), typically
  to spread the cache over a server cluster. When set, the storage URL
  must contain an asterisk (`*`), which will be replaced by one of the
  shard names to form a real URL. A shard name can optionally have an
  appended weight within parentheses to indicate how much of the key
  space should be associated with that shard. A shard with weight **w**
  will contain **w**/**S** of the cache, where **S** is the sum of all
  shard weights. A weight could for instance be set to represent the
  available memory for a memory cache on a specific server. The default
  weight is **1**.

  Examples:

  - `http://cache-*.example.com shards=a(3),b(1),c(1.5)` will put 55%
    (3/5.5) of the cache on `http://cache-a.example.com`, 18% (1/5.5) on
    `http://cache-b.example.com` and 27% (1.5/5.5) on
    `http://cache-c.example.com`.

  - `http://example.com/* shards=alpha,beta` will put 50% of the cache
    on `http://example.com/alpha` and 50% on `http://example.com/beta`.

Timeouts can be specified with an ms (milliseconds), s (seconds), m
(minutes), h (hours) or d (days) suffix.

### Custom attributes {#_custom_attributes}

Custom attributes on the form `@key=value` are specific to each storage
helper implementation. See the backend's documentation for which
attributes are available. Examples:

- `file:///example/directory @umask=002 @update-mtime=true`

- `https://example.com/path @bearer-token=deadbeef`

## Storage interaction {#_storage_interaction}

The table below describes the interaction between local and remote
storage on cache hits and misses if
[**remote_only**](#config_remote_only) is false (which is the default):

+-------------+-------------+------------------------------------------+
| **Local     | **Remote    | **What happens**                         |
| storage**   | storage**   |                                          |
+=============+=============+==========================================+
| miss        | miss        | Compile, write to local, write to        |
|             |             | remote^\[1\]^                            |
+-------------+-------------+------------------------------------------+
| miss        | hit         | Read from remote, write to local         |
+-------------+-------------+------------------------------------------+
| hit         | -           | Read from local, don't write to          |
|             |             | remote^\[2\]^                            |
+-------------+-------------+------------------------------------------+

^\[1\]^ Unless remote storage has property `read-only=true`.\
^\[2\]^ Unless local storage is set to share its cache hits with the
[**reshare**](#config_reshare) option.

If [**remote_only**](#config_remote_only) is true:

+-------------+-------------+------------------------------------------+
| **Local     | **Remote    | **What happens**                         |
| storage**   | storage**   |                                          |
+=============+=============+==========================================+
| -           | miss        | Compile, write to remote, don't write to |
|             |             | local                                    |
+-------------+-------------+------------------------------------------+
| -           | hit         | Read from remote, don't write to local   |
+-------------+-------------+------------------------------------------+

## File storage backend {#_file_storage_backend}

URL format: `file:DIRECTORY` or `file://[HOST]DIRECTORY`

This backend stores data as separate files in a directory structure
below **DIRECTORY**, similar (but not identical) to the local cache
storage. A typical use case for this backend would be sharing a cache on
an NFS directory. **DIRECTORY** must start with a slash. **HOST** can be
the empty string or localhost. On Windows, **HOST** can also be the name
of a server hosting a shared folder.

:::: important
::: title
:::

ccache will not perform any cleanup of the storage --- that has to be
done by other means, for instance by running `ccache --trim-dir`
periodically.
::::

Examples:

- `file:/shared/nfs/directory`

- `file:///shared/nfs/directory @umask=002 @update-mtime=true`

- `file:///Z:/example/windows/folder`

- `file://example.com/shared/ccache%20folder`

Optional attributes:

- **\@layout**: How to store file under the cache directory. Available
  values:

  - **flat**: Store all files directly under the cache directory.

  - **subdirs**: Store files in 256 subdirectories of the cache
    directory.

  The default is **subdirs**.

- **\@umask**: This attribute (an octal integer) overrides the umask to
  use for files and directories in the cache directory.

- **\@update-mtime**: If **true**, update the modification time (mtime)
  of cache entries that are read. The default is **false**.

## CRSH storage backend {#_crsh_storage_backend}

URL format: `crsh:IPC_ENDPOINT`

This backend connects to an already running [ccache storage
helper](#_storage_helper_process) (CRSH) process listening on
`IPC_ENDPOINT` (Unix socket path or Windows named pipe). The use case
for this is mainly when developing or debugging a storage helper, or in
special setups where the helper program is started and managed
externally.

Examples:

- `crsh:/path/to/your.sock` (Unix socket)

- `crsh:name-of-your-pipe` (Windows named pipe)

## HTTP storage backend {#_http_storage_backend}

:::: warning
::: title
:::

Built-in support for the HTTP protocol will likely be removed in a
future ccache release.
::::

URL format: `http://HOST[:PORT][/PATH]`

This backend stores data in an HTTP-compatible server. The required HTTP
methods are `GET`, `PUT` and `DELETE`.

:::: important
::: title
:::

ccache will not perform any cleanup of the storage --- that has to be
done by other means, for instance by running `ccache --trim-dir`
periodically.
::::

:::: note
::: title
:::

HTTPS is not supported.
::::

:::: tip
::: title
:::

See [How to set up HTTP
storage](https://ccache.dev/howto/http-storage.html) for hints on how to
set up an HTTP server for use with ccache.
::::

Examples:

- `http://localhost`

- `http://someusername:p4ssw0rd@example.com/cache/`

- `http://localhost:8080 @layout=bazel`

Optional attributes:

- **\@bearer-token**: Bearer token used to authorize the HTTP requests.

- **\@keep-alive**: If **true**, keep the HTTP connection to the storage
  server open to avoid reconnects. The default is **true**.

- **\@layout**: How to map key names to the path part of the URL.
  Available values:

  - **bazel**: Store values in a format compatible with the Bazel HTTP
    caching protocol. More specifically, the entries will be stored as
    64 hex digits under the `/ac/` part of the cache.

    :::: note
    ::: title
    :::

    You may have to disable verification of action cache values in the
    server for this to work since ccache entries are not valid action
    result metadata values.
    ::::

  - **flat**: Append the key directly to the path part of the URL (with
    a leading slash if needed).

  - **subdirs**: Append the first two characters of the key to the URL
    (with a leading slash if needed), followed by a slash and the rest
    of the key. This divides the entries into 256 buckets.

  The default is **subdirs**.

- **\@header**: Add the key=value pair to the HTTP headers of the
  request. For example: `@header=Content-Type=application/octet-stream`
  adds \"Content-Type: application/octet-stream\" to the HTTP headers of
  the request.

## Redis storage backend {#_redis_storage_backend}

:::: warning
::: title
:::

Built-in support for the Redis protocol will likely be removed in a
future ccache release.
::::

URL formats:

`redis://[[USERNAME:]PASSWORD@]HOST[:PORT][/DBNUMBER]`\
`redis+unix:SOCKET_PATH[?db=DBNUMBER]`\
`redis+unix://[[USERNAME:]PASSWORD@localhost]SOCKET_PATH[?db=DBNUMBER]`

This backend stores data in a [Redis](https://redis.io) (or
Redis-compatible) server. There are implementations for both
memory-based and disk-based storage. **PORT** defaults to **6379** and
**DBNUMBER** defaults to **0**.

:::: note
::: title
:::

ccache will not perform any cleanup of the Redis storage, but you can
[configure LRU eviction](https://redis.io/topics/lru-cache).
::::

:::: tip
::: title
:::

See [How to set up Redis
storage](https://ccache.dev/howto/redis-storage.html) for hints on
setting up a Redis server for use with ccache.
::::

:::: tip
::: title
:::

You can set up a cluster of Redis servers using the `shards` property
described in *[Remote storage backends](#_remote_storage_backends)*.
::::

Examples:

- `redis://localhost`

- `redis://p4ssw0rd@cache.example.com:6379/0`

- `redis+unix:/run/redis.sock`

- `redis+unix:///run/redis.sock`

- `redis+unix://p4ssw0rd@localhost/run/redis.sock?db=0`

# Cache size management {#_cache_size_management}

By default, ccache has a 5 GB limit on the total size of files in the
cache and no limit on the number of files. You can set different limits
using the command line options `-M`/`--max-size` and `-F`/`--max-files`.
Use the `-s`/`--show-stats` option to see the cache size and the
currently configured limits (in addition to other various statistics).

Cleanup can be triggered in two different ways: automatic and manual.

## Automatic cleanup {#_automatic_cleanup}

After a new compilation result has been stored in the local cache,
ccache will trigger an automatic cleanup if
[**max_size**](#config_max_size) or [**max_files**](#config_max_files)
is exceeded. The cleanup removes cache entries in approximate LRU (least
recently used) order based on the modification time (mtime) of files in
the cache. For this reason, ccache updates mtime of the cache files read
on a cache hit to mark them as recently used.

For performance reasons only entries in a subset of the cache are
considered when automatic cleanup is triggered, so the oldest entries
aren't always removed first but the overall behavior approximates LRU
over time.

## Manual cleanup {#_manual_cleanup}

Run `ccache --cleanup` to force cleanup of the whole cache. This will
recalculate the cache size information and make sure that the cache size
does not exceed [**max_size**](#config_max_size) and
[**max_files**](#config_max_files).

Note that there is no guarantee that only the oldest entries are
evicted, as discussed in *[Automatic cleanup](#_automatic_cleanup)*
above. To evict based on age use `ccache --evict-older-than AGE`.

# Cache compression {#_cache_compression}

By default, ccache compresses all cached data using the
[Zstandard](http://zstd.net) (zstd) algorithm at compression level 1.
This algorithm is fast enough that compression rarely impacts
performance. You might want to disable compression only if your cache is
stored on an already-compressed filesystem, where ccache's compression
would be redundant.

For configuration details, see [**compression**](#config_compression)
and [**compression_level**](#config_compression_level).

Use `ccache --show-compression` to display compression information.
Example output:

    Total data:           14.8 GB (16.0 GB disk blocks)
    Compressed data:      11.3 GB (30.6% of original size)
      Original size:      36.9 GB
      Compression ratio: 3.267 x  (69.4% space savings)
    Incompressible data:   3.5 GB

Notes:

- **Disk blocks**: The actual cache size accounting for filesystem block
  size. This should match the \"Cache size\" from `ccache --show-stats`.

- **Compressed data**: Result and manifest files stored in the cache.

- **Incompressible data**: Files stored without compression (due to
  [**file_clone**](#config_file_clone) or
  [**hard_link**](#config_hard_link) settings) or legacy files from
  older ccache versions.

- **Compression ratio**: Affected by
  [**compression_level**](#config_compression_level).

You can recompress cached data to different compression levels using
`ccache --recompress`. Only files with different compression levels than
the target will be recompressed.

# Cache statistics {#_cache_statistics}

`ccache --show-stats` shows a summary of statistics, including cache
size, cleanups (number of performed cleanups, either implicitly due to a
cache size limit being reached or due to explicit `ccache -c` calls),
overall hit rate, hit rate for
[direct](#_the_direct_mode)/[preprocessed](#_the_preprocessor_mode)
modes and hit rate for local and [remote
storage](#config_remote_storage).

The statistics counters are not used by ccache itself during builds.
This means that you can safely reset them at any time using
`ccache --zero-stats` without affecting the build process. For example,
you might reset them before a build so that `ccache --show-stats` will
only summarize the results from that specific build. Alternatively, you
can set [**stats_log**](#config_stats_log) before starting the build and
then run `ccache --show-log-stats` afterward to view build-specific
statistics. This approach allows the statistics counters to continue
tracking the entire lifetime of the cache while still giving you
detailed information for individual builds. Another advantage of
**stats_log** is that it collects statistics without interference from
other concurrent builds that access the same cache.

The summary also includes counters called "Errors" and "Uncacheable",
which are sums of more detailed counters. To see those detailed
counters, use the `-v`/`--verbose` flag. The verbose mode can show the
following counters:

+--------------------+--------------------------------------------------------+
| **Counter**        | **Description**                                        |
+====================+========================================================+
| Autoconf           | Uncacheable compilation or linking by an Autoconf      |
| compile/link       | test.                                                  |
+--------------------+--------------------------------------------------------+
| Bad compiler       | Malformed compiler argument, e.g. missing a value for  |
| arguments          | a compiler option that requires an argument or failure |
|                    | to read a file specified by a compiler option          |
|                    | argument.                                              |
+--------------------+--------------------------------------------------------+
| Called for linking | The compiler was called for linking, not compiling.    |
|                    | Ccache only supports compilation of a single file,     |
|                    | i.e. calling the compiler with the `-c` option to      |
|                    | produce a single object file from a single source      |
|                    | file.                                                  |
+--------------------+--------------------------------------------------------+
| Called for         | The compiler was called for preprocessing, not         |
| preprocessing      | compiling.                                             |
+--------------------+--------------------------------------------------------+
| Ccache disabled    | Ccache was disabled by a `ccache:disable` string in    |
|                    | the source code file.                                  |
+--------------------+--------------------------------------------------------+
| Could not use      | Preconditions for using [C++ modules](#_c_modules)     |
| modules            | were not fulfilled.                                    |
+--------------------+--------------------------------------------------------+
| Could not use      | Preconditions for using [precompiled                   |
| precompiled header | headers](#_precompiled_headers) were not fulfilled.    |
+--------------------+--------------------------------------------------------+
| Could not read or  | An input file could not be read or parsed (see the     |
| parse input file   | debug log for details).                                |
+--------------------+--------------------------------------------------------+
| Could not write to | The output path specified with `-o` could not be       |
| output file        | written to.                                            |
+--------------------+--------------------------------------------------------+
| Compilation failed | The compilation failed. No result stored in the cache. |
+--------------------+--------------------------------------------------------+
| Compiler check     | A compiler check program specified by                  |
| failed             | [**compiler_check**](#config_compiler_check)           |
|                    | (**CCACHE_COMPILERCHECK**) failed.                     |
+--------------------+--------------------------------------------------------+
| Compiler output    | One of the files expected to be produced by the        |
| file missing       | compiler was missing after compilation.                |
+--------------------+--------------------------------------------------------+
| Compiler produced  | The compiler's output file (typically an object file)  |
| empty output       | was empty after compilation.                           |
+--------------------+--------------------------------------------------------+
| Could not find the | The compiler to execute could not be found.            |
| compiler           |                                                        |
+--------------------+--------------------------------------------------------+
| Error hashing      | Failure reading a file specified by                    |
| extra file         | [**extra_files_to_hash**](#config_extra_files_to_hash) |
|                    | (**CCACHE_EXTRAFILES**).                               |
+--------------------+--------------------------------------------------------+
| Forced recache     | [**CCACHE_RECACHE**](#config_recache) was used to      |
|                    | overwrite an existing result.                          |
+--------------------+--------------------------------------------------------+
| Input file         | An input file was modified during compilation.         |
| modified during    |                                                        |
| compilation        |                                                        |
+--------------------+--------------------------------------------------------+
| Internal error     | Unexpected failure, e.g. due to problems               |
|                    | reading/writing the cache.                             |
+--------------------+--------------------------------------------------------+
| Missing cache file | A file was unexpectedly missing from the cache. This   |
|                    | only happens in rare situations, e.g. if one ccache    |
|                    | instance is about to get a file from the cache while   |
|                    | another instance removed the file as part of cache     |
|                    | cleanup.                                               |
+--------------------+--------------------------------------------------------+
| Multiple source    | The compiler was called to compile multiple source     |
| files              | files in one go. This is not supported by ccache.      |
+--------------------+--------------------------------------------------------+
| No input file      | No input file was specified to the compiler.           |
+--------------------+--------------------------------------------------------+
| Output to stdout   | The compiler was instructed to write its output to     |
|                    | standard output using `-o -`. This is not supported by |
|                    | ccache.                                                |
+--------------------+--------------------------------------------------------+
| Preprocessing      | Preprocessing the source code using the compiler's     |
| failed             | `-E` option failed.                                    |
+--------------------+--------------------------------------------------------+
| Unsupported code   | Code like the assembler `.incbin` directive was found. |
| directive          | This is not supported by ccache.                       |
+--------------------+--------------------------------------------------------+
| Unsupported        | A compiler option not supported by ccache was found.   |
| compiler option    |                                                        |
+--------------------+--------------------------------------------------------+
| Unsupported        | An environment variable not supported by ccache was    |
| environment        | set.                                                   |
| variable           |                                                        |
+--------------------+--------------------------------------------------------+
| Unsupported source | Source file (or an included header) has unsupported    |
| encoding           | encoding. ccache currently requires UTF-8-encoded      |
|                    | source code for MSVC when `msvc_utf8` is true.         |
+--------------------+--------------------------------------------------------+
| Unsupported source | A source language e.g. specified with `-x` was         |
| language           | unsupported by ccache.                                 |
+--------------------+--------------------------------------------------------+

# How ccache works {#_how_ccache_works}

Ccache detects when you're compiling the same code and reuses previously
stored output. It works by creating a unique hash (the "input hash")
from various information that affects the compilation. When the same
hash is encountered again, ccache can supply all the correct compiler
outputs from the cache.

For hashing, ccache uses [BLAKE3](https://blake3.io), a fast
cryptographic hash algorithm. For data integrity, cached data is
protected with [XXH3](https://xxhash.com) checksums to detect
corruption.

Ccache has two strategies for gathering the information used to create
cache lookup keys:

- **Preprocessor mode**: Ccache runs the preprocessor on the source code
  and hashes the result.

- **Direct mode**: Ccache hashes the source code and include files
  directly.

Direct mode is generally faster because it avoids the overhead of
running the preprocessor.

When direct mode doesn't find a cached result (cache miss), ccache falls
back to preprocessor mode unless **depend mode** is enabled. In depend
mode, ccache never runs the preprocessor, even on cache misses. See
*[The depend mode](#_the_depend_mode)* for details.

## Common hashed information {#_common_hashed_information}

The following information is always included in the hash:

- the extension used by the compiler for a file with preprocessor output
  (normally `.i` for C code and `.ii` for C++ code)

- the compiler's size and modification time (or other compiler-specific
  information specified by [**compiler_check**](#config_compiler_check))

- the name of the compiler

- the current directory (if [**hash_dir**](#config_hash_dir) is enabled)

- contents of files specified by
  [**extra_files_to_hash**](#config_extra_files_to_hash) (if any)

## The preprocessor mode {#_the_preprocessor_mode}

In the preprocessor mode, the hash is formed of the common information
and:

- the preprocessor output from running the compiler with `-E`

- the command line options except those that affect include files (`-I`,
  `-include`, `-D`, etc; the theory is that these command line options
  will change the preprocessor output if they have any effect at all)

- any standard error output generated by the preprocessor

Based on the hash, the cached compilation result can be looked up
directly in the cache.

## The direct mode {#_the_direct_mode}

In the direct mode, the hash is formed of the common information and:

- the input source file

- the compiler options

Based on the hash, a data structure called "manifest" is looked up in
the cache. The manifest contains:

- references to cached compilation results (object file, dependency
  file, etc) that were produced by previous compilations that matched
  the hash

- paths to the include files that were read at the time the compilation
  results were stored in the cache

- hash sums of the include files at the time the compilation results
  were stored in the cache

The current contents of the include files are then hashed and compared
to the information in the manifest. If there is a match, ccache knows
the result of the compilation. If there is no match, ccache falls back
to running the preprocessor. The output from the preprocessor is parsed
to find the include files that were read. The paths and hash sums of
those include files are then stored in the manifest along with
information about the produced compilation result.

There is a catch with the direct mode: header files that were used by
the compiler are recorded, but header files that were **not** used, but
would have been used if they existed, are not. To mitigate this problem,
ccache records whether directories specified with `-I` and similar exist
at the time of compilation, which handles most cases. Still, when ccache
checks if a result can be taken from the cache, it currently can't check
with 100% accuracy if the existence of a new header file should
invalidate the result. In practice, the direct mode is safe to use in
the absolute majority of cases.

The direct mode will be disabled if any of the following holds:

- [**direct_mode**](#config_direct_mode) is false

- a modification time of one of the include files is too new (needed to
  avoid a race condition)

- a compiler option not supported by the direct mode is used, for
  example:

  - a `-Wp,*` compiler option other than `-Wp,-MD,<path>`,
    `-Wp,-MMD,<path>`, `-Wp,-D<macro[=defn]>` or `-Wp,-U<macro>`

  - most uses of `-Xpreprocessor`

- the string `__TIME__` is present in the source code

## The depend mode {#_the_depend_mode}

If the depend mode is enabled, ccache will not use the preprocessor at
all. The hash used to identify results in the cache will be based on the
direct mode hash described above plus information about include files
read from the dependency list generated by MSVC with `/showIncludes`, or
the dependency file generated by other compilers with `-MD` or `-MMD`.

Advantages:

- The ccache overhead of a cache miss will be much smaller.

- Not running the preprocessor at all can be good if compilation is
  performed remotely, for instance when using distcc or similar; ccache
  then won't make potentially costly preprocessor calls on the local
  machine.

Disadvantages:

- The cache hit rate will likely be lower since any change to compiler
  options or source code will make the hash different. Compare this with
  the default setup where ccache will fall back to the preprocessor
  mode, which is tolerant to some types of changes of compiler options
  and source code changes.

- If `-MD` is used, the manifest entries will include system header
  files as well, thus slowing down cache hits slightly, just as using
  `-MD` slows down make. This is also the case for MSVC with
  `/showIncludes`.

- If `-MMD` is used, the manifest entries will not include system header
  files, which means ccache will ignore changes in them.

The depend mode will be disabled if any of the following holds:

- [**depend_mode**](#config_depend_mode) is false.

- The compiler is not generating dependencies using `-MD` or `-MMD` (for
  MSVC, `/showIncludes` is added automatically if not specified by the
  user).

# Handling of newly created source files {#_handling_of_newly_created_source_files}

If modification time (mtime) or status change time (ctime) of the source
file or one of the include files is equal to (or newer than) the time
that ccache was invoked, ccache disables caching completely. This is
done as a safety measure to avoid a race condition (see below). In
practice, this is only a problem when using file systems with very low
timestamp granularity. You can set [**sloppiness**](#config_sloppiness)
to **include_file_ctime,include_file_mtime** to opt out of the safety
measure.

For reference, the race condition mentioned above consists of these
events:

1.  A source code file is read by ccache and added to the input hash.

2.  The source code file is modified.

3.  The compiler is executed and reads the modified source code.

4.  Ccache stores the compiler output in the cache associated with the
    incorrect key (based on the unmodified source code).

# Cache debugging {#_cache_debugging}

To find out what information ccache actually is hashing, you can enable
the debug mode via the configuration option [**debug**](#config_debug)
or by setting `CCACHE_DEBUG` in the environment. This can be useful if
you are investigating why you don't get cache hits. Note that
performance will be reduced slightly.

When the debug mode is enabled, ccache will create up to five additional
files next to the object file:

+----------------------------------------------+---------+------------------------------------------+
| **Filename**                                 | **Debug | **Description**                          |
|                                              | level** |                                          |
+==============================================+=========+==========================================+
| `<objectfile>.<timestamp>.ccache-input-c`    | 2       | Binary input hashed by both the direct   |
|                                              |         | mode and the preprocessor mode.          |
+----------------------------------------------+---------+------------------------------------------+
| `<objectfile>.<timestamp>.ccache-input-d`    | 2       | Binary input only hashed by the direct   |
|                                              |         | mode.                                    |
+----------------------------------------------+---------+------------------------------------------+
| `<objectfile>.<timestamp>.ccache-input-p`    | 2       | Binary input only hashed by the          |
|                                              |         | preprocessor mode.                       |
+----------------------------------------------+---------+------------------------------------------+
| `<objectfile>.<timestamp>.ccache-input-text` | 2       | Human-readable combined diffable text    |
|                                              |         | version of the three files above.        |
+----------------------------------------------+---------+------------------------------------------+
| `<objectfile>.<timestamp>.ccache-log`        | 1       | Log for this object file.                |
+----------------------------------------------+---------+------------------------------------------+

The timestamp format is
`<year><month><day>_<hour><minute><second>_<microsecond>`.

If you only need the log file, set [**debug_level**](#config_debug)
(environment variable `CCACHE_DEBUGLEVEL`) to 1.

If [**debug_dir**](#config_debug_dir) (environment variable
`CCACHE_DEBUGDIR`) is set, the files above will be written to that
directory with full absolute paths instead of next to the object file.

In the direct mode, ccache uses the 160 bit BLAKE3 hash of the
"ccache-input-c" + "ccache-input-d" data (where **+** means
concatenation), while the "ccache-input-c" + "ccache-input-p" data is
used in the preprocessor mode.

The "ccache-input-text" file is a combined text version of the three
binary input files. It has three sections ("COMMON", "DIRECT MODE" and
"PREPROCESSOR MODE"), which is turn contain annotations that say what
kind of data comes next.

To debug why you don't get an expected cache hit for an object file, you
can do something like this:

1.  Enable `debug` (`CCACHE_DEBUG`).

2.  Build.

3.  Clean and build again.

4.  Compare the `<objectfile>.<timestamp>.ccache-input-text` files for
    the two builds. This together with the
    `<objectfile>.<timestamp>.ccache-log` files should give you some
    clues about what is happening.

# Compiling in different directories {#_compiling_in_different_directories}

When compiling the same source code in different directories, ccache
often can't share cached results if absolute paths become part of the
input hash. These paths appear in:

- preprocessed source code (when using `-g` for debug info or absolute
  paths in `-I` options)

- command-line arguments (absolute paths to source files or include
  directories)

- macro expansions (`__FILE__` macros and preprocessor warnings)

To enable cache sharing across different build directories for debug
builds (using `-g`), normalize debug paths e.g. with GCC option
`-fdebug-prefix-map=$PWD=.` (map current directory to relative) or
`-fdebug-compilation-dir=.` (set compilation directory). Alternatively,
set [**hash_dir**](#config_hash_dir) to `false` (disables directory
hashing).

For builds with absolute paths, set [**base_dir**](#config_base_dir) to
a common parent directory. Ccache will convert absolute paths under this
directory to relative paths before hashing.

For example, if projects are in `/home/user/projects`, set **base_dir**
to `/home/user/projects` or just `/home/user`.

# Precompiled headers {#_precompiled_headers}

Ccache has limited support for precompiled headers (PCH) with GCC and
Clang.

Required configuration:

1.  Set [**sloppiness**](#config_sloppiness) to
    `pch_defines,time_macros`

    - This is needed because ccache can't detect time macro usage or
      `#define` changes when using PCH.

    - Consider adding `include_file_mtime,include_file_ctime` for newly
      created files (see *[Handling of newly created source
      files](#_handling_of_newly_created_source_files)*).

2.  One of:

    - **GCC/Clang**: Use `-include header` (don't use `#include` in
      source; the filename must be sufficient to find the header).

    - **Clang only**: Use `-include-pch` with the generated PCH file.

    - **GCC only**: Add `-fpch-preprocess` when compiling.

3.  For Clang, add `-fno-pch-timestamp` to disable timestamp checks.

Troubleshooting:

- Without proper setup, ccache falls back to the non-precompiled header
  (if available).

- If no fallback exists, you'll see "Preprocessing failed" in
  statistics.

- Files using `#pragma once` instead of include guards may cause issues.

# C++ modules {#_c_modules}

Ccache does currently not support standard C++20 modules.

There is however limited support for "Clang modules" (the `-fmodules`
option) with these requirements:

- Set [**sloppiness**](#config_sloppiness) to `modules`.

- Enable both [**direct mode**](#_the_direct_mode) and [**depend
  mode**](#_the_depend_mode).

This is how it works:

- Ccache hashes `module.modulemap` files but ignores Clang's binary
  module cache.

- This works because identical `module.modulemap` files should produce
  compatible cached results.

:::: note
::: title
:::

The preprocessor mode doesn't provide enough information for module
support [**depend mode**](#_the_depend_mode). When using [the
preprocessor mode](#The preprocessor
mode) Clang does not provide enough information to allow hashing of
`module.modulemap` files.
::::

# Sharing a local cache {#_sharing_a_local_cache}

A group of developers can increase the cache hit rate by sharing a local
cache directory. To share a local cache without unpleasant side effects,
the following conditions should to be met:

- Use the same cache directory.

- Make sure that the configuration option
  [**hard_link**](#config_hard_link) is false (which is the default).

- Make sure that all users are in the same group.

- Set the configuration option [**umask**](#config_umask) to **002**.
  This ensures that cached files are accessible to everyone in the
  group.

- Make sure that all users have write permission in the entire cache
  directory (and that you trust all users of the shared cache).

- Make sure that the setgid bit is set on all directories in the cache.
  This tells the filesystem to inherit group ownership for new
  directories. The following command might be useful for this:

      find $CCACHE_DIR -type d | xargs chmod g+s

The reason to avoid the hard link mode is that the hard links cause
unwanted side effects, as all links to a cached file share the file's
modification timestamp. This results in false dependencies to be
triggered by timestamp-based build systems whenever another user links
to an existing file. Typically, users will see that their libraries and
binaries are relinked without reason.

You may also want to make sure that a base directory is set
appropriately, as discussed in a previous section.

# Sharing a cache on NFS {#_sharing_a_cache_on_nfs}

It is possible to put the cache directory on an NFS filesystem (or
similar filesystems), but keep in mind that:

- Having the cache on NFS may slow down compilation. Make sure to do
  some benchmarking to see if it's worth it.

- Ccache hasn't been tested very thoroughly on NFS.

A tip is to set [**temporary_dir**](#config_temporary_dir) to a
directory on the local host to avoid NFS traffic for temporary files.

It is recommended to use the same operating system version when using a
shared cache. If operating system versions are different then system
include files will likely be different and there will be few or no cache
hits between the systems. One way of improving cache hit rate in that
case is to set [**sloppiness**](#config_sloppiness) to
**system_headers** to ignore system headers.

An alternative to putting the main cache directory on NFS is to set up a
[remote storage](#config_remote_storage) file cache.

# Using ccache with other compiler wrappers {#_using_ccache_with_other_compiler_wrappers}

The recommended way of combining ccache with another compiler wrapper
(such as "distcc") is by letting ccache execute the compiler wrapper.
This is accomplished by defining
[**prefix_command**](#config_prefix_command), for example by setting the
environment variable `CCACHE_PREFIX` to the name of the wrapper (e.g.
`distcc`). Ccache will then prefix the command line with the specified
command when running the compiler. To specify several prefix commands,
set [**prefix_command**](#config_prefix_command) to a space-separated
list of commands.

Unless you set [**compiler_check**](#config_compiler_check) to a
suitable command (see the description of that configuration option), it
is not recommended to use the form `ccache anotherwrapper compiler args`
as the compilation command. It's also not recommended to use the
masquerading technique for the other compiler wrapper. The reason is
that by default, ccache will in both cases hash the mtime and size of
the other wrapper instead of the real compiler, which means that:

- Compiler upgrades will not be detected properly.

- The cached results will not be shared between compilations with and
  without the other wrapper.

Another minor thing is that if
[**prefix_command**](#config_prefix_command) is used, ccache will not
invoke the other wrapper when running the preprocessor, which increases
performance. You can use
[**prefix_command_cpp**](#config_prefix_command_cpp) if you also want to
invoke the other wrapper when doing preprocessing (normally by adding
`-E`).

# Caveats {#_caveats}

- The direct mode fails to pick up new header files in some rare
  scenarios. See *[The direct mode](#_the_direct_mode)* above.

# Troubleshooting {#_troubleshooting}

## General {#_general}

To understand what ccache is doing you can enable debug logging by
setting [**debug**](#config_debug) to `true` or using the environment
variable `CCACHE_DEBUG=1`. See *[Cache debugging](#_cache_debugging)*
for details.

You can also use `ccache -s` to view cache hit rates, miss reasons and
other performance metrics.

## Performance {#_performance}

Ccache is designed to work well with minimal configuration, but you can
optimize performance further:

- Place the cache directory on fast storage (SSD preferred).

- Ensure sufficient RAM so cached files stay in the filesystem cache.

- Consider using [remote storage](#config_remote_storage) for sharing
  the cache.

To monitor cache effectiveness, compare `ccache -s` output before and
after builds to identify issues.

If "preprocessed cache hits" increases instead of "direct cache hits",
ccache is falling back to the slower preprocessor mode. Causes include:

- source code changes that don't affect preprocessor output

- changes to include-related options (`-I`, `-include`, `-D`) that don't
  change the actual preprocessed code

- using unsupported preprocessor options like `-Xpreprocessor` or
  `-Wp,*` (except `-Wp,-MD,<path>`, `-Wp,-MMD,<path>`, `-Wp,-D<define>`)

- first compilation after changing [**base_dir**](#config_base_dir)

- include files with timestamps newer than ccache startup (see
  *[Handling of newly created source
  files](#_handling_of_newly_created_source_files)*)

- code containing `__TIME__`, `__DATE__`, or `__TIMESTAMP__` forces
  preprocessor mode (if these macros aren't actually used or you don't
  need current values, set [**sloppiness**](#config_sloppiness) to
  `time_macros`)

- input file path changes (affects `__FILE__` macro expansion)

If identical code doesn't produce cache hits these are some possible
causes:

- time/date macros or generated code with timestamps/build counters

- cache cleanup due to size limits

- environment differences affecting compilation

Common error counters:

- "Multiple source files": The compiler was called with multiple source
  files at once (not supported by ccache).

- "Unsupported compiler option": Enable debug logging to see which
  option was rejected.

- "Preprocessing failed": Could indicate precompiled header issues (see
  *[Precompiled headers](#_precompiled_headers)*).

- "Could not use precompiled header": See *[Precompiled
  headers](#_precompiled_headers)* for setup requirements.

- "Could not use modules": See *[C++ modules](#_c_modules)* for
  configuration needs and check which compiler option was rejected.

## Corrupt object files {#_corrupt_object_files}

It should be noted that ccache is susceptible to general storage
problems. If a bad object file sneaks into the cache for some reason, it
will of course stay bad. Some possible reasons for erroneous object
files are bad hardware (disk drive, disk controller, memory, etc), buggy
drivers or file systems, a bad
[**prefix_command**](#config_prefix_command) or compiler wrapper. If
this happens, the easiest way of fixing it is this:

1.  Build so that the bad object file ends up in the build tree.

2.  Remove the bad object file from the build tree.

3.  Rebuild with `CCACHE_RECACHE` set.

An alternative is to clear the whole cache with `ccache -C` if you don't
mind losing other cached results.

There are no reported issues about ccache producing broken object files
reproducibly. That doesn't mean it can't happen, so if you find a
repeatable case, please report it.

# More information {#_more_information}

Credits, mailing list information, bug reporting instructions, source
code, etc, can be found on ccache's web site: <https://ccache.dev>.

# Author {#_author}

Ccache was originally written by Andrew Tridgell and is currently
developed and maintained by Joel Rosdahl. See AUTHORS.txt or
AUTHORS.html and <https://ccache.dev/credits.html> for a list of
contributors.
