Skip to content

fix(dwarf): bridge from /dwarfsource resolver to actual browser stack traces #129

Closed

Description

@zackees

Goal

Reproduce a wasm crash in a sketch and confirm whether the stack trace shows up in Chrome DevTools' "Sources" panel with proper C++ source mapping via the /dwarfsource resolver shipped in #118 (issue #85).

TL;DR

The resolver is server-side ready, client-side broken. A wasm crash today produces a JS stack of raw wasm-function[N]:0xHHHH offsets with no C++ source mapping. Three concrete gaps prevent the legacy debugging experience from being restored, all on the producer/consumer side of the resolver — the resolver endpoints themselves work.

Reproduction

fastled --init Blink --no-interactive
# patch Blink.ino: add `static void crash() { *(volatile int*)0 = 42; }`
#                    and call crash() from loop()
fastled --just-compile --debug --no-interactive ./fastled/Blink
fastled --debug --no-interactive ./fastled/Blink     # compile + serve + watch
curl http://127.0.0.1:<port>/debug/source-roots
curl -X POST http://127.0.0.1:<port>/dwarfsource \
     -H 'Content-Type: application/json' \
     -d '{"path":"sketchsource/Blink.ino"}'

What works

  1. GET /debug/source-roots returns four populated roots after a successful build:
    {"roots":[
      {"prefix":"sketchsource","path":"…\\Temp\\crash-test\\fastled\\Blink"},
      {"prefix":"fastledsource","path":"…\\.fastled\\cache\\fl\\repo\\src"},
      {"prefix":"headers","path":"…\\.fastled\\cache\\fl\\repo\\src"},
      {"prefix":"emsdk","path":"…\\toolchains\\emscripten\\win\\x86_64"}
    ]}
  2. POST /dwarfsource with a prefixed path (sketchsource/Blink.ino, fastledsource/FastLED.h) returns the file content (200 OK).
  3. POST /dwarfsource with .. traversal returns 400 with invalid path:.
  4. --just-compile --debug embeds DWARF: fastled.wasm is 897 KB for a minimal Blink (vs ~540 KB for --quick). 17 absolute source paths are visible in the wasm via strings.

What doesn't work — three gaps

Gap 1 (high): DWARF embeds raw absolute paths, not the prefixed form

The .wasm's DWARF compilation-unit table embeds the raw Windows paths like:

C:/Users/niteris/.fastled/cache/fl/repo/src\fl/stl/flat_map.h
C:/Users/niteris/.fastled/cache/fl/repo/src\platforms/shared/coroutine_context.cpp.hpp
…

When a browser/extension asks /dwarfsource for those paths, the resolver returns 400 (invalid path:) because they don't start with any configured prefix:

POST /dwarfsource {"path":"C:/Users/niteris/.fastled/cache/fl/repo/src/fl/stl/flat_map.h"}
HTTP/1.1 400  {"error":"invalid path: C:/Users/niteris/.fastled/cache/fl/repo/src/fl/stl/flat_map.h"}

Root cause: crates/fastled-cli/src/wasm_build.rs does not pass -ffile-prefix-map=FROM=TO to emcc. FastLED's src/platforms/wasm/compiler/build_flags.toml declares the mapping under [dwarf]:

file_prefix_map_from = "/"
file_prefix_map_to   = "sketchsource/"

…but only the legacy Python compiler honoured that section. The Rust path reads [build_modes.debug] flags directly and never generates the -ffile-prefix-map argument.

Worse, on Windows even a correctly-generated -ffile-prefix-map=/=sketchsource/ would not match anything because compilation paths look like C:/Users/…, not /Users/…. The mapping config is Unix-centric.

Gap 2 (high): no client code calls /dwarfsource

