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

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, 2.11 and Scala 3. Metals supports these Scala versions 2.13.3, 2.12.12, 2.12.11, 2.12.10, 2.13.1, 2.13.2, 2.11.12, 2.12.8, 2.12.9, 2.13.0, 0.26.0, 0.27.0-RC1, 0.25.0 and 0.26.0-RC1. 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

Installation

To use Metals in Emacs, place this snippet in your Emacs configuration (for example .emacs.d/init.el) to load lsp-mode along with its dependencies:

( require 'package) ( add-to-list 'package-archives '( "melpa" . "https://melpa.org/packages/" ) t ) ( package-initialize ) ( unless ( package-installed-p 'use-package) ( package-refresh-contents ) ( package-install 'use-package)) ( require 'use-package) ( setq use-package-always-defer t use-package-always-ensure t backup-directory-alist `(( ".*" . ,temporary-file-directory)) auto-save-file-name-transforms `(( ".*" ,temporary-file-directory t ))) ( use-package scala-mode :interpreter ( "scala" . scala-mode)) ( use-package sbt-mode :commands sbt-start sbt-command :config ( substitute-key-definition 'minibuffer-complete-word 'self-insert-command minibuffer-local-completion-map) ( setq sbt :program-options '( "-Dsbt.supershell=false" )) ) ( use-package flycheck :init ( global-flycheck-mode )) ( use-package lsp-mode :hook ( scala-mode . lsp) ( lsp-mode . lsp-lens-mode) :config ( setq lsp-prefer-flymake nil )) ( use-package lsp-metals :config ( setq lsp-metals-treeview-show-when-views-received t )) ( use-package lsp-ui) ( use-package yasnippet) ( use-package company-lsp) ( use-package posframe ) ( use-package dap-mode :hook ( lsp-mode . dap-mode) ( lsp-mode . dap-ui-mode) )

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.9.4 21 Sep 2020 15:38 -r sonatype:releases 0.9.4+5-9e2a418b-SNAPSHOT 24 Sep 2020 18:58 -r sonatype:snapshots

curl -L -o coursier https://git.io/coursier-cli chmod +x coursier ./coursier bootstrap \ --java-opt -Xss4m \ --java-opt -Xms100m \ --java-opt -Dmetals.client=emacs \ org.scalameta:metals_2.12:0.9.4 \ -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 .

You can check version of your binary by executing metals-emacs -version .

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. Type "Import build" or press Tab and select "Import build" to start the installation step.

"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.

to re-enable the prompt. Use tail -f .metals/metals.log to watch the build import progress.

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.

Manually trigger build import

To manually trigger a build import, run M-x lsp-metals-build-import .

Run doctor

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

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:

( require 'package) ( add-to-list 'package-archives '( "melpa-stable" . "https://stable.melpa.org/packages/" ) t ) ( package-initialize ) ( unless ( package-installed-p 'use-package) ( package-refresh-contents ) ( package-install 'use-package)) ( require 'use-package) ( setq use-package-always-defer t use-package-always-ensure t ) ( use-package scala-mode :interpreter ( "scala" . scala-mode)) ( use-package sbt-mode :commands sbt-start sbt-command :config ( substitute-key-definition 'minibuffer-complete-word 'self-insert-command minibuffer-local-completion-map) ( setq sbt :program-options '( "-Dsbt.supershell=false" )) ) ( use-package eglot :pin melpa-stable :config ( add-to-list 'eglot-server-programs '(scala-mode . ( "metals-emacs" ))) :hook ( scala-mode . eglot-ensure))

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.

.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.

import $dep.`com.lihaoyi::scalatags: 0.7 .0 ` 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.