ccache

Resources

ccache helps avoid repeated recompilation for the same C and C++ object files by fetching result from a cache directory.

Compiler cache is typically useful for:

Developers who rebuild the same/similar codebase multiple times and use /etc/portage/patches to test patches.
Users who frequently play with USE-flag changes and end up rebuilding the same packages multiple times.
Users who use live ebuilds extensively.
Installing very big ebuilds, such as Chromium or LibreOffice, without fear of losing multiple hours of code compilation due to a failure.

Installation

USE flags

USE flags for dev-util/ccache Fast compiler cache

`doc`	Add extra documentation (API, Javadoc, etc). It is recommended to enable per package instead of globally
`redis`	Enable Redis backend for storage via dev-libs/hiredis
`static-c++`	Avoid dynamic dependency on gcc's libstdc++.
`test`	Enable dependencies and/or preparations necessary to run tests (usually controlled by FEATURES=test but can be toggled independently)
`verify-sig`	Verify upstream signatures on distfiles

Data provided by the Gentoo Package Database · Last update: 2024-03-28 05:04 More information about USE flags

Emerge

Install dev-util/ccache:

root #emerge --ask dev-util/ccache

Configuration

Initial setup

Warning
Using ccache globally is not recommended as it will saturate the cache and have few cache hits! Enable it instead for specific packages.

Simply enable ccache support in make.conf:

FILE /etc/portage/make.conf

FEATURES="ccache"
CCACHE_DIR="/var/cache/ccache"

# May be needed to workaround a bug, but has some security implications
# https://bugs.gentoo.org/492910
#CCACHE_UMASK="0002"

Done! From now on, all builds will try to reuse object files from the cache at /var/cache/ccache.

Enabling ccache for certain packages

See /etc/portage/package.env.

ccache.conf

ccache will search /etc/ccache.conf as well as ${CCACHE_DIR}/ccache.conf for its configuration file.

Example config:

FILE /var/cache/ccache/ccache.conf

# Maximum cache size to maintain
max_size = 100.0G

# Allow others to run 'ebuild' and share the cache.
umask = 002

# Don't include the current directory when calculating
# hashes for the cache. This allows re-use of the cache
# across different package versions, at the cost of
# slightly incorrect paths in debugging info.
# https://ccache.dev/manual/4.4.html#_performance
hash_dir = false

# Preserve cache across GCC rebuilds and
# introspect GCC changes through GCC wrapper.
#
# We use -dumpversion here instead of -v,
# see https://bugs.gentoo.org/872971.
compiler_check = %compiler% -dumpversion

# I expect 1.5M files. 300 files per directory.
cache_dir_levels = 3

# Logging setup is optional
# Portage runs various phases as different users
# so beware of setting a log_file path here: the file
# should already exist and be writable by at least
# root and portage. If a log_file path is set, don't
# forget to set up log rotation!
# log_file = /var/log/ccache.log
# Alternatively, log to syslog
# log_file = syslog

Compression

ccache has the ability to perform compression on content. To enable it and set the compression level, edit ccache.conf:

FILE /var/cache/ccache/ccache.conf

compression = true
compression_level = 1

Man page

Manual page for dev-util/ccache (see man ccache) is a great source of various knobs to make caching more robust and aggressive.

General notes

Note
This section is for using ccache outside of Portage and ebuilds.

ccache works by prepending /usr/lib/ccache/bin to PATH variable:

user $ls -l /usr/lib/ccache/bin

...
c++ -> /usr/bin/ccache
c99 -> /usr/bin/ccache
x86_64-pc-linux-gnu-c++ -> /usr/bin/ccache
...

FEATURES="ccache" triggers the same behavior in Portage.

ccache may also be enabled for the current user and reuse the same cache directory:

FILE ~/.bashrc

export PATH="/usr/lib/ccache/bin${PATH:+:}${PATH}"
export CCACHE_DIR="/var/cache/ccache"

Useful variables and commands

Some variables:

Variable CCACHE_DIR points to cache root directory.
Variable CCACHE_RECACHE allows evicting old cache entries with new entries:

root #CCACHE_RECACHE=yes emerge --oneshot cat/pkg

See man ccache for many more variables.

Some commands:

Command ccache -s shows cache hit statistics:

user $CCACHE_DIR=/var/cache/ccache ccache -s

cache directory                     /var/cache/ccache
primary config                      /var/cache/ccache/ccache.conf
secondary config      (readonly)    /etc/ccache.conf
stats zero time                     Fri Sep  7 07:24:24 2018
cache hit (direct)                114988
cache hit (preprocessed)           38254
cache miss                        246428
cache hit rate                     38.34 %
...
files in cache                    603419
cache size                          16.9 GB
max cache size                     100.0 GB

Command ccache -C drops all caches:

user $CCACHE_DIR=/var/cache/ccache/ ccache -C

See man ccache for many more commands.

Gentoo specifics/gotchas

gcc is a wrapper

To pass through a binary, the following entry is suggested for ccache.conf:

FILE ccache.conf

compiler_check = %compiler% -v

Also, -v has a nice side-effect of not invalidating the cache if compiler itself was rebuilt without version changes.

Caveats

Before using advanced ccache options, make sure it's understood what is being used as a cache key by ccache. By default these are:

Timestamp and size of a compiler binary (beware of shell and binary wrappers)
Compiler options used
Contents of a source file
Contents of all include files used for compilation

For more detailed information about caveats to ccache usage, refer to the ccache manual.