# 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, 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.
[homebrew]: http://brew.sh/
[MacPorts]: https://www.macports.org/
## VM installation
WARNING: Do not use a VM from an old edition of CS 3110. Only the Fall 2017 VM
will be supported this semester.
* Download and install [VirtualBox][vbox] for your operating system. Make sure
you have the latest version before proceeding.
* Download [3110 virtual machine][3110vm] (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-2017fa 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][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][3110vm-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!
[vbox]: https://www.virtualbox.org/wiki/Downloads
[3110vm]: https://cornell.box.com/v/cs3110vm-2017fa-64
[vagrant]: https://www.vagrantup.com/
[3110vm-repo]: https://github.com/cs3110/vm
[user-setup]: https://github.com/cs3110/vm/blob/master/user-setup.sh
## 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,
then 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][opam-install] 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][wsl]. (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.05.0 compiler:
```
# Note: do NOT prefix these commands with sudo
opam switch -y 4.05.0
eval `opam config env`
```
Now check your compiler version by running `opam switch show`. If that reports
anything other than `4.05.0`, something has gone wrong. Seek further help
in person from the course staff. Be aware that **OCaml version 4.05.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 bisect
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.
[opam-install]: https://opam.ocaml.org/doc/Install.html
[wsl]: https://msdn.microsoft.com/en-us/commandline/wsl/install_guide
## 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][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`.
[atom]: https://atom.io/
## 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.