IncludeOS: A C repository from heejune

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	Build from source
Master		Coming soon
Dev		Coming soon

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

    $ git clone https://github.com/hioa-cs/IncludeOS
    $ cd IncludeOS
    $ sudo ./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.

NOTE: The script will install packages, and thus will require sudo access.

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

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.
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.

heejune/IncludeOS