Mirage.io onboarding @ Hackathon

Written by GemmaG (Gemma Gordon)
Published: 2016-07-13 (last updated: 2016-07-13)

Onboarding with user M

  • new to OCaml
  • new to Mirage
  • usually works in Python

Documentation: https://mirage.io/docs/


  • mirage docs - not completely clear from this page what to do first - installation is quite hidden. Might expect the step-by-step process on the left.
  • user personally prefers text form rather than screencast for instructions. But if screencast, need text instructions too.

Installation: https://mirage.io/wiki/install


  • requirements section could be clearer - user misread which requirements are needed and tried to download tuntap when not necessary for his use case.

  • tuntap - link doesn't work - tuntap website doesn't work.

  • opam install stages - process described well on mirage.io

  • install homebrew - process described well on mirage.io

  • to allow for easy parsing and separation, could section off specific reqs with headings to avoid reading non-essential information, and to make it easier to read relevant information.

SUCCESS! Woop! (has taken 25 mins to get to this stage from initially starting install)

Homebrew instructions


  • aspcud had problems downloading using homebrew, was fine when downloaded directly. Possibly a homebrew-specific issue.

  • homebrew/bottle (after install of opam) has confusing instructions involving eval opam config env...rather than

"Run the following to initialize your environment variables:

$  eval `opam config env`

To export the needed variables every time, add them to your dotfiles."

"add them" it could specify what you are adding. The instructions for setting up the specific compiler switch are well explained on mirage.io :)

OPAM instructions: https://opam.ocaml.org/doc/Usage.html


  • Slightly different instructions for the same process - less clear via opam site.

e.g. need to run opam init before opam update but the reader instructed to update first.

Could add note saying that opam init will offer to install everything you need without unnecessary steps

Got Mirage. ~45 mins total

Hello World: https://mirage.io/wiki/hello-world


  • Tutorial notes that reading lwt tutorial first might be helpful, but chose to skip lwt for now.

  • Not sure of OCaml features, e.g what is a console?

let main =

foreign "Unikernel.Main" (console @-> job)

let () =

register "console" [main $ default_console]

e.g. could have more information about these functions and definitions - perhaps a clickable link to a definition of them.

  • User suggested that comparisons to other languages e.g. Haskell to help with those who have experience with other languages

  • Very text heavy - could be sectioned for easier reading - have the above details in separate boxes.

  • Not getting much useful help from all of the text - seems like a lot of it is useful to know, but not imperative to the tutorial itself.

  • Hasn't read the tech background docs https://mirage.io/wiki/technical-background, but not sure (from a quick look) that they offer that much more info now - don't bridge the gap sufficiently?

  • User keen to stress that it's most likely because their OCaml knowledge is very basic. Perhaps we could have different tutorials based on existing knowledge.

  • building unix binary - smooth process.

  • step 2: block device section. Definitions of functions could be highlighted with an explanation/side-by-side so you don't have to leave the page to find it out.

e.g no explanation of what foreign is (or no explanation/link that is easy to find). V1.block link takes you to the definition in blob, but could be more clearly described exactly what pre-requisite knowledge is assumed.

  • "As an aside, if you have your editor configured with OCaml mode..."

No link to how to configure your editor for example. The tutorial is assuming certain features are set up but not explicitly saying it.

  • Building on Unix:

$ cd block $ mirage configure --unix $ make $ ./generate_disk_img.sh *** DOES NOT EXIST $ ./mir-block_test *** works ok

  • User can't run xen version - so doesn't need that information - could be hidden/not required reading/separated/sectioned out.

  • Skips to step 3 config.ml does look a little more familiar - getting more used to OCaml. Feels like reading an OCaml tutorial to begin with might be useful - what would be a good starter for this? Could we link to it at the start of the tutorial? https://ocaml.org/learn/tutorials/ - crash course of mirage syntax and functions.

  • The following doesn't work with OCaml 4.03

$ mirage configure --unix --kv_ro fat $ ./make-fat1-image.sh $ file fat1.img fat1.img: x86 boot sector, code offset 0x0, OEM-ID "ocamlfat", sectors/cluster 4, FAT 1, root entries 512, Media descriptor 0xf8, sectors/FAT 1, sectors 49 (volumes > 32 MB) , dos < 4.0 BootSector (0x0)

  • Step 4 Networking: Not sure what is a function definition

open Mirage

let handler = foreign "Unikernel.Main" (console @-> stackv4 @-> job)

let stack = generic_stackv4 default_console tap0

let () = register "stackv4" [handler $ default_console $ stack]

Not sure how much he's learning now - would be good if there was an explanation of what these specific processes are doing that is easy to get to.

  • Went back to read main.ml and unikernel.ml files e.g to find where "main" is defined. (The tutorial does suggest checking main.ml to see how it works under the hood, but it's right at the bottom and easy to miss).

  • Advice from another new user "F" is get it to compile and run, and then look at simple code samples (skeleton)

  • Getting the idea that you can switch out different parts - e.g. different ways to configure networking. But the whole last section is explaining how to do the same thing but in different ways - skimmed through this. This could perhaps be hidden/separate from the main tutorial?

  • mirage-net-macosx is failing to compile 1.1.0 User is on el capitan. Failed to build - ocamlbuild fail.

mirage www: https://mirage.io/wiki/mirage-www


  • Inconsistent use of cd into certain folders - it's assuming you have left the top level, but if you are following the tutorial then you would already be in the right place. It later assumes you are in a different directory e.g. make prepare. Would prefer a simple and consistent assumption for each example.

  • make prepare to build javascript elements fails at make build stage:

install lwt type_conv


Searched for type_conv to install separately and searching with the error to see how to workaround. A lot of noise - difficult to tell what is failing where.

Remains stuck at this point - can't install type_conv https://github.com/ocaml/opam-repository/issues/4730

Maybe we need to install ocaml core? Still failed to install :(

Running make prepare again with core installed this time to see if it changes anything... No.

Tried updates and upgrades - already updated as much as possible.

SKIPPING trying to build it as we can't figure out why it's not building...

Getting 4.02.3 to see if it works...

Other comments

  • Could have a contents to easily follow and navigate back out again.