Debug Adapter Protocol

Metals implements the Debug Adapter Protocol, which can be used by the editor to communicate with JVM to run and debug code.

How to add support for debugging in my editor?#

There are two main ways to add support for debugging depending on the capabilities exposed by the client.

Via code lenses#

The editor needs to handle two commands in its language client extension: metals-run-session-start and metals-debug-session-start. These commands should get executed automatically by the LSP client once the user activates a code lens. The difference between them is that the former ignores all breakpoints being set while the latter respects them. The procedure of starting the run/debug session is as follows:

Then we can request the debug adapter URI from the metals server using the debug-adapter-start command.

Via explicit main or test commands#

Apart from using code lenses, users can start a debug session by executing the debug-adapter-start command with any of following params:

for an explicit main class

{
  "mainClass": "com.foo.App",
  "buildTarget": "foo",
  "args": ["bar"],
  "jvmOptions": ["-Dpropert=123"],
  "env": { "RETRY": "TRUE" },
  "envFile": ".env"
}

for an explicit test class

{
  "testClass": "com.foo.FooSuite",
  "buildTarget": "foo"
}

buildTarget is an optional parameter, which might be useful if there are identically named classes in different modules. A URI will be returned that can be used by the DAP client.

envFile is an optional parameter, which allows you to specify a path to a .env file with additional environment variables. The path can be either absolute or relative to your project workspace. The parser supports single line as well as multi-line quoted values (without value substitution). Any variables defined in the env object take precedence over those from the .env file. Here's an example of a supported .env file:

# single line values
key1=value 1
key2='value 2'   # ignored inline comment
key3="value 3"

# multi-line values
key4='line 1
line 2'
key5="line 1
line 2"

# export statements
export key6=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

for Metals discovery

This option works a bit different than the other two param shapes as you don't specify a test or main class, but rather a runType of either "run", "runOrTestFile", "testFile", or "testTarget" and a file URI representing your current location. "run" will automatically find any main method in the build target that belongs to the URI that was sent in. If multiple are found, you will be given the choice of which to run. "runOrTestFile" will try to find a main or test class in your current file and run them. The "testFile" option will check for any test classes in your current file and run them. Similarly, "testTarget" will run all test classes found in the build target that the URI belongs to. The "args", "jvmOptions", "env", and "envFile" are all valid keys that can be sent as well with the same format as above.

{
  "path": "file:///path/to/my/file.scala"
  "runType": "testTarget"
}

Wiring it all together#

No matter which method you use, you still need to connect the debug adapter extension specific to you editor using the aforementioned URI and let it drive the run/debug session. For reference, take a look at the vscode implementation and how it is wired up together

Debugging the connection#

Create the following trace files to spy on incoming/outgoing JSON communication between the debug server and editor.

# macOS
touch ~/Library/Caches/org.scalameta.metals/dap-server.trace.json
touch ~/Library/Caches/org.scalameta.metals/dap-client.trace.json
# Linux
touch ~/.cache/metals/dap-server.trace.json
touch ~/.cache/metals/dap-client.trace.json