DOCSEARCHbyAlgolia
Submit Docs

StarlingMonkey

repository·main·Indexed 42 days ago

https://github.com/bytecodealliance/starlingmonkey

A SpiderMonkey-based JavaScript runtime optimized for WebAssembly Components. It supports WASI 0.2.0 and provides standards-compliant implementations of web builtins such as the fetch API and WHATWG Streams. The project includes tools for building specialized WebAssembly Components from JS/TS code and a VS Code debugger extension.

Tokens
16.9K
Snippets
71
Records
88
Agent score
55%

What's inside StarlingMonkey

  1. How the StarlingMonkey VS Code extension publishing workflow works

    main

    The StarlingMonkey VS Code debugger extension is published automatically to the VS Code Marketplace via GitHub Actions when changes are merged into the main branch that affect the debugger/vscode-dap-extension/ directory.

    The workflow consists of two main stages:

    1. release-please: Monitors changes and creates/updates a release PR. Merging this PR creates a GitHub release with a version tag (e.g., v0.3.0).
    2. publish-extension: Triggered by a new GitHub release. It builds the extension, packages it as a .vsix file, publishes it to the Marketplace, and uploads the .vsix to the GitHub release.

  2. SpiderMonkey rooting rules for C++ developers

    main

    Because SpiderMonkey uses a moving Garbage Collector (GC), you must ensure the engine is aware of all pointers to GC-managed objects. Follow these rooting rules to prevent memory corruption:

    • Local stack variables: Use JS::Rooted<T>.
    • Function parameters: Use JS::Handle<T>.
    • Function out-parameters: Use JS::MutableHandle<T>.
    • Implicit/Explicit casting: Use an implicit cast from JS::Rooted<T> to get a JS::Handle<T>, or an explicit address-of-operator on JS::Rooted<T> to get a JS::MutableHandle<T>.
    • Return values: Return raw pointers from functions.
    • Aggregates: Use JS::Rooted<T> fields when possible; otherwise, use an AutoRooter.
    • Heap data: Use JS::Heap<T> members. Note: Heap<T> objects are not "rooted" and must be traced.
    • Persistence: Use JS::PersistentRooted<T> for objects that must live until the process exits or until manually deleted.

    CRITICAL: Do not use JS::Rooted<T>, JS::Handle<T>, or JS::MutableHandle<T> on the heap. Do not use JS::Rooted<T> for function parameters.

  3. Use custom SpiderMonkey binaries in StarlingMonkey

    main

    To use your locally modified SpiderMonkey binaries instead of the default downloaded ones, set the SPIDERMONKEY_BINARIES environment variable to the path of your local release/ directory before configuring and building StarlingMonkey with CMake.

    export SPIDERMONKEY_BINARIES=/path/to/spidermonkey-wasi-embedding/release
cmake -S . -B cmake-build-release -DCMAKE_BUILD_TYPE=Release
cmake --build cmake-build-release --parallel 8

  4. Create components directly from JS files

    main

    Instead of using the pre-built starling.wasm component, you can use the componentize.sh script provided in the build directory to create a component directly from a JavaScript file. This approach loads the JS file during the componentization process, executing top-level code (such as registering a fetch event handler) and producing a standalone .wasm component.

    Workflow

    1. Navigate to your build directory (e.g., cmake-build-release).
    2. Run componentize.sh on your JS file.
    3. Run the resulting component with wasmtime.
    cd cmake-build-release
./componentize.sh index.js
wasmtime -S http --dir . index.wasm
    cd cmake-build-release
./componentize.sh index.js
wasmtime -S http --dir . index.wasm

  6. Develop changes to the underlying SpiderMonkey engine

    main

    By default, StarlingMonkey downloads pre-built SpiderMonkey artifacts from the spidermonkey-wasi-embedding repository. If you need to modify SpiderMonkey directly (e.g., for bug fixes or performance optimizations), you must clone the engine source, apply your changes, and rebuild the artifacts locally.

    To do this, you must structure your local environment so that gecko-dev is a subdirectory of spidermonkey-wasi-embedding and ensure you are working on the specific commit hash used by the current StarlingMonkey version.

    git clone https://github.com/bytecodealliance/spidermonkey-wasi-embedding
cd spidermonkey-wasi-embedding/
git clone https://github.com/bytecodealliance/gecko-dev

git checkout `cat ../gecko-revision`
# now edit the source

cd ../
./rebuild.sh release

  8. Build the project using `just build`

    main

    To configure a default cmake-build-debug directory and build the project, run:

    just build

    Note on Reconfiguration: By default, CMake configuration is skipped if the build directory already exists. If you switch targets (e.g., from a default build to a WPT build) and encounter issues, force a reconfiguration using the reconfigure=true parameter:

    just reconfigure=true wpt-build

  9. Configure VSCE_PAT for Marketplace publishing

    main

    To enable automated publishing to the VS Code Marketplace, a Personal Access Token (PAT) must be configured as a GitHub repository secret named VSCE_PAT.

    Setup Steps:

    1. Go to https://dev.azure.com.
    2. Create a Personal Access Token (PAT) with the following settings:
      • Organization: All accessible organizations
      • Scopes: Marketplace > Manage
    3. Add the generated token to your GitHub repository settings as a secret named VSCE_PAT.

  10. Trigger a new VS Code extension release

    main

    To trigger a release, follow these steps:

    1. Modify files within the debugger/vscode-dap-extension/ directory.
    2. Use Conventional Commits with the debugger scope to ensure release-please can determine the correct version bump:
      • feat(debugger): -> Minor version bump
      • fix(debugger): -> Patch version bump
      • BREAKING CHANGE: (in footer) -> Major version bump
      • chore(debugger):, docs(debugger):, etc. -> No version bump
    3. Open and merge a PR to main.
    4. Merge the subsequent release PR created by release-please to initiate the actual publishing process.

  12. Start and use the WPT Server

    main

    After running just wpt-setup, you can start a Web Platform Tests (WPT) server:

    just wpt-server

    Once the server is running, you can interact with tests via a web interface at http://127.0.0.1:7879/. You can filter tests by providing prefixes or exact names in the URL:

    • All StarlingMonkey WPT tests: http://127.0.0.1:7879/
    • All console tests: http://127.0.0.1:7879/console
    • Specific test: http://127.0.0.1:7879/console/console-log-symbol.any.js