Installing OCaml for 3110

You need to have a working installation of OPAM, the OCaml Package Manager, version 1.2.2. You have a choice: you can install OPAM natively on your own operating system, or you can download a Unix virtual machine (VM) that we provide in which OPAM is already installed.

For Linux or OS X, we suggest trying a native installation first. If that doesn't work out, download the VM instead.
For Windows, we suggest that you install the VM. A semi-native installation is possible, but it will require some additional system administration, and it will not blend as nicely with the rest of your OS as you might like. You could also dual-boot Windows and Ubuntu, but that requires some significant system administration.

Regardless of which you choose, once you get an installation working keep it working throughout the semester by being cautious about any updates you apply to your system. Don't perform any major OS upgrades just before an assignment is due, for example.

VM installation

WARNING: Do not use a VM from an old edition of CS 3110. Only the Spring 2018 VM will be supported this semester.

Download and install VirtualBox for your operating system. Make sure you have the latest version before proceeding.
Download 3110 virtual machine (that hyperlink will become active shortly before the semester starts) and save the .ova file wherever you like.
Import the virtual machine:
- Run VirtualBox.
- Select File → Import Appliance
- Choose the .ova file you just downloaded and import it.
Run the virtual machine:
- Select vm3110-2018fa from the list of machines in VirtualBox.
- Click Start.
Login with username vagrant and password vagrant.

