Installing OCaml for 3110

You need to have a working installation of OPAM, the OCaml Package Manager. Any version greater than or equal to 1.2.2 should be fine. 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, install 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.

Click on the installation method below that you want to use. If you get stuck, please follow the instructions under “Need help?”.

• VM installation
• Native installation: OS/X
• Native installation: Linux
• Semi-native installation: Windows
• Dual-boot installation: Windows and Linux
• OPAM configuration
• VS Code configuration
• Need help?

VM installation

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

With Virtual Machines, there are two operating systems involved: the host operating system (OS) and the guest OS. The host is your own native OS (probably Windows). The guest is the OS that runs “inside” the host. We provide a Linux guest OS in the 3110 VM.

• Download and install VirtualBox for your host OS. Or, if you already had it installed, make sure you update to the latest version of VirtualBox before proceeding.

• Go to the 3110 virtual machine download page (that hyperlink will become active shortly before the semester starts). Don’t worry about the “We’re sorry, the preview didn’t load” message you see at that link. Click the Download button and save the .ova file wherever you like. It’s about a 4GB file, so the download might take awhile.

• Import the virtual machine:

  • Run VirtualBox.

  • Select File → Import Appliance

  • Choose the .ova file you just downloaded. Click Next, then Import.

• Run the virtual machine:

  • Select vm3110-2019sp from the list of machines in VirtualBox.

  • Click Start.

  • If you get an error about “VT-x/AMD-V hardware acceleration”, you most likely need to enter your computer’s BIOS settings and enable virtualization. The details of that will vary depending on the model and manufacturer of your computer. If you get stuck, please see a consultant for help.

• 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 VS Code won’t be configured for that user. The instructions to do that initialization can be found below under “OPAM configuration” and “VS Code configuration”.)

• To launch the OCaml toplevel:

  • Start a terminal by choosing the 2nd 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.

  • Send the shutdown signal. This choice is like shutting down a machine you don’t intend to use for a long time, or before unplugging a desktop machine from the wall. When you start the machine again later, it will have to boot from scratch, which takes longer.

  • Power off the machine. This choice is dangerous. It is the equivalent of pulling the power cord of a desktop machine from the wall while the machine is still running: 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 and have to reinstall the VM from scratch. You will be very unhappy.

• Now setup a shared folder between the host and guest OS.

  • With the VM shutdown (i.e., select “send the shutdown signal”), click Settings, then click Shared Folders in the list on the left.

    • 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 that you want to share with the guest OS. 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 will know the folder. You can change it if you like.

    • Check Auto-mount (and Make Permanent, if the option is available); do not check Read-only. Click OK, then click OK again.

    • Start the VM again.

    • You should now see a folder on the desktop named sf_vmshared. That folder is shared between the host OS and the guest OS. You can use it to easily transfer files between the two.

• You’re done!

• If you wish, you can safely delete the .ova file you downloaded to free up some space.

• You might be able to improve the performance of your VM by increasing the amount of memory or CPUs allocated to it, though it depends on how much your actual machine has available and what else you have running at the same time. With the VM shut down, try going in Virtual Box to Settings → System, and tinkering with the Base Memory slider on the Motherboard tab, and the Processors slider on the Processor tab. Then bring up the VM again and see how it does. You might have to play around to find a sweet spot.

Native installation: OS/X

You need a Unix package manager. There are two popular managers on Mac, MacPorts and Homebrew. The instructions below assume MacPorts. Whatever you do, do not install both. They do not play nicely together.

If you previously installed one of them, make sure it 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.

If you’re starting from scratch, here’s what to do:

• Follow the MacPorts install instructions:

  • First install Xcode, the Xcode command line tools, and accept the Xcode EULA.
  • Then install XQuartz. Although the MacPorts instructions say that step is optional, you can save yourself a lot of potential future trouble by doing it now.
  • Finally, install MacPorts itself.

• 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. If you’re on a recent version of Ubuntu, note that you don’t actually need to add the avsm PPA. The packages are now available in the standard apt sources.

• Continue with the instructions under “OPAM configuration” below.

Semi-native installation: Windows

• Follow Microsoft’s instructions to install the Windows Subsystem for Linux. Install the 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 opam
  

• Continue with the instructions under “OPAM configuration” below.

• Your best choice of editor is either vim or emacs installed inside the Ubuntu subsystem. Using Windows GUI apps to write to files stored in the Ubuntu subsystem is recommended against by Microsoft.

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 18.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 less than 1.2.2, you need to update your OPAM version: try opam update followed by opam upgrade. If that doesn’t work, follow the instructions under “Need help?” below.

• 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.1 compiler:

  # Note: do NOT prefix these commands with sudo
  opam switch -y 4.06.1
  eval `opam config env`
  

  Now check your compiler version by running opam switch show. If that reports anything other than 4.06.1, something has gone wrong; follow the instructions under “Need help?” below. Be aware that OCaml version 4.06.1 is the only supported version of the OCaml compiler in CS 3110 this semester. All your code must compile under that version. It is not the most recent release of OCaml (which is 4.07.0 and was released in July), because this summer during testing we discovered that some packages we intended to use this semester had not yet been updated to work with 4.07.0.

• Enter the following commands to install some OPAM packages that will be needed for CS 3110. Make sure to grab the entirety of the first line, which is quite long.

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

• Close the terminal you were in. Open a new terminal. 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.

• Double check your OPAM environment by downloading this script and running bash checkenv.sh from the terminal in the directory in which the script is saved. If it reports any errors, follow the instructions under “Need help?” below.

• You’re done! But if you want to configure the VS Code text editor for OCaml, continue with the instructions below.

VS Code configuration

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

The Visual Studio Code editor is our current recommendation for the best OCaml experience in a modern editor. After installing OPAM, and after installing VS Code, you’ll need to install some packages inside the editor itself.

• Open VS Code and click on the bottom icon on the left-hand side to open the extension pane.

• Search for “OCaml” in the extensions marketplace. Find the extension named “OCaml and Reason IDE”. (Note: not the extension simply named “OCaml”) Click Install. If the Reload button then appears, click it.

• Check that the OCaml integration is working by saving a file with a .ml extension. Try entering let x:string = 3110 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 3110. Click on the “Problems” pane or hover over the squiggle to see the error. Put double quotes around 3110 to fix the error.

• We recommend that you open the user settings (Preferences → Settings) and add the following settings:

      "editor.tabSize": 2,
      "editor.rulers": [ 80 ],
      "editor.formatOnSave": true
  

  A tab size of 2 spaces is fairly standard in the OCaml community. The ruler at column 80 will help you not go over the maximum column length, and you could even set it to 78 or 72 if you prefer. The formatOnSave setting will cause your code to be run through a tool called ocp-indent each time you save. That tool re-indents your code according to some fairly good standards, thus will help keep your code beautiful. Note that you can run that tool anytime by right-clicking and selecting “Format Document”, and that there is a shortcut key for it too (which you will see next to “Format Document”).

Need help?

The course staff is happy to help you out with any trouble you might have. We ask that you come visit a consultant during office hours for that help, because it is far more efficient to provide this kind of technical support in person. Please refrain from posting on Piazza, which creates noise that other students will be forced to filter out.