diff --git a/labs/example-lab.md b/labs/example-lab.md
index 1ab37a2e474b970380a234f494f1ad377e92f9dc..0dde1c3232f92b6f4967275eb339d5af7ae7f803 100644
--- a/labs/example-lab.md
+++ b/labs/example-lab.md
@@ -1,6 +1,6 @@
-# Example Lab
+# Example lab
-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.
+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
@@ -8,7 +8,7 @@ First, make sure you've followed the [Tools Setup](tools-setup.md) page.
**At this point, we strongly encourage you to take the time to read at least the first three chapters of the [Git Book](https://git-scm.com/book/en/v2). 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
+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).
@@ -16,6 +16,13 @@ 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](https://gitlab.epfl.ch/users/sign_in) and [registered in a
+group](https://gitlab.epfl.ch/lamp/cs206/-/blob/master/exercises/Group%20workspaces.md),
+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](tools-setup.md) page again.**
+
```shell
cd cs206-example
```
@@ -38,9 +45,9 @@ Now that we've obtained the project, let's take a look at its structure:
└── 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
+- 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 assignments, and you should write additional tests to check for cases that our tests do not cover.
+- 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
@@ -53,111 +60,122 @@ 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:
+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 `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.
+- 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`.
-It's now time to look at some code: the next section will show you how to start and navigate using the IDE.
+Time to go fix that bug! The next section will show you how to do that 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](https://lampepfl-courses.github.io/moocs/tools-setup/Tools%20Setup.html) page you should have VSCode installed by now, but don't start it just yet, instead run the following command from `sbt`:
+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:
+
```shell
-launchIDE
+code .
```
-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:
-
-
+(In this command the `.` is important, it's how we tell Code to run in the
+current directory)
-#### Data collection
+(if you see an error `Expected ';'` it means you're inside sbt, open a new
+terminal in the same directory)
-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:
-
-
+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 83 of the file ListsSuite.scala, so let's open that file:
+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 method:
+Here's the source code of the test:
-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.
+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:
-Recall that the second line of the stack trace was:
```scala
-at example.Lists$.max(Lists.scala:40)
+at example.Lists$.sum(Lists.scala:25)
```
-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:
+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](#troubleshooting) section.**
The hover is split into two parts: the first part is:
```scala
-(xs: List[Int]): Int
+def sum(xs: List[Int]): Int
```
-This means that `max` is a method that takes a `List` of `Int` as argument and
-returns an `Int`. The second part is the documentation of `max`. We can jump to
-the definition of max by `Ctrl+click` (`Cmd+click` on Mac) or by `right click ->
-Go to Definition` (*note: this is currently broken under Windows, you'll have to
-manually open `src/main/scala/example/Lists.scala`*). Once there we see:
+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: `max` calls `???`, which is a method defined in the Scala standard library that simply crashes your program: whenever you see it in an assignment it means that this is something you need to replace by your own implementation.
+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:
+```scala
+testOnly -- "--tests=.*max of a few.*"
+```
You now know enough to be able to work with the IDE, here are some additional tips:
- When you press `Enter` to make a new line, the IDE will automatically indent the
line if needed (for example, if the last word on the previous line was
`then`), however it will never unindent code for you (for example, when
- writing `else`). You can always indent code manually by pressing `Tab` and
- unindent it by pressing `Shift + Tab`.
-- When working on an assignment, you are free to create as many methods, classes and objects as you want. **But you shouldn't change the name of existing methods, classes and objects, because that may break the automated grading system, this is important!**.
-- You can see a list of all warnings and errors reported by the compiler by clicking on  at the bottom left of VSCode.
+ writing `else`). You can indent code manually by pressing `Tab` and
+ unindent it by pressing `Backspace` or `Shift + Tab`.
+- When working on an lab, you are free to create as many methods, classes and objects as you want. **But you shouldn't change the name of existing methods, classes and objects, because that may break the automated grading system, this is important!**.
+- You can see a list of all warnings and errors reported by the compiler by clicking on  at the bottom left of Code.
- The IDE can show you on hover the documentation of classes, defs and vals defined in the current project but support for external project is currently missing. To compensate for this, you can consult the documentation online:
- - The documentation for the Scala standard library is at [https://www.scala-lang.org/files/archive/api/2.13.1/](https://www.scala-lang.org/files/archive/api/2.13.1/)
- - The documentation for the Java standard library is at [https://docs.oracle.com/en/java/javase/11/docs/api/index.html](https://docs.oracle.com/en/java/javase/11/docs/api/index.html)
-- You can customize Visual Studio Code as much as you want, including installing additional extensions, but please avoid installing other Scala-related extensions: they may conflict with the one we use for this course.
-- While working on your assignment, you will regularly want to go back to the sbt console to run the tests. You could simply run the command `test` every time, but you can take advantage of the watch mode instead: if a command is prefixed by `~`, sbt will watch the source directory for changes and re-run the command every time a file is saved. So a possible workflow is:
-
- 1. Start sbt
- 2. Run `launchIDE`
- 3. Once the IDE has started, go back to sbt and run `~test` (or run `~compile` if you don't want to look at the tests)
+ - The documentation for the Scala standard library is at [https://www.scala-lang.org/files/archive/api/2.13.3/](https://www.scala-lang.org/files/archive/api/2.13.3/)
+ - The documentation for the Java standard library is at [https://docs.oracle.com/en/java/javase/15/docs/api/index.html](https://docs.oracle.com/en/java/javase/15/docs/api/index.html)
+- You can customize Code as much as you want, including installing additional extensions, but please avoid installing other Scala-related extensions: they may conflict with the one we use for this course.
+- While working on your lab, you will regularly want to go back to the sbt console to run the tests. You could simply run the command `test` every time, but you can take advantage of the watch mode instead: if a command is prefixed by `~`, sbt will watch the source directory for changes and re-run the command every time a file is saved. So a possible workflow is:
+
+ 1. Start the IDE
+ 2. Start sbt in the terminal (protip: you can start a terminal inside Code from the
+ menu: `Terminal -> New Terminal`)
+ 3. Inside sbt, run `~test`
4. Work in the IDE, and check the output of the sbt console from time to time
-- We're actively working on improving the IDE support using Visual Studio Code
- and interested in hearing your ideas and suggestions. Feel free to share your
- feedback (both good and bad) with us using Gitlab issues!
-
## Part 4: Running your code
Writing code and running tests is nice, but sometimes more direct feedback is useful, like when you want to experiment with Scala, or try out some methods that you implemented. You can do this using the Scala REPL (Read/Eval/Print Loop) or with a worksheet.
@@ -189,7 +207,7 @@ scala> List().isEmpty
res2: Boolean = true
```
-The classes of the assignment are available inside the REPL, so you can for instance import all the methods from `object Lists` and start using `max`:
+The classes of the lab are available inside the REPL, so you can for instance import all the methods from `object Lists` and start using `max`:
```scala
scala> import example.Lists._
@@ -216,14 +234,52 @@ In order to exit the Scala REPL and go back to sbt, type `Ctrl+D`.
A *worksheet* is a file where every line of code written in the IDE is executed and its output displayed as a comment.
#### Creating a worksheet
-Any file that ends in `.sc` is considered to be a worksheet by the IDE. Once VSCode is launched in a project, all you have to do is create a new file and save it (`Ctrl+N, Ctrl+S`) using any name as long as it ends in `.sc`.
+Any file that ends in `.worksheet.sc` is considered to be a worksheet by the IDE. Once Code is launched in a project, all you have to do is create a new file and save it (`Ctrl+N, Ctrl+S`) using any name as long as it ends in `.worksheet.sc`.
#### Using the worksheet mode
-Inside this file, you can type any line of code you would type in the REPL. To run the worksheet, either press the "Run this worksheet" button at the top of the file, or save the file. Each line of code will be executed one by one and its output is shown in green on the right. If your code contains an infinite loop, the worksheet will never finish running by itself, but you can cancel it by clicking the same button used to run the worksheet at the top of the file.
-
-**IMPORTANT**: When you run a worksheet, you should have sbt open and either `~test` or `~compile` running as recommended in Part 3, otherwise changes to other files won't be reflected in the output of your worksheet.
+Inside this file, you can type any line of code you would type in the REPL. The
+worksheet will be automatically run when the code is saved and auto-save is
+enabled by default. Each line of code will be executed one by one and its output
+will be shown in green on the right.
## Part 5: Submitting your Solution
-[Click here to learn how to submit your assignment.](grading-and-submission.md)
+[Click here to learn how to submit your lab.](grading-and-submission.md)
+
+# Troubleshooting
+
+## IDE features like type-on-hover or go-to-definition do not work
+
+It's likely that the build wasn't imported, we can import it manually:
+
+Click on the "m" logo in the left bar (where the red arrow is in the screenshot below):
+
+
+
+In the sidebar that appears, click on "Import build", then wait a bit:
+
+
+
+If things still don't work, try restarting Code (launch it in the same way you
+started it before, using `code .` from the project directory). If you're still
+having issues, try clicking on "Clean compile workspace" from the same
+sidebar.
+
+## Syntax errors for valid code in the IDE
+
+When first opening a file you might see some syntax errors for valid code:
+
+
+
+This is a known bug and can be ignored, as soon as you start typing in this
+file, these errors should go away (if they don't, try the import build
+instructions above).
+
+## Warning about Bloop installed version
+
+If you get a warning like this:
+
+
+
+Please click the first button "Turn off old server".
diff --git a/labs/images/bloop-update.png b/labs/images/bloop-update.png
new file mode 100644
index 0000000000000000000000000000000000000000..788bc5f8a71c9d1f9f71045a0749562420cc6f41
Binary files /dev/null and b/labs/images/bloop-update.png differ
diff --git a/labs/images/downloading-dls.png b/labs/images/downloading-dls.png
deleted file mode 100644
index 9c2aa05782059ed8e315a5d309c0ba813da82c1c..0000000000000000000000000000000000000000
Binary files a/labs/images/downloading-dls.png and /dev/null differ
diff --git a/labs/images/hover.png b/labs/images/hover.png
index 0fa09a5e447ffe124093ecf184b8ef0e051a349a..6065791252eb55880f76b370ccc572a3c24c5a1c 100644
Binary files a/labs/images/hover.png and b/labs/images/hover.png differ
diff --git a/labs/images/import-build.png b/labs/images/import-build.png
new file mode 100644
index 0000000000000000000000000000000000000000..509db479f515b1ed4133de36cc0b3da2a65c2985
Binary files /dev/null and b/labs/images/import-build.png differ
diff --git a/labs/images/max-def.png b/labs/images/max-def.png
deleted file mode 100644
index 14cd64f48a65de2a539b574537204946d1f4e411..0000000000000000000000000000000000000000
Binary files a/labs/images/max-def.png and /dev/null differ
diff --git a/labs/images/menu-metals.png b/labs/images/menu-metals.png
new file mode 100644
index 0000000000000000000000000000000000000000..869dfa1f1be431d05fca5d09a97d1ad7e76b85e9
Binary files /dev/null and b/labs/images/menu-metals.png differ
diff --git a/labs/images/metals-import.png b/labs/images/metals-import.png
new file mode 100644
index 0000000000000000000000000000000000000000..57f5c5e4af4139202d440c3fcb59c3d7665aae4a
Binary files /dev/null and b/labs/images/metals-import.png differ
diff --git a/labs/images/sbt-test-error.png b/labs/images/sbt-test-error.png
index e4c43ca9e2250f2de84e93f16d80c19131a74a72..3e0856eeee0a8276df224e2d30820f41addd12c1 100644
Binary files a/labs/images/sbt-test-error.png and b/labs/images/sbt-test-error.png differ
diff --git a/labs/images/sum-def.png b/labs/images/sum-def.png
new file mode 100644
index 0000000000000000000000000000000000000000..43d763dbf432bf203e85b1a9146b74092998a2b5
Binary files /dev/null and b/labs/images/sum-def.png differ
diff --git a/labs/images/syntax-error-bug.png b/labs/images/syntax-error-bug.png
new file mode 100644
index 0000000000000000000000000000000000000000..a2a53b294e0b8c848e5a524521268c74436b322d
Binary files /dev/null and b/labs/images/syntax-error-bug.png differ
diff --git a/labs/images/telemetry-allow.png b/labs/images/telemetry-allow.png
deleted file mode 100644
index 74ce0a6bd0cb17f5d6696d8430ccc0dc6441e3f7..0000000000000000000000000000000000000000
Binary files a/labs/images/telemetry-allow.png and /dev/null differ
diff --git a/labs/images/telemetry-status.png b/labs/images/telemetry-status.png
deleted file mode 100644
index 3163eb31cc8d5b60ce12e79a68ef00d25df9a19d..0000000000000000000000000000000000000000
Binary files a/labs/images/telemetry-status.png and /dev/null differ
diff --git a/labs/images/test-source.png b/labs/images/test-source.png
index 3bfc84dd11ed846b3549634542ac69d972d75533..dbd3f7e3a9b2629b196603664a17f07cdbdd2a7f 100644
Binary files a/labs/images/test-source.png and b/labs/images/test-source.png differ