Skip to content

Adding initial debugging instructions for starlingmonkey debugger extension #268

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
squillace wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Adding initial debugging instructions for starlingmonkey debugger extension #268

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0e31c0d
Adding initial debugging instructions for vscode starlingmonkey debug…
squillace Aug 20, 2025
53a26c4
Merge branch 'main' into debugging-docs
squillace Aug 20, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 25 additions & 2 deletions docs/src/developer/debugging.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,26 @@
# Debugging StarlingMonkey application
# Debugging a StarlingMonkey application

TODO
StarlingMonkey is a JavaScript engine -- based on SpiderMonkey -- that is designed to be lightweight and efficient for compilation to WebAssembly components. To debug StarlingMonkey components means the component must implement some projection of the StarlingMonkey debugger API, as the WebAssembly sandbox prevents any access to internal code that isn't formally exposed.

This can be done with a custom WIT-defined API based directly on StarlingMonkey's debugger API, but for flexibility with different IDEs it makes sense to start with a debugging server approach in which a debug-build of the component adds the networking interfaces required to communicate with Visual Studio Code using the Debugger Application Protocol, or _DAP_.
Comment on lines +3 to +5
Copy link
Member

@tschneidereit tschneidereit Aug 29, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

While I think this is excellent background information, I'm not sure we need to front-load it in the documentation here.

How about we instead start with a short intro paragraph along these lines:

Suggested change
StarlingMonkey is a JavaScript engine -- based on SpiderMonkey -- that is designed to be lightweight and efficient for compilation to WebAssembly components. To debug StarlingMonkey components means the component must implement some projection of the StarlingMonkey debugger API, as the WebAssembly sandbox prevents any access to internal code that isn't formally exposed.
This can be done with a custom WIT-defined API based directly on StarlingMonkey's debugger API, but for flexibility with different IDEs it makes sense to start with a debugging server approach in which a debug-build of the component adds the networking interfaces required to communicate with Visual Studio Code using the Debugger Application Protocol, or _DAP_.
Through a combination of a custom sockets based protocol and a Visual Studio Code extension, StarlingMonkey implements the Debug Adapter Protocol, or _DAP_.
Currently, debugging content requires a bit of manual setup, which is described below:


## Visual Studio Code StarlingMonkey Debugger Extension

The Bytecode Alliance Foundation publishes a Visual Studio Code extension for debugging StarlingMonkey applications. This extension provides a user-friendly interface for setting breakpoints, inspecting variables, and controlling the execution flow of StarlingMonkey code running in a WebAssembly environment created using [componentize-js](https://github.com/bytecodealliance/componentize-js).
Copy link
Member

@tschneidereit tschneidereit Aug 29, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We don't commonly use the full official name of the BA:

Suggested change
The Bytecode Alliance Foundation publishes a Visual Studio Code extension for debugging StarlingMonkey applications. This extension provides a user-friendly interface for setting breakpoints, inspecting variables, and controlling the execution flow of StarlingMonkey code running in a WebAssembly environment created using [componentize-js](https://github.com/bytecodealliance/componentize-js).
The Bytecode Alliance publishes a Visual Studio Code extension for debugging StarlingMonkey applications. This extension provides a user-friendly interface for setting breakpoints, inspecting variables, and controlling the execution flow of StarlingMonkey code running in a WebAssembly environment created using [componentize-js](https://github.com/bytecodealliance/componentize-js).


The steps to use this extension in VSCode are:
1. Download and install the [StarlingMonkey Debugger extension](https://marketplace.visualstudio.com/items?itemName=BytecodeAlliance.starlingmonkey-debugger).
2. Open your StarlingMonkey project in VSCode and create a launch.json file that follows [this configuration pattern](https://marketplace.visualstudio.com/items?itemName=BytecodeAlliance.starlingmonkey-debugger#running-content).
3. Make a copy of the `wit` folder to a folder named `wit-debug`. In that `wit-debug` folder, rename the the world .wit file to add `-debug` to the filename and include the following extra interfaces that support the debug connection from StarlingMonkey to Visual Studio Code:
Copy link

Copilot AI Aug 29, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There's a duplicate word 'the' in 'rename the the world .wit file'. Should be 'rename the world .wit file'.

Suggested change
3. Make a copy of the `wit` folder to a folder named `wit-debug`. In that `wit-debug` folder, rename the the world .wit file to add `-debug` to the filename and include the following extra interfaces that support the debug connection from StarlingMonkey to Visual Studio Code:
3. Make a copy of the `wit` folder to a folder named `wit-debug`. In that `wit-debug` folder, rename the world .wit file to add `-debug` to the filename and include the following extra interfaces that support the debug connection from StarlingMonkey to Visual Studio Code:

Copilot uses AI. Check for mistakes.
Copy link
Member

@tschneidereit tschneidereit Aug 29, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This step is only required if the world doesn't already include the necessary interfaces. Would be good to rephrase it accordingly. Along the lines of "Debugging content requires access to some WASI interfaces the component might not already import. If your component doesn't import the following list of interfaces, you need to [..]", perhaps?

```bash
import wasi:cli/environment@0.2.3;
import wasi:sockets/network@0.2.3;
import wasi:sockets/instance-network@0.2.3;
import wasi:sockets/tcp@0.2.3;
import wasi:sockets/tcp-create-socket@0.2.3;
```
4. Retarget the debug build command to be of the form: `npm run bundle && componentize-js --use-debug-build --runtime-args \"--enable-script-debugging\" --wit <wit-debug> -o dist/$npm_package_name.wasm dist/bundle.js` where the `-o` path is to the bundle file name that is specified in the `rollup.config.js` file.
Copy link
Member

@andreiltd andreiltd Aug 29, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wouldn't mention rollout specifics here: 1) user may not use rollout at all, 2) there are many rollout alternatives widely used. I think just componentize-js command would be enough here:

componentize-js --use-debug-build --runtime-args \"--enable-script-debugging\" --wit <wit-debug> -o output.wasm index.js

The -o tells componentize-js the name of output wasm component and the positional argument index.js is an input JS script.


An example may be found in the https://github.com/bytecodealliance/sample-wasi-http-js/package.json file.
Copy link

Copilot AI Aug 29, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The reference to the example should be properly formatted as a markdown link for better readability and accessibility: [sample-wasi-http-js package.json](https://github.com/bytecodealliance/sample-wasi-http-js/package.json).

Suggested change
An example may be found in the https://github.com/bytecodealliance/sample-wasi-http-js/package.json file.
An example may be found in the [`sample-wasi-http-js package.json`](https://github.com/bytecodealliance/sample-wasi-http-js/package.json) file.

Copilot uses AI. Check for mistakes.

Currently, the StarlingMonkey Debugger extension is in active development. (The objective is to use this extension as a generalizable mechanism for any language debugger that requires a debug server to project itself to Visual Studio Code.)