01-example.md

Example Assignment

The goal of this assignment is to familiarize yourself with the infrastructure and tools used in this class. Even though the grade in this assignment won't influence your grade for the course, it is important that you work through this assignment carefully.

Part 1: Obtaining the Project Files

First, make sure you've followed the Tools Setup page.

At this point, we strongly encourage you to take the time to read at least the first three chapters of the Git Book. If you just copy-paste the commands we give you without understanding them, it's likely that you'll make a mistake somewhere and waste time. Git can be a huge productivity enhancer when used correctly, so it's definitely worth the investment!

We'll starting by cloning the repository containing all our assignment (make sure to replace GASPAR with your EPFL username (the one with letters, not the one with number) in the following command).

git clone -b example git@gitlab.epfl.ch:lamp/student-repositories-f19/cs210-GASPAR.git cs210-example

cd cs210-example

Now that we've obtained the project, let's take a look at its structure:

.
├── build.sbt
├── project
│   ├── ...
└── src
    ├── main
    │   └── scala
    │       └── example
    │           └── Lists.scala
    └── test
        └── scala
            └── example
                └── ListsSuite.scala

• All the files ending with .sbt or in the project/ directory are build tool configuration files: you don't need to modify them or look at them for any of the assignments
• The project sources are in src/main/scala/
• The sources of the unit tests are in src/test/scala/. You will need to make all the tests pass to complete the assignments, and you should write additional tests to check for cases that our tests do not cover.

Part 2: Using sbt

Start sbt by running:

sbt

Once it's finished starting (this may take a while), you'll be able to enter sbt commands. You can compile your project using compile and run the tests with test (this automatically compiles your code if needed to). Note that if compilation fails, no tests will be run. The first time you'll run test in an assignment you should see many errors: that's normal, your job is to make the tests pass! To do this, it's useful to understand in details what the test output means, here's an example:

This tells us several things:

• There's a test named max of a few numbers (10pts) in the class ListsSuite in the package example
• The test failed with an exception: scala.NotImplementedError: an implementation is missing. This is followed by a stack trace showing where the exception happened.
• This exception was thrown from the method scala.Predef$.??? in the file Predef.scala at line 284.
• This method was called from example.Lists$.max in the file Lists.scala at line 40.
• ... which was itself called from the method example.ListsSuite.max of a few numbers in the file ListsSuite.scala at line 83.

It's now time to look at some code: the next section will show you how to start and navigate using the IDE.

Part 3: Using the IDE

Startup

This course is run with an experimental version of Scala called Dotty that will become Scala 3 in the future. Because it's so new, most IDEs like IntelliJ and Eclipse are unlikely to work correctly with it. Thankfully we've developed our own IDE support. It's designed to work with any text editor but we currently only support VSCode. If you've followed the Tools Setup page you should have VSCode installed by now, but don't start it just yet, instead run the following command from sbt:

launchIDE

This will download the Dotty extension for VSCode and set everything up. You will need to do this for every assignment, and we recommend always using this command to start the IDE.

The first time the IDE starts, it will take some time to download more components, as displayed in the bottom left:

Data collection

Fixing bugs in the compiler and the IDE is much easier when we have all the information needed to reproduce them. To help us achieve that, we've added an optional data collection mechanism in the IDE extension, when you start an assignment, you'll see the following pop-up:

You are free to either allow or deny the data collection, but we would appreciate it if you clicked "Allow". If you do, you'll contribute to making Scala better! If you change your mind, you can turn on or off the data collection at any time by clicking on the "Scala telemetry" button on the bottom-left of the IDE window:

Usage

It's now time to dig in! Earlier we talked about a failing test, the stack trace told us that it was failing on line 83 of the file ListsSuite.scala, so let's open that file:

Here's the source code of the test method:

This looks like a regular method except for a few things:

• It starts with @Test, this is an annotation that lets JUnit (the testing framework we use) know that this is a test method.
• The name of the method starts and ends with backticks (`): this is what allows us to put spaces in the method name. Normally, names defined in Scala cannot contain special characters such as spaces or dashes, but any character is allowed as long as backticks are put around the name (even emojis 🔥!). We've taken advantage of this in the tests we define to give them nicer names: max of a few numbers failed is easier to read than maxOfAFewNumbers failed, but this is just a convention: if you define your own tests you're free to name them however you want.

Recall that the second line of the stack trace was:

at example.Lists$.max(Lists.scala:40)

This tells us that the crash happened when calling max, we can hover with our mouse over the call to max in the test method to get more information on it: