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.

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

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.

Manually trigger build import

Run doctor

Known issues

lsp-mode blocks the UI during the initialize handshake so you may notice
that opening *.scala file gets slower. Metals does as much as possible to
move computation out of initialize but lsp-mode should ideally not freeze
the UI during any LSP request/response cycle.

lsp-mode does not publish diagnostics for unopened buffers so you only see
compile errors for the open file.

lsp-mode does not send a shutdown request and exit notification when
closing Emacs meaning Metals can't properly clean up resources.

lsp-mode does not respect the Metals server capabilities that are declared
during the initialize handshake. The following warnings can be ignored in the
logs:

textDocument/hover is not supported

textDocument/documentSymbol is not supported

lsp-mode executes workspace/executeCommand commands within a specific
timeout so long-running commands like "Import build" cause the following error
to be reported in the logs:
lsp--send-wait: Timed out while waiting for a response from the language server.
Feel free to ignore this error.

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.