Installation and usage
(package-install 'eglot) ; Requires Emacs 26! ;; Now find some source file, any source file M-x eglot
That's it. If you're lucky, this guesses the LSP executable to start for the language of your choice. Otherwise, it prompts you to enter one:
M-x eglot can guess and work out-of-the-box with these servers:
- 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
- Golang's go-langserver
- Ocaml's ocaml-language-server
I'll add to this list as I test more servers. In the meantime you can
(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. If the server has some quirk or non-conformity, it's possible to extend Eglot to adapt to it. Here's how to get cquery working for example:
(add-to-list 'eglot-server-programs '((c++ mode c-mode) . (eglot-cquery "cquery")))
You can also enter a
server:port pattern to connect to an LSP
server. To skip the guess and always be prompted use
C-u M-x eglot.
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
(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.
Commands and keybindings
Here's a summary of available commands:
M-x eglot, as described above;
M-x eglot-reconnectreconnects to the server;
M-x eglot-shutdownsays bye-bye to the server;
M-x eglot-renameask the server to rename the symbol at point;
M-x eglot-formatasks the server to format buffer or the active region;
M-x eglot-code-actionsasks 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-pointasks the server for help for symbol at point. Currently this is what
eldoc-modedisplays in the echo area;
M-x eglot-events-bufferjumps to the events buffer for debugging communication with the server.
M-x eglot-stderr-bufferif the LSP server is printing useful debug information in stderr, jumps to a buffer with these contents.
M-x eglot-signal-didChangeConfigurationupdates the LSP server configuration according to the value of the variable
eglot-workspace-configuration, which you may be set in a
.dir-localsfile, for example.
There are no keybindings specific to Eglot, but you can bind stuff
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,
(define-key eglot-mode-map (kbd "C-c h") 'eglot-help-at-point) (define-key eglot-mode-map (kbd "<f6>") 'xref-find-definitions)
How does this work exactly?
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
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
completion-at-point, among others.
To "unmanage" these buffers, shutdown the server with
Supported Protocol features (3.6)
- client/registerCapability (but only
workspace/didChangeWatchedFiles, like RLS asks)
- client/unregisterCapability (ditto)
- workspace/workspaceFolders (3.6.0)
- workspace/didChangeWorkspaceFolders (3.6.0)
- workspace/configuration (3.6.0)
- textDocument/didChange (incremental or full)
- completionItem/resolve (works quite well with company-mode)
- textDocument/signatureHelp (fancy stuff with Python's pyls)
- textDocument/typeDefinition (3.6.0)
- textDocument/implementation (3.6.0)
- textDocument/colorPresentation (3.6.0)
Obligatory animated gif section
Differences to lsp-mode.el
Eglot and lsp-mode.el share a common goal, which is to bring LSP to Emacs. lsp-mode.el is a more mature extension with a host of plugins for bells and whistles. Eglot may still lag it in some aspects, but the gap is closing as more features make it into Eglot and more servers are supported out-of-the-box.
Conversely, you may find Eglot surpasses lsp-mode.el in other aspects, namely simplicity. 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.
The single most visible difference is the friendly entry point
M-x eglot, not
M-x eglot-<language>. Also, there are no
There's no "whitelisting" or "blacklisting" directories to languages.
M-x eglotstarts servers to handle file of a major mode inside a specific project, using Emacs's built-in
project.ellibrary 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
Smoother/more responsive (read below).
Under the hood:
- Message parser is much simpler.
- Defers signature requests like
textDocument/hoveruntil server is ready.
textDocument/didChangefor 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
markdown-mode, if you happen to have these installed.
- Has automated tests that check against actual LSP servers.