Installing OCaml for 3110

These installation instructions assume a basic working knowledge of the “command line” or “terminal”, which is used (e.g.) in CS 1110. If you need to brush up on the command line, it would be a good idea to google for a tutorial.

You need to have a Unix development environment with a working installation of OPAM, the OCaml Package Manager, version 2.x. You have a choice: you can install these on your own operating system, or you can download a Linux virtual machine (VM) that we provide.

• For Linux or Mac OS X, we suggest trying a native installation first. If that doesn’t work out, install the VM instead.

• For Windows, we suggest trying a semi-native installation first. This is a new and experimental possibility; we haven’t been able to support it before in 3110. It’s made possible this semester by some advances that Microsoft has recently made with integration of Linux and Windows. We hope it works out, but please bear in mind that it’s new to the course staff, so we might not have all the answers right away. If it doesn’t work out, you can still use the VM, which is what we’ve recommended in the past for Windows.

Regardless of what 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
• Semi-native installation: Windows
• Native installation: OS X
• Native installation: 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 Fall 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-2019fa 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.

• You can use the guest OS’s own interface to safely shutdown or reboot the VM. But more often you will likely use VirtualBox to close the VM by click the VM window’s “X” icon in the host OS. Then 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.

    • 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; do not check Read-only. Make the Mount Point /home/vagrant. Click OK, then click OK again.

    • Start the VM again.

    • You should now have a subdirectory named vmshared in your home directory. It 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.

Semi-native installation: Windows

Overview: We’re going to install a Linux environment inside Windows 10. Microsoft calls it the “Windows Subsystem for Linux” (WSL). Then we’ll install inside OPAM inside WSL. Here is an (optional) introduction to what WSL is and why you need it.

• Don’t skip this first step: in beta testing of these instructions, most problems resulted from having older builds.

  Check your Windows build. To do that, click Start, type winver, and press Enter. A dialog box will open. Look on the second line for “OS Build XXXXX.YYY”. If the XXXXX part of that is a number smaller than 17643, you must update Windows now: go to “Settings → Update & Security → Windows Update → Check for updates” and install updates. When finished, run winver again to double check that the build is 17643 or greater.

  If you can’t get a recent build—perhaps because your hardware is a bit older—you’ll need to install the VM. You could try these instructions to install WSL on older builds. But, (i) we don’t know whether they will work, and (ii) you still might have unknown troubles installing OPAM.

• Open Windows PowerShell as Administrator. To do that, click Start, type PowerShell, right click on “Windows PowerShell” (which should be at the top as the best match), and click “Run as administrator”. Click Yes to allow changes.

• At the prompt (which is probably something like PS C:\windows\system32>), enter the following command:

  Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux
  

• If you are prompted to restart, do so. Otherwise, close PowerShell.

• Click Start, type Microsoft Store, and open the Microsoft Store app. Click Search, and type Ubuntu. Scroll down to Apps, and choose Ubuntu, which should be the first result. (Make sure to chose “Ubuntu” not “Ubuntu 16.04 LTS”. In theory “Ubuntu 18.04 LTS” would be fine, because that’s what “Ubuntu” ought to install anyway.) From the Ubuntu page, click Get. After the download finishes, click Launch. The install will then finish.

• You will be prompted to create a UNIX username and password. You can use any username and password you wish. It has no bearing on your Windows username and password (though you are free to re-use those). You will need to remember the password for future use.

• You will now be inside a terminal at the Bash shell. The prompt will look something like

  user@machine:~$
  

  You’ll want to make sure copy-and-paste into the terminal is enabled: Click on the icon on the top left of the shell window, click Properties, and make sure “Use Ctrl+Shift+C/V as Copy/Paste” is checked. (If you don’t see that option, your Windows build is too old. Make sure you updated Windows to a new enough build, as described above. Right-click might still work to paste even if you don’t have a new enough build.) Now Ctrl+Shift+C will copy and Ctrl+Shift+V will paste into the terminal. Note that you have to include Shift as part of that keystroke.

• Enter the following command into the shell:

  sudo apt update
  

  You will be prompted for the UNIX password you chose. The command that you are running is updating the APT package manager, which is what helps install software inside WSL. The prefix sudo means to run the command as the administrator, aka “super user”. In other words, do this command as super user, hence, “sudo”.

  Pro-tip: Running commands with sudo is potentially dangerous and should not be done lightly. Do not get into the habit of putting sudo in front of commands.

• Now run this command to upgrade all the APT software packages; it will take awhile. If you are prompted about configuring libssl, just hit Enter to accept the default choices.

  sudo apt upgrade -y
  

• Run this command to install some additional packages:

  sudo apt install -y m4 unzip bubblewrap build-essential
  

• WSL has its own filesystem that is distinct from the Windows filesystem. You can edit Windows files from WSL, but you cannot edit WSL files from Windows. So we need to create a Windows directory in which you will store all your 3110 work. Go ahead and do that with the Windows File Explorer wherever you like. For example, you might create a new folder in your Documents called 3110.

