Real World OCaml

2nd Edition (Oct 2022)

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 a high 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 through WSL2, or Docker for Windows.

Let's get started.

Install and set up opam

Install opam

The easiest way to install opam is through your OS's package manager.

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.

Initialize opam

Initialize the opam package database by running:

  
opam init

opam init 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 this will only take effect on a newly launched shell.

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)

Install 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. The second line is required to point your current shell to the new switch.

Installing libraries and tools

Install via opam

You'll need to install base and core, which provide the standard library that all the examples in the book are based on, along with utop, which is the interactive toplevel that you can use for working through the examples.

Both can be installed as follows:

  
opam install core core_bench utop

Other packages will come up in the book, but you can install them when you need them.

Set up utop

You should create an ~/.ocamlinit file in your home directory with the following contents:


#require "core.top";;
#require "ppx_jane";;
open Base;;

This will open the Base standard library and set up some useful pretty-printers and syntax extensions. Notice that # is used to mark a toplevel directive, not a comment.

Set up your editor

Visual Studio Code

We recommend the OCaml Platform plug-in. You'll also need an OCaml Language-Server-Protocol server, which you can install via opam following these instructions.

Emacs

opam comes with a user-setup package that can be used to install Emacs configs. You can install it as follows, along with some related packages.

  
opam install user-setup tuareg ocamlformat merlin
opam user-setup install

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 user-setup merlin ocamlformat
opam user-setup install

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