Skip to content
Open
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
8 changes: 7 additions & 1 deletion .github/workflows/dep_build_wasm_examples.yml
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,9 @@ jobs:
build/*/pulley/*.aot
src/tests/rust_guests/component_sample/wit/component-world.wasm
src/tests/c_guests/wasmsamples/components/runcomponent-world.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') }}
build/*/component-sample-runtime
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/**', 'src/hyperlight_wasm_runtime/**', 'src/hyperlight_wasm_macro/**', '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'
run: sudo rm /usr/bin/clang
Expand Down Expand Up @@ -106,6 +108,8 @@ jobs:
build/*/pulley/*.aot
src/tests/rust_guests/component_sample/wit/component-world.wasm
src/tests/c_guests/wasmsamples/components/runcomponent-world.wasm
build/*/component-sample-runtime
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 +122,5 @@ jobs:
build/*/pulley/*.aot
src/tests/rust_guests/component_sample/wit/component-world.wasm
src/tests/c_guests/wasmsamples/components/runcomponent-world.wasm
build/*/component-sample-runtime
src/tests/rust_guests/component_sample/target/wasm32-unknown-unknown/*/component_sample.wasm
4 changes: 3 additions & 1 deletion .github/workflows/dep_rust.yml
Original file line number Diff line number Diff line change
Expand Up @@ -177,8 +177,10 @@ jobs:
with:
dotnet-version: 8.0.x

# One leg builds the runtime and component through Hyperlight.Wasm.Build.
# The others use the prebuilt ones.
- name: Test .NET packages
run: just dotnet-test-prebuilt ${{ matrix.config }} ${{ env.FEATURES }}
run: just ${{ matrix.hypervisor == 'kvm' && matrix.cpu == 'amd' && matrix.config == 'debug' && 'dotnet-test-build' || 'dotnet-test-prebuilt' }} ${{ matrix.config }} ${{ env.FEATURES }}

- name: Install github-cli (Windows)
if: runner.os == 'Windows'
Expand Down
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ 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.

### Changed

Expand Down
3 changes: 3 additions & 0 deletions Cargo.lock

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

24 changes: 17 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, and the .NET tests' guest runtime, 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 All @@ -168,6 +168,7 @@ build-ci-examples features="" profiles="debug release": (build-wasm-examples "re
mv build/$target/rust_wasm_samples.aot build/$target/component_sample.aot build/$target/pulley/
just build-rust-wasm-examples $target {{ features }}
just build-rust-component-examples $target {{ features }}
just build-component-sample-runtime $target {{ features }}
done

[private]
Expand All @@ -183,17 +184,26 @@ 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

# Builds a guest runtime for the component_sample example world into build/<target>/component-sample-runtime
build-component-sample-runtime target=default-target features="":
cargo run -p hyperlight-wasm-aot -- experimental-build-runtime src/tests/rust_guests/component_sample/wit/example.wit build/{{ target }}/component-sample-runtime --world example --target-dir target/component-sample-runtime {{ if target == "debug" {"--debug"} else {""} }} {{ if features =~ "wasmtime_latest" {"--wasmtime-version latest"} else {""} }}

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

# Runs the .NET tests on the component_sample component that build-ci-examples builds.
# Runs the .NET tests on the component and runtime 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 with the build creating the runtime and component through hyperlight-wasm-aot.
# Needs the component_sample component that build-rust-component-examples builds.
dotnet-test-build 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 {""} }}

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

# A hung test fails after 5 minutes and is named in the output.
Expand Down
31 changes: 23 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 8 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.

```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,9 @@ 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, a test runtime and component, then runs the tests
just dotnet-test-build # runs the tests with the build creating the runtime and component
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,62 @@
</ItemGroup>
</Target>

<PropertyGroup>
<HyperlightWasmAot Condition="'$(HyperlightWasmAot)' == ''">hyperlight-wasm-aot</HyperlightWasmAot>
<HyperlightRuntimeTargetDirectory Condition="'$(HyperlightRuntimeTargetDirectory)' == ''">$(BaseIntermediateOutputPath)hyperlight-wasm-runtime/</HyperlightRuntimeTargetDirectory>
</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)' != ''">
<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.FullPath)&quot; &quot;$(IntermediateOutputPath)HyperlightRuntimes/%(_HyperlightRuntime.Runtime)&quot; %(_HyperlightRuntime.WorldArgument) --target-dir &quot;$(HyperlightRuntimeTargetDirectory)&quot;" />
</Target>

<!-- Records the package and AOT tool, so components recompile when either 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)"
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 &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
23 changes: 14 additions & 9 deletions dotnet/tests/Hyperlight.Wasm.Tests/Hyperlight.Wasm.Tests.csproj
Original file line number Diff line number Diff line change
Expand Up @@ -27,18 +27,23 @@
<ProjectReference Include="../../src/Hyperlight.Wasm.Build/Hyperlight.Wasm.Build.csproj" ReferenceOutputAssembly="false" />
</ItemGroup>

<!-- Item conditions see the default HyperlightWasmAot from the targets, so capture whether it was passed. -->
<PropertyGroup Condition="'$(HyperlightWasmAot)' != ''">
<_BuildSampleAssets>true</_BuildSampleAssets>
<_SampleRuntime>component-sample-runtime</_SampleRuntime>
</PropertyGroup>
<ItemGroup>
<HyperlightWit Include="$(RepoRoot)src/tests/rust_guests/component_sample/wit/example.wit" World="example" Namespace="Hyperlight.Wasm.Tests.Sample" />
<HyperlightWit Include="$(RepoRoot)src/tests/rust_guests/component_sample/wit/example.wit" World="example" Namespace="Hyperlight.Wasm.Tests.Sample" Runtime="$(_SampleRuntime)" />
</ItemGroup>

<!-- Built by `just dotnet-test-assets`. -->
<PropertyGroup>
<HyperlightGuestArch Condition="'$([System.Runtime.InteropServices.RuntimeInformation]::OSArchitecture)' == 'Arm64'">aarch64</HyperlightGuestArch>
<HyperlightGuestArch Condition="'$(HyperlightGuestArch)' == ''">x86_64</HyperlightGuestArch>
</PropertyGroup>
<ItemGroup>
<None Include="$(RepoRoot)build/$(HyperlightCargoProfile)/component_sample.aot" Link="assets/component_sample.aot" CopyToOutputDirectory="PreserveNewest" />
<None Include="$(RepoRoot)target/component-sample-runtime/$(HyperlightGuestArch)-hyperlight-none/$(HyperlightCargoProfile)/hyperlight-wasm-runtime" Link="assets/component-sample-runtime" CopyToOutputDirectory="PreserveNewest" />
<!-- With HyperlightWasmAot set, as `just dotnet-test-build` does, the build creates the runtime and the
component. Otherwise `just build-rust-component-examples` and `just build-component-sample-runtime` do. -->
<ItemGroup Condition="'$(_BuildSampleAssets)' == 'true'">
<HyperlightComponent Include="$(RepoRoot)src/tests/rust_guests/component_sample/target/wasm32-unknown-unknown/$(HyperlightCargoProfile)/component_sample.wasm" />
</ItemGroup>
<ItemGroup Condition="'$(_BuildSampleAssets)' != 'true'">
<None Include="$(RepoRoot)build/$(HyperlightCargoProfile)/component_sample.aot" Link="component_sample.aot" CopyToOutputDirectory="PreserveNewest" />
<None Include="$(RepoRoot)build/$(HyperlightCargoProfile)/component-sample-runtime" Link="component-sample-runtime" CopyToOutputDirectory="PreserveNewest" />
</ItemGroup>

<Import Project="../../src/Hyperlight.Wasm.Build/build/Hyperlight.Wasm.Build.targets" />
Expand Down
Loading
Loading