scalacenter / scala-debug-adapter

Implementation of the Debug Adapter Protocol for Scala

Version Matrix

scala-debug-adapter

build-badge Maven Central

The scala-debug-adapter is a server-side implementation of the Debug Adapter Protocol for the Scala language running on the JVM platform. It is based on and extends the microsoft/java-debug implementation.

The project originated in the Bloop repository, it is now released independently so that it can be used in other build tools of the Scala ecosystem. For instance, the sbt-debug-adapter is an sbt plugin that provide sbt with the debug adapter capability.

Usage

You can add the scala-debug-adapter as a dependency in your build.sbt:

// build.sbt
scalaVersion := "2.12.4",
libraryDependencies += "ch.epfl.scala" %% "scala-debug-adpater" % "1.0.0"

The scala-debug-adapter expects the Java Debug Interface to be class loaded. While it is always the case with Java 9, you probably want to use the sbt-jdi-tools to be able to run on Java 8 as well:

// project/plugins.sbt
addSbtPlugin("org.scala-debugger" % "sbt-jdi-tools" % "1.1.1")

You can start a debug server by providing your own intance of DebuggeeRunner and Logger. Examples of DebuggeeRunner can be found here.

val runner = new MyDebuggeeRunner()
val logger = new MyLogger()
val server = DebugServer(runner, logger)
server.start()
// use `server.uri` for the client to connect

sbt-debug-adapter

The sbt-debug-adapter is an sbt plugin compatible with sbt 1.4.0 or greater. It provides the sbt server with the BSP debugSession/start endpoint to start a Scala DAP server.

The specification of the debugSession/start endpoint can be found in the Bloop documentation.

Usage

As a global plugin use ~/.sbt/1.0/plugins/plugins.sbt, otherwise add to your local project (e.g. project/plugins.sbt):

// project/plugins.sbt
addSbtPlugin("ch.epfl.scala" % "sbt-debug-adapter" % "1.0.0")

Again the JDI tools must be class loaded, this time by sbt itself. To do so you can use the sbt-jdi-tools plugin in the meta project (it goes to project/project/plugins.sbt).

// project/project/plugins.sbt
addSbtPlugin("org.scala-debugger" % "sbt-jdi-tools" % "1.1.1")

Development

test-client

The test-client module is used internally to test the debug server. It contains the TestDebugClient, a minimal debug client that is used to communicate with the real server via socket.

References

History