How to Debug WASI Pipelines with ITK-Wasm
Tags: webassembly, cpp, tutorial
Published: 2023-03-02 18:16:41

###### By: Matt McCormick [![ORCID](https://info.orcid.org/wp-content/uploads/2020/12/orcid_16x16.gif)](https://orcid.org/0000-0001-9475-3756), Mary Elise Dedicke [![ORCID](https://i0.wp.com/info.orcid.org/wp-content/uploads/2020/12/orcid_16x16.gif?resize=16%2C16&ssl=1)](https://orcid.org/0000-0001-8848-3235), Jean-Christophe Fillion-Robin [![ORCID](https://i0.wp.com/info.orcid.org/wp-content/uploads/2020/12/orcid_16x16.gif?resize=16%2C16&ssl=1)](https://orcid.org/0000-0002-9688-8950), Will Schroeder [![ORCID](https://i0.wp.com/info.orcid.org/wp-content/uploads/2020/12/orcid_16x16.gif?resize=16%2C16&ssl=1)](https://orcid.org/0000-0003-3815-9386)

Effective debugging results in effective programming; [itk-wasm](https://wasm.itk.org) makes effective debugging of WebAssembly possible. In this tutorial, adapted from the [itk-wasm documentation](https://wasm.itk.org), we walk through how to debug a C++ data processing pipeline with the mature, native binary debugging tools that are comfortable for developers. This is a fully featured way to ensure the base correctness of a processing pipeline. Next, we will walk through an interactive debugging experience for [WASI WebAssembly](https://wasi.dev/). With itk-wasm, we can debug the same source code in either context with an interactive debugger. We also have a convenvient way to pass data from our local filesystem into a WebAssembly (Wasm) processing pipeline.

Let's get started! 🚀

## 0. Preliminaries

Before starting this tutorial, check out our [Hello Wasm World](https://www.kitware.com/hello-wasm-world/) tutorial.

## 1. Native Debugging

[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.

```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;
}
```

To run these examples, first [install and test](https://www.kitware.com/hello-wasm-world/) Docker and Node/NPM. Then, install the package dependencies and run the example commands:

```
cd itk-wasm/examples/Debugging/
npm install
npm run <name>
```

where `<name>` is the npm script. Available names can be found by calling `npm run` without any arguments.

The [CMake](https://cmake.org)-based, itk-wasm build system tooling enables the same C++ build system configuration and code to be reused when building a native system binary or a WebAssembly binary. As a result, native binary debugging tools, such as [GDB](https://sourceware.org/gdb/), [LLDB](https://lldb.llvm.org/), or the [Visual Studio debugger](https://docs.microsoft.com/en-us/visualstudio/debugger/?view=vs-2022) can be utilized.

We can build the project's standard CMake build configuration,

```cmake
cmake_minimum_required(VERSION 3.10)
project(DebuggingWebAssemblyExample)

add_executable(DebugMe DebugMe.cxx)
```

with standard CMake commands:

![Native build](https://i.imgur.com/vEA9Cwq.png)

The native binary can then be debugged in the standard way. For example, with `gdb` on Linux:

![Native debug Linux](https://i.imgur.com/BJ1H8E3.png)


## 2. WASI Debugging

The most direct way to debug WebAssembly is through the [WebAssembly System Interface (WASI)](https://wasi.dev/). In itk-wasm, we can build to WASI with the [WASI SDK](https://github.com/WebAssembly/wasi-sdk) by specifying the `itkwasm/wasi` toolchain image. A backtrace can quickly be obtained with the `itk-wasm` CLI. Or, a fully fledged debugger session can be started with LLDB.

First, build to WASI WebAssembly with debugging symbols available:

![WASI debug build](https://i.imgur.com/wbGpRWC.png)

Then, the `itk-wasm` CLI can conveniently run the Wasm binary with the included WASI runtime:

![Run WASI debug](https://i.imgur.com/agxGSt9.png)

We can see that `abort` is called in the `main` function at line 13 in `DebugMe.cxx`.

A full debugging session is also possible after [LLDB](https://lldb.llvm.org/) >= 13 and [Wasmtime](https://wasmtime.dev/) are installed.

![LLDB WASI debug](https://i.imgur.com/EhSg8Ay.png)

## What's Next

In our next post, we will provide a tutorial on how to debug C++ WebAssembly processing pipelines in a web browser.

**Enjoy ITK!**