Setting up your OCaml development environment #

This document should help you get up and running with an OCaml development environment on your computer. We assume you have a Unix-like operating system available, such as MacOS or Linux. (For Windows users, we’ll provide instructions on setting up Linux in a virtual machine.)

Background on the Unix command line #

Regardless of the operating system of your computer, you’ll be interacting with it using the Unix operating system’s command line.

Unix is a family of operating systems, originally developed at Bell Labs in the 1970s by Ken Thompson and Dennis Ritchie. Operating systems have many newer user interface features, but some of the original features from Unix will be the most useful in CS 51.

Users of the earliest Unix systems interacted with their computers exclusively through the keyboard, via the command line. They would type commands (names of short programs) that directed the computer to take action, like running a program to switch to a different folder in the file system or to create or delete a text file.

If you took CS 50, you ran commands in the command line on the CS 50 IDE. While you may never have done so before, you can also interact with your Mac, Linux, or Windows machine via the command line. You will spend a good deal of time at the command line in CS 51, and comfort at the command line, developed over time, will be one of the skills you build in this course.

As it turns out, macOS and Linux are both built on versions of Unix. On Windows, alternative command line facilities can be used. This common substrate for interacting with the computer makes it possible to work similarly for this course on the various operating systems.

Accessing the Unix command line #

Interacting with the Unix command line #

Interacting with the command line starts at the command line prompt, which is typically a % or $ though it may include much other information. We will use the % symbol to represent the Unix command line prompt in our examples. (You should not type that symbol itself at the prompt.)

Let’s investigate some programs that are useful for interacting at the command line. (If you are already familiar with Unix, feel free to skip this section.)

• man – The man command (short for ‘manual’) provides documentation on other commands. Try typing

  % man mkdir
  

  Type q to exit the manual page reader.

• mkdir – The mkdir command (short for ‘make directory’) makes a new directory (or in macOS parlance, folder) in the current directory that you are currently accessing. Try typing

  % mkdir testdirectory
  

• ls – The ls command (short for ‘list directory’) lists the contents of the current directory. Try typing

  % ls
  

  It should show the files and subdirectories of your main (‘‘root’’) directory, including the testdirectory directory that you just made.

• cd – The cd command (short for ‘change directory’) changes the current directory. Its argument specifies the directory to move to. You can give a subdirectory of the current directory to change to that subdirectory, or ‘’..’’ to change to the immediately enclosing directory. Try typing

  % cd testdirectory
  

  % ls
  

  It should move you to the testdirectory you just made, and list its contents. (There shouldn’t be anything there.) Now

  % cd ..
  

  to move back to the root directory.

• rm – The rm command (short for ‘remove file’) deletes a file. Its argument specifies the file or files to be deleted. Be careful with this one.

We call these ‘‘commands’’, but they are actually programs. Thinking of them as programs will be helpful when you start to install new ones, and you should be aware that these programs can be run with many different interesting and powerful options. (Take a look at man ls. Type q to exit the manual page reader.)

For more guidance on the command line, check out this link.

Package managers #

Now that you know what the command line is and how to move around, it’s time to start installing software. Your development environment for the course will include the OCaml programming tools (compiler, interpreter, build system, package manager); the git version control system; and a text editor for editing software.

To install all of these things, you could search for instructions on the web and download .zip files. This is how you may have installed software in the past. Since we’re going to be building our own software, however, we care a great deal about keeping careful track of what software we have installed. As such, we’re going to use a package manager.

% brew

% sudo apt-get

Installing software #

Now that you have a package manager, you can install the other software that you will need.

% brew update

% brew install xquartz

% brew install pkg-config
% brew install gpatch
% brew install opam

% sudo apt-get update -y

% sudo apt-get install -y gcc make patch unzip m4 git xorg libx11-dev pkg-config

% sudo apt-get install -y open-vm-tools open-vm-tools-desktop

% sudo apt-get install -y opam

Installing the OCaml tools #

You may be asking yourself why we installed a package manager specifically for OCaml after installing a general package manager for your system.

