[Lldb-commits] [lldb] [lldb][docs] Document testing LLDB with WebAssembly (PR #229242)
Jonas Devlieghere via lldb-commits
lldb-commits at lists.llvm.org
Tue Oct 6 08:11:36 PDT 2026
https://github.com/JDevlieghere updated https://github.com/llvm/llvm-project/pull/229242
>From bc51925e9a5a2cd46374899823c0c9216b5aa3e9 Mon Sep 17 00:00:00 2001
From: Jonas Devlieghere <jonas at devlieghere.com>
Date: Mon, 5 Oct 2026 14:50:55 -0700
Subject: [PATCH 1/2] [lldb][docs] Document testing LLDB with WebAssembly
Describe how to run the API test suite against a Wasm runtime, using the
`wasm` platform. The new doc covers the platform settings, WAMR and
WasmKit as example runtimes, compiler choice, and the test suite
configuration.
---
lldb/docs/index.md | 1 +
lldb/docs/resources/test.md | 7 ++
lldb/docs/resources/wasm-testing.md | 117 ++++++++++++++++++++++++++++
3 files changed, 125 insertions(+)
create mode 100644 lldb/docs/resources/wasm-testing.md
diff --git a/lldb/docs/index.md b/lldb/docs/index.md
index b117c4ab386f2..830d33e39d31d 100644
--- a/lldb/docs/index.md
+++ b/lldb/docs/index.md
@@ -179,6 +179,7 @@ resources/lldbdap-contributing
resources/build
resources/test
resources/qemu-testing
+resources/wasm-testing
resources/debugging
resources/fuzzing
```
diff --git a/lldb/docs/resources/test.md b/lldb/docs/resources/test.md
index 5aaefc077e7d1..87c2f5d9c61f4 100644
--- a/lldb/docs/resources/test.md
+++ b/lldb/docs/resources/test.md
@@ -721,6 +721,13 @@ emulation environment using QEMU helper scripts found in
`llvm-project/lldb/scripts/lldb-test-qemu`. These scripts currently
work with Arm or AArch64, but support for other architectures can be added easily.
+### Running tests against WebAssembly
+
+The API tests can be compiled to WebAssembly and run under a standalone Wasm
+runtime. {doc}`/resources/wasm-testing` describes how to configure LLDB's `wasm`
+platform for a runtime serving a GDB remote stub, with WAMR and WasmKit as
+examples.
+
## Debugging Test Failures
On non-Windows platforms, you can use the `-d` option to `dotest.py` which
diff --git a/lldb/docs/resources/wasm-testing.md b/lldb/docs/resources/wasm-testing.md
new file mode 100644
index 0000000000000..6904ad97eb249
--- /dev/null
+++ b/lldb/docs/resources/wasm-testing.md
@@ -0,0 +1,117 @@
+# Testing LLDB with WebAssembly
+
+The LLDB API test suite can compile its test programs to WebAssembly and debug
+them through a standalone Wasm runtime. The runtime executes the module and
+serves a GDB remote stub. LLDB's `wasm` platform launches the runtime, picks a
+free TCP port and connects to the stub on it.
+
+This page covers configuring LLDB and the `wasm` platform. For building a
+runtime, see the runtime's own documentation.
+
+## Prerequisites
+
+- A [wasi-sdk](https://github.com/WebAssembly/wasi-sdk) release, which provides
+ the WASI sysroot, the wasm `compiler-rt` builtins and a `wasm-ld`.
+- A Wasm runtime that serves a GDB remote stub. WAMR and WasmKit are shown
+ below.
+
+## Choosing a compiler
+
+Test programs are built for `wasm32-wasip1`, which both the wasi-sdk clang and
+an upstream in-tree clang can target. `LLDB_TEST_COMPILER` picks one. It
+defaults to the in-tree `clang` whenever clang is part of the build.
+
+Prefer the in-tree clang, since it matches the LLDB under test and exercises
+in-tree DWARF and codegen changes. Unlike the wasi-sdk clang, it needs two
+things supplied:
+
+- `wasm-ld`. Enable LLD in the build and it lands next to `clang`, where the
+ driver looks before `PATH`. Without LLD, symlink the wasi-sdk's `wasm-ld` into
+ that same directory.
+- The wasm `compiler-rt` builtins, through `LLDB_TEST_RESOURCE_DIR` pointed at
+ the wasi-sdk's clang resource directory.
+
+Either compiler needs the WASI sysroot, through `LLDB_TEST_SYSROOT`.
+
+## Configuring the platform
+
+The `wasm` platform is selected with `--platform-name wasm`. Four global
+settings describe how to invoke the runtime:
+
+| Setting | Meaning |
+| --- | --- |
+| `platform.plugin.wasm.runtime-path` | Path to the runtime binary. A name without a directory separator is looked up in `PATH`. |
+| `platform.plugin.wasm.port-arg` | Argument carrying the GDB remote port. LLDB concatenates the port it chose. |
+| `platform.plugin.wasm.env-arg` | Argument forwarding one environment variable. LLDB concatenates a `key=value` pair, once per variable in the inferior's environment. When empty, no environment is forwarded. |
+| `platform.plugin.wasm.runtime-args` | Extra arguments for the runtime. They precede the port argument. |
+
+LLDB assembles the runtime's command line as:
+
+```
+<runtime-path> <runtime-args...> <port-arg><port> <env-arg><key=value>... <module> <inferior-args...>
+```
+
+`runtime-args` precedes the port argument, so a runtime that dispatches on a
+leading subcommand names that subcommand there. `port-arg` has to carry the port
+in a single argument, because LLDB concatenates the two.
+
+A runtime's diagnostics share the inferior's standard error, so a verbose
+runtime breaks tests that match program output. Use its quietest logging.
+
+Most of these values begin with a dash, so the `settings set` examples below
+pass `--` first to stop the command from reading them as its own options.
+
+## Example runtimes
+
+### WAMR
+
+[WAMR](https://github.com/bytecodealliance/wasm-micro-runtime)'s `iwasm` takes
+the debug server address as `host:port`. Its default heap and stack are small
+enough that some tests trap, so raise them.
+
+```
+settings set -- platform.plugin.wasm.runtime-path /path/to/iwasm
+settings set -- platform.plugin.wasm.runtime-args --heap-size=1048576 --stack-size=1048576 -v=0
+settings set -- platform.plugin.wasm.port-arg -g=127.0.0.1:
+settings set -- platform.plugin.wasm.env-arg --env=
+```
+
+### WasmKit
+
+[WasmKit](https://github.com/swiftwasm/WasmKit)'s CLI takes a bare port number
+and defaults to quiet, so `run` is all it needs beyond the port. That subcommand
+has to come first, which is what `runtime-args` is for.
+
+```
+settings set -- platform.plugin.wasm.runtime-path /path/to/wasmkit-cli
+settings set -- platform.plugin.wasm.runtime-args run
+settings set -- platform.plugin.wasm.port-arg --debugger-port=
+settings set -- platform.plugin.wasm.env-arg --env=
+```
+
+:::{note}
+WasmKit's debugger support is behind a package trait. The stub is only served by
+a CLI built with that trait enabled.
+:::
+
+## Running the test suite
+
+Point the test suite at the sysroot and the resource directory, and pass the
+target and platform configuration through `LLDB_TEST_USER_ARGS`:
+
+```
+$ cmake -G Ninja \
+ -DLLDB_TEST_SYSROOT=/path/to/wasi-sdk/share/wasi-sysroot \
+ -DLLDB_TEST_RESOURCE_DIR=/path/to/wasi-sdk/lib/clang/<version> \
+ -DLLDB_TEST_USER_ARGS="--triple;wasm32-wasip1;--platform-name;wasm;--setting;platform.plugin.wasm.runtime-path=/path/to/iwasm;--setting;platform.plugin.wasm.port-arg=-g=127.0.0.1:;--setting;platform.plugin.wasm.env-arg=--env=;--setting;platform.plugin.wasm.runtime-args=--heap-size=1048576 --stack-size=1048576 -v=0" \
+ <other options>
+$ ninja check-lldb-api
+```
+
+`lldb-dotest` takes the same configuration as command line arguments, which is
+easier if you keep the build configured for the host. There `-C`, `--sysroot`
+and `--resource-dir` replace the three CMake variables. Also pass a separate
+`--build-dir` so Wasm and host inferiors do not share an output directory.
+
+Only the API tests build their inferiors, so this configuration does not affect
+`check-lldb-shell` or `check-lldb-unit`.
>From d41c753c318a6e4a9a4bfdca360c501b2441ee43 Mon Sep 17 00:00:00 2001
From: Jonas Devlieghere <jonas at devlieghere.com>
Date: Tue, 6 Oct 2026 08:11:02 -0700
Subject: [PATCH 2/2] Address David's review feedback
---
lldb/docs/resources/wasm-testing.md | 42 ++++++++++---------
.../WebAssembly/PlatformWasmProperties.td | 7 ++--
2 files changed, 26 insertions(+), 23 deletions(-)
diff --git a/lldb/docs/resources/wasm-testing.md b/lldb/docs/resources/wasm-testing.md
index 6904ad97eb249..aabc52989eb97 100644
--- a/lldb/docs/resources/wasm-testing.md
+++ b/lldb/docs/resources/wasm-testing.md
@@ -1,9 +1,10 @@
-# Testing LLDB with WebAssembly
+# Debugging and Testing LLDB with WebAssembly
-The LLDB API test suite can compile its test programs to WebAssembly and debug
-them through a standalone Wasm runtime. The runtime executes the module and
-serves a GDB remote stub. LLDB's `wasm` platform launches the runtime, picks a
-free TCP port and connects to the stub on it.
+LLDB debugs WebAssembly through a standalone Wasm runtime. The runtime executes
+the module and serves a GDB remote stub. LLDB's `wasm` platform launches the
+runtime, picks a free TCP port and connects to the stub on it. The LLDB API test
+suite uses the same setup to compile its test programs to WebAssembly and run
+them.
This page covers configuring LLDB and the `wasm` platform. For building a
runtime, see the runtime's own documentation.
@@ -31,19 +32,14 @@ things supplied:
- The wasm `compiler-rt` builtins, through `LLDB_TEST_RESOURCE_DIR` pointed at
the wasi-sdk's clang resource directory.
-Either compiler needs the WASI sysroot, through `LLDB_TEST_SYSROOT`.
+Both compilers need the WASI sysroot, passed as `LLDB_TEST_SYSROOT`.
## Configuring the platform
-The `wasm` platform is selected with `--platform-name wasm`. Four global
-settings describe how to invoke the runtime:
-
-| Setting | Meaning |
-| --- | --- |
-| `platform.plugin.wasm.runtime-path` | Path to the runtime binary. A name without a directory separator is looked up in `PATH`. |
-| `platform.plugin.wasm.port-arg` | Argument carrying the GDB remote port. LLDB concatenates the port it chose. |
-| `platform.plugin.wasm.env-arg` | Argument forwarding one environment variable. LLDB concatenates a `key=value` pair, once per variable in the inferior's environment. When empty, no environment is forwarded. |
-| `platform.plugin.wasm.runtime-args` | Extra arguments for the runtime. They precede the port argument. |
+The `wasm` platform is selected with `--platform-name wasm`. The global
+[`platform.plugin.wasm`](/use/settings.md#wasm) settings `runtime-path`,
+`port-arg`, `env-arg` and `runtime-args` describe how to invoke the runtime.
+`env-arg` is optional. Set it to forward the inferior's environment.
LLDB assembles the runtime's command line as:
@@ -53,7 +49,8 @@ LLDB assembles the runtime's command line as:
`runtime-args` precedes the port argument, so a runtime that dispatches on a
leading subcommand names that subcommand there. `port-arg` has to carry the port
-in a single argument, because LLDB concatenates the two.
+in a single argument, because LLDB concatenates the two. `env-arg` is repeated
+once per environment variable, for example `--env=A=1 --env=B=2`.
A runtime's diagnostics share the inferior's standard error, so a verbose
runtime breaks tests that match program output. Use its quietest logging.
@@ -90,8 +87,11 @@ settings set -- platform.plugin.wasm.env-arg --env=
```
:::{note}
-WasmKit's debugger support is behind a package trait. The stub is only served by
-a CLI built with that trait enabled.
+WasmKit's debugger support is behind the `WasmDebuggingSupport` package trait.
+A CLI built without it rejects `--debugger-port` as an unknown option. Build
+with
+`swift build -c release --product wasmkit-cli --traits WasmDebuggingSupport`,
+adding whichever other traits you need.
:::
## Running the test suite
@@ -113,5 +113,7 @@ easier if you keep the build configured for the host. There `-C`, `--sysroot`
and `--resource-dir` replace the three CMake variables. Also pass a separate
`--build-dir` so Wasm and host inferiors do not share an output directory.
-Only the API tests build their inferiors, so this configuration does not affect
-`check-lldb-shell` or `check-lldb-unit`.
+The triple, platform and runtime settings reach only the API tests, so
+`check-lldb-unit` is unaffected and `check-lldb-shell` still builds for the
+host. `LLDB_TEST_SYSROOT` is the exception, since the shell tests also read it
+as their host sysroot. Keep the Wasm sysroot out of a build that runs them.
diff --git a/lldb/source/Plugins/Platform/WebAssembly/PlatformWasmProperties.td b/lldb/source/Plugins/Platform/WebAssembly/PlatformWasmProperties.td
index 21b4985524d1b..9ca5ee58c57f6 100644
--- a/lldb/source/Plugins/Platform/WebAssembly/PlatformWasmProperties.td
+++ b/lldb/source/Plugins/Platform/WebAssembly/PlatformWasmProperties.td
@@ -20,9 +20,10 @@ let Definition = "platformwasm", Path = "platform.plugin.wasm" in {
DefaultStringValue<"">,
Desc<"Argument to the WebAssembly runtime to forward an "
"environment variable to the inferior. A `key=value` pair "
- "is concatenated to this argument, once per variable in the "
- "inferior's environment. For example: `--env=`. If empty, "
- "no environment is forwarded to the runtime.">;
+ "is concatenated to this argument, and the argument is "
+ "repeated once per variable in the inferior's environment. "
+ "For example: `--env=` yields `--env=A=1 --env=B=2`. If "
+ "empty, no environment is forwarded to the runtime.">;
def RuntimeArgs : Property<"runtime-args", "Args">,
Global,
DefaultStringValue<"">,
More information about the lldb-commits
mailing list