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
- 🏆 Folks over at Google seem to like it. Thanks!
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.
By design, Eglot doesn't depend on anything but Emacs. But there
are ELPA dependencies to newer versions of so-called "core packages"
developed in the Emacs mainline. So unless you're using a
bleeding-edge Emacs, where loading eglot.el
is all you'd need to do,
make sure your package system pulls in and loads the newest
project.el
, xref.el
, eldoc.el
, etc... In case of trouble M-x find-library
can help you tell if that happened.
M-x eglot
can guess and work out-of-the-box with these servers:
- Javascript's TS & JS Language Server
- 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 haskell-language-server
- Elm's elm-language-server
- Kotlin's kotlin-language-server
- Go's gopls
- Ocaml's ocaml-lsp
- R's languageserver
- Dart's dart_language_server
- Elixir's elixir-ls
- Erlang's erlang_ls
- Ada's ada_language_server
- Scala's metals
- TeX/LaTeX's Digestif
- Nix's rnix-lsp
- Godot Engine's built-in LSP
- Fortran's fortls
- Zig's zls
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
.
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.
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.
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.
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.
Similarly, some servers require the language identifier strings they
are sent by eglot
to match the exact strings used by VSCode. eglot
usually guesses these identifiers from the major mode name
(e.g. elm-mode
→ "elm"
), but the mapping can be overridden using
the :LANGUAGE-ID
element in the syntax of eglot-server-programs
if
necessary.
Should just work. Try M-x eglot
in a buffer visiting a remote file
on a server where you've also installed the language server. Only
supported on Emacs 27.1.
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:
-
Include the invaluable events transcript. You can display that buffer with
M-x eglot-events-buffer
. It contains the JSONRPC messages exchanged between client and server, as well as the messages the server prints to 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. -
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 loadingeglot.el
,company.el
andyasnippet.el
for example, and you don't even needuse-package.el
to do that).
Some more notes: it is often the case the you will have to report the problem to the LSP server's developers, too, though it's understandable that you report it Eglot first, since it is the user-facing frontend first. If the problem is indeed on Eglot's side, we do want to fix it, but because Eglot's developers have limited resources and no way to test all the possible server combinations, you'll sometimes have to do most of the testing.
Here's a summary of available commands:
-
M-x eglot
, as described above; -
M-x eglot-reconnect
reconnects to current server; -
M-x eglot-shutdown
says bye-bye to server of your choice; -
M-x eglot-shutdown-all
says bye-bye to every 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. Can also be invoked bymouse-1
-clicking some diagnostics. AlsoM-x eglot-code-action-<TAB>
for shortcuts to specific actions. -
M-x eldoc
asks the Eldoc system for help at point (this command isn't specific to Eglot, by the way, it works in other contexts). -
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 variableeglot-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 r") 'eglot-rename)
(define-key eglot-mode-map (kbd "C-c o") 'eglot-code-action-organize-imports)
(define-key eglot-mode-map (kbd "C-c h") 'eldoc)
(define-key eglot-mode-map (kbd "<f6>") 'xref-find-definitions)
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-confirm-server-initiated-edits
: If non-nil, ask for confirmation before allowing server to edit the source buffer's text;
There are a couple more variables that you can customize via Emacs lisp:
-
eglot-server-programs
: as described above; -
eglot-strict-mode
: Set tonil
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; -
eglot-managed-mode-hook
: Hook run after Eglot started or stopped managing a buffer. Useeglot-managed-p
to tell if current buffer is still being managed. -
eglot-stay-out-of
: List of Emacs features that Eglot shouldn't automatically try to manage on users' behalf. Useful when you need non-LSP Flymake or Company backends. See docstring for examples.
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,
This means that information about these file's contents is exchanged
periodically to provide enhanced coding assistance. Eglot works
primarily with Emacs' built-in libraries and not with third-party
replacements for those facilities.
- definitions can be found via
xref-find-definitions
; - on-the-fly diagnostics are given by
flymake-mode
; - function signature hints are given by
eldoc-mode
; - completion can be summoned with
completion-at-point
. - projects are discovered via
project.el
's API;
Some extra features are provided if certain libraries are installed and enabled, such as:
- completion dropdowns via company;
- snippet completions via yasnippet;
- marked-up documentation via markdown.
Eglot doesn't require these libraries to work effectively, but will use them automatically if they are found to be active.
To "unmanage" a project's buffers, shutdown the server with M-x eglot-shutdown
.
- initialize
- initalized
- shutdown
- exit
- $/cancelRequest
- window/showMessage
- window/showMessageRequest
- window/logMessage
- telemetry/event
- client/registerCapability (but only
workspace/didChangeWatchedFiles
, like RLS asks) - client/unregisterCapability (ditto)
- 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
- textDocument/didOpen
- textDocument/didChange (incremental or full)
- textDocument/willSave
- textDocument/willSaveWaitUntil
- textDocument/didSave
- textDocument/didClose
- textDocument/publishDiagnostics
- textDocument/completion
- completionItem/resolve (works quite well with company-mode)
- textDocument/hover
- textDocument/signatureHelp (fancy stuff with Python's pyls)
- textDocument/definition
- textDocument/typeDefinition (3.6.0)
- textDocument/implementation (3.6.0)
- textDocument/declaration (3.14)
- textDocument/references
- textDocument/documentHighlight
- textDocument/documentSymbol
- textDocument/codeAction
- textDocument/codeLens
- codeLens/resolve
- textDocument/documentLink
- documentLink/resolve
- textDocument/documentColor
- textDocument/colorPresentation (3.6.0)
- textDocument/formatting
- textDocument/rangeFormatting
- textDocument/onTypeFormatting
- textDocument/rename
The animation shows company-mode presenting the completion
candidates to the user, but Eglot works with the built-in
completion-at-point
function as well, which is usually bound to
C-M-i
.
Eglot provides template based completion if the server supports
snippet completion and yasnippet is enabled before
Eglot connects to the server. The animation shows
company-mode, but completion-at-point
also works with
snippets.
Eglot relays the diagnostics information received from the server to
flymake. Command display-local-help
(bound to C-h .
)
shows the diagnostic message under point, but flymake provides other
convenient ways to handle diagnostic errors.
When Eglot manages a buffer, it disables other flymake backends. See
variable eglot-stay-out-of
to change that.
The server may provide code actions, for example, to fix a diagnostic
error or to suggest refactoring edits. Command eglot-code-actions
queries the server for possible code actions at point. See variable
eglot-confirm-server-initiated-edits
to customize its behavior.
Type M-x eglot-rename RET
to rename the symbol at point.
To jump to the definition of a symbol, use the built-in
xref-find-definitions
command, which is bound to M-.
.
Eglot here relies on emacs' built-in functionality as well.
xref-find-references
is bound to M-?
. Additionally, Eglot
provides the following similar commands: eglot-find-declaration
,
eglot-find-implementation
, eglot-find-typeDefinition
.
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
, notM-x eglot-<language>
. Also, there are noeglot-<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-inproject.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."