feat: add world selection for multi-world WIT files

Support WIT_WORLD_NAME env var in hyperlight-wasm-macro to select a specific world from WIT files containing multiple worlds.

Signed-off-by: James Sturtevant <jsturtevant@gmail.com>

Author: jsturtevant

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

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/build.rs

@@ -126,6 +126,7 @@ fn build_wasm_runtime() -> PathBuf {
 
     println!("cargo::rerun-if-changed={}", runtime_dir.display());
     println!("cargo::rerun-if-env-changed=WIT_WORLD");
+    println!("cargo::rerun-if-env-changed=WIT_WORLD_NAME");
     // the PROFILE env var unfortunately only gives us 1 bit of "dev or release"
     let cargo_profile = if profile == "debug" { "dev" } else { "release" };
 

src/hyperlight_wasm_macro/src/lib.rs

@@ -26,10 +26,15 @@ mod wasmguest;
 /// into wasmtime) and registers wasmtime host functions with the
 /// wasmtime linker for component imports (which are implemented by
 /// calling to the Hyperlight host).
+///
+/// If the WIT file contains multiple worlds, set the `WIT_WORLD_NAME`
+/// environment variable to select a specific world by name. If not set,
+/// the last world in the file will be used.
 #[proc_macro]
 pub fn wasm_guest_bindgen(_: proc_macro::TokenStream) -> proc_macro::TokenStream {
     let path = std::env::var_os("WIT_WORLD").unwrap();
-    util::read_wit_type_from_file(path, None, |kebab_name, ct| {
+    let world_name = std::env::var("WIT_WORLD_NAME").ok();
+    util::read_wit_type_from_file(path, world_name, |kebab_name, ct| {
         let decls = emit::run_state(true, true, |s| {
             // Emit type/trait definitions for all instances in the world
             rtypes::emit_toplevel(s, &kebab_name, ct);

src/hyperlight_wasm_runtime/build.rs

@@ -65,6 +65,7 @@ fn main() {
     cfg.compile("wasmtime-hyperlight-platform");
 
     println!("cargo::rerun-if-env-changed=WIT_WORLD");
+    println!("cargo::rerun-if-env-changed=WIT_WORLD_NAME");
     println!("cargo::rustc-check-cfg=cfg(component)");
     if env::var_os("WIT_WORLD").is_some() {
         println!("cargo::rustc-cfg=component");