Emacs Polyglot: an Emacs LSP client that stays out of your way:
- ๐ฝ Scroll down this README for some pretty gifs
- ๐ Read the manual
- ๐ฃ Read the NEWS file
- ๐ Folks over at Google seem to like it. Thanks!
Install from GNU 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:
- Ada's ada_language_server
- Bash's bash-language-server
- C/C++'s clangd or ccls
- C#'s omnisharp
- Clojure's clojure-lsp
- CMake's cmake-language-server
- CSS's css-languageserver
- Dart's analysis_server
- Dockerfile's docker-langserver
- Elixir's elixir-ls
- Elm's elm-language-server
- Erlang's erlang_ls
- Fortran's fortls
- Futhark's futhark lsp
- Go's gopls
- Godot Engine's built-in LSP
- HTML html-languageserver
- Haskell's haskell-language-server
- JSON's vscode-json-languageserver
- Java's Eclipse JDT Language Server
- Javascript's TS & JS Language Server
- Kotlin's kotlin-language-server
- Lua's lua-lsp
- Markdown's marksman
- Mint's mint-ls
- Nix's rnix-lsp
- Ocaml's ocaml-lsp
- Perl's Perl::LanguageServer
- PHP's php-language-server
- PureScript's purescript-language-server
- Python's pylsp, pyls pyright, or jedi-language-server
- R's languageserver
- Racket's racket-langserver
- Ruby's solargraph
- Rust's rust-analyzer
- Scala's metals
- TeX/LaTeX's Digestif
- VimScript's vim-language-server
- YAML's yaml-language-server
- Zig's zls
I'll add to this list as I test more servers.
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 LSP server
to Emacs's Flymake, which annotates/underlines the
problematic parts of the buffer. The information is shared with the
ElDoc system, meaning that the commands eldoc
and
eldoc-doc-buffer
(the latter bound to C-h-.
for convenience) show
diagnostics along with other documentation under point.
Flymake provides other convenient ways to view and manage diagnostic errors. These are described in its manual.
When Eglot manages a buffer, it disables pre-existing Flymake
backends. See variable eglot-stay-out-of
to change that.
The LSP server may provide code actions, for example, to fix a
diagnostic error or to suggest refactoring edits. The commands are
frequently associating with Flymake diagnostic annotations, so that
left-clicking them shows a menu. Additionally, the command
eglot-code-actions
asks the server for any code spanning a given
region.
Sometimes, these code actions are initiated by the server. See
eglot-confirm-server-initiated-edits
to control that behaviour.
Here, too, the LSP server's view of a given symbol or function
signature is relayed to the ElDoc system. The commands
eldoc
and eldoc-doc-buffer
commands access that information.
There are customization variables to help adjust ElDoc's
liberal use of the lower "echo area", among other options. If you
still find the solicitous nature of this LSP feature too distracing,
you can use eglot-ignored-server-capabilities
to turn it off.
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;
-
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."
Eglot
is subject to the same copyright assignment
policy as GNU Emacs
.
Any legally significant contributions can only be merged after the author has completed their paperwork. Please ask for the request form, and we'll send it to you.