Skip to content
Documentation

Docs / Adapter commands / ccache

ccache adapter

Keep ccache in your existing compiler path. The adapter adds shared remote storage, safe read and write behavior, and native statistics.

Command
boringcache ccache
Protocol
ccache HTTP remote storage through a local helper
Action
mode: ccache

How the adapter works

Keep your compiler launcher

Your existing build setup keeps compiler and launcher selection. BoringCache adds the remote-cache storage path and safe read and write behavior.

Remote reuse across runners

A fresh runner can read compiler results published by a trusted CI or local build when ccache's own keys match.

Native ccache activity

Keep ccache's own compile requests, remote hits, misses, timeouts, and errors visible.

Set up ccache

Configure ccache as the compiler launcher in the project, keep the tag and build command in .boringcache.toml, then use boringcache ccache locally or mode: ccache in BoringCache One. The adapter does not rewrite CC or CXX.

[adapters.ccache]
tag = "cpp-cache"
command = ["cmake", "--build", "build"]

# Keep CMAKE_C_COMPILER_LAUNCHER=ccache
# and CMAKE_CXX_COMPILER_LAUNCHER=ccache in the project.
# Run: boringcache ccache

Before the first run

  • Configure ccache as the compiler launcher in CMake, Meson, Make, or the project's existing build setup.
  • Do not expect the adapter to rewrite CC or CXX.
  • Measure the complete build; remote compiler hits do not remove configure, link, or test time.

Use the same adapter in GitHub Actions

The Action prepares remote ccache storage for later workflow steps. Keep compiler and launcher selection in your existing build setup.

.github/workflows/ci.yml 
- uses: boringcache/one@f0fb9b2d926a32b10c543e92093ba00c5a291b79 # v1.33.0
  with:
    trust-policy: auto
    mode: ccache

- run: cmake --build build

Approve the repository through Connect CI and grant the job contents: read and id-token: write. The Action uses that Machine connection. Pull requests restore by default; trusted jobs may publish. See the authentication example in the GitHub Actions reference for scoped credentials when OIDC is unavailable.

GitHub Actions reference

Benchmarks

OBS Studio · 447 of 578 compiler requests reused.

77%

Compiler results reused

447 of 578 compiler requests hit the shared cache in an OBS Studio build.

Open run →
ccache cache page All benchmarks

Tool reference

Check the tool's own reference when you need cache-key rules, build settings, or version-specific behavior.

All adapter commands

Compare every supported command, protocol, and Action mode in one place.

Adapter command index →

Need help or found something unclear? Open an issue or browse the CLI repo.