Installation Instructions

These instructions are aimed at readers of Real World OCaml, though much of what you find here will be useful for anyone who wants to get a good working OCaml installation.

At the highest level, here's what you need to do:

• Install opam, OCaml's default package manager
• Set up opam, which means initializing opam and then installing the version of OCaml you'll need, along with the libraries and tools that will help you work through the examples in the book
• Configure utop, the interactive toplevel that will be the primary vehicle we'll use for walking through small examples.
• Set up your editing environment. We have pointers for a few editors, including Visual Studio Code, Emacs, and Vi

Note that Windows is not fully supported by the examples in Real World OCaml or by opam, though it's being worked on. Until that's ready, we recommend using a virtual machine running Debian Linux on your local machine, or Docker for Windows.

Let's get started.

Installing opam

opam is the default package manager for OCaml, and you'll need it to get everything else you need installed and set up.

The easiest way to install opam is through your OS's package manager. In most cases, installing opam will also trigger the installation of OCaml. The version installed isn't important, since we can use opam itself to install other versions of the compiler.

Here are platform-specific installation instructions for installing via your package manager. The same page has instructions for using a binary installer if you have trouble with your package manager.

Setting up opam

Run opam init

The entire opam package database is held in the .opam directory in your home directory, including compiler installations. On Linux and macOS, this will be the ~/.opam directory, which means you don't need administrative privileges to configure it. If you run into problems configuring opam, just delete the whole ~/.opam directory and start over.

Let's begin by initialising the opam package database. We do this by running:

opam init

Before opam init finishes, it will ask you if you want it to adjust some of the config files for your shell. We recommend you say yes here so as to automate adjusting the PATH environment variable of your shell and to prepare your environment in other ways.

Note that if for whatever reason your shell is not set up properly, you can put it in the right state by running:

eval $(opam env)

This evaluates the results of running opam config env in your current shell and sets the variables so that subsequent commands will use them. This only works with your current shell and it can only be automated for future shells by adding the line to your login scripts (which is exactly what opam offers to do for you in opam init).

You can check if your environment is set up properly by running opam switch with no arguments. It will emit a warning if your shell is not set up correctly, along with instructions on how to fix it.

opam switch
#  switch                            compiler                    description
→  default                           ocaml-base-compiler.4.09.1  default

[WARNING] The environment is not in sync with the current switch.
          You should run: eval $(opam env)

Installing the right compiler

Real World OCaml requires OCaml 4.10.0. You can use opam switch to see which version of OCaml you have installed. If, as shown in the above invocation of switch, you have an older version installed, you can use opam to install a more up-to-date version:

opam switch create 4.10.0
eval $(opam env)

The opam switch create will take a few minutes on a modern machine, and will download and install the new compiler and all libraries associated with it in ~/.opam/4.10.0.

Installing libraries and tools

Finally, we're ready to install the libraries and tools we'll need for the book. The two important ones are base, which provides the standard library that all the examples in the book are based on, and utop, which is the interactive toplevel that you can use for working through the examples. We can install them as follows.

opam install base utop

But you'll probably want more than this as you work through the book. Here's a more complete list of libraries you should install:

opam install core async yojson core_extended \
     core_bench cohttp-async async_graphics \
     cryptokit menhir

If some of the above don't work, don't worry too much. Most of them come up in only a few places in the book.

Setting up and using utop

When you first run utop, you'll find yourself at an interactive prompt with a bar at the bottom of the screen. The bottom bar dynamically updates as you write text, and contains the possible names of modules or variables that are valid at that point in the phrase you are entering. You can press the <tab> key to complete the phrase with the first choice.

The ~/.ocamlinit file in your home directory initializes utop with common libraries and syntax extensions so you don't need to type them in every time. Given that you have Core installed, you should update your ocamlinit to load Core every time you start utop, by adding the following lines.

#use "topfind";;
#thread;;
#require "core.top";;

For utop only you could get away with just the last line, but you need the whole thing if you want the traditional ocaml toplevel to work too.

Note that opam will have already added some lines to the file. Also, notice that # is used to mark a toplevel directive, not a comment.

Editor set-up

• An editor mode that understands the language, and can help with the basics of syntax-highlighting and navigation.
• Merlin, which provides out of your code, like auto-completion, go-to-definition, and type-throwback.
• ocp-indent, which auto-indents your code.
• ocamlformat, which provides fully automatic formatting and indentation (including line-breaking).

Visual Studio Code

Emacs

opam install tuareg ocp-indent merlin
opam install user-setup
opam user-setup install

opam install ocamlformat

Vim

Vim users can use the built-in style for handling OCaml source code. Beyond that, Merlin and other associated tools can be installed as follows.

opam install merlin ocp-indent
opam install user-setup
opam user-setup install

opam install ocamlformat