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
159 changes: 158 additions & 1 deletion .github/workflows/CreateRelease.yml
Original file line number Diff line number Diff line change
Expand Up @@ -7,13 +7,101 @@ on:

permissions:
contents: write
id-token: write # Required for crates.io trusted publishing
id-token: write # Required for crates.io and NuGet trusted publishing

jobs:

benchmarks:
uses: ./.github/workflows/Benchmarks.yml

# Builds the native libraries of the experimental .NET packages.
dotnet-native:
timeout-minutes: 60
permissions:
contents: read
strategy:
matrix:
rid: [linux-x64, win-x64, osx-arm64]
runs-on: ${{ matrix.rid == 'win-x64' && fromJSON(format('["self-hosted", "Windows", "X64", "1ES.Pool=hld-win2025-amd", "JobId=dotnet-native-{0}-{1}-{2}"]', github.run_id, github.run_number, github.run_attempt)) || matrix.rid == 'osx-arm64' && 'macos-15' || 'ubuntu-24.04' }}
steps:
- uses: actions/checkout@v5
- name: Hyperlight setup
uses: hyperlight-dev/ci-setup-workflow@v2.3.1
with:
just-version: 1.59.0
# The runner image ships LLVM 18, the version the Linux setup installs.
- name: Use LLVM 18 (macOS)
if: runner.os == 'macOS'
run: echo /opt/homebrew/opt/llvm@18/bin >> "$GITHUB_PATH"
- name: Build native libraries
run: just dotnet-native
env:
# Links the C runtime into the DLLs, so they load without the Visual C++ Redistributable.
CARGO_TARGET_X86_64_PC_WINDOWS_MSVC_RUSTFLAGS: -Ctarget-feature=+crt-static
# pwsh steps on the self-hosted Windows runners can pass when a recipe fails.
shell: bash
- name: Upload native libraries
uses: actions/upload-artifact@v4
with:
name: dotnet-native-${{ matrix.rid }}
path: dotnet/native/
if-no-files-found: error

