How to Debug WebAssembly in a Web Browser

Debugging WebAssembly (Wasm) modules running inside a web browser has become significantly easier thanks to modern browser developer tools and source-level debugging standards. This article provides a practical, step-by-step guide on how to debug your Wasm code directly inside the browser using source maps and DWARF debug information, allowing you to set breakpoints, step through code, and inspect variables in your original source language like C++, Rust, or Go.

1. Compile with Debug Symbols

To debug WebAssembly at the source level, you must compile your source code with debugging symbols enabled. This embeds DWARF debug information into the Wasm binary or generates source maps.

• For C/C++ (Emscripten): Use the -g flag during compilation. To preserve source files, use -g4 to generate source maps.

  emcc main.cpp -g4 -o index.html

• For Rust (wasm-pack / rustc): Ensure you are compiling in debug mode rather than release (which strips symbols by default), or explicitly enable debug symbols in your Cargo.toml:

  [profile.release]
  debug = true

2. Enable Wasm Debugging in Your Browser

Modern browsers like Google Chrome, Microsoft Edge, and Mozilla Firefox support WebAssembly debugging natively or via extensions.

• Google Chrome / Edge: Install the “C/C++ DevTools Support (DWARF)” extension from the Chrome Web Store. This extension allows the Chrome DevTools to parse DWARF debug information embedded in your Wasm file.
• Firefox: Developer Tools support Wasm debugging out of the box, mapping the binary back to the source files if source maps are available.

Open your browser’s Developer Tools (F12 or Ctrl+Shift+I / Cmd+Option+I), go to Settings (gear icon), navigate to Preferences, and ensure that JavaScript source maps and Associated files are enabled.

3. Locate Source Files in DevTools

Once your application is running in the browser with DevTools open:

1. Navigate to the Sources (or Debugger in Firefox) tab.
2. In the file navigator on the left, look for a folder containing your original source files (e.g., C++, Rust, or Go files). These are loaded dynamically via the debug symbols embedded in the .wasm file.
3. Click on a source file to open it in the editor pane.

4. Set Breakpoints and Step Through Code

With your original source code visible in the browser, you can debug it just like standard JavaScript:

• Set Breakpoints: Click on the line number in your C++, Rust, or Go source file where you want execution to pause.
• Trigger Execution: Interact with your web application to trigger the WebAssembly function. The browser will pause execution at your breakpoint.
• Step Through: Use the debugging controls (Step Over, Step Into, Step Out, Resume) to navigate through your source code line by line.

5. Inspect Variables and Call Stacks

When paused at a breakpoint, the DevTools sidebar provides vital information about the state of your Wasm module:

• Scope Panel: Inspect the current values of local and global variables. The DWARF extension translates the raw Wasm memory and stack values back into their original types (e.g., structs, pointers, integers).
• Call Stack: View the active function execution path. You can click on previous stack frames to inspect the state of the application at earlier points in the execution flow.