From 7b83e6a5a6a0d99692c3c6e46634c0cd9541965b Mon Sep 17 00:00:00 2001 From: zackees Date: Tue, 30 Jun 2026 10:24:43 -0700 Subject: [PATCH] docs(arduino-api): record platform_packages override scope decision (#666) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit #666 was the open audit task asking whether `arduino_api.rs` honors `platform_packages`. Per the audit reviewer's call (matches the spirit of #664/#681 — the original LPC8xx-driven bisection workflow targeted the framework, not the API header layer): wiring an override here doesn't pay off, for three reasons documented inline. The three reasons (also in the module docstring): 1. Bisection workflows target frameworks, not the API header layer. 2. `arduino_api` is a one-shot fetcher with no `PackageBase`; threading an override would require either a `PackageBase` refactor (large change for negligible gain) or threading an `Option` through every consumer (`AvrFramework`, `ArduinoMbedCore`, `SilabsCores`). 3. PIO's atmelavr / arduino-mbed / silabs packages don't expose an `arduino-api` override key — there's no canonical PIO package name consumers can set in `platform_packages`. If a future workflow ever needs to swap the ArduinoCore-API tag per-build, the doc points future engineers at the right migration path (convert to `PackageBase`). Closes #666 --- .../src/library/arduino_api.rs | 32 +++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/crates/fbuild-packages/src/library/arduino_api.rs b/crates/fbuild-packages/src/library/arduino_api.rs index 0d589c56..341052af 100644 --- a/crates/fbuild-packages/src/library/arduino_api.rs +++ b/crates/fbuild-packages/src/library/arduino_api.rs @@ -8,6 +8,38 @@ //! This mirrors Arduino's own release process (see ArduinoCore-megaavr's //! `.github/workflows/release.yaml`) which checks out ArduinoCore-API and //! copies its `api/` directory into `cores/arduino/`. +//! +//! # `platform_packages` override scope — intentionally out (FastLED/fbuild#666) +//! +//! The #664 / #681 platform-packages-override audit explicitly does NOT cover +//! ArduinoCore-API. Reasoning: +//! +//! 1. **Bisection workflows target frameworks, not the API header layer.** +//! The motivating use case for the audit (FastLED/FastLED#3325 LPC8xx +//! bisection) bisects framework commits, not ArduinoCore-API releases. +//! ArduinoCore-API is a small, header-only library on a stable tag (`v1.5.2`) +//! that almost never changes in a way that requires per-build override. +//! 2. **No `PackageBase` to extend.** Unlike every other framework package in +//! this directory, `arduino_api` is a one-shot fetcher (`ensure_arduino_api`) +//! that bypasses `PackageBase` entirely — it downloads via the shared HTTP +//! client, extracts, and copies `api/` into an already-existing core dir. +//! Wiring `with_override` would require either: refactoring this into a +//! `PackageBase` (large change for negligible gain), or threading an +//! `Option` through every framework that consumes this +//! helper (`AvrFramework`, `ArduinoMbedCore`, `SilabsCores`), each of which +//! is itself a `PackageBase` consumer that already routes the +//! *framework-level* override. The cost/benefit doesn't pay off. +//! 3. **PIO's atmelavr / arduino-mbed / silabs packages don't expose an +//! `arduino-api` override key either** — there is no canonical +//! `framework-arduino-api` PIO package consumers can set in `platform_packages`. +//! Wiring an override would be inventing an interface no consumer is asking for. +//! +//! If a future bisection workflow ever needs to swap the ArduinoCore-API tag +//! per-build, the right migration is to convert this module to use +//! `PackageBase` (mirror `arduino_core_lpc8xx.rs`) and add a single +//! `framework_name` for `package_override::resolve_override` consumers — but +//! that change should be driven by a real consumer need, not by audit +//! completeness. use std::path::Path;