Table of Contents

LSP layer

Table of ContentsClose

1. 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-describe-session in a LSP buffer to list capabilities of the server.

Warning: This layers main purpose is to turn Spacemacs into an IDE it will therefore also load the syntax-checking and auto-completion layers, this may activate additional packages like flycheck and company in your buffer.

So if you want to use this layer but only part of the IDE features expect to do some manual configuring in your dotfile.

1.1. Features:

  • Cross references (definitions, references, document symbol, workspace symbol search and others)
  • Workspace-wide symbol rename
  • Symbol highlighting
  • Flycheck
  • Completion with LSP
  • Signature help with eldoc
  • Symbol documentation in a child frame (lsp-ui-doc)
  • Navigation using imenu
  • Consistent core key bindings in LSP modes
  • Code folding (lsp-origami)
  • Sonarlint integration (lsp-sonarlint)

2. Configuration

Enabling this layer will set the used backend for all supported languages to LSP unless you explicitly set a specific backend for the language.

The LSP ecosystem is based on two packages: lsp-mode and lsp-ui. Please check out their documentation.

2.1. 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-headerline-breadcrumb-enable t When non-nil, shows breadcrumb on headerline.
lsp-headerline-breadcrumb-segments '(path-up-to-project file symbols) Display the path to the root of project, the name of the current file, and also its symbols. See details below.
lsp-lens-enable nil When non-nil, shows code lens when it's supported.
lsp-modeline-diagnostics-enable t When non-nil, shows error diagnostics in modeline.
lsp-modeline-diagnostics-scope :project Displays all error statistcs per projects. See details below.
lsp-modeline-code-actions-enable t When non-nil, shows available code actions in modeline.
lsp-modeline-code-actions-segments '(count icon) Display the number of available code actions and an icon. See details below.
lsp-navigation 'both 'simple or 'peek to bind only xref OR lsp-ui-peek navigation functions.
lsp-use-lsp-ui t When non-nil, install lsp-ui package
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).
lsp-sonarlint nil When non-nil, use lsp-sonarlint package.

2.2. Code Lens

Code lens is a feature that displays "actionable contextual information interspersed" in your source code. In other words, it displays extra information of the source code, and allows you to perform certain actions. For example, the LSP server may decorate the entry point of a program, and also provides a quick access for running/debugging the program.

To always display code lens, 

