Implementing the Debug Adapter Protocol for Eclipse Theia and Eclipse Che
Over the last couple of years I have added debuggers for several different languages to Eclipse Che. It required a lot of effort. Recently I’ve started adding the same debugger support to the Theia IDE, using the Debug Adapter Protocol (DAP) used in VS Code.
In Eclipse Che, we have made a conscious effort to adopt de facto standards, to enable our users to use the widest selection of tools possible. To support many different programming languages, we use the Language Server Protocol (LSP) popularized by VS Code, and to support a wide array of debuggers, we decided to adopt the Debug Adapter Protocol. In the future, as other similar protocols are adopted, we will continue to use this approach to enable support for other tools.
The idea behind the Debug Adapter Protocol is to abstract into a protocol the way development tools communicate with debuggers. Since it is unrealistic to assume that existing debuggers will adopt this protocol any time soon, we assume that an intermediary component — a debug adapter — which understands the Debug Adapter Protocol and translates it for the existing debugger.
The diagram shows how the Debug Adapter Protocol makes it possible for a development tool to communicate with different debuggers via debug adapters. Debug adapters make it possible for debugger developers to make their tool available to developers who use many different integrated development environments, by separating the front-end view of the state of the debugger session from the back-end implementation.
Architecture and implementation details
When an Eclipse Che user decides to debug an application, they request a specific debug configuration, which will be resolved by the debug adapter. The debug adaptor can alter the passed debug configuration by filling in missing values or by adding, changing, or removing attributes. It is even possible to change the debug type “on the fly” through this mechanism. All of this processing happens before the debug adapter starts.
Next, the debug adapter is started on the server side and the debug session is initialized on the client. For most cases, the default implementation of the client debug session is enough. It is possible for the user to provide a custom implementation by using the client session factory, if we do not need a remote debugger running on the server, and the client debug session has all the functionality of the debug adapter.
And now let’s move on to the server-side details. There are more entities involved in the initialization of a server debug session. First of all, if a new debug adapter needs to be added, there is a contribution point. Basically, a new contribution has to provide all possible debug configuration types and tell the server-side architecture how to start the debug adapter or, in some cases, how to connect to it if it is already running. As you can see in the following diagram, we use a factory to start a debug adapter. This allows us to start the adapter inside a container or just establish a connection with a running container. The latter method is required if Che is running in a container.
When the debug adapter is started, we start the server debug session. The server debug session works as a proxy between the client and the debug adapter itself. As with the debug adapter, the debug session is produced by a factory in case we need to customize it.
To sum it up, the client and server debug sessions communicate with each other, while the server debug session communicates with the debug adapter.
- Use the Theia plugin API. Make the debug adapters plugins.
- Enable restorable debug sessions. If the browser is accidentally closed, there is no way to continue debugging.
- Build more debug adapters. The more debuggers we support, the more powerful the IDE will be.
- Add conditional breakpoints.
How to Contribute?
If you’re interested in contributing to the efforts you can find the source of the debugger plugin here: https://github.com/theia-ide/theia/tree/master/packages/debug
You can also open an issue on our repo: https://github.com/theia-ide/theia/issues
Finally, you can chat with me, or any of the Che committers, on our public channels: https://gitter.im/theia-ide/theia or https://mattermost.eclipse.org/eclipse/channels/theia-discussions.
Adding New Debuggers?
Check out these two stories for learning how you can leverage the implementation of the Debug Adapter Protocol in Eclipse Che, to add support for new debuggers: