Using the Visual Studio Code editor

Visual Studio Code is an open-source, cross-platform text editor. Scala is supported via an official plugin. This is a short guide for installing and using Visual Studio Code (VS Code) for working on programming assignments in the course.

(The exercises should work well with other IDE’s or build systems that support sbt builds, so you are free to use your own set-up if you like, although the course staff might not be able to help you with it.)

Danger

Do not activate any AI tools – using AIs when solving the exercises is considered cheating! (This includes github copilot, which Code might suggest, as well as any other extensions providing AI/LLM coding help.)

---

On Aalto Linux computers

Warning

There is a bug in a software package used by the Scala Metals build-server that reacts with how the home-directories are configured in the exercise classrooms.

Do not store your exercises under Desktop, Download or Documents. Instead create a new folder in your user home directory for the exercises.

You may want to consider using IntelliJ on the Aalto Workstations instead if you are experiencing issues.

A standard version of VS Code is available through the start menu in the Aalto Linux Workstations. Open a menu or terminal and run code.

To use a newer version of code than the default installation (will help if you are experiencing issues) do the following:

1. Open a terminal

2. (On VDI remote desktops only) Authenticate to make vscode (and other) software module available: kinit

3. Load the vscode module by the command: module load vscode/a1120.2025

4. Start VS Code by the command: code

   Do not forget the /a1120.2025 part of the module name. It denotes the version of VS Code used in this course, and contains tweaks to make the Scala plugins work better on VDI.

The VS Code editor should now open, and you are ready to start working.

If this is the first time you start VS Code for the course, make sure to also do the steps under Setup below to install Metals and properly configure Code.

Installation on personal computer

Windows 11MacOSLinux

On Windows you have two choices for how to set up VS Code: you can either develop directly on Windows, or in a so called devcontainer, a virtual machine, running under Windows. The devcontainer option is experimental this year, but it can help if you experience problems related to JDK versions et c.

The installation steps are somewhat different, so we provide both below.

Development on WindowsDevelopment in a devcontainer

In order to run VS Code with the Scala tools under windows, you will need to install a Java Development Kit (JDK), the sbt tool, and VS Code.

1. Install JDK: Download and run installer from Adoptium.net While installing, make sure the option to update JAVA_HOME is selected. This is especially important if you have a user name with ‘special’ characters, such as åäö.

2. Install sbt: Download and run the msi installer from scala-sbt.org (This is to be able to open a scala REPL in the project easily.)

3. Install VS Code: Download and run the installer from https://code.visualstudio.com/.

4. Proceed to Scala setup below

---

Setup

Scala extension setupDevcontainer extension setup

1. Run the VS Code application, select the extensions tab on the left-hand side, or in the menu View → Extensions

2. In the search field, search for “metals”, choose Scala (Metals), and hit install. This will install the Metals language server which adds IDE-like features such as code actions, completion, and syntax and error highlighting, among other things that make the development process concise and convenient.

Installing the Scala (Metals) extension.

Note

Scala (Metals) is incompatible with the VS Code extensions Scala (sbt) and Scala Language Server. Under Windows 10/11 it may also conflict with the WSL extension. If you have used VS Code previously and have any of these extensions installed, make sure to uninstall or disable them for the assignment workspaces.

---

Workflow

Standard workflowWorking in a devcontainer

1. Download an exercise sbt source package from A+

2. Extract it to an assignment directory

   Warning

   If you are using VS Code on an Aalto Workstation do not place the assignment projects under any of the “standard” folders Desktop, Downloads, or Documents (or any other linked folder). Due to an open issue, compilation errors are not handled correctly. Instead, place them under some sub-directory you have created in your home directory.

3. Open the project: navigate to the menu bar, proceed with File → Open Folder…, and select the extracted assignment folder

   

   Open the assignment folder containing the project and src folders (and the file build.sbt, if you can see it).

Common workflow

• Next, VS Code will detect the assignment workspace and ask what you want to do with it. Choose Import build, and wait while the assignment is set up; progress is displayed in the blue status bar located at the bottom of the window. (If the pop up disappears, do not worry, you can get it back by clicking on the little ‘bell’ icon furthest to the right in the same blue status bar.)

Select Import build when asked.

Warning

If you do not get prompted to Import the project, make sure you have opened the correct folder or VS Code will not import it as a Scala project. (It needs to be the assignment folder containing the build.sbt file, and the project and src directories.) If this has happened, just close the current folder from the File menu and open the right one.

