Setting up a development environment

The following instructions will describe how to set up a development environment for testing Uhyve against an upstream version of the Hermit kernel beyond the example and test kernels that can be found in Uhyve's repository.

This guide assumes some familiarity with Git and basic skills with Unix shells (such as commands like cd or ln).

Cloning Hermit repositories

Using Git, we will clone two repositories: Uhyve and hermit-rs.

git clone https://github.com/hermit-os/uhyve.git
git clone https://github.com/hermit-os/hermit-rs --recursive-submodules -j8

hermit-rs and the kernel

The hermit-rs contains many examples of Rust application that can be compiled into a unikernel using Hermit. Although not all of them are guaranteed to work with Uhyve, many of them do - they may be useful on top of the kernels that Uhyve ships with in binary form (under data/x86_64) or in its own tests (under tests/test-kernels). The repository is also very easy to expand and serves as a good first stepping stone, particularly if you have never compiled an application using Hermit before.

These examples expect a copy of the kernel to be present in hermit-rs's repository root. hermit-rs ships with a submodule of the Hermit kernel. It is fetched alongside with hermit-rs thanks to the --recursive-submodules parameter used above, but, in case you forgot to use it earlier, it can also be fetched using git submodule update --init --recursive inside of the hermit-rs directory.

Compiling kernels locally

The Uhyve repository ships with a couple of test kernels used for integration testing in tests/test-kernels. Although it is not required to compile them "by hand" for the tests to work (as cargo test takes care of everything for us), you can try compiling them using the following command:

cargo build -Zbuild-std=std,panic_abort --target x86_64-unknown-hermit

You should be able to run those kernels with Uhyve:

uhyve tests/test-kernels/target/x86_64-unknown-hermit/debug/create_file
uhyve tests/test-kernels/target/x86_64-unknown-hermit/debug/serial

The Cargo Book provides additional explanations on Cargo Targets and build-std.

Testing Hermit apps using cargo run

As mentioned above, the Uhyve repository ships some binaries that can be used for testing purposes.

cargo run -- data/x86_64/rusty_demo
cargo run -- data/x86_64/hello_world
cargo run -- data/x86_64/hello_c

Debugging Hermit apps

Basic support of (single-core) applications is already integrated into Uhyve.

By specifying variable HERMIT_GDB_PORT=port, Uhyve is working as gdbserver and is waiting on port port for a connection to a gdb. For instance, with the following command Uhyve is waiting on port 6677 for a connection.

HERMIT_GDB_PORT=6677 uhyve /path_to_the_unikernel/hello_world

In principle, every gdb-capable IDE should be able to debug Hermit applications. (Eclipse, VSCode, ...)

Visual Studio Code / VSCodium / Eclipse Theia

The repository hermit-rs provides example configuration files to debug a Hermit application with Visual Studio Code, VSCodium or derivatives of Eclipse Theia.