Skip to content

[WIP] Enable native debugging for wasm modules/components #129

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

[WIP] Enable native debugging for wasm modules/components #129

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e7fd9c0
Enable native debugging for wasm modules/components
dblnz Jul 23, 2025
966c54b
Fix build and clippy checks when gdb features is enabled on windows
dblnz Sep 29, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
106 changes: 84 additions & 22 deletions .vscode/launch.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,34 +1,96 @@
{
// Use IntelliSense to learn about possible attributes.
// Hover to view descriptions of existing attributes.
// For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
// this can be used to debug tests
"version": "0.2.0",
"inputs": [
{
"id": "program",
"type": "promptString",
"default": "x64/debug/wasm_runtime",
"description": "Path to the program to debug",
}
],
"configurations": [
{
"type": "lldb",
"request": "launch",
"name": "Cargo test",
"name": "Debug example 'guest-debugging'",
"cargo": {
"args": [
"build",
"--example=guest-debugging",
"--package=hyperlight-wasm",
"--features=gdb",
],
"filter": {
"name": "guest-debugging",
"kind": "example"
}
},
"env": {
"RUST_DIR_FOR_DEBUGGING_TESTS": "${workspaceFolder}/src/hyperlight_wasm",
},
"args": [],
"cwd": "${workspaceFolder}"
},
{
"type": "lldb",
"request": "launch",
"name": "Debug example 'rust_wasm_examples'",
"cargo": {
"args": [
"test",
"--profile=dev",
"--lib",
"--no-run"

],
"filter": {
"name": "hyperlight_wasm",
"kind": "lib"
}
"args": [
"build",
"--example=rust_wasm_examples",
"--package=hyperlight-wasm",
],
"filter": {
"name": "rust_wasm_examples",
"kind": "example"
}
},
"env": {
"RUST_DIR_FOR_DEBUGGING_TESTS": "${workspaceFolder}/src/hyperlight_wasm"
"RUST_DIR_FOR_DEBUGGING_TESTS": "${workspaceFolder}/src/hyperlight_wasm",
},
"args": [],
"cwd": "${workspaceFolder}"
},
{
"name": "Remote GDB attach",
"type": "cppdbg",
"request": "launch",
"program": "${input:program}",
"args": [],
"stopAtEntry": true,
"hardwareBreakpoints": {
"require": false,
"limit": 4
},
"args": [
"--exact",
"sandbox::loaded_wasm_sandbox::tests::test_call_host_func_with_vecbytes"
"cwd": "${workspaceFolder}",
"environment": [],
"externalConsole": false,
"MIMode": "gdb",
"miDebuggerPath": "/usr/bin/gdb",
"miDebuggerServerAddress": "localhost:8080",
"setupCommands": [
{
"description": "Enable pretty-printing for gdb",
"text": "-enable-pretty-printing",
"ignoreFailures": true
},
{
"description": "Set Disassembly Flavor to Intel",
"text": "-gdb-set disassembly-flavor intel",
"ignoreFailures": true
},
]
}
},
{
"name": "Remote LLDB attach",
"type": "lldb",
"request": "launch",
"targetCreateCommands": [
"target create ${input:program}",
],
"processCreateCommands": [
"gdb-remote localhost:8080"
],
},
]
}
40 changes: 40 additions & 0 deletions Cargo.lock
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

21 changes: 12 additions & 9 deletions Justfile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ ensure-tools:
cargo install cargo-component --locked --version 0.21.1
cargo install wit-bindgen-cli --locked --version 0.43.0

build-all target=default-target: (build target) (build-wasm-examples target) (build-rust-wasm-examples target) (build-rust-component-examples target) (build-wasm-runtime target)
build-all target=default-target features="": (build target features) (build-wasm-examples target features) (build-rust-wasm-examples target features) (build-rust-component-examples target) (build-wasm-runtime target features)

build target=default-target features="": (fmt-check)
cargo build {{ if features =="" {''} else if features=="no-default-features" {"--no-default-features" } else {"--no-default-features -F " + features } }} --verbose --profile={{ if target == "debug" {"dev"} else { target } }}
Expand All @@ -32,23 +32,23 @@ compile-wit:
wasm-tools component wit ./src/wasmsamples/components/runcomponent.wit -w -o ./src/wasmsamples/components/runcomponent-world.wasm
wasm-tools component wit ./src/component_sample/wit/example.wit -w -o ./src/component_sample/wit/component-world.wasm

build-wasm-runtime target=default-target:
cd ./src/wasm_runtime && cargo build --verbose --profile={{ if target == "debug" {"dev"} else { target } }} && rm -R target
build-wasm-runtime target=default-target features="":
cd ./src/wasm_runtime && cargo build --verbose {{ if features =="" {''} else if features=="no-default-features" {"--no-default-features" } else {"--features " + features } }} --profile={{ if target == "debug" {"dev"} else { target } }} && rm -R target

build-wasm-examples target=default-target: (compile-wit)
{{ build-wasm-examples-command }} {{target}}
build-wasm-examples target=default-target features="": (compile-wit)
{{ build-wasm-examples-command }} {{target}} {{features}}

