Emacs · Metals

Metals works in Emacs thanks to the the lsp-scala package.

Emacs demo

Requirements

OpenJDK or Oracle Java 8. Eclipse OpenJ9 and Java 11 are not supported, please make sure the JAVA_HOME environment variable points to valid Java 8 installation.

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

Scala 2.12 and 2.11. Metals works only with Scala versions 2.12.8, 2.12.7, 2.11.12, 2.12.6, 2.12.5, 2.12.4, 2.11.11, 2.11.10 and 2.11.9. Note that 2.10.x and 2.13.x are not supported.

Installation

To use Metals in Emacs, place this snippet in your Emacs configuration to load lsp-scala along with its dependencies:

;; Add melpa to your packages repositories
(add-to-list 'package-archives '("melpa" . "https://melpa.org/packages/") t)

;; Enable defer and ensure by default for use-package
(setq use-package-always-defer t
      use-package-always-ensure t)

;; Enable scala-mode and sbt-mode
(use-package scala-mode
  :mode "\\.s\\(cala\\|bt\\)$")

(use-package sbt-mode
  :commands sbt-start sbt-command
  :config
  ;; WORKAROUND: https://github.com/ensime/emacs-sbt-mode/issues/31
  ;; allows using SPACE when in the minibuffer
  (substitute-key-definition
   'minibuffer-complete-word
   'self-insert-command
   minibuffer-local-completion-map))

;; Enable nice rendering of diagnostics like compile errors.
(use-package flycheck
  :init (global-flycheck-mode))

(use-package lsp-mode
 :init (setq lsp-prefer-flymake nil))

(use-package lsp-ui)

;; Add company-lsp backend for metals
(use-package company-lsp)

(use-package lsp-scala
  :after scala-mode
  :demand t
  ;; Optional - enable lsp-scala automatically in scala files
  :hook (scala-mode . lsp))

You may need to disable other packages like ensime or sbt server to prevent conflicts with Metals.

If you start Emacs now then it will fail since the metals-emacs binary does not exist yet.

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

Version	Published	Resolver
0.5.2	06 May 2019 10:14	`-r sonatype:releases`
0.5.2+13-1c09f3e3-SNAPSHOT	21 May 2019 09:56	`-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=emacs \
  org.scalameta:metals_2.12:0.5.2 \
  -r bintray:scalacenter/releases \
  -r sonatype:snapshots \
  -o /usr/local/bin/metals-emacs -f

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

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

The -Dmetals.client=emacs flag is important since it configures Metals for usage with Emacs.

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, run M-x lsp-scala-build-import.

Import build command

Run doctor

Run M-x lsp-scala-doctor-run to troubleshoot potential configuration problems in your build.

Run doctor command

eglot

There is an alternative LSP client called eglot that might be worth trying out if you want to use an alternative to lsp-mode.

To configure Eglot with Metals:

;; Add melpa-stable to your packages repositories
(add-to-list 'package-archives '("melpa-stable" . "https://stable.melpa.org/packages/") t)

;; Enable defer and ensure by default for use-package
(setq use-package-always-defer t
      use-package-always-ensure t)

;; Enable scala-mode and sbt-mode
(use-package scala-mode
  :mode "\\.s\\(cala\\|bt\\)$")

(use-package sbt-mode
  :commands sbt-start sbt-command
  :config
  ;; WORKAROUND: https://github.com/ensime/emacs-sbt-mode/issues/31
  ;; allows using SPACE when in the minibuffer
  (substitute-key-definition
   'minibuffer-complete-word
   'self-insert-command
   minibuffer-local-completion-map))

(use-package eglot
  :pin melpa-stable
  :config
  (add-to-list 'eglot-server-programs '(scala-mode . ("metals-emacs")))
  ;; (optional) Automatically start metals for Scala files.
  :hook (scala-mode . eglot-ensure))

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/