spacemacs/layers/+tools/lsp/README.org

#+TITLE: LSP layer

* Table of Contents                      :TOC_4_gh:noexport:
- [[#description][Description]]
  - [[#features][Features:]]
- [[#configuration][Configuration]]
  - [[#derived-layers][Derived layers]]
    - [[#spacemacslsp-bind-keys-for-mode-mode][=spacemacs/lsp-bind-keys-for-mode mode=]]
  - [[#variables][Variables]]
  - [[#diagnostics][Diagnostics]]
- [[#future-additionsimprovements][Future additions/improvements]]
  - [[#make-spacemacslsp-bind-keys-for-mode-bind-conditionally][Make =spacemacs/lsp-bind-keys-for-mode= bind conditionally]]
- [[#references][References]]

* Description
  This layer adds support for basic language server protocol packages speaking
  [[https://microsoft.github.io/language-server-protocol/specification][language server protocol]].

  Different language servers may support the language server protocol to varying degrees
  and they may also provide extensions; check the language server's website for
  details.
  =M-x lsp-capabilities= in a LSP buffer to list capabilities of the server.

** Features:
   - Cross references (definitions, references, document symbol, workspace symbol
     search and others)
   - Workspace-wide symbol rename
   - Symbol highlighting
   - Flycheck
   - Completion with =company-lsp=
   - Signature help with eldoc
   - Symbol documentation in a child frame (=lsp-ui-doc=)
   - Navigation using imenu

* Configuration
  The LSP ecosystem is based on two packages: [[https://github.com/emacs-lsp/lsp-mode][lsp-mode]] and [[https://github.com/emacs-lsp/lsp-ui][lsp-ui]].
  Please check out their documentation.

  If you add =lsp-*-enable= to major mode hooks for auto initialization of
  language clients, customize =lsp-project-whitelist= =lsp-project-blacklist= to
  disable projects you don't want to enable LSP.

** Derived layers
   A number of elisp functions have been added to facilitate development of derived layers.

*** =spacemacs/lsp-bind-keys-for-mode mode=
    Binds keys to a number of lsp features useful for all/most modes for the given major mode.

    The prefix conventions suggested in spacemacs CONVENTIONS.org have been observed, where appropriate.

    The default bindings are listed below. Derived language server layers should extend this list.

    | binding | function                                        |
    |---------+-------------------------------------------------|
    | ~m = b~ | format buffer (lsp)                             |
    |---------+-------------------------------------------------|
    | ~m g i~ | goto implementation                             |
    | ~m g t~ | goto type-definition                            |
    | ~m g a~ | goto viewport symbol (avy)                      |
    | ~m g m~ | browse file symbols (lsp-ui-imenu)              |
    | ~m g d~ | find definitions                                |
    | ~m g r~ | find references                                 |
    | ~m g s~ | find-workspace-symbol                           |
    | ~m g p~ | jump prev (lsp-ui-peek stack - see Note 1)      |
    | ~m g n~ | jump next (lsp-ui-peek stack - see Note 1)      |
    | ~m g f~ | jump to flycheck error                          |
    |---------+-------------------------------------------------|
    | ~m h h~ | describe thing at point                         |
    |---------+-------------------------------------------------|
    | ~m l r~ | lsp-restart-workspace                           |
    | ~m l a~ | execute code action                             |
    |---------+-------------------------------------------------|
    | ~m r r~ | rename                                          |
    |---------+-------------------------------------------------|
    | ~m T d~ | toggle documentation overlay                    |
    | ~m T F~ | toggle documentation overlay function signature |
    | ~m T s~ | toggle symbol info overlay                      |
    | ~m T S~ | toggle symbol info overlay symbol name          |
    | ~m T I~ | toggle symbol info overlay duplicates           |

    Note 1: There is a window local jump list dedicated to cross references

** Variables
   A number of configuration variables have been exposed via the LSP layer =config.el=.
   Sensible defaults have been provided, however they may all be overridden in your .spacemacs, or dynamically using the bindings added
   under the derived mode t prefix by =(spacemacs/lsp-bind-keys-for-mode mode)=

   | Variable name                   | Default | Description                                                                               |
   |---------------------------------+---------+-------------------------------------------------------------------------------------------|
   | =lsp-ui-remap-xref-keybindings= | nil     | When non-nil, xref keybindings remapped to lsp-ui-peek-find-{definition,references}       |
   | =lsp-ui-doc-enable=             | t       | When non-nil, the documentation overlay is displayed                                      |
   | =lsp-ui-doc-include-signature=  | nil     | When nil, signature omitted from lsp-ui-doc overlay (this is usually redundant)           |
   | =lsp-ui-sideline-enable=        | t       | When non-nil, the symbol information overlay is displayed                                 |
   | =lsp-ui-sideline-show-symbol=   | nil     | When non-nil, the symbol information overlay includes symbol name (redundant for c-modes) |
   | =lsp-ui-peek-expand-by-default= | nil     | When non-nil, =lsp-ui-peek= expands file matches automatically (may degrade performance)  |

** Diagnostics
   If some features do not work as expected, here is a common check list.

  - =M-x lsp-capabilities= If the LSP workspace is initialized correctly
  - =M-: xref-backend-functions= should be =(lsp--xref-backend)= for cross
    references
  - =M-: completion-at-point-functions= should be =(lsp-completion-at-point)= for
    completion

* Future additions/improvements
** Make =spacemacs/lsp-bind-keys-for-mode= bind conditionally
   i.e. only bind keys if the language server supports the capability (queried using =lsp-capabilities=).
   =lsp-capabilities= uses current buffer to determine the language server, so this would probably entail adding the bindings dynamically in
   a mode hook.

* References
  - [[https://github.com/emacs-lsp/lsp-mode][lsp-mode repo]]
  - [[https://github.com/emacs-lsp/lsp-ui][lsp-ui repo]]