Sublime Text · Metals

Metals has experimental support for Sublime Text 3 thanks to tomv564/LSP.

Sublime Text 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 plugin

First, install the LSP plugin: Command Palette (Cmd + Shift + P) > Install package > LSP

Next, build a metals-sublime binary for the latest Metals release using the Coursier command-line interface.

Version	Published	Resolver
0.7.7-SNAPSHOT	10 Oct 2019 22:08	`-r sonatype:releases`
0.7.7-SNAPSHOT	10 Oct 2019 22:08	`-r sonatype:snapshots`

# Make sure to use coursier v1.1.0-M9 or newer.
curl -L -o coursier https://git.io/coursier
chmod +x coursier
./coursier bootstrap \
  --java-opt -Xss4m \
  --java-opt -Xms100m \
  --java-opt -Dmetals.client=sublime \
  org.scalameta:metals_2.12:0.7.7-SNAPSHOT \
  -r bintray:scalacenter/releases \
  -r sonatype:snapshots \
  -o /usr/local/bin/metals-sublime -f

Make sure the generated metals-sublime binary is available on your $PATH.

Configure the system properties -Dhttps.proxyHost=… -Dhttps.proxyPort=… if you are behind an HTTP proxy.

The -Dmetals.client=sublime flag configures Metals for usage with the Sublime Text LSP client.

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 an sbt build. Run the "Enable Language Server in project" command.

Enable Language Server for this project

This starts the Metal language server but no functionality will work because the build has not been imported. The first time you enable Language Server in a project you must open a *.scala file, then it will prompt you to "Import changes". This step is required for compile errors and goto definition to work and while it is running, no Metals functionality will work.

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 library dependencies are cached or 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.

For more detailed information about what is happening behind the scenes during sbt bloopInstall:

tail -f .metals/metals.log

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-binding, you need to be in insert-mode.

Find references

Goto symbol in workspace

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

workspace symbols

Manually trigger build import

You can configure a custom command "Metals: Import Build" to manually trigger build import when changing build.sbt. To learn about Sublime Text commands see here.

Update the contents of your *.sublime-commands file to include the following command.

[
  // ...
  {
    "caption": "Metals: Import Build",
    "command": "lsp_execute",
    "args": { "command_name": "build-import" }
  }
]

If you don't have a existing .sublime-commands file, you can create a new one in this location.

# macOS
~/Library/Application\ Support/Sublime\ Text\ 3/Packages/Metals.sublime-commands
# Ubuntu
~/.config/sublime-text-3/Packages/Metals.sublime-commands

Once configured, the command can be called from the command palette.

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.

LSP client tweaks

Default settings of the LSP client are insufficient to enable the full power of Metals. The first step is a fixing problem with insufficient information in the code completion popup. To fix it, open "Preferences > Preferences: LSP Settings" and add the following setting:

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

Better code completion

The next two steps are optional. If you prefer to only enable Metals completions (without mixing them with the default ones from Sublime) set 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

Known issues

The Sublime Text client uses an alert window for window/showMessage that prevents you from editing code so Metals uses window/logMessage instead.

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/