[clang-tools-extra] r351463 - [Documentation] Add a chapter about Clang-tidy integrations.
Hans Wennborg via cfe-commits
cfe-commits at lists.llvm.org
Fri Jan 18 02:04:44 PST 2019
Merged to 8.0 along with the follow-ups in r351538.
On Thu, Jan 17, 2019 at 7:35 PM Eugene Zelenko via cfe-commits
<cfe-commits at lists.llvm.org> wrote:
>
> Author: eugenezelenko
> Date: Thu Jan 17 10:31:34 2019
> New Revision: 351463
>
> URL: http://llvm.org/viewvc/llvm-project?rev=351463&view=rev
> Log:
> [Documentation] Add a chapter about Clang-tidy integrations.
>
> Patch by Marina Kalashina.
>
> Differential Revision: https://reviews.llvm.org/D54945
>
> Added:
> clang-tools-extra/trunk/docs/clang-tidy/Contributing.rst
> clang-tools-extra/trunk/docs/clang-tidy/Integrations.rst
> Modified:
> clang-tools-extra/trunk/docs/clang-tidy/index.rst
>
> Added: clang-tools-extra/trunk/docs/clang-tidy/Contributing.rst
> URL: http://llvm.org/viewvc/llvm-project/clang-tools-extra/trunk/docs/clang-tidy/Contributing.rst?rev=351463&view=auto
> ==============================================================================
> --- clang-tools-extra/trunk/docs/clang-tidy/Contributing.rst (added)
> +++ clang-tools-extra/trunk/docs/clang-tidy/Contributing.rst Thu Jan 17 10:31:34 2019
> @@ -0,0 +1,507 @@
> +================
> +Getting Involved
> +================
> +
> +:program:`clang-tidy` has several own checks and can run Clang static analyzer
> +checks, but its power is in the ability to easily write custom checks.
> +
> +Checks are organized in modules, which can be linked into :program:`clang-tidy`
> +with minimal or no code changes in :program:`clang-tidy`.
> +
> +Checks can plug into the analysis on the preprocessor level using `PPCallbacks`_
> +or on the AST level using `AST Matchers`_. When an error is found, checks can
> +report them in a way similar to how Clang diagnostics work. A fix-it hint can be
> +attached to a diagnostic message.
> +
> +The interface provided by :program:`clang-tidy` makes it easy to write useful
> +and precise checks in just a few lines of code. If you have an idea for a good
> +check, the rest of this document explains how to do this.
> +
> +There are a few tools particularly useful when developing clang-tidy checks:
> + * ``add_new_check.py`` is a script to automate the process of adding a new
> + check, it will create the check, update the CMake file and create a test;
> + * ``rename_check.py`` does what the script name suggests, renames an existing
> + check;
> + * :program:`clang-query` is invaluable for interactive prototyping of AST
> + matchers and exploration of the Clang AST;
> + * `clang-check`_ with the ``-ast-dump`` (and optionally ``-ast-dump-filter``)
> + provides a convenient way to dump AST of a C++ program.
> +
> +If CMake is configured with ``CLANG_ENABLE_STATIC_ANALYZER``,
> +:program:`clang-tidy` will not be built with support for the
> +``clang-analyzer-*`` checks or the ``mpi-*`` checks.
> +
> +
> +.. _AST Matchers: http://clang.llvm.org/docs/LibASTMatchers.html
> +.. _PPCallbacks: http://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html
> +.. _clang-check: http://clang.llvm.org/docs/ClangCheck.html
> +
> +
> +Choosing the Right Place for your Check
> +---------------------------------------
> +
> +If you have an idea of a check, you should decide whether it should be
> +implemented as a:
> +
> ++ *Clang diagnostic*: if the check is generic enough, targets code patterns that
> + most probably are bugs (rather than style or readability issues), can be
> + implemented effectively and with extremely low false positive rate, it may
> + make a good Clang diagnostic.
> +
> ++ *Clang static analyzer check*: if the check requires some sort of control flow
> + analysis, it should probably be implemented as a static analyzer check.
> +
> ++ *clang-tidy check* is a good choice for linter-style checks, checks that are
> + related to a certain coding style, checks that address code readability, etc.
> +
> +
> +Preparing your Workspace
> +------------------------
> +
> +If you are new to LLVM development, you should read the `Getting Started with
> +the LLVM System`_, `Using Clang Tools`_ and `How To Setup Tooling For LLVM`_
> +documents to check out and build LLVM, Clang and Clang Extra Tools with CMake.
> +
> +Once you are done, change to the ``llvm/tools/clang/tools/extra`` directory, and
> +let's start!
> +
> +.. _Getting Started with the LLVM System: http://llvm.org/docs/GettingStarted.html
> +.. _Using Clang Tools: http://clang.llvm.org/docs/ClangTools.html
> +
> +
> +The Directory Structure
> +-----------------------
> +
> +:program:`clang-tidy` source code resides in the
> +``llvm/tools/clang/tools/extra`` directory and is structured as follows:
> +
> +::
> +
> + clang-tidy/ # Clang-tidy core.
> + |-- ClangTidy.h # Interfaces for users and checks.
> + |-- ClangTidyModule.h # Interface for clang-tidy modules.
> + |-- ClangTidyModuleRegistry.h # Interface for registering of modules.
> + ...
> + |-- google/ # Google clang-tidy module.
> + |-+
> + |-- GoogleTidyModule.cpp
> + |-- GoogleTidyModule.h
> + ...
> + |-- llvm/ # LLVM clang-tidy module.
> + |-+
> + |-- LLVMTidyModule.cpp
> + |-- LLVMTidyModule.h
> + ...
> + |-- objc/ # Objective-C clang-tidy module.
> + |-+
> + |-- ObjCTidyModule.cpp
> + |-- ObjCTidyModule.h
> + ...
> + |-- tool/ # Sources of the clang-tidy binary.
> + ...
> + test/clang-tidy/ # Integration tests.
> + ...
> + unittests/clang-tidy/ # Unit tests.
> + |-- ClangTidyTest.h
> + |-- GoogleModuleTest.cpp
> + |-- LLVMModuleTest.cpp
> + |-- ObjCModuleTest.cpp
> + ...
> +
> +
> +Writing a clang-tidy Check
> +--------------------------
> +
> +So you have an idea of a useful check for :program:`clang-tidy`.
> +
> +First, if you're not familiar with LLVM development, read through the `Getting
> +Started with LLVM`_ document for instructions on setting up your workflow and
> +the `LLVM Coding Standards`_ document to familiarize yourself with the coding
> +style used in the project. For code reviews we mostly use `LLVM Phabricator`_.
> +
> +.. _Getting Started with LLVM: http://llvm.org/docs/GettingStarted.html
> +.. _LLVM Coding Standards: http://llvm.org/docs/CodingStandards.html
> +.. _LLVM Phabricator: http://llvm.org/docs/Phabricator.html
> +
> +Next, you need to decide which module the check belongs to. Modules
> +are located in subdirectories of `clang-tidy/
> +<http://reviews.llvm.org/diffusion/L/browse/clang-tools-extra/trunk/clang-tidy/>`_
> +and contain checks targeting a certain aspect of code quality (performance,
> +readability, etc.), certain coding style or standard (Google, LLVM, CERT, etc.)
> +or a widely used API (e.g. MPI). Their names are same as user-facing check
> +groups names described :ref:`above <checks-groups-table>`.
> +
> +After choosing the module and the name for the check, run the
> +``clang-tidy/add_new_check.py`` script to create the skeleton of the check and
> +plug it to :program:`clang-tidy`. It's the recommended way of adding new checks.
> +
> +If we want to create a `readability-awesome-function-names`, we would run:
> +
> +.. code-block:: console
> +
> + $ clang-tidy/add_new_check.py readability awesome-function-names
> +
> +
> +The ``add_new_check.py`` script will:
> + * create the class for your check inside the specified module's directory and
> + register it in the module and in the build system;
> + * create a lit test file in the ``test/clang-tidy/`` directory;
> + * create a documentation file and include it into the
> + ``docs/clang-tidy/checks/list.rst``.
> +
> +Let's see in more detail at the check class definition:
> +
> +.. code-block:: c++
> +
> + ...
> +
> + #include "../ClangTidy.h"
> +
> + namespace clang {
> + namespace tidy {
> + namespace readability {
> +
> + ...
> + class AwesomeFunctionNamesCheck : public ClangTidyCheck {
> + public:
> + AwesomeFunctionNamesCheck(StringRef Name, ClangTidyContext *Context)
> + : ClangTidyCheck(Name, Context) {}
> + void registerMatchers(ast_matchers::MatchFinder *Finder) override;
> + void check(const ast_matchers::MatchFinder::MatchResult &Result) override;
> + };
> +
> + } // namespace readability
> + } // namespace tidy
> + } // namespace clang
> +
> + ...
> +
> +Constructor of the check receives the ``Name`` and ``Context`` parameters, and
> +must forward them to the ``ClangTidyCheck`` constructor.
> +
> +In our case the check needs to operate on the AST level and it overrides the
> +``registerMatchers`` and ``check`` methods. If we wanted to analyze code on the
> +preprocessor level, we'd need instead to override the ``registerPPCallbacks``
> +method.
> +
> +In the ``registerMatchers`` method we create an AST Matcher (see `AST Matchers`_
> +for more information) that will find the pattern in the AST that we want to
> +inspect. The results of the matching are passed to the ``check`` method, which
> +can further inspect them and report diagnostics.
> +
> +.. code-block:: c++
> +
> + using namespace ast_matchers;
> +
> + void AwesomeFunctionNamesCheck::registerMatchers(MatchFinder *Finder) {
> + Finder->addMatcher(functionDecl().bind("x"), this);
> + }
> +
> + void AwesomeFunctionNamesCheck::check(const MatchFinder::MatchResult &Result) {
> + const auto *MatchedDecl = Result.Nodes.getNodeAs<FunctionDecl>("x");
> + if (MatchedDecl->getName().startswith("awesome_"))
> + return;
> + diag(MatchedDecl->getLocation(), "function %0 is insufficiently awesome")
> + << MatchedDecl
> + << FixItHint::CreateInsertion(MatchedDecl->getLocation(), "awesome_");
> + }
> +
> +(If you want to see an example of a useful check, look at
> +`clang-tidy/google/ExplicitConstructorCheck.h
> +<http://reviews.llvm.org/diffusion/L/browse/clang-tools-extra/trunk/clang-tidy/google/ExplicitConstructorCheck.h>`_
> +and `clang-tidy/google/ExplicitConstructorCheck.cpp
> +<http://reviews.llvm.org/diffusion/L/browse/clang-tools-extra/trunk/clang-tidy/google/ExplicitConstructorCheck.cpp>`_).
> +
> +
> +Registering your Check
> +----------------------
> +
> +(The ``add_new_check.py`` takes care of registering the check in an existing
> +module. If you want to create a new module or know the details, read on.)
> +
> +The check should be registered in the corresponding module with a distinct name:
> +
> +.. code-block:: c++
> +
> + class MyModule : public ClangTidyModule {
> + public:
> + void addCheckFactories(ClangTidyCheckFactories &CheckFactories) override {
> + CheckFactories.registerCheck<ExplicitConstructorCheck>(
> + "my-explicit-constructor");
> + }
> + };
> +
> +Now we need to register the module in the ``ClangTidyModuleRegistry`` using a
> +statically initialized variable:
> +
> +.. code-block:: c++
> +
> + static ClangTidyModuleRegistry::Add<MyModule> X("my-module",
> + "Adds my lint checks.");
> +
> +
> +When using LLVM build system, we need to use the following hack to ensure the
> +module is linked into the :program:`clang-tidy` binary:
> +
> +Add this near the ``ClangTidyModuleRegistry::Add<MyModule>`` variable:
> +
> +.. code-block:: c++
> +
> + // This anchor is used to force the linker to link in the generated object file
> + // and thus register the MyModule.
> + volatile int MyModuleAnchorSource = 0;
> +
> +And this to the main translation unit of the :program:`clang-tidy` binary (or
> +the binary you link the ``clang-tidy`` library in)
> +``clang-tidy/tool/ClangTidyMain.cpp``:
> +
> +.. code-block:: c++
> +
> + // This anchor is used to force the linker to link the MyModule.
> + extern volatile int MyModuleAnchorSource;
> + static int MyModuleAnchorDestination = MyModuleAnchorSource;
> +
> +
> +Configuring Checks
> +------------------
> +
> +If a check needs configuration options, it can access check-specific options
> +using the ``Options.get<Type>("SomeOption", DefaultValue)`` call in the check
> +constructor. In this case the check should also override the
> +``ClangTidyCheck::storeOptions`` method to make the options provided by the
> +check discoverable. This method lets :program:`clang-tidy` know which options
> +the check implements and what the current values are (e.g. for the
> +``-dump-config`` command line option).
> +
> +.. code-block:: c++
> +
> + class MyCheck : public ClangTidyCheck {
> + const unsigned SomeOption1;
> + const std::string SomeOption2;
> +
> + public:
> + MyCheck(StringRef Name, ClangTidyContext *Context)
> + : ClangTidyCheck(Name, Context),
> + SomeOption(Options.get("SomeOption1", -1U)),
> + SomeOption(Options.get("SomeOption2", "some default")) {}
> +
> + void storeOptions(ClangTidyOptions::OptionMap &Opts) override {
> + Options.store(Opts, "SomeOption1", SomeOption1);
> + Options.store(Opts, "SomeOption2", SomeOption2);
> + }
> + ...
> +
> +Assuming the check is registered with the name "my-check", the option can then
> +be set in a ``.clang-tidy`` file in the following way:
> +
> +.. code-block:: yaml
> +
> + CheckOptions:
> + - key: my-check.SomeOption1
> + value: 123
> + - key: my-check.SomeOption2
> + value: 'some other value'
> +
> +If you need to specify check options on a command line, you can use the inline
> +YAML format:
> +
> +.. code-block:: console
> +
> + $ clang-tidy -config="{CheckOptions: [{key: a, value: b}, {key: x, value: y}]}" ...
> +
> +
> +Testing Checks
> +--------------
> +
> +To run tests for :program:`clang-tidy` use the command:
> +
> +.. code-block:: console
> +
> + $ ninja check-clang-tools
> +
> +:program:`clang-tidy` checks can be tested using either unit tests or
> +`lit`_ tests. Unit tests may be more convenient to test complex replacements
> +with strict checks. `Lit`_ tests allow using partial text matching and regular
> +expressions which makes them more suitable for writing compact tests for
> +diagnostic messages.
> +
> +The ``check_clang_tidy.py`` script provides an easy way to test both
> +diagnostic messages and fix-its. It filters out ``CHECK`` lines from the test
> +file, runs :program:`clang-tidy` and verifies messages and fixes with two
> +separate `FileCheck`_ invocations: once with FileCheck's directive
> +prefix set to ``CHECK-MESSAGES``, validating the diagnostic messages,
> +and once with the directive prefix set to ``CHECK-FIXES``, running
> +against the fixed code (i.e., the code after generated fix-its are
> +applied). In particular, ``CHECK-FIXES:`` can be used to check
> +that code was not modified by fix-its, by checking that it is present
> +unchanged in the fixed code. The full set of `FileCheck`_ directives
> +is available (e.g., ``CHECK-MESSAGES-SAME:``, ``CHECK-MESSAGES-NOT:``), though
> +typically the basic ``CHECK`` forms (``CHECK-MESSAGES`` and ``CHECK-FIXES``)
> +are sufficient for clang-tidy tests. Note that the `FileCheck`_
> +documentation mostly assumes the default prefix (``CHECK``), and hence
> +describes the directive as ``CHECK:``, ``CHECK-SAME:``, ``CHECK-NOT:``, etc.
> +Replace ``CHECK`` by either ``CHECK-FIXES`` or ``CHECK-MESSAGES`` for
> +clang-tidy tests.
> +
> +An additional check enabled by ``check_clang_tidy.py`` ensures that
> +if `CHECK-MESSAGES:` is used in a file then every warning or error
> +must have an associated CHECK in that file. Or, you can use ``CHECK-NOTES:``
> +instead, if you want to **also** ensure that all the notes are checked.
> +
> +To use the ``check_clang_tidy.py`` script, put a .cpp file with the
> +appropriate ``RUN`` line in the ``test/clang-tidy`` directory. Use
> +``CHECK-MESSAGES:`` and ``CHECK-FIXES:`` lines to write checks against
> +diagnostic messages and fixed code.
> +
> +It's advised to make the checks as specific as possible to avoid checks matching
> +to incorrect parts of the input. Use ``[[@LINE+X]]``/``[[@LINE-X]]``
> +substitutions and distinct function and variable names in the test code.
> +
> +Here's an example of a test using the ``check_clang_tidy.py`` script (the full
> +source code is at `test/clang-tidy/google-readability-casting.cpp`_):
> +
> +.. code-block:: c++
> +
> + // RUN: %check_clang_tidy %s google-readability-casting %t
> +
> + void f(int a) {
> + int b = (int)a;
> + // CHECK-MESSAGES: :[[@LINE-1]]:11: warning: redundant cast to the same type [google-readability-casting]
> + // CHECK-FIXES: int b = a;
> + }
> +
> +To check more than one scenario in the same test file use
> +``-check-suffix=SUFFIX-NAME`` on ``check_clang_tidy.py`` command line or
> +``-check-suffixes=SUFFIX-NAME-1,SUFFIX-NAME-2,...``.
> +With ``-check-suffix[es]=SUFFIX-NAME`` you need to replace your ``CHECK-*``
> +directives with ``CHECK-MESSAGES-SUFFIX-NAME`` and ``CHECK-FIXES-SUFFIX-NAME``.
> +
> +Here's an example:
> +
> +.. code-block:: c++
> +
> + // RUN: %check_clang_tidy -check-suffix=USING-A %s misc-unused-using-decls %t -- -- -DUSING_A
> + // RUN: %check_clang_tidy -check-suffix=USING-B %s misc-unused-using-decls %t -- -- -DUSING_B
> + // RUN: %check_clang_tidy %s misc-unused-using-decls %t
> + ...
> + // CHECK-MESSAGES-USING-A: :[[@LINE-8]]:10: warning: using decl 'A' {{.*}}
> + // CHECK-MESSAGES-USING-B: :[[@LINE-7]]:10: warning: using decl 'B' {{.*}}
> + // CHECK-MESSAGES: :[[@LINE-6]]:10: warning: using decl 'C' {{.*}}
> + // CHECK-FIXES-USING-A-NOT: using a::A;$
> + // CHECK-FIXES-USING-B-NOT: using a::B;$
> + // CHECK-FIXES-NOT: using a::C;$
> +
> +
> +There are many dark corners in the C++ language, and it may be difficult to make
> +your check work perfectly in all cases, especially if it issues fix-it hints. The
> +most frequent pitfalls are macros and templates:
> +
> +1. code written in a macro body/template definition may have a different meaning
> + depending on the macro expansion/template instantiation;
> +2. multiple macro expansions/template instantiations may result in the same code
> + being inspected by the check multiple times (possibly, with different
> + meanings, see 1), and the same warning (or a slightly different one) may be
> + issued by the check multiple times; :program:`clang-tidy` will deduplicate
> + _identical_ warnings, but if the warnings are slightly different, all of them
> + will be shown to the user (and used for applying fixes, if any);
> +3. making replacements to a macro body/template definition may be fine for some
> + macro expansions/template instantiations, but easily break some other
> + expansions/instantiations.
> +
> +.. _lit: http://llvm.org/docs/CommandGuide/lit.html
> +.. _FileCheck: http://llvm.org/docs/CommandGuide/FileCheck.html
> +.. _test/clang-tidy/google-readability-casting.cpp: http://reviews.llvm.org/diffusion/L/browse/clang-tools-extra/trunk/test/clang-tidy/google-readability-casting.cpp
> +
> +
> +Running clang-tidy on LLVM
> +--------------------------
> +
> +To test a check it's best to try it out on a larger code base. LLVM and Clang
> +are the natural targets as you already have the source code around. The most
> +convenient way to run :program:`clang-tidy` is with a compile command database;
> +CMake can automatically generate one, for a description of how to enable it see
> +`How To Setup Tooling For LLVM`_. Once ``compile_commands.json`` is in place and
> +a working version of :program:`clang-tidy` is in ``PATH`` the entire code base
> +can be analyzed with ``clang-tidy/tool/run-clang-tidy.py``. The script executes
> +:program:`clang-tidy` with the default set of checks on every translation unit
> +in the compile command database and displays the resulting warnings and errors.
> +The script provides multiple configuration flags.
> +
> +* The default set of checks can be overridden using the ``-checks`` argument,
> + taking the identical format as :program:`clang-tidy` does. For example
> + ``-checks=-*,modernize-use-override`` will run the ``modernize-use-override``
> + check only.
> +
> +* To restrict the files examined you can provide one or more regex arguments
> + that the file names are matched against.
> + ``run-clang-tidy.py clang-tidy/.*Check\.cpp`` will only analyze clang-tidy
> + checks. It may also be necessary to restrict the header files warnings are
> + displayed from using the ``-header-filter`` flag. It has the same behavior
> + as the corresponding :program:`clang-tidy` flag.
> +
> +* To apply suggested fixes ``-fix`` can be passed as an argument. This gathers
> + all changes in a temporary directory and applies them. Passing ``-format``
> + will run clang-format over changed lines.
> +
> +
> +On checks profiling
> +-------------------
> +
> +:program:`clang-tidy` can collect per-check profiling info, and output it
> +for each processed source file (translation unit).
> +
> +To enable profiling info collection, use the ``-enable-check-profile`` argument.
> +The timings will be output to ``stderr`` as a table. Example output:
> +
> +.. code-block:: console
> +
> + $ clang-tidy -enable-check-profile -checks=-*,readability-function-size source.cpp
> + ===-------------------------------------------------------------------------===
> + clang-tidy checks profiling
> + ===-------------------------------------------------------------------------===
> + Total Execution Time: 1.0282 seconds (1.0258 wall clock)
> +
> + ---User Time--- --System Time-- --User+System-- ---Wall Time--- --- Name ---
> + 0.9136 (100.0%) 0.1146 (100.0%) 1.0282 (100.0%) 1.0258 (100.0%) readability-function-size
> + 0.9136 (100.0%) 0.1146 (100.0%) 1.0282 (100.0%) 1.0258 (100.0%) Total
> +
> +It can also store that data as JSON files for further processing. Example output:
> +
> +.. code-block:: console
> +
> + $ clang-tidy -enable-check-profile -store-check-profile=. -checks=-*,readability-function-size source.cpp
> + $ # Note that there won't be timings table printed to the console.
> + $ ls /tmp/out/
> + 20180516161318717446360-source.cpp.json
> + $ cat 20180516161318717446360-source.cpp.json
> + {
> + "file": "/path/to/source.cpp",
> + "timestamp": "2018-05-16 16:13:18.717446360",
> + "profile": {
> + "time.clang-tidy.readability-function-size.wall": 1.0421266555786133e+00,
> + "time.clang-tidy.readability-function-size.user": 9.2088400000005421e-01,
> + "time.clang-tidy.readability-function-size.sys": 1.2418899999999974e-01
> + }
> + }
> +
> +There is only one argument that controls profile storage:
> +
> +* ``-store-check-profile=<prefix>``
> +
> + By default reports are printed in tabulated format to stderr. When this option
> + is passed, these per-TU profiles are instead stored as JSON.
> + If the prefix is not an absolute path, it is considered to be relative to the
> + directory from where you have run :program:`clang-tidy`. All ``.`` and ``..``
> + patterns in the path are collapsed, and symlinks are resolved.
> +
> + Example:
> + Let's suppose you have a source file named ``example.cpp``, located in the
> + ``/source`` directory. Only the input filename is used, not the full path
> + to the source file. Additionally, it is prefixed with the current timestamp.
> +
> + * If you specify ``-store-check-profile=/tmp``, then the profile will be saved
> + to ``/tmp/<ISO8601-like timestamp>-example.cpp.json``
> +
> + * If you run :program:`clang-tidy` from within ``/foo`` directory, and specify
> + ``-store-check-profile=.``, then the profile will still be saved to
> + ``/foo/<ISO8601-like timestamp>-example.cpp.json``
>
> Added: clang-tools-extra/trunk/docs/clang-tidy/Integrations.rst
> URL: http://llvm.org/viewvc/llvm-project/clang-tools-extra/trunk/docs/clang-tidy/Integrations.rst?rev=351463&view=auto
> ==============================================================================
> --- clang-tools-extra/trunk/docs/clang-tidy/Integrations.rst (added)
> +++ clang-tools-extra/trunk/docs/clang-tidy/Integrations.rst Thu Jan 17 10:31:34 2019
> @@ -0,0 +1,117 @@
> +==================================
> +Clang-tidy IDE/Editor Integrations
> +==================================
> +
> +.. _Clangd: https://clang.llvm.org/extra/clangd.html
> +
> +Apart from being a standalone tool, :program:`clang-tidy` is integrated into
> +various IDEs, code analyzers, and editors. Besides, it is currently being
> +integrated into Clangd_. The following table shows the most
> +well-known :program:`clang-tidy` integrations in detail.
> +
> ++--------------------------------------+------------------------+---------------------------------+--------------------------+-----------------------------------------+--------------------------+
> +| | Feature |
> ++======================================+========================+=================================+==========================+=========================================+==========================+
> +| **Tool** | On-the-fly inspection | Check list configuration (GUI) | Options to checks (GUI) | Configuration via ``.clang-tidy`` files | Custom clang-tidy binary |
> ++--------------------------------------+------------------------+---------------------------------+--------------------------+-----------------------------------------+--------------------------+
> +|A.L.E. for Vim | \+\ | \-\ | \-\ | \-\ | \+\ |
> ++--------------------------------------+------------------------+---------------------------------+--------------------------+-----------------------------------------+--------------------------+
> +|Clang Power Tools for Visual Studio | \-\ | \+\ | \-\ | \+\ | \-\ |
> ++--------------------------------------+------------------------+---------------------------------+--------------------------+-----------------------------------------+--------------------------+
> +|Clangd | \+\ | \-\ | \-\ | \-\ | \-\ |
> ++--------------------------------------+------------------------+---------------------------------+--------------------------+-----------------------------------------+--------------------------+
> +|CLion IDE | \+\ | \+\ | \+\ | \+\ | \+\ |
> ++--------------------------------------+------------------------+---------------------------------+--------------------------+-----------------------------------------+--------------------------+
> +|CodeChecker | \-\ | \-\ | \-\ | \-\ | \+\ |
> ++--------------------------------------+------------------------+---------------------------------+--------------------------+-----------------------------------------+--------------------------+
> +|CPPCheck | \-\ | \-\ | \-\ | \-\ | \-\ |
> ++--------------------------------------+------------------------+---------------------------------+--------------------------+-----------------------------------------+--------------------------+
> +|CPPDepend | \-\ | \-\ | \-\ | \-\ | \-\ |
> ++--------------------------------------+------------------------+---------------------------------+--------------------------+-----------------------------------------+--------------------------+
> +|Flycheck for Emacs | \+\ | \-\ | \-\ | \+\ | \+\ |
> ++--------------------------------------+------------------------+---------------------------------+--------------------------+-----------------------------------------+--------------------------+
> +|KDevelop IDE | \-\ | \+\ | \+\ | \+\ | \+\ |
> ++--------------------------------------+------------------------+---------------------------------+--------------------------+-----------------------------------------+--------------------------+
> +|Qt Creator IDE | \+\ | \+\ | \-\ | \-\ | \+\ |
> ++--------------------------------------+------------------------+---------------------------------+--------------------------+-----------------------------------------+--------------------------+
> +|ReSharper C++ for Visual Studio | \+\ | \+\ | \-\ | \+\ | \-\ |
> ++--------------------------------------+------------------------+---------------------------------+--------------------------+-----------------------------------------+--------------------------+
> +|Syntastic for Vim | \+\ | \-\ | \-\ | \-\ | \+\ |
> ++--------------------------------------+------------------------+---------------------------------+--------------------------+-----------------------------------------+--------------------------+
> +|Visual Assist for Visual Studio | \+\ | \+\ | \-\ | \-\ | \-\ |
> ++--------------------------------------+------------------------+---------------------------------+--------------------------+-----------------------------------------+--------------------------+
> +
> +**IDEs**
> +
> +.. _CLion: https://www.jetbrains.com/clion/
> +.. _integrates clang-tidy: https://www.jetbrains.com/help/clion/clang-tidy-checks-support.html
> +
> +CLion_ 2017.2 and later `integrates clang-tidy`_ as an extension to the
> +built-in code analyzer. Starting from 2018.2 EAP, CLion allows using
> +:program:`clang-tidy` via Clangd. Inspections and applicable quick-fixes are
> +performed on the fly, and checks can be configured in standard command line
> +format. In this integration, you can switch to the :program:`clang-tidy`
> +binary different from the bundled one, pass the configuration in
> +``.clang-tidy`` files instead of using the IDE settings, and configure
> +options for particular checks.
> +
> +.. _KDevelop: https://www.kdevelop.org/
> +.. _kdev-clang-tidy: https://github.com/KDE/kdev-clang-tidy/
> +
> +KDevelop_ with the kdev-clang-tidy_ plugin, starting from version 5.1, performs
> +static analysis using :program:`clang-tidy`. The plugin launches the
> +:program:`clang-tidy` binary from the specified location and parses its
> +output to provide a list of issues.
> +
> +.. _QtCreator: https://www.qt.io/
> +.. _Clang Code Model: http://doc.qt.io/qtcreator/creator-clang-codemodel.html
> +
> +QtCreator_ 4.6 integrates :program:`clang-tidy` warnings into the editor
> +diagnostics under the `Clang Code Model`_. To employ :program:`clang-tidy`
> +inspection in QtCreator, you need to create a copy of one of the presets and
> +choose the checks to be performed in the Clang Code Model Warnings menu.
> +
> +.. _MS Visual Studio: https://visualstudio.microsoft.com/
> +.. _ReSharper C++: https://www.jetbrains.com/help/resharper/Clang_Tidy_Integration.html
> +.. _Visual Assist: https://docs.wholetomato.com/default.asp?W761
> +.. _Clang Power Tools: https://marketplace.visualstudio.com/items?itemName=caphyon.ClangPowerTools
> +.. _clang-tidy-vs: https://github.com/llvm-mirror/clang-tools-extra/tree/master/clang-tidy-vs
> +
> +`MS Visual Studio`_ has a native clang-tidy-vs_ plugin and also can integrate
> +:program:`clang-tidy` by means of three other tools. The `ReSharper C++`_
> +extension, version 2017.3 and later, provides seamless :program:`clang-tidy`
> +integration: checks and quick-fixes run alongside native inspections. Apart
> +from that, ReSharper C++ incorporates :program:`clang-tidy` as a separate
> +step of its code clean-up process. `Visual Assist`_ build 2210 includes a
> +subset of :program:`clang-tidy` checklist to inspect the code as you edit.
> +Another way to bring :program:`clang-tidy` functionality to Visual Studio is
> +the `Clang Power Tools`_ plugin, which includes most of the
> +:program:`clang-tidy` checks and runs them during compilation or as a separate
> +step of code analysis.
> +
> +**Editors**
> +
> +.. _Flycheck: https://github.com/ch1bo/flycheck-clang-tidy
> +.. _Syntastic: https://github.com/vim-syntastic/syntastic
> +.. _A.L.E.: https://github.com/w0rp/ale
> +.. _Emacs24: https://www.gnu.org/s/emacs/
> +.. _Vim: https://www.vim.org/
> +
> +Emacs24_, when expanded with the Flycheck_ plugin, incorporates the
> +:program:`clang-tidy` inspection into the syntax analyzer. For Vim_, you can
> +use Syntastic_, which includes :program:`clang-tidy`, or `A.L.E.`_,
> +a lint engine that applies :program:`clang-tidy` along with other linters.
> +
> +**Analyzers**
> +
> +.. _CPPDepend: https://www.cppdepend.com/cppdependv2018
> +.. _CPPCheck: https://sourceforge.net/p/cppcheck/news/
> +.. _CodeChecker: https://github.com/Ericsson/codechecker
> +.. _plugin: https://github.com/Ericsson/CodeCheckerEclipsePlugin
> +
> +:program:`clang-tidy` is integrated in CPPDepend_ starting from version 2018.1
> +and CPPCheck_ 1.82. CPPCheck integration lets you import Visual Studio
> +solutions and run the :program:`clang-tidy` inspection on them. The
> +CodeChecker_ application of version 5.3 or later, which also comes as a plugin_
> +for Eclipse, supports :program:`clang-tidy` as a static analysis instrument and
> +allows to use a custom :program:`clang-tidy` binary.
>
> Modified: clang-tools-extra/trunk/docs/clang-tidy/index.rst
> URL: http://llvm.org/viewvc/llvm-project/clang-tools-extra/trunk/docs/clang-tidy/index.rst?rev=351463&r1=351462&r2=351463&view=diff
> ==============================================================================
> --- clang-tools-extra/trunk/docs/clang-tidy/index.rst (original)
> +++ clang-tools-extra/trunk/docs/clang-tidy/index.rst Thu Jan 17 10:31:34 2019
> @@ -10,6 +10,8 @@ See also:
> :maxdepth: 1
>
> The list of clang-tidy checks <checks/list>
> + Clang-tidy IDE/Editor Integrations <Integrations>
> + Getting Involved <Contributing>
>
> :program:`clang-tidy` is a clang-based C++ "linter" tool. Its purpose is to
> provide an extensible framework for diagnosing and fixing typical programming
> @@ -310,511 +312,3 @@ the parenthesis) whitespaces can be used
>
> .. _LibTooling: http://clang.llvm.org/docs/LibTooling.html
> .. _How To Setup Tooling For LLVM: http://clang.llvm.org/docs/HowToSetupToolingForLLVM.html
> -
> -
> -Getting Involved
> -================
> -
> -:program:`clang-tidy` has several own checks and can run Clang static analyzer
> -checks, but its power is in the ability to easily write custom checks.
> -
> -Checks are organized in modules, which can be linked into :program:`clang-tidy`
> -with minimal or no code changes in :program:`clang-tidy`.
> -
> -Checks can plug into the analysis on the preprocessor level using `PPCallbacks`_
> -or on the AST level using `AST Matchers`_. When an error is found, checks can
> -report them in a way similar to how Clang diagnostics work. A fix-it hint can be
> -attached to a diagnostic message.
> -
> -The interface provided by :program:`clang-tidy` makes it easy to write useful
> -and precise checks in just a few lines of code. If you have an idea for a good
> -check, the rest of this document explains how to do this.
> -
> -There are a few tools particularly useful when developing clang-tidy checks:
> - * ``add_new_check.py`` is a script to automate the process of adding a new
> - check, it will create the check, update the CMake file and create a test;
> - * ``rename_check.py`` does what the script name suggests, renames an existing
> - check;
> - * :program:`clang-query` is invaluable for interactive prototyping of AST
> - matchers and exploration of the Clang AST;
> - * `clang-check`_ with the ``-ast-dump`` (and optionally ``-ast-dump-filter``)
> - provides a convenient way to dump AST of a C++ program.
> -
> -If CMake is configured with ``CLANG_ENABLE_STATIC_ANALYZER``,
> -:program:`clang-tidy` will not be built with support for the
> -``clang-analyzer-*`` checks or the ``mpi-*`` checks.
> -
> -
> -.. _AST Matchers: http://clang.llvm.org/docs/LibASTMatchers.html
> -.. _PPCallbacks: http://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html
> -.. _clang-check: http://clang.llvm.org/docs/ClangCheck.html
> -
> -
> -Choosing the Right Place for your Check
> ----------------------------------------
> -
> -If you have an idea of a check, you should decide whether it should be
> -implemented as a:
> -
> -+ *Clang diagnostic*: if the check is generic enough, targets code patterns that
> - most probably are bugs (rather than style or readability issues), can be
> - implemented effectively and with extremely low false positive rate, it may
> - make a good Clang diagnostic.
> -
> -+ *Clang static analyzer check*: if the check requires some sort of control flow
> - analysis, it should probably be implemented as a static analyzer check.
> -
> -+ *clang-tidy check* is a good choice for linter-style checks, checks that are
> - related to a certain coding style, checks that address code readability, etc.
> -
> -
> -Preparing your Workspace
> -------------------------
> -
> -If you are new to LLVM development, you should read the `Getting Started with
> -the LLVM System`_, `Using Clang Tools`_ and `How To Setup Tooling For LLVM`_
> -documents to check out and build LLVM, Clang and Clang Extra Tools with CMake.
> -
> -Once you are done, change to the ``llvm/tools/clang/tools/extra`` directory, and
> -let's start!
> -
> -.. _Getting Started with the LLVM System: http://llvm.org/docs/GettingStarted.html
> -.. _Using Clang Tools: http://clang.llvm.org/docs/ClangTools.html
> -
> -
> -The Directory Structure
> ------------------------
> -
> -:program:`clang-tidy` source code resides in the
> -``llvm/tools/clang/tools/extra`` directory and is structured as follows:
> -
> -::
> -
> - clang-tidy/ # Clang-tidy core.
> - |-- ClangTidy.h # Interfaces for users and checks.
> - |-- ClangTidyModule.h # Interface for clang-tidy modules.
> - |-- ClangTidyModuleRegistry.h # Interface for registering of modules.
> - ...
> - |-- google/ # Google clang-tidy module.
> - |-+
> - |-- GoogleTidyModule.cpp
> - |-- GoogleTidyModule.h
> - ...
> - |-- llvm/ # LLVM clang-tidy module.
> - |-+
> - |-- LLVMTidyModule.cpp
> - |-- LLVMTidyModule.h
> - ...
> - |-- objc/ # Objective-C clang-tidy module.
> - |-+
> - |-- ObjCTidyModule.cpp
> - |-- ObjCTidyModule.h
> - ...
> - |-- tool/ # Sources of the clang-tidy binary.
> - ...
> - test/clang-tidy/ # Integration tests.
> - ...
> - unittests/clang-tidy/ # Unit tests.
> - |-- ClangTidyTest.h
> - |-- GoogleModuleTest.cpp
> - |-- LLVMModuleTest.cpp
> - |-- ObjCModuleTest.cpp
> - ...
> -
> -
> -Writing a clang-tidy Check
> ---------------------------
> -
> -So you have an idea of a useful check for :program:`clang-tidy`.
> -
> -First, if you're not familiar with LLVM development, read through the `Getting
> -Started with LLVM`_ document for instructions on setting up your workflow and
> -the `LLVM Coding Standards`_ document to familiarize yourself with the coding
> -style used in the project. For code reviews we mostly use `LLVM Phabricator`_.
> -
> -.. _Getting Started with LLVM: http://llvm.org/docs/GettingStarted.html
> -.. _LLVM Coding Standards: http://llvm.org/docs/CodingStandards.html
> -.. _LLVM Phabricator: http://llvm.org/docs/Phabricator.html
> -
> -Next, you need to decide which module the check belongs to. Modules
> -are located in subdirectories of `clang-tidy/
> -<http://reviews.llvm.org/diffusion/L/browse/clang-tools-extra/trunk/clang-tidy/>`_
> -and contain checks targeting a certain aspect of code quality (performance,
> -readability, etc.), certain coding style or standard (Google, LLVM, CERT, etc.)
> -or a widely used API (e.g. MPI). Their names are same as user-facing check
> -groups names described :ref:`above <checks-groups-table>`.
> -
> -After choosing the module and the name for the check, run the
> -``clang-tidy/add_new_check.py`` script to create the skeleton of the check and
> -plug it to :program:`clang-tidy`. It's the recommended way of adding new checks.
> -
> -If we want to create a `readability-awesome-function-names`, we would run:
> -
> -.. code-block:: console
> -
> - $ clang-tidy/add_new_check.py readability awesome-function-names
> -
> -
> -The ``add_new_check.py`` script will:
> - * create the class for your check inside the specified module's directory and
> - register it in the module and in the build system;
> - * create a lit test file in the ``test/clang-tidy/`` directory;
> - * create a documentation file and include it into the
> - ``docs/clang-tidy/checks/list.rst``.
> -
> -Let's see in more detail at the check class definition:
> -
> -.. code-block:: c++
> -
> - ...
> -
> - #include "../ClangTidy.h"
> -
> - namespace clang {
> - namespace tidy {
> - namespace readability {
> -
> - ...
> - class AwesomeFunctionNamesCheck : public ClangTidyCheck {
> - public:
> - AwesomeFunctionNamesCheck(StringRef Name, ClangTidyContext *Context)
> - : ClangTidyCheck(Name, Context) {}
> - void registerMatchers(ast_matchers::MatchFinder *Finder) override;
> - void check(const ast_matchers::MatchFinder::MatchResult &Result) override;
> - };
> -
> - } // namespace readability
> - } // namespace tidy
> - } // namespace clang
> -
> - ...
> -
> -Constructor of the check receives the ``Name`` and ``Context`` parameters, and
> -must forward them to the ``ClangTidyCheck`` constructor.
> -
> -In our case the check needs to operate on the AST level and it overrides the
> -``registerMatchers`` and ``check`` methods. If we wanted to analyze code on the
> -preprocessor level, we'd need instead to override the ``registerPPCallbacks``
> -method.
> -
> -In the ``registerMatchers`` method we create an AST Matcher (see `AST Matchers`_
> -for more information) that will find the pattern in the AST that we want to
> -inspect. The results of the matching are passed to the ``check`` method, which
> -can further inspect them and report diagnostics.
> -
> -.. code-block:: c++
> -
> - using namespace ast_matchers;
> -
> - void AwesomeFunctionNamesCheck::registerMatchers(MatchFinder *Finder) {
> - Finder->addMatcher(functionDecl().bind("x"), this);
> - }
> -
> - void AwesomeFunctionNamesCheck::check(const MatchFinder::MatchResult &Result) {
> - const auto *MatchedDecl = Result.Nodes.getNodeAs<FunctionDecl>("x");
> - if (MatchedDecl->getName().startswith("awesome_"))
> - return;
> - diag(MatchedDecl->getLocation(), "function %0 is insufficiently awesome")
> - << MatchedDecl
> - << FixItHint::CreateInsertion(MatchedDecl->getLocation(), "awesome_");
> - }
> -
> -(If you want to see an example of a useful check, look at
> -`clang-tidy/google/ExplicitConstructorCheck.h
> -<http://reviews.llvm.org/diffusion/L/browse/clang-tools-extra/trunk/clang-tidy/google/ExplicitConstructorCheck.h>`_
> -and `clang-tidy/google/ExplicitConstructorCheck.cpp
> -<http://reviews.llvm.org/diffusion/L/browse/clang-tools-extra/trunk/clang-tidy/google/ExplicitConstructorCheck.cpp>`_).
> -
> -
> -Registering your Check
> -----------------------
> -
> -(The ``add_new_check.py`` takes care of registering the check in an existing
> -module. If you want to create a new module or know the details, read on.)
> -
> -The check should be registered in the corresponding module with a distinct name:
> -
> -.. code-block:: c++
> -
> - class MyModule : public ClangTidyModule {
> - public:
> - void addCheckFactories(ClangTidyCheckFactories &CheckFactories) override {
> - CheckFactories.registerCheck<ExplicitConstructorCheck>(
> - "my-explicit-constructor");
> - }
> - };
> -
> -Now we need to register the module in the ``ClangTidyModuleRegistry`` using a
> -statically initialized variable:
> -
> -.. code-block:: c++
> -
> - static ClangTidyModuleRegistry::Add<MyModule> X("my-module",
> - "Adds my lint checks.");
> -
> -
> -When using LLVM build system, we need to use the following hack to ensure the
> -module is linked into the :program:`clang-tidy` binary:
> -
> -Add this near the ``ClangTidyModuleRegistry::Add<MyModule>`` variable:
> -
> -.. code-block:: c++
> -
> - // This anchor is used to force the linker to link in the generated object file
> - // and thus register the MyModule.
> - volatile int MyModuleAnchorSource = 0;
> -
> -And this to the main translation unit of the :program:`clang-tidy` binary (or
> -the binary you link the ``clang-tidy`` library in)
> -``clang-tidy/tool/ClangTidyMain.cpp``:
> -
> -.. code-block:: c++
> -
> - // This anchor is used to force the linker to link the MyModule.
> - extern volatile int MyModuleAnchorSource;
> - static int MyModuleAnchorDestination = MyModuleAnchorSource;
> -
> -
> -Configuring Checks
> -------------------
> -
> -If a check needs configuration options, it can access check-specific options
> -using the ``Options.get<Type>("SomeOption", DefaultValue)`` call in the check
> -constructor. In this case the check should also override the
> -``ClangTidyCheck::storeOptions`` method to make the options provided by the
> -check discoverable. This method lets :program:`clang-tidy` know which options
> -the check implements and what the current values are (e.g. for the
> -``-dump-config`` command line option).
> -
> -.. code-block:: c++
> -
> - class MyCheck : public ClangTidyCheck {
> - const unsigned SomeOption1;
> - const std::string SomeOption2;
> -
> - public:
> - MyCheck(StringRef Name, ClangTidyContext *Context)
> - : ClangTidyCheck(Name, Context),
> - SomeOption(Options.get("SomeOption1", -1U)),
> - SomeOption(Options.get("SomeOption2", "some default")) {}
> -
> - void storeOptions(ClangTidyOptions::OptionMap &Opts) override {
> - Options.store(Opts, "SomeOption1", SomeOption1);
> - Options.store(Opts, "SomeOption2", SomeOption2);
> - }
> - ...
> -
> -Assuming the check is registered with the name "my-check", the option can then
> -be set in a ``.clang-tidy`` file in the following way:
> -
> -.. code-block:: yaml
> -
> - CheckOptions:
> - - key: my-check.SomeOption1
> - value: 123
> - - key: my-check.SomeOption2
> - value: 'some other value'
> -
> -If you need to specify check options on a command line, you can use the inline
> -YAML format:
> -
> -.. code-block:: console
> -
> - $ clang-tidy -config="{CheckOptions: [{key: a, value: b}, {key: x, value: y}]}" ...
> -
> -
> -Testing Checks
> ---------------
> -
> -To run tests for :program:`clang-tidy` use the command:
> -
> -.. code-block:: console
> -
> - $ ninja check-clang-tools
> -
> -:program:`clang-tidy` checks can be tested using either unit tests or
> -`lit`_ tests. Unit tests may be more convenient to test complex replacements
> -with strict checks. `Lit`_ tests allow using partial text matching and regular
> -expressions which makes them more suitable for writing compact tests for
> -diagnostic messages.
> -
> -The ``check_clang_tidy.py`` script provides an easy way to test both
> -diagnostic messages and fix-its. It filters out ``CHECK`` lines from the test
> -file, runs :program:`clang-tidy` and verifies messages and fixes with two
> -separate `FileCheck`_ invocations: once with FileCheck's directive
> -prefix set to ``CHECK-MESSAGES``, validating the diagnostic messages,
> -and once with the directive prefix set to ``CHECK-FIXES``, running
> -against the fixed code (i.e., the code after generated fix-its are
> -applied). In particular, ``CHECK-FIXES:`` can be used to check
> -that code was not modified by fix-its, by checking that it is present
> -unchanged in the fixed code. The full set of `FileCheck`_ directives
> -is available (e.g., ``CHECK-MESSAGES-SAME:``, ``CHECK-MESSAGES-NOT:``), though
> -typically the basic ``CHECK`` forms (``CHECK-MESSAGES`` and ``CHECK-FIXES``)
> -are sufficient for clang-tidy tests. Note that the `FileCheck`_
> -documentation mostly assumes the default prefix (``CHECK``), and hence
> -describes the directive as ``CHECK:``, ``CHECK-SAME:``, ``CHECK-NOT:``, etc.
> -Replace ``CHECK`` by either ``CHECK-FIXES`` or ``CHECK-MESSAGES`` for
> -clang-tidy tests.
> -
> -An additional check enabled by ``check_clang_tidy.py`` ensures that
> -if `CHECK-MESSAGES:` is used in a file then every warning or error
> -must have an associated CHECK in that file. Or, you can use ``CHECK-NOTES:``
> -instead, if you want to **also** ensure that all the notes are checked.
> -
> -To use the ``check_clang_tidy.py`` script, put a .cpp file with the
> -appropriate ``RUN`` line in the ``test/clang-tidy`` directory. Use
> -``CHECK-MESSAGES:`` and ``CHECK-FIXES:`` lines to write checks against
> -diagnostic messages and fixed code.
> -
> -It's advised to make the checks as specific as possible to avoid checks matching
> -to incorrect parts of the input. Use ``[[@LINE+X]]``/``[[@LINE-X]]``
> -substitutions and distinct function and variable names in the test code.
> -
> -Here's an example of a test using the ``check_clang_tidy.py`` script (the full
> -source code is at `test/clang-tidy/google-readability-casting.cpp`_):
> -
> -.. code-block:: c++
> -
> - // RUN: %check_clang_tidy %s google-readability-casting %t
> -
> - void f(int a) {
> - int b = (int)a;
> - // CHECK-MESSAGES: :[[@LINE-1]]:11: warning: redundant cast to the same type [google-readability-casting]
> - // CHECK-FIXES: int b = a;
> - }
> -
> -To check more than one scenario in the same test file use
> -``-check-suffix=SUFFIX-NAME`` on ``check_clang_tidy.py`` command line or
> -``-check-suffixes=SUFFIX-NAME-1,SUFFIX-NAME-2,...``.
> -With ``-check-suffix[es]=SUFFIX-NAME`` you need to replace your ``CHECK-*``
> -directives with ``CHECK-MESSAGES-SUFFIX-NAME`` and ``CHECK-FIXES-SUFFIX-NAME``.
> -
> -Here's an example:
> -
> -.. code-block:: c++
> -
> - // RUN: %check_clang_tidy -check-suffix=USING-A %s misc-unused-using-decls %t -- -- -DUSING_A
> - // RUN: %check_clang_tidy -check-suffix=USING-B %s misc-unused-using-decls %t -- -- -DUSING_B
> - // RUN: %check_clang_tidy %s misc-unused-using-decls %t
> - ...
> - // CHECK-MESSAGES-USING-A: :[[@LINE-8]]:10: warning: using decl 'A' {{.*}}
> - // CHECK-MESSAGES-USING-B: :[[@LINE-7]]:10: warning: using decl 'B' {{.*}}
> - // CHECK-MESSAGES: :[[@LINE-6]]:10: warning: using decl 'C' {{.*}}
> - // CHECK-FIXES-USING-A-NOT: using a::A;$
> - // CHECK-FIXES-USING-B-NOT: using a::B;$
> - // CHECK-FIXES-NOT: using a::C;$
> -
> -
> -There are many dark corners in the C++ language, and it may be difficult to make
> -your check work perfectly in all cases, especially if it issues fix-it hints. The
> -most frequent pitfalls are macros and templates:
> -
> -1. code written in a macro body/template definition may have a different meaning
> - depending on the macro expansion/template instantiation;
> -2. multiple macro expansions/template instantiations may result in the same code
> - being inspected by the check multiple times (possibly, with different
> - meanings, see 1), and the same warning (or a slightly different one) may be
> - issued by the check multiple times; :program:`clang-tidy` will deduplicate
> - _identical_ warnings, but if the warnings are slightly different, all of them
> - will be shown to the user (and used for applying fixes, if any);
> -3. making replacements to a macro body/template definition may be fine for some
> - macro expansions/template instantiations, but easily break some other
> - expansions/instantiations.
> -
> -.. _lit: http://llvm.org/docs/CommandGuide/lit.html
> -.. _FileCheck: http://llvm.org/docs/CommandGuide/FileCheck.html
> -.. _test/clang-tidy/google-readability-casting.cpp: http://reviews.llvm.org/diffusion/L/browse/clang-tools-extra/trunk/test/clang-tidy/google-readability-casting.cpp
> -
> -
> -Running clang-tidy on LLVM
> ---------------------------
> -
> -To test a check it's best to try it out on a larger code base. LLVM and Clang
> -are the natural targets as you already have the source code around. The most
> -convenient way to run :program:`clang-tidy` is with a compile command database;
> -CMake can automatically generate one, for a description of how to enable it see
> -`How To Setup Tooling For LLVM`_. Once ``compile_commands.json`` is in place and
> -a working version of :program:`clang-tidy` is in ``PATH`` the entire code base
> -can be analyzed with ``clang-tidy/tool/run-clang-tidy.py``. The script executes
> -:program:`clang-tidy` with the default set of checks on every translation unit
> -in the compile command database and displays the resulting warnings and errors.
> -The script provides multiple configuration flags.
> -
> -* The default set of checks can be overridden using the ``-checks`` argument,
> - taking the identical format as :program:`clang-tidy` does. For example
> - ``-checks=-*,modernize-use-override`` will run the ``modernize-use-override``
> - check only.
> -
> -* To restrict the files examined you can provide one or more regex arguments
> - that the file names are matched against.
> - ``run-clang-tidy.py clang-tidy/.*Check\.cpp`` will only analyze clang-tidy
> - checks. It may also be necessary to restrict the header files warnings are
> - displayed from using the ``-header-filter`` flag. It has the same behavior
> - as the corresponding :program:`clang-tidy` flag.
> -
> -* To apply suggested fixes ``-fix`` can be passed as an argument. This gathers
> - all changes in a temporary directory and applies them. Passing ``-format``
> - will run clang-format over changed lines.
> -
> -
> -On checks profiling
> --------------------
> -
> -:program:`clang-tidy` can collect per-check profiling info, and output it
> -for each processed source file (translation unit).
> -
> -To enable profiling info collection, use the ``-enable-check-profile`` argument.
> -The timings will be output to ``stderr`` as a table. Example output:
> -
> -.. code-block:: console
> -
> - $ clang-tidy -enable-check-profile -checks=-*,readability-function-size source.cpp
> - ===-------------------------------------------------------------------------===
> - clang-tidy checks profiling
> - ===-------------------------------------------------------------------------===
> - Total Execution Time: 1.0282 seconds (1.0258 wall clock)
> -
> - ---User Time--- --System Time-- --User+System-- ---Wall Time--- --- Name ---
> - 0.9136 (100.0%) 0.1146 (100.0%) 1.0282 (100.0%) 1.0258 (100.0%) readability-function-size
> - 0.9136 (100.0%) 0.1146 (100.0%) 1.0282 (100.0%) 1.0258 (100.0%) Total
> -
> -It can also store that data as JSON files for further processing. Example output:
> -
> -.. code-block:: console
> -
> - $ clang-tidy -enable-check-profile -store-check-profile=. -checks=-*,readability-function-size source.cpp
> - $ # Note that there won't be timings table printed to the console.
> - $ ls /tmp/out/
> - 20180516161318717446360-source.cpp.json
> - $ cat 20180516161318717446360-source.cpp.json
> - {
> - "file": "/path/to/source.cpp",
> - "timestamp": "2018-05-16 16:13:18.717446360",
> - "profile": {
> - "time.clang-tidy.readability-function-size.wall": 1.0421266555786133e+00,
> - "time.clang-tidy.readability-function-size.user": 9.2088400000005421e-01,
> - "time.clang-tidy.readability-function-size.sys": 1.2418899999999974e-01
> - }
> - }
> -
> -There is only one argument that controls profile storage:
> -
> -* ``-store-check-profile=<prefix>``
> -
> - By default reports are printed in tabulated format to stderr. When this option
> - is passed, these per-TU profiles are instead stored as JSON.
> - If the prefix is not an absolute path, it is considered to be relative to the
> - directory from where you have run :program:`clang-tidy`. All ``.`` and ``..``
> - patterns in the path are collapsed, and symlinks are resolved.
> -
> - Example:
> - Let's suppose you have a source file named ``example.cpp``, located in the
> - ``/source`` directory. Only the input filename is used, not the full path
> - to the source file. Additionally, it is prefixed with the current timestamp.
> -
> - * If you specify ``-store-check-profile=/tmp``, then the profile will be saved
> - to ``/tmp/<ISO8601-like timestamp>-example.cpp.json``
> -
> - * If you run :program:`clang-tidy` from within ``/foo`` directory, and specify
> - ``-store-check-profile=.``, then the profile will still be saved to
> - ``/foo/<ISO8601-like timestamp>-example.cpp.json``
>
>
> _______________________________________________
> cfe-commits mailing list
> cfe-commits at lists.llvm.org
> http://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
More information about the cfe-commits
mailing list