Sublime Text

Metals works with Sublime Text (build 4000 or later) thanks to the sublimelsp/LSP and scalameta/metals-sublime plugins.

Requirements

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

macOS, Linux or Windows. Metals is developed on many operating systems and every PR is tested on Ubuntu, Windows and MacOS.

Scala 2.13, 2.12, 2.11 and Scala 3. Metals supports these Scala versions:

• Scala 2.11: 2.11.12

• Scala 2.12: 2.12.17, 2.12.18, 2.12.19, 2.12.20

• Scala 2.13: 2.13.12, 2.13.13, 2.13.14, 2.13.15

• Scala 3: 3.3.1, 3.3.3

Scala 3 versions from 3.3.4 are automatically supported by Metals.

Any older Scala versions will no longer get bugfixes, but should still work properly with newest Metals.

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 plugins

Install the following packages:

• sublimelsp/LSP: Language Server Protocol support for Sublime Text.
  Command Palette (Cmd + Shift + P) > Install package > LSP

• scalameta/metals-sublime: For automatic installation of metals and custom commands. Command Palette (Cmd + Shift + P) > Install package > LSP-metals

Finally restart sublime text.

Next, open "Preferences > Key Binding" and register F12 to trigger goto definition.

[
  // ...
  {
    "keys": ["f12"],
    "command": "lsp_symbol_definition"
  }
]

Importing a build

Open Sublime in the base directory of your Scala project and it will then prompt you to import the build as long as you're using one of the supported build tools. Click "Import build" to start the installation step.

This starts the Metal language server but no functionality will work yet because the build has not been imported.

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

Server logs

For more detailed information about what is happening behind the scenes during sbt bloopInstall run lsp toggle server panel in the command palette. You can optionally add key binding for this command.

Once the import step completes, compilation starts for your open *.scala files. Once the sources have compiled successfully, you can navigate the sources with "Goto definition" by pressing F12.

Find symbol references

The default key binding is shift+F12. If you use vim-bindings, you need to be in insert-mode.

Goto symbol in workspace

You can search for symbols in your dependency source using the command palette.

Manually trigger build import

You can optionally register a key binding for the command.

Tweaking Sublime Text for a better productivity

This paragraph contains a few tips & trick that can improve your daily productivity with Metals.

Optional LSP client tweaks

If you prefer to only enable Metals completions (without mixing them with the default ones from Sublime) set the following setting in the "Preferences > Preferences: LSP Settings":

{
  // ...
  "only_show_lsp_completions": true,
}

Also, if you prefer to show symbol references in Sublime's quick panel instead of the bottom panel set following setting in the "Preferences > Preferences: LSP Settings":

{
  // ...
  "show_references_in_quick_panel": true,
}

Additional key mappings

You can set a few optional key mappings for enable useful action shortcuts and perform some tweaks for the completion popup.

Keymapping for formatting document via scalafmt

Open "Preferences > Key Binding" and register ctrl+alt+l to trigger formatting document. definition.

[
  // ...
  {
    "keys": ["ctrl+alt+l"],
    "command": "lsp_format_document"
  }
]

Add key mapping for Goto symbol in workspace

This an optional step if you want to have a shortcut for looking up symbols in the workspace. Open "Preferences > Key Binding" and add:

[
  // ...
  { 
    "keys": ["ctrl+t"], 
    "command": "show_overlay",
    "args": {"overlay": "command_palette", "command": "lsp_workspace_symbols" }
  }
]

Enabling auto-import on completion

Metals can complete symbols from your workspace scope and automatically import them. By default, however, if you hit "Enter" to select a completion, the LSP client will complete the class without importing it, but you can easy remap to use also "Enter" key. Open "Preferences > Key Binding" and add:

[ 
  // ...
  { "keys": ["enter"], "command": "commit_completion", "context": [{ "key": "auto_complete_visible" } ] },
  { "keys": ["tab"], "command": "commit_completion", "context": [{ "key": "auto_complete_visible" } ] }
]

Using latest Metals SNAPSHOT

Update the "server_version" setting to try out the latest pending Metals features by accessing Preferences > Package Settings > LSP > Servers > LSP-metals

Version	Published
1.4.2	16 Dec 2024 14:05
1.4.2+29-82907609-SNAPSHOT	20 Dec 2024 15:31

Files and Directories to include in your Gitignore

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. The Bloop plugin that generates Bloop configuration is added in the metals.sbt file, which is added at project/metals.sbt as well as further project directories depending on how deep *.sbt files need to be supported. To support each *.sbt file Metals needs to create an additional file at ./project/project/metals.sbt relative to the sbt file. Working with Ammonite scripts will place compiled scripts into the .ammonite directory. It's recommended to exclude these directories and files from version control systems like git.

# ~/.gitignore
.metals/
.bloop/
.ammonite/
metals.sbt

Worksheets

Worksheets are a great way to explore an api, try out an idea, or code up an example and quickly see the evaluated expression or result. Behind the scenes worksheets are powered by the great work done in mdoc.

Getting started with Worksheets

To get started with a worksheet you can either use the metals.new-scala-file command and select Worksheet or create a file called *.worksheet.sc. This format is important since this is what tells Metals that it's meant to be treated as a worksheet and not just a Scala script. Where you create the script also matters. If you'd like to use classes and values from your project, you need to make sure the worksheet is created inside of your sources next to any existing Scala files. directory. You can still create a worksheet in other places, but you will only have access to the standard library and your dependencies.

Evaluations

After saving you'll see the result of the expression as a inlay hint at the end of the line. You may not see the full result for example if it's too long, so you are also able to hover on the inlay hint to expand it.

Keep in mind that you don't need to wrap your code in an object. In worksheets everything can be evaluated at the top level.

Using dependencies in worksheets

You are able to include an external dependency in your worksheet by including it in one of the following two ways.

// $$dep.`organisation`::artifact:version` style
import $$dep.`com.lihaoyi::scalatags:0.7.0`

// $$ivy.`organisation::artifact:version` style
import $$ivy.`com.lihaoyi::scalatags:0.7.0`

:: is the same as %% in sbt, which will append the current Scala binary version to the artifact name.

You can also import scalac options in a special $$scalac import like below:

import $$scalac.`-Ywarn-unused`

Troubleshooting

Since worksheets are not standard Scala files, you may run into issues with some constructs. For example, you may see an error like this:

value classes may not be a member of another class - mdoc

This means that one of the classes defined in the worksheet extends AnyVal, which is not currently supported. You can work around this by moving the class to a separate file or removing the AnyVal parent.

Running scalafix rules

Scalafix allows users to specify some refactoring and linting rules that can be applied to your codebase. Please checkout the scalafix website for more information.

Since Metals v0.11.7 it's now possible to run scalafix rules using a special command metals.scalafix-run. This should run all the rules defined in your .scalafix.conf file. All built-in rules and the community hygiene ones can be run without any additional settings. However, for all the other rules users need to add an additional dependency in the metals.scalafixRulesDependencies user setting. Those rules need to be in form of strings such as com.github.liancheng::organize-imports:0.6.0, which follows the same convention as coursier dependencies.

A sample scalafix configuration can be seen below:

rules = [
  OrganizeImports,
  ExplicitResultTypes,
  RemoveUnused
]

RemoveUnused.imports = false

OrganizeImports.groupedImports = Explode
OrganizeImports.expandRelative = true
OrganizeImports.removeUnused = true
OrganizeImports.groups = [
  "re:javax?\."
  "scala."
  "scala.meta."
  "*"
]