Real World OCaml

2nd Edition (published in Q4 2021)

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:

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.13.1. 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.13.1
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.13.1.

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

In order to have a reasonable editing experience, there are a collection of different tools you'll want set up. In the following, we'll describe how to set up what you need for each of the editors.

Visual Studio Code

There are several OCaml modes for Visual Studio, but we recommend the OCaml Platform plug-in. This works alongside a server that supports the Visual Studio's Language Server Protocol (LSP). Instructions for installing OCaml LSP server can be found here. These instructions show you how to set things up so you can install the LSP server via opam. Eventually the LSP server will be available from opam by default.

Emacs

opam comes with a user-setup package that can be used to install Emacs configs. You can install it as follows. Note that we first make sure that ocp-indent, an OCaml indentation tool, is available, as well as tuareg, which is an Emacs mode for OCaml.

opam install tuareg ocp-indent merlin
opam install user-setup
opam user-setup install
An alternative to ocp-indent is ocamlformat, which is a full-on code formatter, as opposed to just an indenter. user-setup doesn't support ocamlformat yet, but you can find instructions here If you want fully automatic formatting (as opposed to just indentation), you should first install it via opam.

opam install ocamlformat
user-setup doesn't support ocamlformat yet, but here are instructions for setting up ocamlformat for emacs.

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
If you want fully automatic formatting (as opposed to just indentation), you should first install it via opam.

opam install ocamlformat
user-setup doesn't support ocamlformat yet, but here are instructions for setting up ocamlformat for VIM.