From 9e4b626f7eea788966a1ad92d4af76f8b0a2573f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jo=C3=A3o=20T=C3=A1vora?= Date: Tue, 28 Jan 2025 10:37:41 +0000 Subject: [PATCH] Eglot: restructure and overhaul documentation * doc/misc/eglot.texi (Starting Eglot): Tweak. (Using Eglot): Remove link to 'Eglot Variables'. (Eglot Features): Rework. (Eglot and Buffers): Rework. (Eglot Commands): Rework. (Customizing Eglot): New chapter. (Customization Variables): Now contains what 'Eglot Variables' used to contain. (Other Variables): New section. (More Customization): New section. (...elsewhere...): Apply 'fill-paragraph'. --- doc/misc/eglot.texi | 1141 +++++++++++++++++++++++-------------------- 1 file changed, 612 insertions(+), 529 deletions(-) diff --git a/doc/misc/eglot.texi b/doc/misc/eglot.texi index d7bd78e134b..df24cf2a1dc 100644 --- a/doc/misc/eglot.texi +++ b/doc/misc/eglot.texi @@ -17,8 +17,8 @@ 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''. +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.'' @@ -68,22 +68,20 @@ Eglot is the Emacs client for the @dfn{Language Server Protocol} @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 +@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 +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. +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 @@ -111,8 +109,8 @@ This manual documents how to configure, use, and customize Eglot. @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 +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. @@ -137,19 +135,19 @@ Servers} or have Eglot prompt you about it (@pxref{Eglot Commands}). @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 @dfn{managing} file-visiting buffers -related to that programming language. This includes files that are -already visited at the time the @code{eglot} command is invoked, as -well as any files visited after this invocation. +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 @dfn{managing} file-visiting buffers related +to that programming language. This includes files that are already +visited at the time the @code{eglot} command is invoked, as well as any +files visited after this invocation. 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. +(@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. There are alternate ways of starting Eglot; see @ref{Starting Eglot} for details. @@ -157,13 +155,12 @@ for details. @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 language 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. +Most Eglot facilities are integrated into Emacs features, such as ElDoc, +Flymake, Xref, and Imenu. However, Eglot also provides commands of its +own, mainly to perform tasks by the language server, such as @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! @@ -188,10 +185,10 @@ start it. @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. +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 @@ -211,19 +208,17 @@ 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{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: +The @var{server} part of the alist elements can be one of the following: @table @code @item (@var{program} @var{args}@dots{}) @@ -232,42 +227,40 @@ This says to invoke @var{program} with zero or more arguments standard input and standard output streams. @item (@var{program} @var{args}@dots{} :initializationOptions @var{options}@dots{}) -@var{program} is invoked with @var{args} but @var{options} specifies -how to construct the @samp{:initializationOptions} JSON object to pass -the server on during the LSP handshake (@pxref{Advanced server +@var{program} is invoked with @var{args} but @var{options} specifies how +to construct the @samp{:initializationOptions} JSON object to pass the +server on during the LSP handshake (@pxref{Advanced server configuration}). @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}). +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. +@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. +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: +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 @@ -297,10 +290,9 @@ given major-mode. In those cases, you may combine the helper function ("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. +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 @@ -308,33 +300,33 @@ is available. @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}. +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. +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}: +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) @@ -342,21 +334,21 @@ example for a hypothetical @code{foo-mode}: @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. +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. -Note that it's often difficult to establish this confidence fully, so -it may be wise to use the interactive command @code{eglot} instead. -You only need to invoke it once per project, as all other files -visited within the same project will automatically be managed with no -further user intervention needed. +Note that it's often difficult to establish this confidence fully, so it +may be wise to use the interactive command @code{eglot} instead. You +only need to invoke it once per project, as all other files visited +within the same project will automatically be managed with no further +user intervention needed. -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}). +When Eglot connects to a language server for the first time in an Emacs +session, it runs the hook @code{eglot-connect-hook} (@pxref{Other +Variables}). @node Shutting Down LSP Servers @section Shutting Down LSP Servers @@ -366,27 +358,26 @@ 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. +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. +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. +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 @@ -399,15 +390,14 @@ commands and variables. * Eglot Features:: * Eglot and Buffers:: * Eglot Commands:: -* Eglot Variables:: @end menu @node Eglot Features @section Eglot Features @cindex features in buffers supported by Eglot -While Eglot is enabled in a buffer, it is said to be @dfn{managing} -it, using LSP and the specific capabilities of the language server to +While Eglot is enabled in a buffer, it is said to be @dfn{managing} it, +using LSP and the specific capabilities of the language server to activate and enhance modern IDE features in Emacs. Some of these features are provided via other Emacs packages, and some via Eglot directly (@pxref{Eglot Commands}). @@ -416,79 +406,82 @@ Here's an overview of the main features that Eglot 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{Programming Language Doc,,, emacs, GNU Emacs Manual}). This -allows major modes to provide extensive help and documentation about -the program identifiers. +At-point documentation: when point is near a symbol or an identifier, +information about the identifier's significance in the program (its +function or method signature, its type, its custom documentation string, +etc.) is made available via the ElDoc package (@pxref{Programming +Language Doc,,, emacs, GNU Emacs Manual}). @item On-the-fly diagnostic annotations, via the Flymake package -(@pxref{Top,,, flymake, GNU Flymake manual}). Eglot's Flymake backend +(@pxref{Top,,, Flymake, GNU Flymake manual}). Eglot's Flymake backend replaces other Flymake backends while it is managing a buffer, and -enhances diagnostics with interactive server-suggested fixes -(so-called @dfn{code actions}, @pxref{Eglot Commands}) +enhances diagnostics with interactive server-suggested fixes (so-called +@dfn{code actions}, @pxref{Eglot Commands}). @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. +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. +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. +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. +On-the-fly succinct informative annotations, so-called @dfn{inlay +hints}. Eglot adds special intangible text nearby certain identifiers, +be it the type of a variable, or the name of a formal parameter in a +function call. @xref{Eglot Commands} and the +@code{eglot-inlay-hints-mode} minor mode. @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.) +Code reformatting via the @code{eglot-format} and related commands +(@pxref{Eglot Commands}). Automatic reformatting of source code is also +supported and is activated automatically as you type. @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.) +If a completion package such as the Company package (a popular +third-party completion package providing @code{company-mode}), is +installed, Eglot enhances it by providing completion candidates based on +the language-server analysis of the source code. (Company can be +installed from GNU ELPA.) + +@item +If 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 YASnippet. +(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. +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 number of user commands based on the -capabilities of language servers. Examples include renaming symbols -with @kbd{eglot-rename} and asking to automatically correct problems -with @kbd{eglot-code-actions}. @xref{Eglot Commands}. +In addition to enabling and enhancing other features and packages, Eglot +also provides a number of user commands based on the capabilities of +language servers. Examples include renaming symbols with +@kbd{eglot-rename} and asking to automatically correct problems with +@kbd{eglot-code-actions}. @xref{Eglot Commands}. @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. +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 @@ -507,17 +500,17 @@ Buffers}). @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: +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 @@ -535,8 +528,8 @@ 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 +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 @@ -544,80 +537,86 @@ 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. +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. +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: +When Eglot is active for a project, the project's buffers are treated +specially in several ways: @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. +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. +The layout of the Eglot mode-line can be changed by customizing +@code{eglot-mode-line-format} (@pxref{Customizing Eglot}). @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 function -@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. +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. @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 +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. + +@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. +Unlike other minor-modes, this special minor mode is @emph{not} +activated manually by the user, but automatically, as the result of +starting an Eglot session for the buffer. When Eglot stops managing the +buffer, the minor mode is turned off, and all the settings that Eglot +changed are restored to their original values. + +@vindex eglot-managed-mode-hook +@vindex eglot-managed-p +@item +The minor mode's main job is to ``hook up'' Eglot to other Emacs +functionality, i.e. arrange for these features to receive information +from the language server, by changing special variables controlling +these features. @xref{Eglot Features}. + +@item +To customize this, Eglot's special minor mode provides a hook variable +@code{eglot-managed-mode-hook} specifically to alter Eglot's interaction +with these variables in each buffer. This hook is run both when the +minor mode is turned on and when it's turned off; use the function +@code{eglot-managed-p} to tell if current buffer is still being managed +or not. @end itemize @node Eglot Commands @@ -629,48 +628,48 @@ 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. +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. +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 +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 +(@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. +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. +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 +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 @@ -687,8 +686,8 @@ 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. +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 @@ -712,11 +711,11 @@ region. If there are, you have the choice to execute one of them via the minibuffer. A common use of code actions is fixing the Flymake error diagnostics -issued by Eglot (@pxref{Top,,, flymake, GNU Flymake manual}). -Clicking on a diagnostic with @kbd{mouse-2} invokes +issued by Eglot (@pxref{Top,,, Flymake, GNU Flymake manual}). Clicking +on a diagnostic with @kbd{mouse-2} invokes @code{eglot-code-actions-at-mouse} which pops up a menu of available -code actions. The variable @code{eglot-diagnostics-map} can be used -to control the mouse binding. +code actions. The variable @code{eglot-diagnostics-map} can be used to +control the mouse binding. Other commands execute a specific code action. For example, @code{eglot-code-action-organize-imports} rearranges the program's @@ -726,12 +725,12 @@ uses. @cindex inlay hints @item M-x eglot-inlay-hints-mode This command toggles LSP @dfn{inlay hints} on and off for the current -buffer. Inlay hints are small text annotations to specific parts of -the whole buffer, not unlike diagnostics, but designed to help -readability instead of indicating problems. For example, a C++ -language server can serve hints about positional parameter names in -function calls and a variable's automatically deduced type. Inlay -hints help the user not have to remember these things by heart. +buffer. Inlay hints are small text annotations to specific parts of the +whole buffer, not unlike diagnostics, but designed to help readability +instead of indicating problems. For example, a C++ language server can +serve hints about positional parameter names in function calls and a +variable's automatically deduced type. Inlay hints help the user not +have to remember these things by heart. @end ftable The following Eglot commands are used less commonly, mostly for @@ -751,36 +750,35 @@ 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} +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. +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: +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 ElDoc, and Eglot @cindex documentation using Eglot @item M-x eldoc Ask the ElDoc system for help at point. -@cindex flymake, and Eglot +@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. @@ -805,8 +803,34 @@ variable, etc.) and offering completion. Request completion of the symbol at point. @end table -@node Eglot Variables -@section Eglot Variables +@node Customizing Eglot +@chapter Customizing Eglot +@cindex customizing Eglot + +To have Eglot behave like you want it, sometimes it suffices to +customize Emacs packages and features that Eglot uses but to do so for +all of Emacs (regardless of Eglot) . For example, 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}. To configure +Flymake faces used for errors and warnings, customize the +@code{flymake-error} and @code{flymake-warning} faces. + +Compared to the breadth of its functionality, Eglot itself has a +relatively small number of customization variables. There is +additionally a set of variables that are usually set from Elisp snippets +(@pxref{Init File,,, emacs, The GNU Emacs Manual}). + +Other times, it's necessary to have finer control of Eglot's interaction +with these features. @xref{More Customization}. + +@menu +* Customization Variables:: +* Other Variables:: +* More Customization:: +@end menu + +@node Customization Variables +@section Customization Variables @cindex variables, Eglot This section provides a reference for the Eglot user options. @@ -815,13 +839,12 @@ This section provides a reference for the Eglot user options. @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}). +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 @@ -833,10 +856,10 @@ 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. +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-config This configures the size and format of the Eglot events buffer. @@ -856,32 +879,32 @@ The default is @code{nil}; if you want to shut down a server, use @item eglot-confirm-server-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}, Eglot will ask for confirmation before performing -edits proposed by the language server. This option's value can be -crafted to require this confirmation for specific commands or only -when the edit affects files not yet visited by the user. Consult this -option's docstring for more information. +non-@code{nil}, Eglot will ask for confirmation before performing edits +proposed by the language server. This option's value can be crafted to +require this confirmation for specific commands or only when the edit +affects files not yet visited by the user. Consult this option's +docstring for more information. @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. +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}. +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: +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) @@ -890,40 +913,19 @@ this map. For example: (define-key eglot-mode-map (kbd "") 'xref-find-definitions) @end lisp +@cindex progress +@item eglot-report-progress +Set this variable to non-nil if you'd like progress notifications coming +from the language server to be handled by Emacs's progress reporting +facilities. If the value is the symbol @code{messages} the message +buffer is used, else the progress is reported in the mode line. @end vtable -Additional variables, which are relevant for customizing the server -connections, are documented in @ref{Customizing Eglot}. +@node Other Variables +@section Other Variables -@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. +This section provides a reference for Eglot variables that are meant to +be changed from Elisp snippets. @c @table, not @vtable, because some of the variables are indexed @c elsewhere @@ -960,12 +962,11 @@ A hook run after Eglot started or stopped managing a buffer. @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: +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) @@ -974,29 +975,121 @@ example: 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 language server to be handled as Emacs's progress reporting -facilities. @end table +@node More Customization +@section More Customization + +As explained earlier (@pxref{Eglot and Buffers}), Eglot hooks onto +existing Emacs packages and features by setting special variables in its +special minor mode. To gain finer control of Eglot's operation, the +@code{eglot-managed-mode-hook} should be used to tweak, subdue or +completely override Eglot's setting of these variables. + +@itemize @bullet +@item +Eglot hooks onto ElDoc's @code{eldoc-documentation-functions} variable, +adding a number of functions to it: +@itemize @minus +@item @code{eglot-hover-eldoc-function}, to display general information +about an identifier. +@item @code{eglot-signature-eldoc-function}, to display function +signature information. +@item @code{eglot-highlight-eldoc-function}, to highlight nearby +manifestations of an identifier. +@end itemize + +A simple tweak to remove at-point identifier information for +hypothetical language @code{Foo} may look like: + +@lisp +(add-hook 'foo-mode-hook + (lambda () + (add-hook 'eglot-managed-mode-hook + (lambda () + (remove-hook 'eldoc-documentation-functions + 'eglot-hover-eldoc-function + nil t)) + nil t))) +@end lisp + +For more sophisticated changes, we can take advantage of ElDoc's +well-defined protocols. @xref{Programming Language Doc,,, emacs, GNU +Emacs Manual}. For instance, the functions in +@code{eldoc-display-functions} control displays of the at-point +documentation produced by @code{eldoc-documentation-functions}. As an +example, to ensure that hover documentation specifically is never output +into the Echo area (in all programming modes): + +@lisp +(require 'cl-lib) + +(defun my/special-eglot-hover-function (cb &rest _ignored) + "Same as `eglot-hover-eldoc-function`, but skip the echo area." + (eglot-hover-eldoc-function (lambda (info &rest _ignore) + (funcall cb info :echo 'skip)))) + +;; substitute 'eldoc-hover-eldoc-function with our "fixed" variant. +(add-hook + 'eglot-managed-mode-hook + (lambda () + (setq-local eldoc-documentation-functions + (cl-substitute #'my/special-eglot-hover-function + 'eglot-hover-eldoc-function + eldoc-documentation-functions)))) +@end lisp + +@item +Eglot hooks onto Flymake's @code{flymake-diagnostic-functions} variable, +completely replacing its value with Eglot's own +@code{eglot-flymake-backend} function. Additional backends may be added +to work alongside Eglot's. + +@lisp +(add-hook 'foo-mode-hook + (lambda () + (add-hook 'eglot-managed-mode-hook + (lambda () + (add-hook 'flymake-diagnostic-functions + #'my/special-foo-mode-backend + nil t)) + nil t))) +@end lisp + +@item +Eglot hooks onto Xref's @code{xref-backend-functions} variable, adding +its own @code{eglot-xref-backend} function to it. + +@item +Eglot hooks onto Imenu's @code{imenu-create-index-function}. + +@item +Eglot hooks onto Emacs's @code{completion-at-point-functions}. + +@item +Eglot hooks onto Company's @code{company-backends} variable, ensuring +only the @code{company-capf} backend lives there. This ensures the same +set of completions as regular @code{completion-at-point}. + +@item +Eglot hooks onto YASnippet by automatically activating +@code{yas-minor-mode} when needed to expand server-provided snippets. +@end itemize + @node Advanced server configuration @chapter Advanced server configuration Though many language servers work well out-of-the-box, most allow fine-grained control of their operation via specific configuration -options that are transmitted over the LSP protocol and vary from -server to server. A small number of servers require such special -configuration to work acceptably, or even to work at all. +options that are transmitted over the LSP protocol and vary from server +to server. A small number of servers require such special configuration +to work acceptably, or even to work at all. After having setup a server executable program in @code{eglot-server-programs} (@pxref{Setting Up LSP Servers}) and -ensuring Eglot can invoke it, you may want to take advantage of some -of these options. You should first distinguish two main kinds of -server configuration: +ensuring Eglot can invoke it, you may want to take advantage of some of +these options. You should first distinguish two main kinds of server +configuration: @itemize @bullet @item @@ -1016,20 +1109,20 @@ teach how Eglot's user variables can be used to achieve it: @end menu It's important to note that not all servers allow both kinds of -configuration, nor is it guaranteed that user options can be copied -over to project options, and vice-versa. When in doubt, consult your +configuration, nor is it guaranteed that user options can be copied over +to project options, and vice-versa. When in doubt, consult your language server's documentation. It's also worth noting that some language servers can read these -settings from configuration files in the user's @code{HOME} directory -or in a project's directory. For example, the @command{pylsp} Python +settings from configuration files in the user's @code{HOME} directory or +in a project's directory. For example, the @command{pylsp} Python server reads the file @file{~/.config/pycodestyle} for user configuration. The @command{clangd} C/C++ server reads both @file{~/.config/clangd/config.yaml} for user configuration and -@file{.clangd} for project configuration. It may be advantageous to -use these mechanisms instead of Eglot's, as this will probably work -with other LSP clients and may be easier to debug than options riding -on the LSP wire. +@file{.clangd} for project configuration. It may be advantageous to use +these mechanisms instead of Eglot's, as this will probably work with +other LSP clients and may be easier to debug than options riding on the +LSP wire. @node Project-specific configuration @section Project-specific configuration @@ -1040,17 +1133,17 @@ To set project-specific settings, which the LSP specification calls @dfn{workspace configuration}, the variable @code{eglot-workspace-configuration} may be used. -This variable is a directory-local variable (@pxref{Directory -Variables, , Per-directory Local Variables, emacs, The GNU Emacs -Manual}). It's important to recognize that this variable really only -makes sense when set directory-locally. It usually does not make -sense to set it file-locally or in a major-mode hook. +This variable is a directory-local variable (@pxref{Directory Variables, +, Per-directory Local Variables, emacs, The GNU Emacs Manual}). It's +important to recognize that this variable really only makes sense when +set directory-locally. It usually does not make sense to set it +file-locally or in a major-mode hook. The most common way to set @code{eglot-workspace-configuration } is -using a @file{.dir-locals.el} file in the root of your project. If -you can't do that, you may also set it from Elisp code via the -@code{dir-locals-set-class-variables} function. (@pxref{Directory -Local Variables,,, elisp, GNU Emacs Lisp Reference Manual}). +using a @file{.dir-locals.el} file in the root of your project. If you +can't do that, you may also set it from Elisp code via the +@code{dir-locals-set-class-variables} function. (@pxref{Directory Local +Variables,,, elisp, GNU Emacs Lisp Reference Manual}). However you choose to set it, the variable's value is a plist (@pxref{Property Lists,,, elisp, GNU Emacs Lisp Reference Manual}) with @@ -1074,10 +1167,10 @@ server (@pxref{JSONRPC objects in Elisp}). This helper command works even before actually connecting to the server. These variable's value doesn't take effect immediately. That happens -upon establishing the connection, in response to an explicit query -from the server, or when issuing the command @kbd{M-x -eglot-signal-didChangeConfiguration} which notifies the server during -an ongoing Eglot session. +upon establishing the connection, in response to an explicit query from +the server, or when issuing the command @kbd{M-x +eglot-signal-didChangeConfiguration} which notifies the server during an +ongoing Eglot session. @subsection Examples @@ -1090,11 +1183,10 @@ plists. Some examples are useful. Let's say you want to configure two language servers to be used in a project written in a combination of the Python and Go languages. You -want to use the @command{pylsp} and @command{gopls} languages -servers. In the documentation of the servers in question (or in some -other editor's configuration file, or in some blog article), you find -the following configuration options in informal dotted-notation -syntax: +want to use the @command{pylsp} and @command{gopls} languages servers. +In the documentation of the servers in question (or in some other +editor's configuration file, or in some blog article), you find the +following configuration options in informal dotted-notation syntax: @example pylsp.plugins.jedi_completion.include_params: true @@ -1119,12 +1211,11 @@ To apply this to Eglot, and assuming you chose the @noindent This sets the value of @code{eglot-workspace-configuration} in all the -buffers inside the project; each server will use only the section of -the parameters intended for that server, and ignore the rest. Note -how alists are used for associating Emacs mode names with alists -associating variable names with variable values. Then notice how -plists are used inside the value of -@code{eglot-workspace-configuration}. +buffers inside the project; each server will use only the section of the +parameters intended for that server, and ignore the rest. Note how +alists are used for associating Emacs mode names with alists associating +variable names with variable values. Then notice how plists are used +inside the value of @code{eglot-workspace-configuration}. This following form may also be used: @@ -1170,13 +1261,12 @@ may use something like: . (:gopls (:usePlaceholders nil)))))) @end lisp -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 plist suitable for use as the variable's -value. +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 plist suitable for use as the variable's value. @node User-specific configuration @section User-specific configuration @@ -1187,9 +1277,9 @@ This kind of configuration applies to all projects the server is used for. Here, there are a number of ways to do this inside Eglot. A common way is to pass command-line options to the server invocation -via @code{eglot-server-programs}. Let's say we want to configure -where the @command{clangd} server reads its -@code{compile_commands.json} from. This can be done like so: +via @code{eglot-server-programs}. Let's say we want to configure where +the @command{clangd} server reads its @code{compile_commands.json} from. +This can be done like so: @lisp (with-eval-after-load 'eglot @@ -1199,9 +1289,9 @@ where the @command{clangd} server reads its @end lisp @noindent -Another way is to have Eglot pass a JSON object to the server during -the LSP handshake. This is done using the -@code{:initializationOptions} syntax of @code{eglot-server-programs}: +Another way is to have Eglot pass a JSON object to the server during the +LSP handshake. This is done using the @code{:initializationOptions} +syntax of @code{eglot-server-programs}: @lisp (with-eval-after-load 'eglot @@ -1213,21 +1303,21 @@ the LSP handshake. This is done using the @noindent The argument @code{(:compilationDatabasePath "/tmp")} is Emacs's representation in plist format of a simple JSON object -@code{@{"compilationDatabasePath": "/tmp"@}}. To learn how to -represent more deeply nested options in this format, @pxref{JSONRPC -objects in Elisp}. +@code{@{"compilationDatabasePath": "/tmp"@}}. To learn how to represent +more deeply nested options in this format, @pxref{JSONRPC objects in +Elisp}. -In this case, the two examples achieve exactly the same, but notice -how the option's name has changed between them. +In this case, the two examples achieve exactly the same, but notice how +the option's name has changed between them. @vindex eglot-workspace-configuration Finally there is another way to do user-specific configuration of language servers, which may be used if the methods above are not supported. It consists of @emph{globally} setting -@code{eglot-workspace-configuration}, a variable originally intended -for project-specific configuration. This has the same effect as -giving all your projects a certain default configuration, as described -in @ref{Project-specific configuration}. Here is an example: +@code{eglot-workspace-configuration}, a variable originally intended for +project-specific configuration. This has the same effect as giving all +your projects a certain default configuration, as described in +@ref{Project-specific configuration}. Here is an example: @lisp (setq-default eglot-workspace-configuration @@ -1243,10 +1333,10 @@ always overridden if a directory-local value is detected. @node JSONRPC objects in Elisp @section JSONRPC objects in Elisp -Emacs's preferred way of representing JSON is via Lisp lists. In -Eglot, the syntax of this list is the simplest possible (the one with -fewer parenthesis), a plist (@pxref{Property Lists,,, elisp, GNU Emacs -Lisp Reference Manual}). +Emacs's preferred way of representing JSON is via Lisp lists. In Eglot, +the syntax of this list is the simplest possible (the one with fewer +parenthesis), a plist (@pxref{Property Lists,,, elisp, GNU Emacs Lisp +Reference Manual}). The plist may be arbitrarily complex, and generally containing other keyword-value property sub-plists corresponding to JSON sub-objects. @@ -1254,8 +1344,8 @@ keyword-value property sub-plists corresponding to JSON sub-objects. For representing the JSON leaf values @code{true}, @code{false}, @code{null} and @code{@{@}}, you can use the Lisp values @code{t}, @code{:json-false}, @code{nil}, and @code{eglot-@{@}}, respectively. -JSON arrays are represented as Elisp vectors surrounded by square brackets -(@pxref{Vectors,,,elisp,GNU Emacs Lisp Reference Manual}). +JSON arrays are represented as Elisp vectors surrounded by square +brackets (@pxref{Vectors,,,elisp,GNU Emacs Lisp Reference Manual}). For example, the plist @@ -1293,22 +1383,21 @@ is serialized by Eglot to the following JSON text: @node Extending Eglot @chapter Extending Eglot -Sometimes it may be useful to extend existing Eglot functionality -using Elisp its public methods. A good example of when this need may -arise is adding support for a custom LSP protocol extension only -implemented by a specific server. +Sometimes it may be useful to extend existing Eglot functionality using +Elisp its public methods. A good example of when this need may arise is +adding support for a custom LSP protocol extension only implemented by a +specific server. -The best source of documentation for this is probably Eglot source -code itself, particularly the section marked ``API''. +The best source of documentation for this is probably Eglot source code +itself, particularly the section marked ``API''. -Most of the functionality is implemented with Common-Lisp style -generic functions (@pxref{Generics,,,eieio,EIEIO}) that can be easily -extended or overridden. The Eglot code itself is an example on how to -do this. +Most of the functionality is implemented with Common-Lisp style generic +functions (@pxref{Generics,,,eieio,EIEIO}) that can be easily extended +or overridden. The Eglot code itself is an example on how to do this. The following is a relatively simple example that adds support for the -@code{inactiveRegions} experimental feature introduced in version 17 -of the @command{clangd} C/C++ language server++. +@code{inactiveRegions} experimental feature introduced in version 17 of +the @command{clangd} C/C++ language server++. Summarily, the feature works by first having the server detect the Eglot's advertisement of the @code{inactiveRegions} client capability @@ -1318,18 +1407,18 @@ surrounded by C/C++ @code{#ifdef} macros that the preprocessor removes based on compile-time information. The language server reports the regions by periodically sending a -@code{textDocument/inactiveRegions} notification for each managed -buffer (@pxref{Eglot and Buffers}). Normally, unknown server -notifications are ignored by Eglot, but we're going change that. +@code{textDocument/inactiveRegions} notification for each managed buffer +(@pxref{Eglot and Buffers}). Normally, unknown server notifications are +ignored by Eglot, but we're going change that. Both the announcement of the client capability and the handling of the new notification is done by adding methods to generic functions. @itemize @bullet @item -The first method extends @code{eglot-client-capabilities} using a -simple heuristic to detect if current server is @command{clangd} and -enables the @code{inactiveRegion} capability. +The first method extends @code{eglot-client-capabilities} using a simple +heuristic to detect if current server is @command{clangd} and enables +the @code{inactiveRegion} capability. @lisp (cl-defmethod eglot-client-capabilities :around (server) @@ -1343,10 +1432,10 @@ enables the @code{inactiveRegion} capability. base)) @end lisp -Notice we use an internal function of the @code{jsonrpc.el} library, -and a regexp search to detect @command{clangd}. An alternative would -be to define a new EIEIO subclass of @code{eglot-lsp-server}, maybe -called @code{eglot-clangd}, so that the method would be simplified: +Notice we use an internal function of the @code{jsonrpc.el} library, and +a regexp search to detect @command{clangd}. An alternative would be to +define a new EIEIO subclass of @code{eglot-lsp-server}, maybe called +@code{eglot-clangd}, so that the method would be simplified: @lisp (cl-defmethod eglot-client-capabilities :around ((_s eglot-clangd)) @@ -1356,11 +1445,11 @@ called @code{eglot-clangd}, so that the method would be simplified: '(:inactiveRegions t)))) @end lisp -However, this would require that users tweak -@code{eglot-server-program} to tell Eglot instantiate such sub-classes -instead of the generic @code{eglot-lsp-server} (@pxref{Setting Up LSP -Servers}). For the purposes of this particular demonstration, we're -going to use the more hacky regexp route which doesn't require that. +However, this would require that users tweak @code{eglot-server-program} +to tell Eglot instantiate such sub-classes instead of the generic +@code{eglot-lsp-server} (@pxref{Setting Up LSP Servers}). For the +purposes of this particular demonstration, we're going to use the more +hacky regexp route which doesn't require that. Note, however, that detecting server versions before announcing new capabilities is generally not needed, as both server and client are @@ -1368,8 +1457,8 @@ required by LSP to ignore unknown capabilities advertised by their counterparts. @item -The second method implements @code{eglot-handle-notification} to -process the server notification for the LSP method +The second method implements @code{eglot-handle-notification} to process +the server notification for the LSP method @code{textDocument/inactiveRegions}. For each region received it creates an overlay applying the @code{shadow} face to the region. Overlays are recreated every time a new notification of this kind is @@ -1379,8 +1468,8 @@ To learn about how @command{clangd}'s special JSONRPC notification message is structured in detail you could consult that server's documentation. Another possibility is to evaluate the first capability-announcing method, reconnect to the server and peek in the -events buffer (@pxref{Eglot Commands, eglot-events-buffer}). You -could find something like: +events buffer (@pxref{Eglot Commands, eglot-events-buffer}). You could +find something like: @lisp [server-notification] Mon Sep 4 01:10:04 2023: @@ -1395,17 +1484,17 @@ could find something like: @end lisp This reveals that the @code{textDocument/inactiveRegions} notification -contains a @code{:textDocument} property to designate the managed -buffer and an array of LSP regions under the @code{:regions} property. -Notice how the message (originally in JSON format), is represented as -Elisp plists (@pxref{JSONRPC objects in Elisp}). +contains a @code{:textDocument} property to designate the managed buffer +and an array of LSP regions under the @code{:regions} property. Notice +how the message (originally in JSON format), is represented as Elisp +plists (@pxref{JSONRPC objects in Elisp}). -The Eglot generic function machinery will automatically destructure -the incoming message, so these two properties can simply be added to -the new method's lambda list as @code{&key} arguments. Also, the +The Eglot generic function machinery will automatically destructure the +incoming message, so these two properties can simply be added to the new +method's lambda list as @code{&key} arguments. Also, the @code{eglot-uri-to-path} and @code{eglot-range-region} may be used to -easily parse the LSP @code{:uri} and @code{:start ... :end ...} -objects to obtain Emacs objects for file names and positions. +easily parse the LSP @code{:uri} and @code{:start ... :end ...} objects +to obtain Emacs objects for file names and positions. The remainder of the implementation consists of standard Elisp techniques to loop over arrays, manage buffers and overlays. @@ -1432,9 +1521,8 @@ techniques to loop over arrays, manage buffers and overlays. After evaluating these two additions and reconnecting to the @command{clangd} language server (version 17), the result will be that -all the inactive code in the buffer will be nicely grayed out using -the LSP server knowledge about current compile time preprocessor -defines. +all the inactive code in the buffer will be nicely grayed out using the +LSP server knowledge about current compile time preprocessor defines. @node Troubleshooting Eglot @chapter Troubleshooting Eglot @@ -1460,19 +1548,17 @@ indicate the problems or at least provide a hint. @section Performance @cindex performance problems, with Eglot A common and easy-to-fix cause of performance problems in Eglot -(especially in older versions) is its events buffer, since it -represents additional work that Eglot must do (@pxref{Eglot Commands, +(especially in older versions) is its events buffer, since it represents +additional work that Eglot must do (@pxref{Eglot Commands, eglot-events-buffer}). If you find Eglot is operating correctly but -slowly, try to customize the variable -@code{eglot-events-buffer-config} (@pxref{Eglot Variables}) and set -its @code{:size} property to 0. This will disable recording any -events and may speed things up. +slowly, try to customize the variable @code{eglot-events-buffer-config} +(@pxref{Customization Variables}) and set its @code{:size} property to +0. This will disable recording any events and may speed things up. -In other situations, the cause of poor performance lies in the -language server itself. Servers use aggressive caching and other -techniques to improve their performance. Often, this can be tweaked -by changing the server configuration (@pxref{Advanced server -configuration}). +In other situations, the cause of poor performance lies in the language +server itself. Servers use aggressive caching and other techniques to +improve their performance. Often, this can be tweaked by changing the +server configuration (@pxref{Advanced server configuration}). @node Getting the latest version @section Getting the latest version @@ -1483,19 +1569,19 @@ Eglot, use @kbd{M-x package-install}. Often, a newer Eglot version exists that has fixed a longstanding bug, has more LSP features, or just better supports a particular language -server. Recent Eglot versions can self-update via the command -@kbd{M-x eglot-upgrade-eglot}. This will replace any currently -installed version with the newest one available from the ELPA archives -configured in @code{package-archives}. +server. Recent Eglot versions can self-update via the command @kbd{M-x +eglot-upgrade-eglot}. This will replace any currently installed version +with the newest one available from the ELPA archives configured in +@code{package-archives}. You can also update Eglot through other methods, such as @code{use-package} (@pxref{Installing packages,,, use-package, -use-package User Manual}), @code{package-install}, -@code{list-packages} or the newer @code{package-upgrade} -(@pxref{Packages,,, emacs, GNU Emacs Manual}). However, do read the -docstrings of the command you intend to use before you use it, as some -of them may not work in exactly the same way across Emacs versions, -meaning your configuration may be not portable. +use-package User Manual}), @code{package-install}, @code{list-packages} +or the newer @code{package-upgrade} (@pxref{Packages,,, emacs, GNU Emacs +Manual}). However, do read the docstrings of the command you intend to +use before you use it, as some of them may not work in exactly the same +way across Emacs versions, meaning your configuration may be not +portable. @node Reporting bugs @section Reporting bugs @@ -1504,9 +1590,8 @@ meaning your configuration may be not portable. If you think you have found a bug, we want to hear about it. Before reporting a bug, keep in mind that interaction with language servers represents a large quantity of unknown variables. Therefore, it is -generally both @emph{difficult} and @emph{absolutely essential} that -the maintainers reproduce bugs exactly as they happened to you, the -user. +generally both @emph{difficult} and @emph{absolutely essential} that the +maintainers reproduce bugs exactly as they happened to you, the user. To report an Eglot bug, send e-mail to @email{bug-gnu-emacs@@gnu.org}. @@ -1516,29 +1601,29 @@ follow this Eglot-specific checklist: @enumerate @item -Include the transcript of JSONRPC events obtained from the buffer -popped up by @kbd{M-x eglot-events-buffer}. You may narrow down the -transcript if you are sure of where the problematic exchange is, but -it's safer to include the whole transcript, either attached or inline. +Include the transcript of JSONRPC events obtained from the buffer popped +up by @kbd{M-x eglot-events-buffer}. You may narrow down the transcript +if you are sure of where the problematic exchange is, but it's safer to +include the whole transcript, either attached or inline. @item If Emacs signaled an error (an error message was seen or heard), make sure to repeat the process after turning on @code{debug-on-error} 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. +@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 -Include a description of how the maintainer should obtain, install, -and configure the language server you used. Maintainers usually have -access to GNU/Linux systems, though not necessarily the distribution -that you may be using. If possible, try to replicate the problem with -the C/C@t{++} or Python servers, as these are very easy to install. +Include a description of how the maintainer should obtain, install, and +configure the language server you used. Maintainers usually have access +to GNU/Linux systems, though not necessarily the distribution that you +may be using. If possible, try to replicate the problem with the +C/C@t{++} or Python servers, as these are very easy to install. @item Describe how to setup a @emph{minimal} project directory where Eglot -should be started for the problem to happen. Describe each file's -name and its contents. Alternatively, you can supply the address of a -public Git repository. +should be started for the problem to happen. Describe each file's name +and its contents. Alternatively, you can supply the address of a public +Git repository. @item Include versions of the software used. The Emacs version can be @@ -1551,31 +1636,29 @@ first check if the problem isn't already fixed in the latest version It's also essential to include the version of ELPA packages that are explicitly or implicitly loaded. The optional but popular Company or Markdown packages are distributed as GNU ELPA packages, not to mention -Eglot itself in some situations. Some major modes (Go, Rust, etc.) -are provided by ELPA packages. It's sometimes easy to miss these, -since they are usually implicitly loaded when visiting a file in that +Eglot itself in some situations. Some major modes (Go, Rust, etc.) are +provided by ELPA packages. It's sometimes easy to miss these, since +they are usually implicitly loaded when visiting a file in that language. ELPA packages usually live in @code{~/.emacs.d/elpa} (or what is in @code{package-user-dir}). Including a listing of files in that -directory is a way to tell the maintainers about ELPA package -versions. +directory is a way to tell the maintainers about ELPA package versions. @item -Include a recipe to replicate the problem with @emph{a clean Emacs -run}. The invocation @code{emacs -Q -f package-initialize} starts -Emacs with no configuration and initializes the ELPA packages. A very -minimal @file{.emacs} initialization file (10 lines or less) is also -acceptable and good means to describe changes to variables. +Include a recipe to replicate the problem with @emph{a clean Emacs run}. +The invocation @code{emacs -Q -f package-initialize} starts Emacs with +no configuration and initializes the ELPA packages. A very minimal +@file{.emacs} initialization file (10 lines or less) is also acceptable +and good means to describe changes to variables. There is usually no need to include @code{require} statements in the recipe, as Eglot's functionality uses autoloads. -Likewise, there is rarely the need to use things like -@code{use-package} or @code{eglot-ensure}. This just makes the recipe -harder to follow. Prefer setting variables with @code{setq} and -adding to hooks with @code{add-hook}. Prefer starting Eglot with -@code{M-x eglot}. +Likewise, there is rarely the need to use things like @code{use-package} +or @code{eglot-ensure}. This just makes the recipe harder to follow. +Prefer setting variables with @code{setq} and adding to hooks with +@code{add-hook}. Prefer starting Eglot with @code{M-x eglot}. @item Make sure to double check all the above elements and re-run the recipe