MirageOS consists of a set of OCaml libraries that link with a runtime to form either a standalone Xen operating system or a normal UNIX binary. These libraries are managed via the OPAM tool. After describing MirageOS's system requirements, we will introduce the basics of OPAM and setting up for MirageOS.
MirageOS has been tested on ArchLinux, Debian Wheezy/Jessie, Ubuntu 14.04/16.10, CentOS 6/7 and MacOS X 10.10+. To compile the Xen backend, you must have a 64-bit Linux host. 32-bit is not supported at this time.
If you are using Homebrew, run
brew install opam opam init opam install mirage
This has the latest packages required in the base distribution, so just run:
sudo apt-get update sudo apt-get install opam opam init opam install mirage
The version of OPAM in older Ubuntus is not high enough to run Mirage (which requires OPAM 1.2.2 or higher), so you will need to add a custom PPA for the latest packages:
sudo add-apt-repository ppa:avsm/ppa sudo apt-get update sudo apt-get install ocaml ocaml-native-compilers camlp4-extra opam opam init opam install mirage
Also note that the
mirage configuration and deployment tool relies on the
xl Xen toolstack to run Xen virtual machines. Older Ubuntus may use the
xm toolstack, so you will need to change it.
Debian Jessie only packages OPAM 1.2.0, but Mirage needs OPAM 1.2.2 or higher. You can use 0install to get the right version of OPAM:
sudo apt-get update sudo apt-get install ca-certificates curl 0install-core --no-install-recommends -y 0install add opam http://tools.ocaml.org/opam.xml opam init opam install mirage
These distributions include everything you need to run Mirage in the base distribution, so just do:
sudo apt-get update sudo apt-get install ocaml ocaml-native-compilers camlp4-extra opam opam init opam install mirage
We use OPAM to manage OCaml compiler and library installations. It tracks library versions across upgrades and will recompile dependencies automatically if they get out of date. Please refer to OPAM documentation if you want to know more, but we will cover the basics to get you started here. There is a Quick Install Guide if the above instructions don't cover your operating system.
Note that you require OPAM 1.2.2 or greater to use with MirageOS. Some distribution packages provide earlier versions and must be updated; check with
$ opam --version ## response should be at least 1.2.2 viz. 1.2.2
All the OPAM state is held in the
.opam directory in your home directory, including compiler installations. You should never need to switch to a root user to install packages. Package listings are obtained through
remote sources, which defaults to the contents of github.com/ocaml/opam-repository.
opam update -u refreshes the package list and recompiles packages to the latest versions. You should run this regularly to get the latest packages.
$ opam init # list of your remotes, which should include opam.ocaml.org $ opam remote
Next, make sure you have at least OCaml 4.02.3 or higher as your active compiler. This is generally the case on MacOS X, though Debian only has it in the testing distribution at present. But don't worry: if your compiler is out of date, just run
opam switch to have it locally install the right version for you.
$ ocaml -version # if it is not 4.02.3 or higher, then run this $ opam switch 4.02.3
Once you've got the right version, set up your shell environment to point to the current compiler switch.
$ eval `opam config env` # add the above line to your startup shell profile
This updates the variables in your shell to match the current OPAM installation, mainly by altering your system
PATH. You can see the shell fragment by running
opam config env at any time. If you add the
eval line to your login shell (usually
~/.bash_profile), it will automatically import the correct PATH on every subsequent login.
Check that the base packages are installed correctly:
$ opam list Installed packages for system: base-bigarray base Bigarray library distributed with the OCaml compiler base-threads base Threads library distributed with the OCaml compiler base-unix base Unix library distributed with the OCaml compiler [ possibly other installed packages ]
Finally, install the MirageOS command-line tool.
$ opam install mirage $ mirage --help
This will install Mirage!
If you're upgrading from an older beta installation of MirageOS, then be sure that you have at least 2.9.0. You can verify this by checking that the version number in the manual page from
mirage --help is at least 2.9.0 (as of the time of writing this page).
That's it. You now have everything required to start developing MirageOS unikernels that will run either as POSIX processes or as Xen VMs using the MirageOS network stack. Next, why not try building a MirageOS hello world?