Vim · Metals

Vim demo

Metals works with most LSP clients for Vim, but we recommend using the coc-metals extension for coc.nvim which will provide the most complete implementation of LSP and Metals-specific helpers.

Requirements

Java 8 or 11 provided by OpenJDK or Oracle. Eclipse OpenJ9 is not supported, please make sure the JAVA_HOME environment variable points to a valid Java 8 or 11 installation.

macOS, Linux or Windows. Metals is developed on macOS and every PR is tested on Ubuntu+Windows.

Scala 2.13, 2.12 and 2.11. Metals supports these Scala versions 2.13.1, 2.12.11, 2.12.10, 2.11.12, 2.12.8, 2.12.9 and 2.13.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

Installing Vim

The coc.nvim plugin requires either Vim >= 8.1 or Neovim >= 0.3.1. Make sure you have the correct version installed. While it works with both Vim and Neovim, we recommend using Neovim since it provides a smoother experience with some of the features such as code actions and general performance.

# If using Vim
vim --version | head
VIM - Vi IMproved 8.2

# If using Neovim
nvim --version | head
NVIM v0.4.3

Installing yarn

coc.nvim requires Node.js in order to work. It also uses Yarn to manage extensions but you could opt-out of it and use vim-plug instead.

For convenience we recommend installing both via your favorite package manager or manually:

curl -sL install-node.now.sh/lts | sh
curl --compressed -o- -L https://yarnpkg.com/install.sh | bash

Installing coc.nvim

Once the requirements are satisfied, we can now proceed to install the following plugins:

neoclide/coc.nvim: Language Server Protocol client to communicate with the Metals language server.
derekwyatt/vim-scala: for syntax highlighting Scala and sbt source files.

Assuming vim-plug is used (another plugin manager like vundle works too), update your ~/.vimrc to include the following settings.

" ~/.vimrc

" Configuration for vim-plug
Plug 'derekwyatt/vim-scala'
Plug 'neoclide/coc.nvim', {'branch': 'release'}

" Configuration for vim-scala
au BufRead,BufNewFile *.sbt set filetype=scala

Run :PlugInstall to install the plugin. If you already have coc.nvim installed, be sure to update to the latest version with :PlugUpdate.

coc.nvim uses jsonc as a configuration file format. It's basically json with comment support.

In order to get comment highlighting, please add:

autocmd FileType json syntax match Comment +\/\/.\+$+

Recommended coc.nvim mappings

coc.nvim doesn't come with a default key mapping for LSP commands, so you need to configure it yourself.

Here's a recommended configuration:

" ~/.vimrc
" Configuration for coc.nvim

set hidden

" Some servers have issues with backup files
set nobackup
set nowritebackup

" Better display for messages
set cmdheight=2

" You will have a bad experience with diagnostic messages with the default 4000.
set updatetime=300

" Don't give |ins-completion-menu| messages.
set shortmess+=c

" Always show signcolumns
set signcolumn=yes

" Use tab for trigger completion with characters ahead and navigate.
" Use command ':verbose imap <tab>' to make sure tab is not mapped by other plugin.
inoremap <silent><expr> <TAB>
      \ pumvisible() ? "\<C-n>" :
      \ <SID>check_back_space() ? "\<TAB>" :
      \ coc#refresh()
inoremap <expr><S-TAB> pumvisible() ? "\<C-p>" : "\<C-h>"

" Used in the tab autocompletion for coc
function! s:check_back_space() abort
  let col = col('.') - 1
  return !col || getline('.')[col - 1]  =~# '\s'
endfunction

" Use <c-space> to trigger completion.
inoremap <silent><expr> <c-space> coc#refresh()

" Use <cr> to confirm completion, `<C-g>u` means break undo chain at current position.
" Coc only does snippet and additional edit on confirm.
inoremap <expr> <cr> pumvisible() ? "\<C-y>" : "\<C-g>u\<CR>"

" Use `[c` and `]c` to navigate diagnostics
nmap <silent> [c <Plug>(coc-diagnostic-prev)
nmap <silent> ]c <Plug>(coc-diagnostic-next)

" Remap keys for gotos
nmap <silent> gd <Plug>(coc-definition)
nmap <silent> gy <Plug>(coc-type-definition)
nmap <silent> gi <Plug>(coc-implementation)
nmap <silent> gr <Plug>(coc-references)

" Used to expand decorations in worksheets
nmap <Leader>ws <Plug>(coc-metals-expand-decoration)

" Use K to either doHover or show documentation in preview window
nnoremap <silent> K :call <SID>show_documentation()<CR>

function! s:show_documentation()
  if (index(['vim','help'], &filetype) >= 0)
    execute 'h '.expand('<cword>')
  else
    call CocAction('doHover')
  endif
endfunction

" Highlight symbol under cursor on CursorHold
autocmd CursorHold * silent call CocActionAsync('highlight')

" Remap for rename current word
nmap <leader>rn <Plug>(coc-rename)

" Remap for format selected region
xmap <leader>f  <Plug>(coc-format-selected)
nmap <leader>f  <Plug>(coc-format-selected)

augroup mygroup
  autocmd!
  " Setup formatexpr specified filetype(s).
  autocmd FileType scala setl formatexpr=CocAction('formatSelected')
  " Update signature help on jump placeholder
  autocmd User CocJumpPlaceholder call CocActionAsync('showSignatureHelp')
augroup end

" Remap for do codeAction of selected region, ex: `<leader>aap` for current paragraph
xmap <leader>a  <Plug>(coc-codeaction-selected)
nmap <leader>a  <Plug>(coc-codeaction-selected)

" Remap for do codeAction of current line
nmap <leader>ac  <Plug>(coc-codeaction)
" Fix autofix problem of current line
nmap <leader>qf  <Plug>(coc-fix-current)

" Use `:Format` to format current buffer
command! -nargs=0 Format :call CocAction('format')

" Use `:Fold` to fold current buffer
command! -nargs=? Fold :call     CocAction('fold', <f-args>)

" Add status line support, for integration with other plugin, checkout `:h coc-status`
set statusline^=%{coc#status()}%{get(b:,'coc_current_function','')}

" Show all diagnostics
nnoremap <silent> <space>a  :<C-u>CocList diagnostics<cr>
" Manage extensions
nnoremap <silent> <space>e  :<C-u>CocList extensions<cr>
" Show commands
nnoremap <silent> <space>c  :<C-u>CocList commands<cr>
" Find symbol of current document
nnoremap <silent> <space>o  :<C-u>CocList outline<cr>
" Search workspace symbols
nnoremap <silent> <space>s  :<C-u>CocList -I symbols<cr>
" Do default action for next item.
nnoremap <silent> <space>j  :<C-u>CocNext<CR>
" Do default action for previous item.
nnoremap <silent> <space>k  :<C-u>CocPrev<CR>
" Resume latest coc list
nnoremap <silent> <space>p  :<C-u>CocListResume<CR>

" Notify coc.nvim that <enter> has been pressed.
" Currently used for the formatOnType feature.
inoremap <silent><expr> <cr> pumvisible() ? coc#_select_confirm()
      \: "\<C-g>u\<CR>\<c-r>=coc#on_enter()\<CR>"

" Toggle panel with Tree Views
nnoremap <silent> <space>t :<C-u>CocCommand metals.tvp<CR>
" Toggle Tree View 'metalsBuild'
nnoremap <silent> <space>tb :<C-u>CocCommand metals.tvp metalsBuild<CR>
" Toggle Tree View 'metalsCompile'
nnoremap <silent> <space>tc :<C-u>CocCommand metals.tvp metalsCompile<CR>
" Reveal current current class (trait or object) in Tree View 'metalsBuild'
nnoremap <silent> <space>tf :<C-u>CocCommand metals.revealInTreeView metalsBuild<CR>

Installing coc-metals

Once you have coc.nvim installed, you can then install Metals a few different ways. The easiest is by running:

:CocInstall coc-metals

If you'd like to use the latest changes on master, you can also use the url of the repo in the command like so:

:CocInstall https://github.com/scalameta/coc-metals

If you'd like to use the latest changes on master, but would prefer managing the plugin using a plugin manager to download the extension, make sure you run the below snippet to uninstall the old version first.

:CocUninstall coc-metals

Then, if you are using vim-plug for example, enter the following into where you manage your plugins:

Plug 'scalameta/coc-metals', {'do': 'yarn install --frozen-lockfile'}

Then, issue a :PlugInstall to install the extension, and regularly a :PlugUpdate to update it and pull in the latest changes. If you're relying on coc.nvim to install the extension, it will automatically pull in the latest versions when published.

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.

Import build

"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.
Use tail -f .metals/metals.log to watch the build import progress.
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 metals.sbtScript setting to use a custom sbt script instead of the default Metals launcher if you need further customizations like reading environment variables.

Sbt Launcher

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.

Consult the Bloop documentation to learn how to speed up build import.

Importing changes

When you change build.sbt or sources under project/, you will be prompted to re-import the build.

Import sbt changes

Configure Java version

The coc-metals extension uses by default the JAVA_HOME environment variable (via find-java-home) to locate the java executable.

No Java Home

If no JAVA_HOME is detected you can then Open Settings by following the instructions or do it at a later time by using :CocConfig or :CocConfigLocal which will open up your configuration where you can manually enter your JAVA_HOME location.

Enter Java Home

Using latest Metals SNAPSHOT

Update the "Server Version" setting to try out the latest pending Metals features.

Version	Published
0.8.3	20 Mar 2020 08:09
0.8.3+176-14c95365-SNAPSHOT	09 Apr 2020 17:38

After updating the version, you'll be triggered to reload the window. This will be necessary before the new version will be downloaded and used.

Update Metals Version

List all workspace compile errors

To list all compilation errors and warnings in the workspace, run the following command.

:CocList diagnostics

Or use the default recommended mapping <space> a.

This is helpful to see compilation errors in different files from your current open buffer.

Diagnostics

Worksheets

Metals allows users to create a *.worksheet.sc file and see evaluations right in the file. In Vim, this is done using comments that are inserted which will allow you to hover on them to expand. In Neovim, this is done using Neovim's virtual text to implement Metal's Decoration Protocol. If using Neovim, make sure to have the following line in included in your .vimrc along with your coc.nvim mappings.

nmap <Leader>ws <Plug>(coc-metals-expand-decoration)

Then, when on the line that you'd like to expand the decoration to get the hover information, execute a <leader>ws in order to see the expanded text for that line.

Decorations with worksheets

Tree View Protocol

coc-metals has a built-in implementation of the Tree View Protocol. If you have the recommended mappings copied, you'll notice that in the bottom you'll have some TVP related settings. You can start by opening the TVP panel by using the default <space> t. Once open, you'll see there are two parts to the panel. The first being the MetalsCompile where you can see the status of ongoing compilations for your modules and also options to compile.

MetalsCompile

You are able to trigger the compiles while being on top of the option you are attempting to trigger and pressing r. You can change this default in the settings. You can find all the relevant TVP settings below in the Tree View Protocol configuration options.

The second part of the TVP panel is a view of your project and external dependencies. You can navigate through them by jumping to the next or previous nodes, the last or first nodes, or jumping to parent or first child nodes. There are shortcuts to all of these found below. You will see the traits, classes, objects, members, and methods are all color coded.

Tree View Protocol configuration options

Configuration Option	Description
`metals.treeviews.toggleNode`	Expand / Collapse tree node (default `<CR>`)
`metals.treeviews.initialWidth`	Initial Tree Views panels (default `40`)
`metals.treeviews.initialViews`	Initial views that the Tree View Panel displays. Done mess with this unless you know what you're doing.
`metals.treeviews.gotoLastChild`	Go to the last child Node (defalt `J`)
`metals.treeviews.gotoParentNode`	Go to parent Node (default `p`)
`metals.treeviews.gotoFirstChild`	Go to first child Node (default `K`)
`metals.treeviews.executeCommand`	Execute command for node (default `r`)
`metals.treeviews.gotoPrevSibling`	Go to prev sibling (default `<C-k>`)
`metals.treeviews.gotoNextSibling`	Go to next sibling (default `<C-j>`)
`metals.treeviews.forceChildrenReload`	Force the reloading of the children of this node. May be useful when the wrong result is cached and tree contains invalid data. (default `f`)
`metals.treeviews.executeCommandAndOpenTab`	Execute command and open node under cursor in tab (if node is class, trait and so on) (default `t`)
`metals.treeviews.executeCommandAndOpenSplit`	Execute command and open node under cursor in horizontal split (if node is class, trait and so on) (default `s`)
`metals.treeviews.executeCommandAndOpenVSplit`	Execute command and open node under cursor in horizontal split (if node is class, trait and so on) (default `v`)

Run doctor

To troubleshoot problems with your build workspace, open your coc commands by either using :CocCommand or the recommend mapping <space> c. This will open your command window allowing you to search for metals.doctor-run command.

Run Doctor Command

This command opens an embedded doctor in your preview window. If you're not familiar with having multiple windows, you can use <C-w> + w to jump into it.

Embedded Doctor

Other Available Command

metals.restartServer
metals.build-import
metals.build-connect
metals.sources-scan
metals.compile-cascade
metals.compile-cancel
metals.doctor-run
metals.logs-toggle

Show document symbols

Run :CocList outline to show a symbol outline for the current file or use the default mapping <space> o.

Document Symbols

Available Configuration Options

The following configuration options are currently available. The easiest way to set these configurations is to enter :CocConfig or :CocLocalConfig to set your global or local configuration settings respectively. If you'd like to get autocompletion help for the configuration values you can install coc-json.

Java Home directory

The Java Home directory used for indexing JDK sources and locating the java binary.

Default: JAVA_HOME environment variable with fallback to user.home system property.

Example:

{
  "metals.javaHome": "/Library/Java/JavaVirtualMachines/jdk1.8.0_192.jdk/Contents/Home"
}

sbt script

Optional absolute path to an sbt executable to use for running sbt bloopInstall. By default, Metals uses java -jar sbt-launch.jar with an embedded launcher while respecting .jvmopts and .sbtopts. Update this setting if your sbt script requires more customizations like using environment variables.

Default: empty string "".

Example:

{
  "metals.sbtScript": "/usr/local/bin/sbt"
}

gradle script

Optional absolute path to a gradle executable to use for running gradle bloopInstall. By default, Metals uses gradlew with 5.3.1 gradle version. Update this setting if your gradle script requires more customizations like using environment variables.

Default: empty string "".

Example:

{
  "metals.gradleScript": "/usr/local/bin/gradle"
}

maven script

Optional absolute path to a maven executable to use for generating bloop config. By default, Metals uses mvnw maven wrapper with 3.6.1 maven version. Update this setting if your maven script requires more customizations

Default: empty string "".

Example:

{
  "metals.mavenScript": "/usr/local/bin/mvn"
}

mill script

Optional absolute path to a mill executable to use for running mill mill.contrib.Bloop/install. By default, Metals uses mill wrapper script with 0.5.0 mill version. Update this setting if your mill script requires more customizations like using environment variables.

Default: empty string "".

Example:

{
  "metals.millScript": "/usr/local/bin/mill"
}

Scalafmt config path

Optional custom path to the .scalafmt.conf file. Should be relative to the workspace root directory and use forward slashes / for file separators (even on Windows).

Default: .scalafmt.conf

Example:

{
  "metals.scalafmtConfigPath": "project/.scalafmt.conf"
}

Pants targets

The pants targets to export.

Space separated list of Pants targets to export, for example src/main/scala:: src/main/java::. Syntax such as src/{main,test}:: is not supported.

Default: empty string "".

Example:

{
  "metals.pantsTargets": "src::"
}

Don't generate Bloop plugin file for sbt

If true, Metals will not generate a project/metals.sbt file under the assumption that sbt-bloop is already manually installed in the sbt build. Build import will fail with a 'not valid command bloopInstall' error in case Bloop is not manually installed in the build when using this option.

Default: false

Example:

{
  "metals.bloopSbtAlreadyInstalled": "false"
}

Version of Bloop

This version will be used for the Bloop build tool plugin, for any supported build tool, while importing in Metals as well as for running the embedded server

Default: 1.4.0-RC1-190-ef7d8dba

Example:

{
  "metals.bloopVersion": "1.4.0-RC1"
}

Should display lenses with links to super methods

Super method lenses are visible above methods definition that override another methods. Clicking on a lens jumps to super method definition. Disabled lenses are not calculated for opened documents which might speed up document processing.

Default: true

Example:

{
  "metals.superMethodLensesEnabled": "false"
}

Remote language server

A URL pointing to an endpoint that implements a remote language server.

See https://scalameta.org/metals/docs/contributors/remote-language-server.html for documentation on remote language servers.

Default: empty string "".

Example:

{
  "metals.remoteLanguageServer": "https://language-server.company.com/message"
}

Enable on type formatting for multiline string formatting

on-type

To properly support adding | in multiline strings we are using the onTypeFormatting method. To enable the functionality you need to enable coc.preferences.formatOnType setting.

coc-preferences-formatOnType

Close buffer without exiting

To close a buffer and return to the previous buffer, run the following command.

:bd

This command is helpful when navigating in library dependency sources in the .metals/readonly directory.

Shut down the language server

The Metals server is shutdown when you exit vim as usual.

:wq

Statusline integration

It's recommended to use a statusline integration with coc-metals in order to allow messages to be displayed in your status line rather than as a message. This will allow for a better experience as you can continue to get status information while entering a command or responding to a prompt. However, we realize that not everyone by default will have this setup, and since the user needs to see messages about the status of their build, the following is defaulted to false.

"metals.statusBarEnabled": true

Again, it's recommended to make this active, and use a statusline plugin, or manually add the coc status information into your statusline. coc.nvim has multiple ways to integrate with various statusline plugins. You can find instructions for each of them located here. If you're unsure of what to use, vim-airline is a great minimal choice that will work out of the box.

With vim-airline you'll notice two noteworthy things. The first will be that you'll have diagnostic information on the far right of your screen.

Diagnostic statusline

You'll also have metals status information in your status bar.

Status bar info

Without a statusline integration, you'll get messages like you see below.

No status line

If you don't use a statusline plugin, but would still like to see this information, the easiest way is to make sure you have the following in your .vimrc.

set statusline^=%{coc#status()}%{get(b:,'coc_current_function','')}

Formatting on save

Add the following configuration to :CocConfig if you'd like to have :w format using Metals and Scalafmt.

"coc.preferences.formatOnSaveFiletypes": ["scala"]

This step cleans up resources that are used by the server.

Gitignore `project/metals.sbt` `.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. Bloop plugin that generates Bloop configuration is added in the project/metals.sbt file. It's recommended to ignore these directories and file from version control systems like git.

# ~/.gitignore
.metals/
.bloop/
project/metals.sbt

Using an alternative LSP Client

While we recommend using the coc-metals extension with coc.nvim, Metals will work with these alternative LSP clients. Keep in mind that they have varying levels of LSP support.

vim-lsc: simple installation and written in Vimscript.
LanguageClient-neovim: client written in Rust.
vim-lsp: simple installation and written in Vimscript.

Generating metals binary

If you now start Vim in a Scala project, it will fail since the metals-vim binary does not exist yet.

Next, build a metals-vim binary for the latest Metals release using the Coursier command-line interface.

Version	Published	Resolver
0.8.3	20 Mar 2020 08:09	`-r sonatype:releases`
0.8.3+176-14c95365-SNAPSHOT	09 Apr 2020 17:38	`-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.8.3 \
  -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.

Configure the system properties -Dhttps.proxyHost=… -Dhttps.proxyPort=… if you are behind an HTTP proxy.

The -Dmetals.client=vim-lsc flag is important since it configures Metals for usage with the vim-lsc client.

Requirements

Installing Vim

Installing yarn

Installing coc.nvim

Recommended coc.nvim mappings

Installing coc-metals

Importing a build

Custom sbt launcher

Speeding up import

Importing changes

Configure Java version

Using latest Metals SNAPSHOT

List all workspace compile errors

Worksheets

Tree View Protocol

Tree View Protocol configuration options

Run doctor

Other Available Command

Show document symbols

Available Configuration Options

Java Home directory

sbt script

gradle script

maven script

mill script

Scalafmt config path

Pants targets

Don't generate Bloop plugin file for sbt

Version of Bloop

Should display lenses with links to super methods

Remote language server

Enable on type formatting for multiline string formatting

Close buffer without exiting

Shut down the language server

Statusline integration

Formatting on save

Gitignore project/metals.sbt .metals/ and .bloop/

Using an alternative LSP Client

Generating metals binary

Gitignore `project/metals.sbt` `.metals/` and `.bloop/`