From 54e123a5055ab5a78a19a7a23ef329e954101754 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Jo=C3=A3o=20T=C3=A1vora?= Date: Sun, 12 Mar 2023 19:44:53 +0000 Subject: [PATCH] Update Eglot's manual about eglot-workspace-configuration There is a possible use for a global setting eglot-workspace-configuration, which is to (ab)use it to set user-specific configuration when the server doesn't permit other methods. Rearrange the "Advanced server configuration" section and describe that use in the manual. * doc/misc/eglot.texi (Project-specific configuration): Correct mistake about global usefulness of eglot-workspace-configuration. (Advanced server configuration): Swap order of sections. (User-specific configuration): Mention possibility of globally setting eglot-workspace-configuration. --- doc/misc/eglot.texi | 114 ++++++++++++++++++++++++++------------------ 1 file changed, 67 insertions(+), 47 deletions(-) diff --git a/doc/misc/eglot.texi b/doc/misc/eglot.texi index 99dc4ae1501..735da5f0163 100644 --- a/doc/misc/eglot.texi +++ b/doc/misc/eglot.texi @@ -989,24 +989,24 @@ server configuration: @itemize @bullet @item -User-specific, applying to all projects the server is used for; +Project-specific, applying to a specific project; @item -Project-specific, applying to a specific project. +User-specific, applying to all projects the server is used for. @end itemize When you have decided which kind you need, the following sections teach how Eglot's user variables can be used to achieve it: @menu -* User-specific configuration:: * Project-specific configuration:: +* User-specific configuration:: * JSONRPC objects in Elisp:: @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 project options, and vice-versa. When in doubt, consult your +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 @@ -1019,48 +1019,6 @@ configuration. The @command{clangd} C/C++ server reads both use these mechanisms instead of Eglot's, as the latter have the advantage of working with other LSP clients. -@node User-specific configuration -@section User-specific configuration -@cindex initializationOptions -@cindex command-line arguments - -This kind of configuration applies to all projects the server is used -for. Here, there are again two main 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: - -@lisp -(with-eval-after-load 'eglot - (add-to-list 'eglot-server-programs - `(c++-mode . ("clangd" "--compile-commands-dir=/tmp")))) - -@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}: - -@lisp -(with-eval-after-load 'eglot - (add-to-list 'eglot-server-programs - `(c++-mode . ("clangd" :initializationOptions - (:compilationDatabasePath "/tmp"))))) -@end lisp - -@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, @xref{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. - @node Project-specific configuration @section Project-specific configuration @vindex eglot-workspace-configuration @@ -1074,7 +1032,7 @@ 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 globally or in a major-mode hook. +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 @@ -1207,6 +1165,68 @@ 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 +@cindex initializationOptions +@cindex command-line arguments + +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: + +@lisp +(with-eval-after-load 'eglot + (add-to-list 'eglot-server-programs + `(c++-mode . ("clangd" "--compile-commands-dir=/tmp")))) + +@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}: + +@lisp +(with-eval-after-load 'eglot + (add-to-list 'eglot-server-programs + `(c++-mode . ("clangd" :initializationOptions + (:compilationDatabasePath "/tmp"))))) +@end lisp + +@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, @xref{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. + +@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 @xref{Project-specific configuration}. Here is an example. + +@lisp +(setq-default eglot-workspace-configuration + '(:pylsp (:plugins (:jedi_completion (:include_params t + :fuzzy t) + :pylint (:enabled :json-false))) + :gopls (:usePlaceholders t))) +@end lisp + +Note that the global value of @code{eglot-workspace-configuration} is +always overriden if a directory-local value is detected. + @node JSONRPC objects in Elisp @section JSONRPC objects in Elisp -- 2.39.2