(setq-default dotspacemacs-configuration-layers
              '((lsp :variables lsp-lens-enable t)))

This doesn't have any effect when code lens is not supported by current language server.

2.3. Error statistics on modeline

By default, all error statistics of a project is displayed in the modeline. To disable this feature, set lsp-modeline-diagnostics-enable to nil. 

(setq-default dotspacemacs-configuration-layers
              '((lsp :variables lsp-modeline-diagnostics-enable nil)))

To only display errors for the current file, you can set lsp-modeline-diagnostics-scope to :file. 

(setq-default dotspacemacs-configuration-layers
              '((lsp :variables lsp-modeline-diagnostics-scope :file)))

Alternatively, if you want to see all errors across all projects, you can set it to :global.

2.4. Code actions on modeline

By default, available code actions are displayed in modeline. To disable this feature, set lsp-modeline-code-actions-enable to nil. 

(setq-default dotspacemacs-configuration-layers
              '((lsp :variables lsp-modeline-code-actions-enable nil)))

You can also customize its appearance via lsp-modeline-code-actions-segments. Available segments are:

  • icon shows a lightbulb icon.
  • name shows the name of the preferred code action.
  • count shows the how many code actions are available.
(setq-default dotspacemacs-configuration-layers
              '((lsp :variables
                     ;; default segments
                     lsp-modeline-code-actions-segments '(count icon))))

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.

To display breadcrumb in the headerline, set lsp-headerline-breadcrumb-enable to t.

You can customize the breadcrumb segments via lsp-headerline-breadcrumb-segments. Available segments are:

  • project shows the name of the current project.
  • file shows the name of the current file.
  • path-up-to-project shows the path up to the current project.
  • symbols shows the document symbols.

For example, to display only the symbols, 

(setq-default dotspacemacs-configuration-layers
              '((lsp :variables lsp-headerline-breadcrumb-segments '(symbols))))

To display the current project, current file, and document symbols, 

(setq-default dotspacemacs-configuration-layers
              '((lsp :variables lsp-headerline-breadcrumb-segments '(project file symbols))))

You may need to run all-the-icons-install-fonts if you have all-the-icons package installed, otherwise separators used by lsp-headerline-breadcrumb-mode will be garbled due to fonts missing.

3. Key bindings

A number of lsp features useful for all/most modes have been bound to the lsp minor mode, meaning they'll be available in all language layers based on the lsp layer.

3.1. Key binding prefixes

The key bindings are grouped under the following prefixes:

prefix name functional area
SPC m a action Code actions
SPC m = format Source formatting
SPC m g goto Source navigation
SPC m G peek Source navigation (lsp-ui-peek overlay)
SPC m F folder Add/remove folders from workspace
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 mode specific features
SPC m T l lsp Toggle LSP backend features (documentation / symbol info overlays etc.)
SPC m x text (source) Text (source) document related bindings

3.2. Core key bindings

The lsp minor mode bindings are:

binding function
SPC m = b format buffer (lsp-mode)
SPC m = r format region (lsp-mode)
SPC m = o format (organise) imports
Note The f, r and s actions are placeholders for imminent lsp-mode features
SPC m a a Execute code action
SPC m a f Execute fix action
SPC m a r Execute refactor action
SPC m a s Execute source action
SPC m g t goto type-definition (lsp-mode)
SPC m g e browse flycheck errors (lsp-treemacs)
SPC m g M browse file symbols (lsp-ui-imenu)
SPC m g h goto call hierachy (lsp-treemacs)
SPC m g T goto type hierachy (lsp-treemacs)
Note /Replaced by the lsp-ui-peek equivalents when lsp-navigation is 'peek /
SPC m g b jump back (xref / lsp)
SPC m g i find implementations (lsp-mode)
SPC m g d find definitions (xref / lsp-mode)
SPC m g r find references (xref / lsp)
SPC m g s find symbol in project (helm-lsp)
SPC m g S find symbol in all projects (helm-lsp)
SPC m g p goto previous (xref-pop-marker-stack)
Note /Omitted when lsp-navigation is 'peek or 'simple /
  Bound under SPC m g rather than SPC m G when lsp-navigation == 'peek
SPC m G b jump back (lsp-ui-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 S goto workspace symbol (lsp-treemacs-symbols)
SPC m G p goto previous (lsp-ui-peek stack - see Note 2)
SPC m G n goto next (lsp-ui-peek stack - see Note 2)
SPC m G E browse flycheck errors (lsp-ui)
SPC m h h describe thing at point
SPC m b s lsp-workspace-shutdown
SPC m b r lsp-workspace-restart
SPC m b d lsp-describe-session
SPC m b v lsp-version
SPC m r r rename
SPC m T l d toggle documentation overlay
SPC m T l F toggle documentation overlay function signature
SPC m T l s toggle symbol info overlay
SPC m T l S toggle symbol info overlay symbol name
SPC m T l I toggle symbol info overlay duplicates
SPC m T l l toggle lenses
SPC m F r Remove workspace folder
SPC m F a Add workspace folder
SPC m F s Switch workspace folder
SPC m x h Highlight all instances of symbol under point
SPC m x l Show code lenses
SPC m x L Hide code lenses

Note 1: Your language server may not distinguish between the word and symbol variants of this binding. Note 2: There is a window local jump list dedicated to cross references.

3.3. Language-specific key binding extensions

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.

3.3.1. 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

3.3.2. 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.

3.4. Bind to lsp upstreams

Alternatively, you can have lsp-mode handle the bindings for you, by setting lsp-use-upstream-bindings to t. In this case Spacemacs will bind the lsp-command-map behind SPC m, , and M-m.

The detailed bindings can be found here where Spacemacs only replaces the prefix s-l with SPC m.

lsp binding Spacemacs binding
s-l w s SPC m w s or , w s or M-m w s

As lsp-mode and has a deep integration into Spacemacs. Spacemacs hackers should pay attention to avoid any binding collision with lsp-mode. 

(lsp :variables lsp-use-upstream-bindings t)

4. DAP integration

lsp-mode integrates with dap-mode, which implements DAP(Debugger Adapter Protocol). See documentation on DAP layer for details.

5. Diagnostics

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

  • M-x lsp-describe-session 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

6. References

Author: root

Created: 2024-11-11 Mon 09:19

Validate