emacs/doc/misc/eglot.texi

\input texinfo  @c -*-texinfo-*-
@c %**start of header
@setfilename ../../eglot.info
@settitle Eglot: The Emacs Client for the Language Server Protocol
@include docstyle.texi
@syncodeindex vr cp
@syncodeindex fn cp
@c %**end of header

@copying
This manual is for Eglot, the Emacs LSP client.

Copyright @copyright{} 2022 Free Software Foundation, Inc.

@quotation
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.''
@end quotation
@end copying

@dircategory Emacs misc features
@direntry
* Eglot: (eglot).             Language Server Protocol client for Emacs.
@end direntry

@titlepage
@sp 4
@c The title is printed in a large font.
@center @titlefont{User's Guide}
@sp 1
@center @titlefont{to}
@sp 1
@center @titlefont{Eglot: The Emacs LSP Client}
@ignore
@sp 2
@center release 1.8
@c -release-
@end ignore
@sp 3
@center Jo@~ao T@'avora & Eli Zaretskii
@c -date-

@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@contents

@ifnottex
@node Top
@top Eglot

@cindex LSP
@cindex language server protocol
Eglot is the Emacs client for the @dfn{Language Server Protocol}
(@acronym{LSP}).  The name ``Eglot'' is an acronym that stands for
@ifhtml
``@emph{E}macs Poly@emph{glot}''.
@end ifhtml
@ifnothtml
``Emacs polyGLOT''.
@end ifnothtml
@footnote{
A @dfn{polyglot} is a
person who is able to use several languages.
} 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.

@insertcopying

@menu
* Quick Start::                 For the impatient.
* Eglot and LSP Servers::       How to work with language servers.
* Using Eglot::                 Important Eglot commands and variables.
* Customizing Eglot::           Eglot customization and advanced features.
* Troubleshooting Eglot::       Troubleshooting and reporting bugs.
* GNU Free Documentation License::  The license for this manual.
* Index::
@end menu
@end ifnottex

@node Quick Start
@chapter Quick Start
@cindex 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, @pxref{Eglot and LSP
Servers}.  @xref{Using Eglot}, for detailed description of using Eglot,
and see @ref{Customizing Eglot}, for adapting Eglot to less common use
patterns.

Here's how to start using Eglot with your programming project:

@enumerate
@item
Select and install a language server.

Eglot comes pre-configured with many popular language servers, see the
value of @code{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 of
@code{eglot-server-programs}, as described in @ref{Setting Up LSP
Servers}.

@item
Turn on Eglot for your project.

To start using Eglot for a project, type @kbd{M-x eglot @key{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 (@pxref{Projects,,,
emacs, 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 @ref{Starting
Eglot}.

@item
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 LSP server, such
as @kbd{M-x eglot-rename} (to rename an identifier across the entire
project), @kbd{M-x eglot-format} (to reformat and reindent code), and
some others.  @xref{Eglot Commands}, for the detailed list of Eglot
commands.

@item
That's it!
@end enumerate

@node Eglot and LSP Servers
@chapter Eglot and LSP Servers

This chapter describes how to set up Eglot for your needs, and how to
start it.

@menu
* Setting Up LSP Servers::   How to configure LSP servers for your needs.
* Starting Eglot::              Ways of starting Eglot for your project.
* Shutting Down LSP Servers::
@end menu

@node Setting Up LSP Servers
@section Setting Up LSP Servers
@cindex setting up LSP server for Eglot
@cindex LSP server for Eglot, setting up
@cindex language server for Eglot

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 (@pxref{Processes,,, elisp, 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 @code{eglot-server-programs}.

@defvar 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
@w{@code{(@var{major-mode} . @var{server})}}.

The @var{major-mode} of the alist elements can be either a symbol of
an Emacs major mode or a list of the form @w{@code{(@var{mode}
:language-id @var{id})}}, with @var{mode} being a major-mode symbol
and @var{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,
@var{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 @var{server} part of the alist elements can be one of the
following:

@table @code
@item (@var{program} @var{args}@dots{})
This says to invoke @var{program} with zero or more arguments
@var{args}; the program is expected to communicate with Emacs via the
standard input and standard output streams.

@item (@var{program} @var{args}@dots{} :initializationOptions @var{options}@dots{})
Like above, but with @var{options} specifying the options to be
used for constructing the @samp{initializationOptions} JSON object for
the server.  @var{options} can also be a function of one argument, in
which case it will be called with the server instance as the argument,
and should return the JSON object to use for initialization.

@item (@var{host} @var{port} @var{args}@dots{})
Here @var{host} is a string and @var{port} is a positive integer
specifying a TCP connection to a remote server.  The @var{args} are
passed to @code{open-network-stream}, e.g.@: if the connection needs
to use encryption or other non-default parameters (@pxref{Network,,,
elisp, GNU Emacs Lisp Reference Manual}).

@item (@var{program} @var{args}@dots{} :autoport @var{moreargs}@dots{})
@var{program} is started with a command line constructed from
@var{args} followed by an available server port and the rest of
arguments in @var{moreargs}; Eglot then establishes a TCP connection
with the server via that port on the local host.

@item @var{function}
This should be a function of a single argument: non-@code{nil} if the
connection was requested interactively (e.g., by the @code{eglot}
command), otherwise @code{nil}.  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.
@end table

@end defvar

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 @code{add-to-list}.  For
example, if there is a hypothetical language server program
@command{fools} for the language @code{Foo} which is supported by an
Emacs major-mode @code{foo-mode}, you can add it to the alist like
this:

@lisp
(with-eval-after-load 'eglot
  (add-to-list 'eglot-server-programs
               '(foo-mode . ("fools" "--stdio"))))
@end lisp

This will invoke the program @command{fools} with the command-line
argument @option{--stdio} in support of editing source files for which
Emacs turns on @code{foo-mode}, and will communicate with the program
via the standard streams.  As usual with invoking programs, the
executable file @file{fools} should be in one of the directories
mentioned by the @code{exec-path} variable (@pxref{Subprocess
Creation,,, elisp, 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
@code{eglot-alternatives} with the functional form of
@code{eglot-server-programs}.

@lisp
(with-eval-after-load 'eglot
  (add-to-list 'eglot-server-programs
               `(foo-mode . ,(eglot-alternatives
                               '(("fools" "--stdio")
                                 ("phewls" "--fast"))))))
@end lisp

If you have @command{fools} and @command{phewls} installed, the
function produced by @code{eglot-alternatives} will prompt for the
server to use in @code{foo-mode} buffers.  Else it will use whichever
is available.

@node Starting Eglot
@section Starting Eglot
@cindex starting Eglot
@cindex activating Eglot for a project

@findex eglot
The most common way to start Eglot is to simply visit a source file of
a given language and use the command @kbd{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 @code{[eglot:@var{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 @ref{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 @ref{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 @kbd{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 @ref{Eglot and Buffers}, 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.

@findex eglot-ensure
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 @code{foo-mode}:

@lisp
 (add-hook 'foo-mode-hook 'eglot-ensure)
@end lisp

@noindent
The function @code{eglot-ensure} will start an Eglot session for each
buffer in which @code{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 @code{eglot-connect-hook}
(@pxref{Eglot Variables}).

@node Shutting Down LSP Servers
@section Shutting Down LSP Servers
@cindex shutting down LSP server

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.  @xref{Eglot and Buffers}, for more details of what Eglot
management of a buffer entails.

@findex eglot-shutdown
You can also shut down a language server manually, by using the
command @kbd{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 (@pxref{Troubleshooting Eglot}), but a prefix argument prevents
that.

Alternatively, you can customize the variable
@code{eglot-autoshutdown} to a non-@code{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 @code{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.

@node Using Eglot
@chapter 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.

@menu
* Eglot Features::
* Eglot and Buffers::
* Eglot Commands::
* Eglot Variables::
@end menu

@node Eglot Features
@section Eglot Features
@cindex features in buffers supported by Eglot

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:

@itemize @bullet
@item
At-point documentation: when point is at or near a symbol or an
identifier, the information about the symbol/identifier, such as the
signature of a function or class method and server-generated
diagnostics, is made available via the ElDoc package (@pxref{Lisp
Doc,,, emacs, GNU Emacs Manual}).  This allows major modes to provide
extensive help and documentation about the program identifiers.

@item
On-the-fly diagnostic annotations with server-suggested fixes, via the
Flymake package (@pxref{Top,,, flymake, GNU Flymake manual}).  This
improves and enhances the Flymake diagnostics, replacing the other
Flymake backends.

@item
Finding definitions and uses of identifiers, via Xref (@pxref{Xref,,,
emacs, GNU Emacs Manual}).  Eglot provides a backend for the Xref
capabilities which uses the language-server understanding of the
program source.  In particular, it eliminates the need to generate
tags tables (@pxref{Tags tables,,, emacs, GNU Emacs Manual}) for
languages which are only supported by the @code{etags} backend.

@item
Buffer navigation by name of function, class, method, etc., via Imenu
(@pxref{Imenu,,, emacs, GNU Emacs Manual}).  Eglot provides its own
variant of @code{imenu-create-index-function}, which generates the
index for the buffer based on language-server program source analysis.

@item
Enhanced completion of symbol at point by the
@code{completion-at-point} command (@pxref{Symbol Completion,,, emacs,
GNU Emacs Manual}).  This uses the language-server's parser data for
the completion candidates.

@item
Automatic reformatting of source code as you type it.  This is similar
to what the @code{eglot-format} command does (see below), but is
activated automatically as you type.

@item
If a completion package such as @code{company-mode}, a popular
third-party completion package (or any other completion package), is
installed, Eglot enhances it by providing completion candidates based
on the language-server analysis of the source code.
(@code{company-mode} can be installed from GNU ELPA.)

@item
If @code{yasnippet}, a popular third-party package for automatic
insertion of code templates (snippets), is installed, and the language
server supports snippet completion candidates, Eglot arranges for the
completion package to instantiate these snippets using
@code{yasnippet}.  (@code{yasnippet} can be installed from GNU ELPA.)

@item
If the popular third-party package @code{markdown-mode} is installed,
and the server provides at-point documentation formatted as Markdown
in addition to plain text, Eglot arranges for the ElDoc package to
enrich this text with fontifications and other nice formatting before
displaying it to the user.  This makes the documentation shown by
ElDoc look nicer on display.

@item
In addition to enabling and enhancing other features and packages,
Eglot also provides a small number of user commands based directly on
the capabilities of language servers.  These commands are:

@table @kbd
@item M-x eglot-rename
This prompts for a new name for the symbol at point, and then modifies
all the project source files to rename the symbol to the new name,
based on editing data received from the language-server.  @xref{Eglot
and Buffers}, for the details of how project files are defined.

@item M-x eglot-format
This reformats and prettifies the current active region according to
source formatting rules of the language-server.  If the region is not
active, it reformats the entire buffer instead.

@item M-x eglot-format-buffer
This reformats and prettifies the current buffer according to source
formatting rules of the language-server.

@cindex code actions
@item M-x eglot-code-actions
@itemx M-x eglot-code-action-organize-imports
@itemx M-x eglot-code-action-quickfix
@itemx M-x eglot-code-action-extract
@itemx M-x eglot-code-action-inline
@itemx M-x eglot-code-action-rewrite
These command allow you to invoke the so-called @dfn{code actions}:
requests for the language-server to provide editing commands for
various code fixes, typically either to fix an error diagnostic or to
beautify/refactor code.  For example,
@code{eglot-code-action-organize-imports} rearranges the program
@dfn{imports}---declarations of modules whose capabilities the program
uses.  These commands affect all the files that belong to the
project.  The command @kbd{M-x eglot-code-actions} will pop up a menu
of code applicable actions at point.
@end table

@end itemize

Not all servers support the full set of LSP capabilities, but most of
them support enough to enable the basic set of features mentioned
above.  Conversely, some servers offer capabilities for which no
equivalent Emacs package exists yet, and so Eglot cannot (yet) expose
these capabilities to Emacs users.

@node Eglot and Buffers
@section Buffers, Projects, and Eglot
@cindex buffers managed by Eglot
@cindex projects and Eglot

@cindex workspace
One of the main strong points of using a language server is that a
language server has a broad view of the program: it considers more
than just the single source file you are editing.  Ideally, the
language server should know about all the source files of your program
which are written in the language supported by the server.  In the
language-server parlance, the set of the source files of a program is
known as a @dfn{workspace}.  The Emacs equivalent of a workspace is a
@dfn{project} (@pxref{Projects,,, emacs, GNU Emacs Manual}).  Eglot
fully supports Emacs projects, and considers the file in whose buffer
Eglot is turned on as belonging to a project.  In the simplest case,
that file is the entire project, i.e.@: your project consists of a
single file.  But there are other more complex projects:

@itemize @bullet
@item
A single-directory project: several source files in a single common
directory.

@item
A VC project: source files in a directory hierarchy under some VCS,
e.g.@: a VCS repository (@pxref{Version Control,,, emacs, GNU Emacs
Manual}).

@item
An EDE project: source files in a directory hierarchy managed via the
Emacs Development Environment (@pxref{EDE,,, emacs, GNU Emacs
Manual}).
@end itemize

Eglot uses Emacs's project management infrastructure to figure out
which files and buffers belong to what project, so any kind of project
supported by that infrastructure is automatically supported by Eglot.

When Eglot starts a server program, it does so in the project's root
directory, which is usually the top-level directory of the project's
directory hierarchy.  This ensures the language server has the same
comprehensive view of the project's files as you do.

For example, if you visit the file @file{~/projects/fooey/lib/x.foo}
and @file{x.foo} belongs to a project rooted at
@file{~/projects/fooey} (perhaps because a @file{.git} directory
exists there), then @kbd{M-x eglot} causes the server program to start
with that root as the current working directory.  The server then will
analyze not only the file @file{lib/x.foo} you visited, but likely
also all the other @file{*.foo} files under the
@file{~/projects/fooey} directory.

In some cases, additional information specific to a given project will
need to be provided to the language server when starting it.  The
variable @code{eglot-workspace-configuration} (@pxref{Customizing
Eglot}) exists for that purpose.  It specifies the parameters and
their values to communicate to each language server which needs that.

When Eglot is active for a project, it performs several background
activities on behalf of the project and its buffers:

@itemize @bullet
@cindex mode-line indication of language server
@cindex mouse clicks on mode-line, and Eglot
@vindex eglot-menu
@item
All of the project's file-visiting buffers under the same major-mode
are served by a single language-server connection.  (If the project
uses several programming languages, there will usually be a separate
server connection for each group of files written in the same language
and using the same Emacs major-mode.)  Eglot adds the
@samp{[eglot:@var{project}]} indication to the mode line of
each such buffer, where @var{server} is the name of the server and
@var{project} identifies the project by its root directory.  Clicking
the mouse on the Eglot mode-line indication activates a menu with
server-specific items.

@item
For each buffer in which Eglot is active, it notifies the language
server that Eglot is @dfn{managing} the file visited by that buffer.
This tells the language server that the file's contents on disk may no
longer be up-to-date due to unsaved edits.  Eglot reports to the
server any changes in the text of each managed buffer, to make the
server aware of unsaved changes.  This includes your editing of the
buffer and also changes done automatically by other Emacs features and
commands.  Killing a buffer relinquishes its management by Eglot and
notifies the server that the file on disk is up-to-date.

@vindex eglot-managed-mode-hook
@vindex eglot-managed-p
@item
Eglot turns on a special minor mode in each buffer it manages.  This
minor mode ensures the server is notified about files Eglot manages,
and also arranges for other Emacs features supported by Eglot
(@pxref{Eglot Features}) to receive information from the language
server, by changing the settings of these features.  Unlike other
minor-modes, this special minor mode is not activated manually by the
user, but automatically, as the result of starting an Eglot session
for the buffer.  However, this minor mode provides a hook variable
@code{eglot-managed-mode-hook} that can be used to customize the Eglot
management of the buffer.  This hook is run both when the minor mode
is turned on and when it's turned off; use the variable
@code{eglot-managed-p} to tell if current buffer is still being
managed or not.  When Eglot stops managing the buffer, this minor mode
is turned off, and all the settings that Eglot changed are restored to
their original values.

@item
When you visit a file under the same project, whether an existing or a
new file, its buffer is automatically added to the set of buffers
managed by Eglot, and the server which supports the buffer's
major-mode is notified about that.  Thus, visiting a non-existent file
@file{/home/joe/projects/fooey/lib/y.foo} in the above example will
notify the server of the @file{*.foo} files' language that a new file
was added to the project, even before the file appears on disk.  The
special Eglot minor mode is also turned on automatically in the buffer
visiting the file.
@end itemize

@node Eglot Commands
@section Eglot Commands
@cindex commands, Eglot

This section provides a reference for the most commonly used Eglot
commands:

@ftable @code
@item M-x eglot
This command adds the current buffer and the file it visits to the
group of buffers and files managed by Eglot on behalf of a suitable
language server.  If a language server for the buffer's
@code{major-mode} (@pxref{Major Modes,,, emacs, GNU Emacs Manual}) is
not yet running, it will be started; otherwise the buffer and its file
will be added to those managed by an existing server session.

The command attempts to figure out the buffer's major mode and the
suitable language server; in case it fails, it might prompt for the
major mode to use and for the server program to start.  If invoked
with @kbd{C-u}, it always prompts for the server program, and if
invoked with @kbd{C-u C-u}, it also prompts for the major mode.

If the language server is successfully started and contacted, this
command arranges for any other buffers belonging to the same project
and using the same major mode to use the same language-server session.
That includes any buffers created by visiting files after this command
succeeds to connect to a language server.

All the Emacs features that are capable of using Eglot services
(@pxref{Eglot Features}) are automatically configured by this command
to start using the language server via Eglot.  To customize which
Emacs features will be configured to use Eglot, use the
@code{eglot-stay-out-of} option (@pxref{Customizing Eglot}).

@item M-x eglot-reconnect
This command shuts down the current connection to the language
server and immediately restarts it using the same options used
originally.  This can sometimes be useful to unclog a partially
malfunctioning server connection.

@item M-x eglot-shutdown
This command shuts down a language server.  It prompts for a language
server to shut down (unless there's only one server session, and it
manages the current buffer).  Then the command shuts down the server
and stops managing the buffers the server was used for.  Emacs
features (@pxref{Eglot Features}) that Eglot configured to work with
the language server are restored back to their original configuration.

Normally, this command kills the buffers used for communicating with
the language server, but if invoked with a prefix argument @kbd{C-u},
the command doesn't kill those buffers, allowing them to be used for
diagnostics and problem reporting (@pxref{Troubleshooting Eglot}).

@item M-x eglot-shutdown-all
This command shuts down all the language servers active in the current
Emacs session.  As with @code{eglot-shutdown}, invoking this command
with a prefix argument avoids killing the buffers used for
communications with the language servers.

@item M-x eglot-rename
This command renames the program symbol (a.k.a.@: @dfn{identifier}) at
point to another name.  It prompts for the new name of the symbol, and
then modifies all the files in the project which are managed by the
language server of the current buffer to implement the renaming.

@item M-x eglot-format
This command reformats the active region according to the
language-server rules.  If no region is active, it reformats the
entire current buffer.

@item M-x eglot-format-buffer
This command reformats the current buffer, in the same manner as
@code{eglot-format} does.

@item M-x eglot-code-actions
@itemx mouse-1
This command asks the server for any @dfn{code actions} applicable at
point.  It can also be invoked by @kbd{mouse-1} clicking on
diagnostics provided by the server.

@item M-x eglot-code-action-organize-imports
@itemx M-x eglot-code-action-quickfix
@itemx M-x eglot-code-action-extract
@itemx M-x eglot-code-action-inline
@itemx M-x eglot-code-action-rewrite
These commands invoke specific code actions supported by the language
server.
@c FIXME: Need more detailed description of each action.
@end ftable

The following Eglot commands are used less commonly, mostly for
diagnostic and troubleshooting purposes:

@ftable @code
@item M-x eglot-events-buffer
This command pops up the events buffer used for communication with the
language server of the current buffer.

@item M-x eglot-stderr-buffer
This command pops up the buffer with the debug info printed by the
language server to its standard error stream.

@item M-x eglot-forget-pending-continuations
Forget pending requests for the server of the current buffer.
@c FIXME: Better description of the need.

@item M-x eglot-signal-didChangeConfiguration
This command updates the language server configuration according to
the current value of the variable @code{eglot-workspace-configuration}
(@pxref{Customizing Eglot}).

@item M-x eglot-clear-status
Clear the last JSONRPC error for the server of the current buffer.
Eglot keeps track of erroneous situations encountered by the server in
its mode-line indication so that the user may inspect the
communication leading up to it (@pxref{Troubleshooting Eglot}).  If
the situation is deemed uninteresting or temporary, this command can
be used to ``forget'' the error.  Note that the command @code{M-x
eglot-reconnect} can sometimes be used to unclog a temporarily
malfunctioning server.
@end ftable

As described in @ref{Eglot Features} most features associated with
Eglot are actually provided by other Emacs packages and features, and
Eglot only enhances them by allowing them to use the information
coming from the language servers.  For completeness, here's the list
of commands of those other packages that are very commonly used in
Eglot-managed buffers:

@c Not @ftable, because the index entries should mention Eglot
@table @code
@cindex eldoc, and Eglot
@cindex documentation using Eglot
@item M-x eldoc
Ask the ElDoc system for help at point.

@cindex flymake, and Eglot
@cindex on-the-fly diagnostics using Eglot
@item M-x flymake-show-buffer-diagnostics
Ask Flymake system to display diagnostics for the current buffer.

@item M-x flymake-show-project-diagnostics
Ask Flymake to list diagnostics for all the files in the current
project.

@cindex xref, and Eglot
@cindex finding definitions of identifiers using Eglot
@item M-x xref-find-definitions
Ask Xref to go the definition of the identifier at point.

@cindex imenu navigation using Eglot
@item M-x imenu
Let the user navigate the program source code using buffer index,
categorizing program elements by syntactic class (class, method,
variable, etc.) and offering completion.

@cindex symbol completion using Eglot
@item M-x completion-at-point
Request completion of the symbol at point.
@end table

@node Eglot Variables
@section Eglot Variables
@cindex variables, Eglot

This section provides a reference for the Eglot user options.

@vtable @code
@item eglot-autoreconnect
This option controls the ability to reconnect automatically to the
language server when Eglot detects that the server process terminated
unexpectedly.  The default value @code{3} means to attempt reconnection only
if the previous successful connection lasted for more than that number
of seconds; a different positive value changes the minimal length of
the connection to trigger reconnection.  A value of @code{t} means
always reconnect automatically, and @code{nil} means never reconnect
(in which case you will need to reconnect manually using @kbd{M-x
eglot}).

@item eglot-connect-timeout
This specifies the number of seconds before connection attempt to a
language server times out.  The value of @code{nil} means never time
out.  The default is 30 seconds.

@item eglot-sync-connect
This setting is mainly important for connections which are slow to
establish.  Whereas the variable @code{eglot-connect-timeout} controls
how long to wait for, this variable controls whether to block Emacs's
user interface while waiting.  The default value is @code{3}; a positive
value means block for that many seconds, then wait for the connection
in the background.  The value of @code{t} means block during the whole
waiting period.  The value of @code{nil} or @code{0} means don't block at
all during the waiting period.

@item eglot-events-buffer-size
This determines the size of the Eglot events buffer.  @xref{Eglot
Commands, eglot-events-buffer}, for how to display that buffer.  If
the value is changed, for it to take effect the connection should be
restarted using @kbd{M-x eglot-reconnect}.
@c FIXME: Shouldn't the defcustom do this by itself using the :set
@c attribute?
@xref{Troubleshooting Eglot}, for when this could be useful.

@item eglot-autoshutdown
If this is non-@code{nil}, Eglot shuts down a language server when the
last buffer managed by it is killed.  @xref{Shutting Down LSP Servers}.
The default is @code{nil}; if you want to shut down a server, use
@kbd{M-x eglot-shutdown} (@pxref{Eglot Commands}).

@item eglot-confirm-server-initiated-edits
Various Eglot commands and code actions result in the language server
sending editing commands to Emacs.  If this option's value is
non-@code{nil} (the default), Eglot will ask for confirmation before
performing edits initiated by the server or edits whose scope affects
buffers other than the one where the user initiated the request.

@item eglot-ignored-server-capabilities
This variable's value is a list of language server capabilities that
Eglot should not use.  The default is @code{nil}: Eglot uses all of
the capabilities supported by each server.

@item eglot-extend-to-xref
If this is non-@code{nil}, and @kbd{M-.}
(@code{xref-find-definitions}) lands you in a file outside of your
project, such as a system-installed library or header file,
transiently consider that file as managed by the same language server.
That file is still outside your project (i.e. @code{project-find-file}
won't find it), but Eglot and the server will consider it to be part
of the workspace.  The default is @code{nil}.

@item eglot-mode-map
This variable is the keymap for binding Eglot-related command.  It is
in effect only as long as the buffer is managed by Eglot.  By default,
it is empty, with the single exception: @kbd{C-h .} is remapped to
invoke @code{eldoc-doc-buffer}.  You can bind additional commands in
this map.  For example:

@lisp
  (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)
@end lisp

@end vtable

Additional variables, which are relevant for customizing the server
connections, are documented in @ref{Customizing Eglot}.

@node Customizing Eglot
@chapter Customizing Eglot
@cindex customizing Eglot

Eglot itself has a relatively small number of customization options.
A large part of customizing Eglot to your needs and preferences should
actually be done via options of the Emacs packages and features which
Eglot supports and enhances (@pxref{Eglot Features}).  For example:

@itemize @bullet
@item
To configure the face used for server-derived errors and warnings,
customize the Flymake faces @code{flymake-error} and
@code{flymake-warning}.

@item
To configure the amount of space taken up by documentation in the
echo area, customize the ElDoc variable
@code{eldoc-echo-area-use-multiline-p}.

@item
To completely change how ElDoc displays the at-point documentation
destination, customize the ElDoc variable
@code{eldoc-display-functions}.
@end itemize

For this reason, this manual describes only how to customize
Eglot's own operation, which mainly has to do with the server
connections and the server features to be used by Eglot.

@c @table, not @vtable, because some of the variables are indexed
@c elsewhere
@table @code
@item eglot-server-programs
This variable determines which language server to start for each
supported major mode, and how to invoke that server's program.
@xref{Setting Up LSP Servers}, for the details.

@vindex eglot-strict-mode
@item eglot-strict-mode
This is @code{nil} by default, meaning that Eglot is generally lenient
about non-conforming servers.  If you need to debug a server, set this
to @w{@code{(disallow-non-standard-keys enforce-required-keys)}}.

@vindex eglot-server-initialized-hook
@item eglot-server-initialized-hook
A hook run after the server object is successfully initialized.

@vindex eglot-connect-hook
@item eglot-connect-hook
A hook run after connection to the server is successfully
established.  @xref{Starting Eglot}.

@item eglot-managed-mode-hook
A hook run after Eglot started or stopped managing a buffer.
@xref{Eglot and Buffers}, for details of its usage.

@vindex eglot-stay-out-of
@item eglot-stay-out-of
This variable's value lists Emacs features that Eglot shouldn't
automatically try to manage on the user's behalf.  It is useful, for
example, when you need to use non-LSP Flymake or Company back-ends.
To have Eglot stay away from some Emacs feature, add that feature's
symbol or a regexp that will match a symbol's name to the list: for
example, the symbol @code{xref} to leave Xref alone, or the string
@samp{company} to stay away from your Company customizations.  Here's an
example:

@lisp
(add-to-list 'eglot-stay-out-of 'flymake)
@end lisp

Note that you can still configure the excluded Emacs features manually
to use Eglot in your @code{eglot-managed-mode-hook} or via some other
mechanism.

@vindex eglot-report-progress
@cindex progress
@item eglot-report-progress
Set this variable to true if you'd like progress notifications coming
from the LSP server to be handled as Emacs's progress reporting
facilities.

@vindex eglot-workspace-configuration
@cindex server workspace configuration
@item eglot-workspace-configuration
This variable is meant to be set in the @file{.dir-locals.el} file, to
provide per-project settings, as described below in more detail.
@end table

Some language servers need to know project-specific settings, which
the LSP calls @dfn{workspace configuration}.  Eglot allows such fine
tuning of per-project settings via the variable
@code{eglot-workspace-configuration}.  Eglot sends the settings in
this variable to each server, and each server applies the portion of the
settings relevant to it and ignores the rest.  These settings are
communicated to the server initially (upon establishing the
connection) or when the settings are changed, or in response to a
configuration request from the server.

In many cases, servers can be configured globally using a
configuration file in the user's home directory or in the project
directory, which the language server reads.  For example, the
@command{pylsp} server for Python reads the file
@file{~/.config/pycodestyle} and the @command{clangd} server reads the
file @file{.clangd} anywhere in the current project's directory tree.
If possible, we recommend using those configuration files that are
independent of Eglot and Emacs; they have the advantage that they will
work with other LSP clients as well.

If you do need to provide Emacs-specific configuration for a language
server, we recommend defining the appropriate value in the
@file{.dir-locals.el} file in the project's directory.  The value of
this variable should be a property list of the following format:

@lisp
 (:@var{server} @var{plist}@dots{})
@end lisp

@noindent
Here @code{:@var{server}} identifies a particular language server and
@var{plist} is the corresponding keyword-value property list of one or
more parameter settings for that server, serialized by Eglot as a JSON
object.  @var{plist} may be arbitrarily complex, generally containing
other keyword-value property sublists corresponding to JSON subobjects.
The JSON values @code{true}, @code{false}, @code{null} and @code{@{@}}
are represented by the Lisp values @code{t}, @code{:json-false},
@code{nil}, and @code{eglot-@{@}}, respectively.

@findex eglot-show-workspace-configuration
When experimenting with workspace settings, you can use the command
@kbd{M-x eglot-show-workspace-configuration} to inspect and debug the
JSON value to be sent to the server.  This helper command works even
before actually connecting to the server.

Here's an example of defining the workspace-configuration settings for
a project that uses two different language servers, one for Python,
the other one for Go (presumably, the project is written in a
combination of these two languages).  The server for Python in this
case is @command{pylsp}, the server for Go is @command{gopls}.  The
value of @code{eglot-workspace-configuration} in this case should be:

@lisp
((python-mode
  . ((eglot-workspace-configuration
      . (:pylsp (:plugins (:jedi_completion (:include_params t
                                             :fuzzy t)
                           :pylint (:enabled :json-false)))))))
 (go-mode
  . ((eglot-workspace-configuration
      . (:gopls (:usePlaceholders t))))))
@end lisp

@noindent
This should go into the @file{.dir-locals.el} file in the project's
root directory.  It sets up the value of
@code{eglot-workspace-configuration} separately for each major mode.

Alternatively, the same configuration could be defined as follows:

@lisp
((nil
  . ((eglot-workspace-configuration
      . (:pylsp (:plugins (:jedi_completion (:include_params t
                                             :fuzzy t)
                           :pylint (:enabled :json-false)))
         :gopls (:usePlaceholders t))))))
@end lisp

This is an equivalent setup which sets the value for all the
major-modes inside the project; each server will use only the section
of the parameters intended for that server, and ignore the rest.

As yet another alternative, you can set the value of
@code{eglot-workspace-configuration} programmatically, via the
@code{dir-locals-set-class-variables} function, @pxref{Directory Local
Variables,,, elisp, GNU Emacs Lisp Reference Manual}.

Finally, if one needs to determine the workspace configuration based
on some dynamic context, @code{eglot-workspace-configuration} can be
set to a function.  The function is called with the
@code{eglot-lsp-server} instance of the connected server (if any) and
with @code{default-directory} set to the root of the project.  The
function should return a value of the form described above.

Some servers need special hand-holding to operate correctly.  If your
server has some quirks or non-conformity, it's possible to extend
Eglot via Elisp to adapt to it, by defining a suitable
@code{eglot-initialization-options} method via @code{cl-defmethod}
(@pxref{Generic Functions,,, elisp, GNU Emacs Lisp Reference Manual}).

Here's an example:

@lisp
(require 'eglot)

(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)))
@end lisp

@noindent
See the doc string of @code{eglot-initialization-options} for more
details.
@c FIXME: The doc string of eglot-initialization-options should be
@c enhanced and extended.

@node Troubleshooting Eglot
@chapter Troubleshooting Eglot
@cindex troubleshooting Eglot

This section documents commands and variables that can be used to
troubleshoot Eglot problems.  It also provides guidelines for
reporting Eglot bugs in a way that facilitates their resolution.

When you encounter problems with Eglot, try first using the commands
@kbd{M-x eglot-events-server} and @kbd{M-x eglot-stderr-buffer}.  They
pop up special buffers that can be used to inspect the communications
between the Eglot and language server.  In many cases, this will
indicate the problems or at least provide a hint.

A common and easy-to-fix cause of performance problems is the length
of these two buffers.  If Eglot is operating correctly but slowly,
customize the variable @code{eglot-events-buffer-size} (@pxref{Eglot
Variables}) to limit logging, and thus speed things up.

If you need to report an Eglot bug, please keep in mind that, because
there are so many variables involved, it is generally both very
@emph{difficult} and @emph{absolutely essential} to reproduce bugs
exactly as they happened to you, the user.  Therefore, every bug
report should include:

@enumerate
@item
The transcript of events obtained from the buffer popped up by
@kbd{M-x eglot-events-buffer}.  If the transcript can be narrowed down
to show the problematic exchange, so much the better.  This is
invaluable for the investigation and reproduction of the problem.

@item
If Emacs signaled an error (an error message was seen or heard), make
sure to repeat the process after toggling @code{debug-on-error} on
(via @kbd{M-x toggle-debug-on-error}).  This normally produces a
backtrace of the error that should also be attached to the bug report.

@item
An explanation of how to obtain, install, and configure the language
server you used.  If possible, try to replicate the problem with the
C/C@t{++} or Python servers, as these are very easy to install.

@item
A description of how to setup the @emph{minimal} project (one or two
files and their contents) where the problem happens.

@item
A recipe to replicate the problem with @emph{a clean Emacs run}.  This
means @kbd{emacs -Q} invocation or a very minimal (no more that 10
lines) @file{.emacs} initialization file.  @code{eglot-ensure} and
@code{use-package} calls are generally @emph{not} needed.

@item
Make sure to double check all the above elements and re-run the
recipe to see that the problem is reproducible.
@end enumerate

Please keep in mind that some problems reported against Eglot may
actually be bugs in the language server or the Emacs feature/package
that used Eglot to communicate with the language server.

@node GNU Free Documentation License
@appendix GNU Free Documentation License
@include doclicense.texi

@node Index
@unnumbered Index
@printindex cp

@bye