feat: add world selection for multi-world WIT files

.github/dependabot.yml

@@ -32,7 +32,7 @@ updates:
       - dependency-name: "wasmtime"
         update-types: ["version-update:semver-minor", "version-update:semver-major"]
   - package-ecosystem: "cargo"
-    directory: "/src/rust_wasm_samples"
+    directory: "/src/tests/rust_guests/rust_wasm_samples"
     schedule:
       interval: "daily"
       time: "03:00"
@@ -48,7 +48,7 @@ updates:
     labels:
       - "kind/dependencies"
   - package-ecosystem: "cargo"
-    directory: "/src/component_sample"
+    directory: "/src/tests/rust_guests/component_sample"
     schedule:
       interval: "daily"
       time: "03:00"

.github/workflows/dep_build_wasm_examples.yml

@@ -66,8 +66,8 @@ jobs:
         # Only push if not from a fork, not from pull request, and not from dependabot
           uses: docker/build-push-action@v6
           with:
-            context: src/wasmsamples
-            file: src/wasmsamples/dockerfile
+            context: src/tests/c_guests/wasmsamples
+            file: src/tests/c_guests/wasmsamples/dockerfile
             load: true
             push: ${{ env.DO_PUSH }}
             build-args: |
@@ -81,7 +81,6 @@ jobs:
             just ensure-tools
             just build-wasm-examples release
           shell: bash
-          working-directory:  src/wasmsamples
         - name: Upload Wasm Modules
           uses: actions/upload-artifact@v4
           with:

.github/workflows/dep_rust.yml

@@ -120,10 +120,6 @@ jobs:
           # required for gh cli when downloading
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
-      - name: Test Component Model Examples
-        run: just examples-components ${{ matrix.config }}
-        working-directory: ./src/hyperlight_wasm
-
       ### Benchmarks ###
 
       - name: Download benchmarks from "latest"

CHANGELOG.md

@@ -6,8 +6,12 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 ## [Prerelease] - Unreleased
 
 ### Changed
