Skip to content

Commit 3a28293

Browse files
authored
docs: improve guest creation documentation (#1254)
Add a few more directions to readme and add some trouble shooting. Signed-off-by: James Sturtevant <jsturtevant@gmail.com>
1 parent 550d328 commit 3a28293

File tree

2 files changed

+52
-1
lines changed

2 files changed

+52
-1
lines changed

README.md

Lines changed: 27 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -69,10 +69,30 @@ fn main() -> hyperlight_host::Result<()> {
6969

7070
### Guest
7171

72+
First, create a `Cargo.toml` with the required dependencies:
73+
74+
```toml
75+
[package]
76+
name = "my-hyperlight-guest"
77+
version = "0.1.0"
78+
edition = "2024"
79+
80+
[dependencies]
81+
hyperlight-guest = "0.12"
82+
hyperlight-guest-bin = "0.12"
83+
hyperlight-common = { version = "0.12", default-features = false }
84+
```
85+
86+
> **Important:** The `hyperlight-common` crate must have `default-features = false` to avoid pulling in
87+
> the standard library, which conflicts with the `no_std` requirement for guests.
88+
89+
Then, create `src/main.rs`:
90+
7291
```rust
7392
#![no_std]
7493
#![no_main]
7594
extern crate alloc;
95+
extern crate hyperlight_guest_bin;
7696

7797
use alloc::vec::Vec;
7898
use alloc::string::String;
@@ -106,11 +126,15 @@ pub fn guest_dispatch_function(function_call: FunctionCall) -> Result<Vec<u8>> {
106126

107127
Build the guest using [cargo-hyperlight](https://github.com/hyperlight-dev/cargo-hyperlight):
108128

109-
```
129+
```sh
110130
cargo install --locked cargo-hyperlight
111131
cargo hyperlight build
112132
```
113133

134+
> **Note:** You must use `cargo hyperlight build` instead of the regular `cargo build` command.
135+
> The `cargo-hyperlight` tool sets up the required custom target, sysroot, and compiler flags
136+
> that are necessary for building Hyperlight guests.
137+
114138
For additional examples of using the Hyperlight host Rust library, see
115139
the [./src/hyperlight_host/examples](./src/hyperlight_host/examples) directory.
116140

@@ -199,6 +223,8 @@ your user is a member of that group.
199223
For more details on how to verify that KVM is correctly installed and permissions are correct, follow the
200224
guide [here](https://help.ubuntu.com/community/KVM/Installation).
201225

226+
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.
227+
202228
### Or you can use a codespace
203229

204230
[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/hyperlight-dev/hyperlight)

docs/how-to-build-a-hyperlight-guest-binary.md

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,31 @@ the guest to:
2323
- register functions that can be called by the host application
2424
- call host functions that have been registered by the host.
2525

26+
### Requirements
27+
28+
- **`#![no_std]`**: Hyperlight guests run in a minimal environment without an operating system
29+
- **`#![no_main]`**: The entry point is `hyperlight_main`, not the standard `main` function
30+
- **`extern crate alloc`**: Required for heap allocations (Vec, String, etc.)
31+
- **`extern crate hyperlight_guest_bin`**: Required to link the guest runtime (panic handler, etc.)
32+
33+
### Troubleshooting
34+
35+
#### "duplicate lang item `panic_impl`" error
36+
37+
This error occurs when the standard library's panic handler conflicts with
38+
`hyperlight_guest_bin`'s panic handler. To fix this:
39+
40+
1. Ensure `hyperlight-common` has `default-features = false` in your `Cargo.toml`
41+
2. Make sure your crate has `#![no_std]` at the top of `main.rs`
42+
3. Run `cargo clean` to clear any stale build artifacts
43+
4. Use `cargo hyperlight build` instead of `cargo build`
44+
45+
#### Build errors with dependencies
46+
47+
If you see errors related to building dependencies (like serde), ensure you're using
48+
`cargo hyperlight build`. This sets up the proper environment variables and sysroot
49+
for the custom Hyperlight target.
50+
2651
## C guest binary
2752

2853
For the binary written in C, the generated C bindings can be downloaded from the

0 commit comments

Comments
 (0)