Vim
While Metals works with most LSP clients for Vim and Neovim, we recommend using the dedicated Neovim plugin to get the best Metals support. Metals has many specific commands and LSP extensions that won't be available when not using the extension.
Requirements
Java 8, 11, 17 provided by OpenJDK or Oracle. Eclipse OpenJ9 is not
supported, please make sure the JAVA_HOME
environment variable
points to a valid Java 8, 11 or 17 installation.
macOS, Linux or Windows. Metals is developed on many operating systems and every PR is tested on Ubuntu, Windows and MacOS.
Scala 2.13, 2.12, 2.11 and Scala 3. Metals supports these Scala versions:
Scala 2.13: 2.13.8, 2.13.7, 2.13.6, 2.13.5, 2.13.4, 2.13.3, 2.13.2, 2.13.1
Scala 2.12: 2.12.15, 2.12.14, 2.12.13, 2.12.12, 2.12.11, 2.12.10, 2.12.9, 2.12.8
Scala 2.11: 2.11.12
Scala 3: 3.1.3-RC3, 3.1.3-RC2, 3.1.2, 3.1.1, 3.1.0, 3.0.2, 3.0.1, 3.0.0
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
nvim-metals
nvim-metals
Is the the dedicated
Metals extension for the built-in LSP
support in Neovim.
To get started with installation please see the nvim-metals
prerequisites and
installation steps.
Version | Published |
---|---|
0.11.5 | 28 Apr 2022 17:01 |
0.11.5+76-0087d07f-SNAPSHOT | 16 May 2022 09:36 |
Keep in mind that by default Neovim doesn't have default mappings for the functionality you'll want like, hovers, goto definition, method signatures, etc. You can find a full example configuration of these in the example configuration.
For a guide on all the available features in nvim-metals
, refer to the
features list.
Vim alternatives
There are multiple Vim alternatives if you're not a Neovim user. Metals did have
a Metals-specific plugin that worked with Vim,
coc-metals
, but it doesn't work
with the newest versions of Metals and is currently deprecated and
unmaintained.
Using an alternative LSP Client
There are multiple other LSP clients that work with Vim. Here are a few:
natebosch/vim-lsc
: simple installation and written in Vimscript.vim-lsp
: simple installation and written in Vimscript.yegappan/lsp
: Very new and targeting Vim9.
Keep in mind that they have varying levels of LSP support, don't support Metals specific commands (like build import), or Metals specific LSP extensions (like tree view), and you need to manage the Metals installation yourself.
There are two ways to install Metals yourself in order to work with an alternative client.
- Most easily is to just use Coursier to do a
cs install metals
. - Generating a Metals binary yourself.
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.
# ~/.gitignore
.metals/
.bloop/
.ammonite/
metals.sbt
Next, build a metals-vim
binary for the latest Metals release using the
Coursier command-line interface.
Version | Published | Resolver |
---|---|---|
0.11.5 | 28 Apr 2022 17:01 | -r sonatype:releases |
0.11.5+76-0087d07f-SNAPSHOT | 16 May 2022 09:36 | -r sonatype:snapshots |
# Make sure to use coursier v1.1.0-M9 or newer.
curl -L -o coursier https://git.io/coursier-cli
chmod +x coursier
./coursier bootstrap \
--java-opt -Xss4m \
--java-opt -Xms100m \
--java-opt -Dmetals.client=vim-lsc \
org.scalameta:metals_2.12:0.11.5 \
-r bintray:scalacenter/releases \
-r sonatype:snapshots \
-o /usr/local/bin/metals-vim -f
Make sure the generated metals-vim
binary is available on your $PATH
.
You can check version of your binary by executing metals-vim -version
.
Configure the system properties -Dhttps.proxyHost=… -Dhttps.proxyPort=…
if you are behind an HTTP proxy.
The -Dmetals.client=vim-lsc
flag is there just as a helper to match your
potential client. So make sure it matches your client name. This line isn't
mandatory though as your client should be able to fully be configured via
InitializationOptions
. You can read more about his
here.
Getting help
There is an active community using Vim and Metals. Apart from creating an
issue or starting
a discussion for
nvim-metals
users, you can also ask questions in our #vim-users
Discord
Channel or Matrix
Bridge.