View the Project on GitHub TiarkRompf/cs502

Project 1: L3 Desugaring

The purpose of this first assignment is to get familar with the L3 language and the existing code base of the L3 compiler and interpreter. You should take it seriously, as it guides you through the L3 code base and it explains how to set up the tools that will make code development efficient. This assignment will require completing 5 steps:

Step 1: Setting up the Infrastructure

The first step of this assignment is to set up your environment, as described in the Getting Started - Tools page. If you have any trouble installing the tools for the course ask the TAs for help. Note that all of the prerequisites, even Eclipse, are installed on the CS department linux machines, and you are free to use an X server such as xming to do the project remotely. Alternatively you may do the project on your own machine and then upload your results to your home directory on data.cs.purdue.edu and turn in your results using turnin.

Download the Skeleton Code:

The skeleton code is available at https://www.cs.purdue.edu/homes/rompf/cs502/project/proj1.tgz See the course Piazza for access credentials. To download the code from a Linux terminal, go into the directory that you intend to use for the course (e.g ~/cs502) and do the following:

wget https://www.cs.purdue.edu/homes/rompf/cs502/project/proj1.tgz --http-user=USER --http=password=PASS
tar -xvf proj1.tgz
cd proj1

Step 2: Desugaring in the L3 compiler

Now you should have decompressed the skeleton code and should have found a compiler directory:

$ cd proj1
$ cd compiler
$ sbt compile
$ sbt eclipse

After running sbt eclipse you should be able to load the project in Eclipse using File > Import... and General > Existing Projects into Workspace and point Eclipse to the acc2016-groupXX directory. It should load a project called l3-compiler, as described here.

Now, run the program examples/hello.l3. This can be done in two ways:

$ sbt "run ../examples/hello.l3"
[info] Loading project definition from ...
[info] Set current project to l3-compiler (in build file:...)
[info] Running l3.Main ../examples/hello.l3
[error] (run-main) scala.NotImplementedError: an implementation is missing

You will notice that it fails with a “not implemented” error (with a long stacktrace). Your next task is to add the missing pieces to the syntactic sugar translation. Navigate to the bottom of file src/l3/L3Parser.scala. You will notice that some methods are implemented in terms of a ??? method, which throws a runtime exception. Rewrite those method bodies according to the rewrite rules on the slides shown in this week's lecture.

Once you provided implementations for sBegin and sFun in src/l3/L3Parser.scala you should be able to run the hello.l3 example. Now implement all the other desugaring methods.


Step 3: Test cases for the desugaring

As you are developing the desugaring, it would be good to verify your implementation. For this assignment, you have tests that make sure your desugaring is correct. There are two categories of tests: whitebox tests, which verify the trees you generate (L3DesugaringWhitebox.scala) and blackbox tests, which check the output of running the compiled program (L3DesugaringBlackbox.scala). To run the tests, it is easiest to navigate to the l3.test package in the test/ directory and open up one of the files. Then from the Run menu select Run As > Scala JUnit Test. You can also use sbt:

$ sbt test
[info] Test run started
[error] Failed: : Total 21, Failed 3, Errors 0, Passed 18, Skipped 0

Even with a perfect implementation the last three whitebox tests will fail. Your next task is to complete the test suite so all tests pass. To do this, have a look at methods testSAnd, testSOr and testSNot in test/l3/test/L3DesugaringWhitebox.scala. They contain ??? instead of the expected output. Fill in the correct tree so the test suite passes.


Step 4: Completing the Library Code

Once you are done with the desugaring and all tests pass, run printint.l3 and enter a number when asked to.

> run ../library/lib.ml3 ../examples/printint.l3
[info] Running l3.Main ../library/lib.ml3 ../examples/printint.l3
Enter a number: 12
You entered
[success] Total time: 2 s, completed Feb 15, 2013 4:03:13 AM

You will notice that it cannot print the number you have entered: it is missing a library function int-print that accepts a number and prints it to the console. Your last task is to add the body of int-print in library/integers.l3 such that it prints the correct output. Make sure it prints a given number to the base of 10 and that it can handle negative numbers as well. Hint: implement it recursively in terms of char-print and int->char-digit. Modify printint.l3 so that it prints the number you have entered and verify that it runs correctly.


Step 5: Submitting the Assignment

At this point everything should be working: compiler code should be ready, local tests should be passing and all examples should be running fine. When you are comfortable with the status of your project, it's time to use the turnin command on one of the CS machines to submit your code. You may use data.cs.purdue.edu or any of the lab machines. If you developed your assignment on a different machine, make sure to copy your files to one of the CS machines remotely before running the turnin command.

To turn in your project, go to the same directory that your proj1 directory lives in (you do not have to name it proj1, but it must contain all of the project files) and type:

turnin -c cs502 -p project1 proj1 

You can verify the status of your turned in project by running:

turnin -c cs502 -p project1 -v

The rest of this page describes the use of sbt and Eclipse in this assignment.


Tutorial: Simple Build Tool (sbt) for the l3 compiler

Simple Build Tool performs a series of tasks for you:

Sbt can work in two modes: as a command-line tool, invoked with

$ sbt <task>

and as a console:

$ sbt
[info] Set current project to acc-1 (in build file:/...)
> <task>

Both the console and the command line have a series of common useful tasks:

Preceeding any of the task with "~" (tilda, no quotes) will run the task each time you change a file:

$ sbt '~test-only my.Test' # quotes are necessary to prevent the shell from expanding ~ to /home/$USER
1. Waiting for source changes... (press enter to interrupt)

Tutorial: Eclipse for the L3 Compiler

In order to work on the compiler in Eclipse you need to create the Eclipse project files. It is easiest to do using sbt:

$ sbt eclipse

Don't worry about the errors shown by sbt -- it is set to download source archives for all the projects the compiler depends on -- and some of the source archives are not available, but this will not affect the Eclipse functionality.

To add the project in Eclipse, from the File menu, choose Import.. and then General > Existing Projects into Workspace. For the root directory, pick the directory where you unpacked the exercise sources. Eclipse should locate the l3-compiler project that sbt created and import it. 

You will now need to specify that the project needs to be compiled with the Java 8 library. In the Package Explorer on the left, right-click on your project and go to Properties-> Java build path -> Add library -> JRE system library. Click on alternate JRE -> Installed JREs -> Add, and navigate to the home directory of your Java 8 installation.

You can now build and run the L3 compiler / interpreter directly in Eclipse. If you get errors regarding the econding of the source files while building the project, you have to make the project encoding as UTF-8 in the project properties -> resource menu. For running (or debugging) create a new Run Configuration of type Scala Application and specify l3.Main as main class. You have to specify one ore more source files as the arguments (../examples/hello.l3 is a good start).

You can also run the test suite from within Eclipse. For the first assignment, you have two test suites:

To run a test suite, you can use either sbt test or navigate to the test suite source file (in the test directory), open the test suite file and choose Run > Run as > Scala JUnit Test from the menu.

A good video on using Eclipse can be found on the ScalaIDE main page.