HW1: HellOCaml

Download: from Canvas

Due: Tuesday September 10, 11:59pm

Submit: on Gradescope

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.

Before you begin:

For help on how to get started with OCaml see the Resources page and the Caml web site.

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. To get started on this project, read the set-up instructions below 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. 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 -libs unix 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 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
CS153 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.

Grading

What to submit

Submit the files hellocaml.ml and providedtests.ml via Gradescope. To make it a bit easier, you can execute make zip, which will create a zip file containing those two files. You can then upload that zip file to Gradescope.

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 the Resources page on the course website for a link to a style document.