CS 434 Lab Guide

Basic Expectations

I assume you are comfortable with the following tools. If not, you should familiarize yourself with them ASAP. The semester will go much smoother if you invest a small amount of time learning to effectively use the necessary tools.

• Basic BASH shell commands and a programmer’s editor.

• The standard git commands:

  $ git clone REPOSITORY
  $ git status
  $ git add
  $ git commit -m MESSAGE -a
  $ git push
  $ git pull

  You can find more details on git and GitHub in the official git documentation and the GitHub documentation.

• Writing Markdown documents.

• Java, C, and x86 assembly code, at the level of CS 136 and 237.

• The Scala language.

  You may have seen Scala in CS 334. That background is sufficient. If you did not, you should go through the Scala materials from Week 1 carefully, and revisit anything that didn’t make sense during the first lab. We use Scala 3; if your experience is with Scala 2, skim the Scala 3 Book to pick up the newer syntax.

Installing the Toolchain on Your Own Computer

All the projects build with sbt, the standard Scala build tool. Everything is already installed on the lab machines. On your own computer, the easiest path is Coursier, which installs a JDK, Scala, and sbt in one shot:

$ cs setup

You need a JDK (17 or later is recommended) and sbt on your PATH; sbt downloads the pinned Scala compiler version for each project automatically the first time you build.

Editors

You may use whichever editor you like. The one I will be able to support most effectively is VS Code with Metals: Install the “Metals” extension, then use “File | Open Folder…” on a project directory (the folder containing build.sbt). Metals will ask to import the build — click “Import build” and wait for the first import to finish. You then get error squiggles, completion, jump-to-definition, hover types, “run” / “debug” code lenses above main methods, and a test explorer.

Working in a Shell

All the operations you need are sbt commands, run from the project directory (the one containing build.sbt):

Building

$ sbt compile

The first build of a project downloads the Scala compiler and libraries; later builds are fast. For an edit-compile loop, run sbt once to get its interactive prompt and use ~compile to rebuild automatically on every save.

Running

The following runs the compiler on the file test/test1.ic:

$ sbt "run test/test1.ic"

For scripted testing over many files, build a standalone jar once and run it directly — this avoids sbt’s startup time on every file:

$ sbt assembly
$ java -jar target/icc.jar test/test1.ic

The starters also include a specTests runner that runs the compiler on every .ic file in a directory (each in a fresh JVM) and compares the output against the .expected files:

$ sbt "specTests tests/pa1"

Unit Testing

Unit tests are designed to test individual components in a system. They help tease out errors without running the whole project. Having good unit tests is essential for catching mistakes early and effectively debugging them. The unit test library we’re using is MUnit; look at src/test/scala in each starter for example tests. Run them all with:

$ sbt test

To run a single suite: sbt "testOnly tests.LexicalTests". You should write unit tests early and often — they are one of the best defenses against bugs.

Debugging

Both VS Code/Metals and IntelliJ can run the compiler under a debugger: click the “debug” code lens (Metals) or create a Run Configuration with main class ic.Compiler and program arguments like test/test1.ic (IntelliJ), then set breakpoints in the editor margin. Play around with the debugger early — it will be handy when the code gets more sophisticated later.