IncludeOS is an includable, minimal unikernel operating system for C++ services running in the cloud. Starting a program with
#include <os> will literally include a tiny operating system into your service during link-time.
The build system will:
- link your service with the necessary OS objects into a single binary
- attach a boot loader
- combine everything into a self-contained bootable disk image, ready to run on almost any modern hypervisor.
IncludeOS is free software, with "no warranties or restrictions of any kind".
Note: IncludeOS is under active development. The public API should not be considered stable.
|Master branch||Dev branch|
- Extreme memory footprint: A minimal bootable 64-bit web server, including operating system components and a anything needed from the C/C++ standard libraries is currently 2.5 MB.
- KVM, VirtualBox and VMWare support with full virtualization, using x86 hardware virtualization, available on most modern x86 CPUs. IncludeOS will run on any x86 hardware platform, even on a physical x86 computer, given appropriate drivers. Officially, we develop for- and test on Linux KVM, and VMWare ESXi/Fusion which means that you can run your IncludeOS service on Linux, Microsoft Windows and macOS, as well as on cloud providers such as Google Compute Engine, OpenStack and VMWare vcloud.
- Instant boot: IncludeOS on Qemu/kvm boots in about 300ms but IBM Research has also integrated IncludeOS with Solo5/uKVM, providing boot times as low as 10 milliseconds.
- Modern C++ support
- Standard C library using musl libc.
- Virtio and vmxnet3 Network drivers with DMA. Virtio provides a highly efficient and widely supported I/O virtualization. vmxnet3 is the VMWare equivalent.
- A highly modular TCP/IP-stack.
A longer list of features and limitations can be found on our documentation site.
Set custom location and compiler
By default the project is installed to
However, it is recommended to choose a custom location as well as select the compiler we want clang to find. In this document we assume you install IncludeOS in your home directory, in the folder
To do this we can edit
~/.bash_profile (mac os) or
~/.bashrc (linux), adding these lines at the end of the file:
export INCLUDEOS_PREFIX=~/includeos/ export PATH=$PATH:$INCLUDEOS_PREFIX/bin
This will also crucially make the boot program visible globally, so that you can simply run
boot <myservice> inside any service folder.
If you want to install IncludeOS on Mac OS you'll need a working installation of brew so the install script can install its dependencies.
NOTE: The script will install packages.
$ git clone https://github.com/hioa-cs/IncludeOS $ cd IncludeOS $ ./install.sh
The script will:
- Install the required dependencies:
curl make clang-3.8 nasm bridge-utils qemu.
- Create a network bridge called
bridge43, for tap-networking.
- Build IncludeOS with CMake:
- Download the latest binary release bundle from github together with the required git submodules.
- Unzip the bundle to the current build directory.
- Build several tools used with IncludeOS, including vmbuilder, which turns your service into a bootable image.
- Install everything in
Configuration of your IncludeOS installation can be done inside
Testing the installation
A successful setup enables you to build and run a virtual machine. There are a few demonstration services in the source folder. If you look in the
examples/ folder you see these. If you enter
demo_service and type
boot --create-bridge . this script will build the service and boot it using qemu.
$ cd examples/demo_service $ boot --create-bridge .
More information is available on our documentation site.
Writing your first service
- Copy the ./seed/service directory to a convenient location like
~/your_service. Then, just start implementing the
Service::startfunction in the
Serviceclass, located in your_service/service.cpp (very simple example provided). This function will be called once the OS is up and running.
- Update the CMakeLists.txt to specify the name of your project, enable any needed drivers or plugins, etc.
$ cp -r seed/service ~/my_service $ cd ~/my_service $ emacs service.cpp ... add your code $ mkdir build && cd build $ cmake .. $ make $ boot my_service
Contributing to IncludeOS
Important: Send your pull requests to the
dev branch. It is ok if your pull requests come from your master branch.
We want to adhere as much as possible to the ISO C++ Core Guidelines. When you find code in IncludeOS which doesn't adhere, please let us know in the issue tracker - or even better, fix it in your own fork and send us a pull-request.
If you discover a security issue in IncludeOS please avoid the public issue tracker. Instead send an email to email@example.com. For more information and encryption please refer to the documentation.