DEV Community

Cover image for How to Debug WASI Pipelines with ITK-Wasm
Matt McCormick
Matt McCormick

Posted on • Originally published at kitware.com

1

How to Debug WASI Pipelines with ITK-Wasm

By: Matt McCormick
ORCID
, Mary Elise Dedicke
ORCID
, Jean-Christophe Fillion-Robin
ORCID
, Will Schroeder
ORCID

Effective debugging results in effective programming; itk-wasm makes effective debugging of WebAssembly possible. In this tutorial, adapted from the itk-wasm documentation, 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. 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 tutorial.

1. Native Debugging

The tutorial code provides npm scripts as a convenient way to execute debugging commands, which you may also invoke directly in a command line shell.

#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;
}
Enter fullscreen mode Exit fullscreen mode

To run these examples, first install and test Docker and Node/NPM. Then, install the package dependencies and run the example commands:

cd itk-wasm/examples/Debugging/
npm install
npm run <name>
Enter fullscreen mode Exit fullscreen mode

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

The CMake-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, LLDB, or the Visual Studio debugger can be utilized.

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

cmake_minimum_required(VERSION 3.10)
project(DebuggingWebAssemblyExample)

add_executable(DebugMe DebugMe.cxx)
Enter fullscreen mode Exit fullscreen mode

with standard CMake commands:

Native build

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

Native debug Linux

2. WASI Debugging

The most direct way to debug WebAssembly is through the WebAssembly System Interface (WASI). In itk-wasm, we can build to WASI with the 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

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

Run WASI debug

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 >= 13 and Wasmtime are installed.

LLDB WASI debug

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!

AWS Security LIVE!

Join us for AWS Security LIVE!

Discover the future of cloud security. Tune in live for trends, tips, and solutions from AWS and AWS Partners.

Learn More

Top comments (0)

Billboard image

The Next Generation Developer Platform

Coherence is the first Platform-as-a-Service you can control. Unlike "black-box" platforms that are opinionated about the infra you can deploy, Coherence is powered by CNC, the open-source IaC framework, which offers limitless customization.

Learn more

👋 Kindness is contagious

Please leave a ❤️ or a friendly comment on this post if you found it helpful!

Okay