# How to Debug WebAssembly Pipelines in Your Web Browser

**URL:** <https://discourse.itk.org/t/how-to-debug-webassembly-pipelines-in-your-web-browser/5788>\
**Category:** Engineering\
**Tags:** debugging, webassembly\
**Created:** [March 8, 2023, 9:28pm UTC](https://discourse.itk.org/t/how-to-debug-webassembly-pipelines-in-your-web-browser/5788 "2023-03-08T21:28:32Z")\
**Posts on this page:** 1\
**Page:** 1

<div class="post-metadata">

**Author:** ![matt.mccormick](https://discourse.itk.org/user_avatar/discourse.itk.org/matt.mccormick/32/7_2.png) [@matt.mccormick](https://discourse.itk.org/u/matt.mccormick)\
**Post date:** [March 8, 2023, 9:28pm UTC](https://discourse.itk.org/t/how-to-debug-webassembly-pipelines-in-your-web-browser/5788/1 "2023-03-08T21:28:32Z")

</div>

###### By: Matt McCormick [![ORCID](https://discourse.itk.org/uploads/default/original/2X/b/bff6a0d75375482cfaf128e71b58c428272d88a0.gif)](https://orcid.org/0000-0001-9475-3756), Mary Elise Dedicke , Jean-Christophe Fillion-Robin , Will Schroeder

Did you know that your web browser comes bundled with extremely powerful development tools?

Modern web browsers are the foundation of the [The Web Platform](https://en.wikipedia.org/wiki/Web_platform), a full-featured computing environment. However, _full-featured platforms are not useful in and of themselves_. A large community of software developers is required to program the applications on a platform that people love. And, [effective debugging results in effective programming](https://www.kitware.com/how-to-debug-wasi-pipelines-with-itk-wasm/).

In this tutorial, we will learn how to debug [itk-wasm](https://wasm.itk.org) C++ data processing pipelines built to [WebAssembly (wasm)](https://webassembly.org) with the full-featured graphical debugger built into Chromium-based browsers.

In the following sections, we will first explain how to obtain a useful JavaScript backtrace in Node.js, then debug C++ code built to WebAssembly in a Chromium-based web browser. Let’s get started! 🚀

## 0. Preliminaries

Before starting this tutorial, check out our [WASI WebAssembly command line debugging tutorial](https://www.kitware.com/how-to-debug-wasi-pipelines-with-itk-wasm/).

As with the previous tutorial, we will be debugging the following C++ code:

```cpp
#include <iostream>

int main() {
  std::cout << "Hello debugger world!" << std::endl;

  const char * wasmDetails = "are no longer hidden";

  const int a = 1;
  const int b = 2;
  const auto c = a + b;

  // Simulate a crash.
  abort();
  return 0;
}

```

[The tutorial code](https://github.com/InsightSoftwareConsortium/itk-wasm/tree/main/examples/debugging) provides npm scripts as a convenient way to execute debugging commands, which you may also invoke directly in a command line shell.

## 1. Node.js Backtrace

When debugging WebAssembly built with the itk-wasm Emscripten toolchain, set the `CMAKE_BUILD_TYPE` to `Debug` just like with native binary debug builds.

As with native builds, this build configuration adds debugging symbols, the human-readable names of functions, variables, etc., into the binary. This also adds support for C++ exceptions and retrieving the string name associated with exceptions. Without this itk-wasm instrumentation, a C++ exception will throw an error with an opaque integer value. And, Emscripten JavaScript WebAssembly bindings will not be minified, which facilitates debugging.

When built with the default `Release` build type:

 ![Emscripten build Release](https://discourse.itk.org/uploads/default/original/2X/9/9f4cff8f0af9d6abc59f327cfae1c02601c5d651.png)

the JavaScript support code is minified, and difficult to debug:

 ![Run Node Release](https://discourse.itk.org/uploads/default/original/2X/0/078da7ff4bd6d6e7f704acf9dcc0894f1ec8771c.png)

However, when built with the `Debug` build type:

 ![Emscripten build Debug](https://discourse.itk.org/uploads/default/original/2X/4/4f03298d9c0e447837b7497d86eefab8e8ca118b.png)

you can obtain a useful backtrace:

 ![Run Node Debug](https://discourse.itk.org/uploads/default/original/2X/a/a651e49f7ace3fd1b1e7553f626e2327e430959f.png)

This is helpful for debugging issues that occur in the Emscripten JavaScript interface. The next section describes how to debug issues inside the Emscripten-generated WebAssembly.

## 2. Debugging in Chromium-based Browsers

Recent Chromium-based browsers have support for debugging C++ -based WebAssembly in the browser. With a few extra steps described in this section, it is possible to interactively step through and inspect WebAssembly that is compiled with C++ running in the browser.

WebAssembly debugging in DevTools requires a few extra setup steps compared to a default browser installation.

First, [install the Chrome WebAssembly Debugging extension](https://goo.gle/wasm-debugging-extension).

Next, enable it in DevTools:

1. In DevTools, click the _gear (⚙)_ icon in the top-right corner.
2. Go to the _Experiments_ panel.
3. Select _WebAssembly Debugging: Enable DWARF support_.

 ![Enable Wasm Debugging](https://discourse.itk.org/uploads/default/original/2X/a/a5e2031acdb914bb97f7c9296b0aa5c5e70ff8d8.png)

Exit Settings, then reload DevTools as prompted.

Next, open the options for the Chrome WebAssembly Debugging extension:

 ![Wasm Debugging Options](https://discourse.itk.org/uploads/default/original/2X/b/b703b7b9cc9803e8cf705673444e2d6060908293.png)

Since itk-wasm builds in a clean Docker environment, the debugging source paths in the Docker environment are different from the paths on the host system. The debugging extension has a path substitution system that can account for these differences. In the Docker image, the directory where `itk-wasm` is invoked is mounted as `/work`. Substitute `/work` with the directory where the `itk-wasm` CLI is invoked. For example, if `itk-wasm` was invoked at `/home/matt/src/itk-wasm/examples/Debugging`, then set the path substitution as shown below:

 ![Path substitution](https://discourse.itk.org/uploads/default/original/2X/b/b18c1a5f08208cf951921b631f8bc53f9149ac15.png)

Build the project with itk-wasm and the `Debug` `CMAKE_BUILD_TYPE` to include DWARF debugging information:

 ![Emscripten build Debug](https://discourse.itk.org/uploads/default/original/2X/4/4f03298d9c0e447837b7497d86eefab8e8ca118b.png)

Here we load and run the WebAssembly with a simple HTML file and server:

```html
<html>
  <head>
    <script src="https://cdn.jsdelivr.net/npm/itk-wasm@1.0.0-a.11/dist/umd/itk-wasm.js"></script>
  </head>
  <body>
    <p>This is an example to demonstrate browser-based debugging of
    C++-generated WebAssembly. For more information, please see the
    <a target="_blank" href="https://wasm.itk.org/examples/debugging.html">associated
      documentation</a>.</p>

    <script>
      window.addEventListener('load', (event) => {
        const pipeline = new URL('emscripten-build-debug/DebugMe', document.location)
        itk.runPipeline(null, pipeline)
      });
    </script>

  </body>
</html>

```

 ![HTTP Server](https://discourse.itk.org/uploads/default/original/2X/5/556c7682b43fa7249522b07983b0bc1f825a062b.png)

And we can debug the C++ code in Chrome’s DevTools debugger alongside the executing JavaScript!

 ![Debug C++ DevTools](https://discourse.itk.org/uploads/default/original/2X/f/f9f5fac52f1cb1cbbd1bee6be3b7e0acaff7ec67.png)

## What’s Next

In our next post, we will provide a tutorial on how to generate JavaScript and TypeScript bindings for Node.js and the browser.

**Enjoy ITK!**