This is Gentoo's testing wiki. It is a non-operational environment and its textual content is outdated.
Please visit our production wiki at https://wiki.gentoo.org
Ccache
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
Emerge
root #
emerge --ask dev-util/ccache
Configuration
Initial setup
Create the cache directory:
root #
mkdir -p /gentoo/ccache
root #
chown root:portage /gentoo/ccache
root #
chmod 2775 /gentoo/ccache
Set initial configuration file:
/gentoo/ccache/ccache.conf
# Maximum cache size to maintain max_size = 100.0G # Allow others to run 'ebuild' and share the cache. umask = 002 # Preserve cache across GCC rebuilds and # introspect GCC changes through GCC wrapper. compiler_check = %compiler% -v # I expect 1.5M files. 300 files per directory. cache_dir_levels = 3
Enable ccache support in make.conf:
/etc/portage/make.conf
FEATURES="${FEATURES} ccache" CCACHE_DIR="/gentoo/ccache"
Done! From now on all builds will try to reuse object files from /gentoo/ccache cache.
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
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.
You can also enable ccache for your current user and reuse the same cache directory:
~/.bashrc
export PATH="/usr/lib/ccache/bin${PATH:+:}$PATH" export CCACHE_DIR="/gentoo/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=/gentoo/ccache ccache -s
cache directory /gentoo/ccache primary config /gentoo/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=/gentoo/ccache/ ccache -C
See man ccache for many more commands.
Gentoo specifics/gotchas
gcc is a wrapper
For sys-devel/gcc-config before 2.0 gcc used to be a wrapper binary. This means by default ccache is not safe to use and leads to errors like bug #640958. sys-devel/gcc-config-2.0 will fix it.
To pass through a binary I suggest using
ccache.conf
compiler_check = %compiler% -v
in all your ccache.conf files. -v also has a nice side-effect of not invalidating your cache if compiler itself was rebuilt without version changes.
Caveats
Before using advanced ccache options make sure you understand 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