grep of the bundled frontend assets in fastled_js/*.js:

grep -lE 'dwarfsource|sketchsource|fastledsource|/debug/source-roots' \
     /tmp/crash-test/fastled/Blink/fastled_js/*.js
# (no output)

Nothing in the shipped JS bundle ever posts to /dwarfsource or fetches /debug/source-roots. The endpoints are reachable but never invoked. Two consumer paths existed historically:

Neither one is the path a user takes when they hit a crash in the default fastled <sketch> Tauri viewer / browser.

Gap 3 (medium): /debug/source-roots leaks the \\?\ long-path prefix

The JSON above shows the paths as "\\\\?\\C:\\Users\\…". The Windows long-path prefix that we now strip from the build-side path consumers (via NormalizedPath) is still surfacing in the resolver's source-roots output, because debug_symbols::DebugSymbolConfig::source_roots() uses path.canonicalize() directly instead of going through NormalizedPath. Not a functional break for the resolver itself, but a regression risk if a future browser consumer compares root paths.

Gap 4 (low): --serve-dir cannot serve DWARF sources

--serve-dir skips the build, so the resolver handle is never populated. /debug/source-roots returns {"roots":[]} and any /dwarfsource POST returns 400 debug source resolver unavailable. If we want post-mortem debugging of a pre-built fastled_js/ directory, the resolver needs to be reconstructible from on-disk state (e.g. a dwarf-roots.json sidecar written at build time).

Current state of issue #85 acceptance criteria

Criterion Status
Failing sketch produces a readable mapped stack trace ❌ JS stack of raw wasm-function[N]:0xHHHH offsets
No Playwright / Chrome Web Store CRX dependency ✅
No hidden --internal-ensure-chrome-extension path ✅
Automated coverage that doesn't require Playwright ✅ — 6 resolver unit tests + 4 server integration tests in #118
Documented diagnostic path ⚠️ partial — endpoints documented but no end-to-end story

Next steps

In rough priority order:

  1. Plumb -ffile-prefix-map through the Rust build path. wasm_build.rs::get_sketch_compile_flags should read [dwarf] from build_flags.toml and append -ffile-prefix-map={file_prefix_map_from}={file_prefix_map_to} to the per-mode flags. Handle Windows by mapping the actual prefixes that emcc sees (<sketch_dir>/ → sketchsource/, <fastled_dir>/src/ → fastledsource/, <emsdk_root>/ → dwarfsource/emsdk/). Verify with strings fastled.wasm | grep sketchsource after a clean debug build.
  2. Pick a client path and wire it. Options:
    • Chrome devtools native + extension-free: leverage -gsource-map so the C++ frames resolve through the same source-map endpoint that JS frames already use. Implies dropping /dwarfsource and the resolver in favour of source-map URLs.
    • Browser overlay: ship a tiny JS error handler in the frontend bundle that catches the wasm trap, walks the JS stack, posts each wasm frame to a new /wasm/symbolicate endpoint, and renders the mapped frames in an HTML overlay. Bridge doesn't depend on a Chrome extension.
    • Restore the Chrome extension, but without the Web Store CRX download path (e.g. bundle the extension's unpacked source in the Tauri viewer and load it via --load-extension).
  3. Strip the \\?\ prefix from source_roots() output — fold NormalizedPath into DebugSymbolConfig::source_roots().
  4. Persist a dwarf-roots.json sidecar in fastled_js/ so --serve-dir can rehydrate the resolver from a pre-built directory.
  5. Add an end-to-end smoke test that compiles a known-crashing sketch, starts the server, walks the wasm strings table for embedded source paths, posts each one to /dwarfsource, and asserts every resolution succeeds. That makes Gap 1 a hard error in CI.

Evidence captured during this session

  • fastled --just-compile --debug on a setup()-crashing Blink → fastled.wasm 897 KB with 17 raw C:/Users/… paths.
  • GET /debug/source-roots after compile+serve → 4 prefixed roots populated, but the path strings carry \\?\.
  • POST /dwarfsource {"path":"sketchsource/Blink.ino"} → 200 with full Blink source.
  • POST /dwarfsource {"path":"<raw embedded path>"} → 400 invalid path:.
  • grep on bundled JS in fastled_js/*.js → no references to dwarfsource / sketchsource / /debug/source-roots.

Refs #85, follow-up to #118.

Activity

  1. zackees commented on Jun 1, 2026

    @zackees
    MemberAuthor

    Fixed by the combined cross-repo work:

    The four gaps from this issue are now covered:

    • debug builds synthesize root-specific prefix maps for sketch, FastLED, and emsdk paths
    • generated fastled.wasm.map uses source-map paths such as .../sketchsource/Blink.ino and .../fastledsource/...
    • the native server can resolve browser-normalized source-map GETs back to source files
    • dwarf-roots.json is written into fastled_js/ and --serve-dir rehydrates it
    • /debug/source-roots uses normalized paths instead of leaking Windows long-path prefixes
    • Linux x86 DWARF smoke CI verifies embedded wasm/source-map paths resolve through the server

    Final raw-CDP browser acceptance from #130 also passed: Chrome loaded fastled.wasm with sourceMapURL: fastled.wasm.map, and a breakpoint at the generated wasm location mapped from Blink.ino:26 paused in $issue_130_null_deref() with the C++ wasm stack intact.

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