+
 - **BREAKING CHANGE:** Removed `SandboxBuilder::with_function_definition_size`. Host function definitions are now pushed to the guest at runtime load time instead of using a separate memory region. (#388)
 
+### Added
+- Added support for selecting a specific world from WIT files with multiple worlds using the `WIT_WORLD_NAME` environment variable (#202)
+
 ## [v0.12.0] - 2025-12
 
 ### Added

Cargo.toml

@@ -1,6 +1,6 @@
 [workspace]
 members = [ "src/hyperlight_wasm", "src/examples_common", "src/hyperlight_wasm_aot", "src/hyperlight_wasm_runtime", "src/hyperlight_wasm_macro" ]
-exclude = [ "src/rust_wasm_samples", "src/component_sample" ]
+exclude = [ "src/tests/rust_guests/rust_wasm_samples", "src/tests/rust_guests/component_sample", "src/tests/rust_guests/greeter_sample" ]
 resolver = "2"
 
 [workspace.package]

Justfile

@@ -3,11 +3,18 @@ default-tag:= "latest"
 build-wasm-examples-command := if os() == "windows" { "./src/hyperlight_wasm/scripts/build-wasm-examples.bat" } else { "./src/hyperlight_wasm/scripts/build-wasm-examples.sh" }
 mkdir-arg := if os() == "windows" { "-Force" } else { "-p" }
 latest-release:= if os() == "windows" {"$(git tag -l --sort=v:refname | select -last 2 | select -first 1)"} else {`git tag -l --sort=v:refname | tail -n 2 | head -n 1`}
-wit-world := if os() == "windows" { "$env:WIT_WORLD=\"" + justfile_directory() + "\\src\\component_sample\\wit\\component-world.wasm" + "\";" } else { "WIT_WORLD=" + justfile_directory() + "/src/component_sample/wit/component-world.wasm" }
-wit-world-c := if os() == "windows" { "$env:WIT_WORLD=\"" + justfile_directory() + "\\src\\wasmsamples\\components\\runcomponent-world.wasm" + "\";" } else { "WIT_WORLD=" + justfile_directory() + "/src/wasmsamples/components/runcomponent-world.wasm" }
+wit-world := if os() == "windows" { "$env:WIT_WORLD=\"" + justfile_directory() + "\\src\\tests\\rust_guests\\component_sample\\wit\\component-world.wasm" + "\";" } else { "WIT_WORLD=" + justfile_directory() + "/src/tests/rust_guests/component_sample/wit/component-world.wasm" }
+wit-world-c := if os() == "windows" { "$env:WIT_WORLD=\"" + justfile_directory() + "\\src\\tests\\c_guests\\wasmsamples\\components\\runcomponent-world.wasm" + "\";" } else { "WIT_WORLD=" + justfile_directory() + "/src/tests/c_guests/wasmsamples/components/runcomponent-world.wasm" }
+wit-world-name-greeter := if os() == "windows" { "$env:WIT_WORLD_NAME=\"greeter-world\";" } else { "WIT_WORLD_NAME=greeter-world" }
 
 set windows-shell := ["pwsh.exe", "-NoLogo", "-Command"]
 
+make-vendor-tar:
+    tar cf ./src/hyperlight_wasm/vendor.tar \
+        --owner=0 --group=0 \
+        --exclude-vcs-ignores \
+        -C ./src wasm_runtime hyperlight_wasm_macro
+
 ensure-tools:
     cargo install wasm-tools --locked --version 1.235.0
     cargo install cargo-component --locked --version 0.21.1
@@ -24,8 +31,8 @@ mkdir-redist target=default-target:
     mkdir {{ mkdir-arg }} x64/{{ target }}
 
 compile-wit:
-    wasm-tools component wit ./src/wasmsamples/components/runcomponent.wit -w -o ./src/wasmsamples/components/runcomponent-world.wasm
-    wasm-tools component wit ./src/component_sample/wit/example.wit -w -o ./src/component_sample/wit/component-world.wasm
+    wasm-tools component wit ./src/tests/c_guests/wasmsamples/components/runcomponent.wit -w -o ./src/tests/c_guests/wasmsamples/components/runcomponent-world.wasm
+    wasm-tools component wit ./src/tests/rust_guests/component_sample/wit/example.wit -w -o ./src/tests/rust_guests/component_sample/wit/component-world.wasm
 
 build-examples target=default-target features="": (build-wasm-examples target features) (build-rust-wasm-examples target features) (build-rust-component-examples target features)
 
@@ -34,54 +41,63 @@ build-wasm-examples target=default-target features="": (compile-wit)
 
 build-rust-wasm-examples target=default-target features="": (mkdir-redist target)
     rustup target add wasm32-unknown-unknown
-    cd ./src/rust_wasm_samples && cargo build --target wasm32-unknown-unknown --profile={{ if target == "debug" {"dev"} else { target } }}
-    cargo run {{ if features =="" {''} else if features=="no-default-features" {"--no-default-features" } else {"--features " + features } }} -p hyperlight-wasm-aot compile {{ if features =~ "gdb" {"--debug"} else {""} }} ./src/rust_wasm_samples/target/wasm32-unknown-unknown/{{ target }}/rust_wasm_samples.wasm ./x64/{{ target }}/rust_wasm_samples.aot
+    cd ./src/tests/rust_guests/rust_wasm_samples && cargo build --target wasm32-unknown-unknown --profile={{ if target == "debug" {"dev"} else { target } }}
+    cargo run {{ if features =="" {''} else if features=="no-default-features" {"--no-default-features" } else {"--features " + features } }} -p hyperlight-wasm-aot compile {{ if features =~ "gdb" {"--debug"} else {""} }} ./src/tests/rust_guests/rust_wasm_samples/target/wasm32-unknown-unknown/{{ target }}/rust_wasm_samples.wasm ./x64/{{ target }}/rust_wasm_samples.aot
 
 build-pulley-rust-wasm-examples target=default-target features="": (mkdir-redist target)
     rustup target add wasm32-unknown-unknown
-    cd ./src/rust_wasm_samples && cargo build --target wasm32-unknown-unknown --profile={{ if target == "debug" {"dev"} else { target } }}
-    cargo run {{ if features =="" {''} else if features=="no-default-features" {"--no-default-features" } else {"--features " + features } }} -p hyperlight-wasm-aot compile --pulley {{ if features =~ "gdb" {"--debug"} else {""} }} ./src/rust_wasm_samples/target/wasm32-unknown-unknown/{{ target }}/rust_wasm_samples.wasm ./x64/{{ target }}/rust_wasm_samples.aot
+    cd ./src/tests/rust_guests/rust_wasm_samples && cargo build --target wasm32-unknown-unknown --profile={{ if target == "debug" {"dev"} else { target } }}
+    cargo run {{ if features =="" {''} else if features=="no-default-features" {"--no-default-features" } else {"--features " + features } }} -p hyperlight-wasm-aot compile --pulley {{ if features =~ "gdb" {"--debug"} else {""} }} ./src/tests/rust_guests/rust_wasm_samples/target/wasm32-unknown-unknown/{{ target }}/rust_wasm_samples.wasm ./x64/{{ target }}/rust_wasm_samples.aot
 
 build-rust-component-examples target=default-target features="": (compile-wit)
     # use cargo component so we don't get all the wasi imports https://github.com/bytecodealliance/cargo-component?tab=readme-ov-file#relationship-with-wasm32-wasip2
     # we also explicitly target wasm32-unknown-unknown since cargo component might try to pull in wasi imports https://github.com/bytecodealliance/cargo-component/issues/290
     rustup target add wasm32-unknown-unknown
-    cd ./src/component_sample && cargo component build --target wasm32-unknown-unknown --profile={{ if target == "debug" {"dev"} else { target } }}
-    cargo run {{ if features =="" {''} else if features=="no-default-features" {"--no-default-features" } else {"--features " + features } }} -p hyperlight-wasm-aot compile {{ if features =~ "gdb" {"--debug"} else {""} }} --component ./src/component_sample/target/wasm32-unknown-unknown/{{ target }}/component_sample.wasm ./x64/{{ target }}/component_sample.aot
+    cd ./src/tests/rust_guests/component_sample && cargo component build --target wasm32-unknown-unknown --profile={{ if target == "debug" {"dev"} else { target } }}
+    cargo run {{ if features =="" {''} else if features=="no-default-features" {"--no-default-features" } else {"--features " + features } }} -p hyperlight-wasm-aot compile {{ if features =~ "gdb" {"--debug"} else {""} }} --component ./src/tests/rust_guests/component_sample/target/wasm32-unknown-unknown/{{ target }}/component_sample.wasm ./x64/{{ target }}/component_sample.aot
+    cd ./src/tests/rust_guests/greeter_sample && cargo component build --target wasm32-unknown-unknown --profile={{ if target == "debug" {"dev"} else { target } }}
+    cargo run {{ if features =="" {''} else if features=="no-default-features" {"--no-default-features" } else {"--features " + features } }} -p hyperlight-wasm-aot compile {{ if features =~ "gdb" {"--debug"} else {""} }} --component ./src/tests/rust_guests/greeter_sample/target/wasm32-unknown-unknown/{{ target }}/greeter_sample.wasm ./x64/{{ target }}/greeter_sample.aot
 
 build-pulley-rust-component-examples target=default-target features="": (compile-wit)
     # use cargo component so we don't get all the wasi imports https://github.com/bytecodealliance/cargo-component?tab=readme-ov-file#relationship-with-wasm32-wasip2
     # we also explicitly target wasm32-unknown-unknown since cargo component might try to pull in wasi imports https://github.com/bytecodealliance/cargo-component/issues/290
     rustup target add wasm32-unknown-unknown
-    cd ./src/component_sample && cargo component build --target wasm32-unknown-unknown --profile={{ if target == "debug" {"dev"} else { target } }}
-    cargo run {{ if features =="" {''} else if features=="no-default-features" {"--no-default-features" } else {"--features " + features } }} -p hyperlight-wasm-aot compile --pulley {{ if features =~ "gdb" {"--debug"} else {""} }} --component ./src/component_sample/target/wasm32-unknown-unknown/{{ target }}/component_sample.wasm ./x64/{{ target }}/component_sample.aot
+    cd ./src/tests/rust_guests/component_sample && cargo component build --target wasm32-unknown-unknown --profile={{ if target == "debug" {"dev"} else { target } }}
+    cargo run {{ if features =="" {''} else if features=="no-default-features" {"--no-default-features" } else {"--features " + features } }} -p hyperlight-wasm-aot compile --pulley {{ if features =~ "gdb" {"--debug"} else {""} }} --component ./src/tests/rust_guests/component_sample/target/wasm32-unknown-unknown/{{ target }}/component_sample.wasm ./x64/{{ target }}/component_sample.aot
 
 check target=default-target:
     cargo check --profile={{ if target == "debug" {"dev"} else { target } }}
-    cd src/rust_wasm_samples  && cargo check --profile={{ if target == "debug" {"dev"} else { target } }}
-    cd src/component_sample  && cargo check --profile={{ if target == "debug" {"dev"} else { target } }}
+    cd src/tests/rust_guests/rust_wasm_samples  && cargo check --profile={{ if target == "debug" {"dev"} else { target } }}
+    cd src/tests/rust_guests/component_sample  && cargo check --profile={{ if target == "debug" {"dev"} else { target } }}
+    cd src/tests/rust_guests/greeter_sample  && cargo check --profile={{ if target == "debug" {"dev"} else { target } }}
     cd src/hyperlight_wasm_runtime && cargo hyperlight check --profile={{ if target == "debug" {"dev"} else { target } }}
     cd src/hyperlight_wasm_macro && cargo check --profile={{ if target == "debug" {"dev"} else { target } }}
 
 fmt-check:
     rustup toolchain install nightly -c rustfmt && cargo +nightly fmt -v --all -- --check
-    cd src/rust_wasm_samples && rustup toolchain install nightly -c rustfmt && cargo +nightly fmt -v --all -- --check
-    cd src/component_sample && rustup toolchain install nightly -c rustfmt && cargo +nightly fmt -v --all -- --check
+    cd src/tests/rust_guests/rust_wasm_samples && rustup toolchain install nightly -c rustfmt && cargo +nightly fmt -v --all -- --check
+    cd src/tests/rust_guests/component_sample && rustup toolchain install nightly -c rustfmt && cargo +nightly fmt -v --all -- --check
+    cd src/tests/rust_guests/greeter_sample && rustup toolchain install nightly -c rustfmt && cargo +nightly fmt -v --all -- --check
     cd src/hyperlight_wasm_runtime && rustup toolchain install nightly -c rustfmt && cargo +nightly fmt -v --all -- --check
     cd src/hyperlight_wasm_macro && rustup toolchain install nightly -c rustfmt && cargo +nightly fmt -v --all -- --check
 
 fmt:
     rustup toolchain install nightly -c rustfmt
     cargo +nightly fmt --all
-    cd src/rust_wasm_samples &&  cargo +nightly fmt -v --all
-    cd src/component_sample &&  cargo +nightly fmt -v --all
+    cd src/tests/rust_guests/rust_wasm_samples &&  cargo +nightly fmt -v --all
+    cd src/tests/rust_guests/component_sample &&  cargo +nightly fmt -v --all
+    cd src/tests/rust_guests/greeter_sample &&  cargo +nightly fmt -v --all
     cd src/hyperlight_wasm_runtime && cargo +nightly fmt -v --all
     cd src/hyperlight_wasm_macro && cargo +nightly fmt -v --all
 
+export CC_x86_64_unknown_none:= if os() == "windows" { justfile_directory() / "src/hyperlight_wasm_runtime/guest-toolchain/clang" } else { "" }
+export AR_x86_64_unknown_none:= if os() == "windows" { "llvm-ar" } else { "" }
+
 clippy target=default-target: (check target)
     cargo clippy --profile={{ if target == "debug" {"dev"} else { target } }} --all-targets --all-features -- -D warnings
-    cd src/rust_wasm_samples &&  cargo clippy --profile={{ if target == "debug" {"dev"} else { target } }} --all-targets --all-features -- -D warnings
-    cd src/component_sample &&  cargo clippy --profile={{ if target == "debug" {"dev"} else { target } }} --all-targets --all-features -- -D warnings
+    cd src/tests/rust_guests/rust_wasm_samples &&  cargo clippy --profile={{ if target == "debug" {"dev"} else { target } }} --all-targets --all-features -- -D warnings
+    cd src/tests/rust_guests/component_sample &&  cargo clippy --profile={{ if target == "debug" {"dev"} else { target } }} --all-targets --all-features -- -D warnings
+    cd src/tests/rust_guests/greeter_sample &&  cargo clippy --profile={{ if target == "debug" {"dev"} else { target } }} --all-targets --all-features -- -D warnings
     cd src/hyperlight_wasm_runtime && cargo hyperlight clippy --profile={{ if target == "debug" {"dev"} else { target } }} --all-targets --all-features -- -D warnings
     cd src/hyperlight_wasm_macro && cargo clippy --profile={{ if target == "debug" {"dev"} else { target } }} --all-targets --all-features -- -D warnings
 
@@ -94,18 +110,20 @@ test target=default-target features="":
     cargo test {{ if features =="" {''} else if features=="no-default-features" {"--no-default-features" } else {"--no-default-features -F " + features } }}  --profile={{ if target == "debug" {"dev"} else { target } }}
     cargo test test_metrics {{ if features =="" {''} else if features=="no-default-features" {"--no-default-features" } else {"--no-default-features -F " + features } }}  --profile={{ if target == "debug" {"dev"} else { target } }} -- --ignored 
 
-examples-ci target=default-target features="": (build-rust-wasm-examples target)
+examples-modules target=default-target features="": (build-rust-wasm-examples target)
     cargo run {{ if features =="" {''} else {"--no-default-features -F " + features } }} --profile={{ if target == "debug" {"dev"} else { target } }} --example helloworld
     cargo run {{ if features =="" {''} else {"--no-default-features -F " + features } }} --profile={{ if target == "debug" {"dev"} else { target } }} --example hostfuncs
     cargo run {{ if features =="" {''} else {"--no-default-features -F " + features } }} --profile={{ if target == "debug" {"dev"} else { target } }} --example rust_wasm_examples
     cargo run {{ if features =="" {''} else {"--no-default-features -F " + features } }} --profile={{ if target == "debug" {"dev"} else { target } }} --example interruption
     cargo run {{ if features =="" {''} else {"--no-default-features -F function_call_metrics," + features } }} --profile={{ if target == "debug" {"dev"} else { target } }} --example metrics
     cargo run {{ if features =="" {"--no-default-features --features kvm,mshv3"} else {"--no-default-features -F function_call_metrics," + features } }} --profile={{ if target == "debug" {"dev"} else { target } }} --example metrics
-    just examples-pulley {{ target }} {{ features }}
+
+examples-ci target=default-target features="": (examples-modules target features) (examples-components target features) (examples-pulley target features)
 
 examples-components target=default-target features="": (build-rust-component-examples target) 
     {{ wit-world }} cargo run {{ if features =="" {''} else {"--no-default-features -F kvm -F " + features } }} --profile={{ if target == "debug" {"dev"} else { target } }} --example component_example
     {{ wit-world-c }} cargo run {{ if features =="" {''} else {"--no-default-features -F kvm -F " + features } }} --profile={{ if target == "debug" {"dev"} else { target } }} --example c-component
+    {{ wit-world }} {{ wit-world-name-greeter }} cargo run {{ if features =="" {''} else {"--no-default-features -F kvm -F " + features } }} --profile={{ if target == "debug" {"dev"} else { target } }} --example component_greeter_example
 
 # Test a component and a module compiled with pulley
 examples-pulley target=default-target features="": (build-pulley-rust-component-examples target) (build-pulley-rust-wasm-examples target)

README.md

@@ -98,6 +98,32 @@ generate bindings from the same component type in the host.  For a
 complete (albeit small) example of this, see [this
 example](https://aka.ms/hyperlight-wasm-sockets-sample).
 
+### Selecting a specific world
+
+If your WIT file contains multiple worlds, you can select which world
+to use by setting the `WIT_WORLD_NAME` environment variable to the name
+of the desired world. If not set, the last world in the file will be used.
+
+For example, given a WIT file with multiple worlds:
+
+```wit
+package example:worlds;
+
+world http-world {
+    export http-interface;
+}
+
+world queue-world {
+    export queue-interface;
+}
+```
+
+To generate bindings for `http-world` instead of the default `queue-world`:
+
+```
+WIT_WORLD=/path/to/output.wasm WIT_WORLD_NAME=http-world cargo build -p hyperlight-wasm
+```
+
 ### Debugging the macro
 
 You can get more detailed error messages by expanding the Macro locally:

src/hyperlight_wasm/Cargo.toml

@@ -51,6 +51,11 @@ name = "interruption"
 path = "examples/interruption/main.rs"
 test = true
 
+[[example]]
+name = "component_greeter_example"
+path = "examples/component_greeter_example/main.rs"
+test = true
+
 [dependencies]
 hyperlight-host.workspace = true
 hyperlight-common.workspace = true

src/hyperlight_wasm/benches/benchmarks_components.rs

@@ -8,7 +8,7 @@ use crate::bindings::example::runcomponent::Guest;
 extern crate alloc;
 mod bindings {
     hyperlight_component_macro::host_bindgen!(
-        "../../src/wasmsamples/components/runcomponent-world.wasm"
+        "../../src/tests/c_guests/wasmsamples/components/runcomponent-world.wasm"
     );
 }