Debian Codegraph @

llvm-project/clang-tools-extra/docs/clang-tidy/index.rst

raw
1 ==========
2 Clang-Tidy
3 ==========
4
5 .. contents::
6
7 See also:
8
9 .. toctree::
10 :maxdepth: 1
11
12 The list of clang-tidy checks <checks/list>
13 Clang-tidy IDE/Editor Integrations <Integrations>
14 Getting Involved <Contributing>
15
16 :program:`clang-tidy` is a clang-based C++ "linter" tool. Its purpose is to
17 provide an extensible framework for diagnosing and fixing typical programming
18 errors, like style violations, interface misuse, or bugs that can be deduced via
19 static analysis. :program:`clang-tidy` is modular and provides a convenient
20 interface for writing new checks.
21
22
23 Using clang-tidy
24 ================
25
26 :program:`clang-tidy` is a `LibTooling`_-based tool, and it's easier to work
27 with if you set up a compile command database for your project (for an example
28 of how to do this, see `How To Setup Tooling For LLVM`_). You can also specify
29 compilation options on the command line after ``--``:
30
31 .. code-block:: console
32
33 $ clang-tidy test.cpp -- -Imy_project/include -DMY_DEFINES ...
34
35 :program:`clang-tidy` has its own checks and can also run Clang Static Analyzer
36 checks. Each check has a name and the checks to run can be chosen using the
37 ``-checks=`` option, which specifies a comma-separated list of positive and
38 negative (prefixed with ``-``) globs. Positive globs add subsets of checks, and
39 negative globs remove them. For example,
40
41 .. code-block:: console
42
43 $ clang-tidy test.cpp -checks=-*,clang-analyzer-*,-clang-analyzer-cplusplus*
44
45 will disable all default checks (``-*``) and enable all ``clang-analyzer-*``
46 checks except for ``clang-analyzer-cplusplus*`` ones.
47
48 The ``-list-checks`` option lists all the enabled checks. When used without
49 ``-checks=``, it shows checks enabled by default. Use ``-checks=*`` to see all
50 available checks or with any other value of ``-checks=`` to see which checks are
51 enabled by this value.
52
53 .. _checks-groups-table:
54
55 There are currently the following groups of checks:
56
57 ====================== =========================================================
58 Name prefix Description
59 ====================== =========================================================
60 ``abseil-`` Checks related to Abseil library.
61 ``altera-`` Checks related to OpenCL programming for FPGAs.
62 ``android-`` Checks related to Android.
63 ``boost-`` Checks related to Boost library.
64 ``bugprone-`` Checks that target bug-prone code constructs.
65 ``cert-`` Checks related to CERT Secure Coding Guidelines.
66 ``clang-analyzer-`` Clang Static Analyzer checks.
67 ``concurrency-`` Checks related to concurrent programming (including
68 threads, fibers, coroutines, etc.).
69 ``cppcoreguidelines-`` Checks related to C++ Core Guidelines.
70 ``darwin-`` Checks related to Darwin coding conventions.
71 ``fuchsia-`` Checks related to Fuchsia coding conventions.
72 ``google-`` Checks related to Google coding conventions.
73 ``hicpp-`` Checks related to High Integrity C++ Coding Standard.
74 ``linuxkernel-`` Checks related to the Linux Kernel coding conventions.
75 ``llvm-`` Checks related to the LLVM coding conventions.
76 ``llvmlibc-`` Checks related to the LLVM-libc coding standards.
77 ``misc-`` Checks that we didn't have a better category for.
78 ``modernize-`` Checks that advocate usage of modern (currently "modern"
79 means "C++11") language constructs.
80 ``mpi-`` Checks related to MPI (Message Passing Interface).
81 ``objc-`` Checks related to Objective-C coding conventions.
82 ``openmp-`` Checks related to OpenMP API.
83 ``performance-`` Checks that target performance-related issues.
84 ``portability-`` Checks that target portability-related issues that don't
85 relate to any particular coding style.
86 ``readability-`` Checks that target readability-related issues that don't
87 relate to any particular coding style.
88 ``zircon-`` Checks related to Zircon kernel coding conventions.
89 ====================== =========================================================
90
91 Clang diagnostics are treated in a similar way as check diagnostics. Clang
92 diagnostics are displayed by :program:`clang-tidy` and can be filtered out using
93 the ``-checks=`` option. However, the ``-checks=`` option does not affect
94 compilation arguments, so it cannot turn on Clang warnings which are not
95 already turned on in the build configuration. The ``-warnings-as-errors=``
96 option upgrades any warnings emitted under the ``-checks=`` flag to errors (but
97 it does not enable any checks itself).
98
99 Clang diagnostics have check names starting with ``clang-diagnostic-``.
100 Diagnostics which have a corresponding warning option, are named
101 ``clang-diagnostic-<warning-option>``, e.g. Clang warning controlled by
102 ``-Wliteral-conversion`` will be reported with check name
103 ``clang-diagnostic-literal-conversion``.
104
105 The ``-fix`` flag instructs :program:`clang-tidy` to fix found errors if
106 supported by corresponding checks.
107
108 An overview of all the command-line options:
109
110 .. code-block:: console
111
112 $ clang-tidy --help
113 USAGE: clang-tidy [options] <source0> [... <sourceN>]
114
115 OPTIONS:
116
117 Generic Options:
118
119 --help - Display available options (--help-hidden for more)
120 --help-list - Display list of available options (--help-list-hidden for more)
121 --version - Display the version of this program
122
123 clang-tidy options:
124
125 --checks=<string> -
126 Comma-separated list of globs with optional '-'
127 prefix. Globs are processed in order of
128 appearance in the list. Globs without '-'
129 prefix add checks with matching names to the
130 set, globs with the '-' prefix remove checks
131 with matching names from the set of enabled
132 checks. This option's value is appended to the
133 value of the 'Checks' option in .clang-tidy
134 file, if any.
135 --config=<string> -
136 Specifies a configuration in YAML/JSON format:
137 -config="{Checks: '*',
138 CheckOptions: {x, y}}"
139 When the value is empty, clang-tidy will
140 attempt to find a file named .clang-tidy for
141 each source file in its parent directories.
142 --config-file=<string> -
143 Specify the path of .clang-tidy or custom config file:
144 e.g. --config-file=/some/path/myTidyConfigFile
145 This option internally works exactly the same way as
146 --config option after reading specified config file.
147 Use either --config-file or --config, not both.
148 --dump-config -
149 Dumps configuration in the YAML format to
150 stdout. This option can be used along with a
151 file name (and '--' if the file is outside of a
152 project with configured compilation database).
153 The configuration used for this file will be
154 printed.
155 Use along with -checks=* to include
156 configuration of all checks.
157 --enable-check-profile -
158 Enable per-check timing profiles, and print a
159 report to stderr.
160 --explain-config -
161 For each enabled check explains, where it is
162 enabled, i.e. in clang-tidy binary, command
163 line or a specific configuration file.
164 --export-fixes=<filename> -
165 YAML file to store suggested fixes in. The
166 stored fixes can be applied to the input source
167 code with clang-apply-replacements.
168 --extra-arg=<string> - Additional argument to append to the compiler command line.
169 Can be used several times.
170 --extra-arg-before=<string> - Additional argument to prepend to the compiler command line.
171 Can be used several times.
172 --fix -
173 Apply suggested fixes. Without -fix-errors
174 clang-tidy will bail out if any compilation
175 errors were found.
176 --fix-errors -
177 Apply suggested fixes even if compilation
178 errors were found. If compiler errors have
179 attached fix-its, clang-tidy will apply them as
180 well.
181 --fix-notes -
182 If a warning has no fix, but a single fix can
183 be found through an associated diagnostic note,
184 apply the fix.
185 Specifying this flag will implicitly enable the
186 '--fix' flag.
187 --format-style=<string> -
188 Style for formatting code around applied fixes:
189 - 'none' (default) turns off formatting
190 - 'file' (literally 'file', not a placeholder)
191 uses .clang-format file in the closest parent
192 directory
193 - '{ <json> }' specifies options inline, e.g.
194 -format-style='{BasedOnStyle: llvm, IndentWidth: 8}'
195 - 'llvm', 'google', 'webkit', 'mozilla'
196 See clang-format documentation for the up-to-date
197 information about formatting styles and options.
198 This option overrides the 'FormatStyle` option in
199 .clang-tidy file, if any.
200 --header-filter=<string> -
201 Regular expression matching the names of the
202 headers to output diagnostics from. Diagnostics
203 from the main file of each translation unit are
204 always displayed.
205 Can be used together with -line-filter.
206 This option overrides the 'HeaderFilterRegex'
207 option in .clang-tidy file, if any.
208 --line-filter=<string> -
209 List of files with line ranges to filter the
210 warnings. Can be used together with
211 -header-filter. The format of the list is a
212 JSON array of objects:
213 [
214 {"name":"file1.cpp","lines":[[1,3],[5,7]]},
215 {"name":"file2.h"}
216 ]
217 --list-checks -
218 List all enabled checks and exit. Use with
219 -checks=* to list all available checks.
220 -load=<plugin> -
221 Load the dynamic object ``plugin``. This
222 object should register new static analyzer
223 or clang-tidy passes. Once loaded, the
224 object will add new command line options
225 to run various analyses. To see the new
226 complete list of passes, use the
227 :option:`--list-checks` and
228 :option:`-load` options together.
229 -p <string> - Build path
230 --quiet -
231 Run clang-tidy in quiet mode. This suppresses
232 printing statistics about ignored warnings and
233 warnings treated as errors if the respective
234 options are specified.
235 --store-check-profile=<prefix> -
236 By default reports are printed in tabulated
237 format to stderr. When this option is passed,
238 these per-TU profiles are instead stored as JSON.
239 --system-headers - Display the errors from system headers.
240 --use-color -
241 Use colors in diagnostics. If not set, colors
242 will be used if the terminal connected to
243 standard output supports colors.
244 This option overrides the 'UseColor' option in
245 .clang-tidy file, if any.
246 --verify-config -
247 Check the config files to ensure each check and
248 option is recognized.
249 --vfsoverlay=<filename> -
250 Overlay the virtual filesystem described by file
251 over the real file system.
252 --warnings-as-errors=<string> -
253 Upgrades warnings to errors. Same format as
254 '-checks'.
255 This option's value is appended to the value of
256 the 'WarningsAsErrors' option in .clang-tidy
257 file, if any.
258
259 -p <build-path> is used to read a compile command database.
260
261 For example, it can be a CMake build directory in which a file named
262 compile_commands.json exists (use -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
263 CMake option to get this output). When no build path is specified,
264 a search for compile_commands.json will be attempted through all
265 parent paths of the first input file . See:
266 https://clang.llvm.org/docs/HowToSetupToolingForLLVM.html for an
267 example of setting up Clang Tooling on a source tree.
268
269 <source0> ... specify the paths of source files. These paths are
270 looked up in the compile command database. If the path of a file is
271 absolute, it needs to point into CMake's source tree. If the path is
272 relative, the current working directory needs to be in the CMake
273 source tree and the file must be in a subdirectory of the current
274 working directory. "./" prefixes in the relative files will be
275 automatically removed, but the rest of a relative path must be a
276 suffix of a path in the compile command database.
277
278
279 Configuration files:
280 clang-tidy attempts to read configuration for each source file from a
281 .clang-tidy file located in the closest parent directory of the source
282 file. If InheritParentConfig is true in a config file, the configuration file
283 in the parent directory (if any exists) will be taken and current config file
284 will be applied on top of the parent one. If any configuration options have
285 a corresponding command-line option, command-line option takes precedence.
286 The effective configuration can be inspected using -dump-config:
287
288 $ clang-tidy -dump-config
289 ---
290 Checks: '-*,some-check'
291 WarningsAsErrors: ''
292 HeaderFilterRegex: ''
293 FormatStyle: none
294 InheritParentConfig: true
295 User: user
296 CheckOptions:
297 some-check.SomeOption: 'some value'
298 ...
299
300 .. _clang-tidy-nolint:
301
302 Suppressing Undesired Diagnostics
303 =================================
304
305 :program:`clang-tidy` diagnostics are intended to call out code that does not
306 adhere to a coding standard, or is otherwise problematic in some way. However,
307 if the code is known to be correct, it may be useful to silence the warning.
308 Some clang-tidy checks provide a check-specific way to silence the diagnostics,
309 e.g. `bugprone-use-after-move <checks/bugprone/use-after-move.html>`_ can be
310 silenced by re-initializing the variable after it has been moved out,
311 `bugprone-string-integer-assignment
312 <checks/bugprone/string-integer-assignment.html>`_ can be suppressed by
313 explicitly casting the integer to ``char``,
314 `readability-implicit-bool-conversion
315 <checks/readability/implicit-bool-conversion.html>`_ can also be suppressed by
316 using explicit casts, etc.
317
318 If a specific suppression mechanism is not available for a certain warning, or
319 its use is not desired for some reason, :program:`clang-tidy` has a generic
320 mechanism to suppress diagnostics using ``NOLINT``, ``NOLINTNEXTLINE``, and
321 ``NOLINTBEGIN`` ... ``NOLINTEND`` comments.
322
323 The ``NOLINT`` comment instructs :program:`clang-tidy` to ignore warnings on the
324 *same line* (it doesn't apply to a function, a block of code or any other
325 language construct; it applies to the line of code it is on). If introducing the
326 comment on the same line would change the formatting in an undesired way, the
327 ``NOLINTNEXTLINE`` comment allows suppressing clang-tidy warnings on the *next
328 line*. The ``NOLINTBEGIN`` and ``NOLINTEND`` comments allow suppressing
329 clang-tidy warnings on *multiple lines* (affecting all lines between the two
330 comments).
331
332 All comments can be followed by an optional list of check names in parentheses
333 (see below for the formal syntax). The list of check names supports globbing,
334 with the same format and semantics as for enabling checks. Note: negative globs
335 are ignored here, as they would effectively re-activate the warning.
336
337 For example:
338
339 .. code-block:: c++
340
341 class Foo {
342 // Suppress all the diagnostics for the line
343 Foo(int param); // NOLINT
344
345 // Consider explaining the motivation to suppress the warning
346 Foo(char param); // NOLINT: Allow implicit conversion from `char`, because <some valid reason>
347
348 // Silence only the specified checks for the line
349 Foo(double param); // NOLINT(google-explicit-constructor, google-runtime-int)
350
351 // Silence all checks from the `google` module
352 Foo(bool param); // NOLINT(google*)
353
354 // Silence all checks ending with `-avoid-c-arrays`
355 int array[10]; // NOLINT(*-avoid-c-arrays)
356
357 // Silence only the specified diagnostics for the next line
358 // NOLINTNEXTLINE(google-explicit-constructor, google-runtime-int)
359 Foo(bool param);
360
361 // Silence all checks from the `google` module for the next line
362 // NOLINTNEXTLINE(google*)
363 Foo(bool param);
364
365 // Silence all checks ending with `-avoid-c-arrays` for the next line
366 // NOLINTNEXTLINE(*-avoid-c-arrays)
367 int array[10];
368
369 // Silence only the specified checks for all lines between the BEGIN and END
370 // NOLINTBEGIN(google-explicit-constructor, google-runtime-int)
371 Foo(short param);
372 Foo(long param);
373 // NOLINTEND(google-explicit-constructor, google-runtime-int)
374
375 // Silence all checks from the `google` module for all lines between the BEGIN and END
376 // NOLINTBEGIN(google*)
377 Foo(bool param);
378 // NOLINTEND(google*)
379
380 // Silence all checks ending with `-avoid-c-arrays` for all lines between the BEGIN and END
381 // NOLINTBEGIN(*-avoid-c-arrays)
382 int array[10];
383 // NOLINTEND(*-avoid-c-arrays)
384 };
385
386 The formal syntax of ``NOLINT``, ``NOLINTNEXTLINE``, and ``NOLINTBEGIN`` ...
387 ``NOLINTEND`` is the following:
388
389 .. parsed-literal::
390
391 lint-comment:
392 lint-command
393 lint-command lint-args
394
395 lint-args:
396 **(** check-name-list **)**
397
398 check-name-list:
399 *check-name*
400 check-name-list **,** *check-name*
401
402 lint-command:
403 **NOLINT**
404 **NOLINTNEXTLINE**
405 **NOLINTBEGIN**
406 **NOLINTEND**
407
408 Note that whitespaces between
409 ``NOLINT``/``NOLINTNEXTLINE``/``NOLINTBEGIN``/``NOLINTEND`` and the opening
410 parenthesis are not allowed (in this case the comment will be treated just as
411 ``NOLINT``/``NOLINTNEXTLINE``/``NOLINTBEGIN``/``NOLINTEND``), whereas in the
412 check names list (inside the parentheses), whitespaces can be used and will be
413 ignored.
414
415 All ``NOLINTBEGIN`` comments must be paired by an equal number of ``NOLINTEND``
416 comments. Moreover, a pair of comments must have matching arguments -- for
417 example, ``NOLINTBEGIN(check-name)`` can be paired with
418 ``NOLINTEND(check-name)`` but not with ``NOLINTEND`` `(zero arguments)`.
419 :program:`clang-tidy` will generate a ``clang-tidy-nolint`` error diagnostic if
420 any ``NOLINTBEGIN``/``NOLINTEND`` comment violates these requirements.
421
422 .. _LibTooling: https://clang.llvm.org/docs/LibTooling.html
423 .. _How To Setup Tooling For LLVM: https://clang.llvm.org/docs/HowToSetupToolingForLLVM.html