Skip to content

epic: end-to-end DWARF stack-trace debugging — meta tracker across fastled-wasm + FastLED #130

Closed

Description

@zackees

Goal

Restore the end-to-end DWARF stack-trace debugging experience so that when a sketch crashes in the browser, the user sees their actual C++ .ino source line in DevTools, not raw wasm-function[N]:0xHHHH offsets.

The original work landed the server-side resolver scaffolding (#118, closes none of #85). This meta issue tracks every remaining piece across every repo that has to change for the experience to actually work for an end user.

Current state

Net effect today: a real wasm crash in the Tauri viewer shows the JS stack only; C++ frames are unresolved.

Work breakdown

zackees/fastled-wasm (this repo)

FastLED/FastLED (upstream library)

  • Windows-aware [dwarf] mapping in build_flags.toml. The current config is Unix-centric:
    file_prefix_map_from = "/"
    file_prefix_map_to   = "sketchsource/"
    On Windows, build paths look like C:/Users/… (or \\?\C:\… after canonicalize), so a single-prefix mapping cannot capture both the sketch tree and the FastLED tree. Either:
    • expand the section to declare multiple (from, to) pairs, one per logical root (sketch / FastLED src / emsdk); or
    • drop the config and let the build system synthesize prefix-maps from the actual on-disk roots it knows about.
  • Frontend symbolicator (if we ship the JS-overlay path). A small JS module bundled into the WASM frontend that catches errors, walks the wasm stack, and renders mapped frames using /dwarfsource. Likely lives next to the existing JS bundle under src/platforms/wasm/compiler/.
  • Confirm .dwarf separate-file output isn't expected. build_flags.toml declares dwarf_filename = "fastled.wasm.dwarf" but no such file is produced today — emscripten embeds DWARF in the .wasm directly. Either drop the key or wire it up via -gseparate-dwarf=<path> if external DWARF is wanted.

Future Chrome-extension repo (only if the extension path is picked)

Documentation

  • Once the experience works, document the diagnostic path in CLAUDE.md (or a new docs/debugging.md) so future maintainers know how a sketch crash is supposed to surface in DevTools.

Definition of done

fastled --init Blink → add a null-deref crash → fastled <sketch> (compile + serve + viewer) → trigger the crash → Chrome DevTools' "Sources" panel highlights the offending .ino / .h line, with a JS-style stack listing each C++ frame mapped to its source file. No Playwright. No Chrome Web Store CRX. No manual extension install.

Refs

#85 #118 #129 — local-side state and the resolver scaffolding shipped in #118.

Activity

  1. zackees commented on Jun 1, 2026

    @zackees
    MemberAuthor

    Status update on the DWARF stack-trace path:

    Local combined smoke using fastled-wasm#132 + FastLED#2675:

    • fastled --init Blink --no-interactive
    • fastled --just-compile --debug --no-interactive --fastled-path <FastLED PR worktree> .\fastled\Blink
    • generated fastled_js/fastled.wasm.map, fastled.wasm, and dwarf-roots.json
    • source map contains sketchsource/Blink.ino and fastledsource/...
    • no matches for the raw FastLED PR worktree path in fastled.wasm.map
    • no src\platforms / fastledsource\platforms backslash source-path matches in fastled.wasm.map

    Still intentionally not closing this meta issue until the final browser DevTools null-deref acceptance path is verified after the PRs land.

  2. zackees commented on Jun 1, 2026

    @zackees
    MemberAuthor

    Implemented and verified end-to-end.

    Merged PRs:

    Final acceptance run, no Playwright / no CRX / no extension install:

    • built merged fastled-wasm main release binary
    • initialized a fresh Blink sketch from FastLED master
    • added a deliberate sketch crash:
      • Blink.ino:24 issue_130_null_deref()
      • Blink.ino:26 *missing = 130;
    • compiled with:
      • fastled --just-compile --debug --no-interactive --fastled-path C:\Users\niteris\dev\FastLED <temp>\Blink
    • served generated fastled_js with the native --serve-dir path
    • verified /debug/source-roots rehydrated sketch/FastLED/emsdk roots from dwarf-roots.json
    • verified browser-normalized source URL GET /dev/fastled/sketchsource/Blink.ino returns the modified sketch source
    • drove Chrome 148 through raw CDP and confirmed:
      • fastled.wasm loads with sourceMapURL: fastled.wasm.map
      • fastled.wasm.map maps generated wasm line 0, column 7344 to Blink.ino:26
      • CDP breakpoint at http://127.0.0.1:<port>/fastled.wasm:0:7344 pauses in the worker at $issue_130_null_deref()
      • paused stack includes $issue_130_null_deref() -> $loop() -> $fl::fastled_loop_once() -> $extern_loop()

    That satisfies this meta issue's definition of done: the browser has the wasm source map, the server can resolve the mapped .ino source, and the debugger stops on the offending sketch frame/source location without Playwright or a Chrome extension.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions