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.
  • Install ccache 4.13.6 or newer and ccache-storage-http 0.8 or newer before the BoringCache step. For Docker tool caches, install both in the image stage that runs the compiler.
  • The Action checks both before it starts cache setup. The next CLI also checks them before a wrapped boringcache ccache build and looks for the helper where ccache does: ccache's libexec directories, the ccache directory, then PATH.
  • 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.

Compiler forecasts and resources

Forecast a prepared target

The next CLI adds an optional --forecast flag for Linux GNU C and C++ builds configured with CMake and Ninja. Prepare a fresh, disposable build tree with CMAKE_EXPORT_COMPILE_COMMANDS=ON, ccache as the compiler launcher, and the target's generated inputs already present. Pass an explicit target through ninja -C BUILD TARGET or cmake --build BUILD --target TARGET. The CLI returns native hit, miss and unknown counts without executing the wrapped target. --forecast-output PATH also writes the per-compilation predictions as JSON.

Forecasting can run the native preprocessor and download complete cached objects into that planning tree. Use matching sources, compiler, flags and cache settings for the later build. Native ccache counters include these probes, while cache entries remain read-only. Unsupported native lookups remain unknown; failed shared-cache access stops the forecast without running the target or writing a successful prediction file. --on-demand is incompatible with forecasting. This does not analyze an arbitrary Dockerfile, select a machine, or stop and restart a build. Inside a container, invoke it in the matching prepared Linux build environment.

Measure compiler misses

The separate --compiler-resources option runs a fresh prepared CMake/Ninja target and records CPU time and maximum process RSS for successful compiler misses. CPU includes the compiler and its waited descendants. RSS is the largest accounted process, not the whole build's peak memory. Generation, separate preprocessing, linking and cache transfers are outside those measurements.

Warm hits have no compiler samples. Missing measurements stay absent rather than implying zero cost, and incomplete coverage is reported explicitly. --fail-on-cache-error also fails a successful build command when requested resource evidence is incomplete. If the cache proxy cannot start, the target does not run unmeasured. These optional CLI capabilities are not yet released and do not add an Action input or a machine recommendation.

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@1781572d7b3ec5aef652f8ba479b981439b2776b # v1.48.2
  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 builds the same upstream commits with BoringCache and GHA Cache on the same runner classes.

OBS Studio

ccache

Benchmark →

Video recording and live streaming application in C and C++.

Average restore, build and save · lower is better

GitHub runner

4 vCPU · 16 GB · Ubuntu 26.04 x86-64

BoringCache
1 min 52 s 28 builds
GHA Cache
2 min 3 s 28 builds
Same CPU model

Builds of one commit can land on different CPU models. These ratios use only the build pairs where both caches ran on the same model; above 1.00× means BoringCache's total time over those pairs was lower.

GHA Cache vs BoringCache
1.28× · 11 of 28
6 CPU models recorded
BoringCache · Remote storage
AMD EPYC 7763 (15 builds) · AMD EPYC 9V45 (5 builds) · AMD EPYC 9V74 (5 builds) · Intel Xeon 6973P-C (2 builds) · Intel Xeon Platinum 8573C (1 build)
GHA Cache · Local cache directory restored and saved by actions/cache
AMD EPYC 7763 (14 builds) · AMD EPYC 9V45 (5 builds) · AMD EPYC 9V74 (3 builds) · Intel Xeon Platinum 8573C (3 builds) · Intel Xeon Platinum 8370C (2 builds) · Intel Xeon 6973P-C (1 build)

Cache hits

BoringCache · GitHub runner · 4 vCPU

96.2% of 16,612 lookups over 28 builds

Served from the runner
Under 1 ms per read
Read from cache
4.23 GB

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.