This is a reasonable question, and luckily it also has a reasonable answer. A software project is often developed by many different people, each of whom may be running a different operating system. Many software projects also take advantage of external libraries that have been made available to other developers. Sharing previously written libraries and packages for specific programming languages across multiple operating system package managers (note that there are 4 different version of this document), and keeping all of the different listings in sync with each other, would be a true challenge of coordination. This complexity arises before considering the fact that several different projects that one developer is working on may each require a different version of the same programming language.

To solve this problem, the developer communities for most popular programming languages have built abstractions between the libraries for and versions of their language and the operating system in the form of language-specific package managers. Each system’s version of a language-specific package manager knows how to install libraries on that system, so that the authors of a library need only describe how the single manager should install the library. Package managers for particular languages thus serve as an abstraction mechanism over the various operating systems they support.

Setting up OPAM #

OPAM is the package manager for OCaml; you installed it above. Some other examples of language-specific package managers are pip for Python, npm for Node.js, and gem for Ruby.

To set up OPAM, run:

% opam init -a

At this point, close your terminal window and open a new one.

The official version of OCaml used in CS 51 this year is 4.12.0. This may not be the version installed by default by the system package manager. In addition to managing OCaml packages, OPAM can also manage OCaml versions. To install the correct version, run:

% opam update
% opam switch create 4.12.0
% opam switch 4.12.0

Now that you have the right version, you can install some packages that you will need during the course.

% opam install -y graphics
% opam install -y ocamlbuild
% opam install -y ocamlfind
% opam install -y ocamlnet
% opam install -y yojson
% opam install -y merlin
% opam install -y utop
% opam install -y menhir

We also have created a special package for CS51 called CS51Utils. Feel free to peruse the CS51Utils package on Github. This is how OCaml distributes third party packages, similar to the ones you installed above. This package contains some useful functions that you can use across the problem sets and labs in the course. You will be introduced to these functions during the labs.

% opam pin add CS51Utils https://github.com/cs51/utils.git -y

After all of this is done, you should finish the process by running the following command, which should have no output:

% eval $(opam env)

At this point, close anything you are working on and restart your computer.

Verifying that OCaml graphics is working #

Next, we want to check whether OCaml graphics is properly installed on your computer. To verify that graphics is properly working on your computer, we’ve included a graphics verification tool in CS51Utils. (Thanks to CIS120 at UPenn for help with the following instructions.)

Run the following shell comand.

% cs51-graphics-check

The XQuartz implementation of the X11 window system should run, and a small window with a white exclamation mark on a red background should appear, as in the figure below.

If so, OCaml graphics is properly installed and you’re all set. If not, proceed with the remaining instructions.

% find /opt -name libX11.6.dylib

% brew install xquartz

% opam uninstall graphics
% opam install graphics

% cd
% mkdir lib
% cd lib
% ln -s /opt/X11/lib/libX11.6.dylib libX11.6.dylib

$ opam list

$ opam uninstall {package-name}
$ opam install {package-name}

Fatal error: exception Graphics.Graphic_failure("Cannot open display xxx.xx.xx.x:x")

The OCaml REPL #

Now that you have OCaml installed, to verify that everything went well, open your system’s Terminal and type:

% ocaml

You should see the following:

% ocaml
        OCaml version 4.12.0

#

This is the OCaml read-eval-print loop (REPL), where you can type or paste OCaml code and see the output evaluated. To quit the REPL, press ctrl + D or type #quit;; to call the REPL’s quit command.

utop #

You also installed a more-fully featured OCaml REPL, called utop. It has useful features like auto-completion built-in. To make sure that it is working, type:

% utop

It should also identify 4.12.0 as the version of OCaml it is running. It can be quit in the same way as the ocaml REPL.

Then verify that typing the string "are we there yet?" (including quotes) followed by two semicolons and pressing enter results in something like this:

# "are we there yet?" ;;
- : string = "are we there yet?"

(The # character represents the OCaml prompt; you don’t need to type it.)

Congratulations! You just ran your first OCaml code!