CS 444/644 - Compiler Construction (Winter 2026) - Assignment 5

For this last assignment, you will make your compiler generate i386 assembly language (32-bit mode).

If the input program is valid Joos 1W, your compiler should output, into the subdirectory output of the current working directory, one or more files with the extension .s containing the assembly language code implementing the program. It is recommended that the code implementing each class be generated into a separate .s file. You may assume that the output directory exists before your compiler runs, and that the directory is empty. After your compiler runs, each of the .s files in the directory will be assembled with the command:

/usr/bin/nasm -O1 -f elf -g -F dwarf filename.s

After all of the files are successfully assembled, the file runtime.s from the standard library (see below for description) will also be assembled and placed in the output directory. Then, all of the .o files generated by nasm in the output directory will be linked using the command:

ld -melf_i386 -o main output/*.o

Finally, the generated executable main will be executed.

One of the generated .s files must define the global symbol _start:

global _start
_start:

When your program is run, execution will start from this point.

Unlike in Java, the first method that begins executing is not static void main(String[]), but static int test(). All of the test inputs will have such a method. The class containing the test method will be listed first on the joosc command line, before any other compilation units. The code that you generate at _start should initialize all static fields, then call this method. When the method returns with return value x, your program should exit with exit code x using the sys_exit system call. To execute this system call, load the value 1 (indicating sys_exit) into register eax, load the exit code into register ebx, then execute the instruction int 0x80.

Java specifies a very precise but complicated order in which static fields must be initialized (JLS 12.4). For Joos, the order is specified by the following rules:

All static fields must be initialized before the startup code calls the static int test() method.
Static fields within the same class must be initialized in the order in which they appear in the class.
Static fields in different classes can be initialized in any order.

Note that Java and Joos require that any field without an explicit initializer be initialized to the value false, 0, or null, depending on its declared type.

Another simplification is that arrays in a Joos program inherit the clone() method from java.lang.Object. In Java, arrays are required to implement a different clone method as specified in Section 10.7 of the Java Language Specification.

The runtime.s file included with the standard library contains several utilities that are likely to be useful.

The function __malloc allocates a number of bytes of memory. The number of bytes to be allocated must be in the register eax before executing the instruction call __malloc. The address of the beginning of the allocated memory can be found on register eax after the call. There is no provision for freeing allocated memory; you should not need it for the simple programs that we will be testing with.
The function __exception ends the program with exit code 13. You should call this function in any situation in which the equivalent Java code would throw an exception, such as a failed null check, array bounds check, or cast check.
The function NATIVEjava.io.OutputStream.nativeWrite is an implementation of the native method nativeWrite found in the java.io.OutputStream class of the standard library. The method writes the low-order byte of its parameter to the standard output. This method is used as the basis of more sophisticated output methods in the standard library such as System.out.println(). In general, you should translate the call of any native method into a call to the symbol that begins with the string NATIVE, followed by the canonical name of the class containing the native method, followed by a dot (.), followed by the name of the native method. Although no native methods other than nativeWrite will appear in the tests, you can use this mechanism in your own tests to implement additional interaction between your Joos code and the operating system. Recall that in Joos 1W, all native methods must be static, must take a single argument of type int, and must return a value of type int. The parameter passing conventions for native methods are the following. The argument must be placed in the register eax prior to calling the native method, and the return value can be found in the register eax after the native method returns.

Important note: Although most of the Assignment 5 Marmoset tests do not use or test standard output, all of the secret tests, which are worth many marks, do. To get a non-zero mark on the secret tests, it is essential to pass the J1_Hello test for Assignment 5, which prints Hello, World! to standard output.

Marmoset tests the code generated by your compiler on a server running Linux. If you are using Windows or a Mac, the recommended way to test the generated code is either to copy it to linux.student.cs and run it there, or to run it using Linux in a virtual machine. For the convenience of groups doing their development on Windows, a former student has made available a Windows translation of runtime.s. You may use it but it is unsupported. Marmoset will test your compiler on the linux.student.cs servers with the runtime.s file that is included with the Joos standard library.

Before starting to implement this assignment, it is strongly recommended that you meet with your group to design and agree on conventions for

parameter passing,
local variable storage,
object layout, and
naming of labels for method implementations and data.

It is recommended that you document these conventions at this stage, and include this documentation in the design document that you hand in. It is suggested that you modularize the implementation of these conventions in dedicated modules in your compiler, to ensure consistency between the different parts of your compiler that rely on the conventions.

Code Submission

Submit to Marmoset a .zip archive containing everything required to build and run your project. It should also include all your test cases and test code that you used to test your compiler. It must also include a file named git.log showing the commit history of your Git repository.

In addition to the above, the .zip file should contain a file named Makefile in the root directory. Marmoset will run make on this Makefile to build your compiler. The Makefile must generate an executable (binary or shell script) called joosc.

As in previous assignments, joosc should process the Joos 1W files given on the command line, produce appropriate diagnostic messages on standard error, and exit with one of the following Unix return codes:

0: the input file is valid Joos 1W
42: the input file is not valid Joos 1W
any other value: your compiler crashed

In addition, joosc should generate assembly language code as described above.

Your build process and execution of joosc should not send or receive data from/to the internet in any way.

The Marmoset tests for this assignment take several minutes to run. Do not submit more than one submission at a time to Marmoset. If Marmoset reports that your previous submission has not been tested yet, do not submit another one. Denial-of-service attacks on Marmoset will result in disciplinary action.

Document Submission

Submit to Marmoset a PDF document explaining the design decisions you made in completing this assignment. The document will be evaluated based on both writing and technical content. Good writing often reflects good thinking. Be clear, thorough, and concise.

The document should be no more than five letter-sized pages long, should use a 10-12 point font, and should use reasonable margins and line spacing. It should have a title and should list the names and WatIAM (Quest) userids of the group members.

Documents submitted after the assignment deadline will not be marked and will receive a mark of zero. If you cannot finish the implementation by the deadline, document what you have by the deadline, and explain any unfinished parts in your document.

The document should typically cover the following topics:

Design and Implementation

This should be the main part of your document. Things to consider:

Organization of your compiler
Design patterns, special data structures and algorithms, libraries
Trade-offs you made between conflicting design goals (e.g., code simplicity vs. performance)
Challenges you ran into and how you addressed them
Any other noteworthy aspects of your design and implementation

Your goal is to enable someone unfamiliar with your compiler to understand it (without looking at the source code) and to convince the course staff that you have thought carefully about the construction of your compiler.

Testing and Known issues

Describe your test cases and the result of testing. Detail any known issues of your compiler. Your compiler will be evaluated on secret Marmoset tests at the end of the term, so you want to achieve good coverage of the input space and of your code in your own tests.

Contributions

Describe what each group member did.

Thoughts

How much time did you spend on the assignments? What did you like or dislike about the assignments? What would you change about them?
What aspects of your chosen programming language did you find helpful in writing the compiler? What aspects caused annoyance?
Any other thoughts?

The document will be hand-marked, with 50% of the marks for organization, clarity, and style, and 50% of the marks for technical content.