| =================== |
| Protocol extensions |
| =================== |
| |
| .. contents:: |
| |
| clangd supports some features that are not in the official |
| `Language Server Protocol specification |
| <https://microsoft.github.io/language-server-protocol/specification>`__. |
| |
| We cautious about adding extensions. The most important considerations are: |
| |
| - **Editor support**: How many users will the feature be available to? |
| - **Standardization**: Is the feature stable? Is it likely to be adopted by more |
| editors over time? |
| - **Utility**: Does the feature provide a lot of value? |
| - **Complexity**: Is this hard to implement in clangd, or constrain future work? |
| Is the protocol complicated? |
| |
| These extensions may evolve or disappear over time. If you use them, try to |
| recover gracefully if the structures aren't what's expected. |
| |
| Switch between the implementation file and the header |
| ===================================================== |
| |
| *This extension is supported in clangd 6 and newer.* |
| |
| Switching between the implementation file and the header is an important |
| feature for C++. A language server that understands C++ can do a better job |
| than the editor. |
| |
| **New client->server request**: ``textDocument/switchSourceHeader``. |
| |
| Lets editors switch between the main source file (``*.cpp``) and header (``*.h``). |
| |
| Parameter: ``TextDocumentIdentifier``: an open file. |
| |
| Result: ``string``: the URI of the corresponding header (if a source file was |
| provided) or source file (if a header was provided). |
| |
| If the corresponding file can't be determined, ``""`` is returned. |
| |
| File status |
| =========== |
| |
| *This extension is supported in clangd 8 and newer.* |
| |
| It is important to provide feedback to the user when the UI is not responsive. |
| |
| This extension provides information about activity on clangd's per-file worker |
| thread. This information can be displayed to users to let them know that the |
| language server is busy with something. For example, in clangd, building the |
| AST blocks many other operations. |
| |
| **New server->client notification**: ``textDocument/clangd.fileStatus`` |
| |
| Sent when the current activity for a file changes. Replaces previous activity |
| for that file. |
| |
| Parameter: ``FileStatus`` object with properties: |
| |
| - ``uri : string``: the document whose status is being updated. |
| - ``state : string``: human-readable information about current activity. |
| |
| **New initialization option**: ``initializationOptions.clangdFileStatus : bool`` |
| |
| Enables receiving ``textDocument/clangd.fileStatus`` notifications. |
| |
| Compilation commands |
| ==================== |
| |
| *This extension is supported in clangd 8 and newer.* |
| |
| clangd relies on knowing accurate compilation options to correctly interpret a |
| file. Typically they are found in a ``compile_commands.json`` file in a |
| directory that contains the file, or an ancestor directory. The following |
| extensions allow editors to supply the commands over LSP instead. |
| |
| **New initialization option**: ``initializationOptions.compilationDatabasePath : string`` |
| |
| Specifies the directory containing the compilation database (e.g., |
| ``compile_commands.json``). This path will be used for all files, instead of |
| searching their ancestor directories. |
| |
| **New initialization option**: ``initializationOptions.fallbackFlags : string[]`` |
| |
| Controls the flags used when no specific compile command is found. The compile |
| command will be approximately ``clang $FILE $fallbackFlags`` in this case. |
| |
| **New configuration setting**: ``settings.compilationDatabaseChanges : {string: CompileCommand}`` |
| |
| Provides compile commands for files. This can also be provided on startup as |
| ``initializationOptions.compilationDatabaseChanges``. |
| |
| Keys are file paths (Not URIs!) |
| |
| Values are ``{workingDirectory: string, compilationCommand: string[]}``. |
| |
| Force diagnostics generation |
| ============================ |
| |
| *This extension is supported in clangd 7 and newer.* |
| |
| 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: |
| |
| - diagnostics do not get too stale, |
| - if you stop editing, diagnostics will catch up. |
| |
| This extension allows editors to force diagnostics to be generated or not |
| generated at a particular revision. |
| |
| **New property of** ``textDocument/didChange`` **request**: ``wantDiagnostics : bool`` |
| |
| - if true, diagnostics will be produced for exactly this version. |
| - if false, diagnostics will not be produced for this version, even if there |
| are no further edits. |
| - if unset, diagnostics will be produced for this version or some subsequent |
| one in a bounded amount of time. |
| |
| Diagnostic categories |
| ===================== |
| |
| *This extension is supported in clangd 8 and newer.* |
| |
| Clang compiler groups diagnostics into categories (e.g., "Inline Assembly |
| Issue"). Clangd can emit these categories for interested editors. |
| |
| **New property of** ``Diagnostic`` **object**: ``category : string``: |
| |
| A human-readable name for a group of related diagnostics. Diagnostics with the |
| same code will always have the same category. |
| |
| **New client capability**: ``textDocument.publishDiagnostics.categorySupport``: |
| |
| Requests that clangd send ``Diagnostic.category``. |
| |
| Inline fixes for diagnostics |
| ============================ |
| |
| *This extension is supported in clangd 8 and newer.* |
| |
| LSP specifies that code actions for diagnostics (fixes) are retrieved |
| asynchronously using ``textDocument/codeAction``. clangd always computes fixes |
| eagerly. Providing them alongside diagnostics can improve the UX in editors. |
| |
| **New property of** ``Diagnostic`` **object**: ``codeActions : CodeAction[]``: |
| |
| All the code actions that address this diagnostic. |
| |
| **New client capability**: ``textDocument.publishDiagnostics.codeActionsInline : bool`` |
| |
| Requests clangd to send ``Diagnostic.codeActions``. |
| |
| Symbol info request |
| =================== |
| |
| *This extension is supported in clangd 8 and newer.* |
| |
| **New client->server request**: ``textDocument/symbolInfo``: |
| |
| This request attempts to resolve the symbol under the cursor, without |
| retrieving further information (like definition location, which may require |
| consulting an index). This request was added to support integration with |
| indexes outside clangd. |
| |
| Parameter: ``TextDocumentPositionParams`` |
| |
| Response: ``SymbolDetails``, an object with properties: |
| |
| - ``name : string`` the unqualified name of the symbol |
| - ``containerName : string`` the enclosing namespace, class etc (without |
| trailing ``::``) |
| - ``usr : string``: the clang-specific "unified symbol resolution" identifier |
| - ``id : string?``: the clangd-specific opaque symbol ID |