IncludeOS is an includable, minimal unikernel operating system for C++ services running in the cloud and on real HW. Starting a program with #include <os> will literally include a tiny operating system into your service during link-time.
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.
- Extreme memory footprint: A minimal bootable 64-bit web server, including operating system components and 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.
For building and booting IncludeOS services you will need nix and Linux. Nix will automatically download and set up the correct versions of all the required libraries and compilers.
To speed up local builds we also recommend configuring nix with ccache support but this is not a requirement. To use ccache, --arg withCcache true can be added to most nix-build and nix-shell commands shown below.
IncludeOS can currently not be built on macOS or Windows.
A minimal IncludeOS "hello world" looks like a regular C++ program:
#include <iostream> int main(){ std::cout << "Hello world\n"; }
A full "Hello world" service with a working nix workflow is available in the hello world repo. The repository can also be used as a a starting point for developing your own IncludeOS service.
For more advanced service examples see the the integration tests (under ./IncludeOS/test/\*/integration).
To build IncludeOS, run
$ nix-build
This will build the toolchain and all IncludeOS kernel libraries.
Note that the first build will take some time (~7 hours on our machines) to complete, as the IncludeOS toolchain is rebuilt from source code. This includes clang, llvm, libcxx, musl and so on. There is no nix binary cache available for these files at the moment. Subsequent builds will go much faster when the toolchain has been cached in the local nix-store.
After making changes to the kernel, run nix-build again to get new binaries. If you are iterating on changes in one section of the kernel you can speed up the build significantly (from a few minutes to a matter of seconds) by using ccache. All nix-build and nix-shell commands in this section support the optional parameter --arg withCcache <true|false> (this is only enabled by default for the development shell). We strongly advise setting up the ccache before you start iterating on the code. For NixOS, you can check the wiki on how to do this, other distros will have different instructions.
It's not always practical to rebuild the whole kernel during development. You can get a development shell with a preconfigured environment using develop.nix:
$ nix-shell ./develop.nix
From here, you will be put in a shell suited for development. If your editor has LSP support with clangd (e.g. neovim, emacs, VSCode, Zed), you will get proper goto-declarations and warnings. You can quickly rebuild the kernel library from here with cmake -B build && cmake --build build, with all build dependencies handled by the shell.
You can also build and run a unikernel from the shell with this oneliner: nix-build unikernel.nix && boot ./result/hello_includeos.elf.bin) after building IncludeOS. It might be convenient to use one terminal (or tab) for your editor, a second for building IncludeOS, and a third for building a unikernel.
In summary:
~/repos/IncludeOS $ nix-shell ./develop.nix [nix-shell:~/repos/IncludeOS]$ cmake -B build && cmake --build build # rebuilds IncludeOS [nix-shell:~/repos/IncludeOS]$ nix-build ./unikernel.nix # rebuilds the example unikernel [nix-shell:~/repos/IncludeOS]$ boot ./result/hello_includeos.elf.bin # runs the unikernel image with qemu through vmrunner
Alternatively, you may want to use nix-shell by itself (or nested inside the development shell), which handles both building the unikernel found under ./example/ and puts you in a convenient shell for testing out a unikernel.
# both these require vmrunner's booth on path ~/repos/IncludeOS $ nix-shell unikernel.nix --run 'boot hello_includeos.elf.bin' # or ~/repos/IncludeOS $ nix-shell unikernel.nix [nix-shell:~/repos/IncludeOS/result]$ boot hello_includeos.elf.bin
If you want to build a different unikernel than the example, this can be specified with the --argstr unikernel [path] parameter. This is primarily used for integration tests. For example, to build and run the stacktrace-test:
$ nix-build unikernel.nix --argstr unikernel ./test/integration/kernel/stacktrace --doCheck true [...] nix$ ls -l kernel* kernel_stacktrace nix$ boot kernel_stacktrace [...] Calling os::print_backtrace() symtab or strtab is empty, indicating image may be stripped [0] 0x000000000025dcd2 + 0x000: 0x25dcd2 [1] 0x000000000021097d + 0x000: 0x21097d [2] 0x00000000002b370a + 0x000: 0x2b370a [3] 0x0000000000210eea + 0x000: 0x210eea We reached the end.
To build and run the test VM as a single command:
$ nix-build unikernel.nix --argstr unikernel ./test/integration/kernel/stacktrace --doCheck trueYou can run all the integration tests using the script ./test/test.sh. The tests will run locally in the nix environment. We recommend manually verifying that all the tests pass locally before submitting a new PR to IncludeOS to save review time.
Most individual tests can be run with nix-build directly, while some require nix-shell due to sandboxing constraints. See ./test/test.sh for more details.
IncludeOS is being developed on GitHub. Create your own fork and send us a pull request. Please read the Guidelines for Contributing to IncludeOS.
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 protected]. For more information and encryption please refer to the documentation.