# How to Debug WASI Pipelines with ITK-Wasm

**URL:** <https://discourse.itk.org/t/how-to-debug-wasi-pipelines-with-itk-wasm/5778>\
**Category:** Community\
**Tags:** wasi, debugging, webassembly\
**Created:** [March 2, 2023, 6:07pm UTC](https://discourse.itk.org/t/how-to-debug-wasi-pipelines-with-itk-wasm/5778 "2023-03-02T18:07:39Z")\
**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 2, 2023, 6:07pm UTC](https://discourse.itk.org/t/how-to-debug-wasi-pipelines-with-itk-wasm/5778/1 "2023-03-02T18:07:39Z")

</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

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:

```auto
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://discourse.itk.org/uploads/default/original/2X/0/0bf16ddd3b677284eba977642e9d047a96d7e086.png)

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

 ![Native debug Linux](https://discourse.itk.org/uploads/default/original/2X/a/ac24b88dd789145a218f0d8c2c7731ffd89de5de.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://discourse.itk.org/uploads/default/original/2X/a/a85dbb3cb203436b2bc10bd8d3873b7ea8f689c4.png)

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

 ![Run WASI debug](https://discourse.itk.org/uploads/default/original/2X/8/893848ae8d0a2a2f915241d87468981164b25f2b.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://discourse.itk.org/uploads/default/original/2X/9/9b79a987c9baaf257e459f8079e99fecd105e6f4.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!**