OCaml Software
Setup

Installing OCaml and Related Tools

We will use opam, OCaml's package manager, to install OCaml as well as various libraries and tools.  We recommend (but do not require) the Visual Studio Code editor (referred to as VS Code).

This guide from ocaml.org provides a tutorial walk through for installing OCaml: 

Up and Running with OCaml

But before working through the general information above, read on for specific instructions we believe will work and suffice for CSE 341 based on our own experience.  Please speak up on the discussion board if you run into problems after following these steps carefully, so we can improve these notes.  If they don't make sense, please ask!

Here is what we have found to work:

1. Install opam

Windows (preferred method)

• Follow these instructions to install Windows Subsystem for Linux (WSL). 

  • WSL allows Windows developers to run a GNU/Linux environment directly on Windows without the overhead of a traditional virtual machine or dual-booting setup. 

  • Install WSL 2 if possible.

• To install make and cc, run this command:

  • sudo apt install build-essential

• Now follow the Linux, MacOS, and WSL instructions below.

Windows (alternate method)

• Follow the instructions from the OCaml for Windows project's page on installing opam on Windows. 

  • The 64-bit graphical installer is probably what you want.

  • If you get a virus-scan failure on the graphical-installer download, try "save link as" from an incognito browser window. 

• After installation completes (it takes a while), open the cygwin shell created in the previous step, called something like cygwin64 Terminal, and proceed to step 2.

  • If you already had cygwin installed, you now have a second one installed.  This is no problem, but you will need to keep track of "which is which" and open a terminal for the cygwin you just created here for the instructions that follow and whenever opening vscode.

Linux, MacOS, and WSL

• Follow the instructions on opam's official installation page mindful of the notes below.

• Note:  For MacOS, you need to have Xcode command line developer tools installed. You can install them using:       

  • xcode-select --install

•  Note:  For WSL, you need to have unzip installed and sandboxing disabled:  

  • If unzip is not installed, install it like so:
    sudo apt-get install unzip

  • To disable sandboxing do:

opam init --disable-sandboxing --reinit

• You may want to use your OS's package manager to install opam, but you can also directly install the binary distribution.

2. Use opam to install dune, utop, and ocaml-lsp-server

• Once opam is installed, install dune and utop by running this command:

  • opam install dune utop

  • If you get an error in the previous step of the form, " [ERROR] No switch is currently set. Please use 'opam switch' to set or install a switch", there are various workarounds, but this has worked for people (note in the future the ocaml version number may be different, but this is current as of January 2022).

    • First run this command: 

opam switch create ocaml-base-compiler.4.13.1 

• • • Then again try:

opam install dune utop

• If you use VS Code (see more below), you will also want ocaml-lsp-server, so run this command:

opam install ocaml-lsp-server

You can learn more about managing your opam installation from the opam usage guide, but you don't need to.

Alternatively, instead of installing everything on your system, you can choose to use attu (remote CSE Linux cluster, available to CSE students only), which has an OCaml installation. From a terminal, run ssh <CSENetID>@attu.cs.washington.edu and use your CSE login as the password. VS Code also has SSH support (instructions below). However, the OCaml version installed by default on attu might be outdated, which could be an issue on some assignments. You can, if needed, follow these instructions to install an up-to-date version of OCaml in your attu home directory.

As yet another alternative, OCaml should already be installed on the CSE lab machines.

As a final alternative, The UW CSE Virtual Machine is a CentOS Linux set up to approximate the set up on Allen School lab computers. Roughly speaking, it will let you run a fresh, full-fledged Linux machine as if it was just another application. If you are struggling to set up software on your personal computer, you may have better luck by:

• Setting up the UW CSE VM and then

• Following the installation instructions for Linux above.

3. [Optional-but-possibly-helpful] Configure utop as used in lecture

You can do either or both of these things:

