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>

Author: jsturtevant

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<Vec<u8>> {
 
 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)

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