From 3e5856b21a83a52dda8c0b3ab541d106d809d625 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Tue, 18 Oct 2022 12:17:51 +0100 Subject: [PATCH] Add new Texinfo manual for the Eglot LSP client * doc/misc/eglot.texi: New file. --- doc/misc/eglot.texi | 1116 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 1116 insertions(+) create mode 100644 doc/misc/eglot.texi diff --git a/doc/misc/eglot.texi b/doc/misc/eglot.texi new file mode 100644 index 00000000000..761964334bb --- /dev/null +++ b/doc/misc/eglot.texi @@ -0,0 +1,1116 @@ +\input texinfo @c -*-texinfo-*- +@c %**start of header +@setfilename ../../eglot.info +@settitle Eglot: The Emacs Client for 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 Language Server Protocol. The name +``Eglot'' is an acronym that stands for ``@emph{E}macs +Poly@emph{glot}''.@footnote{ +A @dfn{polyglot} is a person who is able to use several languages. +} Eglot provides infrastructure and a set of commands for enriching +Emacs source code editing capabilities using the @dfn{Language Server +Protocol} (@acronym{LSP}) -- a standardized communications protocol +between source code editors (such as Emacs) and language servers -- +programs external to Emacs that 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 +functions 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 +Server}. + +@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 Server:: How to configure LSP servers for your needs. +* Starting Eglot:: Ways of starting Eglot for your project. +* Shutting Down LSP Server:: +@end menu + +@node Setting Up LSP Server +@section Setting Up LSP Server +@cindex setting up LSP server for Eglot +@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 @code{eglot-server-programs} variable. + +@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. This variable 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 mode specified in one +of the above forms -- this means the server can support more than one +major mode. + +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 in this variable. 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 +(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. + +@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{server}} 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}. +@c FIXME: Is the mode-line indication just eglot:server, or +@c egloit:serve/project, as described farther down? + +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 Server +@section Shutting Down LSP Server +@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 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 does Eglot +management of a buffer entail. + +@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 are the main features 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 @code{company-mode}, a popular 3rd-party completion package, is +installed, Eglot enhances it by providing completion candidates based +on the language-server analysis of the source code. + +@item +If @code{yasnippet}, a popular package for automatic insertion of code +templates, is installed, and the language server supports +template-based completion, Eglot provides to @code{yasnippet} +completion templates based on the language-server analysis and +knowledge bases. + +@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, +i.e.@: 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 the 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{server}/@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 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 of 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}, also prompt 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 +@c FIXME: When and why would this command be useful? Move to less common? +Reconnect to current language server. + +@item M-x eglot-shutdown +Shut down a language server. This commands 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 arte 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. +@c FIXME: Better description of the need and the effect. +@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 of the Eglot' user options. + +@vtable @code +@item eglot-autoreconnect +This option controls the ability to reconnect automatically to the +language server. The default value 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. The alternative to automatic reconnection is the command +@code{eglot-reconnect} (@pxref{Eglot Commands}). + +@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 controls whether attempts to connect to language servers should +be blocking. The setting is mainly important for slow connections. +The default value is 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 for @code{eglot-connect-timeout} seconds. The +value of @code{nil} or zero means don't block at all. +@c FIXME: the code doesn't use eglot-connect-timeout, it uses a +@c hard-coded value of 30. + +@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{eglot-shutdown} followed by +@kbd{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 Server}. +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 the edits requested by the server. +@c FIXME: Not clear: is the confirmation required for each individual +@c edit, or for as group? for each buffer or just once? And what +@c about on-type reformatting -- does that require confirmation as +@c well (which would be annoying)? + +@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 "") '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 + +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-error}. + +@item +To configure the amount of space taken up by documentation in the +echo area, the 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 the +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 Server}, 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 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 of 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 of 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-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 portion of the +settings contained in this variable to each server for which such +settings were defined in the variable. These settings are +communicated to the server initially (upon establishing the +connection) or when the settings are changed, or in response to the +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 to use these 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 to define 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. That list of parameters is +serialized to JSON by Eglot and sent to the server. For that reason +JSON values @code{true}, @code{false}, and @code{@{@}} should be +represented in the property lists as Lisp symbols @code{t}, +@code{:json-false}, and @code{nil}, 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, +whose server is @command{pylsp}, the other one for Go, with +@command{gopls} as its server (presumably, the project is written in a +combination of these two languages): + +@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; Eglot will use for each server only +the section of the parameters intended for that server + +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 +(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 how to obtain and install 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 -- 2.39.5