1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
|
===================
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
|
