Assignments


Programming Projects

Project Overview

In P1–P5, you will build a complete compiler that grows phase by phase. The rules below apply to every checkpoint; each project page only adds what is specific to that phase.

You design the internals. Unlike CS 432 in previous years, you will not be given a reference code framework to work with, and no internal function signatures, data structures, or headers are prescribed. You will build your own project (your own Makefile and C source files). Your grade depends only on the observable command-line behavior of the decaf binary that make produces.

Here is the the core command-line contract, which is the specification you will be graded against:

  • Running make must build ./decaf in your project root.
  • Signal validity by exit status: exit 0 for a program your compiler accepts, non-zero for one it rejects (a lex, parse, or analysis error). Automated invalid-program tests check only that an error was reported, not the message text; reasonable error messages with line numbers are still required but will be spot-checked manually.
  • Send error messages to stderr — lexical (P1), syntax (P2), and semantic (P3). Keep stdout clean: it should contain only the dump output described below. It is compared byte-for-byte with the reference output, and for P4/P5 it is sometimes piped straight into the ILOC simulator (isim), so a stray message printed there will corrupt the ILOC stream. This applies to your own debugging output too.
  • You must implement the following phase output flags: --fdump-tokens (P1), --fdump-expr (P2), --fdump-iloc (P4), and --fdump-iloc-alloc (P5). Token and ILOC output are compared byte-for-byte, so take care to match the reference format exactly. P3 produces no graded stdout at all -- automated grading is based only on validity (exit status).
  • You must implement the following stop flags: --stop-after-{lex,parse,analysis,codegen} must halt the pipeline after a phase. They should be orthogonal to the --fdump-* flags and compose with them. The provided main.c in the minimal scaffold already implements these.
  • The compiler only emits code — it never runs it. P4/P5 output is executed by a separate, provided ILOC simulator (isim). For P5, isim -r N also verifies that allocation used only the N allowed physical registers.

Grading is cumulative. At each checkpoint your one decaf is run against the test suites for every phase up to and including the current one, so you should go back and fix any missing corner case functionality in the earlier projects. Because a phase's --stop-after flag is a no-op in the phase that introduces it, the public tests that exercise it are included with the next project.

Distribution: Folders will be posted in /cs/students/cs432/f26 on stu (the student server). The P1 distribution includes two folders: 1) skeleton, a minimal scaffold (a Makefile and a src/main.c that already parses the command-line contract above and leaves each phase as a TODO), and 2) test-p1/, the public test suite along with the reference compiler binary decaf-ref. Each later phase includes only a drop-in test-p<N>/ folder that you add to your existing project beside the earlier test folders. The distributions contain none of the reference implementation's source.

To run the test suites, execute make test from your project root folder. By default, the tests run twice; once for output testing and once for memory testing using Valgrind's Memcheck tool. If you run the tests on a platform that doesn't have Valgrind installed, it will skip that part. You can also disable the memory tests with NO_VALGRIND=1 to avoid the extra overhead. The public test suites are only a sample; the graded suites include the memory testing and many additional hidden/edge cases that are what determine the auto-graded portion of your grade. You should build your own test cases to ensure your implementation is robust.

I strongly recommend working on stu; that is the canonical grading setup, so working there provides the best guard against works-for-you-but-not-for-me issues. If you choose to work elsewhere, make sure you run on stu at least once before submitting. Anecdotally, the testing framework works on MacOS (without memory checking) but not on Windows; you may have some success with WSL or MSYS2, but I cannot provide support.

Submission is by GitHub Release: verify that make builds ./decaf from a clean copy, push your commits, then create a release and corresponding tag named p<N> (e.g., p1) targeting the commit you want graded, using the GitHub CLI (gh):

git tag p<N>
git push origin p<N>
gh release create p<N>

You can also create a release from the GitHub web interface if you prefer. Here is the documentation for creating releases on GitHub.

The GitHub release is your submission for grading. If you need to resubmit (e.g., to fix something before the deadline), delete the release (and its underlying tag) and recreate it against the corrected commit:

gh release delete p<N> --cleanup-tag --yes
git push
git tag p<N>
git push origin p<N>
gh release create p<N>

Late submissions are penalized as described in the syllabus. I highly encourage you to make at least one on-time submission for deadline status verification, even if you plan to resubmit late. Do not delete the on-time submission; use a different release name for the resubmission (e.g., p<N>-late).

With each checkpoint your repository must also include an AI-use disclosure and (if you used AI) a curated prompt portfolio, consistent with your group's declared AI-use level (I recommend a dedicated subfolder called ai-portfolio for storing prompts and logs). Projects with a code review (P0, P2, P4) additionally require uploading your code to Canvas so your reviewers can access it — see that project's page for details.