spacemacs/layers/+tools/lsp

LSP layer

• Description
  • Features:
• Configuration
  • Variables
  • Navigation mode
    • Extended navigation functions for derived layers
      • spacemacs/lsp-define-extensions layer-name kind request &optional extra-parameters
      • spacemacs/lsp-bind-extensions-for-mode
  • Core key bindings for derived layers
    • Declared prefixes
      • Navigation prefixes
    • Default key bindings
  • Diagnostics
• Future additions/improvements
  • Make spacemacs/lsp-bind-keys-for-mode bind conditionally
• References

Description

This layer adds support for basic language server protocol packages speaking 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: lsp-mode and 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.

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-navigation	`both’	`simple’ or `peek’ to bind xref OR lsp-ui-peek navigation functions
lsp-ui-remap-xref-keybindings	nil	When non-nil, xref key bindings 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)

Navigation mode

The lsp-navigation variable defined in config.el allows you to define a preference for lightweight or pretty (using lsp-ui-peek) source navigation styles. By default, the lightweight functions are bound under SPC m g and the lsp-ui-peek variants under SPC m G. Setting lsp-navigation to either 'simple or 'peek eliminates the bindings under SPC m G and creates bindings under SPC m g according to the specified preference.

Extended navigation functions for derived layers

Some LSP server implementations provide extensions to the protocol, which can be leveraged using lsp-find-custom or lsp-ui-peek-find-custom. A number of additional functions have been provided to facilitate wrapping these extensions in a manner consistent with the lsp-navigation setting.

spacemacs/lsp-define-extensions layer-name kind request &optional extra-parameters

Use this to define an extension to the lsp find functions. An example from the c-c++ layer:

  (spacemacs/lsp-define-extensions "c-c++" 'refs-address
                                   "textDocument/references"
                                   '(plist-put (lsp--text-document-position-params) :context '(:role 128)))

This defines the following interactive functions:

• c-c++/find-refs-address
• c-c++/peek-refs-address

spacemacs/lsp-bind-extensions-for-mode

Use this to bind one or more extensions under SPC m g and/or SPC m G, as dictated by the value of lsp-navigation. Using another example from the c-c++ layer:

  (spacemacs/lsp-bind-extensions-for-mode mode "c-c++"
                                          "&" 'refs-address
                                          "R" 'refs-read
                                          "W" 'refs-write
                                          "c" 'callers
                                          "C" 'callees
                                          "v" 'vars)

With lsp-navigation set to 'both (the default), this is equivalent to:

  (spacemacs/set-leader-keys-for-major-mode mode
    "g&" 'c-c++/find-refs-address
    "gR" 'c-c++/find-refs-read
    "gW" 'c-c++/find-refs-write
    "gc" 'c-c++/find-callers
    "gC" 'c-c++/find-callees
    "gv" 'c-c++/find-vars
    "G&" 'c-c++/peek-refs-address
    "GR" 'c-c++/peek-refs-read
    "GW" 'c-c++/peek-refs-write
    "Gc" 'c-c++/peek-callers
    "GC" 'c-c++/peek-callees
    "Gv" 'c-c++/peek-vars)

whereas with lsp-navigation set to 'peek, this is equivalent to:

  (spacemacs/set-leader-keys-for-major-mode mode
    "g&" 'c-c++/peek-refs-address
    "gR" 'c-c++/peek-refs-read
    "gW" 'c-c++/peek-refs-write
    "gc" 'c-c++/peek-callers
    "gC" 'c-c++/peek-callees
    "gv" 'c-c++/peek-vars)

etc.

Core key bindings for derived layers

The spacemacs/lsp-bind-keys-for-mode mode function binds keys to a number of lsp features useful for all/most modes for the given major mode. It also declares some relevant keyboard shortcut prefixes.

Declared prefixes

The following prefixes have been declared:

prefix	name	functional area
SPC m =	format	Source formatting
SPC m g	goto	Source navigation
SPC m G	peek	Source navigation (lsp-ui-peek overlay)
SPC m h	help	Help
SPC m b	lsp/backend	Catchall. Restart LSP backend, other implementation-specific functionality
SPC m r	refactor	What it says on the tin
SPC m T	toggle	Toggle LSP backend features (documentation / symbol info overlays etc.)

Navigation prefixes

The following prefixes have been declared under each of the navigation prefixes (i.e. SPC m g / SPC m G)

prefix	name	functional area
SPC m <g/G> h	hierarchy	Heirarchy (i.e. call/inheritance hierarchy etc. )
SPC m <g/G> m	member hierarchy	Class/namespace members (functions, nested classes, vars

Default key bindings

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

binding	function
SPC m = b	format buffer (lsp)
SPC m g t	goto type-definition (lsp)
SPC m g k	goto viewport symbol (avy)
SPC m g e	browse flycheck errors
SPC m g M	browse file symbols (lsp-ui-imenu)
Note	Replaced by the lsp-ui-peek equivalents when lsp-navigation = ='peek
SPC m g i	find implementations (lsp)
SPC m g d	find definitions (xref/lsp)
SPC m g r	find references (xref/lsp)
SPC m g s	find-workspace-symbol (lsp-ui)
SPC m g p	goto previous (xref-pop-marker-stack)
Note	Omitted when lsp-navigation = ='peek or 'simple
	Bound under SPC m g rather than SPC m G when lsp-navigation = ='peek
SPC m G i	find implementation (lsp-ui-peek)
SPC m G d	find definitions (lsp-ui-peek)
SPC m G r	find references (lsp-ui-peek)
SPC m G s	find-workspace-symbol (lsp-ui-peek)
SPC m G p	goto previous (lsp-ui-peek stack - see Note 1)
SPC m G n	goto next (lsp-ui-peek stack - see Note 1)
SPC m h h	describe thing at point
SPC m b r	lsp-restart-workspace
SPC m b a	execute code action
SPC m b c	lsp-capabilities
SPC m r r	rename
SPC m T d	toggle documentation overlay
SPC m T F	toggle documentation overlay function signature
SPC m T s	toggle symbol info overlay
SPC m T S	toggle symbol info overlay symbol name
SPC m T I	toggle symbol info overlay duplicates

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

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

• lsp-mode repo
• lsp-ui repo