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.)
On Aalto Linux computers
VS Code is accessible as a software module on the Aalto workstations found in the computer labs (or on a virtual desktop using Aalto VDI),
To start Code on an Aalto Linux workstation do the following:
Open a terminal
(On VDI remote desktops only) Authenticate to make vscode (and other) software module available:
kinit
Load the vscode module by the command:
module load vscode/a1120
Start VS Code by the command:
code
Do not forget the /a1120
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. If you simply load vscode
then you will have the vanilla version. (If you happen to load the default version, you can unload it with the command module unload vscode
).
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.
Warning
When working on Aalto Linux computers 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 messages and errors are not handled correctly. Instead, your projects under a sub-directory you have created in your home directory.
Installation on personal computer
If you would like to use your own computer to work on the exercises you need to install VS Code, Java, and sbt:
First things first
Install JDK 11
Windows: download and run Java 11 installer at adoptium.net
MacOS: use package manager sdkman or download and run installer from adoptium.net
If you use the installer from adoptium, make sure to pick the aarch64 architecture if you have the newer M1/M2 chipset.
If you use sdkman:
Follow instructions to install sdkman,
Run
sdk install java 11.0.18-tem
. (sdk can also be used to install sbt, see below.)
Ubuntu Linux: install package openjdk-11-jdk
Other Linux distributions: consult your package manager
Install sbt
(Note: sbt is needed if you like to open a Scala console, Code + Metals will usually work without it)
MacOS: instructions Note: several options are given for Mac OS in the link above, the most straight forward is probably to install a package manager, such as sdkman, first if you are OK with that. Then you can do the following:
Follow instructions to install sdkman, (unless you already have it)
run
sdk install sbt
in your terminal to install sbt.
Windows 11: download and run the msi installer
Linux: instructions
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 & 11
Download the installer from https://code.visualstudio.com/ and run it.
Setup
Run the VS Code application, select the extensions tab on the left-hand side, or in the menu View → Extensions
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.
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
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.
Navigate to the menu bar, proceed with File → Open Folder…, and select the extracted sbt assignment folder
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.
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.
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.)
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
???
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: View → Problems
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.)
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
).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.
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.
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.
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.
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
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.
If the problem persists:
Make sure JDK 11 was properly installed
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. Fix: Start using the pre-release of Metals (2023-02-28), you can do this by clicking on the ‘cogwheel’ of the Metals extension and select Switch to Pre-Release Version. This will give you the developer version which seems to fix the bug. Alternatively switch to using IntelliJ instead.
Can happen if the wrong, or multiple versions of Java is installed
Make sure JDK 11 was properly installed
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 runcode
, 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 thevscode/a1120
module every time you log in to the VDI workstationIf 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 runkinit
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.