Skip to content

Add experimental-build-runtime to hyperlight-wasm-aot - #574

Open
ludfjig wants to merge 1 commit into
mainfrom
experimental-build-runtime
Open

ludfjig wants to merge 1 commit into
mainfrom
experimental-build-runtime

Conversation

@ludfjig

@ludfjig ludfjig commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Using the C API or .NET packages needs a guest runtime built for the component's WIT world. That takes a hyperlight-wasm checkout, cargo-hyperlight and wasm-tools.

This adds hyperlight-wasm-aot experimental-build-runtime <wit> <output>. Installed from crates.io, the tool carries the runtime source and builds it with the cargo-hyperlight library, so users need only rustup and clang. The guest macro accepts a .wit file or directory in WIT_WORLD.

Hyperlight.Wasm.Build can run it during the build. With Runtime set on a HyperlightWit item, dotnet build creates the runtime, and HyperlightComponent items are precompiled to .aot. Both go in the output directory. This is opt-in because it needs Rust.

CI builds the .NET tests' runtime with the subcommand and ships it with the example modules, so the .NET tests run it. One test leg builds the runtime and component through Hyperlight.Wasm.Build instead. CI covers the checkout path. The installed path was verified manually.

Based on #564.

@ludfjig ludfjig added the kind/enhancement New feature or request label Nov 13, 2026
@ludfjig
ludfjig added this pull request to stack #576 November 13, 2026 00:42
@ludfjig
ludfjig force-pushed the experimental-build-runtime branch from 71e1b5a to 32aefd7 Compare November 13, 2026 00:55
@ludfjig
ludfjig force-pushed the experimental-build-runtime branch 2 times, most recently from efedd2e to 6d5e1ba Compare November 16, 2026 18:46
@ludfjig
ludfjig force-pushed the experimental-build-runtime branch 2 times, most recently from 5b62b8a to 4318aab Compare November 17, 2026 18:45
@ludfjig
ludfjig force-pushed the experimental-build-runtime branch from 4318aab to 00ead69 Compare November 17, 2026 19:33
@ludfjig
ludfjig force-pushed the experimental-build-runtime branch 2 times, most recently from 0aca748 to 1638a53 Compare November 17, 2026 21:39
@ludfjig
ludfjig force-pushed the experimental-build-runtime branch from 1638a53 to 21672fa Compare November 17, 2026 22:16
@ludfjig
ludfjig force-pushed the experimental-build-runtime branch from 21672fa to fadfe44 Compare November 18, 2026 21:45
}
cmd.status()?;

let built = target_dir

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Is it possible that there could be concurrent builds with different outputs? if so is it possible that this copy picks up the build output from the concurrent build (i.e. the second build finishes before this one starts copying)

cargo_metadata = "0.23"
cargo-util-schemas = "=0.14.1"
object = { version = "0.39.1", default-features = false, features = ["read_core", "elf"] }
cargo-hyperlight = "0.1.14"

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

think there is a later version

Base automatically changed from hyperlight-0.18-capi to main November 18, 2026 22:39
ludfjig added a commit that referenced this pull request Nov 18, 2026
.NET and other non-Rust hosts can't use hyperlight-wasm, because its
host API is Rust only.

This adds an experimental C API and .NET packages on top of it:

* `hyperlight-wasm-capi` is a C API for running components. Callers
register host functions, load a component and call its functions. They
can also snapshot, restore and interrupt a sandbox.
* The C API works with any component, because it never decodes values.
Callers pass each argument as a byte buffer in Hyperlight's component
wire format and get the result back the same way. Generated bindings,
such as the .NET ones, do the encoding.
* `Hyperlight.Wasm` wraps the C API. `Hyperlight.Wasm.Build` generates
typed C# bindings from WIT at build time. Its MSBuild task loads
`hyperlight-wasm-csharp-bindgen`, a native library around Hyperlight's
`hyperlight-component-csharp`, so builds need no Rust.

A guest runtime is built for one WIT world and is embedded when a Rust
host builds. A non-Rust host has no Rust build to embed it in. So the C
API loads the runtime from a file, through
`SandboxBuilder::with_runtime_file` behind the
`experimental_runtime_file` feature. Here users build that runtime with
`cargo hyperlight`. #574 adds a tool and MSBuild support for it.

* The `hyperlight-wasm-runtime` guest binary has an ELF section,
`.note_hyperlight_wasm_runtime`, holding its crate version and a hash of
its WIT world. The hash covers the `WIT_WORLD` file or directory and
`WIT_WORLD_NAME`.
* `with_runtime_file` rejects a guest binary whose crate version differs
from the host's `hyperlight-wasm` crate version, because host and guest
must agree on the guest ABI. The `hyperlight-wasm` build checks its
embedded guest binary the same way.
* A snapshot records the world hash of its guest binary. A host built
with `WIT_WORLD` only loads snapshots with the same hash. A host built
without one, like the C API, loads snapshots of any world, because it
only uses guest binaries from files.
* `SandboxBuilder::with_interrupt_vcpu_sigrtmin_offset` changes the
interrupt signal, since .NET uses `SIGRTMIN`.

The C API and packages are versioned as experimental and not published
yet. `just dotnet-test` and `just examples-components` run their tests,
and CI runs both on every platform. On macOS the .NET tests run as a
signed executable, because the `dotnet` host lacks the hypervisor
entitlement.

---------

Signed-off-by: Ludvig Liljenberg <4257730+ludfjig@users.noreply.github.com>
Add an experimental hyperlight-wasm-aot subcommand that builds a guest
runtime for a WIT world. C API and .NET users can then build a runtime
without a hyperlight-wasm checkout and without cargo-hyperlight.
Installed from crates.io, the tool embeds the runtime source. In a
checkout it builds the workspace's runtime in place.

The guest macro accepts a .wit file or a directory of .wit files in
WIT_WORLD, so no wasm-tools step is needed.

Hyperlight.Wasm.Build runs the subcommand for HyperlightWit items with
Runtime set, and precompiles HyperlightComponent items, so dotnet build
creates both. This is opt-in, because it needs Rust.

CI builds the .NET tests' runtime with the subcommand in the examples
job, which already compiles hyperlight-wasm-aot, and ships it with the
modules. One test leg builds the runtime and component through
Hyperlight.Wasm.Build instead.

Signed-off-by: Ludvig Liljenberg <4257730+ludfjig@users.noreply.github.com>
@ludfjig
ludfjig force-pushed the experimental-build-runtime branch from fadfe44 to 69e647b Compare November 18, 2026 22:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

kind/enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants