Overview
This project provides a refresher on OCaml programming and some warm-up exercises involving tree manipulation and recursive programming (both of which will be highly useful when building the compiler). It will also familiarize you with the basic workflow of the projects in this course, including the testing framework that we will use to (partially) automate the grading of your projects.
For help on how to get started with OCaml see the toolchain web pages and the Caml web site.
Please also take some time to skim the available resources on the course homepage -- in particular, the book Introduction to Objective Caml provides a very good reference for learning OCaml. In the problems below when you see a note like "See IOC 5.2" please refer to the corresponding section of the book.
It is not possible to cover all of OCaml's features in just a couple weeks, so we expect you to be able to learn most of what you need on your own.
Also, please feel free to ask a course staff member for help -- post on Piazza to make sure you reach everyone who might be available for help.
Getting Started
Unlike future projects, most of the instructions for this project are found as comments in the source files of hw1.zip. To get started on this project, choose either the "command line" or "Eclipse" development methods, read the appropriate set-up instructions, and then continue to the hellocaml.ml file. and follow the instructions (in comments) there.
Command-line Compilation (recommended)
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 >We have included a Makefile that can help you invoke ocamlbuild. It provides several make targets that can help you with the homework:
make -- builds main.native using ocamlbuild make test -- runs the test suite make clean -- cleans your project directory make zip -- creates a (timestamped) zip file suitable for submitting to the grading site
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 (alternate)
If you choose to develop your project code in Eclipse with the OcaIDE OCaml plugin. See the toolchain web pages for help getting your Eclipse installation set up.The instructions below walk you through downloading and compiling this project for development in Eclipse. You will need to do a similar configuration process to import future project codebases too. The above documentation gives a command-line oriented alternative, which can be helpful when you test later projects, or if you choose to use a different code editor (Emacs or vim both have good OCaml support).
First, download the project source and import it into Ecplise as a new project as directed on the toolchain web pages. If all was successful, Eclipse should pop up a Console window with the output of running the main program's test cases. You should see output like this:
Student-Provided Tests For Problem 1-3: case1: failed - Problem 3 case1 test unimplemented case2: failed - Problem 3 case2 test unimplemented case3: failed - not equal Problem1-1 (0/3 points) pieces: failed - not equal cube0: failed - cube unimplemented cube1: failed - cube unimplemented cube2: failed - cube unimplemented cube3: failed - cube unimplemented Problem1-2 (0/3 points) cents_of1: failed - cents_of unimplemented cents_of2: failed - cents_of unimplemented cents_of3: failed - cents_of unimplemented cents_of4: failed - cents_of unimplemented cents_of5: failed - cents_of unimplemented cents_of6: failed - cents_of unimplemented cents_of7: failed - cents_of unimplemented Problem1-3 (??/3 points): Hidden ...
This output shows the results of test cases we provide. Some of the cases are available for you to see (such as Problem1-1), some tests will be written by you, and others are hidden in reserve for testing your final project.
Grading
What to submit
Submit a file called hw01-submit(TIMESTAMP).zip containing: hellocaml.ml and providedtests.ml. (The easiest way to create the zip file is by using make zip from the command line.)Submit it by following this link. Projects that do not compile will receive no credit!
Points
Your grade for this project will be based on:
- 64 Points for the test cases that are visible to you
- 23 Points for the hidden test cases
- 8 Points for the tests you provide (manually graded)
- 5 Points for "programming style" (manually graded) -- see these guidelines