M-x Eglot

Emacs Polyglot: an Emacs LSP client that stays out of your way:

📽 Scroll down this README for some pretty gifs
📚 Read about servers, commands and keybindings, and customization
📣 Read the NEWS file

1-2-3

Install from ELPA or MELPA. Just type M-x package-install RET eglot RET into Emacs 26.1+.

Now find some source file, any source file, and type M-x eglot.

That's it. If you're lucky, this guesses the LSP program to start for the language you're using. Otherwise, it prompts you to enter one.

Connecting to a server

M-x eglot can guess and work out-of-the-box with these servers:

Javascript's javascript-typescript-stdio
Rust's rls
Python's pyls
Ruby's solargraph
Java's Eclipse JDT Language Server
Bash's bash-language-server
PHP's php-language-server
C/C++'s ccls (cquery and clangd also work)
Haskell's IDE engine
Kotlin's kotlin-language-server
Go's gopls
Ocaml's ocaml-language-server
R's languageserver
Dart's dart_language_server
Elixir's elixir-ls
Ada's ada_language_server

I'll add to this list as I test more servers. In the meantime you can customize eglot-server-programs:

(add-to-list 'eglot-server-programs '(foo-mode . ("foo-language-server" "--args")))

Let me know how well it works and we can add it to the list.

To skip the guess and always be prompted use C-u M-x eglot.

Connecting automatically

You can also do:

  (add-hook 'foo-mode-hook 'eglot-ensure)

, to attempt to start an eglot session automatically everytime a foo-mode buffer is visited.

Connecting via TCP

The examples above use a "pipe" to talk to the server, which works fine on Linux and OSX but in some cases may not work on Windows.

To circumvent this limitation, or if the server doesn't like pipes, you can use C-u M-x eglot and give it server:port pattern to connect to a previously started TCP server serving LSP information.

If you don't want to start it manually every time, you can configure Eglot to start it and immediately connect to it. Ruby's solargraph server already works this way out-of-the-box.

For another example, suppose you also wanted start Python's pyls this way:

