feat: the wasm runtime is a feature that cargo wasm turns on

Author: dylan-sutton-chavez

.cargo/config.toml

@@ -1,5 +1,5 @@
 # `cargo wasm` build edge-python release WebAssembly artifact.
 [alias]
-wasm = "build --release --target wasm32-unknown-unknown -p edge-python --no-default-features"
+wasm = "rustc --release --target wasm32-unknown-unknown -p edge-python --lib --no-default-features --features runtime --crate-type cdylib,rlib"
 # `cargo wasm-cli` builds the speed-tuned copy released CLIs embed.
-wasm-cli = "build --profile cli --target wasm32-unknown-unknown -p edge-python --no-default-features"
+wasm-cli = "rustc --profile cli --target wasm32-unknown-unknown -p edge-python --lib --no-default-features --features runtime --crate-type cdylib,rlib"

.github/actions/compiler/action.yml

@@ -37,7 +37,9 @@ runs:
 
     - name: Clippy (wasm)
       shell: bash
-      run: cargo clippy --locked --lib --no-default-features --target wasm32-unknown-unknown -p edge-python -p slugify-mod -- -D warnings
+      run: |
+        cargo clippy --locked --lib --no-default-features --features edge-python/runtime --target wasm32-unknown-unknown -p edge-python -p slugify-mod -- -D warnings
+        cargo clippy --locked --lib --no-default-features --target wasm32-unknown-unknown -p edge-python -- -D warnings
 
     # build-std needs nightly plus rust-src.
     - name: Toolchain (nightly)
@@ -58,12 +60,14 @@ runs:
       shell: bash
       run: |
         RUSTFLAGS="-Z location-detail=none -Z fmt-debug=none -Z unstable-options -C panic=immediate-abort" \
-        cargo +nightly build \
+        cargo +nightly rustc \
           --target wasm32-unknown-unknown \
           --lib \
           --release \
           -p edge-python \
           --no-default-features \
+          --features runtime \
+          --crate-type cdylib,rlib \
           -Z build-std=std,panic_abort \
           -Z build-std-features=optimize_for_size
 
@@ -110,7 +114,7 @@ runs:
     - name: Build (CLI)
       shell: bash
       run: |
-        cargo build --locked --profile cli --target wasm32-unknown-unknown -p edge-python --no-default-features
+        cargo rustc --locked --profile cli --target wasm32-unknown-unknown -p edge-python --lib --no-default-features --features runtime --crate-type cdylib,rlib
         CLI_WASM=target/wasm32-unknown-unknown/cli/compiler.wasm
         wasm-opt -O3 --enable-bulk-memory --enable-bulk-memory-opt --enable-nontrapping-float-to-int --enable-sign-ext --enable-mutable-globals --enable-multivalue --enable-reference-types -o /tmp/compiler-cli.wasm "$CLI_WASM"
         mv /tmp/compiler-cli.wasm "$CLI_WASM"

CONTRIBUTING.md

@@ -24,7 +24,8 @@ Run these from the repo root before sending. The maintainer runs CI once the PR
 cargo wasm
 cargo test --release
 cargo clippy --all-targets -- -D warnings
-cargo clippy --lib --no-default-features --target wasm32-unknown-unknown -p edge-python -p slugify-mod -- -D warnings
+cargo clippy --lib --no-default-features --features edge-python/runtime --target wasm32-unknown-unknown -p edge-python -p slugify-mod -- -D warnings
+cargo clippy --lib --no-default-features --target wasm32-unknown-unknown -p edge-python -- -D warnings
 cargo shear
 ```
 
@@ -38,9 +39,11 @@ The root Cargo workspace holds the engine, `abi`, `pdk`, `skill`, `lang` and `be
 
 ```bash
 cargo wasm # compiler.wasm, CI ships a smaller build
-cargo build --release # .rlib and cdylib for Rust embedders
+cargo build --release # the .rlib Rust embedders link
 ```
 
+`cargo wasm` turns on the `runtime` feature, the wrapper that makes `compiler.wasm` with its exports, host imports, allocator and panic handler. Without it the crate is the engine alone, for a wasm that links it as a library, such as a plugin that only parses.
+
 `cli/` embeds `compiler.wasm` and the JS host from `js/dist` at build time. Build them first, or point `EDGE_COMPILER_WASM` and `EDGE_JS_DIST` at copies. Releases embed the speed build from `cargo wasm-cli`.
 
 The system calls in `js/src/system` run in SpiderMonkey inside the CLI, through `mozjs`, which compiles SpiderMonkey from source on the first build and wants clang, python3 and `llvm-objdump` on the path. On macOS a symlink named `llvm-objdump` to `/usr/bin/objdump` serves, and CI sets `MOZJS_FROM_SOURCE=1` on every target. The static Linux binary builds inside `rust:alpine` through [`.github/actions/cli/musl.sh`](.github/actions/cli/musl.sh), since musl-gcc has no C++.

Cargo.toml

@@ -9,9 +9,9 @@ readme = "README.md"
 autotests = false
 autobins = false
 
+# `cargo wasm` builds compiler.wasm as a cdylib, so a crate depending on this one links a plain rlib.
 [lib]
 name = "compiler"
-crate-type = ["cdylib", "rlib"]
 doctest = false
 
 [[test]]
@@ -23,6 +23,8 @@ default = ["std"]
 std = []
 # Records each instruction a run executes for `VM::ran`, method calls left unfused so every ip is the compiler's own.
 coverage = []
