Awesome
IncludeOS Hello World
A basic example to demonstrate the open source unikernel project - IncludeOS.
IncludeOS is built with nix. Before building the example
you need a working nix-installation. To speed up the build process, we also
recommend having ccache enabled installed, but this is
not a requirement. To use ccache, add --arg withCcache true
to the nix commands below.
The source code for the example is in ./src/main.cpp
. It prints "Hello world" and calls shutdown:
$ cat ./src/main.cpp
#include <iostream>
#include <os>
int main(){
std::cout << "Hello world\n";
os::shutdown();
}
The following steps let you build and boot this example with IncludeOS.
$ nix-build
This will download and build the latest IncludeOS libraries and their
dependencies and build the hello-world
service. The final binary will be
called hello.bin.elf
in ./result/bin
.
$ ls ./result/bin
hello.elf.bin
To boot the unikernel you need to add a bootloader or use the IncludeOS
chainloader. The separate tool
vmrunner, can be used to automatically
manage this. QEMU and vmrunner
is already configured in shell.nix
.
To boot the unikernel, run
$ nix-shell --command "boot ./result/bin/hello.elf.bin"
[...]
ELF 32-bit LSB executable, Intel 80386, version 1 (SYSV), statically linked, stripped
SeaBIOS (version rel-1.16.3-0-ga6ed6b701f0a-prebuilt.qemu.org)
iPXE (http://ipxe.org) 00:03.0 CA00 PCI2.10 PnP PMM+06FD0E60+06F30E60 CA00
Press Ctrl-B to configure iPXE (PCI 00:03.0)...
Booting from ROM..* Multiboot begin: 0x9500
* Multiboot cmdline @ 0x29d02e: /nix/store/jd9dhri62mz7lm5mld58c7c1wn2dsnbx-chainloader-static-i686-unknown-linux-musl-dev/bin/chainloader ""
* Multiboot end: 0x29d09c
* Module list @ 0x29d000
* Module @ 0x29e000
* Args: ./result/bin/hello.elf.bin ""
* End: 0x43d6c0
* Multiboot end: 0x43d6c0
* ELF syms header CRC OK
<Multiboot>Booted with multiboot
* Boot flags: 0x24f
* Valid memory (130559 Kib):
0x00000000 - 0x0009fbff (639 Kib)
0x00100000 - 0x07fdffff (129920 Kib)
* Booted with parameters @ 0x29d02e: /nix/store/jd9dhri62mz7lm5mld58c7c1wn2dsnbx-chainloader-static-i686-unknown-linux-musl-dev/bin/chainloader ""
* Multiboot provided memory map (7 entries @ 0x9000)
0x0000000000 - 0x000009fbff FREE (639 Kb.)
0x000009fc00 - 0x000009ffff RESERVED (1 Kb.)
0x00000f0000 - 0x00000fffff RESERVED (64 Kb.)
0x0000100000 - 0x0007fdffff FREE (129920 Kb.)
0x0007fe0000 - 0x0007ffffff RESERVED (128 Kb.)
0x00fffc0000 - 0x00ffffffff RESERVED (256 Kb.)
0x0000000000 - 0x00ffffffff RESERVED (0 Kb.)
<Multiboot>OS loaded with 1 modules
* ./result/bin/hello.elf.bin "" @ 0x29e000 - 0x43d6c0, size: 1701568b
* Multiboot begin: 0x9500
* Multiboot end: 0x3e59c0
[x86_64 PC] constructor
[ Machine ] Initializing heap
[ Machine ] Main memory detected as 129998656 b
[ Machine ] Reserving 1048576 b for machine use
<Multiboot>Booted with multiboot
* Boot flags: 0x24f
* Valid memory (130559 Kib):
0x00000000 - 0x0009fbff (639 Kib)
0x00100000 - 0x07fdffff (129920 Kib)
* Booted with parameters @ 0x8000: ./result/bin/hello.elf.bin ""
* Multiboot provided memory map (7 entries @ 0x9000)
0x0000000000 - 0x000009fbff FREE (639 Kb.)
0x000009fc00 - 0x000009ffff RESERVED (1 Kb.)
0x00000f0000 - 0x00000fffff RESERVED (64 Kb.)
0x0000100000 - 0x0007fdffff FREE (129920 Kb.)
0x0007fe0000 - 0x0007ffffff RESERVED (128 Kb.)
0x00fffc0000 - 0x00ffffffff RESERVED (256 Kb.)
0xfd00000000 - 0xffffffffff RESERVED (12582912 Kb.)
================================================================================
IncludeOS VERY_DIRTY (x86_64 / 64-bit)
+--> Running [ Hello world - OS included ]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+--> WARNING: No good random source found: RDRAND/RDSEED instructions not available.
+--> To make this warning fatal, re-compile with FOR_PRODUCTION=ON.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Hello world
[ main ] returned with status 0
[ Kernel ] Stopping service
[ Kernel ] Powering off
[ SUCCESS ] process exited
You can also use shell.nix
to rebuild and boot the unikernel during
development, without having to invoke nix-shell
every time. Just run
nix-shell
and follow the instructions:
$ nix-shell
To build the hello_world unikernel:
cmake src/CMakeLists.txt -B ./build
cd ./build
make
boot ./hello.elf.bin
For more details on how to develop with IncludeOS see the main repository.