(add-to-list 'eglot-server-programs
             `(python-mode . ("pyls" "-v" "--tcp" "--host"
                              "localhost" "--port" :autoport)))

You can see that the element associated with python-mode is now a more complicated invocation of the pyls program, which requests that it be started as a server. Notice the :autoport symbol in there: it is replaced dynamically by a local port believed to be vacant, so that the ensuing TCP connection finds a listening server.

Per-project server configuration

Most servers can guess good defaults and will operate nicely out-of-the-box, but some need to be configured specially via LSP interfaces. Additionally, in some situations, you may also want a particular server to operate differently across different projects.

Per-project settings are realized with Emacs's directory variables and the Elisp variable eglot-workspace-configuration. To make a particular Python project always enable Pyls's snippet support, put a file named .dir-locals.el in the project's root:

((python-mode
  . ((eglot-workspace-configuration
      . ((:pyls . (:plugins (:jedi_completion (:include_params t)))))))))

This tells Emacs that any python-mode buffers in that directory should have a particular buffer-local value of eglot-workspace-configuration. That variable's value should be association list of parameter sections which are presumably understood by the server. In this example, we associate section pyls with the parameters object (:plugins (:jedi_completion (:include_params t))).

Now, supposing that you also had some Go code in the very same project, you can configure the Gopls server in the same file. Adding a section for go-mode, the file's contents become:

((python-mode
  . ((eglot-workspace-configuration
      . ((:pyls . (:plugins (:jedi_completion (:include_params t))))))))
 (go-mode
  . ((eglot-workspace-configuration
      . ((:gopls . (:usePlaceholders t)))))))

If you can't afford an actual .dir-locals.el file, or if managing these files becomes cumbersome, the Emacs manual teaches you programmatic ways to leverage per-directory local variables.

Handling quirky servers

Some servers need even more special hand-holding to operate correctly. If your server has some quirk or non-conformity, it's possible to extend Eglot via Elisp to adapt to it. Here's an example on how to get cquery working:

(add-to-list 'eglot-server-programs '((c++ mode c-mode) . (eglot-cquery "cquery")))

(defclass eglot-cquery (eglot-lsp-server) ()
  :documentation "A custom class for cquery's C/C++ langserver.")

(cl-defmethod eglot-initialization-options ((server eglot-cquery))
  "Passes through required cquery initialization options"
  (let* ((root (car (project-roots (eglot--project server))))
         (cache (expand-file-name ".cquery_cached_index/" root)))
    (list :cacheDirectory (file-name-as-directory cache)
          :progressReportFrequencyMs -1)))

See eglot.el's section on Java's JDT server for an even more sophisticated example.

Reporting bugs

Having trouble connecting to a server? Expected to have a certain capability supported by it (e.g. completion) but nothing happens? Or do you get spurious and annoying errors in an otherwise smooth operation? We may have help, so open a new issue and try to be as precise and objective about the problem as you can:

Try to replicate the problem with as clean an Emacs run as possible. This means an empty .emacs init file or close to it (just loading eglot.el, company.el and yasnippet.el for example, and you don't even need use-package.el to do that).
Include the log of LSP events and the stderr output of the server (if any). You can find the former with M-x eglot-events-buffer and the latter with M-x eglot-stderr-buffer. You run these commands in the buffer where you enabled Eglot, but if you didn't manage to enable Eglot at all (because of some bootstrapping problem), you can still find these buffers in your buffer list: they're named like *EGLOT <project>/<major-mode> events* and *EGLOT <project>/<major-mode> stderr*.
If Emacs errored (you saw -- and possibly heard -- an error message), make sure you repeat the process using M-x toggle-debug-on-error so you get a backtrace of the error that you should also attach to the bug report.

Some more notes: it's understandable that you report it to Eglot first, because that's the user-facing side of the LSP experience in Emacs, but the outcome may well be that you will have to report the problem to the server's developers, as is often the case. But the problem can very well be on Eglot's side, of course, and in that case we want to fix it! Also bear in mind that Eglot's developers have limited resources and no way to test all the possible server combinations, so you'll have to do most of the testing.

Commands and keybindings

Here's a summary of available commands:

M-x eglot, as described above;
M-x eglot-reconnect reconnects to the server;
M-x eglot-shutdown says bye-bye to the server;
M-x eglot-rename ask the server to rename the symbol at point;
M-x eglot-format asks the server to format buffer or the active region;
M-x eglot-code-actions asks the server for any code actions at point. These may tipically be simple fixes, like deleting an unused variable, or fixing an import. Left click on diagnostics to check if there are any there;
M-x eglot-help-at-point asks the server for help for symbol at point.
M-x eglot-events-buffer jumps to the events buffer for debugging communication with the server.
M-x eglot-stderr-buffer if the LSP server is printing useful debug information in stderr, jumps to a buffer with these contents.
M-x eglot-signal-didChangeConfiguration updates the LSP server configuration according to the value of the variable eglot-workspace-configuration, which you may be set in a .dir-locals file, for example.

There are no keybindings specific to Eglot, but you can bind stuff in eglot-mode-map, which is active as long as Eglot is managing a file in your project. The commands don't need to be Eglot-specific, either:

(define-key eglot-mode-map (kbd "C-c h") 'eglot-help-at-point)
(define-key eglot-mode-map (kbd "<f6>") 'xref-find-definitions)

Customization

Here's a quick summary of the customization options. In Eglot's customization group (M-x customize-group) there is more documentation on what these do.

eglot-autoreconnect: Control ability to reconnect automatically to the LSP server;
eglot-connect-timeout: Number of seconds before timing out LSP connection attempts;
eglot-sync-connect: Control blocking of LSP connection attempts;
eglot-events-buffer-size: Control the size of the Eglot events buffer;
eglot-ignored-server-capabilites: LSP server capabilities that Eglot could use, but won't;
eglot-put-doc-in-help-buffer: If non-nil, put eldoc docstrings in separate *eglot-help* buffer;
eglot-auto-display-help-buffer: If non-nil, automatically display *eglot-help* buffer;

There are a couple more variables that you can customize via Emacs lisp:

eglot-server-programs: as described above;
eglot-strict-mode: Set to nil by default, meaning Eglot is generally lenient about non-conforming servers. Set this to (disallow-non-standard-keys enforce-required-keys) when debugging servers.
eglot-server-initialized-hook: Hook run after server is successfully initialized;

How does Eglot work?

M-x eglot starts a server via a shell-command guessed from eglot-server-programs, using the current major-mode (for whatever language you're programming in) as a hint.

If the connection is successful, you see an [eglot:<server>] indicator pop up in your mode-line. More importantly, this means current and future file buffers of that major mode inside your current project automatically become "managed" by the LSP server, i.e. information about their contents is exchanged periodically to provide enhanced code analysis via xref-find-definitions, flymake-mode, eldoc-mode, completion-at-point, among others.

To "unmanage" these buffers, shutdown the server with M-x eglot-shutdown.

Supported Protocol features

General

Window

window/showMessage
window/showMessageRequest
window/logMessage
telemetry/event

Client

client/registerCapability (but only workspace/didChangeWatchedFiles, like RLS asks)
client/unregisterCapability (ditto)

Workspace

workspace/workspaceFolders (3.6.0)
workspace/didChangeWorkspaceFolders (3.6.0)
workspace/didChangeConfiguration
workspace/configuration (3.6.0)
workspace/didChangeWatchedFiles
workspace/symbol
workspace/executeCommand
workspace/applyEdit

Text Synchronization

Diagnostics

textDocument/publishDiagnostics

Language features

Obligatory animated gif section

Historical differences to lsp-mode.el

Around May 2018, I wrote a comparison of Eglot to lsp-mode.el, and was discussed with its then-maintainer. That mode has since been refactored/rewritten and now purports to support a lot of features that differentiated Eglot from it. It may now be very different or very similar to Eglot, or even sing with the birds in the trees, so go check it out. That said, here's the original comparison, which I will not be updating any more.

"Eglot is considerably less code and hassle than lsp-mode.el. In most cases, there's nothing to configure. It's a minimalist approach focused on user experience and performance.

User-visible differences:

The single most visible difference is the friendly entry point M-x eglot, not M-x eglot-<language>. Also, there are no eglot-<language> extra packages.
There's no "whitelisting" or "blacklisting" directories to languages. M-x eglot starts servers to handle file of a major mode inside a specific project, using Emacs's built-in project.el library to discover projects. Then it automatically detects current and future opened files under that project and syncs with server;
Easy way to quit/restart a server, just middle/right click on the connection name;
Pretty interactive mode-line section for live tracking of server communication;
Automatically restarts frequently crashing servers (like RLS);
Slow-to-start servers start asynchronously in the background;
Server-initiated edits are confirmed with the user;
Diagnostics work out-of-the-box (no flycheck.el needed);
Smoother/more responsive (read below).

Under the hood:

Message parser is much simpler.
Defers signature requests like textDocument/hover until server is ready.
Sends textDocument/didChange for groups of edits, not one per each tiny change.
Easier to read and maintain elisp. Yeah I know, very subjective, so judge for yourself.
Doesn't require anything other than Emacs, but will automatically upgrade to work with stuff outside Emacs, like company, markdown-mode, if you happen to have these installed.
Has automated tests that check against actual LSP servers."

paulmr / eglot Goto Github PK

eglot's Introduction