Lines Matching +full:docs +full:- +full:clang +full:- +full:tools +full:- +full:html
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
28 matchers and exploration of the Clang 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
38 .. _PPCallbacks: https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html
39 .. _clang-check: https://clang.llvm.org/docs/ClangCheck.html
43 ---------------------------------------
48 + *Clang diagnostic*: if the check is generic enough, targets code patterns that
51 make a good Clang diagnostic.
53 + *Clang static analyzer check*: if the check requires some sort of control flow
56 + *clang-tidy check* is a good choice for linter-style checks, checks that are
61 ------------------------
64 the LLVM System`_, `Using Clang Tools`_ and `How To Setup Clang Tooling For
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
162 * create a lit test file in the ``test/clang-tidy/`` directory;
164 ``docs/clang-tidy/checks/list.rst``.
168 .. code-block:: c++
174 namespace clang {
189 } // namespace clang
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 ----------------------
241 with the LLVM and Clang code bases. Here are some suggestions for orienting yourself
247 Many of the support classes created for LLVM are used by Clang, such as `StringRef
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
258 <https://llvm.org/doxygen/STLExtras_8h.html>`_ you'll find useful versions of the STL
260 <https://llvm.org/doxygen/STLExtras_8h.html#func-members>`_.
262 Clang is implemented on top of LLVM and introduces its own set of classes that you
264 fix-its, these are associated with locations in the source code. Source code locations,
266 <https://clang.llvm.org/doxygen/classclang_1_1SourceManager.html>`_ class provide
268 other topics are described in the `"Clang" CFE Internals Manual
269 <https://clang.llvm.org/docs/InternalsManual.html>`_. Whereas the doxygen generated
270 documentation serves as a reference to the internals of Clang, this document serves
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
307 check with the Transformer library. The `Clang Transformer Tutorial
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
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
392 check is robust. Running your check on a large code base, such as Clang/LLVM, is a
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.
430 `release notes <https://clang.llvm.org/extra/ReleaseNotes.html>`_, the list of
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
454 ----------------------
461 .. code-block:: c++
467 "my-explicit-constructor");
474 .. code-block:: c++
476 static ClangTidyModuleRegistry::Add<MyModule> X("my-module",
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.
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
669 LLVM as done for other kinds of Clang plugins. If using CMake, use the keyword
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 --------------------------
701 To test a check it's best to try it out on a larger code base. LLVM and Clang
703 convenient way to run :program:`clang-tidy` is with a compile command database;
705 `How To Setup Clang Tooling For LLVM`_. Once ``compile_commands.json`` is in
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`