Documentation and guides

Learning about Mirage

How to learn about Mirage

The Mirage community is very welcoming of newcomers; your optimal learning route is try out the software on your own development machine, then familiarise yourself with the various backends and the main modules and techniques used in building and running real unikernels.

If you know some OCaml but don't know about Mirage, your first steps should be to try either our Hello Mirage World tutorial, or go directly to building some of the example apps in Mirage Skeleton.

Mirage abstracts away various OS-level functionality (e.g., networking and storage), which must be provided by backends. Commonly used backends are unix, hvt and xen; the unix backend works within a normal laptop-based development environment. The others tend to involve various degrees of configuration effort, but are more realistic for production use. You can write your code, test it on unix first, and later adapt your environment to run one of the other backends.

How to get help

A brief survey of the Mirage development community revealed that the preferred method of getting help is the email mailing list: the core developers all read it. Mailing lists aren't for everyone, so here are the alternatives, roughly in descending order of preference:

Typical development workflow

When checking out an example project, a typical workflow would look something like this:

    $ mirage configure -t unix
    $ make depends
    $ make
    $ ./main.native

Be aware that the behaviour of mirage configure depends intimately on the contents of the config.ml file in your current directory. This is true even of its command-line options. It follows that the syntax you observe in one tutorial or project may not always carry across to another.

The mirage configure phase does the heavy lifting to resolve what code must be available for the backend you specify. The backend is specified with the -t option.

What are backends?

Backends include:

The backends above are listed in ascending order of invasiveness. unix runs as a normal process on your unmodified Linux kernel, albeit it may require root privileges. hvt uses Solo5 and hardware virtualization on Linux and FreeBSD, which entails some setup work, e.g., of IP routing. xen requires that Xen be run underneath your operating system(s), and that Mirage will be run directly on top of Xen. Installing Xen is not hard (about 20 minutes), and it may conveniently co-exist as a dual-booted environment if you don't want to dedicate your host machine exclusively to it.

Configuration

For now, see the relevant blog post.

Mirage effectively treats functionality such as persistent storage, networking, protocols, etc, as libraries. The configuration phase for Mirage determines which implementations of these libraries will be compiled into your unikernel.