Skip to content

Installing OCaml

Here are the steps you should go through to install OCaml on your computer. You should install the latest OCaml version, which as of this writing is version 5.3.0.

Install OCaml and opam

See the instructions on the OCaml website. Note that opam is the OCaml package manager, which needs to be installed in order to install critical libraries.

MacOS

The instructions for MacOS refer to the Homebrew package manager, which needs to be installed first (it's very easy). Follow the instructions on the Homebrew website to install it.

Note

Don't use any other package manager for MacOS (e.g. MacPorts).

Linux

If you are using Linux, you should install OCaml using your distribution's package manager. The instructions linked to above contain more details. For example, for Ubuntu Linux the commands are

$ sudo apt update
$ sudo apt install opam

The sudo is so you don't have to install the software as the root user. You may be asked to enter your password, which you should do.

Windows

If you are using Windows, you should install an Ubuntu Linux system inside of Windows using the Windows Subsystem for Linux, also known as "WSL". Then you can use apt like on any Ubuntu Linux system.

It's possible to install OCaml directly on Windows, but it's probably not worth the trouble. WSL is a much easier solution, and it will work fine with external editors like VS Code (discussed below). This course does not support OCaml directly on Windows, because we assume a Unix-like environment (Makefiles etc.) for much of our tooling.

Initialization

Once you have a version of OCaml and opam installed, you need to set it up, and, if necessary, upgrade the versions. Start up your terminal program and go through the following steps.

  • Initialize opam by typing opam init in a terminal and following the instructions.

    Note

    There is an issue with initializing opam inside of WSL (Windows Subsystem for Linux). Basically, due to the way WSL works, you have to initialize opam differently by disabling sandboxing. This theoretically can cause some problems if a package does something really stupid, but it probably won't. The fix is to use this command instead of just opam init:

    $ opam init --disable-sandboxing

  • At the end of the opam init command, it will ask you to run eval ${opam env}. (Or it might say eval ${opam config env} or something similar. It all does the same thing.) This sets up the PATH variable of your shell to point to the opam directories. This is important, because if you don't do this, adding new packages (and new OCaml versions) will not work. Opam will also ask you if it can change your shell initialization file (e.g. ~/.bashrc for bash) by adding some commands. You should say yes, because if you don't, every time you start up a new terminal you will have to type eval ${opam env} to get opam to work correctly.

  • In your terminal, type

    $ opam update
$ opam upgrade

    to make sure the package repository is up to date and all OCaml packages have been upgraded to the most recent versions.

  • Check the OCaml version by typing ocaml --version. If it's the most current version (which is 5.3.0 as of this writing) you are done with this part. Otherwise do opam switch create 5.3.0 and wait for the new version to be installed. (This will take a while.)

  • Install these libraries:

    $ opam install ocamlfind dune utop sexplib ppx_sexp_conv ocaml-lsp-server

Note particularly the utop library, which installs the utop program. utop is an improved version of the ocaml interpreter, and you should use it instead of ocaml when testing code interactively.

The ocaml-lsp-server library is important if you want to use Visual Studio Code as your editor (see below).

Using OCaml

There are only a few things you need to know in order to use OCaml effectively.

Starting OCaml

You can start the OCaml interpreter by opening a terminal and typing:

$ utop

at the terminal prompt. This will bring up the OCaml interactive interpreter, which is a good environment for experimenting with the language and for testing code you've written.

Note

You can also use ocaml instead of utop, but utop is much more full-featured.

utop makes it possible to easily recall and edit previously-input lines of text by using the up and down arrow keys. To see what it can do, start it up

$ utop

and type the following commands (one per line, hitting the return key at the end of each line):

# Printf.printf "hello\n" ;;
# Printf.printf "goodbye\n" ;;

Note that the OCaml interpreter prompt is the hash sign (#); don't type that! These lines should, when evaluated, print the words hello and goodbye respectively. Once you've done this, you should be able to recall either line by using the up arrow key. For instance, you can hit the up arrow key once to get the line:

Printf.printf "goodbye\n" ;;

and edit it so that it says:

Printf.printf "adios\n" ;;

When you hit return, it should print out adios on a separate line. You can also use control-a to get to the beginning of a line you are editing and control-e to get to the end. control-l (lower-case L) clears the terminal and puts the cursor at the top of the terminal window.

One annoying thing about utop is that it tends to go overboard on command completion. You can disable this by typing this inside utop:

# #utop_prompt_dummy;;
# UTop.set_show_box false;;

It's annoying to type this every time you start utop, so what I do is make a utop initialization file called init.ml and put it in the directory ~/.config/utop (creating that directory if necessary). Then these commands will be run every time utop starts.

Note

Unfortunately, this will not work properly if used in a directory that has a .ocamlinit file in it (usually your home directory). There are workarounds, but most of the time it will work properly. Other than that, utop is far superior to the basic ocaml interpreter.

Using Visual Studio Code

You can use any text editor you like to write OCaml code, but we recommend you try Visual Studio Code (also known as VS Code), which has excellent OCaml support. In order to use it, you need to do the following steps:

  • Make sure you've install the OCaml Language Server Protocol (we did this above). If you haven't, type this:

    $ opam install ocaml-lsp-server

  • Install Visual Studio Code from https://code.visualstudio.com/.

  • When inside VS Code, look at the Extensions pane (select View/Extensions from the menu). Type "OCaml" into the search bar at the top, and select and install "OCaml Platform".

Now you will get nice syntax highlighting and code completion when you edit OCaml source code. You can also start a terminal while inside VS Code to test your code by running the OCaml interpreter. When you do, make sure you choose a WSL (Ubuntu Linux) terminal, not a PowerShell terminal!

Now you are ready to write OCaml code!

Disabling Github Copilot

If you have previously installed the Github Copilot Extension for VS Code, you must disable it while working on your CS 164 code! (See the Administrative/Collaboration Policies document for more on this.) The way to do this is as follows:

  • Open VS Code.
  • Go to the Extensions view by clicking the Extensions icon in the Activity Bar (or press Ctrl+Shift+X).
  • Search for "GitHub Copilot."
  • Click the gear icon next to the "GitHub Copilot" extension and select "Disable." You may be prompted to restart VS Code or to reload the window in order for changes to take effect.

Using the terminal

In this book, we assume that you will be running OCaml from inside a Unix-like terminal environment, such as you can find on Linux, MacOS, or Windows (if you're using WSL). This means that we will assume that you know how to do basic terminal tasks and commands such as

  • creating a directory (mkdir)
  • removing a directory (rmdir)
  • changing directories (cd)
  • removing files (rm)
  • running programs

In addition, we will be using the GNU make program to build our compilers. We will include instructions on how to use make in the assignments, but you should ensure that make is installed by typing

$ which make

If it replies with make not found or something similar, you need to install it. On a Mac with Homebrew, type:

$ brew install make

On an Ubuntu Linux system or Windows with WSL, type:

$ sudo apt install make

However, it's likely that make is already installed.