Metals v2

What is it all about?

Tomasz Godzik

VirtusLab

Maintainer of multiple Scala tools including Metals, Bloop, Scalameta, Munit, Mdoc and parts of the Scala 3 compiler.

 

Release officer for Scala LTS versions

 

Part of the Scala Core team as coordinator and VirtusLab representative

 

Part of the moderation team

What do I do?

Most prominent Metals issues

01

02

03

04

MBT - Metals Build Tool

Fast IDE features

Improved Java Support

05

Plans

06

Questions

Metals

Metals is a language server protocol server.

Uses Language Server Protocol to provide IDE features in any editor that implements the LSP client

 

Based on JSON RPC

 

Widely supported by multiple editors, de facto standard for most languages

Metals LSP Server

Metals is also a model context protocol server.

Model Context Protocol is similar, but it is designed to be used by LLM agents

 

Provide tools and other resources to improve LLM results.

Metals MCP Server

We talked about it last year

Metals most prominent problems

 

  • Worse Java support in mixed Scala/Java projects
  • IDE features only available after a successful build
  • Workspace symbol search delegated entirely to BSP — slow, incomplete, brittle
  • Large monorepo setups can have even worse issues

Most prominent problems

 

Main Metals v2 goal: 

Make the IDE useful from the moment you clone a repo.

 

 

Main Metals v2 was worked on in Databricks by Ólafur Páll Geirsson, Iulian Dragos and others in the team.

 

"How many of you have waited 5+ minutes for IDE features after opening a project?"

 

  1. Metals Build Tool symbol index

  2. IDE Features available from the start
  3. Better Java Language Support

 

 

 

Main changes

Each feature reinforces the others — together they make Metals viable for large, mixed-language monorepos.

Metals Build Tool

Wait! Another build tool!?

 

It's not really a build tool

It's about getting the minimal amount of information from the build to somewhere Metals can access it directly.

Symbol search depended on the BSP build server. We needed to connect to the build server (could be different from the build tool)

 

We had to wait to get all `src/main/scala` etc.

Before (current main)

Before (current main)

Editor opened

Build import

(1-5 min)

Build import 

Build import 

Build import 

Build server start (20s-2min)

Build import 

Build import 

Build import 

Not imported

Already imported

Indexing

(30s - 3min)

Build import 

Build import 

Build import 

Ready to serve requests

Build import 

Build import 

Build import 

Compilation (30s - 10min)

Build import 

Build import 

Build import 

Future (main-v2)

Self-contained index, zero build dependency. Can work as soon as it's indexed.

Future (main-v2)

Editor opened

Build import

(1-5 min)

Build import 

Build import 

Build import 

Build server start (20s-2min)

Build import 

Build import 

Build import 

Not imported

Already imported

Indexing

(30s - 3min)

Build import 

Build import 

Build import 

Ready to serve requests

Build import 

Build import 

Build import 

Compilation (30s - 10min)

Build import 

Build import 

Build import 

How MBT works

git ls-files --stage  

~200-300ms  

Each file checked if modified by OID 

Index each file using existing fast indexers

Create IndexedDocument

Overwrite existing index.mbt on close

Special IndexedDocument

Contains information about all found identifiers added to bloom filters and definitions in a separate collection.

 

This is enough for navigation.

 

For references it's used together with the presentation compiler for correctness.

Bloom filters

  Query: "UserSer"
        │
        ├─ File A → MAYBE match → compile it
        ├─ File B → NO match    → skip         
        ├─ File C → NO match    → skip
        └─ File D → MAYBE match → compile it

  Result: only 2 of 4 files opened instead of all 4

Bloom filters

At scale (10k+ files), this means orders of magnitude fewer files scanned.

  Query: "UserSer"
        │
        ├─ File A → MAYBE match → compile it
        ├─ File B → NO match    → skip         
        ├─ File C → NO match    → skip
        └─ File D → MAYBE match → compile it

  Result: only 2 of 4 files opened instead of all 4

MBT features

Feature How MBT helps
Workspace Symbol     Primary provider
Find References  Pre-filter via Bloom filters → only scan candidates
Find Implementations Walks inheritance graph (depth ≤ 10) from index
Go to Definition  Fallback when classpath has no entry (pre-build)
Protobuf support   `.proto` files indexed alongside `.scala` and `.java`

 Protobuf Support via mbt

No separate Protobuf language server needed.

 

Very simple indexing in most cases

 

// ← appears in workspace/symbol
message TextDocuments { 
  // ← go-to-definition soon supported
  repeated TextDocument documents = 1; 
}

message TextDocument {
  reserved 4, 8, 9;
  Schema schema = 1;
  string uri = 2;
}

No startup time IDE - interactive features

git clone

 Full IDE: 

  • Hover
  • Complete
  • Navigate
  • References

 

Build import 

Build import 

Build import 

Open editor

Ideal scenario

If we don't have anything we put all sources into the presentation compiler.

 

This means that even in projects with broken build tool you should be able to work on your code.

How does it work?

And it does work in a lot of cases.

How does it work?

With caveats.

How does it work?

And it does work in a lot of cases.

The Scala presentation compiler accepts a `-sourcepath` flag that lets it resolve symbols directly from source files rather than requiring compiled class files on the classpath. 

Scala compiler -sourcepath option

 

The fallback Scala compiler now receives the full source path of the project, including sources from transitive dependencies — not just direct ones.

 

This means  the fallback compiler can resolve most symbols even in a large multi-module project without any compiled output.

 

 

Presentation compiler fallbacks

Two improvements make it possible.

  1. Files are pre-parsed to identify the package within each file.
  2. The compiler then asks the created structure when loading symbols.
  3.  It uses it to find out which files it needs to compile from a specific package.

 

Everything is lazy

Everything is lazy

package org.myorg.core

import org.myorg.util.Helper

object Main {
  Helper.printMessage(
    "Hello London!"
  )
}
package org.myorg.util

import org.myorg.util.Helper

object Helper {
  def printMessage(msg: String): Unit = {
    val message = "<info>" + msg
    println(message)
  }
}
package org.myorg.services

object Service {
  def execute(): Unit = {
    // very complicated code ...
  } 
}
org.myorg.core -> Main.scala
org.myorg.util -> Helper.scala
org.myorg.services -> Service.scala

Everything is lazy

package org.myorg.core

import org.myorg.util.Helper

object Main {
  Helper.printMessage(
    "Hello London!"
  )
}
package org.myorg.util

object Helper {
  def printMessage(msg: String): Unit = {
    val message = "<info>" + msg
    println(message)
  }
}
package org.myorg.services

object Service {
  def execute(): Unit = {
    // very complicated code ...
  } 
}

This file is ignored

This is compiled

When we edit this file

It's even more lazy

If we have explicit types for our methods there is no reason to compile the method itself  if we are not in that specific file.

 

Please use ExplicitResults rules in scalafix, it helps the tools a lot!

Actual compiler view

package org.myorg.core

import org.myorg.util.Helper

object Main {
  Helper.printMessage(
    "Hello London!"
  )
}
package org.myorg.util

object Helper {
  def printMessage(msg: String): Unit = ???
}

Bodies are ignored

When we edit this file

Actual compiler view

package org.myorg.core

import org.myorg.util.Helper

object Main {
  Helper.printMessage(
    "Hello London!"
  )
}
package org.myorg.util

object Helper {
  def printMessage(msg: String): Unit = ???
}

When we edit this file

Bodies are ignored

Sourcepath helps with the current project, but we still need to know what are the dependencies for the project.

 

This is where another feature of mbt comes in and the reason it's a "build tool"

 

What about the dependencies

.metals/mbt.json
{
  "dependencyModules": [
    {
      "id": "com.google.guava:guava:30.0-jre",
      "jar": "/path/to/guava-30.0-jre.jar",
      "sources": "/path/to/guava-30.0-jre-sources.jar"
    }
  ]
}

Separate source of information

It's a very simple file format, we have extractors ready for Bazel, Maven and Gradle.

 

It can be setup for your project and updated similar to lock files.

 

Will make the experience work faster and better, you might not need a build server sometimes

Separate source of information

  1. BSP dependency modules from the build server
  2. Manually or automatically generated `.metals/mbt.json`
  3. Heuristic scan of `.bloop/` or `.bazelbsp/` cached outputs (disabled by default)

 

Dependency fallback priority

This approach also works if we do have a full project structure

 

Results in completions and other features being up to date even with compilation issues

When does it help?

You can experiment with the new options

- workspaceSymbolProvider - mbt, bsp
- definitionProviders - protobuf, mbt
- javaSymbolLoader - javac-sourcepath, turbine-classpath
- javaTurbineRecompileDelay - 1.minute
- referenceProvider - bsp, mbt
- additionalPcChecks - [], [refchecks]
- scalaImportsPlacement - smart, append-last

Better Java support 

One of the main goals in Metals 2 to was to make it viable for large mixed codebases.

 

Hence we needed to step up out Java support as well.

Java support

We decided to implement most of the basic features of LSP for Java.

 

No complex refactors, since most likely LLM era makes them redundant.

Java support

Feature Status Powered by.
Completions ✅  Presentation compiler
Hover ✅  Presentation compiler
Signature Help  ✅  Presentation compiler
Diagnostics ✅  Presentation compiler
Semantic Highlighting ✅  Java Semanticdb 
Selection Range ✅  Javac AST
Document Symbols ✅  Javac AST
Go to Definition ✅  SemanticDB + mbt
Find References ✅  mbt + Bloom filters

But how to make it efficient in large codebase?

We use google turbine which allows us to define stubs for each file without compiling method bodies.

 

We get in-memory classfiles which the javac compiler can use as a normal classpath

But how to make it efficient in large codebase?

 

Caveat: It does not support project Lombok or annotation processors currently.

Google Turbine

example/File.java (edited)

example/Other.java

...

Classfiles stubs: example/Other.class, example/Other2.class

File.java, 

Google Turbine

Presentation compiler

Javac outline compiler, compiles the file fully

example/File.java (edited)

example/Other.java

...

Classfiles stubs: example/Other.class, example/Other2.class

File.java

Google Turbine

Presentation compiler

Javac outline compiler, compiles the file fully

Outline compiler, compiles without method bodies

AlsoEdited.java

By default turbine will run every minute, so we are back to classfiles once that completes

Google Turbine

Why not just `-sourcepath`?


 

  Edit Foo.java

javac resolves Bar (from sourcepath)

Bar references Baz → compile Baz too

Baz references Qux → compile Qux...

  💥 500 files compiled for one edit

Why not just `-sourcepath`?


 

Sourcepath will still be used for any broken files and any changed files within last minute.

 

We still prefer to depend on fully compiled workspace as it's more efficient.

Overall, the approach in Java is very much similar to what we have in Scala.

 

The main difference is the inclusion of Google Turbine.

Java Support

 

Plans

  1. Port upstream v1 changes (v1.5.2+) - new features and bugfixes
  2. Scala 3 validation - making sure that Scala 3 works correctly also with sourcepath.
  3. Stabilization - test across all build tools, not just Bazel/Bloop.
  4. Documentation - configuration guide for all new options, make sure config is up to date.

What's left?

A lot was done to improve Bazel support:

- source jar as roots;

- handling large BSP messages;

 

But a lot of this was done with internal Bazel BSP server inside Databricks.

 

We're working on our own Scala based inlined inside Metals.

Bazel Improvements

We are happy to work with you to improve your workflow

 

Via contracts if needed, but usually just happy to help

Summary

 

Java Support

  • mostly feature complete
  • turbine
  • outline compiler

 

Fast IDE features

  • sourcepath fallback
  • mbt fallback
  • better crash resilience

 

MBT Index

  • bloom filters
  • protobuf
  • persists to disk
  • can use mbt.json

How do I actually use it?

Build from source on main-v2 

 

or

 

​metals.serverVersion : "2.0.0-M8"

Thank You

Tomasz Godzik

Bluesky:      @tgodzik.bsky.social 

Mastodon:  fosstodon.org/@tgodzik

Discord:       tgodzik

 

tgodzik@virtuslab.com

Metals V2

By Tomek Godzik

Metals V2

  • 92

More from Tomek Godzik