docs/tips_and_troubleshooting/ci-ccache.md

### ccache in CI: troubleshooting and controls

This document applies to GitHub Actions CI only.

The CI uses ccache to accelerate C/C++ builds. The cache is stored via GitHub
Actions Cache with weekly rotation, and ccache validates every object retrieval
for correctness.

Common tasks (CI)

-   Disable ccache for a run:
    -   Add `[no-ccache]` in the commit message, or
    -   Manually dispatch the `Tests` workflow with `disable_ccache=true`.
-   Force cache rotation for a run:
    -   Manually dispatch `Tests` with `cache_suffix` set to any string (e.g., a
        short hash). This appends to the cache key so a new cache archive is
        created.

When master builds fail

-   The Linux job automatically retries without ccache if the initial build
    fails on `master`.

Debugging tips (CI)

-   Print stats: use the existing `ccache -s` step to inspect hit/miss rates.
-   Compiler/version changes: protected by `CCACHE_COMPILERCHECK=content`, so
    caches are automatically missed on compiler changes.
-   Time macros: CI uses `CCACHE_SLOPPINESS=time_macros`. If your build embeds
    `__DATE__`/`__TIME__`, be aware objects may be reused across runs for these
    macros.

Notes

-   External cache keys rotate weekly; ccache still validates per-object for
    correctness.