141 lines
4.8 KiB
ReStructuredText
141 lines
4.8 KiB
ReStructuredText
.. -*- mode: rst -*-
|
|
|
|
.. include:: course.links
|
|
|
|
.. _hellocaml:
|
|
|
|
HW1: Hellocaml
|
|
==============
|
|
|
|
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 :ref:`toolchain web pages <toolchain>`
|
|
and the `OCaml web site <https://ocaml.org/>`_.
|
|
|
|
Please also take some time to skim the available resources on the
|
|
course homepage -- in particular, the book `Introduction to Objective
|
|
Caml <../../../current/_static/files/ocaml-book.pdf>`_
|
|
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.
|
|
|
|
|
|
**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,
|
|
run ``make`` from the project root directory (in VSCode or in a terminal)
|
|
and then continue to the ``bin/hellocaml.ml`` file and follow the instructions
|
|
(in comments) there.
|
|
|
|
**Building the Project**
|
|
|
|
It is recommended that you compile your projects from the command
|
|
line, using ``make``. We have included a ``Makefile`` that provides
|
|
several make targets that can help you with the homework::
|
|
|
|
make -- builds oatc using dune
|
|
make dev -- runs dune build in "watch" mode for more interactive errors
|
|
make test -- runs the test suite
|
|
make clean -- cleans your project directory
|
|
make utop -- starts a utop for the project
|
|
make zip -- creates a zip file with the code you need to submit
|
|
|
|
For example, using make we can build the project and run the tests all
|
|
in one go::
|
|
|
|
> make test
|
|
dune build
|
|
... [[ warnings omitted ]]
|
|
./oatc --test
|
|
Running test Student-Provided Tests For Problem 1-3
|
|
Running test Problem1-1
|
|
Running test Problem1-2
|
|
...
|
|
|
|
Command-line Running and Testing Projects
|
|
-----------------------------------------
|
|
|
|
After compiling the project, you can run it from the command line.
|
|
|
|
The projects in this course are designed to have a single, top-level
|
|
entry point in the file ``main.ml``. Upon running ``make``, it compiles to
|
|
an executable ``main.exe``, and copies it as ``oatc`` to the root of the project.
|
|
|
|
The ``oatc`` 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``::
|
|
|
|
> ./oatc -help
|
|
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::
|
|
|
|
> ./oatc --test
|
|
|
|
Test1:
|
|
case1: failed - not equal
|
|
case2: failed - assert fail
|
|
case3: failed - test threw an unknown exception
|
|
Test2:
|
|
OK
|
|
Test3 (3/10 points)
|
|
case1: failed - not equal
|
|
case2: failed - not equal
|
|
case3: passed
|
|
Test4-Manual (0/3 points = 0/1 tests)
|
|
FAILED - manually: assert fail
|
|
Test5 (??/20 points):
|
|
Hidden
|
|
Test5 (10/10 points):
|
|
OK
|
|
---------------------------------------------------
|
|
Passed: 5/10
|
|
Failed: 5/10
|
|
Score: 13/20 (given)
|
|
??/20 (hidden)
|
|
|
|
**Note:** problems that will be manually graded after you submit the
|
|
homework are considered to "fail" according to the test harness.
|
|
|
|
Once the compiler projects reach the stage where we can generate good
|
|
assembly output, ``oatc`` 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
|
|
-------
|
|
|
|
Submit your solution to this assignment by following the :ref:`submission instructions <submit>`
|
|
|
|
**Projects that do not compile will receive no credit!**
|
|
|
|
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
|
|
* 13 Points of manually graded parts
|
|
* 3 points for the type annotations in problem 2-1 (manually graded)
|
|
* 5 points for proper tail call implementation in 3-4 (manually graded)
|
|
* 5 points for "Style" and additional test cases for 4-3 and 5 (manually graded)
|