You will need the following applications installed:
- Java 8, make sure
JAVA_HOMEpoints to a Java 8 installation and not Java 11.
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.
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.
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 # Run once in the beginning and run again for every change in the sbt plugin. > sbt-metals/publishLocal # (recommended) run specific test suite, great for edit/test/debug workflows. > metals/testOnly -- tests.DefinitionSuite # run unit tests, modestly 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
SlowSuite 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
WarningsSlowSuite 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, search 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=vim-lsc \ org.scalameta:metals_2.12:0.7.5-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
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 is recommended to delete the files if you are not interested in debugging the JSON communication.