docs(readme): document eh_frame strip default — deviation from PlatformIO behavior (#243 #245 follow-up)

[zackees]

Follow-up to #243 / #244 / PR #245.

Deviation from PlatformIO

PR #245 introduces an eh_frame strip policy that, on most GCC targets, defaults to Strip (-fno-asynchronous-unwind-tables -fno-unwind-tables). This is a meaningful deviation from PlatformIO's default behavior — PIO ships GCC's stock flags, which means .eh_frame is preserved on every build, contributing ~36 % of the firmware size on a stock ESP32-S3 Blink.

Anyone migrating a project from PIO to fbuild and comparing binaries will see one of two things:

1. ESP32 (Arduino framework): identical behavior. We Preserve by default because CONFIG_ESP_SYSTEM_PANIC_PRINT_BACKTRACE=y is the ESP-IDF Arduino default. esp32_exception_decoder keeps working.
2. Teensy / STM32 / RP2040 / NRF52 / ESP8266: smaller firmware. We Strip by default because those platforms ship with -fno-exceptions and nothing in their stock runtime consumes .eh_frame.

This is mostly a win, but it's a silent win — a downstream user who isn't reading PRs won't know why their STM32 firmware shrank or how to undo the change. That's the gap this issue tracks closing.

What needs to land in the README

A new section under "size optimization" or "PlatformIO compatibility" covering:

1. What changed

By default, fbuild strips GCC's .eh_frame exception-unwinding tables on release builds for platforms that don't use them (Teensy, STM32, RP2040, NRF52, ESP8266). This saves 40-180 KB of flash on a typical FastLED sketch. PlatformIO does not do this — running the same project under pio run produces a larger binary.

2. When the strip applies

A table cross-referencing the policy precedence list from PR #245's body:

Condition	Policy
FBUILD_STRIP_EH_FRAME=1 env var	Strip
FBUILD_KEEP_EH_FRAME=1 env var	Preserve
build_type = debug in platformio.ini	Preserve
-fexceptions / -funwind-tables in build_flags	Preserve
ESP32 with CONFIG_ESP_SYSTEM_PANIC_PRINT_BACKTRACE=y (Arduino default)	Preserve
Otherwise	Strip

3. How to opt out (per project)

For a project that needs the same eh_frame layout as PlatformIO produces — e.g. a custom panic handler that walks .eh_frame — add to platformio.ini:

[env:my_board]
build_flags = -funwind-tables

Or set FBUILD_KEEP_EH_FRAME=1 in the environment.

4. Why we deviate

Short rationale referencing FastLED/FastLED#2473 (the symbol-level audit). Anyone curious why fbuild's binary is smaller than PIO's should land on this section.

Acceptance

• README has a "PlatformIO compatibility differences" or "Size optimization" section describing the deviation.
• The opt-out instructions (FBUILD_KEEP_EH_FRAME=1, build_flags = -funwind-tables) are explicit and copy-pasteable.
• Cross-link to feat(build): #243 #244 strip .eh_frame on release builds across all GCC platforms #245 for the implementation history and to ESP32-S3 binary size: 657 KB on master vs 344 KB on 3.10.3 — remaining +313 KB delta breakdown FastLED#2473 for the byte-level audit.
• One sentence in the top-level README also mentions the deviation, with a link to the longer section. Most readers stop at the top-level README; this is the place to surface "fbuild's binaries will differ from PIO's, and here's the knob".

Why this is its own ticket, not a doc commit in PR #245

PR #245 is already large (1012 LOC, 20 files). A README change requires a tone/style review that's orthogonal to the build-system change — better to handle it in a follow-up commit on main once the implementation has soaked for a few days and any unexpected behavior has surfaced.

Out of scope

• Docs for the env-var overrides themselves; those go inline with the README section.
• A migration guide between PIO and fbuild generally. The eh_frame deviation is the most visible per-platform difference today, but a full migration guide is a separate, larger effort.

Related

• feat(build): #243 #244 strip .eh_frame on release builds across all GCC platforms #245 — implementation PR (closes ESP32: auto-strip .eh_frame when exception handling and panic backtrace are both off (~225 KB savings on FastLED Blink) #243 + Propagate eh_frame strip policy to ARM Cortex-M / Teensy / RISC-V GCC targets (follow-up to #243) #244).
• ESP32: auto-strip .eh_frame when exception handling and panic backtrace are both off (~225 KB savings on FastLED Blink) #243 — ESP32 root issue with the 225 KB measurement.
• Propagate eh_frame strip policy to ARM Cortex-M / Teensy / RISC-V GCC targets (follow-up to #243) #244 — propagation to other GCC platforms.
• ESP32-S3 binary size: 657 KB on master vs 344 KB on 3.10.3 — remaining +313 KB delta breakdown FastLED#2473 — symbol-level audit showing eh_frame contributes 36 % of firmware size on ESP32-S3 Blink.
• feat(fl/stl): add FL_NO_UNWIND macros, apply to ESP32 unity headers FastLED#2423 — the library-side pragma workaround that PR feat(build): #243 #244 strip .eh_frame on release builds across all GCC platforms #245 obviates.