Justfile

import 'c.just'

set windows-shell := ["pwsh.exe", "-NoLogo", "-Command"]
set dotenv-load := true

set-env-command := if os() == "windows" { "$env:" } else { "export " }
bin-suffix := if os() == "windows" { ".bat" } else { ".sh" }
nightly-toolchain := "nightly-2026-09-22"
# Pinned cargo-hyperlight version used to build the guest sysroot. Keep this in
# lockstep with the version pinned in flake.nix.
cargo-hyperlight-version := "0.1.14"

################
### cross-rs ###
################
target-triple := env('TARGET_TRIPLE', "")
docker := if target-triple != "" { require("docker") } else { "" }
# this command is only used host side not for guests
# include the --target-dir for the cross builds.  This ensures that the builds are separated and avoid any conflicts with the guest builds
cargo-cmd := if target-triple != "" { require("cross") } else { "cargo" } 
target-triple-flag := if target-triple != "" { "--target " + target-triple + " --target-dir ./target/host"} else { "" }
# set up cross to use the devices
kvm-gid := if path_exists("/dev/kvm") == "true" { `getent group kvm | cut -d: -f3` } else { "" }
export CROSS_CONTAINER_OPTS := if path_exists("/dev/kvm") == "true" { "--device=/dev/kvm" } else if path_exists("/dev/mshv") == "true" { "--device=/dev/mshv" } else { "" }
export CROSS_CONTAINER_GID := if path_exists("/dev/kvm") == "true" { kvm-gid } else {"1000"} # required to have ownership of the mapped in device on kvm

root := justfile_directory()

default-target := "debug"
hyperlight-target-arch := env("HYPERLIGHT_TARGET", arch())
hyperlight-target := if hyperlight-target-arch == "x86_64" { "x86_64-hyperlight-none" } else if hyperlight-target-arch == "aarch64" { "aarch64-hyperlight-none" } else { error("Unsupported architecture: " + arch()) }
# All three guest crates share one workspace under src/tests/rust_guests,
# so they share one target dir and hyperlight-libc / hyperlight-guest-bin
# get compiled once per profile instead of once per crate.
rust_guests_target := "src/tests/rust_guests/target/" + hyperlight-target
simpleguest_source := rust_guests_target
dummyguest_source := rust_guests_target
witguest_source := rust_guests_target
rust_guests_bin_dir := "src/tests/rust_guests/bin"

################
### BUILDING ###
################
alias b := build
alias rg := build-and-move-rust-guests
alias cg := build-and-move-c-guests

# build host library
build target=default-target:
    {{ cargo-cmd }} build --profile={{ if target == "debug" { "dev" } else { target } }} {{ target-triple-flag }}

# build testing guest binaries
guests: build-and-move-rust-guests build-and-move-rust-guests-non-pie build-and-move-c-guests

# Ensure the pinned cargo-hyperlight is installed. We compare the *actual*
# installed binary's reported version instead of relying on `cargo install`
# alone: on persistent/self-hosted CI runners a stale binary can survive while
# cargo's metadata still claims the pinned version is present, silently skipping
# the upgrade (this is how the broken 0.1.5 `--build-plan` binary kept running).
# When the version doesn't match we force a reinstall to the pinned version.
ensure-cargo-hyperlight:
    {{ if os() == "windows" { "if (-not ((cargo hyperlight --version 2>$null) -like '*" + cargo-hyperlight-version + "*')) { cargo install --locked --force --version " + cargo-hyperlight-version + " cargo-hyperlight }" } else { "cargo hyperlight --version 2>/dev/null | grep -qF '" + cargo-hyperlight-version + "' || cargo install --locked --force --version " + cargo-hyperlight-version + " cargo-hyperlight" } }}

build-rust-guests target=default-target features="": (ensure-cargo-hyperlight)
    @# --workspace unifies feature resolution so shared deps build once. Needed because witguest
    @# pulls bindgen via hyperlight-component-macro, which would otherwise turn on extra features
    @# on libc's build.rs host deps and force a libc rebuild. simple/dummyguest don't hit this.
    cd src/tests/rust_guests && cargo hyperlight build --workspace {{ if features =="" {''} else if features=="no-default-features" {"--no-default-features" } else {"--no-default-features -F " + features } }} --profile={{ if target == "debug" { "dev" } else { target } }}

@move-rust-guests target=default-target:
    cp {{ simpleguest_source }}/{{ target }}/simpleguest* {{ rust_guests_bin_dir }}/{{ target }}/
    cp {{ dummyguest_source }}/{{ target }}/dummyguest* {{ rust_guests_bin_dir }}/{{ target }}/
    cp {{ witguest_source }}/{{ target }}/witguest* {{ rust_guests_bin_dir }}/{{ target }}/

build-and-move-rust-guests: (build-rust-guests "debug") (move-rust-guests "debug") (build-rust-guests "release") (move-rust-guests "release")
build-and-move-c-guests: (build-c-guests "debug") (move-c-guests "debug") (build-c-guests "release") (move-c-guests "release")

# Build non-PIE variants of rust guests for testing ELF VA mapping.
# Phase 1 builds the sysroot without RUSTFLAGS (avoids RUSTFLAGS leaking
# into the sysroot wrapper build in cargo-hyperlight).
# Phase 2 uses plain cargo with --sysroot and non-PIE link flags.
build-rust-guests-non-pie target=default-target: (ensure-cargo-hyperlight)
    cd src/tests/rust_guests/simpleguest && cargo hyperlight build --target-dir ../target-non-pie --profile={{ if target == "debug" { "dev" } else { target } }}
    {{ if os() == "windows" { "$env:RUSTC_BOOTSTRAP=1; $env:RUSTFLAGS='--sysroot=' + (Resolve-Path src/tests/rust_guests/target-non-pie/sysroot).Path + ' -C relocation-model=static -C link-args=--no-pie -C link-args=--image-base=0x1000000 --cfg=hyperlight --check-cfg=cfg(hyperlight) -Clink-args=-eentrypoint';" } else { "" } }} cd src/tests/rust_guests/simpleguest && {{ if os() == "windows" { "" } else { "RUSTC_BOOTSTRAP=1 RUSTFLAGS=\"--sysroot=$(cd .. && pwd)/target-non-pie/sysroot -C relocation-model=static -C link-args=--no-pie -C link-args=--image-base=0x1000000 --cfg=hyperlight --check-cfg=cfg(hyperlight) -Clink-args=-eentrypoint\"" } }} cargo build --target {{ hyperlight-target }} --target-dir ../target-non-pie/build --profile={{ if target == "debug" { "dev" } else { target } }}

non_pie_guests_target := "src/tests/rust_guests/target-non-pie/build/" + hyperlight-target

