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

    #+BEGIN_SRC bash
    apt-get install -y m4
    #+END_SRC

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

    #+BEGIN_SRC bash
    wget https://github.com/ocaml/opam/releases/download/2.0.3/opam-2.0.3-x86_64-linux
    #+END_SRC

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

    On Ubuntu:

    #+BEGIN_SRC bash
    add-apt-repository ppa:avsm/ppa
    apt update
    apt install -y opam m4
    #+END_SRC

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

    On macOS (using Homebrew):

    #+BEGIN_SRC bash
    brew install -y opam m4
    #+END_SRC

    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~):

    #+BEGIN_SRC bash
    wget https://github.com/ocaml/opam/releases/download/2.0.3/opam-2.0.3-x86_64-darwin
    #+END_SRC

*** 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~

    #+BEGIN_SRC bash
    opam init -y --compiler=4.07.1
    eval $(opam env)
    #+END_SRC

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

    #+BEGIN_SRC bash
    opam switch create 4.07.1
    eval $(opam env)
    #+END_SRC

    If you get an error like this:
    #+BEGIN_SRC
    bash[ERROR] Compiler selection '4.07.1' is ambiguous. matching packages: { ocaml-base-compiler.4.07.1, ocaml-system.4.07.1 }
    #+END_SRC
    pick the system one:

    #+BEGIN_SRC bash
    opam switch create ocaml-system.4.07.1
    eval $(opam env)
    #+END_SRC

    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.

    #+BEGIN_SRC bash
    opam update -uy
    #+END_SRC

* Install libraries and tools from ~opam~
  Next we'll install a set of basic libraries that you'll need for this
  workshop:

  #+BEGIN_SRC bash
   opam install -y async core js_of_ocaml js_of_ocaml-ppx merlin utop ocp-indent
  #+END_SRC

* Test your installation
** Test that you can build basic program
   Clone this repo and ~cd~ to the directory with these instructions:

   #+BEGIN_SRC bash
   git clone https://github.com/janestreet/install-ocaml
   cd install-ocaml/01-hello-world
   #+END_SRC

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

   #+BEGIN_SRC bash
   dune build hello_world.exe
   dune exec ./hello_world.exe
   #+END_SRC

   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 [[https://blog.janestreet.com/testing-with-expectations/][our blog post]] for an
   overview.

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

   #+BEGIN_SRC bash
   dune runtest
   #+END_SRC

   If the installation worked successfully, this should produce output that
   looks like this:
   #+BEGIN_SRC bash
     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 |}]
      ;;
   #+END_SRC

   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:

   #+BEGIN_SRC bash
   dune promote
   #+END_SRC

   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:

   #+BEGIN_SRC bash
   dune runtest # no output
   git diff # expect_test_example.ml has been overwritten
   #+END_SRC
* Set up your editor
** vim and emacs
   #+BEGIN_SRC bash
    opam user-setup install
   #+END_SRC

   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 [[https://github.com/reasonml-editor/vscode-reasonml][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:

   #+BEGIN_SRC bash
    opam update -uy
   #+END_SRC

   and if the problem persists:

   #+BEGIN_SRC bash
    opam reinstall -y ppx_inline_test ppx_expect
   #+END_SRC