Having thoroughly enjoyed delving into ReasonML recently I was curious to learn more about OCaml itself. For those of you unaware ReasonML is a alternative syntax for OCaml. The main motivation has been to develop front-end web applications with OCaml semantics in a syntax reminiscent of Javascript (and ultimately compiling to Javascript using the Bucklescript toolchain).

OCaml encourages a functional approach and has a extremely good type inference while still allowing non-functional approaches when practicalities call for it.

I have been developing a side-project in OCaml in VSCode and wanted to share my experience on this.

Install OCaml and OPAM

First step is to install the OCaml compiler itself. If you already have OCaml and an existing project you can skip this step.

Instuctions are detailed on the OCaml site. Follow the instructions for your environment.

I am using Windows (specifically WSL) so I follow the Ubuntu instructions:

apt install ocaml

We will also need OPAM which is a package manager for OCaml. We will need to use this to install Merlin and Ocpindent later

Instructions can be found here for v1 and here for v2. OPAM will soon be making the switch to 2.0.0. The rest of the article assumes OPAM v2.0.0.

apt-get install opam

We need to initialize OPAM globally (you will be prompted, I accepted the defaults)

opam init 

Or if you are using WSL which does not yet support sandboxing (it will complain about a missing bubblewrap dependency) you can instead run the following to disable.

opam init --disable-sandboxing

Update the current shell environment

eval $(opam env)

Create a new project

mkdir ocaml-project
cd ocaml-project

We will make a switch for this project. This essentially allows specific versions of packages and the compiler to be used just for this project. To do this run the following (for OPAM 2.0.0)

opam switch create . ocaml-base-compiler.4.05.0

This will download and recompile any dependencies with the above compiler version. If any fail you may have missing system dependencies. Myself, when running this, I was missing m4 - this was easily fixed by installing via the OS package manager (in my case apt-get).

There are two other tools we will need to install to fully support VSCode OCaml IDE functions

Merlin

Merlin provides services such as autocompletion to IDEs such as VSCode

opam install merlin

Merlin will be aware of any third party libraries installed via OPAM from its .merlin file. See the Merlin documentation on how to configure this. Build tools such as Dune will typically manage this for you.

Ocpindent

Ocp-indent is a tool for auto-formatting OCaml code

opam install ocp-indent

Out-of-the box defaults work fine for me but can be configured further. See ocp-indent's documentation on configuration options.

VS Code setup

We are going to use the OCaml and Reason IDE extension. This can be installed directly from VSCode by searching for "OCaml and Reason IDE".

If you are using ReasonML in parallel I strongly suggest following the extension's suggested config options in Code > Preferences > Settings. If using WSL this looks like:

    "reason.path.env": "bash -c env",
    "reason.path.bsb": "bash -ic bsb",
    "reason.path.ocamlfind": "bash -ic ocamlfind",
    "reason.path.ocamlmerlin": "bash -ic ocamlmerlin",
    "reason.path.opam": "bash -ic opam",
    "reason.path.rebuild": "bash -ic rebuild",
    "reason.path.refmt": "bash -ic refmt",
    "reason.path.refmterr": "bash -ic refmterr",
    "reason.path.rtop": "bash -ic rtop",
    "reason.diagnostics.tools": [
        "merlin",
        "bsb"
    ],
    "editor.formatOnSave": true,
    "reason.codelens.enabled": true,

As OPAM 2.0.0 installs libraries within the project directory (./_opam) and the .merlin file needs to know about these to provide autocompletion for third party libraries I configured the below Workspace settings (Ctrl+P > Workspace Settings) for each of my OCaml projects

{
  "reason.path.ocamlmerlin": "bash -ic ./_opam/bin/ocamlmerlin",
  "reason.path.ocamlfind": "bash -ic ./_opam/bin/ocamlfind",
  "reason.path.ocpindent": "bash -ic ./_opam/bin/ocp-indent",
  "reason.diagnostics.tools": [
    "merlin"
  ],
}

You should now have autocompletion, mouse-over type definitions and codelens enabled for .ml and .mli files in your project.

Troubleshooting

Check the following if you are still not seeing the expected IDE functionality (eg mouse-over definitions, autocompletion):

1. Check that sourcing your .bashrc is "silent". Any output either from echos or errors will be picked up by the plugin when it tries to run merlin. I think this should only be a problem for Windows users
2. Make sure that you are using bash on Windows
3. Check that your ./_opam/bin/ directory is in your PATH
4. Check that CAMLLDLIBRARYPATH and OCAMLTOPLEVEL_PATH envs are set in your shell when inside your project directory. If they are not check that OPAM envs are being sourced in your .bashrc (this is typically added during opam init)
5. Ensure that you have a .merlin file
6. Make sure that your .merlin file has the correct absolute paths to your libraries (most of the time should be libraries installed in ./_opam/lib
7. Make sure you have restarted VSCode after any changes

Let me know how you get on and if there is anything worth adding to the guide