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.
Getting started
On this page
j / k move between sections.
Docs / Adapter commands / ccache
Keep ccache in your existing compiler path. The adapter adds shared remote storage, safe read and write behavior, and native statistics.
Your existing build setup keeps compiler and launcher selection. BoringCache adds the remote-cache storage path and safe read and write behavior.
A fresh runner can read compiler results published by a trusted CI or local build when ccache's own keys match.
Keep ccache's own compile requests, remote hits, misses, timeouts, and errors visible.
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
boringcache ccache build and looks for the helper where ccache does: ccache's libexec directories, the ccache directory, then PATH.
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.
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.
The Action prepares remote ccache storage for later workflow steps. Keep compiler and launcher selection in your existing build setup.
- 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.
OBS Studio builds the same upstream commits with BoringCache and GHA Cache on the same runner classes.
ccache
Benchmark →Video recording and live streaming application in C and C++.
Average restore, build and save · lower is better
4 vCPU · 16 GB · Ubuntu 26.04 x86-64
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.
BoringCache · GitHub runner · 4 vCPU
96.2% of 16,612 lookups over 28 builds
Check the tool's own reference when you need cache-key rules, build settings, or version-specific behavior.
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.
We use cookies to understand how people use BoringCache. Privacy policy