Skip to content

perf(espidf): declare delegated IDF builds cold-only, with the measurement behind it (#1974) - #1987

Merged
zackees merged 1 commit into
mainfrom
agent/idf-caching-decision
Nov 10, 2026
Merged

zackees merged 1 commit into
mainfrom
agent/idf-caching-decision

Conversation

@zackees

@zackees zackees commented Nov 10, 2026

Copy link
Copy Markdown
Member

Follow-up 5 of 5 of the #1761 research pass: caching for delegated ESP-IDF builds. Closes #1974.

Decision: cold-only, declared (not "maybe later")

The wrapper option was measured before being rejected. Harness:
fbuild-steward/probes/idf_cache_bench.py (local, untracked) replays the exact
child environment the delegated build builds (IDF_PATH, IDF_PYTHON_ENV_PATH,
IDF_TOOLS_PATH, profile PATH prepended to the host PATH) and passes the
launcher as -DCMAKE_C_COMPILER_LAUNCHER=… -DCMAKE_CXX_COMPILER_LAUNCHER=… —
the only insertion point, because ninja spawns gcc. Pinned release v5.5.1
(fcae3288), spike project tests/platform/espidf_component, 1047 ninja
compile actions, host load average 9–30 (the deltas are far outside that noise).

Run Wall time Cache
cold, no launcher 41.8 s configure 6.2 s + 1047 compiles
no-op (ninja up to date) 1.2 s existing build dir
fullclean + build, no launcher 34.0 s same build dir
cold, zccache launcher, empty cache 50.6 s 233 MB stored
new build dir, launcher, cache warm 67.4 s no reuse — second full object set (436 MB)
fullclean + build, launcher 110.6 s no reuse — third set (640 MB)

zccache --show-stats after those runs: 2838 compilations, 0.2 % hit rate.
The wrapper works (replaying one identical entry does hit); what it cannot reuse
is ninja's command line, which embeds the absolute build directory (-o, -MF,
-I, -fmacro-prefix-map). Every build directory and every fullclean therefore
recompiles everything, at 1.2–3.3× the unwrapped wall time; inside one build
directory the only rebuild it could serve is the one ninja answers in 1.2 s.
A future launcher must key on IDF release + sdkconfig digest rather than the raw
command line before it can claim anything.

What the build now says

  • IdfCacheMode::ColdOnly with label() and log_line() — a type, so a report
    cannot quietly claim a cache the build did not have.
  • Stack summary: …, integration=idf-cmake, cache=cold-only, idf=v5.5.1; proof: …
    (also fixes the doubled spacing that string had).
  • Build log: idf.py caching: cold-only — compiler invocations are driven by ninja, so no object is served from fbuild's zccache; ….
  • <build>/idf/idf-artifacts.json: "cache": "cold-only".

Tests (real output)

  • soldr cargo test -p fbuild-build-esp --lib → 244 passed; 0 failed; 2 ignored
    (up from 242: the_delegated_build_reports_cold_only_caching and
    idf_cmake_summary_claims_cold_only_caching_and_no_cache_hit, which asserts the
    summary says cache=cold-only and contains no "cached"/"cache=hit" claim).
  • idf-artifacts.json test asserts index["cache"] == "cold-only".
  • Ignored real e2e against the pinned release: espidf_component_project_builds_and_publishes_artifacts
    → 1 passed in 48.4 s (warm install, full cold delegated build through the orchestrator).
  • soldr cargo clippy --workspace --all-targets -- -D warnings → exit 0.
  • soldr cargo fmt --all -- --check → 0 diffs; ci/check_test_layout.py ok;
    ci/enforce_platform_boundary.py --print-totals → rows=44; dylint_rows=43.

Docs

docs/design/bare-idf-component-builds.md gets the measurement table (question 3

  • a new "Caching decision" section) so the note stays the single source of truth,
    and follow-up 5 is marked decided.

Non-goals respected: no change to the Arduino-on-IDF caching path, no new CI lane.

A delegated `idf.py` build hands compilation to ninja, so fbuild's embedded
zccache dispatcher never sees its compiler invocations. #1974 has to be a
decision with a number, not a surprise, so the wrapper option was measured
before being rejected:

  cold, no launcher               41.8 s
  no-op (ninja up to date)         1.2 s
  fullclean + build, no launcher  34.0 s
  cold, zccache launcher          50.6 s   (233 MB stored)
  new build dir, launcher, warm   67.4 s   no reuse (436 MB)
  fullclean + build, launcher    110.6 s   no reuse (640 MB)

zccache reports a 0.2% hit rate over 2838 compilations: the key covers ninja's
command line, which embeds the absolute build directory (-o, -MF, -I,
-fmacro-prefix-map), so every build directory and every fullclean recompiles
everything at 1.2-3.3x the unwrapped wall time. Inside one build directory the
only rebuild it could serve is one ninja already answers in 1.2 s.

So the delegated path is declared cold-only, in the report and not just in a
comment:

- `IdfCacheMode` (ColdOnly) with a `label()` and a build-log line, so the mode
  a summary or index names is the mode that ran;
- `esp32_idf_cmake_stack_summary` carries `cache=cold-only` beside
  `integration=idf-cmake`;
- `idf-artifacts.json` records `"cache": "cold-only"`.

Tests pin both halves: the summary cannot read as a cache hit, and the artifact
index has to name the mode. Design note gets the measurement table.
@coderabbitai

coderabbitai Bot commented Nov 10, 2026

Copy link
Copy Markdown

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

Run configuration

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • Trigger review
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

@zackees
zackees added this pull request to the merge queue Nov 10, 2026
Merged via the queue into main with commit 0ec0639 Nov 10, 2026
37 checks passed
@fastled-project-sync fastled-project-sync Bot moved this to Triage in FastLED Tracker Nov 11, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: Triage

Development

Successfully merging this pull request may close these issues.

perf(espidf): decide caching for delegated IDF builds (zccache launcher vs documented cold-only)

1 participant