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