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%)

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

Cache Access

Use a cache:readonly Token by default on developer and AI agent machines. Trusted environments like CI should use a cache:readwrite Token and explicitly enable uploads.

For Token management, rotation, and Open Source guidance, see Set up BuildFetch Cache Project.

Read-only

Configure the remote backend with the read-only property. Local ccache storage remains writable:

export CCACHE_REMOTE_STORAGE="https://token-auth:<generated-token>@cache.region.buildfetch.com/project-id/ccache @layout=flat read-only"
export CCACHE_NAMESPACE="<project-id>"

Read-write

Remove the read-only property:

export CCACHE_REMOTE_STORAGE="https://token-auth:<generated-token>@cache.region.buildfetch.com/project-id/ccache @layout=flat"
export CCACHE_NAMESPACE="<project-id>"

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

See Also

• Ccache Remote Storage Backends
• Ccache Run Modes
• BuildFetch Cache Architecture
• BuildFetch Cache Pricing