On Eniac

You can do all of your development on Eniac, and we will be testing your projects there. It provides a linux environment.

GCC

The default version of gcc on Eniac is version 4.8.1. which should be fine for this class.

OCaml

We will be compiling your project code using the OCaml version 4.01 suite of tools (including ocaml, ocamlc, ocamlbuild, ocamllex, and ocamlyacc).

The default ocaml installation found in /usr/bin/. If you want to test or develop your projects on Eniac you should use that version of the ocaml.

Check that your set-up on Eniac is correct like this:

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

Code Editors

LLVM

We will make the appropriate version of llvm available in the cis341 course account.

On Linux

GCC

Most linux distributions come with an appropriate version of gcc installed. Make sure that it is in your PATH.

OCaml

For linux users, we recommend using OPAM. Follow the installation istructions from Real World OCaml.

On OS X

GCC

Install Xcode via the App Store. Or install just the "Command Line Tools", which should be available through the Apple Developers Download Site (login with your Apple ID required).

OCaml

There are two ways to install OCaml:

• OS X installer: (Recommended) ocaml-4.01.0-intel.dmg.
  • This distribution works with OS X 10.7.5 and later. If you have an earlier version, contact the course staff for help.
• OPAM (OCaml Package Manager): (Power users) Follow the installation istructions from Real World OCaml.

Using Microsoft Windows

GCC

You should install following software before installing OCaml (and Eclipse):

1. Visual Studio
If you don't have it already, you should use your free MSDNAA access to download a copy of Visual Studio. The installation needs to include at least the VC and Microsoft SDKs components.
2. Cygwin
• Follow the installation instructions at www.cygwin.com.
• Select packages. Besides the default packages, we need two more packages.
  1. After search 'make', click on '+' to extend the categories tree: the root node is "All", and the child node is "Devel". The package ``make: The GNU version of the 'make' utility''
  2. After search 'ncurses', click on '+' to extend the categories tree: the root node is "All", and the child node is "Utils". Then on the package ``ncurses: Utilities for terminal handling''.
  Then click next.
• Click Next, ..., Then finish.
3. FlexDll
Download and install flexdll by following the instructions on that web page.
4. Set environment variables:
In Win 7, click "start" » right click properties on "computer" » click "Advanced system settings" » in the "Advanced" tab click "Environment Variables"

Edit "Path" variable in the system variables, append the appropriate paths string to its variable value, e.g.:

;C:\Program Files (x86)\Microsoft Visual Studio 10.0\VC\bin;C:\Work\Tools\cygwin\bin;C:\Program Files (x86)\flexdll;C:\Program Files (x86)\Microsoft Visual Studio 10.0\Common7\IDE;C:\Program Files (x86)\Microsoft SDKs\Windows\v7.0A\Bin

Note that C:\Program Files (x86)\Microsoft Visual Studio 10.0\VC\bin must be before C:\Work\Tools\cygwin\bin to overwrite executables such as link.exe from Cygwin, and there is a ";" in the beginning of the string.

Edit "Lib" variable in the system variables (New a "Lib" variable if there does not exist one), append the following string to its variable value:

;C:\Program Files (x86)\Microsoft SDKs\Windows\v7.0A\Lib;C:\Program Files (x86)\Microsoft Visual Studio 10.0\VC\lib

OCaml

Windows Users: Install the Windows-based binary available here ocaml-4.01.0-i686-mingw64-installer3.exe. There are installation instructions on the web page http://protz.github.io/ocaml-installer/

• You probably need to add the Cygwin support.

Command-line Compilation

It is recommended that you compile your projects from the command line, using 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 hw1 (assuming you run these commands from within the directory containing the project source):

> cd hw1
> ls
gradedtests.ml   hellocaml.ml     main.ml          providedtests.ml util
> ocamlbuild -I util main.native
Finished, 14 targets (0 cached) in 00:00:00.
> ls
_build           gradedtests.ml   hellocaml.ml     main.ml
main.native      providedtests.ml util
>

Here is a minimal Makefile that can help you invoke ocamlbuild:

DIRS=util

main.native:
	ocamlbuild -Is $(DIRS) main.native

main.byte:
	ocamlbuild -Is $(DIRS) main.byte

all: main.native

clean:
	ocamlbuild -clean
  

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 or 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, HW1 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.

Eclipse and OcaIDE Setup

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

1. 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.
2. 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. You should see the OCaml output display:

     OCaml version 4.01.0
     
     #
             

     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 course staff member for help.

Importing a project into Eclipse

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

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

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

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

• Launch Eclipse and make sure that you are running in the OCaml perspective.
• Create a new Eclipse project: File » New » OCaml project (ocamlbuild)
  
  Note: Unlike CIS 120, CIS 341 uses the OCamlbuild project option not the OCaml Managed option.
  Name the project hw1
• Import the project files:
  1. Select hw1 in the Navigator panel.
  2. Do: File » Import
  3. Pick "General / Archive File" as the "import source" and click Next
  4. Browse to the hw1.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 hw1
  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 Hw1"
  3. Enter hw1 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.

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.