• Recent versions of VS Code will show a dialogue asking if you trust the project. You should select Yes, I trust the authors to be able to build and debug the exercise. (If you pick the No option by mistake you can change it later.) If you organise a separate course folder (as you should!) for A1120, tick the box Trust the authors of all files in the parent folder… to prevent this popup every time you import a new exercise.

  

  If asked, you need to select Yes to trust the exercise and activate the build tools.

Note

Treat trust seriously. Build scripts, such as those of sbt, are often full-fledged scripting languages in themselves, and they have the power to read and write files on your computer. For example to seamlessly install missing libraries and execute components as needed. This is why many modern development tools, such as VS Code and IntelliJ, asks you if you trust a project before it imports a project. Take this seriously. If you are uncertain if you trust the authors of a software project you have just downloaded, it is often safest to choose to open it in a preview-mode first. For this course, however, we hope that you trust the teaching staff sufficiently to import the exercises.

• If this is the first time you open a Scala project VS Code may download and install Metal extension components at this point. This may take a minute or two.

• Read the provided program code and documentation

• Develop your solution. The places you should insert your code are usually marked with ???

  

  Develop your solution.

• Compilation errors are indicated in the status bar, in the program code, and the explorer. The full error messages are displayed in the problems tab: View → Problems

  

  It is hard to miss problems with your code…

• Run tests by opening the corresponding .scala file in the test folder and click on the green ‘play’ ( ▶ ) symbol to the left of the class name. Output will appear in the Debug Console (should appear automatically, otherwise go to View → Debug Console). Note: The test/run links will only appear if your program compiles, so make sure that your code is error-free and saved before testing it. Always run the provided unit tests and check if they pass

Note

Unit tests and A+ grading performs different tasks. Just because your code passes all unit tests does not guarantee a full score by the grader. On the other hand, you may not necessarily need to solve all the tasks in an exercise to submit your solution for grading and get some points. Most exercises award points for every individual task, so you can get points from an exercise even if some unit tests fail. (But in the real world for professional programming, never ship code which fails a unit test.)

Running unit tests.

• When you are happy with your solution, submit the required .scala files to A+ for grading (you can drag-n-drop the files from your system’s file manager/explorer in modern browsers; you can also open a system file manager from Code by right-clicking on a file tab and selecting Open containing folder).

Trouble-shooting

The Test and Run links don’t appear in my source code

• First, check that your code is error free and that you have saved it. The links only appear for programs on successful compilation.

• Were you asked to import the project when you opened it?

  • If not, then you may have opened the wrong folder. The most common ‘wrong’ folder is a folder containing the assignment folder (on Windows machines, this can easily happen if the unzip creates a new directory to place the contents in and you choose the outer folder). The result is that the assignment is not recognised as a Scala project. The fix is easy: close the current folder File → Close Folder and open the right one (the one extracted from the zip file containing the “a” directories, and build.sbt).

    

    The assignment folder (containing build.sbt) must be the top folder you open for the project to be recognised (left). If you open a containing folder (even if it has the same name) it will not be recognised (right). If you are not asked to import the project you have the wrong folder.

  • You were asked to import, but choose not to, or clicked away the pop-up: click on the ‘bell’ icon to bring back the pop-up, or trigger a new import from the BUILD COMMANDS tab (see below), or by closing the folder and opening it again as described above.

• If none of the above, the build server may have crashed. It is uncommon, but can happen.

  1. Go to the Metals tab (the m icon in the vertical tool-bar). Under BUILD COMMANDS click on Restart build server. It will take a few seconds for the build server to come up again, you can see the status in the message-bar.

  2. You can then trigger Metals to re-scan the file for compilation by making a small change (e.g. inserting an empty line) and saving the file.

  3. If the above did not work you can also force a re-import of the project by clicking on Import Build in the same menu.

  

  The Scala Metals build build commands.

  1. Finally, if the links has stopped working suddenly, it could be that the old build process has crashed. In that case, try to terminate it as described in the next section.

Scala not found

This error happens if you have the Code Runner plugin installed in your workspace. Disable it for the current project and runt code and tests through Metals (see basic tasks for more information about ow to run tests and main programs with Metals).

Java not found

1. Check that you do not have an old version of VS Code (if you have installed it previously and not updated it). If so, update it or reinstall it.

2. If the problem persists:

1. Make sure JDK 11 was properly installed

2. In the extensions tab select the cogwheel for Scala (Metals) and open the settings. Find the Metals: Java Home field and fill in the path to the JDK 11 (in windows use explorer, then right-click in the address-bar and select copy-as-text, then paste this value into the field).

Error message about build server

• Windows 11 : This could be because path to your programming exercise contains spaces. The current release of the Metals build-server does not play nice with all windows 11 paths. Fix: remove the spaces, or install the pre-release of Metals as shown in the next item.