# Packs the experimental .NET packages with every native library.
dotnet-pack:
needs: [ dotnet-native ]
timeout-minutes: 15
permissions:
contents: read
runs-on: ubuntu-24.04
outputs:
version: ${{ steps.pack.outputs.version }}
steps:
- uses: actions/checkout@v5
- uses: extractions/setup-just@v3
with:
just-version: "1.59.0"
- uses: actions/setup-dotnet@0f4a354dd5547a28c70b7853dbd95d5b67886e73 # v6.1.0
with:
dotnet-version: 10.0.x
- name: Download native libraries
uses: actions/download-artifact@v5
with:
pattern: dotnet-native-*
merge-multiple: true
path: dotnet/native
- name: Pack
id: pack
# Release packages take hyperlight-wasm's version with the preview suffix.
# Other builds are development builds of the next minor release.
run: |
version=$(cargo metadata --no-deps --format-version 1 | jq -r '.packages[] | select(.name == "hyperlight-wasm") | .version')
if [[ "$GITHUB_REF" == refs/heads/release/* ]]; then
if [[ "$version" != "${GITHUB_REF#refs/heads/release/v}" ]]; then
echo "::error::hyperlight-wasm is version $version, but the branch is ${GITHUB_REF#refs/heads/}"
exit 1
fi
package_version=$version-preview
else
IFS=. read -r major minor _ <<< "$version"
package_version=$major.$((minor + 1)).0-dev.$GITHUB_RUN_NUMBER
fi
just dotnet-pack-prebuilt "$package_version"
echo "version=$package_version" >> "$GITHUB_OUTPUT"
env:
# Reading metadata needs no particular toolchain.
RUSTUP_TOOLCHAIN: stable
shell: bash
- name: Upload packages
uses: actions/upload-artifact@v4
with:
name: dotnet-packages
path: |
dotnet/artifacts/Hyperlight.Wasm.${{ steps.pack.outputs.version }}.nupkg
dotnet/artifacts/Hyperlight.Wasm.${{ steps.pack.outputs.version }}.snupkg
dotnet/artifacts/Hyperlight.Wasm.Build.${{ steps.pack.outputs.version }}.nupkg
if-no-files-found: error

publish:
# see https://github.com/orgs/community/discussions/26286#discussioncomment-3251208 for why we need to check the ref
if: ${{ contains(github.ref, 'refs/heads/release/') }} || ${{ github.ref=='refs/heads/main' }}
Expand Down Expand Up @@ -98,3 +186,72 @@ jobs:
env:
CARGO_REGISTRY_TOKEN: ${{ steps.crates-io-auth.outputs.token }}
shell: bash

# A separate job, so a .NET failure cannot block the crates.io release.
publish-dotnet:
if: github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/heads/release/')
needs: [ publish, dotnet-pack ]
timeout-minutes: 15
runs-on: ubuntu-24.04
env:
VERSION: ${{ needs.dotnet-pack.outputs.version }}
steps:
- name: Download .NET packages
uses: actions/download-artifact@v5
with:
name: dotnet-packages
path: dotnet-packages
- name: Set up .NET
if: startsWith(github.ref, 'refs/heads/release/')
uses: actions/setup-dotnet@0f4a354dd5547a28c70b7853dbd95d5b67886e73 # v6.1.0
with:
dotnet-version: 10.0.x
- name: Authenticate with NuGet
if: startsWith(github.ref, 'refs/heads/release/')
uses: NuGet/login@8d196754b4036150537f80ac539e15c2f1028841 # v1.2.0
id: nuget-login
with:
user: ${{ vars.NUGET_USER }}
# The symbol package is pushed on its own, so a retry pushes it even when its package exists.
- name: Publish to NuGet
if: startsWith(github.ref, 'refs/heads/release/')
run: |
push() {
dotnet nuget push "dotnet-packages/$1" --source https://api.nuget.org/v3/index.json --api-key "$NUGET_API_KEY" --skip-duplicate "${@:2}"
}
push "Hyperlight.Wasm.$VERSION.nupkg" --no-symbols
push "Hyperlight.Wasm.Build.$VERSION.nupkg" --no-symbols
push "Hyperlight.Wasm.$VERSION.snupkg"
env:
NUGET_API_KEY: ${{ steps.nuget-login.outputs.NUGET_API_KEY }}
shell: bash
- name: Attach packages to the release
Comment thread
ludfjig marked this conversation as resolved.
Resolved
run: |
files=(
"dotnet-packages/Hyperlight.Wasm.$VERSION.nupkg"
"dotnet-packages/Hyperlight.Wasm.$VERSION.snupkg"
"dotnet-packages/Hyperlight.Wasm.Build.$VERSION.nupkg"
)
if [[ "$GITHUB_REF" == refs/heads/release/* ]]; then
gh release upload "v${GITHUB_REF#refs/heads/release/v}" --repo "$GITHUB_REPOSITORY" --clobber "${files[@]}"
exit 0
fi
# Each run on main recreates dev-latest, so only the run for main's head attaches to it.
if [[ "$(gh api "repos/$GITHUB_REPOSITORY/commits/main" -q .sha)" != "$GITHUB_SHA" ]]; then
echo "::notice::main is past $GITHUB_SHA. The run for main's head publishes dev-latest."
exit 0
fi
gh release upload dev-latest --repo "$GITHUB_REPOSITORY" --clobber "${files[@]}"
# The AOT compiler builds runtimes from the source it was installed from, so the clone must stay.
printf '%s\n' \
"Development build of $GITHUB_SHA. Install the matching AOT compiler from a clone that you keep:" \
"" \
'```sh' \
"git clone https://github.com/$GITHUB_REPOSITORY hyperlight-wasm" \
"git -C hyperlight-wasm checkout $GITHUB_SHA" \
"cargo install --locked --path hyperlight-wasm/src/hyperlight_wasm_aot" \
'```' |
gh release edit dev-latest --repo "$GITHUB_REPOSITORY" --notes-file -
env:
GH_TOKEN: ${{ github.token }}
shell: bash
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -61,6 +61,7 @@ BenchmarkDotNet.Artifacts/
project.lock.json
project.fragment.lock.json
artifacts/
dotnet/native/

# Tye
.tye/
Expand Down
2 changes: 1 addition & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
* Add `SandboxBuilder::with_interrupt_vcpu_sigrtmin_offset` to change the signal that interrupts a guest on Linux.
* 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 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 published to NuGet as prereleases for linux-x64, win-x64 and osx-arm64.
* 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.

Expand Down
18 changes: 18 additions & 0 deletions Justfile
Original file line number Diff line number Diff line change
Expand Up @@ -222,6 +222,24 @@ dotnet-pack target="release":
dotnet pack dotnet/src/Hyperlight.Wasm -c {{ if target == "debug" {"Debug"} else {"Release"} }} -o dotnet/artifacts
dotnet pack dotnet/src/Hyperlight.Wasm.Build -c {{ if target == "debug" {"Debug"} else {"Release"} }} -o dotnet/artifacts

dotnet-rid := (if os() == "windows" { "win" } else if os() == "macos" { "osx" } else { "linux" }) + (if arch == "x86_64" { "-x64" } else { "-arm64" })
native-lib-prefix := if os() == "windows" { "" } else { "lib" }
native-lib-suffix := if os() == "windows" { ".dll" } else if os() == "macos" { ".dylib" } else { ".so" }

# Builds the .NET packages' native libraries in release and copies them to dotnet/native/runtimes/<rid>/native
dotnet-native:
cargo build -p hyperlight-wasm-capi -p hyperlight-wasm-csharp-bindgen --release
mkdir {{ mkdir-arg }} dotnet/native/runtimes/{{ dotnet-rid }}/native
{{ if os() == "windows" { "Copy-Item -Force" } else { "cp" } }} target/release/{{ native-lib-prefix }}hyperlight_wasm_capi{{ native-lib-suffix }} dotnet/native/runtimes/{{ dotnet-rid }}/native/
{{ if os() == "windows" { "Copy-Item -Force" } else { "cp" } }} target/release/{{ native-lib-prefix }}hyperlight_wasm_csharp_bindgen{{ native-lib-suffix }} dotnet/native/runtimes/{{ dotnet-rid }}/native/

# Packs version `version` of the .NET packages with the linux-x64, win-x64 and osx-arm64 libraries staged in dotnet/native/runtimes into dotnet/artifacts
dotnet-pack-prebuilt version: (dotnet-pack-project "Hyperlight.Wasm" version) (dotnet-pack-project "Hyperlight.Wasm.Build" version)

[private]
dotnet-pack-project project version:
dotnet pack dotnet/src/{{ project }} -c Release -o dotnet/artifacts -p:HyperlightNativeRuntimesDir={{ justfile_directory() }}/dotnet/native/runtimes/ -p:Version={{ version }}

# Test a component and a module compiled with pulley
examples-pulley target=default-target features="": (build-pulley-rust-component-examples target features) (build-pulley-rust-wasm-examples target features) (run-examples-pulley target features)

Expand Down
8 changes: 8 additions & 0 deletions dotnet/Directory.Build.props
Original file line number Diff line number Diff line change
Expand Up @@ -10,9 +10,13 @@
<VersionPrefix>$([System.Text.RegularExpressions.Regex]::Match('$(_HyperlightCargoToml)', '(?&lt;=\[workspace\.package\][^\[]*\nversion\s*=\s*")[^"]+').Value)</VersionPrefix>
<VersionSuffix>preview</VersionSuffix>
<Authors>The Hyperlight Authors</Authors>
<Copyright>Copyright The Hyperlight Authors</Copyright>
<PackageLicenseExpression>Apache-2.0</PackageLicenseExpression>
<PackageProjectUrl>https://github.com/hyperlight-dev/hyperlight-wasm</PackageProjectUrl>
<RepositoryUrl>https://github.com/hyperlight-dev/hyperlight-wasm</RepositoryUrl>
<PackageReadmeFile>README.md</PackageReadmeFile>
<!-- Deterministic builds with source paths that Source Link maps to the repository. -->
<ContinuousIntegrationBuild Condition="'$(GITHUB_ACTIONS)' == 'true'">true</ContinuousIntegrationBuild>
<!-- Cargo output for the native libraries. -->
<HyperlightCargoProfile Condition="'$(HyperlightCargoProfile)' == '' and '$(Configuration)' == 'Release'">release</HyperlightCargoProfile>
<HyperlightCargoProfile Condition="'$(HyperlightCargoProfile)' == ''">debug</HyperlightCargoProfile>
Expand All @@ -23,4 +27,8 @@
<HyperlightNativeSuffix Condition="$([MSBuild]::IsOSPlatform('OSX'))">.dylib</HyperlightNativeSuffix>
</PropertyGroup>

<ItemGroup>
<None Include="$(MSBuildThisFileDirectory)README.md" Pack="true" PackagePath="/" Visible="false" />
</ItemGroup>

</Project>
10 changes: 6 additions & 4 deletions dotnet/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,14 +8,14 @@ Run WebAssembly components in Hyperlight micro VMs from .NET, with typed binding
* `Hyperlight.Wasm` is the runtime library. It wraps the native `hyperlight-wasm-capi` library.
* `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.
Both target .NET 10 or later. The published packages hold native libraries for linux-x64, win-x64 and osx-arm64. Release versions end in `-preview`. Development builds of `main` are attached to the `dev-latest` GitHub release. To use one, download both `.nupkg` files into a directory and add it as a package source with `dotnet nuget add source <directory>`.

## Usage

```xml
<ItemGroup>
<PackageReference Include="Hyperlight.Wasm" Version="0.16.0-preview" />
<PackageReference Include="Hyperlight.Wasm.Build" Version="0.16.0-preview" />
<PackageReference Include="Hyperlight.Wasm" Version="0.17.0-preview" />
<PackageReference Include="Hyperlight.Wasm.Build" Version="0.17.0-preview" />
<HyperlightWit Include="wit/example.wit" World="example" />
</ItemGroup>
```
Expand Down Expand Up @@ -50,6 +50,8 @@ Both steps use `hyperlight-wasm-aot`, which needs rustup and clang. Its runtime
cargo install --locked hyperlight-wasm-aot --version <version>
```

For development packages, the `dev-latest` release notes give the commands that install it from their commit. The `repository` element of a package's `.nuspec` also holds its commit.

### 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`.
Expand Down Expand Up @@ -93,7 +95,7 @@ Hyperlight runs a helper process, `hyperlight_surrogate_<hash>.exe`, for each sa

```sh
just dotnet-test # builds the native libraries and test component, then runs the tests
just dotnet-pack # packs both packages into dotnet/artifacts
just dotnet-pack # packs both packages for this machine's runtime identifier into dotnet/artifacts
```

`HyperlightNativeDir` overrides where the projects find the native libraries.
10 changes: 9 additions & 1 deletion dotnet/src/Hyperlight.Wasm.Build/Hyperlight.Wasm.Build.csproj
Original file line number Diff line number Diff line change
Expand Up @@ -23,13 +23,21 @@
<ItemGroup>
<None Include="build/**" Pack="true" PackagePath="build/" />
<None Include="$(OutputPath)$(AssemblyName).dll" Pack="true" PackagePath="tasks/$(TargetFramework)/" Visible="false" />
</ItemGroup>
<!-- Packs the build machine's library, or the published runtimes staged by `just dotnet-native` when HyperlightNativeRuntimesDir is set. -->
<ItemGroup Condition="'$(HyperlightNativeRuntimesDir)' == ''">
<None Include="$(HyperlightBindgenNative)"
Pack="true"
PackagePath="tasks/$(TargetFramework)/runtimes/$(HyperlightNativeRid)/native/"
Visible="false" />
</ItemGroup>
<ItemGroup Condition="'$(HyperlightNativeRuntimesDir)' != ''">
<None Include="$(HyperlightNativeRuntimesDir)linux-x64/native/libhyperlight_wasm_csharp_bindgen.so" Pack="true" PackagePath="tasks/$(TargetFramework)/runtimes/linux-x64/native/" Visible="false" />
<None Include="$(HyperlightNativeRuntimesDir)win-x64/native/hyperlight_wasm_csharp_bindgen.dll" Pack="true" PackagePath="tasks/$(TargetFramework)/runtimes/win-x64/native/" Visible="false" />
<None Include="$(HyperlightNativeRuntimesDir)osx-arm64/native/libhyperlight_wasm_csharp_bindgen.dylib" Pack="true" PackagePath="tasks/$(TargetFramework)/runtimes/osx-arm64/native/" Visible="false" />
</ItemGroup>

<Target Name="CheckHyperlightNativeLibrary" BeforeTargets="GenerateNuspec">
<Target Name="CheckHyperlightNativeLibrary" BeforeTargets="GenerateNuspec" Condition="'$(HyperlightNativeRuntimesDir)' == ''">
<Error Condition="!Exists('$(HyperlightBindgenNative)')"
Text="Missing '$(HyperlightBindgenNative)'. Build it with `cargo build -p hyperlight-wasm-csharp-bindgen --profile $(HyperlightCargoProfile)`, using `dev` for debug, or set HyperlightNativeDir." />
</Target>
Expand Down
14 changes: 11 additions & 3 deletions dotnet/src/Hyperlight.Wasm/Hyperlight.Wasm.csproj
Original file line number Diff line number Diff line change
Expand Up @@ -6,25 +6,33 @@
<GenerateDocumentationFile>true</GenerateDocumentationFile>
<Description>Experimental. Runs WebAssembly components in Hyperlight micro VMs. Use with Hyperlight.Wasm.Build to generate typed bindings from WIT.</Description>
<PackageTags>hyperlight;wasm;webassembly;component;sandbox</PackageTags>
<IncludeSymbols>true</IncludeSymbols>
<SymbolPackageFormat>snupkg</SymbolPackageFormat>
</PropertyGroup>

<ItemGroup>
<InternalsVisibleTo Include="Hyperlight.Wasm.Tests" />
</ItemGroup>

<!-- The native library is copied next to referencing apps and packed for the build machine's runtime identifier. -->
<!-- The native library is copied next to referencing apps and packed for the build machine's runtime identifier.
With HyperlightNativeRuntimesDir set, the published runtimes staged by `just dotnet-native` are packed instead. -->
<PropertyGroup>
<HyperlightCapiLibrary>$(HyperlightNativeDir)$(HyperlightNativePrefix)hyperlight_wasm_capi$(HyperlightNativeSuffix)</HyperlightCapiLibrary>
</PropertyGroup>
<ItemGroup>
<ItemGroup Condition="'$(HyperlightNativeRuntimesDir)' == ''">
<None Include="$(HyperlightCapiLibrary)"
Link="$(HyperlightNativePrefix)hyperlight_wasm_capi$(HyperlightNativeSuffix)"
CopyToOutputDirectory="PreserveNewest"
Pack="true"
PackagePath="runtimes/$(HyperlightNativeRid)/native/" />
</ItemGroup>
<ItemGroup Condition="'$(HyperlightNativeRuntimesDir)' != ''">
<None Include="$(HyperlightNativeRuntimesDir)linux-x64/native/libhyperlight_wasm_capi.so" Pack="true" PackagePath="runtimes/linux-x64/native/" Visible="false" />
<None Include="$(HyperlightNativeRuntimesDir)win-x64/native/hyperlight_wasm_capi.dll" Pack="true" PackagePath="runtimes/win-x64/native/" Visible="false" />
<None Include="$(HyperlightNativeRuntimesDir)osx-arm64/native/libhyperlight_wasm_capi.dylib" Pack="true" PackagePath="runtimes/osx-arm64/native/" Visible="false" />
</ItemGroup>

<Target Name="CheckHyperlightNativeLibrary" BeforeTargets="PrepareForBuild;GenerateNuspec">
<Target Name="CheckHyperlightNativeLibrary" BeforeTargets="PrepareForBuild;GenerateNuspec" Condition="'$(HyperlightNativeRuntimesDir)' == ''">
<Error Condition="!Exists('$(HyperlightCapiLibrary)')"
Text="Missing '$(HyperlightCapiLibrary)'. Build it with `cargo build -p hyperlight-wasm-capi --profile $(HyperlightCargoProfile)`, using `dev` for debug, or set HyperlightNativeDir." />
</Target>
Expand Down
Loading