ccache is a fast C/C++ compiler cache, which speeds up recompilations of the same code. It is often used while diagnosing bugs in the packaging process, to reduce time wasted on compilation. See also package build tools.

Contents

  1. Usage advice
    1. Choose a good ccache directory
    2. Configure ccache
    3. Ensure ccache symlinks are present

Usage advice

Choose a good ccache directory

ccache stores files in $CCACHE_DIR, or $HOME/.cache/ccache/ if that environment variable is missing. This section discusses some reasons you might want to specify your own $CCACHE_DIR.

Your compilations may not have a shared $HOME/.cache/ccache/ directory. For example, package build tools generally create a new build environment each time, including a new $HOME directory. If so, create a shared directory and look for ccache instructions in your packaging tool's documentation.

If you compile a lot of programs, or those programs are quite large, your cache directory might use a lot of disk space. Depending on your disk layout, it could outgrow the space available in $HOME. For example, if you run Linux on a small SSD that's perpetually full up, but you also have a large external disk for storage, you could put your cache directory on the external disk instead.

Conversely, if you work on one program at a time and call ccache --clear when you're done with each program, you can put your cache in a tmpfs so files appear in the filesystem but are actually just saved in memory. That can be much faster, but uses more memory and won't survive a reboot. Since trixie, /tmp is a tmpfs by default, so this just means setting CCACHE_DIR=/tmp/ccache.

/!\ If you set a custom cache directory, make sure it exists and has the right permissions before using it. For example, packaging tools usually need to bind-mount the directory when creating an environment, and usually run as a user who can't write to your home directory.

Configure ccache

ccache has several configuration options that might help improve your workflow. In particular, cache size management can help avoid filling up your tmpfs.

ccache looks in several locations for your config file, including $CCACHE_DIR/ccache.conf when that environment variable is defined. $CCACHE_DIR/ccache.conf is particularly useful when using build tools, because the configuration file will be available with no extra configuration.

ccache can be either be called explicitly (ccache gcc foo.c) or implicitly (PATH="/usr/lib/ccache:$PATH" gcc foo.c). To see how the latter works, do ls /usr/lib/ccache/.

/usr/lib/ccache should be maintained automatically when packages are installed and removed, but 632779 tracks cases where that doesn't work. You can work around this issue by calling /usr/sbin/update-ccache-symlinks manually to update the relevant files.

If you are using ccache with build tools, you might want to call /usr/sbin/update-ccache-symlinks inside each new container you create, especially if you're building for older versions of Debian which might do the wrong thing in more cases.