diff --git a/README.md b/README.md index 0312124c1..9d88802c7 100644 --- a/README.md +++ b/README.md @@ -69,10 +69,30 @@ fn main() -> hyperlight_host::Result<()> { ### Guest +First, create a `Cargo.toml` with the required dependencies: + +```toml +[package] +name = "my-hyperlight-guest" +version = "0.1.0" +edition = "2024" + +[dependencies] +hyperlight-guest = "0.12" +hyperlight-guest-bin = "0.12" +hyperlight-common = { version = "0.12", default-features = false } +``` + +> **Important:** The `hyperlight-common` crate must have `default-features = false` to avoid pulling in +> the standard library, which conflicts with the `no_std` requirement for guests. + +Then, create `src/main.rs`: + ```rust #![no_std] #![no_main] extern crate alloc; +extern crate hyperlight_guest_bin; use alloc::vec::Vec; use alloc::string::String; @@ -106,11 +126,15 @@ pub fn guest_dispatch_function(function_call: FunctionCall) -> Result> { Build the guest using [cargo-hyperlight](https://github.com/hyperlight-dev/cargo-hyperlight): -``` +```sh cargo install --locked cargo-hyperlight cargo hyperlight build ``` +> **Note:** You must use `cargo hyperlight build` instead of the regular `cargo build` command. +> The `cargo-hyperlight` tool sets up the required custom target, sysroot, and compiler flags +> that are necessary for building Hyperlight guests. + For additional examples of using the Hyperlight host Rust library, see the [./src/hyperlight_host/examples](./src/hyperlight_host/examples) directory. @@ -199,6 +223,8 @@ your user is a member of that group. For more details on how to verify that KVM is correctly installed and permissions are correct, follow the guide [here](https://help.ubuntu.com/community/KVM/Installation). +For additional debugging tips, including common build and runtime issues, see the [How to build a Hyperlight guest binary](./docs/how-to-build-a-hyperlight-guest-binary.md) guide. + ### Or you can use a codespace [![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/hyperlight-dev/hyperlight) diff --git a/docs/how-to-build-a-hyperlight-guest-binary.md b/docs/how-to-build-a-hyperlight-guest-binary.md index a76e43d4b..47275eb24 100644 --- a/docs/how-to-build-a-hyperlight-guest-binary.md +++ b/docs/how-to-build-a-hyperlight-guest-binary.md @@ -23,6 +23,31 @@ the guest to: - register functions that can be called by the host application - call host functions that have been registered by the host. +### Requirements + +- **`#![no_std]`**: Hyperlight guests run in a minimal environment without an operating system +- **`#![no_main]`**: The entry point is `hyperlight_main`, not the standard `main` function +- **`extern crate alloc`**: Required for heap allocations (Vec, String, etc.) +- **`extern crate hyperlight_guest_bin`**: Required to link the guest runtime (panic handler, etc.) + +### Troubleshooting + +#### "duplicate lang item `panic_impl`" error + +This error occurs when the standard library's panic handler conflicts with +`hyperlight_guest_bin`'s panic handler. To fix this: + +1. Ensure `hyperlight-common` has `default-features = false` in your `Cargo.toml` +2. Make sure your crate has `#![no_std]` at the top of `main.rs` +3. Run `cargo clean` to clear any stale build artifacts +4. Use `cargo hyperlight build` instead of `cargo build` + +#### Build errors with dependencies + +If you see errors related to building dependencies (like serde), ensure you're using +`cargo hyperlight build`. This sets up the proper environment variables and sysroot +for the custom Hyperlight target. + ## C guest binary For the binary written in C, the generated C bindings can be downloaded from the