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 developing one’s programming assignments in the course.


Using Code on your own computer

(See the Aalto workstation documentation for instructions on starting Code on the Aalto Linux computers.)

If you already have VS Code on your computer (for example after doing CS-A1120), make sure to upgrade to the latest version! (See Updating an existing installation below for more information.)

First things first

  • Install JDK 11

    • Windows 10/11: download and run installer at Adoptium.net

    • MacOS: use a package manager such as sdkman! to install Java 11 (see sbt instructions too see how to install both Java 11 and sbt)

    • Ubuntu Linux: install package openjdk-11-jdk

    • Other Linux distributions: consult your package manager

  • Install sbt

macOS

  • Download the .zip file from https://code.visualstudio.com/ and extract it

  • Optional: move the now decompressed VS Code application into the Applications folder

Linux

  • Ubuntu: Install “Visual Studio Code” in “Ubuntu Software”

  • Debian-based distributions (Debian, Ubuntu, etc.): Download the .deb file and run the installer

Windows 10

Updating an existing installation

If you already have VS Code installed on your computer make sure that it is updated to the latest version before taking this course. The Scala language extensions can cause issues with old versions of Code.

The easiest way to make sure that you have the latest version is to follow the instructions above to re-install Code for your platform. You can also check which version you currently have and download updates from the Help menu inside the application.

Then, make sure that the extension Scala Metals Extension is updated to the latest version as well. This is usually automatic, but if you have not restarted VS Code in a long time, you could have an old version. You can see the status of Metals in the Extensions tab of VS Code.

You do not necessarily need to update JDK 11 or sbt if you have previously installed and used them for CS-A1120.


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 “scala”, 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.

_images/vscode-scala-metals.png

Installing the Scala (Metals) extension.

Note

Scala (Metals) is incompatible with the VS Code extensions Scala (sbt) and Scala Language Server. Under Windows 10 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

  • Download an exercise sbt source package from A+ and extract 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.

Warning

Placing exercise folder in cloud storage (such as iCloud or OneDrive) can sometimes cause problems due to synchronization conflicts.

  • Navigate to the menu bar, proceed with FileOpen Folder…, and select the extracted sbt assignment folder

    _images/vscode-open-folder.png

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

  • 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 A1140, tick the box Trust the authors of all files in the parent folder… to prevent this popup every time you import a new exercise.

    _images/vscode-trust.png

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

  • 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.

  • 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.)

_images/vscode-import-project.png

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.

  • Read the provided program code and documentation

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

    _images/vscode-insert-code-here.png

    Develop your solution.

  • Some syntax errors will be shown as you type, and the build server will compile your code every time it is saved, so save often

  • 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: ViewProblems

    _images/vscode-error-indication.png

    It is hard to miss problems with your code…

  • Run tests or programs by opening the corresponding .scala file in the test folder and click on the green ⯈ icon next to the corresponding test or main class. (Failed tests will show as a red ⛒, click on it to re-run the test.) Output will appear in the Debug Console (should appear automatically, otherwise go to ViewDebug Console). Tests can also be run and overviewed from the Testing tab.

    • Note: Test/Run links will only appear if your program compiles, so make sure that your code is error-free and saved before testing it. Older versions of Metals will show links named ‘Run’ or ‘Test’ instead of the icons.

  • Always run the provided unit tests and check if they pass

    _images/vscode-run-test.png

    Running unit tests from either the Test tab, or the test source directly. Results are shown in the Debug Console.

  • 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).

Opening an sbt console from Code

While developing your solution it is sometimes handy to be able to test things in the interactive sbt Scala REPL. To start using it do the following:

  • Go to View → Terminal. This will open up a system terminal in your project. Here you can give system commands just as from a normal terminal window.

Note

Use the main menu to start the terminal. Do not use the popup menu from one of the project files, this will start a terminal in the specific sub directory of that file, and the sbt console may not work properly.

  • Give the command sbt "~ console". This will start a Scala console using the sbt build tool, and additionally tell sbt to watch the assignment files for changes. Note that this uses a separate build mechanism from Code, so the first time you run it you may have to wait a few seconds for the files to compile.

_images/vscode-console-1.png

Give the command sbt "~ console" in a Code terminal tab.

Note

If the standard short-cuts pasting clipboard text is not working in the VS Code terminal try using Shift+Insert.

  • You should now see the familiar scala> prompt. Now you have a REPL ready to use, why not test it with some basic Scala? You can also import code from any packages in the current assignment, if needed.

    _images/vscode-console-2.png

    Interactive Scala in the sbt console.

Note

  • If you happen to only give the command sbt by mistake, you will enter the sbt build system (the prompt starts with sbt). That’s not a problem, just enter the command ~ console to start the Scala console from there instead.

  • The console will not start if you have a compilation error in your code.

  • If the terminal gives an error such as command not found: sbt then you need to check that sbt is properly installed and available in your system path.

  • Use Ctrl+d to quit the console, or recompile (if there are saved changes to your source files this will trigger a recompile, otherwise it will quit the console).

Trouble-shooting

The system asks me to unlock my keyring

Directly when starting VS Code a popup like the one below appears on some systems/version of Code, asking you to unlock your password keyring:

_images/vscode-keyring-popup.png

This request can be cancelled.

This is a known issue for versions of Code on some Linux desktops (including the Aalto Workstation and VDI). The keyring is not needed for anything in this course, so you can safely click cancel (twice) to get rid of the popup, and then use Code as normal.

Metals says that the build is mis-configured

After importing a project, Metals shows a popup warning looking like in the following screenshots:

_images/build-warning-1.png

This warning can most likely be ignored.

_images/build-warning-2.png

This warning can most likely be ignored.

Unless you have manually edited build.sbt in an exercise project, this is likely due to Metals not registering all Java/Scala jar sources. Code navigation, debugging, and building of the exercise will still work. You may click away these warnings.

Metals is Unable to find Java

When VS Code is starting up Metals, it stops with the error Unable to find a Java 11 or Java 17 installation:

_images/metals-unable-to-find-java.png

If you get this message, start by checking that you do not have an old version of VS Code.

One possible source for this error is that you have an older version of VS Code installed, while the Metals plugin extension is updated to the newest version. (Perhaps you installed it for another course or project, and turned off automatic updates.)

To make sure you have an up-to-date version of Code, select Check for updates in Code under the Help or Code menus (depending on your OS). Once Code has been updated, restart it. (If you for some reason do not want to update VS Code, you need to roll back Metals to an older version, e.g. to 1.11.1.)

If the error occurs despite you having an up-to-date version of Code, then it might be that Metals cannot find JDK 11 on your computer. The correct JDK location should be auto-detected, but if there are e.g. multiple Java versions on your computer detection can fail. To address this problem, you can explicitly set the Java Home path in the Settings. First, make sure that you have JDK 11 installed, then find the path to the installation directory (varies by OS). Copy this path and paste it in the field for the setting Metals: Java Home. You can open the settings by clicking the small cogwheel on Metals in the extension tab and selecting Extension Settings, as in the following figure:

_images/metals-java-home.png

Finding the settings for Java Home. Note that setting this path is only necessary if updating VS Code does not help.

Error message: build server not started

  • 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 java processes

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

  • (Windows, if you have a user name containing ‘special’ characters [such as ä and ö])

    Sadly, paths are still not always handled properly, and some with non-ASCII characters in their usernames have reported problems under Windows. You can try to circumvent the problem by moving the project to a directory path not including your user-name. However, the more reliable fix seems to be to create a new user to specifically for course-work (using only ASCII characters); then, completely log out of your ‘real’ account (do not simply switch accounts) and use the new one while working on the assignments.

  • (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.)

sbt command not found (Windows)

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