Protocol extensions

clangd supports some features that are not in the official Language Server Protocol specification.

We try to do this sparingly. The most important considerations are:

These extensions may evolve or disappear over time. If you use them, try to recover gracefully if the structures aren’t what’s expected.

Contents

Switch between source/header

Lets editors switch between the main source file (*.cpp) and header (*.h).

New client->server request: textDocument/switchSourceHeader.

If the corresponding file can’t be determined, "" is returned. bug?

File status

Provides information about activity on clangd’s per-file worker thread. This can be relevant to users as building the AST blocks many other operations.

New server->client notification: textDocument/clangd.fileStatus

New initialization option: initializationOptions.clangdFileStatus : bool

Compilation commands

clangd relies on having accurate compilation commands to correctly interpret a file. Typically these are discovered via a compile_commands.json file in a parent directory. These extensions allow editors to supply the commands over LSP instead.

New initialization option: initializationOptions.compilationDatabasePath : string

New initialization option: initializationOptions.fallbackFlags : string[]

New configuration setting: settings.compilationDatabaseChanges : {string: CompileCommand}

Force diagnostics generation

Clangd does not regenerate diagnostics for every version of a file (e.g. after every keystroke), as that would be too slow. Its heuristics ensure:

This extension allows editors to force diagnostics to be generated/not generated at a particular revision.

New property of textDocument/didChange request: wantDiagnostics : bool

Diagnostic categories

Clang groups diagnostics into categories (e.g. “Inline Assembly Issue”). Clangd can emit these categories for interested editors.

New property of Diagnostic object: category : string:

New client capability: textDocument.publishDiagnostics.categorySupport:

Inline fixes for diagnostics

LSP specifies that code actions for diagnostics (fixes) are retrieved asynchronously using textDocument/codeAction. However clangd always computes these eagerly, and providing them alongside diagnostics can improve the UX in editors.

New property of Diagnostic object: codeActions : CodeAction[]:

New client capability: textDocument.publishDiagnostics.codeActionsInline : bool

Symbol info request

This attempts to resolve the symbol under the cursor, without retrieving further information (like definition location, which may require consulting an index). This was added to support integration with indexes outside clangd.

New client->server request: textDocument/symbolInfo:

UTF-8 offsets

LSP specifies that offsets within lines are in UTF-16 code units (for Positions and also delta-encoded document updates). This unusual is an unfortunate legacy of VSCode’s JavaScript implementation.

clangd allows clients to use UTF-8 offsets instead. This allows clients that always speak UTF-8 (in violation of the protocol) to work correctly, and those that are UTF-8 native to avoid unneccesary transcoding (which may be slow if implemented in e.g. vimscript).

New client capability: offsetEncoding : string[]:

Lists the encodings the client supports, in preference order. It SHOULD include "utf-16". If not present, it is assumed to be ["utf-16"]

Well-known encodings are:

New InitializeResponse property: offsetEncoding: string:

Advice for clients using this extension:

Advice for servers using this extension:

Code completion scores

LSP gives servers limited control over completion display order through the sortText attribute. Clangd uses several signals such as number of usages to ensure the most likely completions are near the top.

However as the user continues to type, editors filter and re-rank the results on the client side. This re-ranking should take into account the signals from the server, but LSP does not expose them.

New CompletionItem property: score: number: