Instructions for setting up an OCaml development environment
Switch branches/tags
Nothing to show
Clone or download
Latest commit 9feff66 Mar 19, 2018
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
01-hello-world Setup instructions and test programs Mar 19, 2018
02-expect-tests Setup instructions and test programs Mar 19, 2018
.gitignore Setup instructions and test programs Mar 19, 2018
README.org tweaks Mar 19, 2018

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.2
  • Debian 9.3
  • Fedora 27
  • Ubuntu 16.04.3 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 and Ubuntu:

apt-get install -y opam m4

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/1.2.2/opam-1.2.2-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.

opam init -y --compiler=4.06.1
eval `opam config env`

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

opam switch 4.06.1
eval `opam config env`

Follow the prompts and put eval `opam config env` in the appropriate rcfile for your shell (eg ~~/.bashrc~) to set up paths and so forth.

Update and upgrade

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

opam update -y && opam upgrade -y

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:

jbuilder build hello_world.exe
jbuilder 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:

jbuilder 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:

jbuilder 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:

jbuilder runtest # no output
git diff # hello_world.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.

Troubleshooting

Error: field inline_tests needs a value

This is probably because you have an older version of jbuilder installed. To upgrade:

opam update -y && opam upgrade -y

Make sure you have version 1.0+beta19 or later:

jbuilder --version

Error: No inline tests backend found

This is probably because you had core installed before getting a version of jbuilder that supported inline tests. To reinstall:

opam update -y && opam upgrade -y
opam reinstall -y ppx_inline_test ppx_expect