LSP4E in Eclipse IDE: more for Language (and debug) Servers!

With Eclipse Photon, the Eclipse ecosystem has consolidated its adherence to decoupled development tools, relying on Language Server Protocol and others. The examples of Eclipse projects interacting with the Language Server Protocol are numerous: LSP4J, LSP4E, aCute (C# edition in Eclipse IDE), Corrosion (Rust edition in Eclipse IDE), JDT.LS (Java edition in VSCode and Theia), Xtext, Ceylon, Che, Theia…

We believe that this trend and the rich noteworthy new features of Eclipse LSP4E make it worth an interesting article. Enjoy ;)

Support for Debug Adapter Protocol

LSP4E now supports the Debug Adapter Protocol created for VS Code. Similar to the language server protocol, this now means tool developers may reuse debug adapters developed for the debug protocol and have them automatically integrated with Eclipse debugger functionality.

Debug Protocol Overview

The debug protocol provides a generic interface based on JSON between the Client (IDE or editor) and the Server (the debugger or an adapter to the debugger).

The protocol consists of:

  • Requests e.g. GoToRequest, SetBreakpointRequest, VariablesRequest
  • Responses e.g. GoToResponse, SetBreakpointResponse, VariablesResponse
  • Events e.g. StoppedEvent, BreakpointEvent, ThreadEvent

For more details see the JSON or XTEND version of the protocol.

Integrating a Debug Adapter

LSP4E provides a Debug Adapter launch configuration which allows tool developers to quickly launch their debug extension and test out how it would work in the IDE. Once experiments have been made a launch configuration for the specific debug adapter can be created.

To try it out, install the Debug Adapter client for Eclipse IDE (Incubation) from the update site into your Eclipse installation. You will also need a debug adapter. You can get one from VS Code (it your ~/.vscode/extensions directory).

Create a Debug Adapter Launcher debug configuration.

Fill in the Command and command line Arguments for the debug adapter.

For example, the Command is likely to be the path to node and the argument to the extension's JavaScript. In the screenshot above, this is HOME/.vscode/extensions/ms-python.python-VERSION/out/clint.debugger.Main.js for using Python, with HOME and VERSION adapted to your machine.

Fill in the Launch Parameters (Json) with the bit of JSON that your specific launch adapter understands.

To create your own Eclipse plug-in that uses LSP4E’s Debug implementation you have two choices:

  1. Contribute to the launch configuration extension point, using the LSP4E’s DSPLaunchDelegate as the delegate. This requires saving into the launch configuration command, arguments and json launch parameters using the launch configuration keys defined in the DSPPlugin.
  2. Contribute to the launch configuration extension point using a custom launch delegate. Within the launch delegate, create a DSPDebugTarget and call initialize() on it to start the processing.

The advantage to option 1 is more reuse of some tricky code to launch and trace a debug adapter. The advantage of option 2 is DSPDebugTarget receives a Map and therefore clients of DSPDebugTarget do not have to use/store JSON in their launch configuration.

Using a Debug Adapter

From the end user perspective, nothing changes. They don’t have to do anything different to work with debugger extensions - just debug as normal. Today the debug protocol supports all essential debugging features, but does not support some advanced features of Eclipse debugger. We welcome contributors who want to work drive this forward with the community, see below for how to get involved!

Summary

The debug protocol implementation in LSP4E enables Eclipse IDE to quickly unlock support for new debuggers and debugger features. It also provides a way to support custom debuggers written in different programming languages. Tool developers can develop debug features in an agile and more efficient way for their users and keep up with the pace of fast-changing technology.

Support for latest version of the Language Server Protocol

As usual, LSP4E also comes with support for the latest version of the protocol by adopting the latest version of LSP4J API. As such, compared to previous 0.4.0 version, it includes support for interesting new operations and options. The most notable are supports for:

  • Dynamic command registrations
  • Support for external or HTTP links in completion and hover
  • Better support for CodeLens. With Eclipse Platform now shipping good support for “code mining”, LSP4E can now render CodeLens in a very nice way as code annotations. OCaml Language Server gives type inference as CodeLens, rendered in Eclipse IDE

  • Multi-root workspaces. Last year, language-server based architectures were not able to scale at the size of typical Eclipse IDE workspace with dozens of distinct projects, as LSP spec suffered from a multiplicity issue: each server was expected to be used by a single project. The LSP specification has evolved to support this, and LSP4E immediately made the necessary adaptations to adopt this new important feature.

More control and more logs for users and developers

In order to better enable complex language servers whose lifecycle is very dynamic, LSP4E has added the capability for LS integrators to refine when their LS is enabled for a given file, using a typical enabledWhen expression on the extension point.

LSP4E also now offers end users the possibility to disable a language server for a given file-type. It can be convenient for cases where the user has multiple extensions installed for a given file, one being based on language-server and finds that the one coming from language server is of inferior quality compared to the other one. Then, the user can disable the Language Server for those files in one click.

And finally, to help Language Server and LSP4E developers and integrators in troubleshooting their integrations, some easy to trigger logging capabilities were added in LSP4E. A dedicated preference page allows to control them trivially.

Possible integration with Docker

During the last release, LSP4E developers could also investigate possible integration with Docker-based language servers, and validate that with minimal effort, it’s possible to use a Docker image as a language server, including images developed for Eclipse Che. See the following demo:

Some next steps may happen during the summer on this topic. The project mailing-list is the best place to keep in touch.

LSP4E is your project too ;)

As any Eclipse.org project, LSP4E is a really open project. It’s everyone’s project. So if you’d like to learn more about it, or to simply be aware of the main discussions, or get involved in its continuous development, here are the entry-points:

It’s also important to acknowledge to work of many contributors to this release: Angelo Zerr, Alex Boyko, Elliotte Harold, Jonah Graham, Kris De Volder, Lucas Bullen, Lucia Jelinkova, Markus Ofterdinger, Martin Lippert, Mickael Istria, Philip Alldredge, Rastislav Wagner and Remy Suen.

About the Authors

Mickael Istria

Mickael Istria
Red Hat