Skip to content

feat(toolchain): install the pinned ESP-IDF profile and describe its build environment - #1976

Merged
zackees merged 1 commit into
mainfrom
agent/esp-idf-release-profile
Nov 9, 2026
Merged

zackees merged 1 commit into
mainfrom
agent/esp-idf-release-profile

Conversation

@zackees

@zackees zackees commented Nov 9, 2026

Copy link
Copy Markdown
Member

Follow-up to #1975 (merged), part 2 of #1970.

#1975 pinned the four ESP32-S3 tool components as fbuild packages but could only
prove one of them installed, and nothing turned an install into something a
build could use. This PR adds the profile-level half: install the whole profile,
then describe the environment a delegated idf.py build (#1971) has to hand the
subprocess.

What is new

crates/fbuild-toolchain/src/toolchain/esp_idf_release_profile.rs

  • EspIdfRelease::new(project_dir, profile) — resolves every component of a
    profile against the normal cache; install() installs them in pin order and
    returns an IdfEnvironment.
  • IdfEnvironment::path_dirs() — the bin/ of every component that exports one.
    Decided by the archive, not by a hard-coded table: esp-rom-elfs exports
    linker data and no bin/, so a future component can never be pinned and then
    silently left off PATH.
  • IdfEnvironment::env_vars() — the two variables ESP-IDF's CMake layer reads
    instead of IDF_TOOLS_PATH: ESP_ROM_ELF_DIR and OPENOCD_SCRIPTS. Emitted
    only when the target directory exists, so a profile without OpenOCD does not
    export a path that points at nothing (CMake then blames the board script).
  • EspIdfRelease::is_installed() — all components, not any: three of four
    tools is not a usable ESP-IDF.
  • EspIdfRelease::installed_bytes() — the real byte total of the installed
    tree, used for feat(toolchain): pin an ESP-IDF release as fbuild packages with an esp32s3-only install profile #1970's 1.3 GB acceptance criterion.

The measurement bug this exposed

The first version of installed_bytes() summed every directory entry and
reported 1320 MB — over the 1.3 GB budget, for a profile the merged #1975
constants describe as 1,149 MB. The difference is hardlinks: Espressif ships the
versioned toolchain binaries as hardlinks to the unversioned names (60 of them in
xtensa-esp-elf alone; naive sum 1,262 MB vs du -sb 1,103 MB for that one
component). du counts each inode once, so a budget measurement has to as well.

dir_bytes() now dedupes through fbuild_core::platform::fs::file_identity
(the platform facade, so the rule holds on Windows) and a hardlink unit test
pins it. After the fix the same install measures 1149.2 MB, matching the
du -sb constant already on main.

Real proof (not a claim)

soldr cargo test -p fbuild-toolchain --lib -- --ignored esp_idf_s3_profile
→ 1 passed, 56.5 s: all four pinned archives downloaded (≈192 MB), sha256
verified, extracted, and then:

12 unit tests pass (4 new: PATH derivation, env_vars only for real
directories, a partial profile exporting nothing, and hardlink-aware byte
counting). cargo fmt --check clean, boundary 44/43, test layout ok, dylint
allowlists current.

Deliberately not here

…environment

#1975 pinned the four ESP32-S3 tool components but could only prove one of them
installed, and nothing turned an install into something a build could consume.
This adds the profile-level half:

- `EspIdfRelease` installs every component of an `IdfProfile` in pin order.
- `IdfEnvironment` derives the PATH entries from the archives themselves (a
  component contributes its `bin/` or it does not) and emits `ESP_ROM_ELF_DIR` /
  `OPENOCD_SCRIPTS` only when the target directory exists.
- `is_installed()` requires every component.
- `installed_bytes()` measures the installed tree in `du` terms.

That last point is a real bug found by the proof: summing each directory entry
reported 1320 MB for a profile the merged constants describe as 1149 MB, because
Espressif hardlinks the versioned toolchain binaries to the unversioned names
(60 hardlinks in `xtensa-esp-elf` alone: naive 1262 MB vs `du -sb` 1103 MB).
`du` counts each inode once, so the budget measurement now dedupes through
`fbuild_core::platform::fs::file_identity` and a hardlink unit test pins it.

Proven end to end (ignored test, run for real): all four pinned archives
downloaded and sha256-verified (~192 MB), `xtensa-esp32-elf-gcc --version`
prints `esp-14.2.0_20241119` from the installed tree, the profile measures
1149.2 MB (<= 1.3 GB, #1970 AC2), and a sentinel written into the tree survives
a second install with an unchanged byte total (AC4, package level).
@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

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