CIS 500: SEAS OCaml Tutorial (Work in Progress)

Getting Started

First you will want to obtain a terminal session on a SEAS Unix system. Some of you may have such a system on your desk, or can find one in one of the SEAS Computer Labs. On one of these computers, there will generally be some menu option that will allow you to open a new terminal window in which to work.

If you do not have immediate access to such a computer, the next option is connect to one of the SEAS Unix servers. The best way to do this is using the Secure Shell Protocol (SSH). A good way to do this from a Windows system is to use PuTTY or SecureCRT. SecureCRT should be installed on SEAS Windows Systems. PuTTY requires no installation, so can be easily downloaded and used from most Windows computers. MacOS X and most Unix systems have a SSH client installed which can be invoked from a local terminal with the ssh command. On MacOS X, the Terminal application can be found in the Utilies folder within the Applications folder. The system you will want to connect to is called eniac-l.seas.upenn.edu. This is a Linux cluster with a recent version of OCaml installed. Some of you may also have accounts on halfdome.cis.upenn.edu, another Linux cluster, which also has OCaml installed.

Note: On the Linux clusters, the OCaml binaries are installed under /usr/bin and thus should be in your path automatically.

The last option is to compile OCaml on your own computer. The download page includes binary packages for many common platforms, and if you have any experience with compiling software packages, a source installation should build quite easily out-of-the-box. If you can do this, the rest of this tutorial may not be relevant to you.

Using the OCaml Interactive Toplevel

To start the OCaml interactive toplevel, simply type ocaml at the prompt.

$ ocaml
        Objective Caml version 3.08.1

# 

Now you are ready to do some simple programming. Expressions typed at the OCaml prompt must be terminated by two semi-colons. For example, here is simple arithmetic expression:

# 1 + 1;;
- : int = 2
# 

You may bind values to variables using let:

# let x = "foo";;
val x : string = "foo"
# 

You can read in the contents of a file containing OCaml source code using the following directive:

# #use "myfile.ml";;

One useful feature of the OCaml toplevel is that it will automatically execute the contents of the file .ocamlinit in the current directory (or user's home directory) when started. Thus, by adding the line

#use "myfile.ml";;

to the .ocamlinit file, you will be able to immediately work with the definitions in myfile.ml after starting the OCaml toplevel. (The drawback here is that output about the bindings is surpressed.)

You can load the contents of an OCaml object file that you have already compiled using the following directive:

# #load "myfile.cmo";;

Finally, you can exit the toplevel by hitting Control-D or typing the following:

# #quit;;
$

Using the OCaml Compiler

The OCaml bytecode compiler is named ocamlc, and it's usage is similar to a standard C compiler. To compile a file to object code type:

$ ocamlc -c myfile.ml

This will produce an object code file myfile.cmo, which can be loaded into the toplevel or linked with other object files to produce an executable. If loaded into the toplevel, its definitions can be accessed under the module name Myfile. For example, if the file defines a function foo, it will be accessible under the name Myfile.foo.

If you wish to create an executable, you can run ocamlc with the -o option:

$ ocamlc -o myprog myfile1.ml myfile2.cmo

The executable will be named myprog. Any number of source and object files may be given to the ocamlc command and should be given in dependency order. For example, if myfile2.ml refers to a function Myfile1.foo, then myfile2.ml (or myfile2.cmo) should appear after myfile1.ml (or myfile1.cmo) on the command line. The resulting executable is actually a bytecode file that knows how to invoke the bytecode interpreter on itself. If, for some reason, it cannot properly invoke the bytecode interpreter, you may do it manually by typing:

$ ocamlrun myfile

In order to create native code executables, you may use the ocamlopt command, which has usage similar to ocamlc.

Working with OCaml Code in GNU emacs or XEmacs

If you use the GNU emacs or XEmacs editors on a SEAS Unix system, you can add configure it for editing OCaml code by adding the following lines to your .emacs file:

; Add tuareg-mode elisp to your load path
(setq load-path (cons "/home10/c/cis500/elisp" load-path))

; tuareg-mode configuration
(setq auto-mode-alist (cons '("\\.ml\\w?" . tuareg-mode) auto-mode-alist))
(autoload 'tuareg-mode "tuareg" "Major mode for editing Caml code" t)
(autoload 'camldebug "camldebug" "Run the Caml debugger" t)

(if (and (boundp 'window-system) window-system)
    (when (string-match "XEmacs" emacs-version)
        (if (not (and (boundp 'mule-x-win-initted) mule-x-win-initted))
            (require 'sym-lock))
        (require 'font-lock)))

Next time you start GNU emacs or XEmacs and open a file that ends in .ml or .mli it will activate tuareg-mode. This will provide support for syntax hilighting and indentation. Additionally, it will add a new pull-down menu labeled "Tuareg" that will provide a number of useful features. For example, under the "Interactive Mode" submenu, there is an item "Run Caml Top Level" that will create a new window in which to interactive with the OCaml toplevel. This is particularly useful because it provides command history among other features. Once you have a top level running, it also provides menu items to evaluate a buffer of OCaml code or a selected code region.

Working with OCaml Code in vim

If you use the vim editor (installed in /usr/bin on most SEAS Systems), it should come with support for OCaml syntax hilighting by default. This can be enabled by typing :syntax enable. If you are using vim from a terminal emulator that supports color, be sure that you have the environment variable TERM set to something like ansi or xterm-color in order to get color hilighting.

OCaml is also supported by the vim quickfix compilation/error reporting system.