Bringing Emacs Support to OCaml's LSP Server with ocaml-eglot

The team of people working on editors and editor support at Tarides is excited to announce the release of ocaml-eglot! The project is part of Tarides’ efforts to improve the OCaml developer experience across different platforms and workflows, a high-priority goal continuously evolving with community feedback.

Bringing Emacs integration to OCaml’s LSP server benefits both the user and the maintainer. If you use Emacs and want to start using OCaml, or switch to a more simplified setup, check out the ocaml-eglot repository on GitHub to try the new Emacs minor mode.

This post will give you some background to the development of the new tool, as well as the benefits and limitations of LSP, and the features of ocaml-eglot. Let’s dive in!

The Problem: ‘Editor Burnout’

The goal of the ocaml-eglot project was to address a problem the engineers had dubbed editor burnout. Developers rely on editors to simplify their coding workflow, and over the years, the creation of more and more editor features has transformed editors into sophisticated, feature-rich development environments. However, all these features need to be added and maintained in every editor. Maintaining support for so many different features across different editors, including updating the support every time something changes on the language server's end, can quickly become untenable. ‘Editor burnout’ refers to the pressure this puts on maintainers.

In OCaml, the editor-agnostic server Merlin is used to provide IDE-like services. By providing contextual information about the code, Merlin lets developers use simple text editors to write OCaml and benefit from features that typically come from a fully integrated IDE. However, Merlin also had a high maintenance cost due to each code editor needing its own integration layer.

So, now that we understand the problem, what is the solution?

LSP and OCaml

LSP, or the Language Server Protocol, is a widely documented open protocol that standardises the interactions between an editor and a server providing IDE services. LSP defines a collection of standard features across programming languages, which has contributed to its widespread adoption. This adoption has made LSP a standard protocol across editors, including Visual Studio Code, Vim, Emacs, and many more.

The language server implementation for LSP in OCaml is ocaml-lsp. It uses Merlin as a library. It was originally designed to integrate with Visual Studio Code when paired with the vscode-ocaml-platform plugin. We can significantly reduce the maintenance burden by relying on LSP's defaults for editor compatibility and only providing support for OCaml-specific features. This benefits not only the maintainers, but also the user by ensuring the plugins remain performant, compatible, maintainable, and up-to-date.

LSP aims to be compatible with as many languages as possible, making some assumptions about how those languages are structured and function. Inevitably, these assumptions cannot cover all the features of every language. This is true of OCaml, where the editing experience relies on custom features outside the scope of the LSP.

The solution to this incompatibility is to create a client-side extension that covers what the editor’s standard LSP support does not. That way, we have both the basic LSP compatibility and an extension that adds support for OCaml-specific features. As we’ve hinted above, this has the added benefit of keeping the maintenance workload on the editor side down by delegating the standard LSP handling to the generic LSP plug-ins.

Some of these OCaml-specific editor features include type-enclosing, construct and navigation between holes, destruct, and search by types.

OCaml-Eglot

As an editor popular with the OCaml community, let’s take a brief look at how Emacs and OCaml work together. In Emacs, developers can attach a "buffer"/file to a major mode to handle a feature of a language like OCaml: features like syntax highlighting, for example. One file is always attached to just one major mode.

OCaml has four major modes:

• caml-mode: the original,
• tuareg: a full reimplementation of caml-mode and the most common choice by users,
• ocaml-ts-mode: an experimental version of caml-mode based on tree-sitter grammar,
• neocaml: an experimental full reimplementation of tuareg based on tree-sitter grammar.

Now, we can also attach one or multiple minor-modes to a file, and this is where ocaml-eglot comes into play. For example, we can use a major mode (we generally recommend Tuareg) and link ocaml-eglot to it as a minor mode, thereby attaching LSP features to all files in which Tuareg is active.

Eglot is the default LSP client bundled with Emacs, and ocaml-eglot provides full OCaml language support in Emacs as an alternative to Merlin integration. (By the way, thanks to the ocaml-eglot client using LSP’s defaults, its code size is a lot smaller than the traditional OCaml Emacs mode, which also makes it easier to maintain!).

The ideal user of ocaml-eglot is someone who is already an active Emacs user and wants to start using OCaml with minimal start-up hassle. The simplified configuration, automated setup, and consistency across different editors and languages are helpful both to people new to OCaml and to seasoned users with multiple editors, since they improve the workflow. The plugin supports all the features of the integration of Merlin into Emacs, merlin.el, meaning that users don’t lose any functionality with the new system. The ocaml-eglot project is also actively maintained, and users can expect regular future updates and a tool that evolves with the times.

Creating OCaml-Eglot

Let's peek behind the curtain at the development of ocaml-eglot. There are two common approaches that developers who implement server languages tend to use to add features outside of the LSP. These are Code Actions and Custom Requests:

• Code Action: A contextual action that can be triggered from a document perspective, can perform a file modification, and potentially broadcast a command that can be interpreted by the client. Code Actions are more ‘integrated’, which means that they sometimes even work ‘out of the box’ with the client. However, they are limited in terms of interactions and the command lifecycle.
• Custom Request: Not formally part of the protocol, but since LSP is a protocol layered on top of a regular server that can handle JSON RPC messages and responses, developers can still use arbitrary requests to provide extra features. Custom Requests give developers more power to add interactions and experiences, but always need specific editor integration.

The design process behind OCaml-eglot essentially boiled down to identifying all the features offered by merlin.el that were not covered by the LSP, and then adding them using Code Actions or Custom Requests. During this process, the developers asked themselves two questions to help them decide which approach to use:

• Should the feature be configured by arguments that are independent of the context: If the answer is yes, they used a Custom Request; if no, they used a Code Action.
• Does the feature require additional interaction such as choosing one option from a set of possible results?: If yes, they used a Custom Request; if no, they used a Code Action.

Of course, things were a little more complicated than this in reality, but it still gives you a good idea of the types of technical decisions the team made during development.

Try it Out!

Install ocaml-eglot by checking out its GitHub repository and following the instructions. When you have had a chance to test it out in your projects, please share your experience on OCaml Discuss to give other users an idea of what to expect and the maintainers an idea on what to improve!

Installing ocaml-eglot is just like installing a regular Emacs package. It is available on Melpa and can be installed in many different ways, for example with GNU’s use package. More detailed instructions are available in the repo’s readme, including instructions on recommended configurations for ocaml-eglot.

Features

Some of the features that ocaml-eglot comes with are:

• Error navigation: Quickly jump to the next or previous error(s).
• Type information: Display types under cursor with adjustable verbosity and navigate enclosing expressions.
• Code generation: Pattern match construction, case completion, and wildcard refinement via the ‘destruct’ feature.
• Navigation: Jump between language constructs like let, module, function, match, and navigate phrases and pattern cases.
• Search: Find definitions, declarations, and references. The team also recently introduced a new Xref Backend inspired by one used by Jane Street for years.

Check out the project's readme to discover the full list of commands offered by ocaml-eglot. The new mode is ‘agile’, meaning that the team can also incubate new features quickly, like the refactor extract at toplevel.

Until Next Time

For some really helpful background that goes into more detail than we did in this post, I recommend that you read the paper “A New Era of OCaml Editing Powered by Merlin, Delivered by LSP” by Xavier van de Woestyne, Sonja Heinze, Ulysse Gérard, and Muluh Godson.

You can connect with us on Bluesky, Mastodon, Threads, and LinkedIn or sign up to our mailing list to stay updated on our latest projects. We look forward to hearing from you!