Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .github/workflows/dep_build_wasm_examples.yml
Original file line number Diff line number Diff line change
Expand Up @@ -54,6 +54,7 @@ jobs:
build/*/pulley/*.aot
src/tests/rust_guests/component_sample/wit/component-world.wasm
src/tests/c_guests/wasmsamples/components/runcomponent-world.wasm
src/tests/rust_guests/component_sample/target/wasm32-unknown-unknown/*/component_sample.wasm
key: wasm-modules-${{ matrix.arch.name }}-${{ matrix.wasmtime_version.name }}-${{ hashFiles('src/tests/**', 'src/hyperlight_wasm_aot/**', 'Cargo.lock', '.cargo/config.toml', 'rust-toolchain.toml', 'Justfile', 'c.just', '.github/workflows/dep_build_wasm_examples.yml') }}
- name: Remove default clang
if: steps.modules-cache.outputs.cache-hit != 'true'
Expand Down Expand Up @@ -106,6 +107,7 @@ jobs:
build/*/pulley/*.aot
src/tests/rust_guests/component_sample/wit/component-world.wasm
src/tests/c_guests/wasmsamples/components/runcomponent-world.wasm
src/tests/rust_guests/component_sample/target/wasm32-unknown-unknown/*/component_sample.wasm
key: ${{ steps.modules-cache.outputs.cache-primary-key }}
# Build jobs compile examples against the WIT worlds, so they ship with the modules.
- name: Upload Wasm Modules (wasmtime ${{ matrix.wasmtime_version.name }})
Expand All @@ -118,3 +120,4 @@ jobs:
build/*/pulley/*.aot
src/tests/rust_guests/component_sample/wit/component-world.wasm
src/tests/c_guests/wasmsamples/components/runcomponent-world.wasm
src/tests/rust_guests/component_sample/target/wasm32-unknown-unknown/*/component_sample.wasm
2 changes: 0 additions & 2 deletions .github/workflows/dep_rust.yml
Original file line number Diff line number Diff line change
Expand Up @@ -170,8 +170,6 @@ jobs:
run: just test ${{ matrix.config }} ${{ env.FEATURES }}
working-directory: ./src/hyperlight_wasm

# Runs before Test Examples, which replaces the native components in
# build/<profile> with Pulley ones.
- name: Set up .NET
uses: actions/setup-dotnet@0f4a354dd5547a28c70b7853dbd95d5b67886e73 # v6.1.0
with:
Expand Down
2 changes: 2 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
* Experimental: add the `experimental_runtime_file` feature, with `SandboxBuilder::with_runtime_file` to load the guest runtime from a file.
* Experimental: add the `hyperlight-wasm-capi` crate, a C API that calls component functions with arguments and results in Hyperlight's component wire format. It is not published.
* Experimental: add the `Hyperlight.Wasm` and `Hyperlight.Wasm.Build` .NET packages, which run components from .NET with typed C# bindings generated from WIT at build time. See `dotnet/README.md`. They are not published.
* Experimental: add `hyperlight-wasm-aot experimental-build-runtime`, which builds a guest runtime for a WIT world. `Hyperlight.Wasm.Build` runs it for `HyperlightWit` items with `Runtime` set, and precompiles `HyperlightComponent` items. `HyperlightWasmtimeVersion` selects the Wasmtime version for both.
* Accept a `.wit` file or a directory of `.wit` files in `WIT_WORLD` when building the guest runtime. `host_bindgen!()` without arguments still needs a wasm-encoded package.

### Changed

Expand Down
19 changes: 16 additions & 3 deletions Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

18 changes: 11 additions & 7 deletions Justfile
Original file line number Diff line number Diff line change
Expand Up @@ -152,8 +152,8 @@ examples-ci target=default-target features="": (examples-modules target features
# Runs the examples-ci examples on the modules build-ci-examples builds.
examples-ci-prebuilt target=default-target features="": (run-examples-modules target features) (run-examples-components target features) (use-pulley-examples target) (run-examples-pulley target features)

# Builds every module the CI build jobs load, for the given profiles. C modules build
# in release only. Pulley builds go to build/<profile>/pulley.
# Builds every module the CI build jobs load for the given profiles. C modules build in release
# only. Pulley builds go to build/<profile>/pulley.
build-ci-examples features="" profiles="debug release": (build-wasm-examples "release" features)
#!/usr/bin/env bash
set -euo pipefail
Expand Down Expand Up @@ -183,16 +183,20 @@ run-examples-components target=default-target features="":
{{ 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
{{ wit-world }} cargo test -p hyperlight-wasm-capi {{ if features =="" {''} else {"--no-default-features -F kvm -F " + features } }} --profile={{ if target == "debug" {"dev"} else { target } }} -- --include-ignored

# Builds the native libraries and a guest runtime for the component_sample example world, for the .NET tests
dotnet-test-assets target=default-target features="": ensure-cargo-hyperlight
# Builds the native libraries for the .NET tests
dotnet-test-assets target=default-target features="":
cargo build -p hyperlight-wasm-capi -p hyperlight-wasm-csharp-bindgen {{ if features =="" {''} else {"--no-default-features -F kvm -F " + features } }} --profile={{ if target == "debug" {"dev"} else { target } }}
{{ wit-world }} cargo hyperlight build {{ if features =~ "wasmtime_latest" {"--no-default-features -F wasmtime_latest"} else {""} }} --profile={{ if target == "debug" {"dev"} else { target } }} --manifest-path src/hyperlight_wasm_runtime/Cargo.toml --target-dir target/component-sample-runtime --locked

# Runs the .NET tests. Needs the .NET 10 SDK or later.
dotnet-test target=default-target features="": (build-rust-component-examples target features) (dotnet-test-prebuilt target features)

# Runs the .NET tests on the component_sample component that build-ci-examples builds.
dotnet-test-prebuilt target=default-target features="": (dotnet-test-assets target features) (dotnet-run-tests target)
# Runs the .NET tests on the component_sample component that build-ci-examples builds. The test
# build creates the runtime and compiles the component with hyperlight-wasm-aot. Release runs
# build the runtime in the hyperlight-wasm build script's directory to reuse its Wasmtime
# build. Debug runs use the default directory under obj.
dotnet-test-prebuilt target=default-target features="": (dotnet-test-assets target features)
cargo build -p hyperlight-wasm-aot
just dotnet-run-tests {{ target }} -p:HyperlightWasmAot={{ justfile_directory() }}/target/debug/hyperlight-wasm-aot{{ if os() == "windows" {".exe"} else {""} }} {{ if target == "debug" {""} else {"-p:HyperlightRuntimeTargetDirectory=" + justfile_directory() + "/target/hyperlight-wasm-runtime/"} }} {{ if features =~ "wasmtime_latest" {"-p:HyperlightWasmtimeVersion=latest"} else {""} }}

dotnet-tests := "dotnet/tests/Hyperlight.Wasm.Tests"

Expand Down
4 changes: 3 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -95,7 +95,9 @@ a binary encoding of a component type (e.g. the result of running
`wasm-tools component wit -w -o /path/to/output.wasm
/path/to/input.wit`), which will ensure that the resultant library
includes a guest binary that is specialised to load components with
that type. Then, use `hyperlight_component_macro::host_bindgen!()` to
that type. The guest binary also accepts a `.wit` file or a directory of
`.wit` files, but `host_bindgen!()` without arguments needs the binary
encoding. Then, use `hyperlight_component_macro::host_bindgen!()` to
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).
Expand Down
4 changes: 4 additions & 0 deletions RustDev.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,10 @@ wasm-tools component wit -w -o world.wasm world.wit
export WIT_WORLD=$(readlink -f world.wasm)
```

The guest binary also accepts a `.wit` file or a directory of `.wit`
files in `WIT_WORLD`. `host_bindgen!()` without arguments reads
`WIT_WORLD` too and needs the binary encoding.

## `ProtoWasmSandbox` vs `WasmSandbox` vs `LoadedWasmSandbox`

The three primary APIs with which you'll be interacting are [`ProtoWasmSandbox`](./src/hyperlight_wasm/src/sandbox/proto_wasm_sandbox.rs), [`WasmSandbox`](./src/hyperlight_wasm/src/sandbox/wasm_sandbox.rs) and [`LoadedWasmSandbox`](./src/hyperlight_wasm/src/sandbox/loaded_wasm_sandbox.rs). These are three different Rust `struct`s that provide a type-safe way to ensure the current state of the system.
Expand Down
30 changes: 22 additions & 8 deletions dotnet/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@
Run WebAssembly components in Hyperlight micro VMs from .NET, with typed bindings generated from WIT.

* `Hyperlight.Wasm` is the runtime library. It wraps the native `hyperlight-wasm-capi` library.
* `Hyperlight.Wasm.Build` generates C# from WIT at build time. It needs no Rust toolchain. Visual Studio builds need Visual Studio 2026 or later.
* `Hyperlight.Wasm.Build` generates C# from WIT at build time, which needs no Rust toolchain. It can also build the guest runtime and components. Visual Studio builds need Visual Studio 2026 or later.

Both target .NET 10 or later. The packages hold native libraries for the runtime identifier they were packed on.

Expand Down Expand Up @@ -42,15 +42,29 @@ uint sum = component.Adder.Add(1, 2);

## Guest runtime and components

A component needs a guest runtime built for its WIT world, because the runtime's guest bindings are generated when it is compiled. Building a runtime needs Rust and a hyperlight-wasm checkout of the same version as the packages:
A component needs a guest runtime built for its WIT world, because the runtime's guest bindings are generated when it is compiled. Components must be precompiled. The runtime, the precompiled component and the packages must come from the same hyperlight-wasm version.

Both steps use `hyperlight-wasm-aot`, which needs rustup and clang. Its runtime build is experimental, and uses Rust 1.94.1 unless `RUSTUP_TOOLCHAIN` is set. Install the packages' version without the `-preview` suffix:

```sh
wasm-tools component wit example.wit -w -o example-world.wasm
WIT_WORLD=example-world.wasm cargo hyperlight build --release \
--manifest-path src/hyperlight_wasm_runtime/Cargo.toml --target-dir target/example-runtime
cargo install --locked hyperlight-wasm-aot --version <version>
```

Precompile the component with `hyperlight-wasm-aot compile --component`. The runtime, the AOT tool and the packages must come from the same hyperlight-wasm version.
### Building them with the project

Set `Runtime` on a `HyperlightWit` item and list components as `HyperlightComponent` items. The build then creates the runtime and `<name>.aot` in the output directory. The first runtime build takes several minutes. `HyperlightWasmAot` sets the tool's path, and `HyperlightWasmtimeVersion` selects `lts`, the default, or `latest`.

```xml
<HyperlightWit Include="wit/example.wit" World="example" Runtime="example-runtime" />
<HyperlightComponent Include="example.wasm" />
```

### Building them by hand

```sh
hyperlight-wasm-aot experimental-build-runtime example.wit example-runtime --world example
hyperlight-wasm-aot compile --component example.wasm example.aot
```

## Sandboxes

Expand Down Expand Up @@ -78,8 +92,8 @@ Hyperlight runs a helper process, `hyperlight_surrogate_<hash>.exe`, for each sa
## Development

```sh
just dotnet-test # builds the native libraries, a test runtime and component, then runs the tests
just dotnet-pack # packs both packages into dotnet/artifacts
just dotnet-test # builds the native libraries and test component, then runs the tests
just dotnet-pack # packs both packages into dotnet/artifacts
```

`HyperlightNativeDir` overrides where the projects find the native libraries.
Original file line number Diff line number Diff line change
Expand Up @@ -3,15 +3,22 @@
<!--
List WIT inputs as HyperlightWit items:

<HyperlightWit Include="wit/policy.wit" World="policy" Namespace="MyApp.Policy" />
<HyperlightWit Include="wit/policy.wit" World="policy" Namespace="MyApp.Policy" Runtime="policy-runtime" />

World selects a world when the package has several. Namespace defaults to
the project's root namespace.
the project's root namespace. Runtime names a guest runtime for the world
that the build creates in the output directory with hyperlight-wasm-aot.

List components to precompile into <name>.aot in the output directory as
HyperlightComponent items:

<HyperlightComponent Include="policy.wasm" />
-->
<ItemDefinitionGroup>
<HyperlightWit>
<World></World>
<Namespace></Namespace>
<Runtime></Runtime>
</HyperlightWit>
</ItemDefinitionGroup>

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -34,4 +34,70 @@
</ItemGroup>
</Target>

<!-- Visual Studio skips MSBuild when no known input changed. -->
<ItemGroup>
<UpToDateCheckInput Include="@(HyperlightWit);@(HyperlightComponent)" />
</ItemGroup>

<PropertyGroup>
<HyperlightWasmAot Condition="'$(HyperlightWasmAot)' == ''">hyperlight-wasm-aot</HyperlightWasmAot>
<HyperlightRuntimeTargetDirectory Condition="'$(HyperlightRuntimeTargetDirectory)' == ''">$(BaseIntermediateOutputPath)hyperlight-wasm-runtime/</HyperlightRuntimeTargetDirectory>
<HyperlightWasmtimeVersion Condition="'$(HyperlightWasmtimeVersion)' == ''">lts</HyperlightWasmtimeVersion>
</PropertyGroup>

<!-- Cargo skips the build when nothing changed. Design-time builds skip it because it takes minutes. -->
<Target Name="BuildHyperlightRuntimes" Condition="'$(DesignTimeBuild)' != 'true'">
<ItemGroup>
<_HyperlightRuntime Include="@(HyperlightWit)" Condition="'%(HyperlightWit.Runtime)' != ''">
<!-- A trailing backslash before a closing quote escapes the quote on Windows. -->
<WitPath>$([System.String]::Copy('%(FullPath)').TrimEnd('\/'))</WitPath>
<WorldArgument Condition="'%(HyperlightWit.World)' != ''">--world &quot;%(HyperlightWit.World)&quot;</WorldArgument>
</_HyperlightRuntime>
</ItemGroup>
<Error Condition="'@(_HyperlightRuntime->'%(Runtime)'->Distinct()->Count())' != '@(_HyperlightRuntime->Count())'"
Text="HyperlightWit items must have distinct Runtime names." />
<Exec Condition="'@(_HyperlightRuntime)' != ''"
Command="&quot;$(HyperlightWasmAot)&quot; experimental-build-runtime &quot;%(_HyperlightRuntime.WitPath)&quot; &quot;$(IntermediateOutputPath)HyperlightRuntimes/%(_HyperlightRuntime.Runtime)&quot; %(_HyperlightRuntime.WorldArgument) --wasmtime-version $(HyperlightWasmtimeVersion) --target-dir &quot;$(HyperlightRuntimeTargetDirectory.TrimEnd('\/'))&quot;" />
</Target>

<!-- Records the package, AOT tool, Wasmtime version and component paths, so components recompile when any changes. -->
<Target Name="StampHyperlightWasmAot" Condition="'@(HyperlightComponent)' != '' and '$(DesignTimeBuild)' != 'true'">
<Error Condition="'@(HyperlightComponent->'%(Filename)'->Distinct()->Count())' != '@(HyperlightComponent->Count())'"
Text="HyperlightComponent items must have distinct file names, because each compiles to its name with .aot." />
<Exec Command="&quot;$(HyperlightWasmAot)&quot; --version" ConsoleToMSBuild="true" StandardOutputImportance="low">
<Output TaskParameter="ConsoleOutput" PropertyName="_HyperlightWasmAotVersion" />
</Exec>
<PropertyGroup>
<_HyperlightWasmAotTime Condition="Exists('$(HyperlightWasmAot)')">$([System.IO.File]::GetLastWriteTime('$(HyperlightWasmAot)').Ticks)</_HyperlightWasmAotTime>
</PropertyGroup>
<MakeDir Directories="$(IntermediateOutputPath)HyperlightComponents" />
<WriteLinesToFile File="$(IntermediateOutputPath)HyperlightComponents/aot.stamp"
Lines="$(MSBuildThisFileFullPath);$(_HyperlightWasmAotVersion);$(_HyperlightWasmAotTime);$(HyperlightWasmtimeVersion);@(HyperlightComponent->'%(FullPath)')"
Overwrite="true"
WriteOnlyWhenDifferent="true" />
</Target>

<Target Name="CompileHyperlightComponents"
Condition="'$(DesignTimeBuild)' != 'true'"
DependsOnTargets="StampHyperlightWasmAot"
Inputs="@(HyperlightComponent);$(IntermediateOutputPath)HyperlightComponents/aot.stamp"
Outputs="@(HyperlightComponent->'$(IntermediateOutputPath)HyperlightComponents/%(Filename).aot')">
<Exec Command="&quot;$(HyperlightWasmAot)&quot; compile --component --wasmtime-version $(HyperlightWasmtimeVersion) &quot;%(HyperlightComponent.FullPath)&quot; &quot;$(IntermediateOutputPath)HyperlightComponents/%(HyperlightComponent.Filename).aot&quot;" />
</Target>

<Target Name="CopyHyperlightArtifacts"
BeforeTargets="AssignTargetPaths"
DependsOnTargets="BuildHyperlightRuntimes;CompileHyperlightComponents">
<ItemGroup>
<None Include="@(HyperlightWit->'$(IntermediateOutputPath)HyperlightRuntimes/%(Runtime)')"
Condition="'%(HyperlightWit.Runtime)' != ''"
Link="%(HyperlightWit.Runtime)"
CopyToOutputDirectory="PreserveNewest" />
<None Include="@(HyperlightComponent->'$(IntermediateOutputPath)HyperlightComponents/%(Filename).aot')"
Link="%(HyperlightComponent.Filename).aot"
CopyToOutputDirectory="PreserveNewest" />
<FileWrites Include="$(IntermediateOutputPath)HyperlightRuntimes/**;$(IntermediateOutputPath)HyperlightComponents/**" />
</ItemGroup>
</Target>

</Project>
4 changes: 2 additions & 2 deletions dotnet/tests/Hyperlight.Wasm.Tests/ComponentTests.cs
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ namespace Hyperlight.Wasm.Tests;

public sealed class ComponentTests
{
private static readonly string Assets = Path.Combine(AppContext.BaseDirectory, "assets");
private static readonly string Assets = AppContext.BaseDirectory;
private static readonly string Runtime = Path.Combine(Assets, "component-sample-runtime");
private static readonly string Component = Path.Combine(Assets, "component_sample.aot");

Expand Down Expand Up @@ -334,7 +334,7 @@ public sealed class SignalTests
[Fact]
public async Task GcSuspendsSpinningThreadAfterSandboxLoads()
{
var assets = Path.Combine(AppContext.BaseDirectory, "assets");
var assets = AppContext.BaseDirectory;
using var sandbox = new WasmSandbox(
Path.Combine(assets, "component-sample-runtime"),
new SandboxOptions { ScratchSize = 100 << 20 });
Expand Down
Loading
Loading