Build Tools

Contributing

Text Editors

Metals works with the following text editors with varying degree of
functionality.

Editor

Installation

Build import

Diagnostics

Goto definition

Find references

Document symbols

Workspace symbols

Formatting

Metals Extensions

Visual Studio Code

Single click

✅

✅

✅

✅

✅

✅

✅

✅

Atom

Single click

✅

✅

✅

✅

✅

✅

Status bar

Vim

Few steps

✅

Escaped newlines

✅

✅

Flat

✅

Status bar

Sublime Text 3

Few steps

✅

✅

✅

✅

Flat

✅

✅

Emacs

Few steps

✅

Single buffer

✅

✅

✅

✅

✅

Status bar

Metals is a new project with limited features. If you are learning Scala or
are looking for a rich IDE experience it is recommended to use IntelliJ
instead.

Installation

Single click: Metals is easy to install and requires minimal configuration
out-of-the-box.

Few steps: installing Metals requires a few custom steps and minimal
configuration to work.

Compile from source: installing Metals requires building an editor plugin
from source.

Build import

✅: it is possible to import a build such as an sbt project directly from
the editor.

Requires browser: importing a build requires additional steps in a web
browser using a localhost server. It is not possible to import a build within
the editor.

Diagnostics

✅: Diagnostics are correctly published on compile.

Escaped newlines: Multi-line diagnostic are slightly difficult to read since
newlines are escaped into ^@ characters.

Single buffer: Diagnostics are only published for the current buffer so
compile errors are lost for unopened files.

Compile errors are reported as red squiggles in the editor. Compilation is
triggered on file save for the build target (project/module) containing the
focused text file.

Known limitations

Slow feedback. Compilation is handled by the build tool, meaning diagnostics
may take a while to publish for large projects. The batch compilation mode
used by build tools is slower than the interactive compiler used by IntelliJ
as you type.

Find references

Find symbol references in project sources. References include implicits,
inferred .apply, desugared .flatMap from for comprehensions and other
symbols that may not be explicitly written in source, making it possible to
discover usages of difficult-to-grep symbols. The Metals navigation index is
low-overhead and should only require a few megabytes of memory even for large
projects.

Known limitations

References to overridden methods are not included in the results. For example,
if you run "find references" on the method Dog.name() then it won't include
references to the super method Animal.name().

Document symbols

✅: Document symbols are displayed in a hierarchical outline.

Flat: Document symbols are displayed in a flat outline.

Workspace symbols

Fuzzy search a symbol in the workspace of library dependencies by its name.

All-lowercase queries are treated as case-insensitive searches.

Queries ending with a dot . list nested symbols.

Formatting

Metals uses Scalafmt to respond to formatting requests from the editor,
according to the configuration defined in .scalafmt.conf.

The Metals language server supports custom extensions that are not part of the
Language Server Protocol (LSP). These extensions are not necessary for Metals to
function but they improve the user experience. To learn more about Metals
extensions, see integrating a new editor.