LSP Client Plugin

The LSP Client plugin provides many language features such as code completion, code navigation or finding references based on the Language Server Protocol.

Once you have enabled the LSP Client in the plugin page, a new page called LSP Client will appear in your Kate configuration dialog.

Menu Structure

If appropriate, a corresponding LSP command is also mentioned in the explanation below, the documentation of which may then provide additional background and interpretation, though it may vary depending on the actual language. The phrase 'current symbol' refers to the symbol corresponding to the current cursor position, as so determined by the language and server implementation.

LSP ClientGo to Definition

[textDocument/definition] Go to current symbol definition.

LSP ClientGo to Declaration

[textDocument/declaration] Go to current symbol declaration.

LSP ClientFind References

[textDocument/references] Find references to current symbol.

LSP ClientHighlight

[textDocument/documentHighlight] Highlight current symbol references in current document.

LSP ClientHover

[textDocument/hover] Hover info for current symbol.

LSP ClientFormat

[textDocument/formatting] [textDocument/rangeFormatting] Format the current document or current selection.

LSP ClientRename

[textDocument/rename] Rename current symbol.

LSP ClientShow selected completion documentation

Show documentation for a selected item in the completion list.

LSP ClientInclude declaration in references

Request to include a symbol's declaration when requesting references.

LSP ClientShow hover information

Show hover information upon (mouse cursor) hover. Regardless of this setting, the request can always be manually initiated.

LSP ClientFormat on typing

[document/onTypeFormatting] Format parts of document when typing certain trigger characters. For example, this might apply indentation upon newline, or as otherwise determined by LSP Server. Note that editor indentation scripts might be trying to do the same (depending on the mode) and so it may not be advisable to have both enabled at the same time.

LSP ClientIncremental document synchronization

Send partial document edits to update the server rather than whole document text (if supported).

LSP ClientShow diagnostics notifications

[textDocument/publishDiagnostics] Process and show diagnostics notifications sent by server.

LSP ClientShow diagnostics highlights

Add text highlights for ranges indicated in diagnostics.

LSP ClientShow diagnostics marks

Add document marks for lines indicated in diagnostics.

LSP ClientSwitch to diagnostic tab

Switch to the diagnostic tab in the plugin toolview.

LSP ClientClose all non-diagnostics tabs

Close all non-diagnostics (e.g. references) tabs in plugin toolview.

LSP ClientRestart LSP Server

Restart current document's LSP Server.

LSP ClientRestart all LSP Servers

Stop all LSP Servers which will then be (re)started as needed.

Configuration

The plugin's configuration page mostly allows for persistent configuration of some of the above menu items. However, there is one additional entry to specify the Server Configuration file. This is a JSON file that can be used to specify the LSP server to start (and then to communicate with over stdin/stdout). For convenience, the following default configuration is included (though alternative server implementation are equally valid and possible):

{
    "servers": {
        "bibtex": {
            "use": "latex",
            "highlightingModeRegex": "^BibTeX$"
        },
        "c": {
            "command": ["clangd", "-log=error", "--background-index"],
            "commandDebug": ["clangd", "-log=verbose", "--background-index"],
            "url": "https://clang.llvm.org/extra/clangd/",
            "highlightingModeRegex": "^(C|ANSI C89|Objective-C)$"
        },
        "cpp": {
            "use": "c",
            "highlightingModeRegex": "^(C\\+\\+|ISO C\\+\\+|Objective-C\\+\\+)$"
        },
        "d": {
            "command": ["dls", "--stdio"],
            "url": "https://github.com/d-language-server/dls",
            "highlightingModeRegex": "^D$"
        },
        "fortran": {
            "command": ["fortls"],
            "rootIndicationFileNames": [".fortls"],
            "url": "https://github.com/hansec/fortran-language-server",
            "highlightingModeRegex": "^Fortran.*$"
        },
        "latex": {
            "command": ["texlab"],
            "url": "https://texlab.netlify.com/",
            "highlightingModeRegex": "^LaTeX$"
        },
        "go": {
            "command": ["go-langserver"],
            "commandDebug": ["go-langserver", "-trace"],
            "url": "https://github.com/sourcegraph/go-langserver",
            "highlightingModeRegex": "^Go$"
        },
        "python": {
            "command": ["python3", "-m", "pyls", "--check-parent-process"],
            "url": "https://github.com/palantir/python-language-server",
            "highlightingModeRegex": "^Python$"
        },
        "rust": {
            "command": ["rls"],
            "rootIndicationFileNames": ["Cargo.lock", "Cargo.toml"],
            "url": "https://github.com/rust-lang/rls",
            "highlightingModeRegex": "^Rust$"
        },
        "ocaml": {
            "command": ["ocamlmerlin-lsp"],
            "url": "https://github.com/ocaml/merlin",
            "highlightingModeRegex": "^Objective Caml.*$"
        }
    }
}

Note that each "command" may be an array or a string (in which case it is split into an array). Also, a top-level "global" entry (next to "server") is considered as well (see further below).

The "highlightingModeRegex" is used to map the highlighting mode as used by Kate to the language id of the server. If no regular expression is given, the language id itself is used.

From the above example, the gist is presumably clear. In addition, each server entry object may also have an "initializationOptions" entry, which is passed along to the server as part of the 'initialize' method. If present, a "settings" entry is passed to the server by means of the 'workspace/didChangeConfiguration' notification.

Various stages of override/merge are applied;

  • user configuration (loaded from file) overrides (internal) default configuration

  • "lspclient" entry in .kateproject project configuration overrides the above

  • the resulting "global" entry is used to supplement (not override) any server entry

One server instance is used per (root, servertype) combination. If "root" is specified as an absolute path, then it used as-is, otherwise it is relative to the projectBase (as determined by the Project plugin). If not specified and "rootIndicationFileNames" is an array as filenames, then a parent directory of current document containing such a file is selected. As a last fallback, the home directory is selected as "root". For any document, the resulting "root" then determines whether or not a separate instance is needed. If so, the "root" is passed as rootUri/rootPath.

In general, it is recommended to leave root unspecified, as it is not that important for a server (your mileage may vary though). Fewer server instances are obviously more efficient, and they also have a 'wider' view than the view of many separate instances.

LSP Server Configuration

Each particular LSP server has its own way of customization and may use language/tool specific means for configuration, e.g. tox.ini (a.o. for python), .clang-format for C++ style format. Such configuration may then also be used by other (non-LSP) tools (such as then tox or clang-format). On top of that, some LSP servers also load configuration from custom files (e.g. .ccls). Furthermore, custom server configuration can also be passed through LSP (protocol), see the aforementioned "initializationOptions" and "settings" entries in server configuration.

Since various level of override/merge are applied, the following example of user specified client configuration tweaks some python-language-server configuration.

{
    "servers": {
        "python": {
            "settings": {
                "pyls": {
                    "plugins": {
                        "pylint": {
                            "enable": true
                        }
                    }
                }
            }
        }
    }
}

Unfortunately, LSP server configuration/customization is often not so well documented, in ways that only examining the source code shows configuration approaches and the set of available configuration options. In particular, the above example's server supports many more options in "settings". See another LSP client's documentation for various other language server examples and corresponding settings, which can easily and readily be transformed to the JSON configuration that is used here and outlined above.