• By default, utop presents a lot of information that can be more distracting than helpful in a class where we are focusing on fundamentals.  We can remove most of this "clutter" as follows:

  • In your home directory (at a terminal, type cd then return to get to your home directory), make a directory .config (notice the period as the first character of the directory) with the command mkdir .config).

  • Then inside that directory make a directory utop (you can do mkdir .config/utop).

  • In .config/utop, make a file named init.ml (you can use VSCode to make it after installing VSCode below, but any text editor will do).

  • Make the contents of init.ml exactly these two lines:
    #utop_prompt_dummy;;

UTop.set_show_box false

• By default, utop doesn't syntax highlight (use colors).  This is not a big deal since we do not tend to write a lot of code directly in utop, but you can get syntax highlighting as follows:

  • In your home directory (at a terminal, type cd then return to get to your home directory), make a file named .utoprc (you can use VSCode to make it after installing VSCode below, but any text editor will do). In that file, you can use content like this, which are the colors used in class -- they work well for "light mode" but won't work well for "dark mode".

profile:                  light

identifier.foreground:    none

module.foreground:        x-forestgreen

comment.foreground:       x-firebrick

doc.foreground:           x-violetred4

constant.foreground:      x-darkcyan

keyword.foreground:       x-purple

symbol.foreground:        x-purple

string.foreground:        x-violetred4

char.foreground:          x-violetred4

quotation.foreground:     x-purple

error.foreground:         red

directive.foreground:     x-mediumorchid4

parenthesis.background:   light-blue

Installing Visual Studio Code (VS Code) and Extension(s)

Install VS Code

The VS Code website provides installers for Windows, Linux, and MacOS.

Note: if you installed OCaml via WSL on Windows, follow these instructions to develop in WSL using VS Code. This will let you edit files in WSL using VS Code and use the terminal in WSL to use your OCaml installation.

Install the OCaml Extension

• VS Code provides many extensions to better support developing programs in various languages.

• If you want, you can read the general instructions on how to install an extension, but if you just want to install the extension for OCaml support, you should be able to skip that.

• The key thing is to install the OCaml Platform extension by OCaml Labs.  You can probably just click the big green Install button.

Opening VS Code -- Crucial Information for Windows Users (Cygwin)

On Mac, Linux, and WSL, you should be able to open VS Code however you want and have the OCaml Extension work correctly with the utop REPL, etc.  

But on Windows without WSL (i.e., if you are in Cygwin), the bottom of the OCaml "up and running" instructions contain this key information: On Windows, we must launch Visual Studio Code from within the Cygwin window, rather than by clicking on its icon (otherwise, the language server will not be found):

$ /cygdrive/c/Users/Frank\ Smith/AppData/Local/Programs/Microsoft\ VS\ Code/Code.exe

In other words, do not launch VS Code like a normal application.  Instead, every time you want to launch VS Code open the cygwin terminal and type something like the above, replacing "Frank\ Smith" with your Windows account name on the computer you are using.  

However, that can be annoying, so here is a slightly less annoying approach.  You just have to take these steps one time:

• Open a new cygwin terminal window.

• Type  pwd to find the location of your home directory.  If it says /home/YourName, then your home directory is probably something like C:\OCaml64\home\YourName.  

• In that directory is a file named  .bash_profile (notice the file name starts with a period).

• Open this .bash_profile file in the text editor of your choice.  (You can even use VS Code if you like.)  At the bottom of the file, add this, of course replacing Your\ Name with your Windows account name: 

alias vscode="/cygdrive/c/Users/Your\ Name/AppData/Local/Programs/Microsoft\ VS\ Code/Code.exe"

Now every time you want to open VS Code and use utop within it, you still need to open a cygwin terminal, but now you can just type vscode and hit return.

If using attu

If you chose to use attu, install the Remote-SSH extension to develop on attu within VS Code.

UW CSE VM

The UW CSE Virtual Machine is a CentOS Linux set up to approximate the set up on Allen School lab computers.

Roughly speaking, it will let you run a fresh, full-fledged Linux machine as if it was just another application.

If you are struggling to set up software on your personal computer, you may have better luck by:

• setting up the UW CSE VM and then

• following the installation instructions for Linux above