2018-01-21 20:27:33 +00:00
#+TITLE : LSP layer
2019-05-02 21:49:30 +00:00
#+TAGS : layer|tool
2019-05-07 20:05:06 +00:00
* Table of Contents :TOC_5_gh:noexport:
2018-01-21 20:27:33 +00:00
- [[#description ][Description ]]
- [[#features ][Features: ]]
- [[#configuration ][Configuration ]]
2018-03-16 00:38:24 +00:00
- [[#variables ][Variables ]]
2020-10-08 00:32:35 +00:00
- [[#code-lens ][Code Lens ]]
- [[#error-statistics-on-modeline ][Error statistics on modeline ]]
- [[#code-actions-on-modeline ][Code actions on modeline ]]
2018-09-20 15:59:40 +00:00
- [[#navigation-mode ][Navigation mode ]]
2020-10-08 00:32:35 +00:00
- [[#breadcrumb-on-headerline ][Breadcrumb on headerline ]]
2018-11-22 10:56:35 +00:00
- [[#key-bindings ][Key bindings ]]
- [[#key-binding-prefixes ][Key binding prefixes ]]
- [[#core-key-bindings ][Core key bindings ]]
- [[#language-specific-key-binding-extensions ][Language-specific key binding extensions ]]
- [[#spacemacslsp-define-extensions-layer-name-kind-request-optional-extra-parameters ][~spacemacs/lsp-define-extensions layer-name kind request &optional extra-parameters~ ]]
- [[#spacemacslsp-bind-extensions-for-mode ][~spacemacs/lsp-bind-extensions-for-mode~ ]]
2020-10-08 00:32:35 +00:00
- [[#dap-integration ][DAP integration ]]
2018-11-22 10:56:35 +00:00
- [[#diagnostics ][Diagnostics ]]
2018-03-16 00:38:24 +00:00
- [[#references ][References ]]
2018-01-21 20:27:33 +00:00
* Description
2018-09-19 03:54:47 +00:00
This layer adds support for basic language server protocol packages speaking
[[https://microsoft.github.io/language-server-protocol/specification ][language server protocol ]].
2018-03-16 00:38:24 +00:00
2018-09-19 03:54:47 +00:00
Different language servers may support the language server protocol to varying degrees
2019-05-26 20:58:52 +00:00
and they may also provide extensions; check the language server's website for
2018-09-19 03:54:47 +00:00
details.
2020-10-08 00:32:35 +00:00
~M-x lsp-describe-session~ in a LSP buffer to list capabilities of the server.
2018-01-21 20:27:33 +00:00
** Features:
2018-09-19 03:54:47 +00:00
- Cross references (definitions, references, document symbol, workspace symbol
search and others)
- Workspace-wide symbol rename
- Symbol highlighting
- Flycheck
2020-10-08 00:32:35 +00:00
- Completion with =LSP=
- Signature help with =eldoc=
2018-09-19 03:54:47 +00:00
- Symbol documentation in a child frame (=lsp-ui-doc= )
2020-10-08 00:32:35 +00:00
- Navigation using =imenu=
2018-12-22 11:04:49 +00:00
- Consistent core key bindings in LSP modes
2020-10-08 00:32:35 +00:00
- Code folding (=lsp-origami= )
2018-01-21 20:27:33 +00:00
* Configuration
2019-09-30 04:49:44 +00:00
Enabling this layer will set the used backend for all supported languages to
2020-10-08 00:32:35 +00:00
=LSP= unless you explicitly set a specific backend for the language.
2019-09-30 04:49:44 +00:00
2018-09-19 03:54:47 +00:00
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.
2018-03-16 00:38:24 +00:00
2020-10-08 00:32:35 +00:00
If you add =lsp-**-enable= to major mode hooks for auto initialization of
language clients, customize ~lsp-project-whitelist~ and ~lsp-project-blacklist~ to
2019-05-26 20:58:52 +00:00
disable projects you don't want to enable LSP.
2018-03-16 00:38:24 +00:00
** Variables
2018-09-19 03:54:47 +00:00
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)=
2020-10-08 00:32:35 +00:00
| Variable name | Default | Description |
|--------------------------------------+--------------------------------------+-----------------------------------------------------------------------------------------------------------------|
2020-12-20 21:25:23 +00:00
| =lsp-headerline-breadcrumb-enable= | t | When non-nil, shows breadcrumb on headerline. |
2020-10-08 00:32:35 +00:00
| =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. |
2021-02-20 18:50:38 +00:00
| =lsp-use-lsp-ui= | nil | When non-nil, install lsp-ui package |
2020-10-08 00:32:35 +00:00
| =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). |
** 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,
2020-10-15 21:23:44 +00:00
2020-10-08 00:32:35 +00:00
#+BEGIN_SRC emacs-lisp
2020-10-15 21:23:44 +00:00
(setq-default dotspacemacs-configuration-layers
2020-12-20 21:25:23 +00:00
'((lsp :variables lsp-lens-enable t)))
2020-10-08 00:32:35 +00:00
#+END_SRC
This doesn't have any effect when code lens is not supported by current language server.
** 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~ .
#+BEGIN_SRC emacs-lisp
2020-10-15 21:23:44 +00:00
(setq-default dotspacemacs-configuration-layers
'((lsp :variables lsp-modeline-diagnostics-enable nil)))
2020-10-08 00:32:35 +00:00
#+END_SRC
To only display errors for the current file, you can set ~lsp-modeline-diagnostics-scope~ to ~:file~ .
#+BEGIN_SRC emacs-lisp
2020-10-15 21:23:44 +00:00
(setq-default dotspacemacs-configuration-layers
'((lsp :variables lsp-modeline-diagnostics-scope :file)))
2020-10-08 00:32:35 +00:00
#+END_SRC
Alternatively, if you want to see all errors across all projects, you can set it to ~:global~ .
** 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~ .
#+BEGIN_SRC emacs-lisp
2020-10-15 21:23:44 +00:00
(setq-default dotspacemacs-configuration-layers
'((lsp :variables lsp-modeline-code-actions-enable nil)))
2020-10-08 00:32:35 +00:00
#+END_SRC
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.
#+BEGIN_SRC emacs-lisp
2020-10-15 21:23:44 +00:00
(setq-default dotspacemacs-configuration-layers
'((lsp :variables
;; default segments
lsp-modeline-code-actions-segments '(count icon))))
2020-10-08 00:32:35 +00:00
#+END_SRC
2018-09-20 15:59:40 +00:00
** 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~
2018-11-08 20:21:30 +00:00
and the =lsp-ui-peek= variants under ~SPC m G~ . Setting ~lsp-navigation~ to either ~'simple~ or ~'peek~ eliminates
2018-09-20 15:59:40 +00:00
the bindings under ~SPC m G~ and creates bindings under ~SPC m g~ according to the specified preference.
2020-10-08 00:32:35 +00:00
** Breadcrumb on headerline
2021-02-21 01:23:43 +00:00
To display breadcrumb in the headerline, set ~lsp-headerline-breadcrumb-enable~ to ~t~ .
2020-10-08 00:32:35 +00:00
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,
2020-10-15 21:23:44 +00:00
2020-10-08 00:32:35 +00:00
#+BEGIN_SRC emacs-lisp
2020-10-15 21:23:44 +00:00
(setq-default dotspacemacs-configuration-layers
'((lsp :variables lsp-headerline-breadcrumb-segments '(symbols))))
2020-10-08 00:32:35 +00:00
#+END_SRC
To display the current project, current file, and document symbols,
2020-10-15 21:23:44 +00:00
2020-10-08 00:32:35 +00:00
#+BEGIN_SRC emacs-lisp
2020-10-15 21:23:44 +00:00
(setq-default dotspacemacs-configuration-layers
'((lsp :variables lsp-headerline-breadcrumb-segments '(project file symbols))))
2020-10-08 00:32:35 +00:00
#+END_SRC
2021-01-22 02:49:37 +00:00
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.
2018-11-22 10:56:35 +00:00
* Key bindings
2019-05-26 20:58:52 +00:00
A number of lsp features useful for all/most modes have been bound to the lsp minor mode, meaning they'll be
2018-11-22 10:56:35 +00:00
available in all language layers based on the lsp layer.
** Key binding prefixes
The key bindings are grouped under the following prefixes:
2019-09-04 18:13:57 +00:00
| prefix | name | functional area |
|-----------+---------------+----------------------------------------------------------------------------|
2020-11-09 22:18:57 +00:00
| ~SPC m a~ | action | Code actions |
2019-09-04 18:13:57 +00:00
| ~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 LSP backend features (documentation / symbol info overlays etc.) |
| ~SPC m x~ | text (source) | Text (source) document related bindings |
2018-11-22 10:56:35 +00:00
2018-12-22 11:04:49 +00:00
Some navigation key bindings (i.e. ~SPC m g~ / ~SPC m G~ ) use an additional level of grouping:
2018-11-22 10:56:35 +00:00
2019-04-14 08:47:21 +00:00
| prefix | name | functional area |
|-----------------+------------------+-----------------------------------------------------------|
| ~SPC m <g/G> h~ | hierarchy | Hierarchy (i.e. call/inheritance hierarchy etc. ) |
| ~SPC m <g/G> m~ | member hierarchy | Class/namespace members (functions, nested classes, vars) |
2018-11-22 10:56:35 +00:00
** Core key bindings
The lsp minor mode bindings are:
2019-09-04 18:13:57 +00:00
| binding | function |
|-------------+----------------------------------------------------------------------------------|
2020-10-15 21:23:44 +00:00
| ~SPC m = b~ | format buffer (=lsp-mode=) |
| ~SPC m = r~ | format region (=lsp-mode=) |
2019-09-04 18:13:57 +00:00
| ~SPC m = o~ | format (organise) imports |
|-------------+----------------------------------------------------------------------------------|
2020-10-08 00:32:35 +00:00
| Note | /The ~f~, ~r~ and ~s~ actions are placeholders for imminent =lsp-mode= features/ |
2019-09-04 18:13:57 +00:00
| ~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 |
|-------------+----------------------------------------------------------------------------------|
2020-10-15 21:23:44 +00:00
| ~SPC m g t~ | goto type-definition (=lsp-mode=) |
| ~SPC m g k~ | goto viewport word (=avy=) (See Note 1) |
| ~SPC m g K~ | goto viewport symbol (=avy=) (See Note 1) |
| ~SPC m g e~ | browse flycheck errors (=lsp-treemacs=) |
| ~SPC m g M~ | browse file symbols (=lsp-ui-imenu=) |
2019-09-04 18:13:57 +00:00
|-------------+----------------------------------------------------------------------------------|
2020-10-08 00:32:35 +00:00
| Note | /Replaced by the lsp-ui-peek equivalents when ~lsp-navigation~ is ~'peek~ / |
2020-10-15 21:23:44 +00:00
| ~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~) |
2019-09-04 18:13:57 +00:00
|-------------+----------------------------------------------------------------------------------|
2020-10-08 00:32:35 +00:00
| Note | /Omitted when ~lsp-navigation~ is ~'peek~ or ~'simple~ / |
2019-09-04 18:13:57 +00:00
| | /Bound under ~SPC m g~ rather than ~SPC m G~ when ~lsp-navigation~ == ='peek=/ |
2020-10-15 21:23:44 +00:00
| ~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=) |
2019-09-04 18:13:57 +00:00
|-------------+----------------------------------------------------------------------------------|
| ~SPC m h h~ | describe thing at point |
|-------------+----------------------------------------------------------------------------------|
2020-10-15 21:23:44 +00:00
| ~SPC m b s~ | ~lsp-workspace-shutdown~ |
| ~SPC m b r~ | ~lsp-workspace-restart~ |
| ~SPC m b d~ | ~lsp-describe-session~ |
2020-10-18 20:20:18 +00:00
| ~SPC m b v~ | ~lsp-version~ |
2019-09-04 18:13:57 +00:00
|-------------+----------------------------------------------------------------------------------|
| ~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 |
| ~SPC m T 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 |
2018-11-22 10:56:35 +00:00
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.
** Language-specific key binding extensions
2018-09-20 15:59:40 +00:00
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.
2018-11-22 10:56:35 +00:00
*** ~spacemacs/lsp-define-extensions layer-name kind request &optional extra-parameters~
2018-09-20 15:59:40 +00:00
Use this to define an extension to the lsp find functions. An example from the c-c++ layer:
#+BEGIN_SRC elisp
2020-10-15 21:23:44 +00:00
(spacemacs/lsp-define-extensions "c-c++" 'refs-address
"textDocument/references"
'(plist-put (lsp--text-document-position-params) :context '(:role 128)))
2018-09-20 15:59:40 +00:00
#+END_SRC
This defines the following interactive functions:
- ~c-c++/find-refs-address~
- ~c-c++/peek-refs-address~
2018-11-22 10:56:35 +00:00
*** ~spacemacs/lsp-bind-extensions-for-mode~
2018-09-20 15:59:40 +00:00
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:
#+BEGIN_SRC elisp
2020-10-15 21:23:44 +00:00
(spacemacs/lsp-bind-extensions-for-mode mode "c-c++"
"&" 'refs-address
"R" 'refs-read
"W" 'refs-write
"c" 'callers
"C" 'callees
"v" 'vars)
2018-09-20 15:59:40 +00:00
#+END_SRC
With ~lsp-navigation~ set to ~'both~ (the default), this is equivalent to:
#+BEGIN_SRC elisp
2020-10-15 21:23:44 +00:00
(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)
2018-09-20 15:59:40 +00:00
#+END_SRC
2018-11-08 20:21:30 +00:00
2018-09-20 15:59:40 +00:00
whereas with ~lsp-navigation~ set to ~'peek~ , this is equivalent to:
#+BEGIN_SRC elisp
2020-10-15 21:23:44 +00:00
(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)
2018-09-20 15:59:40 +00:00
#+END_SRC
etc.
2020-10-08 00:32:35 +00:00
* DAP integration
=lsp-mode= integrates with =dap-mode= , which implements DAP(Debugger Adapter Protocol). See documentation on =DAP= layer for details.
2018-11-22 10:56:35 +00:00
* Diagnostics
2018-09-19 03:54:47 +00:00
If some features do not work as expected, here is a common check list.
2020-10-08 00:32:35 +00:00
- ~M-x lsp-describe-session~ If the LSP workspace is initialized correctly
- ~M-: xref-backend-functions~ should be ~(lsp--xref-backend)~ for cross
2018-09-19 03:54:47 +00:00
references
2020-10-08 00:32:35 +00:00
- ~M-: completion-at-point-functions~ should be ~(lsp-completion-at-point)~ for
2018-09-19 03:54:47 +00:00
completion
2018-01-21 20:27:33 +00:00
2018-03-16 00:38:24 +00:00
* References
2018-09-19 03:54:47 +00:00
- [[https://github.com/emacs-lsp/lsp-mode ][lsp-mode repo ]]
- [[https://github.com/emacs-lsp/lsp-ui ][lsp-ui repo ]]