README.md

Update: Looking for Acorn, the innovative web server appliance we demoed at CppCon? Built using Mana, the new C++ Web Application Framework for IncludeOS. Both Acorn and Mana are free and open source, check them out right here on GitHub!

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. Anything may change at any time. The public API should not be considered stable.

Build status

	Build from bundle
Master
Dev

Key features

• Extreme memory footprint: A minimal bootable image, including bootloader, operating system components and a complete C++ standard library is currently 707K when optimized for size.
• KVM and VirtualBox support with full virtualization, using x86 hardware virtualization, available on any modern x86 CPUs). In principle IncludeOS should run on any x86 hardware platform, even on a physical x86 computer, given appropriate drivers. Officially, we develop for- and test on Linux KVM, which power the OpenStack IaaS cloud, and VirtualBox, which means that you can run your IncludeOS service on both Linux, Microsoft Windows and Mac OS X.
• C++11/14 support
  • Full C++11/14 language support with clang v3.8 and later.
  • Standard C++ library (STL) libc++ from LLVM.
  • Exceptions and stack unwinding (currently using libgcc).
  • Note: Certain language features, such as threads and filestreams are currently missing backend support.
• Standard C library using newlib from Red Hat.
• Virtio Network driver with DMA. Virtio provides a highly efficient and widely supported I/O virtualization. We are working towards the new Virtio 1.0 OASIS standard
• A highly modular TCP/IP-stack.

A longer list of features and limitations is on the wiki feature list

Getting started

Install libraries

NOTE: The script will install packages and create a network bridge, and thus will ask for sudo access.

    $ git clone https://github.com/hioa-cs/IncludeOS
    $ cd IncludeOS
    $ ./install.sh

Or if you are running Arch Linux (or one of its flavors):

    $ 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.
• Download the latest binary release bundle from github.
• Unzip the bundle to $INCLUDEOS_INSTALL_LOC (defaults to $HOME).
• Create a network bridge called include0, for tap-networking.
• Build the vmbuilder, which turns your service into a bootable image.
• Copy vmbuild and qemu-ifup from the repo, over to $INCLUDEOS_HOME.

Detailed installation instructions for Vagrant, OS X and Ubuntu are available in the Wiki, as well as instructions for building everything from source.

Testing the installation

A successful setup enables you to build and run a virtual machine. Running:

    $ ./test.sh

will build and run this example service.

More information is available on the wiki.

Writing your first service

1. Copy the ./seed directory to a convenient location like ~/your_service. Then, just start implementing the Service::start function in the Service class, located in your_service/service.cpp (Very simple example provided). This function will be called once the OS is up and running.
2. Enter the name of your service in the first line of the seed Makefile. This will be the base for the name of the final disk image.

Example:

    $ cp -r seed ~/my_service
    $ cd ~/my_service
    $ emacs service.cpp
    ... add your code
    $ make
    $ ./run.sh my_service.img

Take a look at the examples and the tests. These all started out as copies of the same seed.

Contributing to IncludeOS

IncludeOS is being developed on GitHub. Create your own fork, send us a pull request, and chat with us on Gitter. Please read the Guidelines for Contributing to IncludeOS.

C++ Guidelines

We want to adhere as much as possible to the ISO C++ Core Guidelines. When (not if) 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.

Read more on the wiki

We're trying to grow a Wiki, and some questions might already be answered here in the FAQ.

See the Wiki front page for a complete introduction, system overview, and more detailed guides.