| dbaaa92f | 24-Mar-2026 |
Chris Fallin <[email protected]> |
Debugging: add builtin gdbstub component. (#12771)
* Debugging: add builtin gdbstub component.
This adds a debug component that makes use of the debug-main world defined in #12756 and serves the gd
Debugging: add builtin gdbstub component. (#12771)
* Debugging: add builtin gdbstub component.
This adds a debug component that makes use of the debug-main world defined in #12756 and serves the gdbstub protocol, with Wasm extensions, compatible with LLDB.
This component is built and included inside the Wasmtime binary, and is loaded using the lower-level `-D debugger=...` debug-main option; the user doesn't need to specify the `.wasm` adapter component. Instead, the user simply runs `wasmtime run -g <PORT> program.wasm ...` and Wasmtime will load and prepare to run `program.wasm` as the debuggee, waiting for a gdbstub connection on the given TCP port before continuing.
The workflow is:
``` $ wasmtime run -g 1234 program.wasm [ wasmtime starts and waits for connection ]
$ /opt/wasi-sdk/bin/lldb # use LLDB from wasi-sdk release 32 or later (lldb) process connect --plugin wasm connect://localhost:1234 Process 1 stopped * thread #1, stop reason = signal SIGTRAP frame #0: 0x40000000000001cc -> 0x40000000000001cc: unreachable 0x40000000000001cd: end 0x40000000000001ce: local.get 0 0x40000000000001d0: call 13 (lldb) si Process 1 stopped * thread #1, stop reason = instruction step into frame #0: 0x4000000000000184 -> 0x4000000000000184: block 0x4000000000000186: block 0x4000000000000188: global.get 1 0x400000000000018e: i32.const 3664 [ ... ] ```
This makes use of the `gdbstub` third-party crate, into which I've upstreamed support for the Wasm extensions in daniel5151/gdbstub#188, daniel5151/gdbstub#189, daniel5151/gdbstub#190, and daniel5151/gdbstub#192. (I'll add vets as part of this PR.)
* cargo vets.
* Handle Trap events as well as breakpoints.
* Review feedback.
* Fix gdbstub artifact build to make it publishable (by disabling it when isolated crates are used).
* Review feedback.
* fix published-crates list
* For now, empty gdbstub data but no compile error when artifact crate is published.
* add some more Cargo metadata: version for artifact crate dep
show more ...
|
| 133a0ef4 | 13-Mar-2026 |
Chris Fallin <[email protected]> |
Debugging: add the debug-main world. (#12756)
* Debugging: add the debug-main world.
This PR "draws the rest of the owl" for the debug-main world (bytecodealliance/rfcs#45). This includes a WIT wor
Debugging: add the debug-main world. (#12756)
* Debugging: add the debug-main world.
This PR "draws the rest of the owl" for the debug-main world (bytecodealliance/rfcs#45). This includes a WIT world that hosts debug components that have access to "host debug powers" via a debugging API, and the ability to load such a debug-component and give it control of the main program as a debuggee when using `wasmtime run`.
The WIT is namespaced to `bytecodealliance:wasmtime` and is slightly aspirational in places: for example, the host does not yet implement injection of early return values or exception-throws. I intend to fill out a series of TODO issues once this all lands to track followup ("post-MVP") work.
This PR does not include any debug components. I separately have a gdbstub component, with which I tested and co-developed this host-side implementation. My plan is to land it in a followup PR as a component that will be embedded in/shipped with the Wasmtime CLI and available under an easy-to-use CLI option. Once we have that gdbstub component, we can also implement end-to-end integration tests that boot up LLDB and run through an expected interaction. (Separately, those integration tests will require a release of wasi-sdk to ship an LLDB binary that we can use.) As such, there are no real tests in this PR: interesting behaviors only really occur with a full end-to-end flow.
The integration with the CLI is a little awkward (we internally build another `wasmtime run` command that invokes the debug component, and tie it together with the debuggee via a special `invoke_debugger` API; this seemed less bad than reworking all of the WASI setup to be more reusable). Happy to take more ideas here.
* Review feedback.
* Review feedback.
* Review feedback: update vendor-wit.sh.
* Review feedback: -Ddebugger-arg= -> -Darg=.
* Review feedback.
* Review feedback.
* Review feedback: factor host.rs into several submodules.
* Review feedback: rename Debugger to Debuggee on host side.
* Review feedback: split inherit_stdin_stdout, and add corresponding options for the debug component.
* Review feedback.
* Review feedback.
* Add simple debug-component tests.
* Add wasm32-wasip2 target in a few places in CI
* Cargo vets for wstd dependency.
* Add wasm32-wasip2 in more places
* fix debug-component test dependence on componentization byte offsets
* Review feedback.
* Fix cancel-safety of EventFuture.
* Fix: Interrupted events should only occur after interrupt(), not on every epoch yield.
* Review feedback.
* Review feedback: strip down WASI imports in debugger world.
* fold debugger test component back into wasip1 + adapter test artifact compilation flow
show more ...
|