Skip to content

docs: document cross-run CI cache strategy for fbuild consumers #152

Description

@zackees

Problem

After #146, #148, #149, and #150 land, fbuild's build cache will survive tar-extract and (where zccache allows) cross-runner restore. Consumers (FastLED master, downstream projects) need a canonical doc describing:

  1. Which directories to cache:

    • ~/.fbuild/ — toolchain + daemon state
    • \${{ steps.fbuild-setup.outputs.zccache-store-path }} — per-TU objects
    • <project>/.build/pio/<board>/ — per-project build outputs + fingerprint
  2. Cache key composition: runner.os, runner.arch, fbuild version hash, board. Do not include workspace path.

  3. Expected cold vs warm numbers (from [META] Fastest possible FastLED examples CI rebuild — profile + benchmark #112 final iter).

  4. Invalidation pattern: CACHE_BUST env var for manual busts; version-prefix (v1, v2) for schema changes.

  5. Common pitfalls:

Sub-task of #147.

Deliverable

docs/CI_CACHE.md plus a link from docs/CLAUDE.md's "Other docs" section. Include a copy-pasteable actions/cache block for the common case (single-board, same runner image).

Out of scope

  • Caching strategy for non-GitHub-Actions CI (GitLab, CircleCI). Those can follow the same directory list but the YAML isn't portable.

Related

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationpriority: p2Valuable later follow-up after core path is working

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions