[RustyHermit](http://www.hermitcore.org) is a [unikernel](http://unikernel.org) targeting a scalable and predictable runtime for high-performance and cloud computing.
[RustyHermit](https://github.com/hermitcore/rusty-hermit) is a [unikernel](http://unikernel.org) targeting a scalable and predictable runtime for high-performance and cloud computing.
Unikernel means, you bundle your application directly with the kernel library, so that it can run without any installed operating system.
This reduces overhead, therefore, interesting applications include virtual machines and high-performance computing.
The RustyHermit can run Rust applications, as well as C/C++/Go/Fortran applications.
A tutorial on how to use these programming languages on top of RustyHermit is published at [https://github.com/hermitcore/hermit-playground](https://github.com/hermitcore/hermit-playground).
_libhermit-rs_ is the heart of RustyHermit and is the kernel itself.
The kernel is able to run Rust applications, as well as C/C++/Go/Fortran applications.
A tutorial on how to use these programming languages on top of _libhermit-rs_ is published at [https://github.com/hermitcore/hermit-playground](https://github.com/hermitcore/hermit-playground).
## Background
HermitCore was a research unikernel developed at [RWTH-Aachen](https://www.rwth-aachen.de) written in C ([libhermit](https://github.com/hermitcore/libhermit)).
**RustyHermit** is a rewrite of HermitCorewritten in [Rust](https://www.rust-lang.org).
Today, the kernel is completly rewritten in [Rust](https://www.rust-lang.org).
The ownership model of Rust guarantees memory/thread-safety and enables us to eliminate many classes of bugs at compile-time.
Consequently, the use of Rust for kernel development promises less vulnerabilities in comparison to common programming languages.
The kernel and the integration into the Rust runtime is entirely written in Rust and does not use any C/C++ Code.
We extend the Rust toolchain so that the build process is similar to Rust's usual workflow.
Rust applications that do not bypass the Rust runtime and directly use OS services are able to run on RustyHermit without modifications.
## Running an Application in RustyHermit
### Prerequisites
## Prerequisites
The Rust toolchain can be installed from the [official webpage](https://www.rust-lang.org/).
RusyHermit currently requires the **nightly versions** of the toolchain.
...
...
@@ -36,179 +31,42 @@ RusyHermit currently requires the **nightly versions** of the toolchain.
rustup default nightly
```
Further requirements are the source code of the Rust runtime, [cargo-download](https://crates.io/crates/cargo-download), and llvm-tools:
Further requirements are the source code of the Rust runtime, and llvm-tools:
```sh
cargo install cargo-download
rustup component add rust-src
rustup component add llvm-tools-preview
```
### Sample Application
First, create a new cargo project:
```sh
cargo new hello_world
cd hello_world
```
To bind the library operating system to the application, add the crate [hermit-sys](https://crates,io/crates/hermit-sys) to the dependencies in the file *Cargo.toml*.
It is important to use at least the optimization level 1.
Consequently, it is required to **extend***Cargo.toml* with following lines:
```toml
# Cargo.toml
[target.'cfg(target_os = "hermit")'.dependencies]
hermit-sys="0.1.*"
[profile.release]
opt-level=3
[profile.dev]
opt-level=1
```
To link the application with RustyHermit, declare `hermit_sys` an `external crate` in the main file of your application.
```rust
// src/main.rs
#[cfg(target_os="hermit")]
externcratehermit_sys;
fnmain(){
println!("Hello World!");
}
```
The final step is building the application as follows:
The resulting "hypervisor-ready" binary then can be found in `target/x86_64-unknown-hermit/debug/hermit-new`
## Running RustyHermit
### Using uhyve as Hypervisor
RustyHermit can run within our own hypervisor [*uhyve*](https://github.com/hermitcore/uhyve) , which requires [KVM](https://www.linux-kvm.org/) to create a virtual machine.
Please install the hypervisor as follows:
```sh
cargo install uhyve
```
Afterwards, your are able to start RustyHermit applications within our hypervisor:
It is important to enable the processor features _fsgsbase_ and _rdtscp_ because it is a prerequisite to boot RustyHermit.
You can provide arguments to the application via the kernel commandline, which you can set with qemu's `-append` option. Since both the kernel and the application can have parameters, they are separated with `--`:
The Kernel has rudimentary support for the virtio-fs shared file system. Currently only files, no folders are supported. To use it, you have to run a virtio-fs daemon and start qemu as described in [Standalone virtio-fs usage](https://virtio-fs.gitlab.io/howto-qemu.html):
The resulting library then can be found in `target/x86_64-unknown-hermit-kernel/debug/`
* Multikernel support (might be comming)
* Virtio support (comming soon)
* Network support (comming soon)
* Hardware Boot
## Controlling the number of kernel messages
## Troubleshooting
_libhermit-rs_ uses the lightweight logging crate [log](https://github.com/rust-lang/log) to print kernel messages.
If the environment variable `HERMIT_LOG_LEVEL_FILTER` is set at compile time to a string matching the name of a [LevelFilter](https://docs.rs/log/0.4.8/log/enum.LevelFilter.html), then that value is used for the LevelFilter.
If the environment variable is not set, or the name doesn't match, then LevelFilter::Info is used by default, which is the same as it was before.
### command failed with the error message `linker `rust-lld` not found`
The path to the *llvm-tools* is not set.
On Linux, it is typically installed at *${HOME}/.rustup/toolchains/nightly-x86_64-unknown-linux-gnu/lib/rustlib/x86_64-unknown-linux-gnu/bin*.
RustyHermit is derived from following tutorials and software distributions:
_libhermit-rs_ is derived from following tutorials and software distributions:
1. Philipp Oppermann's [excellent series of blog posts][opp].
2. Erik Kidd's [toyos-rs][kidd], which is an extension of Philipp Opermann's kernel.
...
...
@@ -233,5 +91,5 @@ at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
RustyHermit is being developed on [GitHub](https://github.com/hermitcore/libhermit-rs).
libhermit-rs is being developed on [GitHub](https://github.com/hermitcore/libhermit-rs).
Create your own fork, send us a pull request, and chat with us on [Slack](https://radiant-ridge-95061.herokuapp.com)
