From Gentoo Wiki
Jump to:navigation Jump to:search
This page contains changes which are not marked for translation.

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.


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


Install dev-util/ccache:

root #emerge --ask dev-util/ccache


Initial setup

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

# May be needed to workaround a bug, but has some security implications

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 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.
hash_dir = false

# Preserve cache across GCC rebuilds and
# introspect GCC changes through GCC wrapper.
# We use -dumpversion here instead of -v,
# see
compiler_check = %compiler% -dumpversion

# 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


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

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:

  • To show 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
  • To drop 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.


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.

See also