[guest-bin] created the guest-bin crate

danbugs · danbugs · commit 5f321cf71c34 · 2025-06-02T00:10:04.000Z
It's currently hard to use the guest library. For instance, it defines a panic handler, which will
cause compilation errors if a user of the library already has one defined. This commit creates a new crate to
house the opinionated bits of the guest library to make its base functionality (i.e., causing
VM exits, calling host functions) easier to consume without sacrificing functionality that currently exists in
guest lib that makes writing guest apps easier.

Aside from creating the crate, this commit also fixes up some doc references that referenced the guest lib
alone.

Signed-off-by: danbugs &lt;danilochiarlone@gmail.com&gt;
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
@@ -76,6 +76,7 @@ This repository requires commits to be signed you should ensure that any commits
 - `fuzz` - contains the fuzzing tests for the project
 - `src/hyperlight_common/` - contains the common code shared between the host and guest
 - `src/hyperlight_guest/` - contains the hyperlight-guest library code
+- `src/hyperlight_guest_bin/` - contains the hyperlight-guest-bin library code
 - `src/hyperlight_host/` - contains the hyperlight-host library code
 - `src/hyperlight_guest_capi/` - contains the hyperlight-guest C library code
 - `src/hyperlight_testing/` - contains the shared code for tests
diff --git a/.github/workflows/CargoPublish.yml b/.github/workflows/CargoPublish.yml
@@ -45,7 +45,7 @@ jobs:
             VERSION="${{ github.ref }}"
             VERSION="${VERSION#refs/heads/release/v}"
           fi
-          ./dev/verify-version.sh "$VERSION" hyperlight-common hyperlight-guest hyperlight-host
+          ./dev/verify-version.sh "$VERSION" hyperlight-common hyperlight-guest hyperlight-guest-bin hyperlight-host
 
       - name: Publish hyperlight-common
         continue-on-error: ${{ inputs.dry_run }}
@@ -59,6 +59,13 @@ jobs:
         env:
           CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_PUBLISH_TOKEN }}
 
+      # TODO(danbugs): reserve the crate hyperlight-guest-bin on crates.io
+      # - name: Publish hyperlight-guest-bin
+      #   continue-on-error: ${{ inputs.dry_run }}
+      #   run: cargo publish --manifest-path ./src/hyperlight_guest_bin/Cargo.toml ${{ inputs.dry_run && '--dry-run' || '' }}
+      #   env:
+      #     CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_PUBLISH_TOKEN }}
+
       - name: Publish hyperlight-host
         continue-on-error: ${{ inputs.dry_run }}
         run: cargo publish --manifest-path ./src/hyperlight_host/Cargo.toml ${{ inputs.dry_run && '--dry-run' || '' }}
diff --git a/.github/workflows/dep_rust.yml b/.github/workflows/dep_rust.yml
@@ -93,7 +93,7 @@ jobs:
         run: just build ${{ matrix.config }}
 
       - name: Verify MSRV
