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.
Install without Bloop
Automatic build import for sbt happens through Bloop, a compile server for Scala. Bloop implements the Build Server Protocol (BSP) that Metals uses to learn the directory structure of your project and its library dependencies. sbt does not implement BSP so Metals is not able to import sbt builds without Bloop.
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
// One of: // ~/.sbt/0.13/plugins/plugins.sbt // ~/.sbt/1.0/plugins/plugins.sbt resolvers += Resolver.sonatypeRepo("snapshots") addSbtPlugin("ch.epfl.scala" % "sbt-bloop" % "1.4.8-19-4d9f966b")
sbt -Dbloop.export-jar-classifiers=sources bloopInstall
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.
sbt 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.
Connect to sbt 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.
Switching back to Bloop
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.
Waiting for lock on .ivy2/.sbt.ivy.lock
Metals run sbt in a separate process and this error happens where there are two sbt processes resolving dependencies at the same time.
Not valid key: metalsEnable
This error might indicate that you have an old version of
in your project.
[error] Not a valid key: metalsEnable (similar: scalafixEnabled) [error] metalsEnable [error] ^
Try to remove any usage of
sbt-metals in your build.