Skip to content

fbuild build: --shrink[=MODE] (default auto) for per-platform flash reduction via spec-file printf swap #493

Closed
Closed
fbuild build: --shrink[=MODE] (default auto) for per-platform flash reduction via spec-file printf swap#493

Description

@zackees
zackees
opened on Jun 8, 2026

Summary

Add fbuild build --shrink[=MODE] (default auto) and --no-shrink to reduce flash size on a per-platform basis. Auto-resolution is conservative — it picks off on platforms with no measured win and safe on platforms with a documented shrinker. Default behavior on supported platforms (Arduino-ESP32 IDF 5.x newlib, STM32, NRF52, RP2040/RP2350, ESP8266, AVR, ESP32-C3) saves 6–24 KB of flash per sketch with zero behavior change.

Linking is via a GCC spec file (printf-thin.specs) that inserts a precompiled shadow archive (libprintf_thin.a) before -lc. This is naturally LTO-safe and composes with nano.specs. --wrap is the fallback used only for --shrink=printf single-knob debugging.

Supersedes #492.

CLI surface

On Build, Deploy, TestEmu, Ci subcommands:

// crates/fbuild-cli/src/cli/args.rs

#[derive(clap::ValueEnum, Clone, Copy, Debug, Default, PartialEq, Eq)]
pub enum ShrinkMode { #[default] Auto, Off, Safe, Aggressive, Printf }

/// Aggressive flash-size reduction. MODE selects how hard fbuild tries:
///   auto        (default) decide from framework + IDF version + libc probe
///   off         no shrinking; use stock libc, full symbol set
///   safe        no-behavior-change wins (printf-thin + scanf-thin + stdio FILE strip)
///   aggressive  safe + behavior-altering (esp_err_msg strip, coredump disable, -Oz)
///   printf      single-knob: only the printf-family wrap (debuggable A/B)
#[arg(long, value_enum, num_args = 0..=1, default_missing_value = "auto")]
pub shrink: Option<ShrinkMode>,

/// Disable all shrink optimizations. Equivalent to --shrink=off.
#[arg(long = "no-shrink", conflicts_with = "shrink")]
pub no_shrink: bool,

--shrink with no value resolves to auto. --no-shrink overrides any auto-enable from project config or framework detection.

Auto-resolver matrix

Platform libc auto resolves to Est. flash saved
arduino-esp32 / IDF 5.x newlib (Xtensa: S2/S3/D0WD) newlib safe -24 KB
arduino-esp32 / IDF 5.x newlib (RISC-V: C3) newlib safe -6 KB
arduino-esp32 / IDF 5.x (C6/H2) newlib off n/a (ROM full-printf)
arduino-esp32 / IDF 6.x (any) picolibc off n/a (picolibc default)
AVR (atmega328p/32u4/2560, attiny series) avr-libc safe -1.0 to -1.7 KB (printf_min downgrade after static scan)
STM32 (f103/f411/f429/h747) ARM newlib safe -8 KB
NRF52 (nrf52840/833, Adafruit cores) ARM newlib safe -10 KB
RP2040 / RP2350 newlib + pico-sdk safe -6 to -12 KB (pico-sdk printf(compiler) + picolibc)
Teensy 2.0 (AVR) avr-libc safe per AVR rule
Teensy 3+/4+ (Cortex-M) ARM newlib off n/a (Print.cpp bypasses vfprintf)
ESP8266 xtensa-lx106 newlib safe -10 to -12 KB
Unknown / probe fails n/a off fail-closed

Linking strategy

Primary: spec-file + shadow archive

fbuild emits ~/.fbuild/cache/printf-thin/<toolchain-hash>/printf-thin.specs at first build and adds --specs=<path>/printf-thin.specs to the link line. The spec rewrites *libc: to insert -lprintf_thin before -lc:

*libc:
%{!shared-libgcc:--start-group -L${printf_thin_dir} -lprintf_thin -lc -lnosys --end-group}

libprintf_thin.a is a complete shadow of newlib's vfprintf.o + svfprintf.o co-exports — every symbol newlib pulls those objects in for: vfprintf, _vfprintf_r, _printf_r, printf, __sbprintf, _svfprintf_r, vsnprintf, _vsnprintf_r, svfprintf, sprintf, etc. Linker resolves all to our archive during the --start-group scan; newlib's vfprintf.o/svfprintf.o never get pulled.

The archive contains vendored picolibc tinystdio (~8 files from newlib/libc/tinystdio/: vfprintf.c, vfscanf.c, dtoa_engine.c, dtoa.h, stdio_private.h, formatter-spec headers) compiled with -fno-lto, _NEED_IO_LONG_LONG=1, _NEED_IO_DOUBLE=1, io-float-exact=false, no C99/positional/wchar. Plus thin shim functions that wrap each entry point with a stack-allocated cookie FILE whose lock is pre-bound to __lock___libc_recursive_mutex (ESPHome's lazy-mutex-leak fix).

Why this is the right primary path:

  • Naturally LTO-safe. Native archive; sketch bitcode references vfprintf as external; LTO has no bitcode to inline.
  • Clean stack traces. Frames show vfprintf; addr2line resolves to vendored picolibc source.
  • Composes with --specs=nano.specs cumulatively.
  • Mirrors how Espressif (nano.specs), ARM (picolibc.specs), and Newlib itself ship printf variants.

Cost: a per-newlib-version symbol manifest (~50 lines listing each printf-related symbol newlib co-exports). Newlib's stdio layout has been stable for ~15 years; the manifest changes once every few years and is covered by a CI nm-diff test.

Fallback: -Wl,--wrap= (used only by --shrink=printf)

For single-knob debugging via --shrink=printf, use:

-Wl,--wrap=vfprintf,--wrap=vprintf,--wrap=printf,--wrap=fprintf
-Wl,--wrap=vsnprintf,--wrap=snprintf,--wrap=vsprintf,--wrap=sprintf
-Wl,--wrap=fiprintf,--wrap=vfiprintf

The fiprintf/vfiprintf entries cover __assert_func (newlib's integer-only assert path). LTO safety requires (1) vendored picolibc compiled -fno-lto, (2) stub functions marked __attribute__((noinline, externally_visible)).

Linker scripts cannot fix LTO+--wrap interactions because they run after LTO inlining. The spec-file approach sidesteps this entirely.

Bundled appliers per mode

Mode Applier Mechanism
printf printf-thin (vfprintf/vprintf/printf/fprintf/vsnprintf/snprintf/vsprintf/sprintf/fiprintf/vfiprintf) --wrap fallback
safe printf-thin + scanf-thin + stdio FILE strip + drop unused C++ exception personality spec-file (shadow archive includes vfscanf)
aggressive safe + esp_err_msg_table strip + coredump disable + -Oz (GCC ≥ 12) safe + sdkconfig overrides + compile flag
off / --no-shrink none none
auto resolves to one of the above per the matrix per the matrix

Scanf-thin and stdio FILE strip are bundled into the shadow archive at no additional implementation cost — same vendored sources, same --specs integration, additional ~5 KB savings when sketches use sscanf/atof/String::toInt.

ESP32 sdkconfig stack knobs under --shrink=aggressive (CONFIG_BT_CLASSIC_ENABLED=n, CONFIG_BT_BLE_50_FEATURES_SUPPORTED=n, CONFIG_LWIP_PPP_SUPPORT=n) live in a per-platform aggressive registry; trigger a sdkconfig regeneration and ESP-IDF cache rebuild. On detection of explicit CONFIG_ESP_COREDUMP_ENABLE_TO_FLASH=y in user sdkconfig, aggressive mode errors out with "explicit coredump enable detected; use --shrink=safe or remove the config".

Baseline flags already applied across all fbuild platform configs (universal, not new appliers — but surface in reporting): -fno-rtti, -fno-exceptions, -ffunction-sections, -fdata-sections, -Wl,--gc-sections, -fno-unwind-tables, -fno-asynchronous-unwind-tables (via eh_frame_policy.rs).

Reporting

--shrink=auto (default, no flag)

Single green one-liner listing the symbol families being shadowed, sourced from a per-platform registry. Omitted entirely when the platform has no auto-shrink to apply:

0.12 auto shrinking: vfprintf, vsnprintf, snprintf, printf, vprintf, fprintf, vsprintf, sprintf   <- green

When auto resolves to off: no line.

When --no-shrink: Shrink: --no-shrink (user override; auto would have applied: printf-thin).

--shrink=safe|aggressive|printf (explicit)

Verbose multi-line plan with checkboxes — explicit intent earns explicit reporting:

0.12 Shrink: aggressive (explicit)
0.12   [x] printf-thin (spec-file shadow archive, est. -24 KB flash)
0.12   [x] scanf-thin (bundled with printf-thin)
0.12   [x] stdio FILE strip (est. -312 B RAM, -1 KB flash)
0.12   [x] esp_err_msg_table strip (est. -1.8 KB RAM)
0.12   [x] coredump strip (est. -3.0 KB flash, -1.9 KB RAM)
0.12   [x] -Oz (GCC 14.2 ≥ 12)
...
341.48 Flash:  302.10KB / 8.00MB (3.7%)  [stock: 329.78KB; saved 27.7 KB]
341.48 Shrink result: flash -27.7 KB (-8.4 %), ram -4.8 KB (-0.7 %)

Use owo-colors = "4" (auto-disables on non-tty + respects NO_COLOR). The auto shrinking: prefix is green().bold(); the symbol list is plain green(). Verbose plan uses default color with a single bold first line.

Per-platform shrinker registry

pub struct AutoShrinkEntry {
    pub category: &'static str,           // "printf-thin", "esp_err_msg", etc.
    pub symbols: &'static [&'static str], // printed in the green one-liner
}

Empty registry entry → no green line, silent. Adding a new shrinker on a platform appends to its entry and the symbols automatically appear in the green one-liner.

Configuration

platformio.ini

[env:esp32s3]
platform = espressif32
board = esp32-s3-devkitc-1
framework = arduino
fbuild_shrink = aggressive       ; off | safe | aggressive | printf | auto
fbuild_shrink_skip = coredump    ; optional escape hatch, comma-separated

Precedence

lowest → highest: platform default → platformio.ini → CLI flag. --no-shrink always wins.

Auto-disables

  • --platformio compat mode: shrink auto-disabled (byte-identical PIO output expected). Logged at debug level.
  • CONFIG_LIBC_NEWLIB_NANO_FORMAT=y detected in resolved sdkconfig: shrink auto-downgrades to off. Picolibc shadow (~6 KB) is net-negative against nano vfprintf (~2 KB). Logged: "shrink: disabled (newlib-nano already in use)".
  • Libc probe fails: defaults to off and logs warning. Probe is a 5-line TU with #ifdef __PICOLIBC__\n#error PICOLIBC\n#endif inspected via preprocessor exit code. Never guesses.

Implementation layout

crates/fbuild-build/src/shrink/
  mod.rs                       ShrinkMode, ShrinkPlan, auto-resolver
  probe.rs                     fail-closed libc probe (__PICOLIBC__ test TU)
  registry.rs                  per-platform AutoShrinkEntry table
  printf_thin/                 vendored picolibc tinystdio sources (-fno-lto always)
    vfprintf.c                 from picolibc/newlib/libc/tinystdio/
    vfscanf.c
    dtoa_engine.c
    ...
    COPYING.picolibc
    COPYING.NEWLIB
    NOTICE
  newlib_stdio_manifest.rs     per-newlib-version map of vfprintf.o / svfprintf.o co-exports
  shadow_archive.rs            builds libprintf_thin.a (complete shadow + shims with __lock___libc_recursive_mutex pre-binding)
  spec_emitter.rs              emits printf-thin.specs per toolchain hash
  wrap_fallback.rs             --wrap flag set + noinline,externally_visible stub TU (for --shrink=printf)
  applier.rs                   translates ShrinkMode → compile/link flags, sdkconfig overrides

Touch points:

  • crates/fbuild-cli/src/cli/args.rs — ShrinkMode enum, --shrink / --no-shrink flags on Build/Deploy/TestEmu/Ci. Per-subcommand (mirrors --clean/--environment/--verbose precedent).
  • crates/fbuild-build/src/build_fingerprint/mod.rs — include ShrinkMode + resolved applier set in fingerprint so toggling shrink invalidates the link cache.
  • crates/fbuild-build/src/build_info.rs — record shrink: { mode, resolved, applied: [...], strategy: "spec-file" | "wrap" }.
  • crates/fbuild-build/src/compile_many.rs:121 — extend seed_stage2_core_from_stage1 to include libprintf_thin.a + spec file so multi-sketch CI builds amortize printf-thin in stage 1.
  • crates/fbuild-packages/src/library/esp32_framework/sdk_paths.rs — IDF version detection via tools/esp32-arduino-libs/{mcu}/include/esp_common/include/esp_idf_version.h for ESP_IDF_VERSION_MAJOR; cache in Esp32Framework.
  • Cargo.toml — add owo-colors = "4" for the green reporting.

Acceptance

  • fbuild build --shrink and fbuild build --no-shrink both work; --shrink=auto|off|safe|aggressive|printf parses.
  • Default mode (no flag) on tests/platform/esp32s3 -e esp32s3 resolves to safe, prints the green one-liner, and drops flash by ≥ 18 KB (target; measured ceiling ~24 KB).
  • Default mode on tests/platform/uno -e uno resolves to safe (printf_min downgrade) when the sketch has no %f/%lld; resolves to off (the user keeps full printf) when it does.
  • Default mode on Arduino-ESP32 IDF 6.x resolves to off (no green line printed).
  • A clean build with --shrink=safe produces a firmware where xtensa-esp-elf-nm shows no _vfprintf_r / _svfprintf_r; _dtoa_r absent unless the sketch calls strtod / dtostrf.
  • build_info.json records the resolved mode, applied appliers, and link strategy.
  • --no-shrink produces a byte-for-byte identical (modulo timestamp) ELF to the pre---shrink build.
  • CI test diffs newlib's nm output against newlib_stdio_manifest.rs; fails on drift so the shadow archive stays complete across toolchain bumps.
  • CI test on a String-heavy sketch (FastLED Apa102 example uses String += float) confirms _dtoa_r is still present and float formatting is intact after --shrink=safe.
  • CI test confirms snprintf(NULL, 0, "...") does not clobber errno after the shadow archive is in place.
  • ESP32 panic-path test (trigger esp_panic) confirms the shadow is not reached from IRAM/cache-disabled context.
  • --platformio flag auto-disables shrink, produces byte-identical PlatformIO-compat output.
  • Spec-file path is naturally LTO-safe — a sketch with -flto in build_flags builds correctly with --shrink=safe and the shadow is honored.
  • Toggling --shrink between builds correctly invalidates the link cache; second build re-links.

Documented caveats (for BREAKING_CHANGES.md)

  • Banker's vs half-up rounding: picolibc dtoa-engine uses round-half-up; newlib _dtoa_r uses banker's rounding. Sketches with golden-output tests will diverge. Recommend --no-shrink for byte-exact reproduction.
  • Float quality: picolibc tinystdio with io-float-exact=false is slightly less accurate than newlib's _dtoa_r on edge cases (off-by-1-ulp on a tiny fraction of values). Fine for embedded logging; not safe for code that depends on exact IEEE round-trip from snprintf → strtod.
  • Newlib symbol-list drift: if newlib reshuffles vfprintf.o/svfprintf.o co-exports, our shadow misses a symbol and the linker pulls newlib's full object back in. Mitigation is the CI nm-diff test; the manifest is per-newlib-version.

Related

Implementation phases

Eight phases, each independently mergeable, ordered by dependency. Phases 1–5 ship the ESP32-S3 path end-to-end behind explicit opt-in; phase 6 turns on auto-default and rolls out platforms; phases 7–8 add aggressive mode and polish. Sub-phases inside a phase can land as separate PRs.

Phase 0 — Prerequisites

Goal: clear the runway. No user-facing behavior.

Scope:

  • Land fbuild bloat: emit and preserve firmware.map automatically #491 (firmware.map auto-emit) so shrink reports can show archive-attributed deltas. Hard dependency for phase 4 acceptance criteria.
  • Add owo-colors = "4" to crates/fbuild-cli/Cargo.toml (auto-disables on non-tty + NO_COLOR).
  • Create empty crates/fbuild-build/src/shrink/ directory with a mod.rs stub and a README.md. Wire into lib.rs.

Pass: cargo build --workspace --all-targets clean; cargo clippy --workspace --all-targets -- -D warnings clean.

Size: 1 PR, <50 LOC of fbuild code (most of the PR is #491).

Phase 1 — CLI + auto-resolver + reporting (no-op linking)

Goal: user-facing surface lands. Every invocation is a no-op at the link level; the shrink machinery decides and reports but doesn't change link flags yet. Safe to default-on because the resolver returns off for every platform in this phase.

Scope:

  • crates/fbuild-cli/src/cli/args.rs: ShrinkMode enum + --shrink[=MODE] / --no-shrink on Build, Deploy, TestEmu, Ci. default_missing_value = "auto", conflicts_with = "shrink" on --no-shrink.
  • crates/fbuild-build/src/shrink/probe.rs: fail-closed libc probe — compile a 5-line TU with #ifdef __PICOLIBC__\n#error PICOLIBC\n#endif, inspect preprocessor exit. Cache result per toolchain hash. On any failure → return Probe::Unknown.
  • crates/fbuild-build/src/shrink/registry.rs: AutoShrinkEntry { category, symbols } table. All entries empty for v1.
  • crates/fbuild-build/src/shrink/mod.rs: ShrinkPlan { applied: Vec<Applier>, skipped: Vec<(Applier, Reason)>, strategy: Strategy }. Auto-resolver function that returns ShrinkMode::Off for every platform (real resolution lands in phase 4+).
  • crates/fbuild-build/src/shrink/reporting.rs: green one-liner (empty registry → no line); verbose plan for explicit modes; --no-shrink / --platformio overrides logged.
  • crates/fbuild-build/src/build_info.rs: record shrink: { mode, resolved, applied: [], strategy: null } in build_info.json. Empty in phase 1.
  • Auto-disable conditions wired but not yet exercising appliers: --platformio → force off; CONFIG_LIBC_NEWLIB_NANO_FORMAT=y in resolved sdkconfig → force off with log.

Out of scope: any actual flag / file emission; LTO interaction; shadow archive; wrap fallback.

Tests:

  • Unit: CLI parse for all five modes + --no-shrink.
  • Unit: probe TU compiles and returns expected Probe::Newlib / Probe::Picolibc / Probe::Unknown.
  • Integration: fbuild build tests/platform/esp32s3 -e esp32s3 --shrink=safe prints "Shrink: safe (explicit)" + empty plan, builds identically to today.

Pass: every existing test still passes byte-for-byte. --no-shrink and --shrink=off print exactly one line each; --shrink=auto (default) prints nothing because all registries are empty.

Size: ~600 LOC, 1 PR.

Phase 2 — Shadow archive build (no link integration)

Goal: libprintf_thin.a produced as a build artifact; can be inspected with nm but isn't yet linked into any firmware.

Scope:

  • crates/fbuild-build/src/shrink/printf_thin/ — vendor picolibc tinystdio sources from picolibc/newlib/libc/tinystdio/: vfprintf.c, vfscanf.c, dtoa_engine.c, dtoa.h, stdio_private.h, formatter-spec headers. Include COPYING.picolibc, COPYING.NEWLIB, NOTICE.
  • crates/fbuild-build/src/shrink/shadow_archive.rs — shim TUs: each entry point (vfprintf, _vfprintf_r, _printf_r, printf, __sbprintf, _svfprintf_r, vsnprintf, _vsnprintf_r, svfprintf, sprintf, vsprintf, _sprintf_r, _vsprintf_r, fprintf, vprintf, fiprintf, vfiprintf) sets up a stack-allocated cookie FILE whose lock is pre-bound to __lock___libc_recursive_mutex (ESPHome's lazy-mutex-leak fix), then forwards to picolibc's __d_vfprintf. Guarded by #ifdef __PICOLIBC__ #error #endif.
  • build.rs invocation via cc::Build that produces libprintf_thin.a per target triple. Compiled with -fno-lto -Os -ffunction-sections -fdata-sections -D_NEED_IO_LONG_LONG=1 -D_NEED_IO_DOUBLE=1 -DPICOLIBC_FLOAT_PRINTF_SCANF=double -D_NEED_IO_C99_FORMATS=0 -D_NEED_IO_POS_ARGS=0 -D_NEED_IO_WCHAR=0 -D_NEED_IO_LONG_DOUBLE=0 -D_PICOLIBC_PRINTF=__d_vfprintf.

Out of scope: spec-file emission; integration into orchestrator; turning shrink on.

Tests:

  • Build: archive compiles for xtensa-esp-elf toolchain.
  • Symbol: xtensa-esp-elf-nm libprintf_thin.a lists every symbol in the manifest (phase 3 defines the manifest; in phase 2 we hand-check a known list).
  • Size: archive is ≤ 8 KB on Xtensa.

Pass: archive build is reproducible across runs (same byte hash from same sources); nm confirms expected entry points present and no undefined symbols outside libc.

Size: ~1500 LOC vendored + ~200 LOC shim, 1 PR.

Phase 3 — Newlib stdio symbol manifest + CI drift detection

Goal: catch drift between our shadow archive and newlib's actual vfprintf.o / svfprintf.o co-exports before it bites us in production.

Scope:

  • crates/fbuild-build/src/shrink/newlib_stdio_manifest.rs — per-toolchain map: { toolchain_id: { vfprintf_o: [symbols], svfprintf_o: [symbols] } }. Initial entries: xtensa-esp-elf-14.2.0_* (Arduino-ESP32 IDF 5.x newlib), arm-none-eabi-13.x (STM32/NRF52/RP2040), xtensa-lx106-elf-3.x (ESP8266).
  • CI test (crates/fbuild-build/tests/newlib_manifest_drift.rs) that walks each installed toolchain's libc.a, runs nm, and diffs against the manifest. Fails on any drift (missing symbol or new symbol). Provides a clear "update the manifest at X" hint.
  • Documentation: crates/fbuild-build/src/shrink/MANIFEST.md — how to regenerate a manifest entry when a toolchain bumps.

Out of scope: actually using the manifest to build the archive (still hand-coded in phase 2; phase 4 wires the manifest into archive generation).

Tests: CI runs against all toolchains in the test matrix; passes when manifest is in sync.

Pass: manifest is the authoritative source of truth; if a developer adds a new toolchain support, the CI test forces them to add a manifest entry.

Size: ~300 LOC manifest data + ~150 LOC test, 1 PR.

Phase 4 — ESP32-S3 end-to-end (first platform)

Goal: first measurable shrink. fbuild build tests/platform/esp32s3 -e esp32s3 (no flag) saves ≥ 18 KB by default.

Scope:

  • crates/fbuild-build/src/shrink/spec_emitter.rs — emit ~/.fbuild/cache/printf-thin/<toolchain-hash>/printf-thin.specs on first build per toolchain. Cache key includes toolchain hash + manifest version + picolibc source hash.
  • Wire --specs=<path>/printf-thin.specs -L<path> into the ESP32 link orchestrator (crates/fbuild-build/src/esp32/orchestrator/build.rs link step).
  • Turn on registry entry for arduino-esp32 IDF 5.x newlib Xtensa (AutoShrinkEntry listing the 8 wrap targets + scanf symbols).
  • Auto-resolver returns safe for arduino-esp32 IDF 5.x newlib Xtensa; still off everywhere else.
  • crates/fbuild-build/src/build_fingerprint/mod.rs — include ShrinkMode + resolved applier set in fingerprint. Toggling shrink invalidates the link cache (object cache stays valid).
  • crates/fbuild-build/src/compile_many.rs:121 — extend seed_stage2_core_from_stage1 to include libprintf_thin.a + spec file.
  • IDF version detection via tools/esp32-arduino-libs/{mcu}/include/esp_common/include/esp_idf_version.h for ESP_IDF_VERSION_MAJOR; cache in Esp32Framework.
  • build_info.json records strategy: "spec-file" + the applier list.

Out of scope: STM32 / NRF52 / RP2040 / ESP8266 / AVR / C3 (phase 6); aggressive mode (phase 7); --wrap fallback (phase 5).

Tests:

  • Acceptance: fbuild build tests/platform/esp32s3 -e esp32s3 drops flash by ≥ 18 KB (target ~24 KB).
  • Symbol: nm shows no _vfprintf_r / _svfprintf_r; _dtoa_r absent (sketch doesn't call strtod).
  • A/B: --no-shrink build is byte-for-byte identical (modulo timestamp) to pre-shrink baseline.
  • Cache: toggling --shrink between two builds correctly re-links (verified by mtime + symbol diff).
  • Errno: snprintf(NULL, 0, "...") does not clobber errno (small unit-test sketch).
  • Panic path: trigger esp_panic; shadow not reached (verified by addr2line on the panic frame).
  • String sketch: FastLED Apa102 example with String += float shows _dtoa_r still linked, float formatting intact.

Pass: green one-liner appears on default build; flash savings ≥ 18 KB; all symbol / errno / panic / String tests pass.

Size: ~800 LOC + acceptance tests, 1 PR.

Phase 5 — --wrap fallback for --shrink=printf

Goal: single-knob A/B debugging path lands. Implementation is a parallel mechanism; spec-file remains primary.

Scope:

  • crates/fbuild-build/src/shrink/wrap_fallback.rs — -Wl,--wrap= flag set (vfprintf, vprintf, printf, fprintf, vsnprintf, snprintf, vsprintf, sprintf, fiprintf, vfiprintf). Stub TU with __attribute__((noinline, externally_visible)) on each __wrap_*. Picolibc TUs already -fno-lto from phase 2.
  • Wire into orchestrator: --shrink=printf → use wrap path instead of spec-file path. build_info.json records strategy: "wrap".
  • Auto-resolver does NOT pick wrap path for any platform — wrap is debug-only.

Tests: --shrink=printf on ESP32-S3 produces equivalent ELF (same symbol delta, within 200 bytes flash) to --shrink=safe. Differences attributable to wrap overhead are documented.

Pass: wrap path is exercised in CI but not the default for any platform.

Size: ~200 LOC + test, 1 PR.

Phase 6 — Per-platform rollout

Goal: turn on auto = safe for the remaining ~7 platforms with measured wins, one sub-PR per platform.

Scope (one PR each):

Sub-PR Platform Mechanism Target savings
6a STM32 ARM picolibc shadow + spec-file (same path as ESP32-S3) -8 KB
6b NRF52 ARM picolibc shadow + spec-file -10 KB
6c RP2040/RP2350 (a) pico_set_printf_implementation(compiler), (b) ARM picolibc shadow + spec-file -6 to -12 KB
6d ESP8266 xtensa-lx106 picolibc shadow + spec-file -10 KB
6e ESP32-C3 (IDF 5.x RISC-V) RISC-V picolibc shadow + spec-file -6 KB
6f AVR (special case) Static format-string scan + swap -lprintf_min for -lprintf when no %f/%lld -1.0 to -1.7 KB

Per sub-PR:

  • Add manifest entry (uses phase 3's CI test to catch drift)
  • Add platform-specific archive build target
  • Add registry entry with the symbols printed in the green one-liner
  • Acceptance test on a representative sketch (tests/platform/<platform>)
  • Update auto-resolver to return safe for this platform

AVR sub-PR is structurally different — no shadow archive, just a linker flag swap based on a static scan of all printf-family format-string literals in the sketch TUs (reuses fbuild-header-scan).

Out of scope: Teensy 3+/4+, ESP32-C6/H2, IDF 6.x — these stay at off (documented in matrix).

Tests: per platform, acceptance test runs in CI matrix.

Pass: each platform's default build drops flash by its target; green one-liner appears; no behavior regressions.

Size: ~200–400 LOC per sub-PR; 6 PRs total in this phase.

Phase 7 — Aggressive mode appliers

Goal: --shrink=aggressive enables behavior-altering wins behind explicit opt-in. Not part of auto.

Scope (each its own sub-PR):

  • 7a — -Oz (GCC ≥ 12): gate on toolchain GCC version probe; replace -Os with -Oz in compile flags. Toolchain probe at fbuild orchestrator startup.
  • 7b — ESP32 sdkconfig stack knobs: per-MCU registry of CONFIG_BT_CLASSIC_ENABLED=n, CONFIG_BT_BLE_50_FEATURES_SUPPORTED=n, CONFIG_LWIP_PPP_SUPPORT=n, etc. Triggers ESP-IDF cache rebuild. Detect explicit user enables and skip them (don't override).
  • 7c — esp_err_msg_table strip: linker-script EXCLUDE_FILE or --wrap=esp_err_to_name to return "ESP_ERR(0x%x)" formatted from the code. Document the human-readable-name loss.
  • 7d — Coredump strip: sdkconfig override CONFIG_ESP_COREDUMP_ENABLE=n. Detect explicit CONFIG_ESP_COREDUMP_ENABLE_TO_FLASH=y in user sdkconfig.defaults; on detection, error with "explicit coredump enable detected; use --shrink=safe or remove the config". Silent strip of debug feature is wrong default.
  • 7e — Drop unused C++ exception personality: __gxx_personality_v0 already mostly dead via -fno-exceptions; aggressive mode adds -Wl,--gc-sections enforcement on the eh-frame and personality symbols.

Each sub-PR: registry entry + applier + acceptance test that measures the delta.

Tests: per applier, integration test on tests/platform/esp32s3 -e esp32s3 --shrink=aggressive measures expected delta; aggregate test confirms total aggressive delta is sum of individual deltas (no double-counting).

Pass: --shrink=aggressive saves ≥ 27 KB total on tests/platform/esp32s3; explicit-coredump test errors cleanly; loud failure when sdkconfig regeneration fails.

Size: ~150–300 LOC per sub-PR; 5 PRs in this phase.

Phase 8 — Documentation, breaking-change notice, release prep

Goal: ship-ready polish.

Scope:

  • BREAKING_CHANGES.md entry: default-on --shrink=auto changes Arduino-ESP32 IDF 5.x firmware behavior (smaller, picolibc float formatting). Direct users to --no-shrink for byte-exact reproduction.
  • docs/SHRINK.md — user-facing doc: what the modes do, when to use each, troubleshooting (toolchain probe failures, manifest drift, wrap-vs-spec).
  • Update README.md and CLAUDE.md (project root) to mention --shrink in the commands section.
  • Release notes draft for the version that ships phase 4 (initial) and the version that ships phase 6 (per-platform rollout).
  • crates/fbuild-build/src/shrink/README.md — developer doc on the architecture, where to add a new shrinker, manifest update workflow.

Out of scope: blog post, external announcements.

Tests: docs review only.

Pass: docs accurately reflect shipped behavior; release notes ready.

Size: docs only, 1 PR.

Dependency graph

Phase 0  -->  Phase 1  -->  Phase 2  -->  Phase 3  -->  Phase 4  -->  Phase 5
                                                            |             |
                                                            +--> Phase 6 -+
                                                                          |
                                                                          +-->  Phase 7  -->  Phase 8

Phase 5 (wrap fallback) and Phase 6 (per-platform) can run in parallel after phase 4. Phase 6 sub-PRs (6a–6f) can run in parallel with each other. Phase 7 sub-PRs (7a–7e) can run in parallel after phase 6 has at least the ESP32 platforms landed.

Total scope estimate

  • LOC: ~5,000 (40% vendored picolibc, 20% manifests/data, 40% Rust glue + tests)
  • PRs: ~16 (one per phase + sub-phases)
  • Calendar time: phases 1–4 are critical path (~2 weeks); phases 5–7 fan out (~3 weeks parallel)

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    FastLED Tracker
    Status
    Triage

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions