Skip to main content

Sublime Text

Metals works with Sublime Text 3 thanks to the sublimelsp/LSP and scalameta/metals-sublime plugins.

Sublime Text demo

Requirements#

Java 8, 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 8, 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.13: 2.13.7, 2.13.6, 2.13.5, 2.13.4, 2.13.3, 2.13.2, 2.13.1, 2.13.0

  • Scala 2.12: 2.12.15, 2.12.14, 2.12.13, 2.12.12, 2.12.11, 2.12.10, 2.12.9, 2.12.8

  • Scala 2.11: 2.11.12

  • Scala 3: 3.1.1-RC1, 3.1.0, 3.0.2, 3.0.1, 3.0.0

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#

Build Import

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.

Server logs

Once the import step completes, compilation starts for your open *.scala files. Once the sources have compiled successfully, you can navigate the 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.

Find references

Goto symbol in workspace#

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

workspace symbols

Manually trigger build import#

Import build command

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,
}

Symbol references in the popup

Additional key mappings#

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

Keymaping for formatting document via scalafmt#

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

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

Add key mapping for formatting document via scalafmt

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" } ] }
]

Import after Enter key was hit

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

VersionPublished
0.10.903 Nov 2021 14:02
0.10.9+110-2e489b6c-SNAPSHOT01 Dec 2021 11:33

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 src 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 comment as 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 comment to expand.

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`