You will need the following applications installed:
- Java 11 or 8 - Make sure
JAVA_HOMEpoints to a Java 11 or 8 installation. Metals will need to build and run on both.
sbt(for building a local version of the server)
metalsthe main project with sources of the Metals language server.
mtagssource file indexer for Java and Scala, it's a dependency of the
metalsproject but kept in a separate module so it can be used by other projects like Metabrowse.
mtags-interfaces- java interfaces for the presentation compiler.
tests/cross- tests targeting cross builds for common features such as hover, completions, signatures etc.
tests/inputexample Scala code that is used as testing data for unit tests.
tests/unitmoderately fast-running unit tests.
tests/slowslow integration tests.
test-workspacedemo project for manually testing Metals through an editor.
docsdocumentation markdown for the Metals website.
metals-docsmethods used for generating documentation across multiple pages in
websiteholds the static site configuraton, style and blogs posts for the Metals website.
This git repository has a pre-push hook to run Scalafmt.
The CI also uses Scalafix to assert that there a no unused imports. To
automatically remove unused imports run
sbt scalafixAll. We don't run
Scalafix as a pre-push git hook since starting sbt takes a long time.
The improvement you are looking to contribute may belong in a separate repository:
- scalameta/metals-vscode: the Visual Studio Code extension for Metals.
- scalameta/scalameta: SemanticDB, parsing, tokenization.
- scalacenter/bloop: build server for compilation.
- scala/scala: presentation compiler.
- scalameta/scalafmt: code formatting.
- scalacenter/scalafix: code refactoring and linting.
To run the unit tests open an sbt shell and run
sbt # (recommended) run a specific test suite, great for edit/test/debug workflows. > metals/testOnly -- tests.DefinitionSuite # run unit tests, moderately fast but still a bit too slow for edit/test/debug workflows. > unit/test # run slow integration tests, takes several minutes. > slow/test # (not recommended) run all tests, slow. It's better to target individual projects. > test
Manually testing a
Every test suite that extends
LspSuite generates a workspace directory under
tests/unit/target/e2e/$suitename/$testname. To debug why a
be failing, run the test once and then open it directly in your editor. For
example, for the test case
WarningsLspSuite run the
If you are using VS Code, make sure to update the "Server Version" setting to use your locally published version of Metals.
Some functionality is best to manually test through an editor. A common workflow
while iterating on a new feature is to run
publishLocal and then open an
editor in a small demo build.
Visual Studio Code
Install the Metals extension from the Marketplace by searching for "Metals".
Next, update the "Server version" setting under preferences to point to the
version you published locally via
When you make changes in the Metals Scala codebase
- execute the "Metals: Restart server" command in Visual Studio Code (via command palette)
First, follow the
vim installation instruction.
Next, write a
new-metals-vim script that builds a new
script using the locally published version.
coursier bootstrap \ --java-opt -Dmetals.client=coc.nvim \ org.scalameta:metals_2.12:0.8.4-SNAPSHOT \ # double-check version here -r bintray:scalacenter/releases \ -o /usr/local/bin/metals-vim -f
Finally, start vim with the local Metals version
cd test-workspace # any directory you want to manually test Metals new-metals-vim && vim build.sbt # remember to have the script in your $PATH
When you make changes in the Metals Scala codebase, run
sbt publishLocal, quit
vim and re-run
new-metals-vim && vim build.sbt.
Metals logs workspace-specific information to the
tail -f .metals/metals.log
These logs contain information that may be relevant for regular users.
To see trace of incoming/outgoing JSON communication with the text editor or build server, create empty files in your machine cache directory.
# macOS touch -f ~/Library/Caches/org.scalameta.metals/lsp.trace.json # text editor touch -f ~/Library/Caches/org.scalameta.metals/bsp.trace.json # build server # Linux touch ~/.cache/metals/lsp.trace.json # text editor touch ~/.cache/metals/bsp.trace.json # build server
Next when you start Metals, watch the logs with
# macOS tail -f ~/Library/Caches/org.scalameta.metals/lsp.trace.json # Linux tail -f ~/.cache/metals/lsp.trace.json
The traces are very verbose so it's recommended to delete the files if you are not interested in debugging the JSON communication.
To debug the JVM with the Metals server, add a property to your
Server Properties with the usual Java debugging flags, making sure you have the
quiet option on.
It's important to remember about the flag, as the server uses standard input/output to communicate with the client, and the default output of the debuggee interferes with that.
This property will make your server run in debug mode on port 5005 without waiting for the debugger to connect: