Add hyperlight-component-csharp

Signed-off-by: Ludvig Liljenberg <4257730+ludfjig@users.noreply.github.com>

Author: ludfjig

.github/workflows/CargoPublish.yml

@@ -52,7 +52,7 @@ jobs:
             VERSION="${VERSION#refs/heads/release/v}"
             echo "VERSION=$VERSION" >> $GITHUB_ENV
           fi
-          ./dev/verify-version.sh "$VERSION" hyperlight-common hyperlight-guest hyperlight-guest-bin hyperlight-host hyperlight-component-util hyperlight-component-macro hyperlight-guest-tracing
+          ./dev/verify-version.sh "$VERSION" hyperlight-common hyperlight-guest hyperlight-guest-bin hyperlight-host hyperlight-component-util hyperlight-component-macro hyperlight-component-csharp hyperlight-guest-tracing
 
       - name: Determine which crates need publishing
         run: |
@@ -64,6 +64,7 @@ jobs:
             hyperlight-guest-bin \
             hyperlight-component-util \
             hyperlight-component-macro \
+            hyperlight-component-csharp \
             hyperlight-host \
             hyperlight-guest-tracing >> "$GITHUB_ENV"
 
@@ -134,6 +135,13 @@ jobs:
           CARGO_REGISTRY_TOKEN: ${{ steps.crates-io-auth.outputs.token }}
         if: env.PUBLISH_HYPERLIGHT_HOST != 'false'
 
+      - name: Publish hyperlight-component-csharp
+        continue-on-error: ${{ inputs.dry_run }}
+        run: cargo publish --manifest-path ./src/hyperlight_component_csharp/Cargo.toml ${{ inputs.dry_run && '--dry-run' || '' }}
+        env:
+          CARGO_REGISTRY_TOKEN: ${{ steps.crates-io-auth.outputs.token }}
+        if: env.PUBLISH_HYPERLIGHT_COMPONENT_CSHARP != 'false'
+
 
       # TODO: Do we want to publish hyperlight-guest-capi to crates.io given that it's not for Rust consumption?
       # - name: Publish hyperlight-guest-capi

CHANGELOG.md

@@ -5,6 +5,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 ## [Prerelease] - Unreleased
 
 ### Added
+* `hyperlight-component-csharp` crate for generating C# host bindings from WIT worlds by @ludfjig in https://github.com/hyperlight-dev/hyperlight/pull/1946
 
 ### Changed
 * **Breaking:** `hyperlight-component-macro`: `host_bindgen!` and `guest_bindgen!` encode values little-endian and qualify function names with their interface, such as `wasi:http/types@0.2.0#[method]fields.get` by @ludfjig in https://github.com/hyperlight-dev/hyperlight/pull/1946

Cargo.lock

@@ -19,6 +19,7 @@ members = [
     "src/hyperlight_libc",
     "src/hyperlight_component_util",
     "src/hyperlight_component_macro",
+    "src/hyperlight_component_csharp",
     "src/trace_dump",
 ]
 # Guests have custom linker flags and live in their own nested workspace,
