Build and run a C Hello program on Unikraft. Follow the instructions below to set up, configure, build and run C Hello. Make sure you installed the requirements.

For a quick setup, run the commands below. Note that you still need to install the requirements.

To build and run the application for x86_64, use the commands below:

test -d ../repos/unikraft || git clone https://github.com/unikraft/unikraft ../repos/unikraft
make distclean
echo -e 'CONFIG_PLAT_KVM=y\nCONFIG_PLAT_KVM_VMM_QEMU=y\nCONFIG_ARCH_X86_64=y' > /tmp/defconfig
UK_DEFCONFIG=/tmp/defconfig make defconfig
make -j $(nproc)
qemu-system-x86_64 -nographic -m 8 -cpu max -kernel out/c-hello_qemu-x86_64

This will configure, build and run the application, resulting in a Hello from Unikraft! message being printed.

To do the same for AArch64, run the commands below:

test -d ../repos/unikraft || git clone https://github.com/unikraft/unikraft ../repos/unikraft
make distclean
echo -e 'CONFIG_PLAT_KVM=y\nCONFIG_PLAT_KVM_VMM_QEMU=y\nCONFIG_ARCH_ARM_64=y' > /tmp/defconfig
UK_DEFCONFIG=/tmp/defconfig make defconfig
make -j $(nproc)
qemu-system-aarch64 -nographic -machine virt -m 8 -cpu max -kernel out/c-hello_qemu-arm64

Similar to the x86_64 build, this will result in a Hello from Unikraft! message being printed.

Information about every step and about other types of builds is detailed below.

Set up the unikraft repository. Clone it in ../repos/unikraft/ if not already cloned:

test -d ../repos/unikraft || git clone https://github.com/unikraft/unikraft ../repos/unikraft

If you want use a custom variant of the repository (e.g. apply your own patch, make modifications), update it accordingly in the ../repos/ directory.

While not strictly required, it is safest to clean the previous build artifacts:

make distclean

To configure the kernel, use:

make menuconfig

In the console menu interface, choose the target architecture (x86_64 or ARMv8 or ARMv7) and platform (Xen or KVM/QEMU or KVM/Firecracker).

The end result will be the creation of the .config configuration file.

Build the application for the current configuration:

make -j $(nproc)

This results in the creation of the out/ directory storing the build artifacts. The unikernel application image file is out/c-hello_<plat>-<arch>, where <plat> is the platform name (qemu, fc, xen), and <arch> is the architecture (x86_64 or arm64).

If you want to use a different compiler, such as a Clang or a different GCC version, pass the CC variable to make.

To build with Clang, use the commands below:

make properclean
make CC=clang -j $(nproc)

Note that Clang >= 14 is required to build Unikraft.

To build with another GCC version, use the commands below:

make properclean
make CC=gcc-<version> -j $(nproc)

where <version> is the GCC version, such as 11, 12.

Note that GCC >= 8 is required to build Unikraft.

Doing a new configuration, or a new build may require cleaning up the configuration and build artifacts.

In order to remove the build artifacts, use:

make clean

In order to remove fetched files also, that is the removal of the out/ directory, use:

make properclean

In order to remove the generated .config file as well, use:

make distclean

Run the resulting image using the corresponding platform tool. Firecracker requires KVM support. Xen requires a system with Xen installed.

A successful run will show a message such as the one below:

Booting from ROM..Powered by
o.   .o       _ _               __ _
Oo   Oo  ___ (_) | __ __  __ _ ' _) :_
oO   oO ' _ `| | |/ /  _)' _` | |_|  _)
oOo oOO| | | | |   (| | | (_) |  _) :_
 OoOoO ._, ._:_:_,\_._,  .__,_:_, \___)
                Calypso 0.17.0~5d38d108
Hello from Unikraft!

qemu-system-x86_64 -nographic -m 8 -cpu max -kernel out/c-hello_qemu-x86_64

qemu-system-aarch64 -nographic -machine virt -m 8 -cpu max -kernel out/c-hello_qemu-arm64

rm -f firecracker.socket
firecracker-x86_64 --config-file fc.x86_64.json --api-sock firecracker.socket

The user running the above command must be able to use KVM. Typically this means being part of the kvm group. Otherwise, run the command above as root or prefixed by sudo.

rm -f firecracker.socket
firecracker-aarch64 --config-file fc.arm64.json --api-sock firecracker.socket

The user running the above command must be able to use KVM. Typically this means being part of the kvm group. Otherwise, run the command above as the root account or prefixed by sudo.

sudo xl create -c xen.x86_64.cfg

You need use sudo or the root account to run Xen.

sudo xl create -c xen.arm64.cfg

You need use sudo or the root account to run Xen.

C Hello is the simplest application to be run with Unikraft. This makes it ideal as a minimal testing ground for new features: it builds fast, it doesn't have dependencies.

If updating the Unikraft core code in the ../repos/unikraft/ directory, you then go through the configure, build and run steps.

The current configuration use a single source file: hello.c. If looking to add another file to the build, update the Makefile.uk file.

For example, to add a new file support.c to the build, update the Makefile.uk file to:

$(eval $(call addlib,appchello))

APPCHELLO_SRCS-y += $(APPCHELLO_BASE)/hello.c
APPCHELLO_SRCS-y += $(APPCHELLO_BASE)/support.c

To add a new include directory, such as a local include/ directory, update the Makefile.uk file to:

$(eval $(call addlib,appchello))

APPCHELLO_SRCS-y += $(APPCHELLO_BASE)/hello.c
CINCLUDES-y += -I$(APPCHELLO_BASE)/include

Then go through the configure, build and run steps.

It may be the case that you want to add a library to the build, in order to test the library or a certain feature. If that is the case, update the UK_LIBS variable in the Makefile.

For example, to add the Musl library to the build, clone the lib-musl library repository:

test -d ../repos/libs/musl || git clone https://github.com/unikraft/lib-musl ../repos/libs/musl

and update the UK_LIBS line the Makefile to:

UK_LIBS ?= $(LIBS_BASE)/musl

To add another library, such as LWIP, clone the corresponding lib-lwip repository:

test -d ../repos/libs/lwip || git clone https://github.com/unikraft/lib-lwip ../repos/libs/lwip

and update the UK_LIBS line the Makefile to:

UK_LIBS ?= $(LIBS_BASE)/musl:$(LIBS_BASE)/lwip

Then go through the configure, build and run steps.