This is a Language Server Protocol client for the Kakoune editor.
curl -O -L https://github.com/kakoune-lsp/kakoune-lsp/releases/download/v17.1.2/kakoune-lsp-v17.1.2-x86_64-apple-darwin.tar.gz
tar xzvf kakoune-lsp-v17.1.2-x86_64-apple-darwin.tar.gz
# replace `~/.local/bin/` with something on your `$PATH`
mv kak-lsp ~/.local/bin/
# optional: if you want to use specific language servers
mkdir -p ~/.config/kak-lsp
mv kak-lsp.toml ~/.config/kak-lsp/
-
Arch Linux:
pacman -S kakoune-lsp
or AUR/kakoune-lsp-git -
Fedora Copr:
sudo dnf copr enable atim/kakoune -y && sudo dnf install kakoune-lsp
-
Void Linux:
xbps-install -S kak-lsp
wget https://github.com/kakoune-lsp/kakoune-lsp/releases/download/v17.1.2/kakoune-lsp-v17.1.2-x86_64-unknown-linux-musl.tar.gz
tar xzvf kak-lsp-v17.1.2-x86_64-unknown-linux-musl.tar.gz
# replace `~/.local/bin/` with something on your `$PATH`
mv kak-lsp ~/.local/bin/
# optional: if you want to use specific language servers
mkdir -p ~/.config/kak-lsp
mv kak-lsp.toml ~/.config/kak-lsp/
Generally, you need the latest stable version of Rust to build kakoune-lsp.
git clone https://github.com/kakoune-lsp/kakoune-lsp
cd kakoune-lsp
# this installs the kak-lsp binary to ~/.cargo/bin, which must be in your `$PATH`
cargo install --locked --force --path .
# optional: if you want to use specific language servers
mkdir -p ~/.config/kak-lsp
cp kak-lsp.toml ~/.config/kak-lsp/
If you don’t mind using a plugin manager, you can install kakoune-lsp
via plug.kak. Add this code to your kakrc
:
plug "kakoune-lsp/kakoune-lsp" do %{
cargo install --locked --force --path .
# optional: if you want to use specific language servers
mkdir -p ~/.config/kak-lsp
cp -n kak-lsp.toml ~/.config/kak-lsp/
}
cargo install
will install the kak-lsp
binary to ~/.cargo/bin
, which must be in your $PATH
.
Alternatively, you can replace cargo install
with cargo build --release && ln -sf $PWD/target/release/kak-lsp ~/.local/bin/
where ~/.local/bin/
can be replaced with something in your $PATH
.
Examples of configuration with plug.kak can be found at Wiki.
kakoune-lsp doesn’t manage installation of language servers, please install them by yourself for the languages you plan to use kakoune-lsp with. Please consult the How to install servers wiki page for quick installation of language servers supported by kakoune-lsp out of the box.
To enable LSP support for configured languages (see Configuration) just add the following
commands to your kakrc
:
eval %sh{kak-lsp --kakoune} # Not needed if you load it with plug.kak.
lsp-enable
A bit more involved but recommended way is to enable LSP only for specific filetypes you need
via lsp-enable-window
, e.g.:
eval %sh{kak-lsp --kakoune} # Not needed if you load it with plug.kak.
hook global WinSetOption filetype=(rust|python|go|javascript|typescript|c|cpp) %{
lsp-enable-window
}
There are three default mappings in goto-mode: gd
(lsp-definition
), gy
(lsp-type-definition
) and gr
(lsp-references
). You can override them in your kakrc after
this plugin is loaded.
Here are additional recommended mappings. See below for the meaning of each command.
map global user l %{:enter-user-mode lsp<ret>} -docstring "LSP mode"
map global insert <tab> '<a-;>:try lsp-snippets-select-next-placeholders catch %{ execute-keys -with-hooks <lt>tab> }<ret>' -docstring 'Select next snippet placeholder'
map global object a '<a-semicolon>lsp-object<ret>' -docstring 'LSP any symbol'
map global object <a-a> '<a-semicolon>lsp-object<ret>' -docstring 'LSP any symbol'
map global object f '<a-semicolon>lsp-object Function Method<ret>' -docstring 'LSP function or method'
map global object t '<a-semicolon>lsp-object Class Interface Struct<ret>' -docstring 'LSP class interface or struct'
map global object d '<a-semicolon>lsp-diagnostic-object --include-warnings<ret>' -docstring 'LSP errors and warnings'
map global object D '<a-semicolon>lsp-diagnostic-object<ret>' -docstring 'LSP errors'
Note
|
Contents below corresponds to the master branch HEAD and could be slightly out-of-sync with the version installed from pre-built binaries. The most common case is new commands being in a pre-release testing stage. Please refer to the README.asciidoc revision tagged with the version you use or the README.asciidoc from the release archive. |
If you have followed above steps you get
-
completions
-
lsp-definition
command to go to definition, mapped togd
by default -
lsp-hover
command to show hover info (including relevant diagnostics when available) in the info box.-
lsp-hover-buffer
command to show the same in a scratch buffer. -
to automatically show hover when you move around, use
lsp-auto-hover-enable
orlsp-auto-hover-buffer-enable
. -
to show hover anchored to hovered position, use
set global lsp_hover_anchor true
-
to exclude diagnostics, use
set-option global lsp_show_hover_format 'printf %s "${lsp_info}"'
-
-
lsp-declaration
command to jump to the declaration of the symbol under the main cursor -
lsp-definition
command to jump to the definition of the symbol under the main cursor -
lsp-type-definition
command to jump to the definition of the type of the symbol under the main cursor, mapped togy
by default -
lsp-implementation
command to find implementations for the symbol under the main cursor -
lsp-references
command to find references to the symbol under the main cursor, mapped togr
by default-
for the previous five commands, the
*goto*
buffer has filetypelsp-goto
, so you can press<ret>
on a line or use thejump
command
-
-
lsp-find-error
command to jump to the next or previous error in the current file-
lsp-selection-range
command to quickly select interesting ranges around selections. -
lsp-selection-range-select
to navigate ranges fetched bylsp-selection-range
. -
A polyfill of Kakoune’s
jump-
commands to jump to the next or previous location listed in a buffer with thelsp-goto
filetype. These also work for buffers\*grep
,*lint*
and*make*
-
-
lsp-highlight-references
command to select (unless run in a hook context) all references to the symbol under the main cursor in the current buffer and highlight them with theReference
face (which is equal to theMatchingChar
face by default) -
lsp-document-symbol
command to list the current buffer’s symbols in a buffer of typelsp-document-symbol
-
lsp-goto-document-symbol
command to jump to one of the current buffer’s symbols -
lsp-workspace-symbol
command to list project-wide symbols matching the query -
lsp-workspace-symbol-incr
command to incrementally list project-wide symbols matching the query-
*symbols*
buffer has filetypelsp-goto
so you can press<ret>
on a line or use thejump
command
-
-
lsp-diagnostics
command to list project-wide diagnostics (current buffer determines project and language to collect diagnostics for)-
*diagnostics*
buffer has filetypelsp-diagnostics
so you can press<ret>
on a line or use thejump
command
-
-
lsp-incoming-calls
andlsp-outgoing-calls
commands to list callers and callees of the function at the cursor.-
*callers*
and*callees*
buffers have filetypelsp-goto
so you can press<ret>
on a line or use thejump
command
-
-
lsp-signature-help
command to show signature information of the function under the main cursor-
To automatically show signature information in insert mode, use
lsp-auto-signature-help-enable
.
-
-
inline diagnostics highlighting using the
DiagnosticError
,DiagnosticHint
,DiagnosticInfo
andDiagnosticWarning
faces; can be disabled withlsp-inline-diagnostics-disable
command -
flags in the left margin on lines with errors or other diagnostics; can be disabled with
lsp-diagnostic-lines-disable
command -
for lines with code lenses, a
>
flag which can be customized via thelsp_code_lens_sign
option -
lsp-code-lens
command to execute a code lens from the current selection -
commands
lsp-inlay-code-lenses-enable
andlsp-inlay-code-lenses-disable
to toggle rendering of code lenses. -
You can change the code lenses' face with
set-face global InlayCodeLens <face>
. -
lsp-formatting
command to format current buffer, according to thetabstop
andlsp_insert_spaces
options -
lsp-formatting-sync
command to format current buffer synchronously, suitable for use withBufWritePre
hook:
hook global WinSetOption filetype=rust %{
hook window BufWritePre .* lsp-formatting-sync
}
-
lsp-object
command to select adjacent or surrounding syntax tree nodes in [object mode](https://github.com/mawww/kakoune/blob/master/doc/pages/modes.asciidoc#object-mode)-
lsp-diagnostic-object
does something similar but for inline diagnostics.
-
-
lsp-next-symbol
andlsp-previous-symbol
command to go to the buffer’s next and current/previous symbol. -
lsp-hover-next-symbol
andlsp-hover-previous-symbol
to show hover of the buffer’s next and current/previous symbol. -
lsp-rename <new_name>
andlsp-rename-prompt
commands to rename the symbol under the main cursor. -
Breadcrumbs in the modeline indicating the symbol around the main cursor, like (
somemodule > someclass > somefunction
).-
To implement this, kakoune-lsp adds
%opt{lsp_modeline} ` to the front of your global `modelinefmt
at load time.
-
-
An hourglass character (⌛) in the modeline whenever the language server indicates it’s busy.
-
To customize this behavior, override
lsp-handle-progress
.
-
-
If
lsp_auto_show_code_actions
istrue
, a lightbulb (💡) in the modeline whenever code actions are available at the main cursor position-
To customize the lightbulb, you can override
lsp-show-code-actions
andlsp-hide-code-actions
-
-
lsp-code-actions
to open a menu to choose a code action to run-
To customize the menu, you can override
lsp-perform-code-action
-
-
lsp-code-action
to run the code action matching the given pattern. -
lsp-code-action-sync
to synchronously run that code action, suitable for use in aBufWritePre
hook. -
lsp_diagnostic_error_count
,lsp_diagnostic_hint_count
,lsp_diagnostic_info_count
andlsp_diagnostic_warning_count
options which contain the number of diagnostics of the respective level for the current buffer. For example, you can put it into your modeline to see at a glance if there are errors in the current file -
starting new kak-lsp session when Kakoune session begins and stopping it when Kakoune session ends
-
lsp-execute-command
command to execute server-specific commands (listed bylsp-capabilities
). -
Commands starting with either of
ccls-
,clangd-
,ejdtls-
,texlab-
orrust-analyzer-
, that provide server specific features.
Note
|
By default, kak-lsp exits when it doesn’t receive any request from Kakoune for 30 minutes,
even if the Kakoune session is still up and running. Change server.timeout in kak-lsp.toml
to tweak this duration, or set it to 0 to disable this behavior. In any scenario, a new request
would spin up a fresh server if it is down.
|
-
lsp
user mode with the following default mappings:
Binding | Command |
---|---|
a |
lsp-code-actions |
c |
lsp-capabilities |
d |
lsp-definition |
e |
lsp-diagnostics |
f |
lsp-formatting |
h |
lsp-hover |
i |
lsp-implementation |
j |
lsp-outgoing-calls |
k |
lsp-incoming-calls |
l |
lsp-code-lens |
r |
lsp-references |
R |
lsp-rename-prompt |
s |
lsp-goto-document-symbol |
S |
lsp-document-symbol |
o |
lsp-workspace-symbol-incr |
n |
lsp-find-error |
p |
lsp-find-error --previous |
v |
lsp-selection-range |
y |
lsp-type-definition |
9 |
lsp-hover-previous-function |
0 |
lsp-hover-next-function |
& |
lsp-highlight-references |
( |
lsp-previous-function |
) |
lsp-next-function |
[ |
lsp-hover-previous-symbol |
] |
lsp-hover-next-symbol |
{ |
lsp-previous-symbol |
} |
lsp-next-symbol |
To know which subset of LSP commands is backed by the current buffer’s filetype’s language server use
lsp-capabilities
command.
kakoune-lsp itself has configuration, but it also adds configuration options to Kakoune that affect the Kakoune integration.
kakoune-lsp is configured via a configuration file in TOML format. By
default it tries to read $XDG_CONFIG_HOME/kak-lsp/kak-lsp.toml
(which defaults to
~/.config/kak-lsp/kak-lsp.toml
) but you can override it with command-line option --config
.
Look into the default kak-lsp.toml
, it should be quite self-explanatory.
If you don’t need to change configuration then feel free to skip copying it anywhere as the
default configuration is embedded into the kak-lsp binary.
Important: The configuration file does not extend the default configuration, but rather overrides it. This means that if you want to customize any of the configuration, you must copy the entire default configuration and then edit it.
In the language section of kak-lsp.toml
, the roots
parameter is a list of file globs.
Whenever your editor session wants to send an LSP request, the first glob that matches a file
in any of the current buffer’s parent directories will cause kakoune-lsp to set the project root
to that parent directory.
You can define an environment variable like KAK_LSP_PROJECT_ROOT_RUST=/my/project
to always
use /my/project
as root for Rust files inside /my/project
. Substitute RUST
with another
capitalized language ID to do the same for other file types.
The environment variable KAK_LSP_FORCE_PROJECT_ROOT=/my/project
will make kakoune-lsp always
use /my/project
as project root, even for files outside this directory. This avoids starting
separate language servers for files outside /my/project
, and ensures that your language server
is aware of your project’s build configuration even when navigating library code.
If you are setting any server options via cli, do not forget to append them to
%sh{kak-lsp --kakoune …}
in your kakrc
. It’s not needed if you change options in
~/.config/kak-lsp/kak-lsp.toml
.
Please let us know if you have any ideas about how to make the default config more sensible.
Many servers accept configuration options that are not part of the LSP spec. The TOML table
[language_server.<server_name>.settings]
holds those configuration options. It has the same structure
as the corresponding fragments from VSCode’s settings.json
. For example:
[language_server.gopls]
...
settings_section = "gopls" # Optional, defaults to server name.
[language_server.gopls.settings.gopls]
"formatting.gofumpt" = true
During server initialization, kakoune-lsp sends either the section specified by settings_section
,
or the section with same name as the server; in this case {"formatting.gofumpt":true}
.
Whenever you change the Kakoune option lsp_config
, the same section is sent via
workspace/didChangeConfiguration
. Additionally, kakoune-lsp will send arbitrary sections that
are requested by the server in workspace/configuration
.
By default, the Kakoune filetype is sent to the server as LSP language ID.
To send a different identifier for a given filetype, use the [language_ids]
config option, see the example below.
It is possible to map more than one language server to a filetype. For example, if you want to set up TSServer and TailwindCSS to use in React projects:
[language_ids]
javascript = "javascriptreact"
typescript = "typescriptreact"
[language_server.typescript-language-server]
filetypes = ["javascript", "typescript"]
roots = ["package.json", "tsconfig.json", "jsconfig.json", ".git", ".hg"]
args = ["--stdio"]
[language_server.tailwindcss-language-server]
filetypes = ["javascript", "typescript"]
roots = ["tailwind.config.ts", "tailwind.config.js"]
args = ["--stdio"]
[language_server.tailwindcss.settings.tailwindcss]
editor = {}
kakoune-lsp declares the following Kakoune options:
-
lsp_completion_trigger
(str): This option is set to a Kakoune command, which is executed every time the user pauses in insert mode. If the command succeeds, kakoune-lsp will send a completion request to the language server. -
lsp_diagnostic_line_error_sign
,lsp_diagnostic_line_hint_sign
,lsp_diagnostic_line_info_sign
, andlsp_diagnostic_line_warning_sign
(str): When usinglsp-diagnostic-lines-enable
and the language server detects an error or another diagnostic, kakoune-lsp will add a flag to the left-most column of the window, using this string and one of the corresponding facesLineFlagError
,LineFlagHint
,LineFlagInfo
orLineFlagWarning
. -
lsp_hover_anchor
(bool): When usinglsp-hover
orlsp-auto-hover-enable
, if this option istrue
then the hover information will be displayed next to the active selection. Otherwise, the information will be displayed in a box in the lower-right corner. -
lsp_hover_max_info_lines
(int): If greater than 0 then limit information in the hover box to the given number of lines. Default is 20. -
lsp_hover_max_diagnostic_lines
(int): If greater than 0 then limit diagnostics in the hover box to the given number of lines. Default is 20. -
lsp_hover_insert_mode_trigger
(str): This option is set to a Kakoune command. When usinglsp-auto-hover-insert-mode-enable
, this command is executed every time the user pauses in insert mode. If the command succeeds, kakoune-lsp will send a hover-information request for the text selected by the command. -
lsp_insert_spaces
(bool): When usinglsp-formatting
, if this option istrue
, kakoune-lsp will ask the language server to indent with spaces rather than tabs. -
lsp_auto_highlight_references
(bool): If this option istrue
thenlsp-highlight-references
is executed every time the user pauses in normal mode. -
lsp_auto_show_code_actions
(bool): If this option istrue
thenlsp-code-actions
is executed every time the user pauses in normal mode. -
lsp_config
(str): This is a TOML string of the same format askak-lsp.toml
, except it currently only supports one kind of configuration value:-
[language_server.<server_name>.settings]
: this works just like the static configuration of the same name inkak-lsp.toml
, see the section about server-specific configuration. This will override the static configuration of the given language server.
-
For example, you can toggle an option dynamically with a command like this:
set-option global lsp_config %{
[language_server.gopls.settings.gopls]
"formatting.gofumpt" = true
}
Inlay hints are a feature proposed for LSP 3.17 to show inferred types, parameter names in function calls, and the types of chained calls inline in the code. To enable support for it, add the following to your kakrc
:
lsp-inlay-hints-enable global
You can change the hints' face with set-face global InlayHint <face>
.
kakoune-lsp supports the semanticTokens feature for semantic highlighting. If the language server supports it, you can enable it with:
hook global WinSetOption filetype=<language> %{
hook window -group semantic-tokens BufReload .* lsp-semantic-tokens
hook window -group semantic-tokens NormalIdle .* lsp-semantic-tokens
hook window -group semantic-tokens InsertIdle .* lsp-semantic-tokens
hook -once -always window WinSetOption filetype=.* %{
remove-hooks window semantic-tokens
}
}
The faces used for semantic tokens and modifiers can be modified in kak-lsp.toml
, using the semantic_tokens.faces
array, for example:
[semantic_tokens]
faces = [
{face="const_variable_declaration", token="variable", modifiers=["constant", "declaration"]},
]
where face
is the face that will be applied in Kakoune (you’ll want to define these in your theme/config), token
is the token’s name as reported by the language server (see lsp-capabilities
) and modifiers
is an array of modifier names (also reported by the language server). modifiers
may be omitted, but token
and face
are required.
You may create any arbitrary number of definitions with permutations between the token names and modifiers reported by the server. For an entry to match a token, all the entry’s modifiers must exist on the token. However, the token may have additional modifiers not assigned in the config entry.
kakoune-lsp will find the most specific matching configuration to apply, where specificity is defined as the number of matching modifiers. If multiple matching entries have the same number of modifiers, the one that was defined last in the configuration wins.
Example:
Assuming the following configuration,
[semantic_tokens]
faces = [
{face="const_variable_declaration", token="variable", modifiers=["constant","declaration"]},
{face="const_variable", token="variable", modifiers=["constant"]},
{face="variable", token="variable"},
]
kakoune-lsp will perform these mappings:
Token | Modifiers | Face | Comment |
---|---|---|---|
|
|
|
First entry matches with 2 modifiers. |
|
|
|
First and second entry match with 1 modifier, second wins. |
|
|
|
Only third entry matches. First entry doesn’t match, because |
|
|
Third entry matches. |
|
|
No entries match and no face is applied. |
kakoune-lsp supports showing diagnostics inline after their respective line, but this behavior can be somewhat buggy and must be enabled explicitly:
lsp-inlay-diagnostics-enable global
kakoune-lsp shows some additional information provided by the language server in an info box. This information includes documentation for the token under the cursor (lsp-hover
) and documentation for completion candidates. In both cases, the Language Server Protocol allows for both plain text and Markdown, and most servers do implement Markdown.
To make use of Markdown, kakoune-lsp transpiles it into Kakoune’s markup language, utilizing various faces for styling.
These faces all default to the Information
face, to ensure that the text in the info box works with any color scheme.
To enable Markdown highlighting, define some of the following faces in your theme or kakrc
:
Face | Usage |
---|---|
|
The default text color. You’ll likely want to leave this at the default |
|
The face used for code blocks. Language specific syntax highlighting for code blocks is not supported. |
|
The face used for block quotes. The |
|
The face used to highlight the list symbol for both ordered and unordered lists. For list items' text, |
|
The face used for headings. There is currently no distinction between different heading levels. |
|
The face used to highlight link titles. Maybe some classic |
|
This face is assigned to inline code spans within link titles, such as in the following Markdown snippet. Here, the word [the `format` function](https://example.com) |
|
The face used for inline code spans (backtick strings). |
|
The face used for horizontal lines (rules). |
|
Used for error messages in the diagnostics inside hover info. This defaults to Kakoune’s built-in |
|
Used for hints in the diagnostics inside hover info. |
|
Used for informational messages in the diagnostics inside hover info. |
|
Used for warnings in the diagnostics inside hover info. |
For convenience, here is a snippet to paste into your theme/config:
face global InfoDefault Information
face global InfoBlock Information
face global InfoBlockQuote Information
face global InfoBullet Information
face global InfoHeader Information
face global InfoLink Information
face global InfoLinkMono Information
face global InfoMono Information
face global InfoRule Information
face global InfoDiagnosticError Information
face global InfoDiagnosticHint Information
face global InfoDiagnosticInformation Information
face global InfoDiagnosticWarning Information
Current limitations of this feature are:
-
Language specific syntax highlighting for code blocks is not supported.
-
For hyperlinks, only their title (the pretty name) is shown.
-
The original syntax for headings is retained to visualize their level.
Snippets are completions that come with placeholders ("tabstops") in the places you likely want
to insert text (for example function call arguments). The placeholders are highlighted with
the two faces SnippetsNextPlaceholders
and SnippetsOtherPlaceholders
.
The lsp-snippets-select-next-placeholders
command allows to jump to the next tabstop (like
function call arguments). The suggested mapping uses <tab>
(see [Configure mappings]). Here’s
a way to bind it to <c-n>
instead (might need to hide the completion menu with Kakoune’s
<c-o>
command):
map global insert <c-n> '<a-;>:lsp-snippets-select-next-placeholders<ret>' -docstring 'Select next snippet placeholder'
hook global InsertCompletionShow .* %{
unmap global insert <c-n> '<a-;>:lsp-snippets-select-next-placeholders<ret>'
}
hook global InsertCompletionHide .* %{
map global insert <c-n> '<a-;>:lsp-snippets-select-next-placeholders<ret>' -docstring 'Select next snippet placeholder'
}
Snippet support can be disabled by setting snippet_support = false
at the top level of the config.
workspace/didChangeWatchedFiles
is disabled by default; use watch_file_support = true
to enable it.
The LSP spec says that column offsets (Position.character
) are to be
interpreted as UTF-16 code units. Many servers violate the spec. Please refer to
microsoft/language-server-protocol#376 for some background.
kakoune-lsp adheres to the spec but will prefer UTF-8 offsets if the server advertises
support for UTF-8 offsets via client capabilities general.positionEncodings
or
clangd protocol extension.
If kakoune-lsp fails try to put this line in your kakrc
after kak-lsp --kakoune
invocation:
set global lsp_cmd "kak-lsp -s %val{session} -vvv --log /tmp/kak-lsp.log"
to enable debug logging.
If it does not give enough insight to fix the problem or if the problem is a bug in kakoune-lsp itself please don’t hesitate to raise an issue.
Please also try to reproduce the issue with a minimal configuration. Sometimes the problem occurs only with specific settings in your ~/.config/kak-lsp/kak-lsp.toml
and/or ~/.config/kak/
. Use this command to start Kakoune with kakoune-lsp enabled, both with pristine settings.
env -u XDG_CONFIG_HOME HOME=$(mktemp -d) kak -e '
eval %sh{kak-lsp --kakoune}
set global lsp_cmd "kak-lsp -s %val{session} -vvvv --log /tmp/kak-lsp.log"
lsp-enable'
kakoune-lsp follows SemVer with one notable difference from common practice: we don’t use 0 major version to indicate that product is not yet reached stability. Even for non-stable and not feature-complete product user should be clearly informed about breaking change. Therefore we start with major version 1 and increment it each time when upgrade requires user’s attention.