Metals is a language server for Scala that works with VS Code, Vim, Emacs,
Sublime Text and Eclipse. Metals is developed at the
Scala Center and VirtusLab
with the help from Lunatech along with contributors from
the community.
Add code action to add/remove string interpolation.
Offer to organize imports when on an unused import.
[Scala 3] Better names for types in completions and hovers.
Add/remove string interpolation
Thanks to some great work by our newest contributor
Giggiux it's now possible to:
easily add string interpolation to an existing string
val message = "Hello this is a message"
When the cursor is positioned inside of the string we can invoke the code action
and get:
val message = s"Hello this is a message"
While this is a simpler code action, it can be paired with other things like
completions that allow for a workflow with less manual steps.
remove string interpolation if no splices are found
When the cursor is positioned inside a string interpolation, that does not contain
any splices ( $identifier), we will now offer an action to quickly get rid of
the additional s.
val message = s"Hello this is a message without splices"
will change to:
val message = "Hello this is a message without splices"
Offer to organize imports when on an unused import
In addition to the usual "organize imports", to try to improve the user
experience, Metals now offers a code action to organize imports whenever the
cursor is situated on an unused import reported by the diagnostics. Thanks
ckipp01 for this new feature!
[Scala 3] Better names for types in completions and hovers.
Thanks to another great PR by tanishiking
Metals will offer completions and hovers that include shorter names instead of
fully qualified ones whenever they are currently in scope. They will also be
more similar to the ones that you might be accustomed to in Scala 2. You can
find some more examples of improvements in the
pull request itself.
Miscellaneous
Make insert type work with renamed imports.
Treat .srcjar as jars to support Bazel in the future (thanks
darl!).
Contributors
Big thanks to everybody who contributed to this release or reported an issue!
We're happy to announce the release of Metals v0.10.1, which mainly concentrated
on bugfixes together with a couple of smaller improvements. We also added
support for the almost ready Scala 3 version 3.0.0-RC2. Its final release is
coming soon and Metals will try to make it an amazing experience!
Metals is a language server for Scala that works with VS Code, Vim, Emacs,
Sublime Text and Eclipse. Metals is developed at the
Scala Center and VirtusLab
with the help from Lunatech along with contributors from
the community.
Thanks to some great ideas (and obviously execution) by
@ckipp01 it is now possible to specify alternative
debug parameters that enable users to:
Run the main class in the current file, or in case that there are multiple
main classes quick pick window will appear for the users to choose the exact
main class to run.
Run all tests in the current file.
Run all tests in the current target.
To make that work some additional fields must be sent while starting the debug
session:
path - uri to the file that is currently open.
runType - enum value that can either be run, testFile or testTarget
The "args", "jvmOptions", "env", and "envFile" are all valid keys that can be
sent as well with the same format as usual.
In VS Code this is achieved via 3 new commands, that can easily bound to
shortcuts:
metals.run-current-file - run main classes in the current file
metals.test-current-file - run test classes in the current file
metals.test-current-target - run test classes in the current target
More information can be found in the
Debug Adapter Protocol
section of the documentation.
Miscellaneous
Support for Ammonite scripts using Scala 2.12.13 and 2.13.5.
Fix outline for documents with Scala 3 syntax.
Remove println that would sometimes print files while indexing them :(
Show an error when user adds bad dependency into a worksheet.
Fix issues on Windows with renames not being applied on current file.
Change project directory to lower case when using New Scala Project.
Renaming renamed imports now works correctly within a file.
Fix renaming named parameters in constructors.
Find alternative symbol references (such as companion object for a case class)
when not searching from the definition file.
Automatically backtick symbols when renaming.
Fix highlighting overloaded methods.
Fix classloader issues when using worksheets.
Fix issue where override was inserted twice for symbols that were already
overriden.
Infer type for higher kinded functions correctly.
Show better type decorations for higher kinded types.
Improve indexing of Scala 3 sources <- a lot of hard work by
@dos65!
Contributors
Big thanks to everybody who contributed to this release or reported an issue!
We're happy to announce the release of Metals v0.10.0, which is the first
release in the "Tungsten" line. In 0.10.x we will focus on polishing existing
features, fixing bugs and improving the Scala 3 support at least to the level of
Scala 2. This will pave the way towards the 1.0.0 release later this year.
Metals is a language server for Scala that works with VS Code, Vim, Emacs,
Sublime Text and Eclipse. Metals is developed at the
Scala Center and VirtusLab
with the help from Lunatech along with contributors from
the community.
Configuration option for the default Scala version.
Code lens to easily discover the copy worksheet command.
Improved short names when importing.
Debug run/test when using sbt via BSP.
[Scala 3] Support for Scala 3.0.0-RC1
[Scala 3] Filtering and sorting for completions.
[Scala 3] Basic shorter signature support for hover.
[Scala 3] Document outline
[Scala 3] Code folding
[Scala 3] Formatting | in multiline string
[Scala 3] Code action to convert to multiline string.
[Scala 3] Dependency sources navigation
Type decorations for definitions.
One of the most
requested features for Metals
was the ability to show the inferred type for anything that does not have it
defined explicitly. This includes the type at:
value and variable definitions
val a = 1var b = 2
method definitions
defmethod() = ""
variables in pattern matches
list match {
case aa :: tail =>
}
lambda parameters
list.map(param => param.toInt)
for comprehensions
for(i <- 0 to 10)`
The decoration is based on the information produced during the compilation, so
anything new will first need to be compiled to have the type shown.
This feature can easily be controlled by the previously available
metals.showInferredType setting and will currently work for clients that allow
virtual decoration to be inserted into existing text. Those clients currently
include Visual Studio Code, Emacs and Sublime Text (after merging this
PR).
Insert inferred type refactoring.
Another highly requested feature and closely related to the type decorations is
the ability to automatically insert type annotation. This is achieved using a
new Insert type annotations and
Insert type annotation into pattern definition refactor code actions. Those
actions work in the same places as mentioned in the previous point - method,
variables, lambdas etc. - but use the presentation compiler instead of indexes.
What it means is that this new feature will work even in some more problematic
cases when the file is not yet compiled or in files where type decorations are
not yet supported, like in worksheets.
There might be still some work to do when it comes to some more complicated
types, but it should work perfectly well for most daily use cases. Please do
report any issues you might encounter, as it will help us greatly to polish this
new feature.
Configuration option for default Scala version.
Previously, for any standalone files Metals would use the default Scala version
2.12.13. This changed in v0.10.0 and can either be defined with a setting:
"metals.fallbackScalaVersion" : "3.0.0-RC1"
or when the setting is empty or set to automatic Metals will infer the Scala
version automatically from the project, which will be the highest Scala version
used in the project.
Code lens for copy worksheet command.
In the previous version 0.9.8 a new command was added to Metals that allows
clients to export the worksheet output for the users to easily share their
results. This however was not easy to discover for a large chunk of the users,
which is why the command is also now available by using the code lens at the top
of a worksheet file. This will work for any clients that support the
copy-worksheet-output command.
Debug run/test when using sbt via BSP.
Thanks to the great work of @adpi2 and
@er1c on the
scala-debug-adapter Metals
now supports debugging when using sbt BSP. The experience should be almost the
same as when using Bloop, since the new library reuses the already existing
Bloop implementation and will be a standard to use for BSP servers.
To use sbt as a BSP server users still need to use metals.bsp-switch command,
which will take care of setting up everything and adding the appropriate
plugins.
More information about sbt and BSP can be found in the previously published
blogpost.
[Scala 3] Support for Scala 3.0.0-RC1
Scala 3.0.0-RC1 has just been released and it's the first release that starts
us on the way towards the full Scala 3 release. Syntax is now stable and the
compiler team will now focus on fixing existing issues and polishing the
internals.
This is a perfect opportunity to try out Scala 3 alongside Metals and see all
the new and interesting features that the language has to offer as well as
report any issues.
[Scala 3] Filtering and sorting for completions.
In previous versions of Metals, the completions offered by the language server
would just be a list of what is available in the current scope. This however did
not provide the best possible experience to the users. Thanks to work by
@sellophane those initial results are now
filtered and sorted so that the most useful methods and values will be available
first.
[Scala 3] Basic shorter signature support for hover.
Together with better completions we also included a better way to display types
on hover. Previously, we would always display the full class name with the
package prefix, which would mean that some methods could look quite complicated
for example:
Thanks to @tanishiking we no longer display
the long type for anything that is already imported into scope. So the above
method would look like:
def method(first: DType, second: DType)
This needs to be further improved by shortening some of the symbols that are not
imported into scope and we still need to apply the same optimization in other
places where the type is displayed.
[Scala 3] Parser-based features for Scala 3
Under the hood Metals uses a separate parser implementation that can be found in
scalameta and it supports numerous
different Scala versions. Thanks to the recent work on supporting Scala 3, we
now have a dialect that should parse the Scala 3 syntax correctly on par with
3.0.0-RC1 version.
This parser is used by Metals to provide a number of different features, that
should now work correctly for Scala 3:
document outline which shows the map for the current source file and can also
be searched, which is useful to locate a particular method or value in the
current document.
folding ranges which enables users to hide parts of their code.
automatic management of pipes in multiline string.
code action to convert simple string into multiline string.
go to definition in Scala 3 dependency sources.
Last mentioned feature together with recently added on-demand semanticdb index
generation enables users to properly navigate Scala 3 dependency sources.
At the end of 2020 the Metals team sent out a survey to gather input from our
users in hopes to get a better picture of who you are, what you want out of
Metals, and any other useful feedback you may have wanted to provide. With just
under 400 responses we got a ton of great data, some interesting insights, and
a nice picture of what is currently hindering users, and what common
functionality continually comes up as feature requests. In order to best use this
data, and also to share some results, we thought it'd be a good idea to go over
some of the sections, address some of the points that came up, and also clear up
any misconceptions that may have appeared in the survey results. The idea is for
this to be a 2 part series. You can expect the following:
Part 1 - Where we discuss some of the initial results and address some common
misconceptions and questions.
Part 2 - Where we go deeper into the desired features, the biggest pain
points, and our plans for this next year.
Editor Support
Surprising no one, VS Code came out on top for editors with the most desire for
Metals support. Our VS Code
extension has over 100k downloads
and it is safe to say that it offers the best support for overall Metals usage.
The next most popular of our extensions is probably coc-metals which had just
over 20k downloads in 2020. There are certain features that do only work in VS
Code mainly due to the robustness of the LSP support and other extra features.
Here are a few examples of features that we added this past year that work
extremely well with VS Code with no hardly no extra effort on the users part:
Debugging support - Early on in 2020 Metals v0.8.0 added debugging support.
Now with the click of a button you can run, test, and debug your code right
from inside VS Code.
Preview renames - in Metals v0.8.1 functionality was added so that you can now
preview the changes after triggering a rename for up to 300 files.
Analyze stacktrace functionality - As of Metals v0.9.4 Metals gained the ability
to take a stack trace and give you a nice view of the entire stack with
clickable links to go to that part of your code. This is all found in the
very useful web view of VS Code.
Show implicits and type decorations - As of Metals v0.9.5 Metals gained the
ability to show implicits and type decorations as decorations directly
inline of your code.
Show implicits conversion and classes - As of Metals v0.9.6 Metals gained the
ability to show implicits conversion and classes as decorations directly
inline of your code.
Navigativing stacktrace while debugging - Also in Metals v0.9.6 the ability to
navigate stacktraces during a deubugging sesions was added, which re-used
the functionality introduced in v0.9.4 to analyze stacktraces.
Now at this point you may be starting to assume that we heavily favor VS Code
and that Metals is geared towards it. We got a few comments related to this
throughout the survey. However, I want to make a specific point that since the
inception of Metals, the early maintainers did a fantastic job of ensuring that
everything would work in clients that offered the necessary LSP support, and
also extra features to clients that offered support for the Metals specific LSP
extensions that we use. This has remained core for us a we continue to provide
new features. Pretty much any new feature that is added is added in a way that
can also be utilized for editors that may not have the same level of support as
VS Code. Here are a few examples:
Debugging support - Metals actually offers deubugging support for any client
that can serve as a DAP client. So for example using coc-metals you can
also run, test, and debug your code while utilizing
vimspector. The same is true
for emacs clients that are utilizing
lsp-mode.
Analyze stacktrace functionality - For clients that don't have a web view,
this feature is still supported by producing a file with code lens' in it to
allow you to navigate to the relevant parts of the stacktrace.
Implicits, type decorations, implicits conversions and classes - VS Code isn't
the only extension that actually implements this. There is also
metals-sublime that has
inline decorations. For other editors that may not support inline
decorations, this feature is still re-usable and the information is actually
displayed in hover as another section.
So again, while VS Code is an incredible editor, that offers incredible support
for the various Metals features, we work hard to ensure that these features are
also usable in our other extensions, even if they look a bit different. While
there are varying levels of support in the various editor extensions, much of
this is due to the those editors being the editors the current maintainers use.
We are always open for more help in any of the current editor extensions and
this is actually a great way to get involved. We are also open to help you
create a new extension to maybe support an editor that is yet to have a
Metals-specific extension! Here are links to the various Metals clients:
Some of these editors will already actually work with Metals, especially if they
support VS Code extensions like Eclipse Theia does. However, one question we
often get is: "Will you support IntelliJ?" The simple answer to this question is
No, but not for the reason people may think. IntelliJ is a fantastic project
that is the most widely used editor in Scala. Metals aims to be a language
server for clients that implement LSP. Since IntelliJ has no official support
for LSP, we have no intention on adding support for IntelliJ. Many times the
target audience is different as well.
Why do people start using Metals
Reason
Very Important
Somewhat important
Not important
I wanted a lighter alternative to other IDEs.
245
74
27
I could use my favorite editor.
223
62
56
I wanted more accurate compiler errors.
220
86
36
I wanted a fully open source solution.
133
138
69
Metals had features other IDEs didn't
56
112
160
Information and Help with Metals
Over this past year we've done our best to make sure everyone is aware of all
the great stuff that is happening in Metals. We have multiple channels of
communication open with pretty impressive response times if you ever get stuck.
Here are the results about where people go for question about Metals and also
where they get their news about Metals.
Apart from the places that we had listed in the survey, the place mentioned the
most for where people hear about Metals related news was Scala
Times!
As a reminder, don't ever hesitate to reach out, and if anything is missing in
the docs, please lend a helping hand or point it out to us.
I wish Metals had... but it does!
Below are some things that appeared in the survey as wishes, but that Metals
already supports, or has added support for since the survey! Hopefully these
will help highlight some lesser known features of Metals or serve as a reminder
of some of the features we have.
Requested
Status
Renaming symbols
Available since v0.8.0 and all supported editors support this.
Better info about Ammonite scripts failing.
Actually because of this comment, there was some work done to improve the error messages about why Ammonite may not be starting. You can see this here in this pr.
A check telling me if everything is setup correctly.
We recently did some work or the Metals Doctor to help you see what issues are going on. You can trigger Doctor by the run-doctor command. It may differ a bit per client. You can see the recent changes made here in this pr.
Seamless install in Vim
There are two Metals-specific Vim and Neovim extensions, both which offer an automated install feature. coc-metals and nvim-metals.
Navigating stacktrace feature in emacs.
This actually should work, since it just needs code lenses to work for clients that don't have a web view. Part of this is just documentation, so if you're an emacs user, please help us with docs!
Use a specific version of Ammonite
You can currently do this by setting the version in a comment on the top of a file like illustrated here. Also the next release of Metals will have better support for a fallback version of the compiler that is used for standalone scripts. This will give you more control over what version is used in situations like Ammonite scripts.
What's next?
We want to thank you again for taking the time and filling out our year-end
survey. Keep on the lookout for Part 2 of this, and we'll be discussing the
biggest pain points and some of the most desired features that we plan to tackle
this next year. We'll also do a further look into build server and build tool
support finishing off with an update on our current Scala 3 support and the
efforts that are going into it.
We're happy to announce the release of Metals v0.9.10, which contains a number
of fixes and more importantly support for Scala 2.12.13. We're skipping over
the v0.9.9 release due to a significant bug that showed up after the release.
Metals is a language server for Scala that works with VS Code, Vim, Emacs,
Sublime Text and Eclipse. Metals is developed at the
Scala Center and VirtusLab
with the help from Lunatech along with contributors from
the community.
We're happy to announce the release of Metals v0.9.8, which brings along a
number of smaller improvements, new Scala 3 milestone support and a hot new
feature.
Metals is a language server for Scala that works with VS Code, Vim, Emacs,
Sublime Text, Atom and Eclipse. Metals is developed at the
Scala Center and VirtusLab
with the help from Lunatech along with contributors from
the community.
Thanks to the great work by ckipp01 users will now
be able to export their evaluated worksheets using a new command,
copy-worksheet-output, or Metals: Copy worksheet output in Visual Studio
Code.
When using this command existing statements will be copied to your clipboard
along with their evaluations included as comments below them. This will allow
users to freely share their results with others.
Miscellaneous
Add in Scala Sources to standalone worksheets.
Fix auto-connect BSP server without explicit choice.
Make sure to not duplicate semanticdbOptions when using sbt BSP.
Ensure semanticdb is enabled with sbt BSP and Scala 3
Contributors
Big thanks to everybody who contributed to this release or reported an issue!
$ git shortlog -sn --no-merges v0.9.7..v0.9.8
Chris Kipp
Tomasz Godzik
Gabriele Petronella
Victor Mikhaylov
Metals is a language server for Scala that works with VS Code, Vim, Emacs,
Sublime Text, Atom and Eclipse. Metals is developed at the
Scala Center and VirtusLab
with the help from Lunatech along with contributors from
the community.
We're happy to announce the release of Metals v0.9.6, which mostly concentrates
on adding support for the newly released Scala 2.13.4, but also adds some
improvements for already existing features.
Metals is a language server for Scala that works with VS Code, Vim, Emacs,
Sublime Text, Atom and Eclipse. Metals is developed at the
Scala Center and VirtusLab
with the help from Lunatech along with contributors from
the community.
Last
release
introduced the option to display additional data inferred from the code to a
user. Starting with this release it's also possible to show implicit conversions
and classes, which can be enabled by the additional
showImplicitConversionsAndClasses setting. Moreover, Visual Studio Code
extension has 3 new commands to toggle all these new options, which enables
users to quickly peek at the additional information about their code and then
turn it back off. All these commands can be bound to a shortcut to further
improve the user experience.
Any editor that allows for quickly changing these settings will also benefit
from this change, as the file's decorations are refreshed instantly upon
changing any of those settings.
Navigating stacktrace
Previously, it was possible to navigate a stacktrace using the
Analyze stacktrace command which was added in the
v0.9.4
release. It turns out, we can reuse the same mechanism to show file links in the
Debug Console in Visual Studio code:
This was achieved by adding additional information to the output already sent to
the editor, so this additional file links should also be reused by any other DAP
clients.
Troubleshooting
As an addition to these new features, we've also recently added a new
troubleshooting page that should answer
the most basic questions you can have. As the page is fairly new we would appreciate
any help in improving it so let us know if you feel anything is missing.
Miscellaneous
Fix continuous compilation when opening tree view in sbt BSP
Add 0.27.0-RC1 back to supported versions
Contributors
Big thanks to everybody who contributed to this release or reported an issue!
$ git shortlog -sn --no-merges v0.9.5..v0.9.6
Tomasz Godzik
Scala Steward
Chris Kipp
Gabriele Petronella
Krzysiek Bochenek
dependabot[bot]
We're happy to announce the release of Metals v0.9.5, which brings about some of
the long awaited features such as implicit decorations and the organize imports
code action. We also greatly simplified connecting to the sbt BSP server and
added support for Scala 3's first milestone 3.0.0-M1.
Metals is a language server for Scala that works with VS Code, Vim, Emacs,
Sublime Text, Atom and Eclipse. Metals is developed at the
Scala Center and VirtusLab
with the help from Lunatech along with contributors from
the community.
Show implicit parameters and inferred type decorations.
Improved sbt BSP support.
Support for Scala 3.0.0-M1.
Remote debugging.
Environment variables in run/debug.
Organize imports code action
One of the most requested features in the Metals repository, current list can be
found here, was the ability to
automatically organize imports. We are happy to announce, that thanks to
mlachkar's amazing contributions to both
Scalafix and Metals, this new feature
is now available via an Organize imports code action.
Depending on the editor this code action can be invoked differently, please
consult your specific editor's documentation. For example in Visual Studio Code
'organize imports' can be invoked from command console, shortcut, or from the
dropdown menu when right clicking inside a file.
The organize imports code action is enabled using
Scalafix and specifically the awesome
organize imports rule created by liancheng.
The rule can be used to automatically sort imports in a file by the Ascii order,
which is the default setting, or use the user specific configuration defined
using scalafix configuration file. This file can be either .scalafix.conf in
the current workspace or an absolute file specified in the
metals.scalafixConfigPath user setting. It's important to note that the new
code action is consistent with how sbt's scalafix plugin will behave.
An example scalafix configuration for the organize imports rule can look like
this:
import java.lang.{Long => JLong}
import scala.collection.mutable.ArrayBufferobjectRemoveUnused{
val buffer: ArrayBuffer[Int] = ArrayBuffer.empty[Int]
val long: JLong = JLong.parseLong("0")
}
Please do NOT use the Scalafix built-in RemoveUnused.imports together with
OrganizeImports to remove unused imports, since it might result in a broken
code.
Another highly anticipated feature was the ability to show additional
information about the code, which is not provided explicitly. In this new
release, users can use two new options when looking through their code:
metals.showImplicitArguments will enable users to see implicit parameters
within their code:
metals.showInferredType will enable users to see inferred type for any
generic methods they are using:
Both new options are disabled by default, since they add a great number of
information, which might not be necessary for all users. Full name with package
for each of the additional types or values will be available on hover.
These options can be set in Metals options in VS Code or in Emacs
(lsp-metals) using
lsp-metals-show-implicit-arguments and lsp-metals-show-inferred-type
variables set to t.
Unfortunately, due to current limitations, additional decorations are only
possible in Visual Studio Code and Emacs. In other editors the additional
information is available via hover and new With synthetics added section,
which shows how the whole current line would look with the additional
decorations.
Example of how this alternative approach looks in Vim:
Improved sbt BSP support
In recent months, eed3si9n and
adpi2 worked, under the auspices of Scala Center, on
making sbt capable of acting as a
Build Server Protocol server. This
enables Metals and other editors such as Intellij IDEA to directly communicate
with sbt in order to compile the user's code.
Some more work was required in order to make the new features work smoothly with
Metals and currently, thanks to ckipp01, users can
easily try out the new sbt BSP support. It's important to note that using Bloop
instead of sbt is still the recommended approach as we believe it provides the
best user experience and features like running or debugging are still not yet
implemented for sbt. More details and explanations can be found in the
blogpost.
Remote debugging
Thanks to the great work of pvid, Metals now supports
remote debugging, which means that it can attach to a running process with the
proper JVM options specified. There is no longer a need to run the application
or test from within the editor.
In case of a simple java process those options will take a form of for example:
suspend=y will make the process wait for Metals to connect to it if
specified to y. n will cause the process to run normally.
address=5005 specifies which port to use and it can be any free port.
For a detailed explanation of the different options please refer to the proper
documentation
here
When using sbt, remote debugging can be achieved by specifying additional
settings:
javaOptions in run := List("-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=5005"),
fork in run := true
This will cause running sbt run to wait for Metals to connect to it, which
might be especially useful when reading user input, which is currently
impossible to do for example from within VS Code. Similarly, these options can
be specified in any of the supported build tools.
To later connect to the running process, you need to use the additional Attach
request type with the buildTarget, hostname and port fields specified. In
case of Visual Studio Code this will take a form of:
# single line valueskey1=value 1
key2='value 2' # ignored inline comment
key3="value 3"# multi-line valueskey4='line 1
line 2'key5="line 1
line 2"# export statementsexportkey6=value 6
# comma delimiter
key7:value 6
# keys cannot contain dots or dashes
a.b.key8=value 8 # will be ignored
a-b-key9=value 9 # will be ignored
The format is adapted from
mefellows/sbt-dotenv and
bkeepers/dotenv. Example json
configurations above are defined for Visual Studio Code, the type and name
fields can be omitted when using in other clients.
This new feature has been contributed by mwz. Thanks
for the great work!
Miscellaneous
Removed javax from default excluded packages - it can be added back in the
configuration.
Fixed top level completions in empty files.
Fixed issues with run/debug when using VPN.
Fixed go to java sources in standalone worksheets.
Fixed issues with worksheets if the workspace was not first compiled.
Fixed sbt completions coming from project/*.scala files.
Only use import {java.util => ju} when there are conflicting symbols in the
file.
Muted InvalidProtocolException in the logs - this exception might happen.
normally and does not break anything.
Changed scalafix and scalafmt location in user configuration to absolute path.
Only report parsing errors after Scala version is confirmed for a file.
Added automatic retry in case of build server connection failure.
Contributors
Big thanks to everybody who contributed to this release or reported an issue!
If you've been following the sbt
releases, 1.4.x introduced some great new
features, one of those being BSP support. This effort was initiated by community
members and proposed to the Scala Center Advisory
Board.
Then thanks to the work of Adrien Piquerez and
Eugene Yokota BSP support became a reality in
1.4.0. You can read more about the reason behind the work and some of the
details of the implementation in this blog post: BSP Support in sbt
1.4.
The Metals team is also happy to announce that as of the 0.9.5 release, the
process to use other BSP servers like sbt is now much smoother. In some ways,
BSP is an implementation detail abstracted away from a user, and you may not
directly interact at all with your build server, even though it's pivotal for
the Metals experience. Therefore, we'd like to answer some common questions
about what this means to you as a user, explain some of the default choices
Metals makes for you, and show you how to explore the sbt BSP server.
What is BSP?
First off, you may be wondering what BSP is. The Build Server
Protocol (BSP) is a Protocol for IDEs and
build tools to communicate about compilation, running, testing, debugging, and
much more. If you're familiar with the Language Server
Protocol (LSP), BSP is
complementary to LSP and inspired by it. Where LSP allows your editor to
abstract over various programming languages by a shared way to communicate to a
language server, BSP allows IDE's to abstract over various build servers. A
typical example of this can be illustrated like so:
You have your editor (Emacs) communicating with Metals via LSP, and then Metals
communicating with a BSP server (Bloop) via BSP. This communication over BSP can
be about compiling your code, running your code, defining sources in your
workspace, etc. You can read all about the various communication types here in
the
protocol.
Bloop was the first server to implement
BSP, and it's the default build server for all build tools that Metals supports
at the moment. When you open a fresh project, you're prompted to import your
build, and this import process is running a form of "Bloop Install" to write
your build definition to .bloop/ for Bloop to read and use. Then as you
continue to edit, diagnostics and other information are flowing back and forth
from Metals to Bloop. Hopefully this gives you a brief picture of what BSP is,
and how it's used in Metals.
What does sbt BSP support mean for Metals?
Another question you may have is "what does sbt BSP support mean for Metals"?
This means a couple different things. Up until this point, if you wanted to use
sbt BSP, you needed to clear your .metals/ and .bloop directories, and then
start sbt with a specific flag before connecting to it. None of this is
necessary anymore. In order for BSP
discovery
to happen, you need a .bsp/*json file with instructions on how to
start/connect to the build server. A new command has been added to Metals (which
we'll go over down below) that can generate this file for you if it doesn't
exist, and then you will be automatically connected to sbt. If this file already
exist, then we provide a simple way for you to "switch" build servers and for
your choice to be remembered. We also automatically include an sbt plugin to
ensure the correct semantic information is produced by the compiler. So to
summarize, Metals now has the ability to generate the necessary .bsp/sbt.json
file if it doesn't exist, and to also switch back and forth from using Bloop or
sbt as your build server.
What's the difference between Bloop and sbt BSP?
At this point you may be asking, "what's the difference?". For an average user,
there may not be a ton of difference, however I'd like to outline a couple
things that may be relevant to you.
Bloop supports the Debug Adapter
Protocol (DAP) and sbt
doesn't. So you'll notice when using sbt as a build server, you won't have
the run or debug code lenses directly in your editor like you do with
Bloop.
Bloop writes all the necessary information about your build it needs to disk
whereas sbt loads it into memory. If you're a user that works for long
periods of time on a single project, then this may not matter to you at all.
However, if you jump in and out of projects, without having sbt shell
running, then you will pay the cost of loading up your build every time.
Bloop offers sbt file support that enables completions and hover, whereas
this is not yet available in the sbt BSP implementation.
sbt gives you access to the full task graph, so for example if you're using
BuildInfo, and you compile with Bloop, your BuildInfo won't get
generated. However, sources will get generated when using sbt server. This
can help avoid any potential inconsistencies.
While there are some more differences, these are probably the main ones you'll
notice as a user. These are both great tools, and you'll have to explore more to
see what is the best fit for you. For now, Metals defaults to using Bloop mainly
because we believe it provides a richer feature set and because pretty much all
of our testing includes Bloop as a build server.
How do I try it out?
Now to the good stuff. There are two main ways that you can start using sbt
server in Metals.
No .bsp/sbt.json exists
If no .bsp/sbt.json exists yet, you can generate it with the new
metals.generate-bsp-config command. At any time you can execute this command
and Metals will ensure that you're on the minimum required sbt version (1.4.1),
generate the .bsp/sbt.json file for you, include the necessary plugin, and
then auto-connect to the sbt build server. For example in VS Code this looks
like this:
metals.generate-bsp-config
.bsp/sbt.json already exists
If you've ran sbt on your project already, your .bsp/sbt.json file will
already exist. In this case, you can simply use the metals.bsp-switch command
and choose sbt. For example, using coc-metals, it looks like this:
metals.bsp-switch
Switching back to Bloop
After you do a metals.bsp-switch or metals-generate-bsp-config, your choice
will be remembered. So the next time that you open your workspace, you will
automatically connect to the last build server you had chosen. If you'd like to
go back to your previous build server, you can simply use the
metals.bsp-switch command again to choose your previous server. For editors
that have an html doctor, you can also reset your build server choice in the
Doctor.
Doctor reset
Conclusion
We hope you enjoy this easier way to use sbt server with Metals. If you're
curious about the implementation details, much of the work was done in this
pr. As always please don't
hesitate to ask questions on our various channels, submit issues, or create new
feature requests.