+# The wrapper that makes compiler.wasm, its exports, host imports, allocator and panic handler.
+runtime = []
 
 [dependencies]
 wasm-abi = { workspace = true }

docs/03-reference/06-abi.mdx

@@ -504,14 +504,20 @@ Little-endian, self-contained, versioned.
 
 ## Consuming the release from a Rust crate
 
-The `edge-python` crate builds as a `cdylib`. A Rust host can instantiate `compiler.wasm` and call the exports above directly, the same `.wasm` the JS host loads, with the host owning I/O. The crate builds no wasm of its own and fetches nothing at build time, so `cargo build` stays offline and reproducible. Take the artifact from the tagged GitHub Release, or from `https://cdn.edgepython.com/compiler.wasm` for the current `main`. The `edge` CLI is that host, it embeds the `.wasm` precompiled by wasmtime and implements the imports in `cli/src/host`.
+`cargo wasm` builds the `edge-python` crate as a `cdylib`, `compiler.wasm`. A Rust host can instantiate `compiler.wasm` and call the exports above directly, the same `.wasm` the JS host loads, with the host owning I/O. The crate builds no wasm of its own and fetches nothing at build time, so `cargo build` stays offline and reproducible. Take the artifact from the tagged GitHub Release, or from `https://cdn.edgepython.com/compiler.wasm` for the current `main`. The `edge` CLI is that host, it embeds the `.wasm` precompiled by wasmtime and implements the imports in `cli/src/host`.
 
 ```toml
 # Downstream Cargo.toml
 [dependencies]
 edge-python = { git = "https://github.com/dylan-sutton-chavez/edge-python", tag = "v0.1.0" }
 ```
 
+The `runtime` feature is the wrapper that makes `compiler.wasm`, its exports, host imports, allocator and panic handler, and `cargo wasm` turns it on. A wasm that links the crate as a library, such as a plugin that only parses, leaves it off and brings its own allocator and panic handler.
+
+```toml
+edge-python = { git = "https://github.com/dylan-sutton-chavez/edge-python", tag = "v0.1.0", default-features = false }
+```
+
 Vendor the matching `compiler.wasm` next to your own sources and pin it by checksum, the same way the CLI pins the modules it downloads. A release asset is immutable and the CDN path is not, so a checksum is the only thing that ties a build to a known engine.
 
 To add native modules from a Rust host, implement the `Resolver` trait. See [Modules](/docs/reference/modules).

docs/03-reference/07-embedding.mdx

@@ -18,7 +18,7 @@ The `lang` crate is a small, clean embedding API over the Edge Python engine. Us
 lang = { git = "https://github.com/dylan-sutton-chavez/edge-python", tag = "v0.1.0" }
 ```
 
-`lang` is `no_std` and needs only `alloc`. The default `std` feature links the host standard library, and `default-features = false` drops it for wasm and bare-metal targets.
+`lang` is `no_std` and needs only `alloc`. The default `std` feature links the host standard library, and `default-features = false` drops it for wasm and bare-metal targets. On wasm the program that embeds `lang` brings its own allocator and panic handler, since `lang` takes the engine without its `runtime`.
 
 ## Compile and run
 

src/lib.rs

@@ -4,11 +4,11 @@ extern crate alloc;
 
 pub mod abi;
 
-/* Host bridge behind the six plugin imports, wasm only. */
-#[cfg(target_arch = "wasm32")]
+/* Host bridge behind the six plugin imports, part of the wasm `runtime`. */
+#[cfg(all(target_arch = "wasm32", feature = "runtime"))]
 pub mod bridge;
 
-#[cfg(target_arch = "wasm32")]
+#[cfg(all(target_arch = "wasm32", feature = "runtime"))]
 pub mod wasm;
 
 /* Internal compiler helpers (not Edge Python stdlib), separate from pipeline code. */

src/vm/gc.rs

@@ -29,7 +29,7 @@ impl<'a> VM<'a> {
             }
         }
         for &v in current_slots { self.heap.mark(v); }
-        #[cfg(target_arch = "wasm32")]
+        #[cfg(all(target_arch = "wasm32", feature = "runtime"))]
         crate::bridge::mark_handles(self as *const Self as *const u8, &mut self.heap);
         for &v in &self.live_slots { self.heap.mark(v); }
         // Closure cells live on the active call frames until the closures that capture them are built.

src/vm/globals/container.rs

@@ -47,14 +47,14 @@ impl<'a> VM<'a> {
     }
 
     // Build a set Val from items, rejecting unhashable elements first.
-    #[cfg(target_arch = "wasm32")]
+    #[cfg(all(target_arch = "wasm32", feature = "runtime"))]
     pub(crate) fn set_from_items(&mut self, items: Vec<Val>) -> Result<Val, VmErr> {
         for &v in items.iter().filter(|v| v.is_heap()) { self.require_hashable(v)?; }
         self.alloc_set_result(items, false)
     }
 
     // Build a frozenset Val from items, rejecting unhashable elements first.
-    #[cfg(target_arch = "wasm32")]
+    #[cfg(all(target_arch = "wasm32", feature = "runtime"))]
     pub(crate) fn frozenset_from_items(&mut self, items: Vec<Val>) -> Result<Val, VmErr> {
         for &v in items.iter().filter(|v| v.is_heap()) { self.require_hashable(v)?; }
         self.alloc_set_result(items, true)