Improved WebAssembly debugging in Chrome DevTools

Ingvar Stepanyan
Ingvar Stepanyan

Background

Until recently, the only WebAssembly debugging that Chrome DevTools supported was viewing raw WebAssembly stack traces, and stepping over individual instructions in a disassembled WebAssembly text format.

A screenshot of the previously limited WebAssembly debugging support in Chrome DevTools.

While this works with any WebAssembly module and helps somewhat with debugging small, isolated functions, it's not very practical for larger apps where the mapping between the disassembled code and your sources is less obvious.

A temporary workaround

To work around this problem, Emscripten and DevTools have temporarily adapted the existing source maps format to WebAssembly. This allowed mappings between binary offsets in the compiled module to original locations in source files.

A screenshot of the source-maps-powered debugging.

However, source maps were designed for text formats with clear mappings to JavaScript concepts and values, not for binary formats like WebAssembly with arbitrary source languages, type systems, and a linear memory. This made the integration hacky, limited, and not widely supported outside Emscripten.

Enter DWARF

On the other hand, many native languages already have a common debugging format, DWARF, that provides all the necessary information for debuggers to resolve locations, variable names, type layouts, and more.

While there are still some WebAssembly-specific features that need to be added for full compatibility, compilers like Clang and Rust already support emitting DWARF information in WebAssembly modules, which enabled the DevTools team to start using it directly in DevTools.

As the first step, DevTools now supports native source mapping using this information, so you can start debugging Wasm modules produced by any of these compilers without resorting to the disassembled format or having to use any custom scripts.

Instead, you just need to tell your compiler to include debug info like you normally would on other platforms. For example, in Clang and Emscripten this can be done by passing a -g flag during compilation:

  clang -g …sources… -target wasm32 -o out.wasm

  emcc -g …sources… -o out.js

You can use same -g flag in Rust:

  rustc -g source.rs --target wasm32-unknown-unknown -o out.wasm

Or, if you're using Cargo, the debug info will be included by default:

  cargo build --target wasm32-unknown-unknown

This new DevTools integration with DWARF already covers support for stepping over the code, setting breakpoints, and resolving stack traces in your source languages.

A screenshot of the new DWARF-powered debugging.

The future

There is still quite a bit of work to do though. For example, on the tooling side, Emscripten (Binaryen) and wasm-pack (wasm-bindgen) doesn't support updating DWARF information on transformations they perform yet. For now, they won't benefit from this integration.

And on the Chrome DevTools side, we'll be evolving integration more over time to ensure a seamless debugging experience, including:

  • Resolving variable names
  • Pretty-printing types
  • Evaluating expressions in source languages
  • …and much more!

Stay tuned for future updates!

Download the preview channels

Consider using the Chrome Canary, Dev, or Beta as your default development browser. These preview channels give you access to the latest DevTools features, let you test cutting-edge web platform APIs, and help you find issues on your site before your users do!

Get in touch with the Chrome DevTools team

Use the following options to discuss the new features, updates, or anything else related to DevTools.