-        run: ./dev/verify-msrv.sh hyperlight-host hyperlight-guest hyperlight-common
+        run: ./dev/verify-msrv.sh hyperlight-host hyperlight-guest hyperlight-guest-bin hyperlight-common
 
       - name: Run Rust tests
         env:
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -11,7 +11,8 @@ members = [
     "src/hyperlight_host",
     "src/hyperlight_guest_capi",
     "src/hyperlight_testing",
-    "fuzz",
+    "fuzz", 
+    "src/hyperlight_guest_bin",
 ]
 # Guests have custom linker flags, so we need to exclude them from the workspace
 exclude = [
@@ -33,6 +34,7 @@ readme = "README.md"
 hyperlight-common = { path = "src/hyperlight_common", version = "0.5.0", default-features = false }
 hyperlight-host = { path = "src/hyperlight_host", version = "0.5.0", default-features = false }
 hyperlight-guest = { path = "src/hyperlight_guest", version = "0.5.0", default-features = false }
+hyperlight-guest-bin = { path = "src/hyperlight_guest_bin", version = "0.5.0", default-features = false }
 hyperlight-testing = { path = "src/hyperlight_testing", default-features = false }
 
 [workspace.lints.rust]
diff --git a/Justfile b/Justfile
@@ -153,7 +153,7 @@ clippy-apply-fix-windows:
 
 # Verify Minimum Supported Rust Version
 verify-msrv:
-    ./dev/verify-msrv.sh hyperlight-host hyperlight-guest hyperlight-common
+    ./dev/verify-msrv.sh hyperlight-host hyperlight-guest hyperlight-guest-lib hyperlight-common
 
 #####################
 ### RUST EXAMPLES ###
@@ -175,6 +175,7 @@ run-rust-examples-linux target=default-target features="": (run-rust-examples ta
 #########################
 
 tar-headers: (build-rust-capi) # build-rust-capi is a dependency because we need the hyperlight_guest.h to be built
+    # TODO(danbugs): update this when I'm done w/ the move
     tar -zcvf include.tar.gz -C {{root}}/src/hyperlight_guest/third_party/ musl/include musl/arch/x86_64 printf/printf.h -C {{root}}/src/hyperlight_guest_capi include
 
 tar-static-lib: (build-rust-capi "release") (build-rust-capi "debug")
diff --git a/README.md b/README.md
@@ -87,11 +87,9 @@ use hyperlight_common::flatbuffer_wrappers::guest_error::ErrorCode;
 use hyperlight_common::flatbuffer_wrappers::util::get_flatbuffer_result_from_int;
 
 use hyperlight_guest::error::{HyperlightGuestError, Result};
-use hyperlight_guest::guest_function_definition::GuestFunctionDefinition;
-use hyperlight_guest::guest_function_register::register_function;
-use hyperlight_guest::host_function_call::{
-    call_host_function, get_host_value_return_as_int,
-};
+use hyperlight_guest_bin::guest_function::definition::GuestFunctionDefinition;
+use hyperlight_guest_bin::guest_function::register::register_function;
+use hyperlight_guest_bin::host_comm::{call_host_function, call_host_function_without_returning};
 
 fn print_output(function_call: &FunctionCall) -> Result<Vec<u8>> {
     if let ParameterValue::String(message) = function_call.parameters.clone().unwrap()[0].clone() {
@@ -145,9 +143,9 @@ the [./src/tests/rust_guests](./src/tests/rust_guests) directory for Rust guests
     - [src/hyperlight_host](./src/hyperlight_host) - This is the Rust Hyperlight host library.
 
 - Hyperlight Guest Libraries (i.e., the ones to make it easier to create guests that run inside the VMs)
-    - [src/hyperlight_guest](./src/hyperlight_guest) - This is the Rust Hyperlight guest library.
-    - [src/hyperlight_guest_capi](./src/hyperlight_guest_capi) - This is the C compatible wrapper for the Hyperlight
-      guest library.
+    - [src/hyperlight_guest](./src/hyperlight_guest) - The core Rust library for Hyperlight guests. It provides only the essential building blocks for interacting with the host environment, including the VM exit mechanism (`outb`), abstractions for calling host functions and receiving return values, and the input/output stacks used for guest-host communication.
+    - [src/hyperlight_guest_bin](./src/hyperlight_guest_bin/) - A minimal shim that allows using `hyperlight_guest` without adopting its more opinionated components (e.g., panic handler, heap initialization, musl-specific imports, logging, and exception handling).
+    - [src/hyperlight_guest_capi](./src/hyperlight_guest_capi) - A C-compatible wrapper around `hyperlight_guest_bin`, exposing its core functionality for use in C programs and other languages via FFI.
 
 - Hyperlight Common (functionality used by both the host and the guest)
     - [src/hyperlight_common](./src/hyperlight_common)
diff --git a/c.just b/c.just
@@ -3,6 +3,7 @@ mkdir := if os() == "windows" { "mkdir -f -p" } else { "mkdir -p"}
 # Elf options
 # We don't support stack protectors at the moment, but Arch Linux clang auto-enables them for -linux platforms, so explicitly disable them.
 c-compile-options-elf := '-nobuiltininc -H --target=x86_64-unknown-linux-none -fno-stack-protector -fstack-clash-protection -mstack-probe-size=4096 -fPIC'
+# TODO(danbugs): update this when I'm done w/ the move
 c-include-flags-elf := "-I " + root / "src/hyperlight_guest_capi/include/"  + " -I " + root / "src/hyperlight_guest/third_party/musl/include/" + " -I " + root / "src/hyperlight_guest/third_party/musl/arch/x86_64" + " -I " + root / "src/hyperlight_guest/third_party/printf"
 c-linker-options-elf := '--entry "entrypoint" --nostdlib -pie'
 c-flags-debug-elf := '-O0'
diff --git a/dev/verify-msrv.sh b/dev/verify-msrv.sh
@@ -6,7 +6,7 @@ for CRATE in "$@"; do
     if ! rustup toolchain list | grep -q "$VERSION"; then
         rustup --quiet toolchain install "$VERSION" --no-self-update --profile minimal
     fi
-    if [[ "$CRATE" == "hyperlight-guest" ]]; then
+    if [[ "$CRATE" == "hyperlight-guest"  || "$CRATE" == "hyperlight-guest-bin" ]]; then
         TARGET="x86_64-unknown-none"
         rustup target add "$TARGET" --toolchain "$VERSION" >/dev/null
         if cargo +"$VERSION" check --quiet -p "$CRATE" --target "$TARGET"; then
diff --git a/docs/how-to-build-a-hyperlight-guest-binary.md b/docs/how-to-build-a-hyperlight-guest-binary.md
@@ -18,7 +18,7 @@ binary can be used with Hyperlight:
 ## Rust guest binary
 
 In the case of a binary that is written in Rust, one needs to make use of the
-Hyperlight crate, `hyperlight_guest` that contains the types and APIs that enable
+Hyperlight crate, `hyperlight_guest` and `hyperlight_guest_bin` that contains the types and APIs that enable
 the guest to:
 - register functions that can be called by the host application
 - call host functions that have been registered by the host.
diff --git a/docs/how-to-make-releases.md b/docs/how-to-make-releases.md
@@ -55,6 +55,7 @@ After the previous CI job runs to create the new release branch, go to the ["Cre
 When this job is done, a new [GitHub release](https://github.com/hyperlight-dev/hyperlight/releases) will be created for you. This job also publishes the following rust packages to the crates.io:
 - `hyperlight-common`
 - `hyperlight-guest`
+- `hyperlight-guest-bin`
 - `hyperlight-host`
 
 ## Patching a release
diff --git a/src/hyperlight_guest/build.rs b/src/hyperlight_guest/build.rs
@@ -109,6 +109,7 @@ fn cargo_main() {
             unsafe { env::set_var("AR_x86_64_pc_windows_msvc", "llvm-lib") };
         }
 
+        // TODO(danbugs): update this when I'm done w/ the move.
         cfg.compile("hyperlight_guest");
     }
 
diff --git a/src/hyperlight_guest/third_party/musl/include/stdlib.h b/src/hyperlight_guest/third_party/musl/include/stdlib.h
@@ -34,7 +34,7 @@ unsigned long strtoul (const char *__restrict, char **__restrict, int);
 long long strtoll (const char *__restrict, char **__restrict, int);
 unsigned long long strtoull (const char *__restrict, char **__restrict, int);
 
-// These 5 functions are implemented in rust in hyperlight_guest
+// These 5 functions are implemented in rust in hyperlight_guest_bin
 _Noreturn void abort (void);
 void *malloc (size_t);
 void *calloc (size_t, size_t);
diff --git a/src/hyperlight_guest_bin/Cargo.toml b/src/hyperlight_guest_bin/Cargo.toml
@@ -0,0 +1,14 @@
+[package]
+name = "hyperlight-guest-bin"
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+homepage.workspace = true
+repository.workspace = true
+readme.workspace = true
+
+[dependencies]
+
+[lints]
+workspace = true
diff --git a/src/hyperlight_guest_bin/src/lib.rs b/src/hyperlight_guest_bin/src/lib.rs
@@ -0,0 +1,15 @@
+/*
+Copyright 2024 The Hyperlight Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
diff --git a/src/hyperlight_guest_capi/README.md b/src/hyperlight_guest_capi/README.md
@@ -1,4 +1,4 @@
-This is a c-api wrapper over the hyperlight-guest crate. The purpose of this crate is to allow the creation of guests in the c language. This crate generates a .lib/.a library file depending on the platform, as well necessary header files. 
+This is a c-api wrapper over the hyperlight-guest/hyperlight-guest-bin crate. The purpose of this crate is to allow the creation of guests in the c language. This crate generates a .lib/.a library file depending on the platform, as well necessary header files. 
 
 For examples on how to use it, see the c [simpleguest](../tests/c_guests/c_simpleguest/).
 
diff --git a/src/tests/c_guests/c_callbackguest/main.c b/src/tests/c_guests/c_callbackguest/main.c
@@ -1,5 +1,6 @@
 // Included from hyperlight_guest_capi/include
 #include "hyperlight_guest.h"
+// TODO(danbugs): update when I'm done w/ the move
 // Included from hyperlight_guest/third_party/libc
 #include "stdint.h"
 #include "stdio.h"
diff --git a/src/tests/c_guests/c_simpleguest/main.c b/src/tests/c_guests/c_simpleguest/main.c
@@ -1,5 +1,6 @@
 // Included from hyperlight_guest_capi/include
 #include "hyperlight_guest.h"
+// TODO(danbugs): update when I'm done w/ the move
 // Included from hyperlight_guest/third_party/libc
 #include "stdint.h"
 #include "string.h"
diff --git a/typos.toml b/typos.toml
@@ -2,6 +2,7 @@
 extend-ignore-identifiers-re = ["Fo"]
 
 [files]
+# TODO(danbugs): update this when I'm done w/ the move
 extend-exclude = ["**/*.patch", "src/hyperlight_guest/third_party/**/*", "NOTICE.txt"]
 
 [default.extend-words]
