README.org

Let’s install OCaml!

This page has instructions for setting up a modern OCaml development environment.

Prerequisites

These instructions have been tested on

• macOS 10.13.6
• Debian 9.8
• Fedora 29
• Ubuntu 16.04.6 LTS
• Windows 10 1810 with Ubuntu 18.04.2 LTS

They should work on other versions of macOS and mainstream Linux distributions.

At least on my system, installing opam required sudo privilege, but everything else requires only ordinary user privileges.

I assume git is already installed.

opam

The first step is to install opam, the OCaml package manager. (We will also need m4, a tool used by certain packages to preprocess OCaml code).

If you already have opam installed, you can skip this step.

This invocation will vary based on your system.

On Debian:

apt-get install -y m4

At present, it is necessary to download the binary directly:

wget https://github.com/ocaml/opam/releases/download/2.0.3/opam-2.0.3-x86_64-linux

and put it somewhere in your PATH with the name opam.

On Ubuntu:

add-apt-repository ppa:avsm/ppa
apt update
apt install -y opam m4

For the Windows Subsystem for Linux, you should also apt install gcc, binutils-dev, make and pkg-config

On macOS (using Homebrew):

brew install -y opam m4

Or, if you prefer not to use Homebrew, you can download a binary directly (just put it somewhere in your PATH with the name opam):

wget https://github.com/ocaml/opam/releases/download/2.0.3/opam-2.0.3-x86_64-darwin

Initialize opam

Next we initialize the opam installation and pull down the latest OCaml compiler. This step will take a little while, because opam will build the OCaml compiler from source.

For the Windows Subsystem for Linux, you must also include --disable-sandboxing with opam init

opam init -y --compiler=4.07.1
eval $(opam env)

If you already have opam installed and initialized, do this instead to switch to 4.07.1:

opam switch create 4.07.1
eval $(opam env)

If you get an error like this:

bash[ERROR] Compiler selection '4.07.1' is ambiguous. matching packages: { ocaml-base-compiler.4.07.1, ocaml-system.4.07.1 }

pick the system one:

opam switch create ocaml-system.4.07.1
eval $(opam env)

Follow the prompts and put eval $(opam env) in the appropriate rcfile for your shell (eg ~~/.bashrc~) to set up paths and so forth. Alternatively, you can pass -a to opam init, and opam will set-up the files for you.

Update and upgrade

Update opam’s local cache of available packages and upgrade any packages already installed.

opam update -uy

Install libraries and tools from opam

Next we’ll install a set of basic libraries that you’ll need for this workshop:

opam install -y async core js_of_ocaml js_of_ocaml-ppx merlin utop ocp-indent

Test your installation

Test that you can build basic program

Clone this repo and cd to the directory with these instructions:

git clone https://github.com/janestreet/install-ocaml
cd install-ocaml/01-hello-world

Then build and run the hello_world program here, like so:

dune build hello_world.exe
dune exec ./hello_world.exe

This should print Hello, World.

Test that expect-tests work as intended

One pattern that we’ll make a lot of use of at the workshop is expect tests. If you’ve never heard of expect tests, check out our blog post for an overview.

cd to the 02-expect-tests directory in this repo and run this:

dune runtest

If the installation worked successfully, this should produce output that looks like this:

Done: 87/89 (jobs: 1)File "expect_test_example.ml", line 1, characters 0-0:
diff (internal) (exit 1)
(cd _build/default && /usr/bin/diff -u expect_test_example.ml expect_test_example.ml.corrected)
--- expect_test_example.ml      2018-02-26 01:37:02.000000000 +0000
+++ expect_test_example.ml.corrected    2018-02-26 04:36:48.800103324 +0000
@@ -2,5 +2,5 @@

 let%expect_test _ =
   let () = printf "foo" in
-  [%expect {| bar |}]
+  [%expect {| foo |}]
 ;;

This indicates a failed test because there is a diff between what we said the program would output (bar), and what it actually output (foo).

If the test is right and the program wrong, you would fix the program. But if it’s the test that’s wrong, accept the diff like so:

dune promote

This overwrites expect_test_example.ml with a corrected version that expects the output that the program actually produced in the previous run. Running the tests again will result in them passing:

dune runtest # no output
git diff # expect_test_example.ml has been overwritten

Set up your editor

vim and emacs

opam user-setup install

will set up vim and/or emacs (whichever ones you have installed) with syntax highlighting, indentation, go-to-definition and printing the types of expressions.

To learn more, visit https://github.com/OCamlPro/opam-user-setup.

Visual Studio Code

We recommend the vscode-reasonml plugin. Note that on the Windows Subsystem for Linux, it’s not presently possible to link merlin with VS Code running natively.

Troubleshooting

Error: No inline tests backend found

This is probably because you have an older version of core installed. To reinstall:

opam update -uy

and if the problem persists:

opam reinstall -y ppx_inline_test ppx_expect