Skip to content

docs(design): research note for bare-IDF/CMake component builds (#1761) - #1969

Merged
zackees merged 1 commit into
mainfrom
agent/bare-idf-component-research
Nov 9, 2026
Merged

zackees merged 1 commit into
mainfrom
agent/bare-idf-component-research

Conversation

@zackees

@zackees zackees commented Nov 9, 2026

Copy link
Copy Markdown
Member

Research deliverable for #1761 (the honor half of #1664, whose reject half landed in #1730). Docs only — no implementation and no behaviour change.

What this adds

docs/design/bare-idf-component-builds.md: option comparison, measured costs and a recommendation for genuine bare-IDF / CMake-component projects, plus a contents entry in docs/design/README.md and a row in docs/INDEX.md.

Acceptance criteria from #1761

  • Design note comparing the three options, grounded in measurement — yes, with a real spike.
  • At least one spike that actually builds a component project under option 1 and captures the artifacts — done on 2026-11-09: ESP-IDF v5.5.1 (fcae3288), gcc xtensa-esp-elf 14.2.0, a project with a main component (idf_component_register(... REQUIRES mycomp)) and a second component components/mycomp, app_main() only, sdkconfig.defaults, target esp32s3.
    • set-target esp32s3 15.9 s → cold idf.py build 50.3 s (1071 ninja actions / 1064 objects / 108 component archives) on a host at loadavg ~60.
    • Artifacts: app bin 208,528 B, elf 3,721,344 B, map 3,108,610 B, bootloader.bin 21,056 B, partition-table.bin 3,072 B, generated sdkconfig 73,024 B, compile_commands.json 7.39 MB / 959 entries, build/ 144 MB total.
    • No-op rebuild 1.54 s; one-file touch rebuild 10.81 s.
    • Cross-check: FastLED's own ci/idf_app bare-IDF app is 240,368 B on the same IDF 5.5 line, so the spike is representative.
  • Recommendation with explicit cost/risk + follow-up breakdown — option 3 (hybrid), opt-in delegation; 6 proposed follow-ups.
  • Confirmation that fix(esp32): reject framework = espidf instead of silently building Arduino (#1664) #1730's metadata is sufficient to prevent false coverage — yes, with the required addition: integration=idf-cmake may only be emitted alongside artifact proof (elf/bin bytes, compile-db entry count, sdkconfig digest).

Demand evidence (not speculation)

FastLED itself is an IDF component (root CMakeLists.txt:79 calls idf_component_register) and already builds ci/idf_app in .github/workflows/build_bare_idf.yml across IDF 5.5 (esp32/esp32s3/c3/c6/p4) plus 5.1 and 4.4. Meanwhile FastLED's ESP32DEV_IDF5_COMPONENT board (ci/boards.py:900) declares framework = arduino, espidf, the exact shape fbuild builds through the Arduino core — so fbuild's current claim to exercise component registration is unproven.

Cost highlights (measured)

  • xtensa-esp-elf toolchain 1.1 GB (the default install is 3.8 GB because it also pulls the 2.1 GB riscv32 toolchain, gdb, ulp and dist tarballs); IDF source 667 MB per IDF version; python env 63 MB.
  • Portability: IDF's install.sh bootstrap does not work unmodified on NixOS/uv-CPython here (broken ensurepip; openocd needs libusb-1.0.so.0), so a delegating path must provision cmake/ninja/python/constraints itself instead of assuming a working host interpreter.
  • Caching: IDF drives gcc from ninja, so zccache is lost unless the compiler is wrapped; incremental behaviour measured above.

Verification

Docs-only change. No Rust/Python changed, so the local unit/lint gates have nothing to exercise; CI is the check. Numbers above are real output from the spike run, reproduced by the recipe in the note. The spike workspace is scratch (not committed): /home/niteris/dev/hermes/cache/scratch/idf-spike.

Deliberately not done: no code, no new dependency, no change to the espidf rejection, and #1761 stays open for the implementation follow-ups.

Measured idf.py spike + option costs for the "honor" half of #1664.
@coderabbitai

coderabbitai Bot commented Nov 9, 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 9, 2026
Merged via the queue into main with commit fd21004 Nov 9, 2026
29 checks passed
@fastled-project-sync fastled-project-sync Bot moved this to Triage in FastLED Tracker Nov 10, 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.

1 participant