build-rust-wasm-examples target=default-target: (mkdir-redist target)
build-rust-wasm-examples target=default-target features="": (mkdir-redist target)
rustup target add wasm32-unknown-unknown
cd ./src/rust_wasm_samples && cargo build --target wasm32-unknown-unknown --profile={{ if target == "debug" {"dev"} else { target } }}
cargo run -p hyperlight-wasm-aot compile ./src/rust_wasm_samples/target/wasm32-unknown-unknown/{{ target }}/rust_wasm_samples.wasm ./x64/{{ target }}/rust_wasm_samples.aot
cargo run {{ if features =="" {''} else if features=="no-default-features" {"--no-default-features" } else {"--features " + features } }} -p hyperlight-wasm-aot compile ./src/rust_wasm_samples/target/wasm32-unknown-unknown/{{ target }}/rust_wasm_samples.wasm ./x64/{{ target }}/rust_wasm_samples.aot

build-rust-component-examples target=default-target: (compile-wit)
build-rust-component-examples target=default-target features="": (compile-wit)
# use cargo component so we don't get all the wasi imports https://github.com/bytecodealliance/cargo-component?tab=readme-ov-file#relationship-with-wasm32-wasip2
# we also explicitly target wasm32-unknown-unknown since cargo component might try to pull in wasi imports https://github.com/bytecodealliance/cargo-component/issues/290
rustup target add wasm32-unknown-unknown
cd ./src/component_sample && cargo component build --target wasm32-unknown-unknown --profile={{ if target == "debug" {"dev"} else { target } }}
cargo run -p hyperlight-wasm-aot compile --component ./src/component_sample/target/wasm32-unknown-unknown/{{ target }}/component_sample.wasm ./x64/{{ target }}/component_sample.aot
cargo run {{ if features =="" {''} else if features=="no-default-features" {"--no-default-features" } else {"--features " + features } }} -p hyperlight-wasm-aot compile --component ./src/component_sample/target/wasm32-unknown-unknown/{{ target }}/component_sample.wasm ./x64/{{ target }}/component_sample.aot

check target=default-target:
cargo check --profile={{ if target == "debug" {"dev"} else { target } }}
Expand All @@ -72,6 +72,9 @@ fmt:
cd src/wasm_runtime && cargo +nightly fmt -v --all
cd src/hyperlight_wasm_macro && cargo +nightly fmt -v --all

export CC_x86_64_unknown_none:= if os() == "windows" { justfile_directory() / "src/wasm_runtime/guest-toolchain/clang" } else { "" }
export AR_x86_64_unknown_none:= if os() == "windows" { "llvm-ar" } else { "" }

clippy target=default-target: (check target)
cargo clippy --profile={{ if target == "debug" {"dev"} else { target } }} --all-targets --all-features -- -D warnings
cd src/rust_wasm_samples && cargo clippy --profile={{ if target == "debug" {"dev"} else { target } }} --all-targets --all-features -- -D warnings
Expand Down
8 changes: 8 additions & 0 deletions src/hyperlight_wasm/Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,11 @@ name = "helloworld"
path = "examples/helloworld/main.rs"
test = true

[[example]]
name = "guest-debugging"
path = "examples/guest-debugging/main.rs"
test = true

[[example]]
name = "hostfuncs"
path = "examples/hostfuncs/main.rs"
Expand All @@ -52,6 +57,7 @@ tracing = "0.1.27"
log = "0.4.28"
cfg-if = { version = "1" }
metrics = "0.24.2"
env_logger = "0.11.8"

[target.'cfg(windows)'.dependencies]
windows = { version = "0.62", features = ["Win32_System_Threading"] }
Expand All @@ -68,6 +74,7 @@ metrics-util = "0.20.0"
metrics-exporter-prometheus = "0.17"

[build-dependencies]
cfg_aliases = "0.2.1"
chrono = "0.4"
blake3 = "1.8"
built = { version = "0.8.0", features = ["chrono", "git2"] }
Expand All @@ -81,6 +88,7 @@ function_call_metrics = ["hyperlight-host/function_call_metrics"]
seccomp = ["hyperlight-host/seccomp"]
print_debug = ["hyperlight-host/print_debug"]
crashdump = ["hyperlight-host/crashdump"]
gdb = ["hyperlight-host/gdb"]
kvm = ["hyperlight-host/kvm"]
mshv2 = ["hyperlight-host/mshv2"]
mshv3 = ["hyperlight-host/mshv3"]
Expand Down
14 changes: 13 additions & 1 deletion src/hyperlight_wasm/build.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -125,7 +125,7 @@ fn build_wasm_runtime() -> PathBuf {
env_vars.retain(|(key, _)| !key.starts_with("CARGO_"));

let mut cargo_cmd = std::process::Command::new(&cargo_bin);
let cmd = cargo_cmd
let mut cmd = cargo_cmd
.arg("build")
.arg("--profile")
.arg(cargo_profile)
Expand All @@ -134,9 +134,17 @@ fn build_wasm_runtime() -> PathBuf {
.arg(&target_dir)
.current_dir(&in_repo_dir)
.env_clear()
// On windows when `gdb` features is enabled this is not set correctly
.env("CFLAGS_x86_64_unknown_none", "-fPIC")
.envs(env_vars)
.env("PATH", path_with(&toolchain_dir))
.env("HYPERLIGHT_GUEST_TOOLCHAIN_ROOT", &toolchain_dir);

// Add --features gdb if the gdb feature is enabled for this build script
if std::env::var("CARGO_FEATURE_GDB").is_ok() {
cmd = cmd.arg("--features").arg("gdb");
}

let status = cmd
.status()
.unwrap_or_else(|e| panic!("could not run cargo build wasm_runtime: {}", e));
Expand Down Expand Up @@ -239,5 +247,9 @@ fn main() -> Result<()> {

println!("cargo:rerun-if-changed=build.rs");

cfg_aliases::cfg_aliases! {
gdb: { all(feature = "gdb", debug_assertions) },
}

Ok(())
}
Loading