(In case you're curious, this is the standard username/password on a VM built with Vagrant, which is what we use to automate our production of the VM. In fact, you can see the scripts we use to build the VM in this GitHub repo. If you'd rather have a user account on the VM with your own username rather than vagrant, you are welcome to create a new account. But be aware that OPAM and Atom won't be configured for that user. The instructions to do that initialization can be found below under "OPAM configuration" and "Atom configuration".)
To launch the OCaml toplevel:
- Start a terminal by choosing the 4th icon down from the top in the launcher on the left-hand side of the desktop.
- Run utop. Enter 3110;; followed by the Enter key to evaluate the integer 3110. Stop to appreciate how good an integer it is.
- Enter #quit;; or Control-D to exit the toplevel.
When you use VirtualBox to close the VM, you will be presented with three choices:
- Save the machine state. This choice is what you normally want. It's like closing the lid on your laptop: it puts it to sleep, and it can quickly wake.
- Shutdown the machine. This choice is like shutting down your OS. When you start the machine again later, it will have to boot from scratch, which takes longer.
- Power it off. This choice is dangerous. It is the equivalent of pulling the power cord of a desktop machine from the wall: it causes the operating system to suddenly quit without doing any cleanup. Doing this even just a handful of times could cause the file system to become corrupted, which will cause you to lose your source code. You will be very unhappy.
You are eventually going to want to enable the shared clipboard and shared folders, and now would be a good time to do that.
- With the VM running, in the Virtual Box menu bar, click Devices->Shared Clipboard->Bidirectional.
- Then click Devices->Shared Folders->Shared Folder Settings.
  - Click the little icon on the right that looks like a folder with a plus sign.
  - In the dialog box, select a Folder Path. This is the folder on your host OS (your own native OS, perhaps Windows) that you want to share with the guest OS (the Ubuntu OS that is running inside Virtual Box). Let's assume you created a new folder named vmshared inside your Documents folder, or wherever you like to keep files.
  - The Folder Name in the dialog box will automatically be filled with vmshared. This is the name by which the guest OS (Ubuntu) will know the folder. You can change it if you like.
  - Check Auto-mount; do not check Read-only.
  - Reboot the VM by clicking on the icon at the very top-right of the Ubuntu desktop, clicking Shut Down..., and clicking Restart (the left button).
  - Open Nautilus (the Ubuntu file browser) by clicking the second-icon from the top in the launcher on the left. You should now see a folder in the left-hand list named sf_vmshared. That folder is now shared between the host OS and the guest OS. You can use it to easily transfer files between the two.
You're done!

Native installation: OS/X

Install either MacPorts or homebrew as a Unix package manager. These instructions will assume MacPorts.

If you previously installed one of them and later upgraded your OS X version be especially careful: these package managers don't survive such upgrades easily. Make sure your package manager is in working order and fully up-to-date before proceeding. With MacPorts, that means running sudo port selfupdate followed by sudo port upgrade outdated. If there are any errors, you need to resolve them before proceeding. Often the easiest way to do that is to uninstall the package manager then reinstall it from scratch.

Run sudo port install m4 ocaml opam.
Continue with the instructions under "OPAM configuration" below.

Native installation: Linux

Use your distribution's package manager to install OPAM. The OPAM installation page has detailed instructions for many popular package managers.
Continue with the instructions under "OPAM configuration" below.

Semi-native installation: Windows

Follow Microsoft's instructions to install the Windows Subsystem for Linux. (If you are on a Windows Insider release, we will assume you have installed an Ubuntu subsystem.)

Inside the Windows bash shell, run the following commands:

sudo apt-get update
sudo apt-get upgrade
sudo apt-get install m4 ocaml ocaml-native-compilers camlp4-extra opam

Continue with the instructions under "OPAM configuration" below.

Dual-boot installation: Windows and Linux

If your hardware is not powerful enough to run the VM inside Windows without significant lag, you could consider dual-booting Windows and Linux. (We recommend Ubuntu 16.04, because that's what the VM is based on, but you could choose another Linux distribution.) There are many guides you could find online for how to do that, but this is getting into territory that we are unable to support. You should certainly make a backup of your entire Windows system before attempting to get dual-booting working, just in case something goes wrong. If you do get it working, you can follow the instructions above for a native installation on Linux.

OPAM configuration

You do not need to follow these instructions if you are using the VM. We have already done them for you.

Check your OPAM version by running opam --version. If that reports anything other than 1.2.2, you need to update your OPAM version: try opam update followed by opam upgrade. If that doesn't work, seek further help in person from the course staff.

Run the following command to initialize OPAM:

# Note: do NOT prefix this command with sudo
opam init -a -y

Enter the following commands to switch OPAM to the OCaml 4.06.0 compiler:
```
# Note: do NOT prefix these commands with sudo
opam switch -y 4.06.0
eval `opam config env`
```
Now check your compiler version by running opam switch show. If that reports anything other than 4.06.0, something has gone wrong. Seek further help in person from the course staff. Be aware that OCaml version 4.06.0 is the only supported version of the OCaml compiler in CS 3110 this semester. All your code must compile under that version.

Enter the following commands to install some OPAM packages that will be needed for CS 3110.

# Note: do NOT prefix these commands with sudo
opam install -y utop ounit qtest yojson lwt menhir ansiterminal lambda-term merlin ocp-indent user-setup
opam user-setup install

Check that you can run OCaml. Run utop to launch the OCaml toplevel. Enter 3110;; followed by the Enter key to evaluate the integer 3110. Stop to appreciate how good an integer it is. Then enter #quit;; or Control-D to exit the toplevel.
You're done! But if you want to configure the Atom text editor for OCaml, continue with the instructions below.

Atom configuration

You do not need to follow these instructions if you are using the VM. We have already done them for you.

The Atom editor offers excellent integration with OCaml, including syntax highlighting, auto-completion, and auto-indentation. After installing OPAM (including the packages above, particularly merlin and ocp-indent), and after installing Atom, you'll need to install some packages inside Atom itself.

Open the Settings view with Control-, or Command-, depending on your OS.
Click on the Install tab.
Search for and install these packages: language-ocaml, ocaml-merlin, ocaml-indent, and linter. Also install any dependencies that are automatically discovered.
Check that the OCaml integration is working by saving a file with a .ml extension. Atom should now give you the features mentioned above. For example, entering let x:string = 42 should (i) suggest some completions while you are typing, (ii) colorize the syntax as you type, and (iii) indicate a type error with a squiggle under the 42.

Need help?

The course staff is happy to help you out with any trouble you might have. It is far easier to diagnose problems in person, so we ask that you come to office hours rather than post on Piazza.