WebAssembly Source Debugging: Principles, Tools, and Comparative Analysis

1. Introduction

With the rapid growth of the WebAssembly ecosystem, developers increasingly adopt WebAssembly to improve performance of dynamic languages for compute‑intensive tasks, to port high‑performance desktop software to the web, or to run sandboxed code safely on the server. The availability and usability of debugging tools are crucial for turning early experimentation into lasting adoption, because source‑code debugging is often the most efficient way to locate and fix problems across the entire code lifecycle.

2. Debugging Principles

Reading the LLDB manual reveals two fundamental debugging tasks: (1) controlling program execution – commands such as step in , step over , break , finish , continue decide how a program runs, pauses, and terminates; (2) observing program state – commands such as print , backtrace , register read retrieve variable values, call stacks, and memory images. Debugging therefore consists of controlling a target program and extracting runtime information. Depending on the target (native or managed), the underlying implementation differs, but the core ideas remain the same.

2.1 Debugging Native Programs

Debugging a native program typically requires a debugger and the target executable. On Linux the classic system call used is ptrace . The typical workflow is:

Debugger forks a child process and waits for its signals.

Child requests tracing from the parent and prepares to execute the target.

Child runs the target, generates a signal, and the blocked parent receives it.

Parent uses ptrace to perform debugging actions such as stepping, reading registers, or inserting breakpoints.

Example ptrace actions:

// child notifies parent to trace itself
ptrace(PTRACE_TRACEME, 0, 0, 0);
 // single‑step execution
ptrace(PTRACE_SINGLESTEP, child_pid, 0, 0);
 // read all registers
ptrace(PTRACE_GETREGS, child_pid, 0, &regs);
 // read instruction at eip
ptrace(PTRACE_PEEKTEXT, child_pid, regs.eip, 0);
 // replace instruction at an address (breakpoint)
ptrace(PTRACE_POKETEXT, child_pid, (void*)addr, (void*)data_with_trap);

On x86 the breakpoint instruction int 3 is written to the target address via ptrace(PTRACE_POKETEXT, ...) , causing the program to stop when the breakpoint is hit.

2.2 Debugging Managed‑Language Programs

Managed languages run on a virtual machine or runtime, so their debuggers operate at the VM level rather than directly on the OS. The VM knows the layout of stack frames, making it easy to expose variables, call stacks, and memory. For example, V8 maintains a hook_on_function_call flag; when true, the engine enters a debug mode on each function call. Debuggers communicate with the VM via a protocol such as the V8 Inspector protocol. Some managed‑language debugging can also reuse native debugging techniques. Wasmtime, a WebAssembly engine, JIT‑compiles wasm to native code, allowing LLDB to debug the resulting native process. The mixed stack (wasmtime + wasm) can be inspected with standard LLDB commands like backtrace . 2.3 Debug Information To map runtime information back to source code, debugging formats are required. For JavaScript, SourceMap records the relationship between minified/concatenated output and original sources. For compiled languages (C/C++, Rust) the DWARF format (or COFF/PECOFF/OMF/IEEE695) stores line numbers, variable locations, and type information. 3. WebAssembly Debugging WebAssembly runs inside a VM, making it a managed language. Debug information can be either SourceMap (common for AssemblyScript) or DWARF (common for C/C++/Rust). Different execution contexts (browser vs. server) lead to multiple debugging solutions. 3.1 Debugging AssemblyScript with Chrome DevTools Enable the sourceMap compiler option to generate a .sourcemap file, then use Chrome DevTools just like JavaScript debugging. All console features, breakpoints, and step controls work seamlessly. 3.2 Five Native‑Wasm Debugging Approaches 3.2.1 Native Debugging Compile the original source to a native binary and debug with traditional tools (LLDB/GDB). This approach offers mature tooling but cannot reproduce wasm‑specific issues. 3.2.2 lldb + wasmtime Run wasm under wasmtime, which JIT‑compiles to native code and exposes DWARF information to LLDB, providing a near‑native debugging experience within a full wasm environment. 3.2.3 lldb + iwasm iwasm (from wasm‑micro‑runtime) can operate in interpreter or AOT‑compiled mode. In interpreter mode it starts a server; LLDB connects via a socket using an extended GDB remote protocol. In AOT mode, the wasm is compiled to an .aot file with wamrc , then debugged with LLDB. iwasm -g=127.0.0.1:1234 test.wasm lldb (lldb) process connect -p wasm connect://127.0.0.1:1234 wamrc -o test.aot test.wasm lldb iwasm -- test.aot (lldb) target create "iwasm" (lldb) settings set -- target.run-args "test.aot" (lldb) settings set plugin.jit-loader.gdb.enable on (lldb) b main 3.2.4 Chrome/DevTools + C/C++ DWARF Plugin Compile C/C++ to wasm with emcc and the -g flag, then load the resulting HTML/JS/WASM in Chrome. Install the "C/C++ DevTools Support (DWARF)" plugin to let Chrome interpret DWARF debug info. #debug.c #include int fibo(int i) { if (i < 2) return 1; return fibo(i-1) + fibo(i-2); } int main(int argc, char const *argv[]) { printf("fibo(10): %d\n", fibo(10)); return 0; } emcc test_debug.c -o test_debug.html -g -fdebug-compilation-dir='.' 3.2.5 WasmInspect (Standalone Tool) WasmInspect is an open‑source interactive debugger that works directly on wasm modules using WASM‑DWARF. It supports breakpoints, stepping, memory dumps, and full WASI execution, but the project has not been updated since May 2020. 3.2.6 Comparison Debug Method Advantages Drawbacks Native Mature tooling Zero learning curve Cannot reproduce wasm‑specific issues Requires original build chain lldb+wasmtime Native‑like experience Full wasm environment Variable printing not fully supported Breakpoint info may be incomplete lldb+iwasm Native‑like experience Works in wasm environment Requires custom builds of LLDB and iwasm Complex AOT debugging steps Chrome + DWARF plugin Rich debugging UI Runs inside browser Needs emcc and HTML/JS wrapper WASI simulation may differ from native WasmInspect Standalone, ready‑to‑use Feature set limited Unmaintained, may lag behind spec 4. Conclusion Effective debugging tools are essential for any language ecosystem. This article outlined the general principles of source‑level debugging, introduced the specific challenges of WebAssembly, and surveyed several practical debugging solutions, highlighting their strengths and weaknesses. While browser‑based debugging for wasm is fairly mature, server‑side or non‑browser scenarios still have room for improvement. 5. References [1] The AssemblyScript Book: https://www.assemblyscript.org/introduction.html [2] Debugging WebAssembly with modern tools: https://www.youtube.com/watch?v=VBMHswhun-s [3] WasmInspect: https://github.com/kateinoigakukun/wasminspect [4] How to wasm DWARF: https://lucumr.pocoo.org/2020/11/30/how-to-wasm-dwarf [5] The pain of debugging WebAssembly: https://thenewstack.io/the-pain-of-debugging-webassembly [6] Introduction to the DWARF Debugging Format: https://dwarfstd.org/doc/Debugging%20using%20DWARF-2012.pdf [7] Debugging WebAssembly outside of the browser: https://hacks.mozilla.org/2019/09/debugging-webassembly-outside-of-the-browser [8] Debugging WebAssembly with wasmtime: https://docs.wasmtime.dev/examples-debugging.html [9] WAMR source debugging: https://github.com/bytecodealliance/wasm-micro-runtime/blob/main/doc/source_debugging.md