Debug C/C++ WebAssembly

Sofia Emelianova

WebAssembly provides a way to run, for example, C/C++ code on the web at near native speed and alongside JavaScript. This document shows how to set up and use Chrome DevTools to better debug such applications.

Once you set up DevTools, you can:

Inspect your original code in Sources > Editor.
Pause execution with line-of-code breakpoints and step through your original C/C++ source code, not the compiled .wasm binary file.

And, while paused, you can:

Hover over variables in the original source file and see their values.
Understand function names in Call Stack and variables in Scope.
Output deeply nested properties and complex objects to the Console.
Inspect object memory with Memory Inspector.

Set up

To enable C/C++ WebAssembly debugging in DevTools:

Compile your application with DWARF debug information included. Run the latest Emscripten compiler and pass it the -g flag. For example:
```
emcc -g source.cc -o app.html
```
For more information, see Building projects with debug information.
Install the C/C++ DevTools Support (DWARF) Chrome extension.

Debug

With DevTools set up, debug your code:

Open DevTools to inspect your website. For this tutorial, you can try it on this demo page, which was compiled with the required -g flag.
Optionally, group the files you authored for easier navigation. In Sources, check > Page > > Group by Authored/Deployed .
Select your original source file from the file tree. In this case, mandelbrot.cc.
To set a line-of-code breakpoint, click a line number in the column to the left of the Editor, for example, on line 38.
Run the code again. The execution pauses before the line with the breakpoint.

While paused, try the following:

In Sources > Editor, hover over a variable to see its value in a tooltip.

The value of a variable in a tooltip.

In Sources > Call Stack, view function names as they are in the source.

The main function in the Call Stack.

In Sources > Scope, view local and global variables, their types, and values.

The Scope pane with local variables and their values.

In Console, output variables and objects that are hard to navigate to in Scope:
- Deeply nested variables, for example, indexed items in big arrays.
- Complex objects, including those you can access with pointers (->). Expand them to inspect.

A nested variable and a complex object expanded in the Console.

In Sources > Scope, click the icon to open the Memory Inspector and inspect the raw bytes of object memory. For more information, see WebAssembly memory inspection.

Inspecting the memory of a variable.

Profile performance

With DevTools set up and open, the code Chrome runs isn't optimized. It's tiered down to give you better debugging experience.

In this case, you can't rely on console.time() and performance.now() in your code to profile performance. Instead, use the Performance panel to profile.

Alternatively, you can run your profiling code without opening DevTools, then open it to inspect the messages in the Console.

Separate the debug information

To speed up loading but still have a better debugging experience, you can split out the debug information into a separate .wasm file. For more information, see Debugging WebAssembly Faster.

You can either keep this file locally or host it on a separate server. To do it with Emscripten, pass the -gseparate-dwarf=<filename> flag and specify the path to the file:

emcc -g source.cc -o app.html \
     -gseparate-dwarf=temp.debug.wasm \
     -s SEPARATE_DWARF_URL=[file://local/path/to/temp.debug.wasm] | [URL]

Build and debug on different machines

If you build on a machine with a different operating system (container, VM, or remote server) than that on the machine you run Chrome on, you may need to manually map the debug file paths.

For example, if your project is at C:\src\project locally but was built in a Docker container with the path /mnt/c/src/project, do the following:

Go to chrome://extensions/, find the C/C++ DevTools Support (DWARF) extension, and click Details > Extension options.
Specify the old and the new file paths.

Specified old and new file paths.

Learn more

Check out the Chrome DevTools engineering blog for more information on WebAssembly debugging: