LSP4E in Eclipse IDE: More for language (and debug) servers!
Looking to up your language server game? Eclipse Photon has got you covered. Jonah Graham and Mickael Istria explain how Eclipse Photon ships an improved support for Language Servers and enables debugging over the Debug Adapter Protocols. Plus, possible integration with Docker in the future!
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
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.
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:
- 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.
- 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!
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 Language Servers over 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:
- The project mailing-list lsp4e-dev.
- The bugtracker component is LSP4E, if you want to see open bugs (where your help is welcome) or report a new bug/enhancement proposal.
- LSP4E contribution guide and Git repo. LSP4E uses the awesome Gerrit code-review system to handle code contributions and reviews.
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.
This post was originally published in the June 2018 issue of the Eclipse Newsletter: Eclipse Photon – A Quantum Leap
For more information and articles check out the Eclipse Newsletter.