Configure Ccache Remote Storage

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 but say on another machine. It is designed to produce the same compiler output as a normal compiler (gcc, clang, etc) — the difference is significantly faster build times, especially with macros/templates and large projects.

Ccache supports C, C++, Assembler, CUDA, Objective-C, and Objective-C++.

Ccache can use both local storage and remote storage. Local cache helps a single machine; Ccache remote storage lets teams share compiled objects across machines.

For each compiler invocation, Ccache computes an input hash from information that affects the result (compiler identity, options, source and include content, and more), then looks up that key in the cache. On a cache miss Ccache runs the real compiler (slow) and stores the outputs; on a cache hit Ccache restores outputs (fast) and skips the slow compile.

Schematic example: say a first build of the libs/parser module (several C++ translation units) misses the cache, spends ~1 minute compiling, and stores each resulting object file under its computed key:

libs/parser  (module)

  Inputs
  +----------------------+
  | parser.cpp           |
  | lexer.cpp            |
  | ast.cpp              |
  | token.cpp            |
  | ...                  |
  | headers, flags, ...  |
  | compiler identity    |
  +----------+-----------+
             |
             v
  Compute cache key per .cpp
             |
             v
  +----------------------+
  | Ccache               |
  | keys: b7e2... / ...  |
  | status: MISS         |
  +----------+-----------+
             |
             v
  Compile module (~1m)
             |
             v
  Outputs: parser.o, lexer.o,
           ast.o, token.o, ...
             |
             v
  Store each .o under its key

Later builds with the same inputs reuse those entries. Ccache computes the same cache keys, hits the Remote Ccache storage, and restores the module's object files in say ~100ms instead of compiling for ~1 minute — so that part of the build graph finishes almost immediately:

libs/parser  (same inputs)

  Inputs unchanged
  parser.cpp · lexer.cpp · ast.cpp · token.cpp · ...
             |
             v
  Same cache keys per .cpp
             |
             v
  +----------------------+
  | Ccache               |
  | keys: b7e2... / ...  |
  | status: HIT          |
  +----------+-----------+
             |
             v
  Restore module .o files (~100ms)
             |
             v
  Skip ~1m compile
  Build continues sooner

Remote Ccache storage lets teams share compiled objects across engineer workstations, CI, and AI agent environments.

CI, having a more reproducible and controlled environment, typically both reads from and writes to the shared remote storage. Engineers and AI agents read those objects without uploading new entries.

That keeps the cache warm from reproducible CI builds while reducing repeated compilation on other machines.

Ccache reuses an object only when compiler inputs and relevant configuration match. Keep compiler versions, flags, source inputs, and other build environment details consistent when sharing a cache.

Instead of recompiling the same translation units on every machine, ccache restores cached object files — turning builds that took minutes into cached builds that finish in seconds when hit rates are high.

After CI populates Ccache Remote Storage, a clean rebuild on another machine can resolve many slow and resource heavy compiles from cache. In a typical scenario:

First build (CI populates remote storage — ~10 minutes):

$ ccache --zero-stats
$ make -j8

[  5%] Building CXX object src/parser.cpp.o
[ 12%] Building CXX object src/lexer.cpp.o
[ 28%] Building CXX object src/ast/*.cpp.o
...
[100%] Linking CXX executable app

real    10m4.120s

$ ccache --show-stats
Cacheable calls:    842 /  842
Hits:                 0 /  842 (0.00%)
Misses:             842 /  842 (100.0%)

Subsequent build (engineer, AI agent, or fresh CI agent — ~12 seconds):

$ ccache --zero-stats
$ make clean && make -j8

[  5%] Building CXX object src/parser.cpp.o
[ 12%] Building CXX object src/lexer.cpp.o
[ 28%] Building CXX object src/ast/*.cpp.o
...
[100%] Linking CXX executable app

real    0m12.340s

$ ccache --show-stats
Cacheable calls:    842 /  842
Hits:               831 /  842 (98.7%)
Misses:              11 /  842 (1.31%)

Ccache Remote Storage is especially valuable in ephemeral, autoscalable CI environments, where CI agents are often recreated without durable local disk state.

It also tremendously helps in actively developed projects where CI continuously warms the shared Ccache Remote Storage for the whole team as the codebase evolves with each commit.

Install Ccache, then route compiler invocations through it. Official run modes include prefixing the compiler or masquerading via PATH. For project builds, set your build system to launch the compiler through Ccache.

Common project-level options:

# CMake
cmake -D CMAKE_C_COMPILER_LAUNCHER=ccache       -D CMAKE_CXX_COMPILER_LAUNCHER=ccache       ...

# Make
make CC="ccache gcc" CXX="ccache g++"

Once compiles run through Ccache, the local cache works automatically. To share results across machines, configure Ccache Remote Storage with BuildFetch Cache (next sections).

Official Ccache Remote Storage documentation: https://ccache.dev/manual/latest.html#_remote_storage_backends.

Ccache remote storage is configured with environment variables (or the equivalent keys in ccache.conf). BuildFetch Projects use CCACHE_REMOTE_STORAGE and CCACHE_NAMESPACE as shown on the Project Cache Setup tab.

Generate Tokens

We recommend generating a cache:readwrite Token for CI and cache:readonly Token(s) for engineer machines.

Generally, there are two ways to manage engineer Tokens:

• For simpler setups, issuing and rotating a single cache:readonly Token could be sufficient.
• For precise access control, each engineer should register in BuildFetch, then issue and rotate their own individual cache:readonly Token(s).

Generating cache:readwrite Tokens requires Project/Org Admin scope.

For Open Source Projects, we recommend not storing a cache:readonly Token in publicly accessible code because it could lead to misuse and unintended exhaustion of monthly Project limits.

Configure Ccache with the environment variables below before running your builds. Replace the placeholder values with the remote cache URL and Project ID shown in the Project Cache Setup tab:

export CCACHE_REMOTE_STORAGE="https://token-auth:<generated-token>@<project-cluster-cache-public-url>/<project-id>/ccache @layout=flat"
export CCACHE_NAMESPACE="<project-id>"

The CCACHE_REMOTE_STORAGE value contains the authenticated BuildFetch Project URL and uses the @layout=flat option so keys are stored under a flat path layout. Set CCACHE_NAMESPACE to the Project ID so remote objects use the Project namespace.

Keep the generated Token in your CI secret store or local credential environment; do not commit it to source control. On engineer machines that should only read, you can append the read-only property to CCACHE_REMOTE_STORAGE or set CCACHE_READONLY.

Export these variables in the shell or CI environment used for compilation, then run your build through ccache. Use statistics to confirm the cache is active:

ccache --zero-stats
make -j8
ccache --show-stats

The exact build command can differ for your Project; the important requirement is that compiler invocations run through Ccache with remote storage configured.