• Now from the WSL Bash shell, run this command to make your 3110 folder easily accessible from WSL:

  ln -s /mnt/c/Users/<windows user name>/Documents/3110 ~
  

  Replace <windows user name> with whatever your Windows user name is. If you’re not sure, go to the Windows Start Menu and type cmd. A Windows shell will open, and the prompt should be C:\Users\<windows user name>. If you chose a different folder name in the previous step, then replace Documents/3110 with whatever you chose. You 3110 Windows folder will now be accessible from your WSL home directory.

  For more information about the differences between the Windows and WSL filesystems, and how to work with them, see this guide.

• Install OPAM by running these commands:

  wget https://github.com/ocaml/opam/releases/download/2.0.5/opam-2.0.5-x86_64-linux
  sudo mv opam-2.0.5-x86_64-linux /usr/local/bin/opam
  sudo chmod a+x /usr/local/bin/opam
  

  (You might wonder why we’re not installing OPAM through APT. The problem is that APT has OPAM version 1, not version 2. So we have to manually install OPAM instead of using APT to do it automatically.)

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

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. The instructions for that are given on the MacPorts install page linked above.
  • Before proceeding with the MacPorts install, pause to install XQuartz. Technically this step is optional, but you can save yourself some potential future trouble with OCaml graphics packages by doing it now.
  • Finally, resume following the instructions on the MacPorts install page, and install MacPorts itself.

• Open a Terminal. Run sudo port install opam.

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

Native installation: Linux

• It’s best to use your distribution’s package manager to install OPAM. The OPAM installation page has detailed instructions for many popular package managers. Unfortunately, not all distributions make the latest version of OPAM available. If you can’t get v2.0.5 through your package manager, we suggest that you instead follow the instructions at the top of the OPAM install page to install a binary.

• Note that in our testing this August, we discovered that OPAM v2.0.3 on Ubuntu has a configuration bug that makes it impossible to install OCaml 4.08.1. That’s why we recommend above getting OPAM v2.0.5 as a binary.

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

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. That ought to report that you have OPAM version 2, e.g., 2.0.5. If you instead have version 1, e.g., 1.2.2, you have to fix that before proceeding. Follow the instructions under “Need help?” below.

• If you have ever had OPAM installed before this semester, we highly recommend that you start fresh instead of trying to upgrade an earlier install. To start fresh, all you have to do is delete the directory ~/.opam, or, move it to a different location—e.g., mv ~/.opam ~/.opam.bak.

• This step varies depending on whether you are running on Windows, or on OS X or Linux.

  On Windows (WSL), run the following command to initialize OPAM:

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

  (We have to disable sandboxing because of an open OPAM issue related to WSL. Hopefully that will be fixed in the future.)

  On OS X or Linux, run this command:

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

• Enter the following commands to switch OPAM to the OCaml 4.08.1 compiler:

  # Note: do NOT prefix these commands with sudo
  opam switch create 4.08.1 ocaml-base-compiler.4.08.1
  eval $(opam env)
  

  If you get an error about 4.08.1 not being a known compiler version, try running opam update.

  Now check your compiler version by running opam switch show. If that reports anything other than 4.08.1, then something has gone wrong; follow the instructions under “Need help?” below. Be aware that OCaml version 4.08 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. 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_ppx-ocamlbuild
  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.

• Continue with the instructions below to configure the VS Code editor for OCaml.

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 (VS 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.

• Download and install VS Code.

• Open VS Code. If you are on Windows (WSL), make sure to open VS Code by running code . in a WSL terminal, not by double-clicking the desktop icon in Windows. VS Code should automatically recommend that you now install the “Remote WSL” extension. Do that now.

• Go to View → Extensions. Search for “OCaml and Reason IDE”. (Note: you do not want the extension simply named “OCaml”; it is obsolete.) Selection the extension, and click Install. If the “Reload Required” button then appears, click it.

  If you are on Windows (WSL), you may see that there is a “OCaml and Reason IDE - for WSL”, but in our testing of these instructions, we found that extension did not work: so, install the non-WSL version.

  Also if you are on Windows (WSL), make sure that you are installing the “OCaml and Reason IDE” extension remotely on WSL, not locally on Windows.

• We recommend tweaking a few editor settings. Open the user settings JSON file by (i) going to View → Command Palette, (ii) typing “settings json”, and (iii) selecting Open Settings (JSON). Copy and paste these settings into the window:

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

  Save the file and close the tab.

  Here is a brief explanation of what you just changed: 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”).

• Check that the OCaml integration is working. From the command line, type code . to open the current directory in VS Code. Create a new file named test.ml and save it. Try entering let x:string = 3110. VS Code should then (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.

  If you are on Windows (WSL) and get an error about ocamlmerlin, there’s a good chance that you have the file open through Windows, not through WSL. Make sure that you opened VS Code by typing code . in the WSL shell, not by double-clicking a .ml file in the Windows File Explorer. For other ways of opening files through WSL, read this documentation.

Need help?

The course staff is happy to help you out with any trouble you might have! You can come to office hours or post on Campuswire. Before posting, please read these tips on asking technical questions.