sbt is most commonly used build tool in the Scala community and works with Metals out-of-the-box.
The first time you open Metals in a new sbt workspace you will be prompted to import the build. Select "Import Build" to start the automatic installation. This will create all the needed Bloop config files. You should then be able to edit and compile your code utilizing all of the features.
The Automatic build import process for sbt happens through Bloop, a build server for Scala. Bloop implements the Build Server Protocol (BSP) that Metals uses to learn the directory structure of your project, its library dependencies, and to build or run your code.
It's recommended to use automatic installation over manual installation since manual installation requires several independent steps that make it harder to stay up-to-date with the latest Metals version.
Instead of using automatic build import, you can manually install sbt-bloop and generate the Bloop JSON files directly from your sbt shell. This approach may speed up build import by avoiding Metals from starting sbt in a separate process.
First, install the Bloop plugin globally or inside your
to generate the Bloop JSON configuration files. You can also set the
bloopExportJarClassifiers setting inside your main build.sbt file, but using
the above command will do it automatically for you in the current sbt session.
bloopInstall is finished, execute the "Connect to build server"
build.connect) command to tell Metals to establish a connection
with the Bloop build server.
As of sbt 1.4.1, Metals has integrated support for the sbt BSP server. If you'd like to use the sbt server as an alternative to Bloop (which is the default), then at any time while in an sbt workspace you can choose to switch in multiple ways.
Note: that if you are unfamiliar with the features that the different build servers may offer, then simply stick with the default (Bloop), which has great integrated stable support in Metals.
.bsp/sbt.json file if one doesn't exist#
More than likely if you're using sbt >= 1.4.1, you'll have already see this file
exist. However, if you're in a fresh workspace or it doesn't exist for some
reason, you can execute a
metals.generate-bsp-config command via the command
palette, which will automatically detect that you're in a sbt workspace and
generate the necessary file. After the file generation, Metals will then
automatically connect to sbt. From this point on, you'll be using sbt instead of
Bloop as your build server.
If your workspace already has a
.bsp/sbt.json file, then you can switch from
using Bloop to sbt as a build server by executing a
from the command palette. This command will recognize the
and then connect to the sbt build server. After the connection is made, you'll
be using sbt instead of Bloop as your build server.
If you'd like to switch back to using Bloop as your build server, there are multiple ways for you to do this.
- Using the same
metals.bsp-switchcommand as up above, and select "bloop".
- Use the
metals.reset-choicefunctionality and choose to reset the "Build Server Selection". Then follow this with the
metals.build-restartcommand which will disconnect you from the sbt build server, and then connect you back to the default Bloop server.
Before reporting an issue, check if your problem is solved with one of the following tips.
Metals run sbt in a separate process and this error happens where there are two sbt processes resolving dependencies at the same time.
This error might indicate that you have an old version of
in your project.
Try to remove any usage of
sbt-metals in your build.