Skip to content

Commit

Permalink
Merge pull request #468 from avsm/pr467-docs
Browse files Browse the repository at this point in the history 
Refresh the installation instructions to something recent
  • Loading branch information
@avsm
avsm committed Jul 14, 2016
2 parents 59b40c1 + b69c1f9 commit 4c50465
Showing 1 changed file with 62 additions and 25 deletions.
87 changes: 62 additions & 25 deletions tmpl/wiki/install.md
View file
Original file line number Diff line number Diff line change
@@ -1,47 +1,86 @@
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](http://opam.ocaml.org) tool. After describing MirageOS's system requirements, we will introduce the basics of OPAM and setting up for MirageOS.
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](https://opam.ocaml.org) tool. After describing MirageOS's system requirements, we will introduce the basics of OPAM and setting up for MirageOS.

## Requirements

MirageOS has been tested on ArchLinux, Debian Wheezy, Ubuntu Precise/Lucid/Raring/Saucy, CentOS 6.4 and MacOS X 10.8 and 10.9. To compile the Xen backend, you *must* have a 64-bit Linux host. 32-bit is not supported at this time.
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're using MacOS X 10.9 or older, you will also need the [tuntap](http://tuntaposx.sourceforge.net/) kernel module if you want to use the MirageOS network stack from userspace.
### MacOS X

If you're using Ubuntu/Debian, we recommend you also install the essential build tools (GNU make, etc) and GNU M4 as well as the OCaml toolchain including camlp4:
* __10.10__: No special requirements beyond Homebrew or MacPorts to get OCaml.
* __10.9 or lower__: You will also need the [tuntap](http://tuntaposx.sourceforge.net/) kernel module if you want to use the MirageOS network stack from userspace. Note that we do not test older versions of OSX beyond 10.10.

apt-get install build-essential m4 ocaml ocaml-native-compilers camlp4-extra
If you are using Homebrew, run

On CentOS 6.4, install the system compiler and libraries via:
brew install opam
opam init
opam install mirage

sudo yum groupinstall "Development Tools" "Development Libraries"
### Ubuntu

On Arch Linux, install the system compiler and libraries via:
sudo pacman -S ocaml camlp4 ocaml-findlib
yaourt -S opam
#### Ubuntu 16.04 (Xenial) or higher

Also note that the `mirage` configuration and deployment tool relies on the `xl` Xen toolstack to run virtual machines.
This has the latest packages required in the base distribution, so just run:

## Using OPAM
sudo apt-get update
sudo apt-get install opam
opam init
opam install mirage

We use [OPAM](http://opam.ocaml.org) 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](https://opam.ocaml.org) if you want to know more, but we will cover the basics to get you started here. Install OPAM for your operating system by following its [Quick Install Guide](http://opam.ocaml.org/doc/Install.html).
#### Ubuntu 15.10 (Vivid) or lower

Note that you require **OPAM 1.2 or greater** to use with MirageOS. Some distribution packages provide earlier versions and must be updated; check with
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:

$ opam --version ## response should be at least 1.2.0, viz.
1.2.0
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

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](http://github.com/ocaml/opam-repository).
After installation, `opam update -u` refreshes the package list and recompiles packages to the latest versions.
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

#### Debian Stable (Jessie)

Debian Jessie only packages OPAM 1.2.0, but Mirage needs OPAM 1.2.2 or higher. You can use [0install](http://0install.net) 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

#### Debian Testing (Stretch) or Unstable (Sid)

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

## MirageOS Package Management with OPAM

We use [OPAM](https://opam.ocaml.org) 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](https://opam.ocaml.org) if you want to know more, but we will cover the basics to get you started here. There is a [Quick Install Guide](http://opam.ocaml.org/doc/Install.html) 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](https://github.com/ocaml/opam-repository).

After installation, `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.01.0 or higher** as your active compiler. This is generally the case on MacOS X, though Debian only has it in the *unstable* 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.
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.01.0 or higher, then run this
$ opam switch `opam switch | grep Official | tail -1 | awk '{print $3}'`
# to install the latest available 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.

Expand All @@ -64,9 +103,7 @@ Finally, install the MirageOS command-line tool.
$ opam install mirage
$ mirage --help

If you're using Arch Linux and `opam install mirage` gives errors about not finding camlp4 and camlp4 was installed with pacman (and not by OPAM), then running `opam install mirage` without having executed the `eval` line lets `opam` find the system-wide installation of camlp4.

This will install [Mirage](https://github.com/mirage/mirage)!
If you're upgrading from an older beta installation of MirageOS, then be sure that you have at least 1.1.0, or you'll get installation errors. You can verify this by checking that the version number in the manual page from `mirage --help` is at least (as of the time of writing this page) 1.1.0.
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*](/wiki/hello-world)?

0 comments on commit 4c50465

Please sign in to comment.