Repository navigation
feat(toolchain): pin ESP-IDF v5.5.1 tool components as fbuild packages - #1975
Merged
Merged
Conversation
install.sh cannot provision ESP-IDF on every host fbuild supports: it needs a venv with a working ensurepip, and openocd-esp32's install check loads libusb-1.0.so.0. Pin the archives the release publishes instead (tools.json, status recommended) and install them through PackageBase. - IdfComponent/IdfProfile::Esp32S3Only: xtensa-esp-elf, esp32ulp-elf, esp-rom-elfs, openocd-esp32; riscv32-esp-elf (2.1 GiB) and xtensa-esp-elf-gdb are absent from the pin table. - Cache key esp-idf-v5.5.1/<component>, leaf v5.5.1+<component version>: two IDF releases install side by side (#1843 rule). - Unpinned hosts (linux-armel/armhf/i686) error instead of borrowing another host's binaries; esp-rom-elfs uses the release's `any` archive. - Measured S3 profile: 1,149,197,870 B installed (du -sb), asserted in a test. Part of #1970 (tool components slice; source checkout + python env remain for the idf.py follow-up).
|
Important Review skippedAuto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the
|
5 tasks
`dylints/ban_std_pathbuf` denied three signatures in the new module: `install_path`, `ensure_normalized` and `tool_root` all spelled `std::path::PathBuf`, which is exactly the unnormalized-path class the lint exists to prevent (#436, #826). The new file is not and must not be on the shrink-only allowlist. The public surface now returns `fbuild_core::path::NormalizedPath`, and `tool_root` returns `Result<NormalizedPath>` instead of a path that may not exist -- so a caller cannot "install" into a directory the release never produced. `is_installed` now also requires the exported directory, so a cache hit that lost its tree is repaired rather than trusted. Dropping `impl Package` is deliberate: `Package::ensure_installed` is typed `PathBuf` in fbuild-packages-fetch (an allowlisted legacy file), and no consumer of this type needs the trait object yet. `is_installed` + `get_info` stay as inherent methods.
This was referenced Nov 9, 2026
This was referenced Nov 10, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Part of #1970 (follow-up 1, tool components slice).
Why
The merged research pass (
docs/design/bare-idf-component-builds.md, #1969) measured IDFv5.5.1's own bootstrap:
install.shneeds a venv with a workingensurepip, andopenocd-esp32's install check loadslibusb-1.0.so.0, so it cannot provision a toolchain onevery host fbuild supports (it fails on this repo's own NixOS host both ways). A delegated
idf.pybuild (#1971) therefore needs the toolchain to arrive as ordinary fbuild packages.What
crates/fbuild-toolchain/src/toolchain/esp_idf_release.rs— pins the archives Espressifpublishes for ESP-IDF v5.5.1 (
tools/tools.json,status: recommended, commitfcae3288) and installs them through the existingPackageBasepipeline:IdfComponent/IdfProfile::Esp32S3Only:xtensa-esp-elf,esp32ulp-elf,esp-rom-elfs,openocd-esp32— and nothing else.riscv32-esp-elf(2.1 GiB) andxtensa-esp-elf-gdb(104 MiB) are not in the pin table at all, so no code path can install them for an S3 project.
EspIdfToolinstalls throughPackageBase: download → sha256 verify → extract →.install_complete; it exposes an inherentensure_normalized()returningNormalizedPathrather than aPackageimpl, becausePackage::ensure_installedis typedPathBufandban_std_pathbufkeeps that legacy signature allowlisted (no consumer needs the trait object yet)sentinel, then returns the tool root (flat archives and
name-version/name/nesting both work).esp-idf-v5.5.1/<component>and the install leaf isv5.5.1+<component version>, so two IDF releases install side by side and neither entry isshared/overwritten (the setup action: fbuild cache restore-keys fallback crosses fbuild versions and doubles the saved cache #1843/fix(ci): scope the setup action's fbuild caches to one fbuild content hash (#1843) #1844 cache-key rule).
platform_keymaps fbuild's hosts totools.jsonspellings (linux-amd64,linux-arm64,macos,macos-arm64,win32);linux-armel/armhf/i686are deliberately unpinned andreturn an error instead of borrowing another host's binaries.
esp-rom-elfsfalls back tothe release's host-independent
anyarchive.Measured, not estimated (
du -sb, linux-amd64,install.sh-installed v5.5.1 tree):xtensa-esp-elfesp32ulp-elfesp-rom-elfsopenocd-esp32vs
riscv32-esp-elf2,142,092,152 B +xtensa-esp-elf-gdb108,817,092 B that the defaultinstaller adds (3.4 GiB of tools, ~3.8 GiB with the dist tarballs).
Verification (real output)
The ignored test is the end-to-end proof: it downloads the pinned
esp-rom-elfsarchive into anempty cache via
EspIdfTool::ensure_installed, verifies its sha256, extractsesp32s3_rev0_rom.elf, then callsensure_installedagain and gets the same tree from cache (nore-download — the offline-second-install shape of the acceptance criterion).
Pin spot-check against the live object:
Gates:
soldr clippy -p fbuild-toolchain --all-targets -- -D warningsclean;ci/check_test_layout.pyok;ci/enforce_platform_boundary.py --print-totalsstill44/43(no new host-gated rows).
Not in this PR
idf.py; thesource is a 603 MB checkout per version and needs its own pin/provisioning decision.
idf.pyinvocation, nointegration=idf-cmakeemission, no change to theArduino-on-IDF path. The
esp32s3-only profile installs <= 1.3 GBacceptance criterion ismeasured and asserted in a test, but from the recorded
duof aninstall.shtree, notfrom a full fbuild-package install of all four components (that is the AC1 run, ~1.15 GB of
downloads, and belongs with the follow-up that actually builds through the toolchain).