> which ocaml
    /usr/bin/ocaml
    > ocaml
                Objective Caml version 3.12.0
    # 
    

OCaml, Eclipse and OcaIDE Setup

You may skip "Install OCaml" and "Install Eclipse" if working on SEAS lab machines.

1. Install OCaml. (The newest version is 4.0, but we have encountered some issues with that version and Eclipse.) We recommend:
   • Windows Users: Install the Windows-based binary ocaml-3.11.0-win-msvc.exe
   • Mac Users: Install the OS X version ocaml-3.12.0-intel.dmg.
2. Install Eclipse
   • To run Eclipse, a Java Runtime Environment (JRE) must be installed. You can check if Java is installed on your machine.
   • Visit the Eclipse download page.
   • Click on the link for your platform on the right side of the screen and install it by simply unpacking the downloaded file onto your desktop.
     • Note: The 64-bit Windows version of Eclipse may not be able to locate Java installations. If this happens, use the 32-bit Windows version instead.
   • Launch Eclipse. The first time you run Eclipse, you need to choose a workspace (a folder that stores your projects). Use the default location that Eclipse suggests, or choose your own location.
3. Install OcaIDE
   • In Eclipse, click Help » Install New Software...
   • In Work with, enter http://www.algo-prog.info/ocaide then click Add, OK.
   • Check OcaIDE and click Next, Next, I accept, Finish to accept the license and install the software. Eclipse will prompt you to accept unsigned code.
   • Click Restart Now. After Eclipse restarts, close the Welcome tab and click Window » Open Perspective » Other... » OCaml.
   • Go to Window » Preferences (Mac OS X users, go to Eclipse » Preferences). Click on "+" or "▶" next to OcaIDE to expand the tree and then click on Paths. If all the paths in this panel (except for possibly make and omake) are already filled in, then continue to the next step. Otherwise, click Browse next to OCaml Binaries Directory and choose the "bin" directory inside your OCaml installation directory (for example, C:\Program Files\ObjectiveCaml\bin). Then press Apply. Eclipse should fill in additional path values for you (ocaml, ocamlc, etc).
     • Under Other tools » OCaml lib path, click Browse and choose the "lib" directory inside your ObjectiveCaml installation directory. Press OK to close the dialog.
   • Near the top right of Eclipse, you should see an OCaml button and Java button, with the Ocaml button selected. If you only see the Java button, click the button to the left which looks like a window with a yellow "+" sign, and then double click on "OCaml". Now you are in OCaml mode.
   • Click the "Ocaml Toplevel" tab at the bottom of the workspace. Type into the prompt (do not type next to the #; the prompt box is at the bottom of the tab):

     print_endline "hello world";;

     . You should see the output:

     hello world
     - : unit = ()

     If this doesn't work, ask a TA for help.

Importing a project into Eclipse

These instructions show how to import a project into Eclipse. The example shown is for project0.zip -- other projects must be configured similarly.

First, download the project source and import it into Eclipse as a new project:

• Download the project0.zip archive to some folder on your machine.

     > mkdir ~/tmp
     > cd ~/tmp
     > wget http://www.cis.upenn.edu/~cis341/13sp/hw/project0/project0.zip
    

• Launch Eclipse and make sure that you are running in the OCaml perspective.
• Create a new Eclipse project: File » New » OCaml project (ocamlbuild)
  Name the project project0
• Import the project files:
  1. Select project0 in the Navigator panel.
  2. Do: File » Import
  3. Pick "General / Archive File" as the "import source" and click Next
  4. Browse to the project0.zip file as the "from archive file" and then select the "/" directory and its files when they appear in the panel
  5. "into folder" should already be set to project0
  6. Click Finish
• Configure the project to produce the right executables:
  1. Make sure the project is still selected in the Navigator panel.
  2. Open the Project » Properties dialog.
  3. Select the Project pane (choose it from the left column)
  4. In the Targets box add main.byte,main.native (main.ml is the top-level executable; see the details in comments of that file)
  5. Close the dialog by clicking OK. At this point Eclipse should build the project, creating a _build directory and the main.byte and main.native files should appear in the Navigator panel. (Note that every time you save a project file, Eclipse will by default try to rebuild your project; you can also rebuild manually from the Build menu.)
• Create a "Run Configuration" for this project (only needs to be done once)
  1. Open the Run » Configurations... panel. Select "Ocaml Exectuable" and then click on the 'New' button icon (a little white rectancle with a yellow +).
  2. Name the configuration something like "Run Project0"
  3. Enter project0 for the project name
  4. Browse to the main.native file that was created when you built the project.
  5. Enter the flag --test in the "command line arguments" field -- this tells the main harness to run in test mode, most of which will fail until you complete the project.
  6. Click Apply and then Run

If all was successful, Eclipse should pop up a Console window with the output of running the main program's test cases.

In Microsoft Windows

• If Eclipse reports "ocamlbuild" depends on Cygwin, then you need to install Cygwin's make.exe.
• If the compilation is failed because OCaml cannot find tput.exe, you need to install Cygwin's ncurses package.
• If it is failed to find ml.exe, advapi32.lib, msvcrt.lib, mspdb100.dll, please check if the environment variables Path and Lib are set correctly for Visual Studio.
• If it is failed to find flexlink.exe, you need to install flexdll.
• If native linkage fails, please check if Cygwin's path overwrites Visual Studio's path.

Command-line Compilation

If you would like to compile your projects from the command line, use the ocamlbuild tool (which is what Eclipse uses internally). ocamlbuild can generate bytecode (for use in the interactive toplevel) or native code (for better performance).

The session below shows how to build project0 (assuming you run these commands from within the directory containing the project source):

> cd project0
> ls
assert.ml               gradedtests.ml          hellocaml.ml            main.ml                 providedtests.ml
> ocamlbuild main.native main.byte
Finished, 14 targets (0 cached) in 00:00:00.
> ls
_build                  gradedtests.ml          main.byte               main.native
assert.ml               hellocaml.ml            main.ml                 providedtests.ml
>

To run command-line in Microsoft Windows, input "cmd" in Start » "Search Programs or Files", or Start » All Programs » Visual Studio 2010 » Visual Studio Tools » Visual Studio Command Prompt (2010). Note that the path separator '\' in Windows is different from the one '/' in Linux. The main.byte and main.native created by ocamlbuild are soft-links to the ones in _build. In Windows the path separators in the soft-links are sometimes created incorrectly. If that is the case, we can access _build\main.byte and _build\main.native directly.

Command-line Running and Testing Projects

After compiling the project, you can run it from the command line by executing either the native or bytecode versions.

The projects in this course are designed to have a single, top-level entry point in the file main.ml. When compiled by ocamlbuild either in Eclipse or at the command line as shown above, the resulting executables are main.native and main.byte.

This program provides a test harness that can be used from the command line with a variety of switches and command-line arguments, just like any other compiler. You can always check which command-line switches are available by using the -help or --help flags. For example, Project 0 supports only one interesting command-line option --test.

> ./main.native -help
CIS341 main test harness 

  --test run the test suite, ignoring other inputs
  -help  Display this list of options
  --help  Display this list of options

All of our projects will support the --test option, which will simply run the project's unit tests, print a summary of the results and then exit. It might give output something like this (bogus sample) that will give you some idea about how much of the project you've completed:

> ./main.native --test

Test1:
  case1: failed - not equal
  case2: failed - assert fail
  case3: failed - test threw an unknown exception
Test4:
  OK
Test2 (3/10 points)
  case1: failed - not equal
  case2: failed - not equal
  case3: passed
Test3 (??/20 points):
  Hidden
Test5 (10/10 points):
  OK
---------------------------------------------------
Passed: 5/10
Failed: 5/10
Score: 13/20 (given)
       ??/20 (hidden)

Once the compiler projects reach the stage where we can generate good assembly output, the main function will support more interesting command-line options and be able to process input files in a way that should be familiar if you've ever used gcc or another compiler.

Consider using a version-control system

Even if you're working alone, it's still useful to set up a source control system. Subversion works well and integrates nicely with Eclipse. If you're going to be working with a partner, contact CETS about setting up a UNIX group on ENIAC so that you can share a code repository. As the projects become more complicated, having controlled sharing of the source code may save you many headaches. If you do set up a repository, try to avoid checking in binary files.

Subclipse Installation and Configuration

1. Follow the installation instructions.
2. Browse repositories on SVN.
   • Window » Open Perspective » SVN.
   • Right click on the SVN repository view » New » Input SVN URL.
3. Checkin a project into SVN.
   • Right click on the project name, select Team » Share project
   • Select a repository or Create one » Choose a directory to checkin.
4. Create a project from SVN.
   • File » New » Other » SVN » Checkout projects from SVN.
   • Select "Create a new repository location" and then input the URL.
   • Select the directory to checkout from the repository tree, and choose "Checkout as a new project".
   • Then follow the new project wizard to create an OCaml (ocamlbuild) project.
5. Please refer to Help » Help Contents » Subclipse for other features.