Configure Ccache Remote Storage

What is Ccache

Ccache is a compiler wrapper that speeds up builds by caching compiler outputs and reusing them across different machines.

Ccache includes support for caching the compilation of C, C++, Assembler, CUDA, Objective-C, and Objective-C++.

Ccache can use both Local storage and Remote Storage. Local Storage helps a single machine, Remote Storage lets teams share compilation cache across machines: CI & developer environments.

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

Schematic example: say a first build of the libs/parser module misses the cache, spends time 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 storage, and restores the module's object files in seconds.

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

Share Ccache Between Machines

Remote Ccache Storage

For Ccache outputs to be shared across machines, Ccache Remote Storage must be configured. Local cache only helps on a single machine.

BuildFetch Cache natively implements Ccache HTTP remote storage protocol and acts as an extremely fast shared remote cache for CI, engineers, and AI agents.

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, which turns builds that took minutes into cached builds that finish in seconds when hit rates are high.

Cached Ccache Build Example

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, where CI populates remote storage:

$ 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, whether by an engineer, AI agent, or fresh CI agent, can finish in 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%)

When Ccache helps most

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.

Enable Ccache

Install Ccache, then route compiler invocations through it. Official run modes include prefixing the compiler or masquerading via PATH.

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.

Configure Ccache Remote Storage

Before setting up remote cache, ensure you have created BuildFetch Project and Token(s).

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 Project Cache Setup tab will provide:

• CCACHE_REMOTE_STORAGE
• CCACHE_NAMESPACE

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>@cache.region.buildfetch.com/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