{"id":18440772,"url":"https://github.com/hermit-os/hermit-playground","last_synced_at":"2025-04-07T22:31:51.289Z","repository":{"id":40560809,"uuid":"192162607","full_name":"hermit-os/hermit-playground","owner":"hermit-os","description":"A playground to build C/C++/Go/Fortran applications on top of RustyHermit","archived":false,"fork":false,"pushed_at":"2024-07-03T15:49:42.000Z","size":45083,"stargazers_count":34,"open_issues_count":6,"forks_count":13,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-03-17T11:58:22.183Z","etag":null,"topics":["cloud-computing","high-performance-computing","kernel","operating-system","unikernels","virtualization"],"latest_commit_sha":null,"homepage":"https://hermitcore.org","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hermit-os.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE-APACHE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-06-16T07:27:47.000Z","updated_at":"2025-03-12T11:48:34.000Z","dependencies_parsed_at":"2024-06-05T12:58:55.654Z","dependency_job_id":null,"html_url":"https://github.com/hermit-os/hermit-playground","commit_stats":null,"previous_names":["hermit-os/hermit-playground","hermitcore/hermit-playground"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hermit-os%2Fhermit-playground","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hermit-os%2Fhermit-playground/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hermit-os%2Fhermit-playground/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hermit-os%2Fhermit-playground/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hermit-os","download_url":"https://codeload.github.com/hermit-os/hermit-playground/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247740989,"owners_count":20988312,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cloud-computing","high-performance-computing","kernel","operating-system","unikernels","virtualization"],"created_at":"2024-11-06T06:33:01.712Z","updated_at":"2025-04-07T22:31:46.273Z","avatar_url":"https://github.com/hermit-os.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cimg width=\"100\" align=\"right\" src=\"img/hermitcore_logo.png\" /\u003e\n\n\n# HermitCore-rs - A Rust-based, lightweight unikernel for a scalable and predictable runtime behavior\n\n[![Build Status](https://git.rwth-aachen.de/acs/public/hermit-os/hermit-playground/badges/master/pipeline.svg)](https://git.rwth-aachen.de/acs/public/hermit-os/hermit-playground/pipelines)\n[![Slack Status](https://matrix.osbyexample.com:3008/badge.svg)](https://matrix.osbyexample.com:3008)\n\n[HermitCore]( http://www.hermit-os.org ) is a new\n[unikernel](http://unikernel.org) targeting a scalable and predictable runtime\nfor high-performance and cloud computing.\nWe decided to develop a new version of the kernel in [Rust](https://www.rust-lang.org) .\nWe promise that this will make it easier to maintain and extend our kernel.\nAll code beside the kernel can still be developed in your preferred language (C/C++/Go/Fortran).\nIf you want to develope pure Rust applications, please look into [RustyHermit](https://github.com/hermit-os/libhermit-rs).\n\nThis repository contains the Rust-based playground for C/C++/Go/Fortran applications.\nCurrently, it isn't stable and does not support all features of the [C-based version](https://github.com/hermit-os/libhermit) and runs only in our own hypervisor.\n\n## Requirements\n\nThe build process works currently only on **x86-based Linux** systems. To build\nthe HermitCore-rs kernel and applications you need:\n\n * CMake\n * Recent host compiler such as GCC\n * HermitCore cross-toolchain, i.e. Binutils, GCC, newlib, pthreads\n * [Rust compiler (nightly release)](https://www.rust-lang.org/en-US/install.html)\n * Rust source code for cross-compiling, which can be installed with `rustup component add rust-src`.\n\n### HermitCore-rs cross-toolchain\n\nWe provide a Docker container with all required tools to build HermitCore-rs applications.\n\nTo test the toolchain, create a simple C program (e.g. `hello world`) and name the file `main.c`.\nUse following command to build the applications:\n\n```bash\n$ docker run -v $PWD:/volume -w /volume --rm -t ghcr.io/hermit-os/hermit-toolchain:latest x86_64-hermit-gcc -o main main.c\n```\n\nThe command mounts the current directory as working directory into a docker container and runs the cross-compiler to build the application.\nAfterwards, you will find the executable `main` in your current directory.\n\nIf you want to build the toolchain yourself, have a look at the `path2rs` branch of the repository\n[hermit-toolchain](https://github.com/hermit-os/hermit-toolchain).\nIt contains scripts to build the whole toolchain for HermitCore-rs.\n\n## Building\n\n### Preliminary work\n\nAs a first step, the repository and its submodules have to be cloned:\n\n```bash\n$ git clone --recursive https://github.com/hermit-os/hermit-playground.git\n$ cd hermit-playground\n```\n\n### Building the library operating systems and its examples\n\nTo build the Rust-based kernel and its examples, go to the directory with the source code\nand issue the following commands:\n\n```bash\n$ mkdir build\n$ cd build\n$ cmake ..\n$ make\n$ sudo make install\n```\n\nIf your toolchain is not located in `/opt/hermit/bin` then you have to supply\nits location to the `cmake` command above like so:\n\n```bash\n$ cmake -DTOOLCHAIN_BIN_DIR=/home/user/hermit/bin ..\n```\n\nAssuming that binaries like `x86_64-hermit-gcc` and friends are located in that\ndirectory.\nTo install your new version in the same directory, you have to set the installation path and install HermitCore-rs as follows:\n\n```bash\n$ cmake -DTOOLCHAIN_BIN_DIR=/home/user/hermit/bin -DCMAKE_INSTALL_PREFIX=/home/user/hermit ..\n$ make\n$ make install\n```\n\n**Note:** If you use the cross compiler outside of this repository, it uses the library operating system located\nby the toolchain (e.g. `/opt/hermit/x86_64-hermit/lib/libhermit.a`).\n\n## Uhyve - A lightweight hypervisor\n\nPart of HermitCore is a small hypervisor, which is called *uhyve*.\nThis tool helps to start HermitCore applications within a KVM-accelerated virtual machine.\nIn principle it is a bridge to the Linux system.\nIf the uyhve is registered as loader to the Linux system, HermitCore applications can be started like common Linux applications.\n*uhyve* can be registered with the following command:\n\n```bash\n$ sudo -c sh 'echo \":hermit:M:7:\\\\x42::/opt/hermit/bin/uhyve:\" \u003e /proc/sys/fs/binfmt_misc/register'\n```\n\nApplications can then be directly called like:\n```bash\n$ /opt/hermit/x86_64-hermit/extra/tests/hello\n```\n\nOtherwise, *uhyve* must be started directly and needs the path to the HermitCore application as an argument:\n```bash\n$ /opt/hermit/bin/uhyve /opt/hermit/x86_64-hermit/extra/tests/hello\n```\n\nAfterwards, the *uhyve* starts the HermitCore application within a VM.\n\n## Testing\n\nHermitCore applications can be directly started as a standalone kernel within a\nvirtual machine:\n\n```bash\n$ cd build\n$ make install DESTDIR=~/hermit-build\n$ cd ~/hermit-build/opt/hermit\n$ bin/uhyve x86_64-hermit/extra/tests/hello\n```\n\nThe application will be started within our thin\nhypervisor powered by Linux's KVM API and therefore requires *KVM* support.\nIn principle, it is an extension of [ukvm](https://www.usenix.org/sites/default/files/conference/protected-files/hotcloud16_slides_williams.pdf).\n\nThe environment variable `HERMIT_CPUS` specifies the number of\nCPUs (and no longer a range of core ids). Furthermore, the variable `HERMIT_MEM`\ndefines the memory size of the virtual machine. The suffixes *M* and *G* can be\nused to specify a value in megabytes or gigabytes respectively. By default, the\nloader initializes a system with one core and 2 GiB RAM.\nFor instance, the following command starts the stream benchmark in a virtual machine, which\nhas 4 cores and 6GB memory:\n\n```bash\n$ HERMIT_CPUS=4 HERMIT_MEM=6G bin/uhyve x86_64-hermit/extra/benchmarks/stream\n```\n\nTo enable an Ethernet device for `uhyve`, we have to setup a tap device on the\nhost system. For instance, the following command establishes the tap device\n`tap100` on Linux:\n\n```bash\n$ sudo ip tuntap add tap100 mode tap\n$ sudo ip addr add 10.0.5.1/24 broadcast 10.0.5.255 dev tap100\n$ sudo ip link set dev tap100 up\n$ sudo bash -c 'echo 1 \u003e /proc/sys/net/ipv4/conf/tap100/proxy_arp'\n```\n\nBy default, `uhyve`'s network interface uses `10.0.5.2`as IP address, `10.0.5.1`\nfor the gateway and `255.255.255.0` as network mask.\nThe default configuration can be overwritten by the environment variables\n`HERMIT_IP`, `HERMIT_GATEWAY` and `HERMIT_MASk`.\nTo enable the device, `HERMIT_NETIF` must be set to the name of the tap device.\nFor instance, the following command starts an HermitCore application within `uhyve`\nand enables the network support:\n\n```bash\n$ HERMIT_IP=\"10.0.5.3\" HERMIT_GATEWAY=\"10.0.5.1\" HERMIT_MASK=\"255.255.255.0\" HERMIT_NETIF=tap100 bin/uhyve x86_64-hermit/extra/tests/hello\n```\n\n## Building your own HermitCore applications\n\nYou can take `usr/tests` as a starting point to build your own applications. All\nthat is required is that you include\n`[...]/HermitCore/cmake/HermitCore-Application.cmake` in the first line of your application's\n`CMakeLists.txt`. It doesn't have to reside inside the HermitCore repository.\nOther than that, it should behave like normal CMake.\n\n## Tips\n\n### Dumping the kernel log\n\nBy setting the environment variable `HERMIT_VERBOSE` to `1`, *uhyve* prints\nthe kernel log messages to the screen at termination.\n\n## Missing features\n(might be comming)\n* Multikernel support\n* Running baremetal/without hypervisor\n\n## Credits\n\nHermitCore's Emoji is provided for free by [EmojiOne](https://www.gfxmag.com/crab-emoji-vector-icon/).\n\n## License\n\nLicensed under either of\n\n * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)\n * MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)\n\nat your option.\n\n### Contribution\n\nUnless 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.\n\nHermitCore-rs is being developed on [GitHub](https://github.com/hermit-os/hermit-playground\t).\nCreate your own fork, send us a pull request, and chat with us on [Slack](https://radiant-ridge-95061.herokuapp.com)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhermit-os%2Fhermit-playground","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhermit-os%2Fhermit-playground","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhermit-os%2Fhermit-playground/lists"}