Eglot
Eglot is the Emacs client for the Language Server Protocol (LSP). The name “Eglot” is an acronym that stands for “Emacs Polyglot”. 1 Eglot provides infrastructure and a set of commands for enriching the source code editing capabilities of Emacs via LSP. LSP is a standardized communications protocol between source code editors (such as Emacs) and language servers—programs external to Emacs which analyze the source code on behalf of Emacs. The protocol allows Emacs to receive various source code services from the server, such as description and location of function calls, types of variables, class definitions, syntactic errors, etc. This way, Emacs doesn’t need to implement the language-specific parsing and analysis capabilities in its own code, but is still capable of providing sophisticated editing features that rely on such capabilities, such as automatic code completion, go-to definition of function/class, documentation of symbol at-point, refactoring, on-the-fly diagnostics, and more.
Eglot itself is completely language-agnostic, but it can support any programming language for which there is a language server and an Emacs major mode.
This manual documents how to configure, use, and customize Eglot.
This manual is for Eglot, the Emacs LSP client.
Copyright © 2022–2024 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, with the Front-Cover Texts being “A GNU Manual”, and with the Back-Cover Texts as in (a) below. A copy of the license is included in the section entitled “GNU Free Documentation License”.
(a) The FSF’s Back-Cover Text is: “You have the freedom to copy and modify this GNU manual.”
Table of Contents
Next: Eglot and LSP Servers, Previous: Eglot, Up: Eglot [Contents][Index]
1 Quick Start
This chapter provides concise instructions for setting up and using Eglot with your programming project in common usage scenarios. For more detailed instructions regarding Eglot setup, see Eglot and LSP Servers. See Using Eglot, for detailed description of using Eglot, and see Customizing Eglot, for adapting Eglot to less common use patterns.
Here’s how to start using Eglot with your programming project:
- Select and install a language server.
Eglot comes pre-configured with many popular language servers, see the value of
eglot-server-programs
. If the server(s) mentioned there satisfy your needs for the programming language(s) with which you want to use Eglot, you just need to make sure those servers are installed on your system. Alternatively, install one or more servers of your choice and add them to the value ofeglot-server-programs
, as described in Setting Up LSP Servers. - Turn on Eglot for your project.
To start using Eglot for a project, type M-x eglot RET in a buffer visiting any file that belongs to the project. This starts the language server configured for the programming language of that buffer, and causes Eglot to start managing all the files of the project which use the same programming language. The notion of a “project” used by Eglot is the same Emacs uses (see Projects in GNU Emacs Manual): in the simplest case, the “project” is the single file you are editing, but it can also be all the files in a single directory or a directory tree under some version control system, such as Git.
Alternatively, you can start Eglot automatically from the major-mode hook of the mode used for the programming language; see Starting Eglot.
- Use Eglot.
Most Eglot facilities are integrated into Emacs features, such as ElDoc, Flymake, Xref, and Imenu. However, Eglot also provides commands of its own, mainly to perform tasks by the language server, such as M-x eglot-rename (to rename an identifier across the entire project), M-x eglot-format (to reformat and reindent code), and some others. See Eglot Commands, for the detailed list of Eglot commands.
- That’s it!
Next: Using Eglot, Previous: Quick Start, Up: Eglot [Contents][Index]
2 Eglot and LSP Servers
This chapter describes how to set up Eglot for your needs, and how to start it.
Next: Starting Eglot, Up: Eglot and LSP Servers [Contents][Index]
2.1 Setting Up LSP Servers
For Eglot to be useful, it must first be combined with a suitable language server. Usually, that means running the server program locally as a child process of Emacs (see Processes in GNU Emacs Lisp Reference Manual) and communicating with it via the standard input and output streams.
The language server program must be installed separately, and is not further discussed in this manual; refer to the documentation of the particular server(s) you want to install.
To use a language server, Eglot must know how to start it and which
programming languages each server supports. This information is
provided by the variable eglot-server-programs
.
- Variable: eglot-server-programs ¶
This variable associates major modes with names and command-line arguments of the language server programs corresponding to the programming language of each major mode. It provides all the information that Eglot needs to know about the programming language of the source you are editing.
The value of the variable is an alist, whose elements are of the form
(major-mode . server)
.The major-mode of the alist elements can be either a symbol of an Emacs major mode or a list of the form
(mode :language-id id)
, with mode being a major-mode symbol and id a string that identifies the language to the server (if Eglot cannot by itself convert the major-mode to the language identifier string required by the server). In addition, major-mode can be a list of several major modes specified in one of the above forms – this means a running instance of the associated server is responsible for files of multiple major modes or languages in the project.The server part of the alist elements can be one of the following:
(program args…)
This says to invoke program with zero or more arguments args; the program is expected to communicate with Emacs via the standard input and standard output streams.
(program args… :initializationOptions options…)
program is invoked with args but options specifies how to construct the ‘:initializationOptions’ JSON object to pass the server on during the LSP handshake (see Advanced server configuration).
(host port args…)
Here host is a string and port is a positive integer specifying a TCP connection to a remote server. The args are passed to
open-network-stream
, e.g. if the connection needs to use encryption or other non-default parameters (see Network in GNU Emacs Lisp Reference Manual).(program args… :autoport moreargs…)
program is started with a command line constructed from args followed by an available server port and the rest of arguments in moreargs; Eglot then establishes a TCP connection with the server via that port on the local host.
function
This should be a function of a single argument: non-
nil
if the connection was requested interactively (e.g., by theeglot
command), otherwisenil
. The function should return a value of any of the forms described above. This allows interaction with the user for determining the program to start and its command-line arguments.
Eglot comes with a fairly complete set of associations of major-modes
to popular language servers predefined. If you need to add server
associations to the default list, use add-to-list
. For
example, if there is a hypothetical language server program
fools
for the language Foo
which is supported by an
Emacs major-mode foo-mode
, you can add it to the alist like
this:
(with-eval-after-load 'eglot (add-to-list 'eglot-server-programs '(foo-mode . ("fools" "--stdio"))))
This will invoke the program fools
with the command-line
argument --stdio in support of editing source files for which
Emacs turns on foo-mode
, and will communicate with the program
via the standard streams. As usual with invoking programs, the
executable file fools should be in one of the directories
mentioned by the exec-path
variable (see Subprocess
Creation in GNU Emacs Lisp Reference Manual), for Eglot to be
able to find it.
Sometimes, multiple servers are acceptable alternatives for handling a
given major-mode. In those cases, you may combine the helper function
eglot-alternatives
with the functional form of
eglot-server-programs
.
(with-eval-after-load 'eglot (add-to-list 'eglot-server-programs `(foo-mode . ,(eglot-alternatives '(("fools" "--stdio") ("phewls" "--fast"))))))
If you have fools
and phewls
installed, the
function produced by eglot-alternatives
will prompt for the
server to use in foo-mode
buffers. Else it will use whichever
is available.
Next: Shutting Down LSP Servers, Previous: Setting Up LSP Servers, Up: Eglot and LSP Servers [Contents][Index]
2.2 Starting Eglot
The most common way to start Eglot is to simply visit a source file of
a given language and use the command M-x eglot. This starts the
language server suitable for the visited file’s major-mode, and
attempts to connect to it. If the connection to the language server
is successful, you will see the [eglot:project]
indicator
on the mode line which reflects the server that was started. If the
server program couldn’t be started or connection to it failed, you
will see an error message; in that case, try to troubleshoot the
problem as described in Troubleshooting Eglot. Once a language
server was successfully started and Eglot connected to it, you can
immediately start using the Emacs features supported by Eglot, as
described in Eglot Features.
A single Eglot session for a certain major-mode usually serves all the buffers under that mode which visit files from the same project, so you don’t need to invoke M-x eglot again when you visit another file from the same project which is edited using the same major-mode. This is because Eglot uses the Emacs project infrastructure, as described in Buffers, Projects, and Eglot, and this knows about files that belong to the same project. Thus, after starting an Eglot session for some buffer, that session is automatically reused when visiting files in the same project with the same major-mode.
Alternatively, you could configure Eglot to start automatically for
one or more major-modes from the respective mode hooks. Here’s an
example for a hypothetical foo-mode
:
(add-hook 'foo-mode-hook 'eglot-ensure)
The function eglot-ensure
will start an Eglot session for each
buffer in which foo-mode
is turned on, if there isn’t already
an Eglot session that handles the buffer. Note that this variant of
starting an Eglot session is non-interactive, so it should be used
only when you are confident that Eglot can be started reliably for any
file which may be visited with the major-mode in question.
When Eglot connects to a language server for the first time in an
Emacs session, it runs the hook eglot-connect-hook
(see Eglot Variables).
Previous: Starting Eglot, Up: Eglot and LSP Servers [Contents][Index]
2.3 Shutting Down LSP Servers
When Eglot is turned on, it arranges for turning itself off automatically if the language server process terminates. Turning off Eglot means that it shuts down the server connection, ceases its management of all the buffers that use the server connection which was terminated, deactivates its minor mode, and restores the original values of the Emacs variables that Eglot changed when it was turned on. See Buffers, Projects, and Eglot, for more details of what Eglot management of a buffer entails.
You can also shut down a language server manually, by using the command M-x eglot-shutdown. This prompts for the server (unless there’s only one connection and it’s used in the current buffer), and then shuts it down. By default, it also kills the server’s events buffer (see Troubleshooting Eglot), but a prefix argument prevents that.
Alternatively, you can customize the variable
eglot-autoshutdown
to a non-nil
value, in which case
Eglot will automatically shut down the language server process when
the last buffer served by that language server is killed. The default
of this variable is nil
, so that visiting another file would
automatically activate Eglot even when the project which started Eglot
with the server no longer has any buffer associated with it. This
default allows you to start a server only once in each Emacs session.
Next: Customizing Eglot, Previous: Eglot and LSP Servers, Up: Eglot [Contents][Index]
3 Using Eglot
This chapter describes in detail the features that Eglot provides and how it does that. It also provides reference sections for Eglot commands and variables.
Next: Buffers, Projects, and Eglot, Up: Using Eglot [Contents][Index]
3.1 Eglot Features
Once Eglot is enabled in a buffer, it uses LSP and the language-server capabilities to activate, enable, and enhance modern IDE features in Emacs. The features themselves are usually provided via other Emacs packages. Here’s the list of the main features that Eglot enables and provides:
Jump to: | A B C D E F I L M O P Q S T U V W X |
---|
Jump to: | A B C D E F I L M O P Q S T U V W X |
---|