| 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 |