Implementing the Debug Adapter Protocol for Eclipse Theia and Eclipse Che

Anatolii Bazko
Jul 26, 2019 · 4 min read

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.

What’s Next?

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:

Eclipse Che Blog

News and articles for Eclipse Che - next-generation Eclipse…

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store