@move-rust-guests-non-pie target=default-target:
    {{ if os() == "windows" { "New-Item -ItemType Directory -Path " + rust_guests_bin_dir + "/" + target + "/non_pie -Force | Out-Null" } else { "mkdir -p " + rust_guests_bin_dir + "/" + target + "/non_pie" } }}
    cp {{ non_pie_guests_target }}/{{ target }}/simpleguest {{ rust_guests_bin_dir }}/{{ target }}/non_pie/

build-and-move-rust-guests-non-pie: (build-rust-guests-non-pie "debug") (move-rust-guests-non-pie "debug") (build-rust-guests-non-pie "release") (move-rust-guests-non-pie "release")

clean: clean-rust

clean-rust: 
    cargo clean
    cd src/tests/rust_guests && cargo clean
    {{ if os() == "windows" { "Remove-Item src/tests/rust_guests/witguest/*.wasm -Force -ErrorAction SilentlyContinue" } else { "rm -f src/tests/rust_guests/witguest/*.wasm" } }}
    git clean -fdx src/tests/c_guests/bin src/tests/rust_guests/bin

################
### TESTING ####
################

# Note: most testing recipes take an optional "features" comma separated list argument. If provided, these will be passed to cargo as **THE ONLY FEATURES**, i.e. default features will be disabled.

# convenience recipe to run all tests with the given target and features (similar to CI)
test-like-ci config=default-target hypervisor="kvm":
    @# verify the local platforms golden. Fill target/snapshot-goldens first with
    @# `just snapshot-goldens-pull` or `just snapshot-goldens-generate`.
    just snapshot-goldens-verify {{config}}

    @# with default features
    just test {{config}}

    @# with only one driver enabled + build-metadata
    just test {{config}} build-metadata,{{ if hypervisor == "mshv3" {"mshv3"} else {"kvm"} }}

    @# with hw-interrupts enabled (+ explicit driver on Linux)
    {{ if os() == "linux" { if hypervisor == "mshv3" { "just test " + config + " mshv3,hw-interrupts" } else { "just test " + config + " kvm,hw-interrupts" } } else { "just test " + config + " hw-interrupts" } }}

    @# no-surrogate mode smoke tests (Windows/WHP only)
    {{ if os() == "windows" { "just test-no-surrogate " + config } else { "" } }}

    @# make sure certain cargo features compile
    just check

    @# without any driver (should fail to compile)
    just test-compilation-no-default-features {{config}}

    @# test the crashdump feature
    {{ set-env-command }}RUST_LOG='debug'; just test-rust-crashdump {{config}}

    @# test the tracing related features
    {{ if os() == "linux" { "RUST_LOG=debug just test-rust-tracing " + config + " " + if hypervisor == "mshv3" { "mshv3" } else { "kvm" } } else { "" } }}

code-checks-like-ci config=default-target hypervisor="kvm":
    @# Ensure up-to-date Cargo.lock
    cargo fetch --locked
    cargo fetch --manifest-path src/tests/rust_guests/Cargo.toml --locked

    @# fmt
    just fmt-check

    @# clippy
    {{ if os() == "windows" { "just clippy " + config } else { "" } }}
    {{ if os() == "windows" { "just clippy-guests " + config } else { "" } }}

    @# clippy exhaustive check
    {{ if os() == "linux" { "just clippy-exhaustive " + config } else { "" } }}

    @# Verify MSRV
    ./dev/verify-msrv.sh hyperlight-common hyperlight-guest hyperlight-guest-bin hyperlight-host hyperlight-component-util hyperlight-component-macro hyperlight-guest-tracing

    @# Check cargo features compile
    just check

    @# Check compilation with no default features
    just test-compilation-no-default-features debug
    just test-compilation-no-default-features release

build-guests-like-ci config=default-target:
    @# Build and move Rust guests
    just build-rust-guests {{config}}
    just move-rust-guests {{config}}
    just build-rust-guests-non-pie {{config}}
    just move-rust-guests-non-pie {{config}}

    @# Build c guests
    just build-c-guests {{config}}
    just move-c-guests {{config}}

build-test-like-ci config=default-target hypervisor="kvm":
    @# Build
    just build {{config}}

    @# Run Miri tests
    {{ if os() == "linux" { "just miri-tests" } else { "" } }}

    @# Run Rust tests
    just test {{config}}

    @# Run Rust tests with single driver
    {{ if os() == "linux" { "just test " + config+ " " + if hypervisor == "mshv3" { "mshv3" } else { "kvm" } } else { "" } }}

    @# Run Rust tests with hw-interrupts
    {{ if os() == "linux" { if hypervisor == "mshv3" { "just test " + config + " mshv3,hw-interrupts" } else { "just test " + config + " kvm,hw-interrupts" } } else { "just test " + config + " hw-interrupts" } }}

    @# Run Rust Gdb tests
    {{ set-env-command }}RUST_LOG='debug'; just test-rust-gdb-debugging {{config}}

    @# Run Rust Crashdump tests
    {{ set-env-command }}RUST_LOG='debug'; just test-rust-crashdump {{config}}

    @# Run Rust Tracing tests
    {{ if os() == "linux" { "RUST_LOG=debug just test-rust-tracing " + config } else { "" } }}

run-examples-like-ci config=default-target hypervisor="kvm":
    @# Run Rust examples - Windows
    {{ if os() == "windows" { "just run-rust-examples " + config } else { "" } }}

    @# Run Rust examples - linux
    {{ if os() == "linux" { "just run-rust-examples-linux " + config + " " } else { "" } }}

benchmarks-like-ci config=default-target hypervisor="kvm":
    @# Run benchmarks
    {{ if config == "release" { "just bench-ci main" } else { "" } }}

fuzz-like-ci target config=default-target hypervisor="kvm":
    @# Run Fuzzing
    # Use a much shorter time limit (1 vs 300 seconds), because the
    # local version of this step is mostly intended just for making
    # sure that the fuzz harnesses compile
    {{ if config == "release" { "just fuzz-timed " + target + " 1" } else { "" } }}

like-ci config=default-target hypervisor="kvm":
    @# .github/workflows/dep_code_checks.yml
    just code-checks-like-ci {{config}} {{hypervisor}}

    @# .github/workflows/dep_build_guests.yml
    just build-guests-like-ci {{config}}

    @# .github/workflows/dep_build_test.yml
    just build-test-like-ci {{config}} {{hypervisor}}

    @# .github/workflows/dep_run_examples.yml
    just run-examples-like-ci {{config}} {{hypervisor}}

    @# .github/workflows/dep_benchmarks.yml
    just benchmarks-like-ci {{config}} {{hypervisor}}

    @# .github/workflows/dep_fuzzing.yml
    just fuzz-like-ci fuzz_host_print {{config}} {{hypervisor}}
    just fuzz-like-ci fuzz_guest_call {{config}} {{hypervisor}}
    just fuzz-like-ci fuzz_host_call {{config}} {{hypervisor}}
    just fuzz-like-ci fuzz_guest_estimate_trace_event {{config}} {{hypervisor}}
    just fuzz-like-ci fuzz_guest_trace {{config}} {{hypervisor}}
    just fuzz-like-ci fuzz_virtq_malformed {{config}} {{hypervisor}}
    just fuzz-like-ci fuzz_virtq_roundtrip {{config}} {{hypervisor}}

    @# spelling
    typos

    @# license-headers
    just check-license-headers

# runs all tests
test target=default-target features="": (test-unit target features) (test-isolated target features) (test-integration target features) (test-doc target features) (test-tools target)

# runs the tests of the tools this repository builds for itself, which sit
# outside the default members the other recipes select
test-tools target=default-target:
    {{ cargo-cmd }} test -p hyperlight-ci --profile={{ if target == "debug" { "dev" } else { target } }} {{ target-triple-flag }}

# runs unit tests
test-unit target=default-target features="":
    {{ cargo-cmd }} test {{ if features =="" {''} else if features=="no-default-features" {"--no-default-features" } else {"--no-default-features -F " + features } }} --profile={{ if target == "debug" { "dev" } else { target } }} {{ target-triple-flag }} --lib

# runs loom concurrency tests
test-loom:
    {{ set-env-command }}RUSTFLAGS='--cfg loom'; {{ cargo-cmd }} test --quiet -p hyperlight-common --lib {{ target-triple-flag }} virtq::concurrency::

# runs tests that requires being run separately, for example due to global state
test-isolated target=default-target features="" :
    {{ cargo-cmd }} test {{ if features =="" {''} else if features=="no-default-features" {"--no-default-features" } else {"--no-default-features -F " + features } }} --profile={{ if target == "debug" { "dev" } else { target } }} {{ target-triple-flag }} -p hyperlight-host --lib -- sandbox::uninitialized::tests::test_log_trace --exact --ignored
    {{ cargo-cmd }} test {{ if features =="" {''} else if features=="no-default-features" {"--no-default-features" } else {"--no-default-features -F " + features } }} --profile={{ if target == "debug" { "dev" } else { target } }} {{ target-triple-flag }} -p hyperlight-host --lib -- sandbox::outb::tests::test_log_emit_guest_log --exact --ignored
    {{ cargo-cmd }} test {{ if features =="" {''} else if features=="no-default-features" {"--no-default-features" } else {"--no-default-features -F " + features } }} --profile={{ if target == "debug" { "dev" } else { target } }} {{ target-triple-flag }} -p hyperlight-host --lib -- sandbox::initialized::tests::from_snapshot::max_guest_log_level_is_honored_from_snapshot --exact --ignored
    {{ cargo-cmd }} test {{ if features =="" {''} else if features=="no-default-features" {"--no-default-features" } else {"--no-default-features -F " + features } }} --profile={{ if target == "debug" { "dev" } else { target } }} {{ target-triple-flag }} -p hyperlight-host --lib -- sandbox::initialized::tests::from_snapshot::max_guest_log_level_overrides_initialized_snapshot --exact --ignored
    {{ cargo-cmd }} test {{ if features =="" {''} else if features=="no-default-features" {"--no-default-features" } else {"--no-default-features -F " + features } }} --profile={{ if target == "debug" { "dev" } else { target } }} {{ target-triple-flag }} -p hyperlight-host --lib -- sandbox::initialized::tests::from_snapshot::max_guest_log_level_setter_survives_restore --exact --ignored
    {{ cargo-cmd }} test {{ if features =="" {''} else if features=="no-default-features" {"--no-default-features" } else {"--no-default-features -F " + features } }} --profile={{ if target == "debug" { "dev" } else { target } }} {{ target-triple-flag }} -p hyperlight-host --lib -- sandbox::initialized::tests::from_snapshot::max_guest_log_level_can_be_disabled_and_reenabled --exact --ignored
    {{ cargo-cmd }} test {{ if features =="" {''} else if features=="no-default-features" {"--no-default-features" } else {"--no-default-features -F " + features } }} --profile={{ if target == "debug" { "dev" } else { target } }} {{ target-triple-flag }} -p hyperlight-host --lib -- sandbox::initialized::tests::from_snapshot::max_guest_log_level_can_be_enabled_after_off_init --exact --ignored
    {{ cargo-cmd }} test {{ if features =="" {''} else if features=="no-default-features" {"--no-default-features" } else {"--no-default-features -F " + features } }} --profile={{ if target == "debug" { "dev" } else { target } }} {{ target-triple-flag }} -p hyperlight-host --test integration_test -- log_message --exact --ignored
    @# CPU vendor check, gated to known CI runner hardware
    {{ cargo-cmd }} test {{ if features =="" {''} else if features=="no-default-features" {"--no-default-features" } else {"--no-default-features -F " + features } }} --profile={{ if target == "debug" { "dev" } else { target } }} {{ target-triple-flag }} -p hyperlight-host --lib -- sandbox::snapshot::file::config::tests::cpu_vendor_current_is_recognized --exact --ignored
    @# Slow host-dependent MSR audit. Run once per x86_64 CI profile.
    {{ if features == "" { if hyperlight-target-arch == "x86_64" { cargo-cmd + " test --profile=" + (if target == "debug" { "dev" } else { target }) + " " + target-triple-flag + " -p hyperlight-host --lib -- sandbox::initialized::tests::msr_tests::test_no_msr_leaks_across_restore_full_window_sweep --exact --ignored --nocapture" } else { "" } } else { "" } }}
    @# LAPIC-enabled MSHV can expose additional MSRs. Audit it once in debug.
    {{ if features == "mshv3,hw-interrupts" { if target == "debug" { if hyperlight-target-arch == "x86_64" { cargo-cmd + " test --no-default-features -F mshv3,hw-interrupts --profile=dev " + target-triple-flag + " -p hyperlight-host --lib -- sandbox::initialized::tests::msr_tests::test_no_msr_leaks_across_restore_full_window_sweep --exact --ignored --nocapture" } else { "" } } else { "" } } else { "" } }}
    @# metrics tests
    {{ cargo-cmd }} test {{ if features =="" {''} else if features=="no-default-features" {"--no-default-features" } else {"--no-default-features -F function_call_metrics," + features } }} --profile={{ if target == "debug" { "dev" } else { target } }} {{ target-triple-flag }} -p hyperlight-host --lib -- metrics::tests::test_metrics_are_emitted --exact

# runs integration tests
test-integration target=default-target features="":
    @# run execute_on_heap test with feature "executable_heap" on (runs with off during normal tests)
    {{ cargo-cmd }} test {{ if features =="" {"--features executable_heap"} else if features=="no-default-features" {"--no-default-features --features executable_heap"} else {"--no-default-features -F executable_heap," + features } }} --profile={{ if target == "debug" { "dev" } else { target } }} {{ target-triple-flag }} --test integration_test execute_on_heap

    @# run component-util integration tests that exercise WIT input codegen
    {{ cargo-cmd }} test -p hyperlight-component-util --profile={{ if target == "debug" { "dev" } else { target } }} {{ target-triple-flag }} --test wasmtime_guest_codegen

    @# run the rest of the integration tests. `snapshot_goldens` is in
    @# the glob but no-ops without a mode token, so it needs no golden
    @# cache here. It verifies in its own step (see the snapshot-goldens
    @# recipes).
    {{ cargo-cmd }} test -p hyperlight-host {{ if features =="" {''} else if features=="no-default-features" {"--no-default-features" } else {"--no-default-features -F " + features } }} --profile={{ if target == "debug" { "dev" } else { target } }} {{ target-triple-flag }} --test '*'

# tests compilation with no default features on different platforms
test-compilation-no-default-features target=default-target:
    @# Linux should fail without a hypervisor feature (kvm or mshv3)
    {{ if os() == "linux" { "! " + cargo-cmd + " check -p hyperlight-host --no-default-features "+target-triple-flag+" 2> /dev/null" } else { "" } }}
    @# Windows should succeed even without default features
    {{ if os() == "windows" { cargo-cmd + " check -p hyperlight-host --no-default-features" } else { "" } }}
    @# Linux should succeed with a hypervisor driver but without default features
    {{ if os() == "linux" { cargo-cmd + " check -p hyperlight-host --no-default-features --features kvm" } else { "" } }}  {{ target-triple-flag }}
    {{ if os() == "linux" { cargo-cmd + " check -p hyperlight-host --no-default-features --features mshv3" } else { "" } }}  {{ target-triple-flag }}

# runs a subset of existing tests with HYPERLIGHT_MAX_SURROGATES=0 (Windows only).
# Covers guest calls, host callbacks, virtqueue buffers and errors,
# in-memory snapshot/restore, and save/load from disk.
# No-surrogate mode permits only one live VM per process, so tests run serially.
# NOTE: if any of the test names below are renamed, update both this
# recipe AND the matching CI step in .github/workflows/dep_build_test.yml.
test-no-surrogate target=default-target:
    {{ set-env-command }}HYPERLIGHT_MAX_SURROGATES=0; {{ set-env-command }}HYPERLIGHT_INITIAL_SURROGATES=0; {{ cargo-cmd }} test -p hyperlight-host --profile={{ if target == "debug" { "dev" } else { target } }} --lib -- no_surrogate_tests --test-threads=1
    {{ set-env-command }}HYPERLIGHT_MAX_SURROGATES=0; {{ set-env-command }}HYPERLIGHT_INITIAL_SURROGATES=0; {{ cargo-cmd }} test -p hyperlight-host --profile={{ if target == "debug" { "dev" } else { target } }} --test integration_test -- guest_malloc guest_panic --test-threads=1
    {{ set-env-command }}HYPERLIGHT_MAX_SURROGATES=0; {{ set-env-command }}HYPERLIGHT_INITIAL_SURROGATES=0; {{ cargo-cmd }} test -p hyperlight-host --profile={{ if target == "debug" { "dev" } else { target } }} --test sandbox_host_tests -- --exact callback_test float_roundtrip guest_external_bytes_round_trip_and_retention oversized_host_response_returns_transport_error --test-threads=1
    {{ set-env-command }}HYPERLIGHT_MAX_SURROGATES=0; {{ set-env-command }}HYPERLIGHT_INITIAL_SURROGATES=0; {{ cargo-cmd }} test -p hyperlight-host --profile={{ if target == "debug" { "dev" } else { target } }} --lib -- snapshot_evolve_restore_handles_state_correctly restore_from_loaded_snapshot --test-threads=1

# runs tests that exercise gdb debugging
test-rust-gdb-debugging target=default-target features="":
    {{ cargo-cmd }} test --profile={{ if target == "debug" { "dev" } else { target } }}  {{ target-triple-flag }} --example guest-debugging {{ if features =="" {'--features gdb'} else { "--features gdb," + features } }}
    {{ cargo-cmd }} test --profile={{ if target == "debug" { "dev" } else { target } }}  {{ target-triple-flag }} -p hyperlight-host --lib {{ if features =="" {'--features gdb'} else { "--features gdb," + features } }} -- hypervisor::gdb::

# rust test for crashdump
test-rust-crashdump target=default-target features="":
    {{ cargo-cmd }} test --profile={{ if target == "debug" { "dev" } else { target } }}  {{ target-triple-flag }} {{ if features =="" {'--features crashdump'} else { "--features crashdump," + features } }} -- test_crashdump
    {{ cargo-cmd }} test --profile={{ if target == "debug" { "dev" } else { target } }}  {{ target-triple-flag }} --example crashdump {{ if features =="" {'--features crashdump'} else { "--features crashdump," + features } }}

# rust test for tracing
test-rust-tracing target=default-target features="":
    # Run tests for the tracing guest and macro
    {{ cargo-cmd }} test -p hyperlight-guest-tracing -F trace --profile={{ if target == "debug" { "dev" } else { target } }} {{ target-triple-flag }}
    {{ cargo-cmd }} test -p hyperlight-common -F trace_guest --profile={{ if target == "debug" { "dev" } else { target } }} {{ target-triple-flag }}
    {{ cargo-cmd }} test -p hyperlight-host --profile={{ if target == "debug" { "dev" } else { target } }} {{ if features =="" {'--features trace_guest'} else { "--features trace_guest," + features } }} {{ target-triple-flag }}

test-doc target=default-target features="":
    {{ cargo-cmd }} test --profile={{ if target == "debug" { "dev" } else { target } }} {{ target-triple-flag }} {{ if features =="" {''} else { "--features " + features } }} --doc

# Nextest runs one Miri process per job, each with its own interpreter, so
# memory grows with the job count at roughly 0.4GB per job. Lower MIRI_JOBS on
# a machine with many cores but little RAM.
miri-jobs := env('MIRI_JOBS', num_cpus())

ensure-cargo-nextest:
    {{ if os() == "windows" { "if (-not (cargo nextest --version 2>$null)) { cargo install --locked cargo-nextest }" } else { "cargo nextest --version >/dev/null 2>&1 || cargo install --locked cargo-nextest" } }}

# The pinned nightly and Miri, which a runner carries only if its image does
ensure-nightly-miri:
    rustup toolchain list | grep -q '^{{nightly-toolchain}}' || rustup toolchain install {{nightly-toolchain}}
    rustup +{{nightly-toolchain}} component list | grep -q 'miri.*installed' || rustup component add miri --toolchain {{nightly-toolchain}}

miri-tests: (ensure-cargo-nextest) (ensure-nightly-miri)
    @# A Miri interpreter is single-threaded, so libtest's --test-threads cannot
    @# use more than one core. Nextest spawns one Miri process per test.
    # We can add more as needed
    cargo +{{nightly-toolchain}} miri nextest run -p hyperlight-common -F trace_guest -j {{miri-jobs}}
    cargo +{{nightly-toolchain}} miri nextest run -p hyperlight-host --lib -E 'test(/mem::shared_mem::tests/)' -j {{miri-jobs}}

################
### LINTING ####
################

check:
    {{ cargo-cmd }} check  {{ target-triple-flag }}
    {{ cargo-cmd }} check -p hyperlight-host --features crashdump  {{ target-triple-flag }}
    {{ cargo-cmd }} check -p hyperlight-host --features print_debug  {{ target-triple-flag }}
    {{ cargo-cmd }} check -p hyperlight-host --features gdb  {{ target-triple-flag }}
    {{ cargo-cmd }} check -p hyperlight-host --features trace_guest,mem_profile  {{ target-triple-flag }}
    {{ cargo-cmd }} check -p hyperlight-host --features hw-interrupts  {{ target-triple-flag }}
    {{ cargo-cmd }} check -p hyperlight-host --features executable_heap  {{ target-triple-flag }}

fmt-check: (ensure-nightly-fmt)
    cargo +{{nightly-toolchain}} fmt --all -- --check
    cargo +{{nightly-toolchain}} fmt --manifest-path src/tests/rust_guests/Cargo.toml --all -- --check
    cargo +{{nightly-toolchain}} fmt --manifest-path src/hyperlight_guest_capi/Cargo.toml -- --check

[private]
ensure-nightly-fmt:
    {{ if os() == "windows" { "if (-not (rustup +"+nightly-toolchain+" component list | Select-String 'rustfmt.*installed')) { rustup component add rustfmt --toolchain "+nightly-toolchain+" }" } else { "rustup +"+nightly-toolchain+" component list | grep -q 'rustfmt.*installed' || rustup component add rustfmt --toolchain "+nightly-toolchain } }}

check-license-headers:
    ./dev/check-license-headers.sh

fmt-apply: (ensure-nightly-fmt)
    cargo +{{nightly-toolchain}} fmt --all
    cargo +{{nightly-toolchain}} fmt --manifest-path src/tests/rust_guests/Cargo.toml --all
    cargo +{{nightly-toolchain}} fmt --manifest-path src/hyperlight_guest_capi/Cargo.toml

clippy target=default-target:
    {{ cargo-cmd }} clippy --all-targets {{ if hyperlight-target-arch == "x86_64" { "--all-features" } else { "" } }} --profile={{ if target == "debug" { "dev" } else { target } }}  {{ target-triple-flag }} -- -D warnings
    {{ cargo-cmd }} clippy -p hyperlight-ci --all-targets --profile={{ if target == "debug" { "dev" } else { target } }} {{ target-triple-flag }} -- -D warnings

# for use on a linux host-machine when cross-compiling to windows. Uses the windows-gnu which should be sufficient for most purposes
clippyw target=default-target:
    {{ cargo-cmd }} clippy --all-targets --all-features --target x86_64-pc-windows-gnu --profile={{ if target == "debug" { "dev" } else { target } }}  -- -D warnings

clippy-guests target=default-target: (ensure-cargo-hyperlight)
    cd src/tests/rust_guests && cargo hyperlight clippy --workspace --profile={{ if target == "debug" { "dev" } else { target } }} -- -D warnings

clippy-apply-fix-unix:
    cargo clippy --fix --all 

clippy-apply-fix-windows:
    cargo clippy --target x86_64-pc-windows-msvc --fix --all 

# Run clippy with feature combinations for all packages
clippy-exhaustive target=default-target:
    ./hack/clippy-package-features.sh hyperlight-host {{ target }} {{ target-triple }}
    ./hack/clippy-package-features.sh hyperlight-ci {{ target }} {{ target-triple }}
    ./hack/clippy-package-features.sh hyperlight-guest {{ target }} 
    ./hack/clippy-package-features.sh hyperlight-guest-bin {{ target }}
    ./hack/clippy-package-features.sh hyperlight-guest-macro {{ target }}
    ./hack/clippy-package-features.sh hyperlight-common {{ target }} {{ target-triple }}
    ./hack/clippy-package-features.sh hyperlight-testing {{ target }} {{ target-triple }}
    ./hack/clippy-package-features.sh hyperlight-component-macro  {{ target }} {{ target-triple }}
    ./hack/clippy-package-features.sh hyperlight-component-util {{ target }} {{ target-triple }}
    {{ if hyperlight-target-arch == "x86_64" { "./hack/clippy-package-features.sh hyperlight-guest-tracing " + target } else { "" } }}
    just clippy-guests {{ target }}

# Test a specific package with all feature combinations
clippy-package package target=default-target:
    ./hack/clippy-package-features.sh {{ package }} {{ target }}

# Verify Minimum Supported Rust Version
verify-msrv:
    ./dev/verify-msrv.sh hyperlight-common hyperlight-guest hyperlight-guest-bin hyperlight-host hyperlight-component-util hyperlight-component-macro hyperlight-guest-tracing

#####################
### RUST EXAMPLES ###
#####################

run-rust-examples target=default-target features="":
    {{ cargo-cmd }} run --profile={{ if target == "debug" { "dev" } else { target } }}  {{ target-triple-flag }} --example metrics {{ if features =="" {''} else { "--features " + features } }}
    {{ cargo-cmd }} run --profile={{ if target == "debug" { "dev" } else { target } }}  {{ target-triple-flag }} --example metrics {{ if features =="" {"--features function_call_metrics"} else {"--features function_call_metrics," + features} }}
    {{ cargo-cmd }} run --profile={{ if target == "debug" { "dev" } else { target } }}  {{ target-triple-flag }} --example logging {{ if features =="" {''} else { "--features " + features } }}

# The two tracing examples are flaky on windows so we run them on linux only for now, need to figure out why as they run fine locally on windows
run-rust-examples-linux target=default-target features="": (run-rust-examples target features)
    {{ cargo-cmd }} run --profile={{ if target == "debug" { "dev" } else { target } }}   {{ target-triple-flag }} --example tracing {{ if features =="" {''} else { "--features " + features } }}
    {{ cargo-cmd }} run --profile={{ if target == "debug" { "dev" } else { target } }}   {{ target-triple-flag }}  --example tracing {{ if features =="" {"--features function_call_metrics" } else {"--features function_call_metrics," + features} }}
    {{ cargo-cmd }} run --profile={{ if target == "debug" { "dev" } else { target } }}   {{ target-triple-flag }} --example crashdump {{ if features =="" {'--features crashdump'} else { "--features crashdump," + features } }}


#########################
### ARTIFACT CREATION ###
#########################

tar-headers: (build-rust-capi) # build-rust-capi is a dependency because we need the hyperlight_guest.h to be built
    tar -zcvf include.tar.gz -C {{root}}/target/sysroot/ include -C {{root}}/src/hyperlight_guest_capi include

tar-static-lib: (build-rust-capi "release") (build-rust-capi "debug")
    tar -zcvf hyperlight-guest-c-api-linux.tar.gz -C {{root}}/target/x86_64-hyperlight-none/ release/libhyperlight_guest_capi.a -C {{root}}/target/x86_64-hyperlight-none/ debug/libhyperlight_guest_capi.a

# Create release notes for the given tag. The expected format is a v-prefixed version number, e.g. v0.2.0
# For prereleases, the version should be "dev-latest"
@create-release-notes tag:
    echo "## What's Changed"
    ./dev/extract-changelog.sh {{ if tag == "dev-latest" { "Prerelease" } else { tag } }}
    gh api repos/{owner}/{repo}/releases/generate-notes -f tag_name={{ tag }} | jq -r '.body' | sed '1,/## What'"'"'s Changed/d'

####################
### BENCHMARKING ###
####################

# Warning: compares to and then OVERWRITES the given baseline
bench-ci baseline features="":
    cargo ci bench {{ if features == "" {''} else { "--features " + features } }} --verbose --save-baseline {{ baseline }}

# Measure a commit and the current tree on this machine, and compare them
bench-against commit guests features="":
    cargo ci bench {{ if features == "" {''} else { "--features " + features } }} --baseline-ref {{ commit }} --baseline-guests {{ guests }} --verbose

bench features="":
    cargo ci bench {{ if features == "" {''} else { "--features " + features } }} --verbose

###############
### FUZZING ###
###############

# Enough memory (4GB) for the fuzzer to run for 5 hours, with address sanitizer turned on
fuzz_memory_limit := "4096"

# Fuzzes the given target
# Uses *case* for compatibility to determine if the target is a tracing fuzzer or not
fuzz fuzz-target:
    case "{{ fuzz-target }}" in *trace*) just fuzz-trace {{ fuzz-target }} ;; *) cargo +{{nightly-toolchain}} fuzz run {{ fuzz-target }} --release -- -rss_limit_mb={{ fuzz_memory_limit }} ;; esac

# Fuzzes the given target. Stops after `max_time` seconds
# Uses *case* for compatibility to determine if the target is a tracing fuzzer or not
fuzz-timed fuzz-target max_time:
    case "{{ fuzz-target }}" in *trace*) just fuzz-trace-timed {{ max_time }} {{ fuzz-target }} ;; *) cargo +{{nightly-toolchain}} fuzz run {{ fuzz-target }} --release -- -rss_limit_mb={{ fuzz_memory_limit }} -max_total_time={{ max_time }} ;; esac

# Minimises the corpus of the given target to the smallest set preserving coverage
# Uses *case* for compatibility to determine if the target is a tracing fuzzer or not
fuzz-cmin fuzz-target:
    case "{{ fuzz-target }}" in *trace*) just fuzz-trace-cmin {{ fuzz-target }} ;; *) cargo +nightly fuzz cmin {{ fuzz-target }} --release -- -rss_limit_mb={{ fuzz_memory_limit }} ;; esac

# Builds fuzzers for submission to external fuzzing services
build-fuzzers: (build-fuzzer "fuzz_guest_call") (build-fuzzer "fuzz_host_call") (build-fuzzer "fuzz_host_print")

# Builds the given fuzzer
build-fuzzer fuzz-target:
    cargo +{{nightly-toolchain}} fuzz build {{ fuzz-target }}

# Fuzzes the guest with tracing enabled
fuzz-trace fuzz-target="fuzz_guest_trace":
    # We need to build the trace guest with the trace feature enabled
    just build-rust-guests release trace_guest
    just move-rust-guests release
    RUST_LOG="trace,hyperlight_guest=trace,hyperlight_guest_bin=trace" cargo +{{nightly-toolchain}} fuzz run {{ fuzz-target }} --features trace --release -- -rss_limit_mb={{ fuzz_memory_limit }}
    # Rebuild the trace guest without the trace feature to avoid affecting other tests
    just build-rust-guests release
    just move-rust-guests release

# Fuzzes the guest with tracing enabled. Stops after `max_time` seconds
fuzz-trace-timed max_time fuzz-target="fuzz_guest_trace":
    # We need to build the trace guest with the trace feature enabled
    just build-rust-guests release trace_guest
    just move-rust-guests release
    RUST_LOG="trace,hyperlight_guest=trace,hyperlight_guest_bin=trace" cargo +{{nightly-toolchain}} fuzz run {{ fuzz-target }} --features trace --release -- -rss_limit_mb={{ fuzz_memory_limit }} -max_total_time={{ max_time }}
    # Rebuild the trace guest without the trace feature to avoid affecting other tests
    just build-rust-guests release
    just move-rust-guests release

# Minimises the corpus of a tracing fuzzer
# cmin re-executes every input, so the trace guest must be in place for it
fuzz-trace-cmin fuzz-target="fuzz_guest_trace":
    # We need to build the trace guest with the trace feature enabled
    just build-rust-guests release trace_guest
    just move-rust-guests release
    RUST_LOG="trace,hyperlight_guest=trace,hyperlight_guest_bin=trace" cargo +nightly fuzz cmin {{ fuzz-target }} --features trace --release -- -rss_limit_mb={{ fuzz_memory_limit }}
    # Rebuild the trace guest without the trace feature to avoid affecting other tests
    just build-rust-guests release
    just move-rust-guests release

build-trace-fuzzers:
    cargo +{{nightly-toolchain}} fuzz build fuzz_guest_trace --features trace

####################
### COVERAGE #######
####################

# install cargo-llvm-cov if not already installed and ensure nightly toolchain + llvm-tools are available
ensure-cargo-llvm-cov:
    command -v cargo-llvm-cov >/dev/null 2>&1 || cargo install cargo-llvm-cov --locked
    rustup toolchain install {{nightly-toolchain}} 2>/dev/null
    rustup component add llvm-tools --toolchain {{nightly-toolchain}} 2>/dev/null

# host-side packages to collect coverage for (guest/no_std crates are excluded because they
# define #[panic_handler] and cannot be compiled for the host target under coverage instrumentation)
coverage-packages := "-p hyperlight-common -p hyperlight-host -p hyperlight-testing -p hyperlight-component-util -p hyperlight-component-macro"

# run all tests and examples with coverage instrumentation, collecting profdata without
# generating a report. Mirrors test-like-ci + run-examples-like-ci to exercise all code paths
# across all feature combinations. Uses nightly for branch coverage.
#
# Uses the show-env approach so that cargo produces separate binaries per feature combination.
# This avoids "mismatched data" warnings that occur when `cargo llvm-cov --no-report` recompiles
# a crate with different features, overwriting the previous binary and orphaning its profraw data.
#
# (run `just guests` first to build guest binaries)
coverage-run hypervisor="kvm": ensure-cargo-llvm-cov
    #!/usr/bin/env bash
    set -euo pipefail

    # Set up coverage instrumentation environment variables (RUSTFLAGS, LLVM_PROFILE_FILE, etc.)
    # and clean previous artifacts. All subsequent cargo commands inherit instrumentation.
    source <(cargo +{{nightly-toolchain}} llvm-cov show-env --export-prefix --branch)
    cargo +{{nightly-toolchain}} llvm-cov clean --workspace

    # tests with default features (all drivers; skip stress tests — too slow under instrumentation)
    cargo +{{nightly-toolchain}} test {{ coverage-packages }} --tests -- --skip stress_test

    # tests with single driver + build-metadata
    cargo +{{nightly-toolchain}} test {{ coverage-packages }} --no-default-features --features build-metadata,{{ if hypervisor == "mshv3" { "mshv3" } else { "kvm" } }} --tests -- --skip stress_test

    # isolated tests (require running separately due to global state)
    cargo +{{nightly-toolchain}} test -p hyperlight-host --lib -- sandbox::uninitialized::tests::test_log_trace --exact --ignored
    cargo +{{nightly-toolchain}} test -p hyperlight-host --lib -- sandbox::outb::tests::test_log_emit_guest_log --exact --ignored
    cargo +{{nightly-toolchain}} test -p hyperlight-host --lib -- sandbox::initialized::tests::from_snapshot::max_guest_log_level_is_honored_from_snapshot --exact --ignored
    cargo +{{nightly-toolchain}} test -p hyperlight-host --lib -- sandbox::initialized::tests::from_snapshot::max_guest_log_level_overrides_initialized_snapshot --exact --ignored
    cargo +{{nightly-toolchain}} test -p hyperlight-host --lib -- sandbox::initialized::tests::from_snapshot::max_guest_log_level_setter_survives_restore --exact --ignored
    cargo +{{nightly-toolchain}} test -p hyperlight-host --lib -- sandbox::initialized::tests::from_snapshot::max_guest_log_level_can_be_disabled_and_reenabled --exact --ignored
    cargo +{{nightly-toolchain}} test -p hyperlight-host --lib -- sandbox::initialized::tests::from_snapshot::max_guest_log_level_can_be_enabled_after_off_init --exact --ignored
    cargo +{{nightly-toolchain}} test -p hyperlight-host --test integration_test -- log_message --exact --ignored
    cargo +{{nightly-toolchain}} test -p hyperlight-host --no-default-features -F function_call_metrics,{{ if hypervisor == "mshv3" { "mshv3" } else { "kvm" } }} --lib -- metrics::tests::test_metrics_are_emitted --exact

    # integration test with executable_heap feature
    cargo +{{nightly-toolchain}} test {{ coverage-packages }} --no-default-features -F executable_heap,{{ if hypervisor == "mshv3" { "mshv3" } else { "kvm" } }} --test integration_test -- execute_on_heap

    # crashdump tests + example
    cargo +{{nightly-toolchain}} test {{ coverage-packages }} --no-default-features --features crashdump,{{ if hypervisor == "mshv3" { "mshv3" } else { "kvm" } }} --tests -- test_crashdump
    cargo +{{nightly-toolchain}} run --no-default-features --features crashdump,{{ if hypervisor == "mshv3" { "mshv3" } else { "kvm" } }} --example crashdump

    # tracing feature tests (host-side only; hyperlight-guest-tracing is no_std)
    cargo +{{nightly-toolchain}} test -p hyperlight-common --no-default-features --features trace_guest --tests -- --skip stress_test
    cargo +{{nightly-toolchain}} test -p hyperlight-host --no-default-features --features trace_guest,{{ if hypervisor == "mshv3" { "mshv3" } else { "kvm" } }} --tests -- --skip stress_test

    # examples: metrics, logging, tracing
    cargo +{{nightly-toolchain}} run --example metrics
    cargo +{{nightly-toolchain}} run --no-default-features -F function_call_metrics,{{ if hypervisor == "mshv3" { "mshv3" } else { "kvm" } }} --example metrics
    cargo +{{nightly-toolchain}} run --example logging
    cargo +{{nightly-toolchain}} run --example tracing
    cargo +{{nightly-toolchain}} run --no-default-features -F function_call_metrics,{{ if hypervisor == "mshv3" { "mshv3" } else { "kvm" } }} --example tracing
    cargo +{{nightly-toolchain}} test --no-default-features -F gdb,{{ if hypervisor == "mshv3" { "mshv3" } else { "kvm" } }} --example guest-debugging

# generate a text coverage summary to stdout
# for this to work you need to run `coverage-run hypervisor` beforehand
coverage hypervisor="kvm":
    #!/usr/bin/env bash
    set -euo pipefail
    source <(cargo +{{nightly-toolchain}} llvm-cov show-env --export-prefix --branch)
    cargo +{{nightly-toolchain}} llvm-cov report

# generate an HTML coverage report to target/coverage/html/
# for this to work you need to run `coverage-run hypervisor` beforehand
coverage-html hypervisor="kvm":
    #!/usr/bin/env bash
    set -euo pipefail
    source <(cargo +{{nightly-toolchain}} llvm-cov show-env --export-prefix --branch)
    cargo +{{nightly-toolchain}} llvm-cov report --html --output-dir target/coverage/html

# generate LCOV coverage output to target/coverage/lcov.info
# for this to work you need to run `coverage-run hypervisor` beforehand
coverage-lcov hypervisor="kvm":
    #!/usr/bin/env bash
    set -euo pipefail
    source <(cargo +{{nightly-toolchain}} llvm-cov show-env --export-prefix --branch)
    mkdir -p target/coverage
    cargo +{{nightly-toolchain}} llvm-cov report --lcov --output-path target/coverage/lcov.info

# generate all coverage reports for CI: HTML + LCOV + text summary.
# (run `just guests` first to build guest binaries)
coverage-ci hypervisor="kvm": (coverage-run hypervisor)
    #!/usr/bin/env bash
    set -euo pipefail
    source <(cargo +{{nightly-toolchain}} llvm-cov show-env --export-prefix --branch)
    mkdir -p target/coverage
    cargo +{{nightly-toolchain}} llvm-cov report --html --output-dir target/coverage/html
    cargo +{{nightly-toolchain}} llvm-cov report --lcov --output-path target/coverage/lcov.info
    cargo +{{nightly-toolchain}} llvm-cov report | tee target/coverage/summary.txt

###################
### FLATBUFFERS ###
###################

gen-all-fbs-rust-code:
    flatc --rust --rust-module-root-file --gen-all -o ./src/hyperlight_common/src/flatbuffers/ ./src/schema/all.fbs
    just fmt-apply

install-vcpkg:
    cd .. && git clone https://github.com/Microsoft/vcpkg.git || cd -
    cd ../vcpkg && ./bootstrap-vcpkg{{ bin-suffix }} && ./vcpkg integrate install || cd -

install-flatbuffers-with-vcpkg: install-vcpkg
    cd ../vcpkg && ./vcpkg install flatbuffers || cd -

###################################
### SNAPSHOT GOLDEN HELPERS     ###
###################################

default-snapshot-goldens-image := "ghcr.io/hyperlight-dev/hyperlight-snapshot-goldens"

# Check the local snapshots against the goldens for the current
# GOLDENS_VERSION. Run `snapshot-goldens-pull` first to fill the
# local directory. A missing entry fails the test. Each host checks
# only its own (arch, hypervisor, cpu vendor, profile) golden.
snapshot-goldens-verify target=default-target:
    cargo test {{ if target == "release" { "--release" } else { "" } }} \
        -p hyperlight-host --test snapshot_goldens -- verify

# Pull this host's goldens into the directory `snapshot-goldens-verify`
# reads. `all` (default) fetches the current version plus every
# `COMPAT_VERSIONS` major. `compat` fetches only the old majors, for
# regenerate runs where the registry has no current tag.
snapshot-goldens-pull target=default-target which="all" image=default-snapshot-goldens-image:
    #!/usr/bin/env bash
    set -euo pipefail
    if [[ -e /dev/mshv ]]; then hv=mshv
    elif [[ -e /dev/kvm ]]; then hv=kvm
    elif [[ "${OS:-}" == "Windows_NT" ]]; then hv=whp
    elif [[ "$(sysctl -n kern.hv_support)" == "1" ]]; then hv=hvf
    else echo "snapshot-goldens-pull: no hypervisor found" >&2; exit 1
    fi
    # Mirror of `CpuVendor::golden_tag` in file/config.rs. x86_64 reads
    # the cpuid vendor string. aarch64 has a single Apple vendor.
    case "$(uname -m)" in
        x86_64|amd64)
            arch=x86_64
            vendor=$(awk -F': ' '/^vendor_id/{print $2; exit}' /proc/cpuinfo)
            case "${vendor}" in
                GenuineIntel) cpu=intel ;;
                AuthenticAMD) cpu=amd ;;
                *) echo "snapshot-goldens-pull: unrecognized cpu vendor '${vendor}'" >&2; exit 1 ;;
            esac
            ;;
        aarch64|arm64) arch=aarch64; cpu=apple ;;
        *) echo "snapshot-goldens-pull: unsupported arch $(uname -m)" >&2; exit 1 ;;
    esac
    version_file=src/hyperlight_host/tests/snapshot_goldens/goldens_version.rs
    current=$(awk -F'"' '/GOLDENS_VERSION: &str =/{print $2; exit}' "${version_file}")
    # Old majors for backwards-compat verification. Mirror of
    # `COMPAT_VERSIONS` in goldens_version.rs.
    compat=$(grep -E 'COMPAT_VERSIONS.*=.*&\[' "${version_file}" | grep -oE 'v[0-9]+\.[0-9]+' || true)
    case "{{ which }}" in
        all) versions="${current} ${compat}" ;;
        compat) versions="${compat}" ;;
        *) echo "snapshot-goldens-pull: unknown which '{{ which }}' (expected all or compat)" >&2; exit 1 ;;
    esac
    # Mirror of `Platform::tag_for` in platform.rs. Keep both in sync.
    for version in ${versions}; do
        tag="${version}-${arch}-${hv}-${cpu}-{{ target }}"
        dir="target/snapshot-goldens/${tag}"
        mkdir -p "${dir}"
        oras cp --to-oci-layout "{{ image }}:${tag}" "${dir}:${tag}"
    done

# Build the local snapshots into the directory `snapshot-goldens-verify`
# reads. Run this then `snapshot-goldens-verify` to test the round trip
# on one host. Pass `out` to write the snapshots elsewhere.
snapshot-goldens-generate target=default-target out="":
    cargo test {{ if target == "release" { "--release" } else { "" } }} \
        -p hyperlight-host --test snapshot_goldens -- generate {{ out }}

# Generate this host's golden from the branch and place it where
# `snapshot-goldens-verify` reads. For when the registry has no
# published tag for the current version. Pull `COMPAT_VERSIONS`
# goldens separately to also verify backwards compat.
snapshot-goldens-regenerate target=default-target:
    #!/usr/bin/env bash
    set -euo pipefail
    out=$(mktemp -d)
    trap 'rm -rf "${out}"' EXIT
    just snapshot-goldens-generate {{ target }} "${out}"
    # generate writes exactly one {tag}/ layout into the clean dir.
    shopt -s nullglob
    layouts=("${out}"/*/)
    if [[ "${#layouts[@]}" -ne 1 ]]; then
        echo "snapshot-goldens-regenerate: expected one layout in ${out}, found ${#layouts[@]}" >&2
        exit 1
    fi
    layout="${layouts[0]%/}"
    tag="$(basename "${layout}")"
    dest="target/snapshot-goldens/${tag}"
    rm -rf "${dest}"
    mkdir -p target/snapshot-goldens
    cp -r "${layout}" "${dest}"

# Validate the regen-goldens label against the goldens state.
# has_label is true when a PR carries the label. The label is set
# when the current GOLDENS_VERSION was bumped and is not published.
# base_ref is the git ref to diff the version against.
snapshot-goldens-check-label has_label base_ref image=default-snapshot-goldens-image:
    #!/usr/bin/env bash
    set -euo pipefail
    version_file=src/hyperlight_host/tests/snapshot_goldens/goldens_version.rs
    parse_version() { awk -F'"' '/GOLDENS_VERSION: &str =/{print $2; exit}'; }
    version=$(parse_version < "${version_file}")
    published() { oras repo tags "{{ image }}" 2>/dev/null | grep -qxF "${1}-complete"; }
    if [[ "{{ has_label }}" == "true" ]]; then
        # Empty when absent on base_ref (file added or renamed here), read as a bump below.
        base_version=""
        git cat-file -e "{{ base_ref }}:${version_file}" 2>/dev/null && base_version=$(git show "{{ base_ref }}:${version_file}" | parse_version)
        if [[ "${version}" == "${base_version}" ]]; then
            echo "::error::regen-goldens is set but GOLDENS_VERSION is unchanged from {{ base_ref }} (${version}). A regen accompanies a version bump. Remove the label or bump the version." >&2
            exit 1
        fi
        if published "${version}"; then
            echo "::error::regen-goldens is set but goldens for ${version} are already published. Remove the label so CI verifies against the published goldens." >&2
            exit 1
        fi
        echo "snapshot-goldens-check-label: OK. ${version} bumped from ${base_version} and not yet published."
    else
        if ! published "${version}"; then
            echo "::error::goldens for ${version} are not published. Add the regen-goldens label, or run RegenSnapshotGoldens first." >&2
            exit 1
        fi
        echo "snapshot-goldens-check-label: OK. ${version} is published."
    fi