README.md 4.29 KB
Newer Older
Steffen Vogel's avatar
Steffen Vogel committed
1
2
<img width="100" align="right" src="img/hermitcore_logo.png" />

3
# libhermit-rs - A Rust-based library operting system
Stefan Lankes's avatar
Stefan Lankes committed
4

Stefan Lankes's avatar
Stefan Lankes committed
5
[![Build Status](https://travis-ci.com/hermitcore/libhermit-rs.svg?branch=master)](https://travis-ci.com/hermitcore/libhermit-rs)
Stefan Lankes's avatar
Stefan Lankes committed
6
![Actions Status](https://github.com/hermitcore/libhermit-rs/workflows/Build/badge.svg)
Stefan Lankes's avatar
Stefan Lankes committed
7
[![Documentation](https://img.shields.io/badge/docs-latest-blue.svg)](https://hermitcore.github.io/libhermit-rs/hermit/)
Stefan Lankes's avatar
Stefan Lankes committed
8
[![License](https://img.shields.io/crates/l/rusty-hermit.svg)](https://img.shields.io/crates/l/rusty-hermit.svg)
Stefan Lankes's avatar
Stefan Lankes committed
9
[![Slack Status](https://radiant-ridge-95061.herokuapp.com/badge.svg)](https://radiant-ridge-95061.herokuapp.com)
Stefan Lankes's avatar
Stefan Lankes committed
10

11
[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.
Jonathan Klimt's avatar
Jonathan Klimt committed
12
Unikernel means, you bundle your application directly with the kernel library, so that it can run without any installed operating system.
James Daab's avatar
James Daab committed
13
This reduces overhead, therefore, interesting applications include virtual machines and high-performance computing.
14

15
_libhermit-rs_ is the heart of RustyHermit and is the kernel itself.
Stefan Lankes's avatar
Stefan Lankes committed
16
The kernel is able to run [Rust](https://github.com/hermitcore/hermit-playground) applications, as well as [C/C++/Go/Fortran](https://github.com/hermitcore/rusty-hermit) applications.
Stefan Lankes's avatar
Stefan Lankes committed
17

18
## Prerequisites
Jonathan Klimt's avatar
Jonathan Klimt committed
19

20
21
The Rust toolchain can be installed from the [official webpage](https://www.rust-lang.org/).
RusyHermit currently requires the **nightly versions** of the toolchain.
Jonathan Klimt's avatar
Jonathan Klimt committed
22
23
24
```sh
rustup default nightly
```
25

26
Further requirements are the source code of the Rust runtime, and llvm-tools:
27
28
29
30
31
32

```sh
rustup component add rust-src
rustup component add llvm-tools-preview
```

33
## Building the kernel as static library
34

35
36
37
38
The kernel will be linked as static library to C/C++ or Rust applications.
In case of Rust, the crate [hermit-sys](https://github.com/hermitcore/rusty-hermit) automate this process.
For C/C++ applications a modified [C/C++ compiler](https://github.com/hermitcore/hermit-playground) has to be used.
To build the kernel as static library and to link afterwards by its own to the applicatiom, please use following build command:
39
40

```sh
41
cargo build -Z build-std=core,alloc,panic_abort --target x86_64-unknown-hermit-kernel
42
43
```

44
The resulting library then can be found in `target/x86_64-unknown-hermit-kernel/debug/`
45

Stefan Lankes's avatar
Stefan Lankes committed
46

47
## Controlling the number of kernel messages
48

49
50
51
_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.
52

53
For instance, the following command build RustyHermit with debug messages:
54
55

```sh
56
$ HERMIT_LOG_LEVEL_FILTER=Debug cargo build -Z build-std=core,alloc,panic_abort --target x86_64-unknown-hermit-kernel
57
58
```

Stefan Lankes's avatar
Stefan Lankes committed
59

Stefan Lankes's avatar
Stefan Lankes committed
60
## Credits
Stefan Lankes's avatar
Stefan Lankes committed
61

62
_libhermit-rs_ is derived from following tutorials and software distributions:
63
64
65

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.
66
3. The Rust-based teaching operating system [eduOS-rs][eduos].
67
68
69
70
71

[opp]: http://blog.phil-opp.com/
[kidd]: http://www.randomhacks.net/bare-metal-rust/
[eduos]: http://rwth-os.github.io/eduOS-rs/

72
HermitCore's Emoji is provided for free by [EmojiOne](https://www.gfxmag.com/crab-emoji-vector-icon/).
73
74
75
76
77

## License

Licensed under either of

Jens Breitbart's avatar
Jens Breitbart committed
78
79
* Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
* MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
80
81
82

at your option.

Jens Breitbart's avatar
Jens Breitbart committed
83
## Contribution
84
85
86

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.

87
libhermit-rs is being developed on [GitHub](https://github.com/hermitcore/libhermit-rs).
88
Create your own fork, send us a pull request, and chat with us on [Slack](https://radiant-ridge-95061.herokuapp.com)