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

   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