gopls/doc/emacs.md: describe configuration for eglot

Now that joaotavora/eglot#367 is fixed, I think we should recommend it
as a serious alternative to LSP mode. This change describes both
packages, summarizes their different philosophies, and simplifies the
example LSP Mode configuration to avoid relying on another unnecessary
third-party package.

Users who need more detail on alternative configurations should
consult the LSP client vendors' pages — we don't need to recapitulate
all of that detail here.

Change-Id: If125fbde6d609e223ce44936504cc4b08b84dc3d
Reviewed-on: https://go-review.googlesource.com/c/tools/+/278774
Reviewed-by: Muir Manders <[email protected]>
Reviewed-by: Rebecca Stambler <[email protected]>
Trust: Bryan C. Mills <[email protected]>

Author: Bryan C. Mills

gopls/doc/emacs.md

@@ -1,45 +1,69 @@
 # Emacs
 
-Use [lsp-mode]. gopls is built in as a client. You first must install `gopls` and put it somewhere in your `PATH`. Here is a basic config to get you started (assuming you are using [use-package]):
+## Installing `gopls`
 
-```lisp
-(use-package lsp-mode
-  :ensure t
-  :commands (lsp lsp-deferred)
-  :hook (go-mode . lsp-deferred))
+To use `gopls` with Emacs, you must first
+[install the `gopls` binary](user.md#installation) and ensure that the directory
+containing the resulting binary (either `$(go env GOBIN)` or `$(go env
+GOPATH)/bin`) is in your `PATH`.
+
+## Choosing an Emacs LSP client
+
+To use `gopls` with Emacs, you will need to choose and install an Emacs LSP
+client package. Two popular client packages are [LSP Mode] and [Eglot].
+
+LSP Mode takes a batteries-included approach, with many integrations enabled
+“out of the box” and several additional behaviors provided by `lsp-mode` itself.
+
+Eglot takes a minimally-intrusive approach, focusing on smooth integration with
+other established packages. It provides a few of its own `eglot-` commands but
+no additional keybindings by default.
+
+Once you have selected which client you want to use, install it per the packages
+instructions: see [Eglot 1-2-3](https://github.com/joaotavora/eglot#1-2-3) or
+[LSP Mode Installation](https://emacs-lsp.github.io/lsp-mode/page/installation/).
+
+## Common configuration
+
+Both Eglot and LSP Mode can integrate with popular packages in the Emacs
+ecosystem:
+
+*   The built-in [`xref`] package provides cross-references.
+
+*   The built-in [Flymake] package provides an on-the-fly diagnostic overlay.
+
+*   [Company] mode displays code completion candidates (with a richer UI than
+    the built-in [`completion-at-point`]).
+
+Eglot provides documentation using the built-in [ElDoc] minor mode, while LSP
+Mode by default provides documentation using its own [`lsp-ui`] mode.
+
+Eglot by default locates the project root using the [`project`] package. In LSP
+Mode, this behavior can be configured using the `lsp-auto-guess-root` setting.
+
+## Configuring LSP Mode
+
+### Loading LSP Mode in `.emacs`
+
+```elisp
+(require 'lsp-mode)
+(add-hook 'go-mode-hook #'lsp-deferred)
 
 ;; Set up before-save hooks to format buffer and add/delete imports.
 ;; Make sure you don't have other gofmt/goimports hooks enabled.
 (defun lsp-go-install-save-hooks ()
   (add-hook 'before-save-hook #'lsp-format-buffer t t)
   (add-hook 'before-save-hook #'lsp-organize-imports t t))
 (add-hook 'go-mode-hook #'lsp-go-install-save-hooks)
-
-;; Optional - provides fancier overlays.
-(use-package lsp-ui
-  :ensure t
-  :commands lsp-ui-mode)
-
-;; Company mode is a standard completion package that works well with lsp-mode.
-(use-package company
-  :ensure t
-  :config
-  ;; Optionally enable completion-as-you-type behavior.
-  (setq company-idle-delay 0)
-  (setq company-minimum-prefix-length 1))
-
-;; Optional - provides snippet support.
-(use-package yasnippet
-  :ensure t
-  :commands yas-minor-mode
-  :hook (go-mode . yas-minor-mode))
 ```
 
-lsp-mode integrates with xref. By default `lsp-find-definition` is bound to `M-.`. To go back, use `M-,`. Explore other `lsp-*` commands (not everything is supported by gopls).
+### Configuring `gopls` via LSP Mode
 
-## Gopls Configuration
+See [settings] for information about available gopls settings.
 
-Stable gopls settings have first-class support in [lsp-mode]. For example, `(setq lsp-gopls-use-placeholders nil)` will disable placeholders in completion snippets. See [lsp-go] for a list of available variables.
+Stable gopls settings have corresponding configuration variables in `lsp-mode`.
+For example, `(setq lsp-gopls-use-placeholders nil)` will disable placeholders
+in completion snippets. See [`lsp-go`] for a list of available variables.
 
 Experimental settings can be configured via `lsp-register-custom-settings`:
 
@@ -49,22 +73,107 @@ Experimental settings can be configured via `lsp-register-custom-settings`:
    ("gopls.staticcheck" t t)))
 ```
 
-See [settings] for information about gopls settings.
+Note that after changing settings you must restart gopls using e.g. `M-x
+lsp-restart-workspace`.
+
+## Configuring Eglot
+
+### Configuring `project` for Go modules in `.emacs`
+
+Eglot uses the built-in `project` package to identify the LSP workspace for a
+newly-opened buffer. The `project` package does not natively know about `GOPATH`
+or Go modules. Fortunately, you can give it a custom hook to tell it to look for
+the nearest parent `go.mod` file (that is, the root of the Go module) as the
+project root.
+
+```elisp
+(require 'project)
+
+(defun project-find-go-module (dir)
+  (when-let ((root (locate-dominating-file dir "go.mod")))
+    (cons 'go-module root)))
+
+(cl-defmethod project-root ((project (head go-module)))
+  (cdr project))
+
+(add-hook 'project-find-functions #'project-find-go-module)
+```
+
+### Loading Eglot in `.emacs`
+
+```elisp
+;; Optional: load other packages before eglot to enable eglot integrations.
+(require 'company)
+(require 'yasnippet)
 
-Note that after changing settings you must restart gopls using e.g. `M-x lsp-restart-workspace`.
+(require 'go-mode)
+(require 'eglot)
+(add-hook 'go-mode-hook 'eglot-ensure)
+
+;; Optional: install eglot-format-buffer as a save hook.
+;; The depth of -10 places this before eglot's willSave notification,
+;; so that that notification reports the actual contents that will be saved.
+(defun eglot-format-buffer-on-save ()
+  (add-hook 'before-save-hook #'eglot-format-buffer -10 t))
+(add-hook 'go-mode-hook #'eglot-format-buffer-on-save)
+```
+
+### Configuring `gopls` via Eglot
+
+See [settings] for information about available gopls settings.
+
+LSP server settings are controlled by the `eglot-workspace-configuration`
+variable, which can be set either globally in `.emacs` (as below) or in a
+`.dir-locals.el` file in the project root.
+
+```elisp
+(setq-default eglot-workspace-configuration
+    '((:gopls .
+        ((staticcheck . t)
+         (matcher . "CaseSensitive")))))
+```
+
+### Organizing imports with Eglot
+
+`gopls` provides the import-organizing functionality of `goimports` as an LSP
+code action, which you can invoke as needed by running `M-x eglot-code-actions`
+(or a key of your choice bound to the `eglot-code-actions` function) and
+selecting `Organize Imports` at the prompt.
+
+Eglot does not currently support a standalone function to execute a specific
+code action (see
+[joaotavora/eglot#411](https://github.com/joaotavora/eglot/issues/411)), nor an
+option to organize imports as a `before-save-hook` (see
+[joaotavora/eglot#574](https://github.com/joaotavora/eglot/issues/574)). In the
+meantime, see those issues for discussion and possible workarounds.
 
 ## Troubleshooting
 
 Common errors:
-- When prompted by Emacs for your project folder, if you are using modules you must select the module's root folder (i.e. the directory with the "go.mod"). If you are using GOPATH, select your $GOPATH as your folder.
-- Emacs must have your environment set properly (PATH, GOPATH, etc). You can run `M-x getenv <RET> PATH <RET>` to see if your PATH is set in Emacs. If not, you can try starting Emacs from your terminal, using [this package][exec-path-from-shell], or moving your shell config from .bashrc into .bashenv (or .zshenv).
-- Make sure `lsp-mode` and `lsp-ui` are up-to-date, also make sure `lsp-go` and `company-lsp` are _not_ installed.
-- Look for errors in the `*lsp-log*` buffer.
-- Ask for help in the #emacs channel on the [Gophers slack].
-
-[lsp-mode]: https://github.com/emacs-lsp/lsp-mode
-[use-package]: https://github.com/jwiegley/use-package
-[exec-path-from-shell]: https://github.com/purcell/exec-path-from-shell
+
+-   When prompted by Emacs for your project folder, if you are using modules you
+    must select the module's root folder (i.e. the directory with the "go.mod").
+    If you are using GOPATH, select your $GOPATH as your folder.
+-   Emacs must have your environment set properly (PATH, GOPATH, etc). You can
+    run `M-x getenv <RET> PATH <RET>` to see if your PATH is set in Emacs. If
+    not, you can try starting Emacs from your terminal, using [this
+    package][exec-path-from-shell], or moving your shell config from `.bashrc`
+    into `.profile` and logging out and back in.
+-   Make sure only one LSP client mode is installed. (For example, if using
+    `lsp-mode`, ensure that you are not _also_ enabling `eglot`.)
+-   Look for errors in the `*lsp-log*` buffer or run `M-x eglot-events-buffer`.
+-   Ask for help in the `#emacs` channel on the [Gophers slack].
+
+[LSP Mode]: https://emacs-lsp.github.io/lsp-mode/
+[Eglot]: https://github.com/joaotavora/eglot/blob/master/README.md
+[`xref`]: https://www.gnu.org/software/emacs/manual/html_node/emacs/Xref.html
+[Flymake]: https://www.gnu.org/software/emacs/manual/html_node/flymake/Using-Flymake.html#Using-Flymake
+[Company]: https://company-mode.github.io/
+[`completion-at-point`]: https://www.gnu.org/software/emacs/manual/html_node/elisp/Completion-in-Buffers.html
+[ElDoc]: https://elpa.gnu.org/packages/eldoc.html
+[`lsp-ui`]: https://emacs-lsp.github.io/lsp-ui/
+[`lsp-go`]: https://github.com/emacs-lsp/lsp-mode/blob/master/clients/lsp-go.el
+[`use-package`]: https://github.com/jwiegley/use-package
+[`exec-path-from-shell`]: https://github.com/purcell/exec-path-from-shell
 [settings]: settings.md
-[lsp-go]: https://github.com/emacs-lsp/lsp-mode/blob/master/clients/lsp-go.el
 [Gophers slack]: https://invite.slack.golangbridge.org/