example-lab.md

Example lab

The goal of this lab is to familiarize yourself with the infrastructure and tools used in this class. Even though the grade in this lab won't influence your grade for the course, it is important that you work through this lab 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 lab (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-s21/cs206-GASPAR.git cs206-example

If this command fails, make sure you've logged into gitlab and registered in a group, then wait a few minutes. If it still doesn't work it's likely that you didn't correctly upload your ssh key to gitlab, look at the last part of the Tools Setup page again.

cd cs206-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 labs
• 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 labs, 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 lab you should see many errors: that's normal, your job is to make the tests pass! But first, let's look at a failed test in detail:

This tells us several things:

• There's a test named sum of a few numbers (10pts) in the class ListsSuite in the package example
• The test failed (that's why it's in red and starts with ==> X) with an exception: NotImplementedError.
• This exception was thrown from the method ??? in scala.Predef in the file Predef.scala, this file is not part of our project (that's why it's in grey), to find the actual error in our code we have to look at where this method was called from.
• This method was called from method max in example.Lists in the file Lists.scala at line 40, this is where the bug is!
• It's also important to see where in our test this was called from, here it's line 102 of ListsSuite.scala.

Time to go fix that bug! The next section will show you how to do that using the IDE.

Part 3: Using the IDE

Setup

Let's upgrade the IDE support first, close VSCode if it's open and run:

code --force --install-extension scalameta.metals

Startup

To start Code, run the following in the project directory (the same directory where you previously ran sbt), it's important to run Code in the correct directory or it won't be able to import your project:

code .

(In this command the . is important, it's how we tell Code to run in the current directory)

(if you see an error Expected ';' it means you're inside sbt, open a new terminal in the same directory)

The first time the IDE starts, it will take some time to download more components, eventually it will ask you to import the build, please click "Import build":

You'll need to wait a bit for the import to finish, if an error appears try closing and restarting Code in the same way we started it above.

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 102 of the file ListsSuite.scala, so let's open that file:

Here's the source code of the test:

The first line gives a name to the test, the second line runs sum(List(1, 2, 0)) and tests that it equals 3, but in our case we never got to this point because an exception was thrown, recall that the second line of the stack trace was:

at example.Lists$.sum(Lists.scala:25)

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

If hovering doesn't show this see the Troubleshooting section.

The hover is split into two parts: the first part is:

def sum(xs: List[Int]): Int

This means that sum is a method that takes a List of Int as argument and returns an Int. The second part is the documentation of sum. We can jump to the definition of sum by Ctrl+click (Cmd+click on Mac) or by right click -> Go to Definition. Once there we see:

Now we know why the test failed: sum calls ???, which is a method defined in the Scala standard library that simply crashes your program: whenever you see it in a lab it means that this is something you need to replace by your own implementation.

Once you've implemented this method, you can run test from sbt again to see if the test passed, if you want to run a single test instead of all tests you can use testOnly instead and specify part of the name of the test:

testOnly -- "--tests=.*max of a few.*"

You now know enough to be able to work with the IDE, here are some additional tips: