Lines Matching +full:build +full:- +full:docs
5 :program:`clang-tidy` has several own checks and can run Clang static analyzer
8 Checks are organized in modules, which can be linked into :program:`clang-tidy`
9 with minimal or no code changes in :program:`clang-tidy`.
13 report them in a way similar to how Clang diagnostics work. A fix-it hint can be
16 The interface provided by :program:`clang-tidy` makes it easy to write useful
20 There are a few tools particularly useful when developing clang-tidy checks:
25 * :program:`pp-trace` logs method calls on `PPCallbacks` for a source file
27 * :program:`clang-query` is invaluable for interactive prototyping of AST
29 * `clang-check`_ with the ``-ast-dump`` (and optionally ``-ast-dump-filter``)
33 :program:`clang-tidy` will not be built with support for the
34 ``clang-analyzer-*`` checks or the ``mpi-*`` checks.
37 .. _AST Matchers: https://clang.llvm.org/docs/LibASTMatchers.html
39 .. _clang-check: https://clang.llvm.org/docs/ClangCheck.html
43 ---------------------------------------
56 + *clang-tidy check* is a good choice for linter-style checks, checks that are
61 ------------------------
65 LLVM`_ documents to check out and build LLVM, Clang and Clang Extra Tools with
68 Once you are done, change to the ``llvm/clang-tools-extra`` directory, and
71 .. _Getting Started with the LLVM System: https://llvm.org/docs/GettingStarted.html
72 .. _Using Clang Tools: https://clang.llvm.org/docs/ClangTools.html
73 .. _How To Setup Clang Tooling For LLVM: https://clang.llvm.org/docs/HowToSetupToolingForLLVM.html
75 When you `configure the CMake build <https://llvm.org/docs/GettingStarted.html#local-llvm-configuration>`_,
76 make sure that you enable the ``clang`` and ``clang-tools-extra`` projects to
77 build :program:`clang-tidy`.
79 `Sphinx <https://www.sphinx-doc.org/en/master/>`_ and enable it in the CMake configuration.
80 To save build time of the core Clang libraries you may want to only enable the ``X86``
85 -----------------------
87 :program:`clang-tidy` source code resides in the
88 ``llvm/clang-tools-extra`` directory and is structured as follows:
92 clang-tidy/ # Clang-tidy core.
93 |-- ClangTidy.h # Interfaces for users.
94 |-- ClangTidyCheck.h # Interfaces for checks.
95 |-- ClangTidyModule.h # Interface for clang-tidy modules.
96 |-- ClangTidyModuleRegistry.h # Interface for registering of modules.
98 |-- google/ # Google clang-tidy module.
99 |-+
100 |-- GoogleTidyModule.cpp
101 |-- GoogleTidyModule.h
103 |-- llvm/ # LLVM clang-tidy module.
104 |-+
105 |-- LLVMTidyModule.cpp
106 |-- LLVMTidyModule.h
108 |-- objc/ # Objective-C clang-tidy module.
109 |-+
110 |-- ObjCTidyModule.cpp
111 |-- ObjCTidyModule.h
113 |-- tool/ # Sources of the clang-tidy binary.
115 test/clang-tidy/ # Integration tests.
117 unittests/clang-tidy/ # Unit tests.
118 |-- ClangTidyTest.h
119 |-- GoogleModuleTest.cpp
120 |-- LLVMModuleTest.cpp
121 |-- ObjCModuleTest.cpp
125 Writing a clang-tidy Check
126 --------------------------
128 So you have an idea of a useful check for :program:`clang-tidy`.
136 .. _Getting Started with the LLVM System: https://llvm.org/docs/GettingStarted.html
137 .. _LLVM Coding Standards: https://llvm.org/docs/CodingStandards.html
138 .. _LLVM Github: https://github.com/llvm/llvm-project
141 are located in subdirectories of `clang-tidy/
142 <https://github.com/llvm/llvm-project/tree/main/clang-tools-extra/clang-tidy/>`_
145 or a widely used API (e.g. MPI). Their names are the same as the user-facing
146 check group names described :ref:`above <checks-groups-table>`.
149 ``clang-tidy/add_new_check.py`` script to create the skeleton of the check and
150 plug it to :program:`clang-tidy`. It's the recommended way of adding new checks.
152 If we want to create a `readability-awesome-function-names`, we would run:
154 .. code-block:: console
156 $ clang-tidy/add_new_check.py readability awesome-function-names
161 register it in the module and in the build system;
162 * create a lit test file in the ``test/clang-tidy/`` directory;
164 ``docs/clang-tidy/checks/list.rst``.
168 .. code-block:: c++
206 .. code-block:: c++
211 Finder->addMatcher(functionDecl().bind("x"), this);
216 if (!MatchedDecl->getIdentifier() || MatchedDecl->getName().startswith("awesome_"))
218 diag(MatchedDecl->getLocation(), "function %0 is insufficiently awesome")
220 << FixItHint::CreateInsertion(MatchedDecl->getLocation(), "awesome_");
224 `clang-tidy/google/ExplicitConstructorCheck.h
225 <https://github.com/llvm/llvm-project/blob/main/clang-tools-extra/clang-tidy/google/ExplicitConstructorCheck.h>`_
226 and `clang-tidy/google/ExplicitConstructorCheck.cpp
227 <https://reviews.llvm.org/diffusion/L/browse/clang-tools-extra/trunk/clang-tidy/google/ExplicitConstructorCheck.cpp>`_).
238 ----------------------
248 <https://llvm.org/docs/ProgrammersManual.html#the-stringref-class>`_
249 and `SmallVector <https://llvm.org/docs/ProgrammersManual.html#llvm-adt-smallvector-h>`_.
251 <https://llvm.org/docs/ProgrammersManual.html#important-and-useful-llvm-apis>`_ and
253 <https://llvm.org/docs/ProgrammersManual.html#picking-the-right-data-structure-for-a-task>`_
255 <https://llvm.org/docs/ProgrammersManual.html>`_. You don't need to memorize all the
260 <https://llvm.org/doxygen/STLExtras_8h.html#func-members>`_.
264 fix-its, these are associated with locations in the source code. Source code locations,
269 <https://clang.llvm.org/docs/InternalsManual.html>`_. Whereas the doxygen generated
274 - `The Clang "Basic" Library
275 <https://clang.llvm.org/docs/InternalsManual.html#the-clang-basic-library>`_ for
276 information about diagnostics, fix-it hints and source locations.
277 - `The Lexer and Preprocessor Library
278 <https://clang.llvm.org/docs/InternalsManual.html#the-lexer-and-preprocessor-library>`_
281 - `The AST Library
282 <https://clang.llvm.org/docs/InternalsManual.html#the-ast-library>`_
297 Reference <https://clang.llvm.org/docs/LibASTMatchersReference.html>`_ to understand
306 to perform low-level source location manipulation, you may want to consider writing your
308 <https://clang.llvm.org/docs/ClangTransformerTutorial.html>`_ describes the Transformer
314 - Include ``../utils/TransformerClangTidyCheck.h`` instead of ``../ClangTidyCheck.h``
315 - Change the base class of your check from ``ClangTidyCheck`` to ``TransformerClangTidyCheck``
316 - Delete the override of the ``registerMatchers`` and ``check`` methods in your check class.
317 - Write a function that creates the ``RewriteRule`` for your check.
318 - Call the function in your check's constructor to pass the rewrite rule to
328 - Write a test case for your check.
329 - Prototype matchers on the test file using :program:`clang-query`.
330 - Capture the working matchers in the ``registerMatchers`` method.
331 - Issue the necessary diagnostics and fix-its in the ``check`` method.
332 - Add the necessary ``CHECK-MESSAGES`` and ``CHECK-FIXES`` annotations to your
333 test case to validate the diagnostics and fix-its.
334 - Build the target ``check-clang-tools`` to confirm the test passes.
335 - Repeat the process until all aspects of your check are covered by tests.
337 The quickest way to prototype your matcher is to use :program:`clang-query` to
338 interactively build up your matcher. For complicated matchers, build up a matching
339 expression incrementally and use :program:`clang-query`'s ``let`` command to save named
342 .. code-block:: console
344 clang-query> let c1 cxxRecordDecl()
345 clang-query> match c1
353 intention-revealing names can help you understand a complex algorithm, breaking
354 up a matcher into smaller matchers with intention-revealing names can help
357 Once you have a working :program:`clang-query` matcher, the C++ API matchers
360 your intention-revealing names that you applied to nested matchers.
368 in your ``check`` method by eliminating complex hand-crafted AST traversal of the
382 You can build the Clang-tidy unit tests by building the ``ClangTidyTests`` target.
383 Test targets in LLVM and Clang are excluded from the "build all" style action of
384 IDE-based CMake generators, so you need to explicitly build the target for the unit
401 - Create header files that contain code matched by your check.
402 - Validate that fix-its are properly applied to test header files with
403 :program:`clang-tidy`. You will need to perform this test manually until
404 automated support for checking messages and fix-its is added to the
406 - Define macros that contain code matched by your check.
407 - Define template classes that contain code matched by your check.
408 - Define template specializations that contain code matched by your check.
409 - Test your check under both Windows and Linux environments.
410 - Watch out for high false positive rates. Ideally, a check would have no false
411 positives, but given that matching against an AST is not control- or data flow-
415 - There are two primary mechanisms for managing false positives: supporting a
418 - Consider supporting a code pattern to allow the programmer to silence the
422 - Consider adding check configuration options to allow the user to opt into
424 high-confidence cases.
441 Provide enough examples of the diagnostics and fix-its provided by the check so that a
444 will help users understand the scope of the diagnostics and fix-its provided by the check.
446 Building the target ``docs-clang-tools-html`` will run the Sphinx documentation generator
447 and create documentation HTML files in the tools/clang/tools/extra/docs/html directory in
448 your build tree. Make sure that your check is correctly shown in the release notes and the
454 ----------------------
461 .. code-block:: c++
467 "my-explicit-constructor");
474 .. code-block:: c++
476 static ClangTidyModuleRegistry::Add<MyModule> X("my-module",
480 When using LLVM build system, we need to use the following hack to ensure the
481 module is linked into the :program:`clang-tidy` binary:
485 .. code-block:: c++
491 And this to the main translation unit of the :program:`clang-tidy` binary (or
492 the binary you link the ``clang-tidy`` library in)
493 ``clang-tidy/ClangTidyForceLinker.h``:
495 .. code-block:: c++
503 ------------------
505 If a check needs configuration options, it can access check-specific options
509 check discoverable. This method lets :program:`clang-tidy` know which options
511 ``-dump-config`` command line option).
513 .. code-block:: c++
522 SomeOption1(Options.get("SomeOption1", -1U)),
531 Assuming the check is registered with the name "my-check", the option can then
532 be set in a ``.clang-tidy`` file in the following way:
534 .. code-block:: yaml
537 my-check.SomeOption1: 123
538 my-check.SomeOption2: 'some other value'
543 .. code-block:: console
545 $ clang-tidy -config="{CheckOptions: {a: b, x: y}}" ...
549 --------------
551 To run tests for :program:`clang-tidy`, build the ``check-clang-tools`` target.
552 For instance, if you configured your CMake build with the ninja project generator,
555 .. code-block:: console
557 $ ninja check-clang-tools
559 :program:`clang-tidy` checks can be tested using either unit tests or
566 diagnostic messages and fix-its. It filters out ``CHECK`` lines from the test
567 file, runs :program:`clang-tidy` and verifies messages and fixes with two
569 prefix set to ``CHECK-MESSAGES``, validating the diagnostic messages,
570 and once with the directive prefix set to ``CHECK-FIXES``, running
571 against the fixed code (i.e., the code after generated fix-its are
572 applied). In particular, ``CHECK-FIXES:`` can be used to check
573 that code was not modified by fix-its, by checking that it is present
575 is available (e.g., ``CHECK-MESSAGES-SAME:``, ``CHECK-MESSAGES-NOT:``), though
576 typically the basic ``CHECK`` forms (``CHECK-MESSAGES`` and ``CHECK-FIXES``)
577 are sufficient for clang-tidy tests. Note that the `FileCheck`_
579 describes the directive as ``CHECK:``, ``CHECK-SAME:``, ``CHECK-NOT:``, etc.
580 Replace ``CHECK`` by either ``CHECK-FIXES`` or ``CHECK-MESSAGES`` for
581 clang-tidy tests.
584 if `CHECK-MESSAGES:` is used in a file then every warning or error
585 must have an associated CHECK in that file. Or, you can use ``CHECK-NOTES:``
589 appropriate ``RUN`` line in the ``test/clang-tidy`` directory. Use
590 ``CHECK-MESSAGES:`` and ``CHECK-FIXES:`` lines to write checks against
594 to incorrect parts of the input. Use ``[[@LINE+X]]``/``[[@LINE-X]]``
598 source code is at `test/clang-tidy/checkers/google/readability-casting.cpp`_):
600 .. code-block:: c++
602 // RUN: %check_clang_tidy %s google-readability-casting %t
606 // CHECK-MESSAGES: :[[@LINE-1]]:11: warning: redundant cast to the same type [google-readability-casting]
607 // CHECK-FIXES: int b = a;
611 ``-check-suffix=SUFFIX-NAME`` on ``check_clang_tidy.py`` command line or
612 ``-check-suffixes=SUFFIX-NAME-1,SUFFIX-NAME-2,...``.
613 With ``-check-suffix[es]=SUFFIX-NAME`` you need to replace your ``CHECK-*``
614 directives with ``CHECK-MESSAGES-SUFFIX-NAME`` and ``CHECK-FIXES-SUFFIX-NAME``.
618 .. code-block:: c++
620 // RUN: %check_clang_tidy -check-suffix=USING-A %s misc-unused-using-decls %t -- -- -DUSING_A
621 // RUN: %check_clang_tidy -check-suffix=USING-B %s misc-unused-using-decls %t -- -- -DUSING_B
622 // RUN: %check_clang_tidy %s misc-unused-using-decls %t
624 // CHECK-MESSAGES-USING-A: :[[@LINE-8]]:10: warning: using decl 'A' {{.*}}
625 // CHECK-MESSAGES-USING-B: :[[@LINE-7]]:10: warning: using decl 'B' {{.*}}
626 // CHECK-MESSAGES: :[[@LINE-6]]:10: warning: using decl 'C' {{.*}}
627 // CHECK-FIXES-USING-A-NOT: using a::A;$
628 // CHECK-FIXES-USING-B-NOT: using a::B;$
629 // CHECK-FIXES-NOT: using a::C;$
632 your check work perfectly in all cases, especially if it issues fix-it hints. The
640 issued by the check multiple times; :program:`clang-tidy` will deduplicate
657 .. _lit: https://llvm.org/docs/CommandGuide/lit.html
658 .. _FileCheck: https://llvm.org/docs/CommandGuide/FileCheck.html
659 .. _test/clang-tidy/checkers/google/readability-casting.cpp: https://github.com/llvm/llvm-project/blob/main/clang-tools-extra/test/clang-tidy/checkers/google/readability-casting.cpp
661 Out-of-tree check plugins
662 -------------------------
665 Developing an out-of-tree check as a plugin largely follows the steps
668 the clang-tidy build system. Build and link this shared library against
672 The plugin can be loaded by passing `-load` to `clang-tidy` in addition to the
675 .. code-block:: console
677 $ clang-tidy --checks=-*,my-explicit-constructor -list-checks -load myplugin.so
680 compiled against the version of clang-tidy that will be loading the plugin.
682 The plugins can use threads, TLS, or any other facilities available to in-tree
685 Note that testing out-of-tree checks might involve getting ``llvm-lit`` from an LLVM
689 Alternatively, get `lit`_ following the `test-suite guide`_ and get the `FileCheck`_ binary,
692 .. _Getting Started with the LLVM System: https://llvm.org/docs/GettingStarted.html
693 .. _test-suite guide: https://llvm.org/docs/TestSuiteGuide.html
694 .. _lit: https://llvm.org/docs/CommandGuide/lit.html
695 .. _FileCheck: https://llvm.org/docs/CommandGuide/FileCheck.html
696 .. _check_clang_tidy.py: https://github.com/llvm/llvm-project/blob/main/clang-tools-extra/test/clang-tidy/check_clang_tidy.py
698 Running clang-tidy on LLVM
699 --------------------------
703 convenient way to run :program:`clang-tidy` is with a compile command database;
706 place and a working version of :program:`clang-tidy` is in ``PATH`` the entire
707 code base can be analyzed with ``clang-tidy/tool/run-clang-tidy.py``. The script
708 executes :program:`clang-tidy` with the default set of checks on every
712 .. _How To Setup Clang Tooling For LLVM: https://clang.llvm.org/docs/HowToSetupToolingForLLVM.html
715 * The default set of checks can be overridden using the ``-checks`` argument,
716 taking the identical format as :program:`clang-tidy` does. For example
717 ``-checks=-*,modernize-use-override`` will run the ``modernize-use-override``
722 ``run-clang-tidy.py clang-tidy/.*Check\.cpp`` will only analyze `clang-tidy`
724 are displayed from by using the ``-header-filter`` and ``-exclude-header-filter`` flags.
725 They have the same behavior as the corresponding :program:`clang-tidy` flags.
727 * To apply suggested fixes ``-fix`` can be passed as an argument. This gathers
728 all changes in a temporary directory and applies them. Passing ``-format``
729 will run clang-format over changed lines.
733 -------------------
735 :program:`clang-tidy` can collect per-check profiling info, and output it
738 To enable profiling info collection, use the ``-enable-check-profile`` argument.
741 .. code-block:: console
743 $ clang-tidy -enable-check-profile -checks=-*,readability-function-size source.cpp
744 ===-------------------------------------------------------------------------===
745 clang-tidy checks profiling
746 ===-------------------------------------------------------------------------===
749 ---User Time--- --System Time-- --User+System-- ---Wall Time--- --- Name ---
750 0.9136 (100.0%) 0.1146 (100.0%) 1.0282 (100.0%) 1.0258 (100.0%) readability-function-size
755 .. code-block:: console
757 $ clang-tidy -enable-check-profile -store-check-profile=. -checks=-*,readability-function-size source.cpp
760 20180516161318717446360-source.cpp.json
761 $ cat 20180516161318717446360-source.cpp.json
764 "timestamp": "2018-05-16 16:13:18.717446360",
766 "time.clang-tidy.readability-function-size.wall": 1.0421266555786133e+00,
767 "time.clang-tidy.readability-function-size.user": 9.2088400000005421e-01,
768 "time.clang-tidy.readability-function-size.sys": 1.2418899999999974e-01
774 * ``-store-check-profile=<prefix>``
777 is passed, these per-TU profiles are instead stored as JSON.
779 directory from where you have run :program:`clang-tidy`. All ``.`` and ``..``
787 * If you specify ``-store-check-profile=/tmp``, then the profile will be saved
788 to ``/tmp/<ISO8601-like timestamp>-example.cpp.json``
790 * If you run :program:`clang-tidy` from within ``/foo`` directory, and specify
791 ``-store-check-profile=.``, then the profile will still be saved to
792 ``/foo/<ISO8601-like timestamp>-example.cpp.json`