• (Windows, if you have a user name containing ‘special’ characters [such as ä and ö] or spaces [on Win11]) Sadly, paths are still not always handled properly, and some with non-ASCII characters in their usernames have reported problems under Windows, where the build server crashes. This should be fixed in newer versions of Metals, so try to update to the newest version if you experience this problem. Alternatively switch to using IntelliJ instead.

  

  Use the Metals pre-release if you have a space in your user name on Windows 11 and are experiencing problems. Click on the ‘cogwheel’ at the Scala (Metals) extension and select Switch to Pre-Release Version.

• Can happen if the wrong, or multiple versions of Java is installed

  1. Make sure JDK 11 was properly installed

  2. In the extensions tab select the cogwheel for Scala (Metals) and open the settings. Find the Metals: Java Home field and fill in the path to the JDK 11 (in windows use explorer, then right-click in the address-bar and select copy-as-text, then paste this value into the field).

• Conflicting extensions

  If you have either of the VS Code extensions Scala (sbt) or Scala Language Server, uninstall or disable that extension.

• A defunct build server process is left on your system

  This could be the case if the build process works initially, but then crashes. In this case it is worth trying to terminate the process and restart VS Code:

  • Shut down Code, then

    • (MacOS/Ubuntu) open a terminal and run pkill java to terminate all java processes

    • (Windows) open the task manager and terminate any running java processes

  • Restart Code. This should create a new build-server process.

• (Windows) Disable WSL for project

  If you have previously used Code for other courses or projects, you may have the WSL (Windows Subsystem for Linux) extension installed. This extension can interfere with Scala (Metals). The solution is to disable the WSL extension for your Scala projects (Extensions, WSL, click the drop-down menu at Disable and select Disable (Workspace), then restart Code.)

• (OneDrive/iCloud): Some (but not all) users keeping their exercise folders on a cloud drive, such as OneDrive or iCloud, have reported issues with the build server. If you do, and experience problems, it can be worth trying to move the exercises to a location that is not actively synchronised with the cloud.

sbt command not found

• If you have started VS Code before installing sbt you need to either restart Code or open a new terminal as a terminal is not aware of programs installed after it was opened.

• (Windows) You may have to add the sbt directory to your system PATH. See e.g. instructions in this post.

Error: code: No such file or directory (Aalto Linux workstation)

• If you get an error message saying code: No such file or directory when trying to run code, then you may have forgotten to load the module properly.

• A successful call to module load vscode/a1120 will print nothing. If you get an error message here, check that you have typed the command correctly.

• If you want to check that the module is loaded you can give the command module list.

Error: the following module(s) are unknown (Aalto Linux workstation)

You have probably forgotten to run kinit (if using a remote desktop).

• You need to run kinit and load the vscode/a1120 module every time you log in to the VDI workstation

• If you get an error message saying Lmod has detected the following error:  The following module(s) are unknown: "vscode/a1120" you may have forgotten to run kinit on VDI

Note

kinit is part of the kerberos suite, a protocol for authentication of network resources. It will ask for your Aalto password in order to provide the extra software modules of which VS Code is a part. In the Aalto computer labs this is done automatically when you log in, but if you connect to a virtual machine you have to do it yourself. This is current Aalto IT policy, however in general, always think twice when somebody asks you to execute a program which asks for your password.

Warning: Code navigation will not work

This is generally nothing to worry about.

Some recent versions of Scala Metals will somewhat annoyingly pop up a warning saying that code navigation will not work because Java sources are not installed when a project is opened although it will work fine for the assignment project. This message can be ignored - you will still be able to navigate and debug the assignment code.

This warning is shown by some versions of Scala Metals and can be ignored.

Devcontainer: Workaround for non-ascii usernames (Windows)

The VSCode Dev Containers plugin by Microsoft fails to install WSL and Docker for Windows users with non-ascii characters (e.g. “öäå”) in their name. The failure is indicated by the error “WSL not found after install”. The workaround for this is to install WSL manually.

This warning can be fixed by installing WSL manually.

Run wsl --install --no-distribution in Windows Terminal and then restart your computer. Then proceed with opening the course module.

Devcontainer: If Docker installation fails (Windows)

In VS Code, try the following: Open the command palette by CTRL+SHIFT+P and run Dev Containers: Reinstall Docker in WSL then restart vscode

Devcontainer: Running tests fails

Sometimes in the devcontainer metals is too slow to compile and start a program, which causes VSCode to time out and ultimately give up.

If you see this, give metals time to compile the code.