Cross-run framework artifact cache (setup-fbuild + content-addressed core/)

[zackees]

Summary

Each consumer CI run (e.g. FastLED's per-board workflows) pays the full cold-cache framework compile cost — currently ~24 min on esp32-arduino — because the setup-fbuild action caches $RUNNER_TEMP/fbuild-cache but the framework build artifacts (core/*.o, core/lib<env>.a) live elsewhere.

What's cached today

setup-fbuild caches $RUNNER_TEMP/fbuild-cache keyed on the fbuild version + a consumer-supplied cache-key-extra. That covers:

• The fbuild binary install from PyPI (~few seconds; not load-bearing)
• The toolchain downloads (~/.fbuild/cache/toolchains/)
• Package cache (~/.fbuild/cache/packages/)

What's NOT cached

The actual framework compile output, which is the load-bearing cost:

• Per-project <project>/.fbuild/build/<env>/<profile>/core/*.o
• Per-project <project>/.fbuild/build/<env>/<profile>/core/lib<env>.a

Stage-1 of compile-many writes the framework here. Stage-2 hardlinks from it within a single batch (via #337). But once the workflow ends, all of it is thrown away.

Why this matters

FastLED's build_esp32s3.yml runs ~150 examples per commit. The framework compile happens once (stage-1) per workflow run, costing ~5-8 min on its own. Multiply across 8+ ESP32-family boards in FastLED's matrix → every push pays ~40-60 min of redundant framework compiles that didn't change.

If setup-fbuild cached the per-project core/ directory keyed on framework version + flags hash, stage-1 of compile-many would be ~instant on cache-hit runs.

Proposed approach

1. In fbuild: write framework artifacts to a content-addressed location under ~/.fbuild/cache/core/<hash>/ (hash of framework version + compile flags). Symlink/hardlink them into per-project build dirs at orchestrator startup.
2. In setup-fbuild: extend the cached path to include ~/.fbuild/cache/core/. Keep the existing cache-key-extra API so consumers can scope keys per-board.
3. In FastLED's workflows: pass cache-key-extra: ${{ matrix.board }}-${{ hashFiles('platformio.ini') }} so cache keys invalidate when the board or framework flags change.

Blocker for

FastLED PR #2672 is closed pending #361 (stage-2 regression) AND this (cross-run framework cache). Together they unblock flipping FASTLED_USE_FBUILD_CI=1 default-on.

Related

• ci(setup): cache the installed fbuild binary, skip pip install on hit #334 — added cache-key-extra to setup-fbuild; this issue widens the cached scope
• fbuild: seed stage-2 core/ from stage-1 to skip framework recompile (#335 architectural fix) #337 — within-run framework share via stage-1→stage-2 hardlink seed
• compile-many: stage-2 perf regression on big-framework boards (esp32/teensy) #361 — within-run stage-2 perf regression on big-framework boards