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>                - Comma-separated list of globs with optional '-'
 126                                        prefix. Globs are processed in order of
 127                                        appearance in the list. Globs without '-'
 128                                        prefix add checks with matching names to the
 129                                        set, globs with the '-' prefix remove checks
 130                                        with matching names from the set of enabled
 131                                        checks. This option's value is appended to the
 132                                        value of the 'Checks' option in .clang-tidy
 133                                        file, if any.
 134     --config=<string>                - Specifies a configuration in YAML/JSON format:
 135                                          -config="{Checks: '*',
 136                                                    CheckOptions: {x: y}}"
 137                                        When the value is empty, clang-tidy will
 138                                        attempt to find a file named .clang-tidy for
 139                                        each source file in its parent directories.
 140     --config-file=<string>           - Specify the path of .clang-tidy or custom config file:
 141                                         e.g. --config-file=/some/path/myTidyConfigFile
 142                                        This option internally works exactly the same way as
 143                                         --config option after reading specified config file.
 144                                        Use either --config-file or --config, not both.
 145     --dump-config                    - Dumps configuration in the YAML format to
 146                                        stdout. This option can be used along with a
 147                                        file name (and '--' if the file is outside of a
 148                                        project with configured compilation database).
 149                                        The configuration used for this file will be
 150                                        printed.
 151                                        Use along with -checks=* to include
 152                                        configuration of all checks.
 153     --enable-check-profile           - Enable per-check timing profiles, and print a
 154                                        report to stderr.
 155     --enable-module-headers-parsing  - Enables preprocessor-level module header parsing
 156                                        for C++20 and above, empowering specific checks
 157                                        to detect macro definitions within modules. This
 158                                        feature may cause performance and parsing issues
 159                                        and is therefore considered experimental.
 160     --exclude-header-filter=<string> - Regular expression matching the names of the
 161                                        headers to exclude diagnostics from. Diagnostics
 162                                        from the main file of each translation unit are
 163                                        always displayed.
 164                                        Must be used together with --header-filter.
 165                                        Can be used together with -line-filter.
 166                                        This option overrides the 'ExcludeHeaderFilterRegex'
 167                                        option in .clang-tidy file, if any.
 168     --explain-config                 - For each enabled check explains, where it is
 169                                        enabled, i.e. in clang-tidy binary, command
 170                                        line or a specific configuration file.
 171     --export-fixes=<filename>        - YAML file to store suggested fixes in. The
 172                                        stored fixes can be applied to the input source
 173                                        code with clang-apply-replacements.
 174     --extra-arg=<string>             - Additional argument to append to the compiler command line
 175     --extra-arg-before=<string>      - Additional argument to prepend to the compiler command line
 176     --fix                            - Apply suggested fixes. Without -fix-errors
 177                                        clang-tidy will bail out if any compilation
 178                                        errors were found.
 179     --fix-errors                     - Apply suggested fixes even if compilation
 180                                        errors were found. If compiler errors have
 181                                        attached fix-its, clang-tidy will apply them as
 182                                        well.
 183     --fix-notes                      - If a warning has no fix, but a single fix can
 184                                        be found through an associated diagnostic note,
 185                                        apply the fix.
 186                                        Specifying this flag will implicitly enable the
 187                                        '--fix' flag.
 188     --format-style=<string>          - 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>         - Regular expression matching the names of the
 201                                        headers to output diagnostics from. Diagnostics
 202                                        from the main file of each translation unit are
 203                                        always displayed.
 204                                        Can be used together with -line-filter.
 205                                        This option overrides the 'HeaderFilterRegex'
 206                                        option in .clang-tidy file, if any.
 207     --line-filter=<string>           - List of files with line ranges to filter the
 208                                        warnings. Can be used together with
 209                                        -header-filter. The format of the list is a
 210                                        JSON array of objects:
 211                                          [
 212                                            {"name":"file1.cpp","lines":[[1,3],[5,7]]},
 213                                            {"name":"file2.h"}
 214                                          ]
 215     --list-checks                    - List all enabled checks and exit. Use with
 216                                        -checks=* to list all available checks.
 217     --load=<pluginfilename>          - Load the specified plugin
 218     -p <string>                      - Build path
 219     --quiet                          - Run clang-tidy in quiet mode. This suppresses
 220                                        printing statistics about ignored warnings and
 221                                        warnings treated as errors if the respective
 222                                        options are specified.
 223     --store-check-profile=<prefix>   - By default reports are printed in tabulated
 224                                        format to stderr. When this option is passed,
 225                                        these per-TU profiles are instead stored as JSON.
 226     --system-headers                 - Display the errors from system headers.
 227                                        This option overrides the 'SystemHeaders' option
 228                                        in .clang-tidy file, if any.
 229     --use-color                      - Use colors in diagnostics. If not set, colors
 230                                        will be used if the terminal connected to
 231                                        standard output supports colors.
 232                                        This option overrides the 'UseColor' option in
 233                                        .clang-tidy file, if any.
 234     --verify-config                  - Check the config files to ensure each check and
 235                                        option is recognized.
 236     --vfsoverlay=<filename>          - Overlay the virtual filesystem described by file
 237                                        over the real file system.
 238     --warnings-as-errors=<string>    - Upgrades warnings to errors. Same format as
 239                                        '-checks'.
 240                                        This option's value is appended to the value of
 241                                        the 'WarningsAsErrors' option in .clang-tidy
 242                                        file, if any.
 243     --allow-no-checks                - Allow empty enabled checks. This suppresses
 244                                        the "no checks enabled" error when disabling
 245                                        all of the checks.
 246
 247   -p <build-path> is used to read a compile command database.
 248
 249     For example, it can be a CMake build directory in which a file named
 250     compile_commands.json exists (use -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
 251     CMake option to get this output). When no build path is specified,
 252     a search for compile_commands.json will be attempted through all
 253     parent paths of the first input file . See:
 254     https://clang.llvm.org/docs/HowToSetupToolingForLLVM.html for an
 255     example of setting up Clang Tooling on a source tree.
 256
 257   <source0> ... specify the paths of source files. These paths are
 258     looked up in the compile command database. If the path of a file is
 259     absolute, it needs to point into CMake's source tree. If the path is
 260     relative, the current working directory needs to be in the CMake
 261     source tree and the file must be in a subdirectory of the current
 262     working directory. "./" prefixes in the relative files will be
 263     automatically removed, but the rest of a relative path must be a
 264     suffix of a path in the compile command database.
 265
 266
 267   Configuration files:
 268     clang-tidy attempts to read configuration for each source file from a
 269     .clang-tidy file located in the closest parent directory of the source
 270     file. The .clang-tidy file is specified in YAML format. If any configuration
 271     options have a corresponding command-line option, command-line option takes
 272     precedence.
 273
 274     The following configuration options may be used in a .clang-tidy file:
 275
 276     CheckOptions                 - List of key-value pairs defining check-specific
 277                                    options. Example:
 278                                      CheckOptions:
 279                                        some-check.SomeOption: 'some value'
 280     Checks                       - Same as '--checks'. Additionally, the list of
 281                                    globs can be specified as a list instead of a
 282                                    string.
 283     ExcludeHeaderFilterRegex     - Same as '--exclude-header-filter'.
 284     ExtraArgs                    - Same as '--extra-args'.
 285     ExtraArgsBefore              - Same as '--extra-args-before'.
 286     FormatStyle                  - Same as '--format-style'.
 287     HeaderFileExtensions         - File extensions to consider to determine if a
 288                                    given diagnostic is located in a header file.
 289     HeaderFilterRegex            - Same as '--header-filter-regex'.
 290     ImplementationFileExtensions - File extensions to consider to determine if a
 291                                    given diagnostic is located in an
 292                                    implementation file.
 293     InheritParentConfig          - If this option is true in a config file, the
 294                                    configuration file in the parent directory
 295                                    (if any exists) will be taken and the current
 296                                    config file will be applied on top of the
 297                                    parent one.
 298     SystemHeaders                - Same as '--system-headers'.
 299     UseColor                     - Same as '--use-color'.
 300     User                         - Specifies the name or e-mail of the user
 301                                    running clang-tidy. This option is used, for
 302                                    example, to place the correct user name in
 303                                    TODO() comments in the relevant check.
 304     WarningsAsErrors             - Same as '--warnings-as-errors'.
 305
 306     The effective configuration can be inspected using --dump-config:
 307
 308       $ clang-tidy --dump-config
 309       ---
 310       Checks:              '-*,some-check'
 311       WarningsAsErrors:    ''
 312       HeaderFileExtensions:         ['', 'h','hh','hpp','hxx']
 313       ImplementationFileExtensions: ['c','cc','cpp','cxx']
 314       HeaderFilterRegex:   ''
 315       FormatStyle:         none
 316       InheritParentConfig: true
 317       User:                user
 318       CheckOptions:
 319         some-check.SomeOption: 'some value'
 320       ...
 321
 322 .. _clang-tidy-nolint:
 323
 324 Suppressing Undesired Diagnostics
 325 =================================
 326
 327 :program:`clang-tidy` diagnostics are intended to call out code that does not
 328 adhere to a coding standard, or is otherwise problematic in some way. However,
 329 if the code is known to be correct, it may be useful to silence the warning.
 330 Some clang-tidy checks provide a check-specific way to silence the diagnostics,
 331 e.g. `bugprone-use-after-move <checks/bugprone/use-after-move.html>`_ can be
 332 silenced by re-initializing the variable after it has been moved out,
 333 `bugprone-string-integer-assignment
 334 <checks/bugprone/string-integer-assignment.html>`_ can be suppressed by
 335 explicitly casting the integer to ``char``,
 336 `readability-implicit-bool-conversion
 337 <checks/readability/implicit-bool-conversion.html>`_ can also be suppressed by
 338 using explicit casts, etc.
 339
 340 If a specific suppression mechanism is not available for a certain warning, or
 341 its use is not desired for some reason, :program:`clang-tidy` has a generic
 342 mechanism to suppress diagnostics using ``NOLINT``, ``NOLINTNEXTLINE``, and
 343 ``NOLINTBEGIN`` ... ``NOLINTEND`` comments.
 344
 345 The ``NOLINT`` comment instructs :program:`clang-tidy` to ignore warnings on the
 346 *same line* (it doesn't apply to a function, a block of code or any other
 347 language construct; it applies to the line of code it is on). If introducing the
 348 comment on the same line would change the formatting in an undesired way, the
 349 ``NOLINTNEXTLINE`` comment allows suppressing clang-tidy warnings on the *next
 350 line*. The ``NOLINTBEGIN`` and ``NOLINTEND`` comments allow suppressing
 351 clang-tidy warnings on *multiple lines* (affecting all lines between the two
 352 comments).
 353
 354 All comments can be followed by an optional list of check names in parentheses
 355 (see below for the formal syntax). The list of check names supports globbing,
 356 with the same format and semantics as for enabling checks. Note: negative globs
 357 are ignored here, as they would effectively re-activate the warning.
 358
 359 For example:
 360
 361 .. code-block:: c++
 362
 363   class Foo {
 364     // Suppress all the diagnostics for the line
 365     Foo(int param); // NOLINT
 366
 367     // Consider explaining the motivation to suppress the warning
 368     Foo(char param); // NOLINT: Allow implicit conversion from `char`, because <some valid reason>
 369
 370     // Silence only the specified checks for the line
 371     Foo(double param); // NOLINT(google-explicit-constructor, google-runtime-int)
 372
 373     // Silence all checks from the `google` module
 374     Foo(bool param); // NOLINT(google*)
 375
 376     // Silence all checks ending with `-avoid-c-arrays`
 377     int array[10]; // NOLINT(*-avoid-c-arrays)
 378
 379     // Silence only the specified diagnostics for the next line
 380     // NOLINTNEXTLINE(google-explicit-constructor, google-runtime-int)
 381     Foo(bool param);
 382
 383     // Silence all checks from the `google` module for the next line
 384     // NOLINTNEXTLINE(google*)
 385     Foo(bool param);
 386
 387     // Silence all checks ending with `-avoid-c-arrays` for the next line
 388     // NOLINTNEXTLINE(*-avoid-c-arrays)
 389     int array[10];
 390
 391     // Silence only the specified checks for all lines between the BEGIN and END
 392     // NOLINTBEGIN(google-explicit-constructor, google-runtime-int)
 393     Foo(short param);
 394     Foo(long param);
 395     // NOLINTEND(google-explicit-constructor, google-runtime-int)
 396
 397     // Silence all checks from the `google` module for all lines between the BEGIN and END
 398     // NOLINTBEGIN(google*)
 399     Foo(bool param);
 400     // NOLINTEND(google*)
 401
 402     // Silence all checks ending with `-avoid-c-arrays` for all lines between the BEGIN and END
 403     // NOLINTBEGIN(*-avoid-c-arrays)
 404     int array[10];
 405     // NOLINTEND(*-avoid-c-arrays)
 406   };
 407
 408 The formal syntax of ``NOLINT``, ``NOLINTNEXTLINE``, and ``NOLINTBEGIN`` ...
 409 ``NOLINTEND`` is the following:
 410
 411 .. parsed-literal::
 412
 413   lint-comment:
 414     lint-command
 415     lint-command lint-args
 416
 417   lint-args:
 418     **(** check-name-list **)**
 419
 420   check-name-list:
 421     *check-name*
 422     check-name-list **,** *check-name*
 423
 424   lint-command:
 425     **NOLINT**
 426     **NOLINTNEXTLINE**
 427     **NOLINTBEGIN**
 428     **NOLINTEND**
 429
 430 Note that whitespaces between
 431 ``NOLINT``/``NOLINTNEXTLINE``/``NOLINTBEGIN``/``NOLINTEND`` and the opening
 432 parenthesis are not allowed (in this case the comment will be treated just as
 433 ``NOLINT``/``NOLINTNEXTLINE``/``NOLINTBEGIN``/``NOLINTEND``), whereas in the
 434 check names list (inside the parentheses), whitespaces can be used and will be
 435 ignored.
 436
 437 All ``NOLINTBEGIN`` comments must be paired by an equal number of ``NOLINTEND``
 438 comments. Moreover, a pair of comments must have matching arguments -- for
 439 example, ``NOLINTBEGIN(check-name)`` can be paired with
 440 ``NOLINTEND(check-name)`` but not with ``NOLINTEND`` `(zero arguments)`.
 441 :program:`clang-tidy` will generate a ``clang-tidy-nolint`` error diagnostic if
 442 any ``NOLINTBEGIN``/``NOLINTEND`` comment violates these requirements.
 443
 444 .. _LibTooling: https://clang.llvm.org/docs/LibTooling.html
 445 .. _How To Setup Tooling For LLVM: https://clang.llvm.org/docs/HowToSetupToolingForLLVM.html