Edit

Atom

Metals works with Atom thanks to the ide-scala package.

Atom demo

Requirements

Java 8 or 11 provided by OpenJDK or Oracle. Eclipse OpenJ9 is not supported, please make sure the JAVA_HOME environment variable points to a valid Java 8 or 11 installation.

macOS, Linux or Windows. Metals is developed on macOS and every PR is tested on Ubuntu+Windows.

Scala 2.13, 2.12 and 2.11. Metals supports these Scala versions 2.13.0, 2.13.1, 2.12.8, 2.12.9, 2.12.10, 2.12.7 and 2.11.12. Note that 2.11.x support is deprecated and it will be removed in future releases. It's recommended to upgrade to Scala 2.12 or Scala 2.13

Installing the package

Install the package by searching for "ide-scala" or run the following command.

apm install ide-scala

Install Metals package

Importing a build

The first time you open Metals in a new workspace it prompts you to import the build. Click "Import build" to start the installation step.

Import build

  • "Not now" disables this prompt for 2 minutes.
  • "Don't show again" disables this prompt forever, use rm -rf .metals/ to re-enable the prompt.
  • Use tail -f .metals/metals.log to watch the build import progress.
  • Behind the scenes, Metals uses Bloop to import sbt builds, but you don't need Bloop installed on your machine to run this step.

Once the import step completes, compilation starts for your open *.scala files.

Once the sources have compiled successfully, you can navigate the codebase with goto definition.

Custom sbt launcher

By default, Metals runs an embedded sbt-launch.jar launcher that respects .sbtopts and .jvmopts. However, the environment variables SBT_OPTS and JAVA_OPTS are not respected.

Update the server property -Dmetals.sbt-script=/path/to/sbt to use a custom sbt script instead of the default Metals launcher if you need further customizations like reading environment variables.

Speeding up import

The "Import build" step can take a long time, especially the first time you run it in a new build. The exact time depends on the complexity of the build and if library dependencies need to be downloaded. For example, this step can take everything from 10 seconds in small cached builds up to 10-15 minutes in large uncached builds.

Consult the Bloop documentation to learn how to speed up build import.

Importing changes

When you change build.sbt or sources under project/, you will be prompted to re-import the build.

Import sbt changes

Manually trigger build import

To manually trigger a build import, execute the "Import build" command through the command palette (Cmd + Shift + P).

Import build command

Run doctor

Execute the "Run Doctor" through the command palette to troubleshoot potential configuration problems in your workspace.

Run doctor command

Using latest Metals SNAPSHOT

Update the "Metals version" setting to try out the latest pending Metals features.

Version Published
0.7.7-SNAPSHOT 10 Oct 2019 22:08
0.7.7-SNAPSHOT 10 Oct 2019 22:08

Run the "Reload Window" command after updating the setting for the new version to take effect.

Gitignore .metals/ and .bloop/

The Metals server places logs and other files in the .metals/ directory. The Bloop compile server places logs and compilation artifacts in the .bloop directory. It's recommended to ignore these directories from version control systems like git.

# ~/.gitignore
.metals/
.bloop/
← Visual Studio CodeVim →