From 3e5856b21a83a52dda8c0b3ab541d106d809d625 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Tue, 18 Oct 2022 12:17:51 +0100 Subject: [PATCH 01/12] 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 From b92a5174939fba17ffb5235dd926c7063c13b1d1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jo=C3=A3o=20T=C3=A1vora?= Date: Tue, 18 Oct 2022 12:46:48 +0100 Subject: [PATCH 02/12] Minor stylistic fixes to introduction of doc/misc/eglot.texi * doc/misc/eglot.texi (title): Add "the". (Top): Fix sentence structure in top-level introduction. --- doc/misc/eglot.texi | 36 ++++++++++++++++++------------------ 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/doc/misc/eglot.texi b/doc/misc/eglot.texi index 761964334bb..df8509aa218 100644 --- a/doc/misc/eglot.texi +++ b/doc/misc/eglot.texi @@ -1,7 +1,7 @@ \input texinfo @c -*-texinfo-*- @c %**start of header @setfilename ../../eglot.info -@settitle Eglot: The Emacs Client for Language Server Protocol +@settitle Eglot: The Emacs Client for the Language Server Protocol @include docstyle.texi @syncodeindex vr cp @syncodeindex fn cp @@ -60,24 +60,24 @@ modify this GNU manual.'' @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 is the Emacs client for the @dfn{Language Server Protocol} +(@acronym{LSP}). 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. +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 for +analyzing 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 From c681f374788235cbaf1dca062450202e90fd2a86 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jo=C3=A3o=20T=C3=A1vora?= Date: Tue, 18 Oct 2022 14:46:27 +0100 Subject: [PATCH 03/12] More minor fixes to doc/misc/eglot.texi Most, if not all of these, were previously discussed with Eli. * doc/misc/eglot.texi (Setting Up LSP Server): Fix repetition of "This variable". (Setting Up LSP Server): Explain that single a running instance supports multiple major modes. (Starting Eglot, Eglot and Buffers): Correctly describe mode-line indication. (Eglot Features): Suggest that company-mode is just one of the possible packages. Explain that Eglot arranges for the completion package to "instantiate" snippets. Could have used "expand". Mention benefits of having the popular markdown-mode available. (Eglot Commands): Explain how eglot-reconnect and eglot-clear-status are useful. (Eglot Variables): Clarify when eglot-autoreconnect is useful. Clarify how eglot-sync-connect and eglot-connect-timeout relate to each other. Clarify semantics of eglot-confirm-server-initiated-edits. --- doc/misc/eglot.texi | 98 ++++++++++++++++++++++++--------------------- 1 file changed, 53 insertions(+), 45 deletions(-) diff --git a/doc/misc/eglot.texi b/doc/misc/eglot.texi index df8509aa218..3e79e89492d 100644 --- a/doc/misc/eglot.texi +++ b/doc/misc/eglot.texi @@ -191,9 +191,9 @@ 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. +programming language of each major mode. It provides all the +information that Eglot needs to know about the programming language of +the source you are editing. The value of the variable is an alist, whose elements are of the form @w{@code{(@var{major-mode} . @var{server})}}. @@ -205,8 +205,9 @@ 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. +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: @@ -280,17 +281,14 @@ 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 +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}. -@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}. +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 @@ -417,16 +415,22 @@ 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. +If a completion package such as @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. +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}. + +@item +If the popular 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 e.g. fontification before displaying it to the user. @item In addition to enabling and enhancing other features and packages, @@ -547,7 +551,7 @@ 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 +@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 @@ -630,8 +634,10 @@ 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. +Shuts down an 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 Shut down a language server. This commands prompts for a language @@ -706,7 +712,13 @@ the current value of the variable @code{eglot-workspace-configuration} @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. +Eglot keeps track of erroneous situations encountered by the server in +its mode-line indication so that the user may inspect the +communication leading up to it (@pxref{Troubleshooting Eglot}). If +the situation is deemed uninteresting or temporary, this command can +be used to ``forget'' the error. Note that the command @code{M-x +eglot-reconnect} can sometimes be used to unclog a temporarily +malfunctioning server. @end ftable As described in @ref{Eglot Features} most features associated with @@ -757,13 +769,12 @@ 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}). +language server when Eglot detects that the server process terminated +unexpectedly. 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. @item eglot-connect-timeout This specifies the number of seconds before connection attempt to a @@ -771,14 +782,14 @@ 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. +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 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 zero means don't block at +all during the waiting period. @item eglot-events-buffer-size This determines the size of the Eglot events buffer. @xref{Eglot @@ -800,11 +811,8 @@ The default is @code{nil}; if you want to shut down a server, use 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)? +performing edits initiated by the server or edits whose scope affects +buffers other than the one where the user initiated the request. @item eglot-ignored-server-capabilities This variable's value is a list of language server capabilities that From 7a551e92005dc9964c1a74a2896b5dbf0ca231b9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jo=C3=A3o=20T=C3=A1vora?= Date: Wed, 19 Oct 2022 13:21:40 +0100 Subject: [PATCH 04/12] Tweak some node names in doc/misc/eglot.texi "Shutting Down LSP Server" -> "Shutting Down LSP Servers" "Setting Up LSP Server" -> "Setting Up LSP Servers" * doc/misc/eglot.texi: Rework node names. --- doc/misc/eglot.texi | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/doc/misc/eglot.texi b/doc/misc/eglot.texi index 3e79e89492d..286607738b4 100644 --- a/doc/misc/eglot.texi +++ b/doc/misc/eglot.texi @@ -88,11 +88,11 @@ 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. +* 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 @@ -164,13 +164,13 @@ 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:: +* Setting Up LSP Servers:: How to configure LSP servers for your needs. +* Starting Eglot:: Ways of starting Eglot for your project. +* Shutting Down LSP Servers:: @end menu -@node Setting Up LSP Server -@section Setting Up LSP Server +@node Setting Up LSP Servers +@section Setting Up LSP Servers @cindex setting up LSP server for Eglot @cindex language server for Eglot @@ -321,8 +321,8 @@ 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 +@node Shutting Down LSP Servers +@section Shutting Down LSP Servers @cindex shutting down LSP server When Eglot is turned on, it arranges for turning itself off @@ -803,7 +803,7 @@ restarted using @kbd{eglot-shutdown} followed by @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}. +last buffer managed by it is killed. @xref{Shutting Down LSP Servers}. The default is @code{nil}; if you want to shut down a server, use @kbd{M-x eglot-shutdown} (@pxref{Eglot Commands}). @@ -882,7 +882,7 @@ connections and the server features to be used by Eglot. @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. +@xref{Setting Up LSP Servers}, for the details. @vindex eglot-strict-mode @item eglot-strict-mode: From 20d44771201ef96fcfd6aebffe05aa50c5fa8074 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jo=C3=A3o=20T=C3=A1vora?= Date: Wed, 19 Oct 2022 13:23:14 +0100 Subject: [PATCH 05/12] Remove spurious trailing ':' in doc/misc/eglot.texi * doc/misc/eglot.texi (Customizing Eglot): Remove spurious ':'. --- doc/misc/eglot.texi | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/misc/eglot.texi b/doc/misc/eglot.texi index 286607738b4..64f4c84dfda 100644 --- a/doc/misc/eglot.texi +++ b/doc/misc/eglot.texi @@ -885,7 +885,7 @@ supported major mode, and how to invoke that server's program. @xref{Setting Up LSP Servers}, for the details. @vindex eglot-strict-mode -@item eglot-strict-mode: +@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)}}. From 0c7024d0d9172322052de2ee571ba64afff905f0 Mon Sep 17 00:00:00 2001 From: Stefan Kangas Date: Thu, 20 Oct 2022 11:02:09 +0200 Subject: [PATCH 06/12] * doc/misc/Makefile.in (INFO_COMMON): Add eglot. --- doc/misc/Makefile.in | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/misc/Makefile.in b/doc/misc/Makefile.in index 1d881a5fc7f..b6eef7ea799 100644 --- a/doc/misc/Makefile.in +++ b/doc/misc/Makefile.in @@ -68,7 +68,7 @@ DOCMISC_W32 = @DOCMISC_W32@ ## Info files to build and install on all platforms. INFO_COMMON = auth autotype bovine calc ccmode cl \ - dbus dired-x ebrowse ede ediff edt eieio \ + dbus dired-x ebrowse ede ediff edt eglot eieio \ emacs-mime epa erc ert eshell eudc efaq eww \ flymake forms gnus emacs-gnutls htmlfontify idlwave ido info.info \ mairix-el message mh-e modus-themes newsticker nxml-mode octave-mode \ From 4725c123f33eb9579b695748fa9f85c9af3eb01a Mon Sep 17 00:00:00 2001 From: Stefan Kangas Date: Thu, 20 Oct 2022 11:38:18 +0200 Subject: [PATCH 07/12] ; eglot.texi: Fix typos and minor inconsistencies * doc/misc/eglot.texi: Fix typos and minor inconsistencies. --- doc/misc/eglot.texi | 43 ++++++++++++++++++++++--------------------- 1 file changed, 22 insertions(+), 21 deletions(-) diff --git a/doc/misc/eglot.texi b/doc/misc/eglot.texi index 64f4c84dfda..bd92582f900 100644 --- a/doc/misc/eglot.texi +++ b/doc/misc/eglot.texi @@ -89,7 +89,7 @@ This manual documents how to configure, use, and customize Eglot. @menu * Quick Start:: For the impatient. -* Eglot and LSP Servers:: How to work with language servers +* 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. @@ -201,13 +201,13 @@ The value of the variable is an alist, whose elements are of the form 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 a running instance of the associated -server is responsible for files of multiple major modes or languages -in the project. +and @var{id} a string that identifies the language to the server. The +latter form should be used 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: @@ -327,12 +327,12 @@ Emacs session, it runs the hook @code{eglot-connect-hook} 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 +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 does Eglot -management of a buffer entail. +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 @@ -372,7 +372,7 @@ commands and variables. 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: +packages. These are the main features that Eglot enables and provides: @itemize @bullet @item @@ -395,7 +395,7 @@ 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. +languages that are only supported by the @code{etags} backend. @item Buffer navigation by name of function, class, method, etc., via Imenu @@ -416,7 +416,7 @@ activated automatically as you type. @item If a completion package such as @code{company-mode}, a popular -3rd-party completion package, is installed, Eglot enhances it by +third-party completion package, is installed, Eglot enhances it by providing completion candidates based on the language-server analysis of the source code. @@ -505,7 +505,7 @@ 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 +e.g.@: a Git repository (@pxref{Version Control,,, emacs, GNU Emacs Manual}). @item @@ -618,8 +618,9 @@ 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. +with a prefix argument @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 @@ -640,7 +641,7 @@ can sometimes be useful to unclog a partially malfunctioning server connection. @item M-x eglot-shutdown -Shut down a language server. This commands prompts for a language +Shuts 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 @@ -863,7 +864,7 @@ customize the Flymake faces @code{flymake-error} and @item To configure the amount of space taken up by documentation in the -echo area, the customize the ElDoc variable +echo area, customize the ElDoc variable @code{eldoc-echo-area-use-multiline-p}. @item @@ -1008,7 +1009,7 @@ Alternatively, the same configuration could be defined as follows: 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 +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 From 2d2cdb4741a3c1e42c8ed771303a878fd428911b Mon Sep 17 00:00:00 2001 From: Stefan Kangas Date: Thu, 20 Oct 2022 11:40:37 +0200 Subject: [PATCH 08/12] eglot.texi: Move sentence on LSP Servers earlier * doc/misc/eglot.texi (Setting Up LSP Servers): Move explanation on the (lack of) need for customizing servers earlier. --- doc/misc/eglot.texi | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/doc/misc/eglot.texi b/doc/misc/eglot.texi index bd92582f900..9ed482cec62 100644 --- a/doc/misc/eglot.texi +++ b/doc/misc/eglot.texi @@ -185,8 +185,10 @@ 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. +programming languages each server supports. Eglot comes with a fairly +complete set of associations of major-modes to popular language +servers predefined. 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 @@ -249,9 +251,7 @@ arguments. @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 +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 From 16986a9cc42ef4de580456f4acc5feba682ac8b1 Mon Sep 17 00:00:00 2001 From: Stefan Kangas Date: Thu, 20 Oct 2022 11:42:29 +0200 Subject: [PATCH 09/12] eglot.texi: Make example more realistic * doc/misc/eglot.texi (Eglot and Buffers): Prefer more realistic *.c instead of *.foo in example. --- doc/misc/eglot.texi | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/doc/misc/eglot.texi b/doc/misc/eglot.texi index 9ed482cec62..e5f26060827 100644 --- a/doc/misc/eglot.texi +++ b/doc/misc/eglot.texi @@ -523,13 +523,13 @@ 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 +For example, if you visit the file @file{~/projects/fooey/lib/x.c} +and @file{x.c} 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 +analyze not only the file @file{lib/x.c} you visited, but likely +also all the other @file{*.c} files under the @file{~/projects/fooey} directory. In some cases, additional information specific to a given project will @@ -592,8 +592,8 @@ 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 +@file{/home/joe/projects/fooey/lib/y.c} in the above example will +notify the server of the @file{*.c} 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. From 5d73bc5c69f56ce1b22c950d19ef6406b662949f Mon Sep 17 00:00:00 2001 From: Stefan Kangas Date: Thu, 20 Oct 2022 11:43:08 +0200 Subject: [PATCH 10/12] eglot.texi: Explain where to find third-party packages * doc/misc/eglot.texi (Eglot Features): Improve description on third-party packages. --- doc/misc/eglot.texi | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/doc/misc/eglot.texi b/doc/misc/eglot.texi index e5f26060827..caf09769b49 100644 --- a/doc/misc/eglot.texi +++ b/doc/misc/eglot.texi @@ -418,19 +418,21 @@ activated automatically as you type. If a completion package such as @code{company-mode}, a popular third-party completion package, is installed, Eglot enhances it by providing completion candidates based on the language-server analysis -of the source code. +of the source code. (@code{company-mode} can be installed from GNU ELPA.) @item -If @code{yasnippet}, a popular 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}. +If @code{yasnippet}, a popular third-party package for automatic +insertion of code templates (snippets), is installed, and the language +server supports snippet completion candidates, Eglot arranges for the +completion package to instantiate these snippets using +@code{yasnippet}. (@code{yasnippet} can be installed from GNU ELPA.) @item -If the popular 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 e.g. fontification before displaying it to the user. +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 e.g. fontification before displaying it to the +user. @item In addition to enabling and enhancing other features and packages, From 2a9797b422fe8a28bfaab49974ea2be21ae2502e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jo=C3=A3o=20T=C3=A1vora?= Date: Thu, 20 Oct 2022 11:20:30 +0100 Subject: [PATCH 11/12] Fix Eglot manual's description of eglot-workspace-configuration * doc/misc/eglot.texi (Customizing Eglot) (eglot-workspace-configuration): Explain that plist may be arbitrarily complex and correctly identify nil as the Elisp equivalent to JSON null. --- doc/misc/eglot.texi | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/doc/misc/eglot.texi b/doc/misc/eglot.texi index caf09769b49..a05e7fd7ee8 100644 --- a/doc/misc/eglot.texi +++ b/doc/misc/eglot.texi @@ -964,11 +964,12 @@ this variable should be a property list of the following format: @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. +more parameter settings for that server, serialized by Eglot as a JSON +object. @var{plist} may be arbitrarity complex, generally containing +other keywork-value property sublists corresponding to JSON subobjects. +The JSON values @code{true}, @code{false}, @code{null} and @code{@{@}} +are represented by the Lisp values @code{t}, @code{:json-false}, +@code{nil}, and @{eglot-@{@}}, respectively. @findex eglot-show-workspace-configuration When experimenting with workspace settings, you can use the command From 0e7361a5ccce084613d54d6ba3954ffca6074817 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jo=C3=A3o=20T=C3=A1vora?= Date: Thu, 20 Oct 2022 11:42:25 +0100 Subject: [PATCH 12/12] Revert "eglot.texi: Make example more realistic" This quest for realism ignores the fact that a previous example for a hypothetical language Foo and a language server "fools" already exists. It also undermines the intended generality of the instructions. This reverts commit 16986a9cc42ef4de580456f4acc5feba682ac8b1. --- doc/misc/eglot.texi | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/doc/misc/eglot.texi b/doc/misc/eglot.texi index a05e7fd7ee8..c1de1e818dc 100644 --- a/doc/misc/eglot.texi +++ b/doc/misc/eglot.texi @@ -525,13 +525,13 @@ 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.c} -and @file{x.c} belongs to a project rooted at +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.c} you visited, but likely -also all the other @file{*.c} files under the +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 @@ -594,8 +594,8 @@ 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.c} in the above example will -notify the server of the @file{*.c} files' language that a new 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.