@@ -47,6 +48,7 @@ hyperlight-guest-tracing = { path = "src/hyperlight_guest_tracing", version = "0
 hyperlight-libc = { path = "src/hyperlight_libc", version = "0.18.0", default-features = false }
 hyperlight-component-util = { path = "src/hyperlight_component_util", version = "0.18.0", default-features = false }
 hyperlight-component-macro = { path = "src/hyperlight_component_macro", version = "0.18.0", default-features = false }
+hyperlight-component-csharp = { path = "src/hyperlight_component_csharp", version = "0.18.0", default-features = false }
 
 [workspace.lints.rust]
 unsafe_op_in_unsafe_fn = "deny"

Cargo.toml

@@ -151,7 +151,7 @@ code-checks-like-ci config=default-target hypervisor="kvm":
     {{ if os() == "linux" { "just clippy-exhaustive " + config } else { "" } }}
 
     @# Verify MSRV
-    ./dev/verify-msrv.sh hyperlight-common hyperlight-guest hyperlight-guest-bin hyperlight-host hyperlight-component-util hyperlight-component-macro hyperlight-guest-tracing
+    ./dev/verify-msrv.sh hyperlight-common hyperlight-guest hyperlight-guest-bin hyperlight-host hyperlight-component-util hyperlight-component-macro hyperlight-component-csharp hyperlight-guest-tracing
 
     @# Check cargo features compile
     just check
@@ -287,6 +287,7 @@ test-integration target=default-target features="":
 
     @# run component-util unit tests and the integration tests that exercise WIT input codegen
     {{ cargo-cmd }} test -p hyperlight-component-util --profile={{ if target == "debug" { "dev" } else { target } }} {{ target-triple-flag }} --lib --test wasmtime_guest_codegen
+    {{ cargo-cmd }} test -p hyperlight-component-csharp --profile={{ if target == "debug" { "dev" } else { target } }} {{ target-triple-flag }} --lib
 
     @# run the rest of the integration tests. `snapshot_goldens` is in
     @# the glob but no-ops without a mode token, so it needs no golden
@@ -414,6 +415,7 @@ clippy-exhaustive target=default-target:
     ./hack/clippy-package-features.sh hyperlight-testing {{ target }} {{ target-triple }}
     ./hack/clippy-package-features.sh hyperlight-component-macro  {{ target }} {{ target-triple }}
     ./hack/clippy-package-features.sh hyperlight-component-util {{ target }} {{ target-triple }}
+    ./hack/clippy-package-features.sh hyperlight-component-csharp {{ target }} {{ target-triple }}
     {{ if hyperlight-target-arch == "x86_64" { "./hack/clippy-package-features.sh hyperlight-guest-tracing " + target } else { "" } }}
     just clippy-guests {{ target }}
 
@@ -423,7 +425,7 @@ clippy-package package target=default-target:
 
 # Verify Minimum Supported Rust Version
 verify-msrv:
-    ./dev/verify-msrv.sh hyperlight-common hyperlight-guest hyperlight-guest-bin hyperlight-host hyperlight-component-util hyperlight-component-macro hyperlight-guest-tracing
+    ./dev/verify-msrv.sh hyperlight-common hyperlight-guest hyperlight-guest-bin hyperlight-host hyperlight-component-util hyperlight-component-macro hyperlight-component-csharp hyperlight-guest-tracing
 
 #####################
 ### RUST EXAMPLES ###
@@ -548,7 +550,7 @@ ensure-cargo-llvm-cov:
 
 # host-side packages to collect coverage for (guest/no_std crates are excluded because they
 # define #[panic_handler] and cannot be compiled for the host target under coverage instrumentation)
-coverage-packages := "-p hyperlight-common -p hyperlight-host -p hyperlight-testing -p hyperlight-component-util -p hyperlight-component-macro"
+coverage-packages := "-p hyperlight-common -p hyperlight-host -p hyperlight-testing -p hyperlight-component-util -p hyperlight-component-macro -p hyperlight-component-csharp"
 
 # run all tests and examples with coverage instrumentation, collecting profdata without
 # generating a report. Mirrors test-like-ci + run-examples-like-ci to exercise all code paths

Justfile

@@ -1,8 +1,9 @@
 # Component wire format
 
 Bindings generated from WIT exchange values in this format. It is used by
-`host_bindgen!`, `guest_bindgen!` and the hyperlight-wasm guest runtime. The
-host and guest must be built from the same Hyperlight version.
+`host_bindgen!`, `guest_bindgen!`, the hyperlight-wasm guest runtime, and the
+C# generator in `hyperlight-component-csharp`. The host and guest must be built
+from the same Hyperlight version.
 
 ## Calls
 
@@ -49,3 +50,47 @@ their parts with no alignment.
 lists encodings of the types in
 [`wire.wit`](../src/tests/component_wire/wire.wit). The Rust host bindings are
 tested against it.
+
+## C# host bindings
+
+`hyperlight_component_csharp::generate_from_path` generates C# for the host
+side of a world. The generated code depends on the `Hyperlight.Component`
+namespace in `hyperlight_component_csharp::RUNTIME_SOURCE`. It targets .NET 8
+or later.
+
+For a world `w`, the generator emits:
+
+* `WComponent`, constructed from an `IGuestCaller`. It has a property for each
+  exported interface and a method for each function the world exports.
+* `WComponent.RegisterImports`, which registers host functions on an
+  `IHostFunctionRegistry` from an implementation of each imported interface.
+* A C# interface `IName` for each imported interface `name`, and `IWImports`
+  for functions the world imports.
+* Types for every record, variant, enum and flags in the world's interfaces.
+
+| WIT type | C# type |
+|---|---|
+| `bool`, integers, floats | `bool`, `sbyte` to `ulong`, `float`, `double` |
+| `char` | `System.Text.Rune` |
+| `string` | `string` |
+| `list<u8>`, `list<u8, N>` | `byte[]` |
+| `list<T>`, `list<T, N>` | `IReadOnlyList<T>` |
+| `tuple<...>` | Value tuple |
+| `option<T>` | `T?`, or `Option<T>` when `T` is an `option` |
+| `result<T, E>` | `Result<T, E>`, with `Unit` for a missing type |
+| `record` | Sealed record with `required init` properties |
+| `variant` | Abstract record with a nested sealed record per case |
+| `enum` | `enum` with `uint` values |
+| `flags` | `[Flags]` enum with `uint` values |
+
+Resources, async functions, futures, streams, maps and flags with more than 32
+members are rejected.
+
+Records, variant cases, `Option` and `Result` compare lists by element.
+Variants and `Result` have `Match` and `Switch` methods that take one function
+per case. These give a compile error when a case is missing.
+
+For a root namespace `Root`, types from `ns:pkg/iface` are in
+`Root.Ns.Pkg.Iface`. The C# interface or exports class for `iface` is in
+`Root.Ns.Pkg`. A world that uses two versions of a package gets the version
+after `Pkg`, such as `Root.Ns.Pkg.V1_0_0`.

docs/component-wire-format.md

@@ -63,6 +63,7 @@ When this job is done, a new [GitHub release](https://github.com/hyperlight-dev/
 - `hyperlight-guest-bin`
 - `hyperlight-component-util`
 - `hyperlight-component-macro`
+- `hyperlight-component-csharp`
 - `hyperlight-host`
 - `hyperlight-guest-tracing`
 

docs/how-to-make-releases.md

@@ -0,0 +1,21 @@
+[package]
+name = "hyperlight-component-csharp"
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+homepage.workspace = true
+repository.workspace = true
+readme = "README.md"
+description = """
+Generates C# host bindings for Hyperlight components from WIT worlds
+"""
+
+[lib]
+name = "hyperlight_component_csharp"
+
+[dependencies]
+hyperlight-component-util = { workspace = true }
+
+[dev-dependencies]
+proc-macro2 = { version = "1.0.106" }

src/hyperlight_component_csharp/Cargo.toml

@@ -0,0 +1,42 @@
+# hyperlight-component-csharp
+
+Generates C# host bindings for a WIT world. A .NET host uses them to call a
+Hyperlight component guest and to serve its imports.
+
+hyperlight-wasm's .NET packages use this crate to generate bindings at build
+time. Hyperlight itself has no .NET host.
+
+## Usage
+
+```rust
+let cs = hyperlight_component_csharp::generate_from_path(
+    Path::new("wit/world.wit"),
+    None,            // world name, or None for the last world
+    "MyApp.Guest",   // root C# namespace
+)?;
+std::fs::write("Bindings.g.cs", cs)?;
+```
+
+`generate` takes a `hyperlight_component_util::util::WitSource`, the input
+type of the bindgen macros. It reads the world through the same component type
+elaboration as the macros.
+
+For a world `w`, the output has:
+
+* `WComponent`, which calls the guest's exports.
+* `WComponent.RegisterImports`, which registers host implementations of the
+  guest's imports.
+* A C# type for each record, variant, enum and flags type.
+
+See [docs/component-wire-format.md](../../docs/component-wire-format.md) for
+the type mapping and the wire format.
+
+## Runtime.cs
+
+The generated code needs the C# types in [`src/Runtime.cs`](src/Runtime.cs).
+The Rust constant `hyperlight_component_csharp::RUNTIME_SOURCE` holds the text
+of this file, so tools can write it out next to the generated code.
+
+A .NET host library, such as hyperlight-wasm's, includes this file in its build.
+It implements the file's `IGuestCaller` and `IHostFunctionRegistry` interfaces
+with its sandbox.