| 1 |
================ |
| 2 |
Getting Involved |
| 3 |
================ |
| 4 |
|
| 5 |
:program:`clang-tidy` has several own checks and can run Clang static analyzer |
| 6 |
checks, but its power is in the ability to easily write custom checks. |
| 7 |
|
| 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`. |
| 10 |
|
| 11 |
Checks can plug into the analysis on the preprocessor level using `PPCallbacks`_ |
| 12 |
or on the AST level using `AST Matchers`_. When an error is found, checks can |
| 13 |
report them in a way similar to how Clang diagnostics work. A fix-it hint can be |
| 14 |
attached to a diagnostic message. |
| 15 |
|
| 16 |
The interface provided by :program:`clang-tidy` makes it easy to write useful |
| 17 |
and precise checks in just a few lines of code. If you have an idea for a good |
| 18 |
check, the rest of this document explains how to do this. |
| 19 |
|
| 20 |
There are a few tools particularly useful when developing clang-tidy checks: |
| 21 |
* ``add_new_check.py`` is a script to automate the process of adding a new |
| 22 |
check, it will create the check, update the CMake file and create a test; |
| 23 |
* ``rename_check.py`` does what the script name suggests, renames an existing |
| 24 |
check; |
| 25 |
* :program:`pp-trace` logs method calls on `PPCallbacks` for a source file |
| 26 |
and is invaluable in understanding the preprocessor mechanism; |
| 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``) |
| 30 |
provides a convenient way to dump AST of a C++ program. |
| 31 |
|
| 32 |
If CMake is configured with ``CLANG_TIDY_ENABLE_STATIC_ANALYZER=NO``, |
| 33 |
:program:`clang-tidy` will not be built with support for the |
| 34 |
``clang-analyzer-*`` checks or the ``mpi-*`` checks. |
| 35 |
|
| 36 |
|
| 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 |
| 40 |
|
| 41 |
|
| 42 |
Choosing the Right Place for your Check |
| 43 |
--------------------------------------- |
| 44 |
|
| 45 |
If you have an idea of a check, you should decide whether it should be |
| 46 |
implemented as a: |
| 47 |
|
| 48 |
+ *Clang diagnostic*: if the check is generic enough, targets code patterns that |
| 49 |
most probably are bugs (rather than style or readability issues), can be |
| 50 |
implemented effectively and with extremely low false positive rate, it may |
| 51 |
make a good Clang diagnostic. |
| 52 |
|
| 53 |
+ *Clang static analyzer check*: if the check requires some sort of control flow |
| 54 |
analysis, it should probably be implemented as a static analyzer check. |
| 55 |
|
| 56 |
+ *clang-tidy check* is a good choice for linter-style checks, checks that are |
| 57 |
related to a certain coding style, checks that address code readability, etc. |
| 58 |
|
| 59 |
|
| 60 |
Preparing your Workspace |
| 61 |
------------------------ |
| 62 |
|
| 63 |
If you are new to LLVM development, you should read the `Getting Started with |
| 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 |
| 66 |
CMake. |
| 67 |
|
| 68 |
Once you are done, change to the ``llvm/clang-tools-extra`` directory, and |
| 69 |
let's start! |
| 70 |
|
| 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 |
| 74 |
|
| 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`. |
| 78 |
Because your new check will have associated documentation, you will also want to install |
| 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`` |
| 81 |
target in the CMake configuration. |
| 82 |
|
| 83 |
|
| 84 |
The Directory Structure |
| 85 |
----------------------- |
| 86 |
|
| 87 |
:program:`clang-tidy` source code resides in the |
| 88 |
``llvm/clang-tools-extra`` directory and is structured as follows: |
| 89 |
|
| 90 |
:: |
| 91 |
|
| 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. |
| 97 |
... |
| 98 |
|-- google/ # Google clang-tidy module. |
| 99 |
|-+ |
| 100 |
|-- GoogleTidyModule.cpp |
| 101 |
|-- GoogleTidyModule.h |
| 102 |
... |
| 103 |
|-- llvm/ # LLVM clang-tidy module. |
| 104 |
|-+ |
| 105 |
|-- LLVMTidyModule.cpp |
| 106 |
|-- LLVMTidyModule.h |
| 107 |
... |
| 108 |
|-- objc/ # Objective-C clang-tidy module. |
| 109 |
|-+ |
| 110 |
|-- ObjCTidyModule.cpp |
| 111 |
|-- ObjCTidyModule.h |
| 112 |
... |
| 113 |
|-- tool/ # Sources of the clang-tidy binary. |
| 114 |
... |
| 115 |
test/clang-tidy/ # Integration tests. |
| 116 |
... |
| 117 |
unittests/clang-tidy/ # Unit tests. |
| 118 |
|-- ClangTidyTest.h |
| 119 |
|-- GoogleModuleTest.cpp |
| 120 |
|-- LLVMModuleTest.cpp |
| 121 |
|-- ObjCModuleTest.cpp |
| 122 |
... |
| 123 |
|
| 124 |
|
| 125 |
Writing a clang-tidy Check |
| 126 |
-------------------------- |
| 127 |
|
| 128 |
So you have an idea of a useful check for :program:`clang-tidy`. |
| 129 |
|
| 130 |
First, if you're not familiar with LLVM development, read through the `Getting |
| 131 |
Started with LLVM`_ document for instructions on setting up your workflow and |
| 132 |
the `LLVM Coding Standards`_ document to familiarize yourself with the coding |
| 133 |
style used in the project. For code reviews we mostly use `LLVM Phabricator`_. |
| 134 |
|
| 135 |
.. _Getting Started with LLVM: https://llvm.org/docs/GettingStarted.html |
| 136 |
.. _LLVM Coding Standards: https://llvm.org/docs/CodingStandards.html |
| 137 |
.. _LLVM Phabricator: https://llvm.org/docs/Phabricator.html |
| 138 |
|
| 139 |
Next, you need to decide which module the check belongs to. Modules |
| 140 |
are located in subdirectories of `clang-tidy/ |
| 141 |
<https://github.com/llvm/llvm-project/tree/main/clang-tools-extra/clang-tidy/>`_ |
| 142 |
and contain checks targeting a certain aspect of code quality (performance, |
| 143 |
readability, etc.), certain coding style or standard (Google, LLVM, CERT, etc.) |
| 144 |
or a widely used API (e.g. MPI). Their names are the same as the user-facing |
| 145 |
check group names described :ref:`above <checks-groups-table>`. |
| 146 |
|
| 147 |
After choosing the module and the name for the check, run the |
| 148 |
``clang-tidy/add_new_check.py`` script to create the skeleton of the check and |
| 149 |
plug it to :program:`clang-tidy`. It's the recommended way of adding new checks. |
| 150 |
|
| 151 |
If we want to create a `readability-awesome-function-names`, we would run: |
| 152 |
|
| 153 |
.. code-block:: console |
| 154 |
|
| 155 |
$ clang-tidy/add_new_check.py readability awesome-function-names |
| 156 |
|
| 157 |
|
| 158 |
The ``add_new_check.py`` script will: |
| 159 |
* create the class for your check inside the specified module's directory and |
| 160 |
register it in the module and in the build system; |
| 161 |
* create a lit test file in the ``test/clang-tidy/`` directory; |
| 162 |
* create a documentation file and include it into the |
| 163 |
``docs/clang-tidy/checks/list.rst``. |
| 164 |
|
| 165 |
Let's see in more detail at the check class definition: |
| 166 |
|
| 167 |
.. code-block:: c++ |
| 168 |
|
| 169 |
... |
| 170 |
|
| 171 |
#include "../ClangTidyCheck.h" |
| 172 |
|
| 173 |
namespace clang { |
| 174 |
namespace tidy { |
| 175 |
namespace readability { |
| 176 |
|
| 177 |
... |
| 178 |
class AwesomeFunctionNamesCheck : public ClangTidyCheck { |
| 179 |
public: |
| 180 |
AwesomeFunctionNamesCheck(StringRef Name, ClangTidyContext *Context) |
| 181 |
: ClangTidyCheck(Name, Context) {} |
| 182 |
void registerMatchers(ast_matchers::MatchFinder *Finder) override; |
| 183 |
void check(const ast_matchers::MatchFinder::MatchResult &Result) override; |
| 184 |
}; |
| 185 |
|
| 186 |
} // namespace readability |
| 187 |
} // namespace tidy |
| 188 |
} // namespace clang |
| 189 |
|
| 190 |
... |
| 191 |
|
| 192 |
Constructor of the check receives the ``Name`` and ``Context`` parameters, and |
| 193 |
must forward them to the ``ClangTidyCheck`` constructor. |
| 194 |
|
| 195 |
In our case the check needs to operate on the AST level and it overrides the |
| 196 |
``registerMatchers`` and ``check`` methods. If we wanted to analyze code on the |
| 197 |
preprocessor level, we'd need instead to override the ``registerPPCallbacks`` |
| 198 |
method. |
| 199 |
|
| 200 |
In the ``registerMatchers`` method we create an AST Matcher (see `AST Matchers`_ |
| 201 |
for more information) that will find the pattern in the AST that we want to |
| 202 |
inspect. The results of the matching are passed to the ``check`` method, which |
| 203 |
can further inspect them and report diagnostics. |
| 204 |
|
| 205 |
.. code-block:: c++ |
| 206 |
|
| 207 |
using namespace ast_matchers; |
| 208 |
|
| 209 |
void AwesomeFunctionNamesCheck::registerMatchers(MatchFinder *Finder) { |
| 210 |
Finder->addMatcher(functionDecl().bind("x"), this); |
| 211 |
} |
| 212 |
|
| 213 |
void AwesomeFunctionNamesCheck::check(const MatchFinder::MatchResult &Result) { |
| 214 |
const auto *MatchedDecl = Result.Nodes.getNodeAs<FunctionDecl>("x"); |
| 215 |
if (!MatchedDecl->getIdentifier() || MatchedDecl->getName().startswith("awesome_")) |
| 216 |
return; |
| 217 |
diag(MatchedDecl->getLocation(), "function %0 is insufficiently awesome") |
| 218 |
<< MatchedDecl |
| 219 |
<< FixItHint::CreateInsertion(MatchedDecl->getLocation(), "awesome_"); |
| 220 |
} |
| 221 |
|
| 222 |
(If you want to see an example of a useful check, look at |
| 223 |
`clang-tidy/google/ExplicitConstructorCheck.h |
| 224 |
<https://github.com/llvm/llvm-project/blob/main/clang-tools-extra/clang-tidy/google/ExplicitConstructorCheck.h>`_ |
| 225 |
and `clang-tidy/google/ExplicitConstructorCheck.cpp |
| 226 |
<https://reviews.llvm.org/diffusion/L/browse/clang-tools-extra/trunk/clang-tidy/google/ExplicitConstructorCheck.cpp>`_). |
| 227 |
|
| 228 |
If you need to interact with macros or preprocessor directives, you will want to |
| 229 |
override the method ``registerPPCallbacks``. The ``add_new_check.py`` script |
| 230 |
does not generate an override for this method in the starting point for your |
| 231 |
new check. |
| 232 |
|
| 233 |
If your check applies only under a specific set of language options, be sure |
| 234 |
to override the method ``isLanguageVersionSupported`` to reflect that. |
| 235 |
|
| 236 |
Check development tips |
| 237 |
---------------------- |
| 238 |
|
| 239 |
Writing your first check can be a daunting task, particularly if you are unfamiliar |
| 240 |
with the LLVM and Clang code bases. Here are some suggestions for orienting yourself |
| 241 |
in the codebase and working on your check incrementally. |
| 242 |
|
| 243 |
Guide to useful documentation |
| 244 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 245 |
|
| 246 |
Many of the support classes created for LLVM are used by Clang, such as `StringRef |
| 247 |
<https://llvm.org/docs/ProgrammersManual.html#the-stringref-class>`_ |
| 248 |
and `SmallVector <https://llvm.org/docs/ProgrammersManual.html#llvm-adt-smallvector-h>`_. |
| 249 |
These and other commonly used classes are described in the `Important and useful LLVM APIs |
| 250 |
<https://llvm.org/docs/ProgrammersManual.html#important-and-useful-llvm-apis>`_ and |
| 251 |
`Picking the Right Data Structure for the Task |
| 252 |
<https://llvm.org/docs/ProgrammersManual.html#picking-the-right-data-structure-for-a-task>`_ |
| 253 |
sections of the `LLVM Programmer's Manual |
| 254 |
<https://llvm.org/docs/ProgrammersManual.html>`_. You don't need to memorize all the |
| 255 |
details of these classes; the generated `doxygen documentation <https://llvm.org/doxygen/>`_ |
| 256 |
has everything if you need it. In the header `LLVM/ADT/STLExtras.h |
| 257 |
<https://llvm.org/doxygen/STLExtras_8h.html>`_ you'll find useful versions of the STL |
| 258 |
algorithms that operate on LLVM containers, such as `llvm::all_of |
| 259 |
<https://llvm.org/doxygen/STLExtras_8h.html#func-members>`_. |
| 260 |
|
| 261 |
Clang is implemented on top of LLVM and introduces its own set of classes that you |
| 262 |
will interact with while writing your check. When a check issues diagnostics and |
| 263 |
fix-its, these are associated with locations in the source code. Source code locations, |
| 264 |
source files, ranges of source locations and the `SourceManager |
| 265 |
<https://clang.llvm.org/doxygen/classclang_1_1SourceManager.html>`_ class provide |
| 266 |
the mechanisms for describing such locations. These and |
| 267 |
other topics are described in the `"Clang" CFE Internals Manual |
| 268 |
<https://clang.llvm.org/docs/InternalsManual.html>`_. Whereas the doxygen generated |
| 269 |
documentation serves as a reference to the internals of Clang, this document serves |
| 270 |
as a guide to other developers. Topics in that manual of interest to a check developer |
| 271 |
are: |
| 272 |
|
| 273 |
- `The Clang "Basic" Library |
| 274 |
<https://clang.llvm.org/docs/InternalsManual.html#the-clang-basic-library>`_ for |
| 275 |
information about diagnostics, fix-it hints and source locations. |
| 276 |
- `The Lexer and Preprocessor Library |
| 277 |
<https://clang.llvm.org/docs/InternalsManual.html#the-lexer-and-preprocessor-library>`_ |
| 278 |
for information about tokens, lexing (transforming characters into tokens) and the |
| 279 |
preprocessor. |
| 280 |
- `The AST Library |
| 281 |
<https://clang.llvm.org/docs/InternalsManual.html#the-lexer-and-preprocessor-library>`_ |
| 282 |
for information about how C++ source statements are represented as an abstract syntax |
| 283 |
tree (AST). |
| 284 |
|
| 285 |
Most checks will interact with C++ source code via the AST. Some checks will interact |
| 286 |
with the preprocessor. The input source file is lexed and preprocessed and then parsed |
| 287 |
into the AST. Once the AST is fully constructed, the check is run by applying the check's |
| 288 |
registered AST matchers against the AST and invoking the check with the set of matched |
| 289 |
nodes from the AST. Monitoring the actions of the preprocessor is detached from the |
| 290 |
AST construction, but a check can collect information during preprocessing for later |
| 291 |
use by the check when nodes are matched by the AST. |
| 292 |
|
| 293 |
Every syntactic (and sometimes semantic) element of the C++ source code is represented by |
| 294 |
different classes in the AST. You select the portions of the AST you're interested in |
| 295 |
by composing AST matcher functions. You will want to study carefully the `AST Matcher |
| 296 |
Reference <https://clang.llvm.org/docs/LibASTMatchersReference.html>`_ to understand |
| 297 |
the relationship between the different matcher functions. |
| 298 |
|
| 299 |
Using the Transformer library |
| 300 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 301 |
|
| 302 |
The Transformer library allows you to write a check that transforms source code by |
| 303 |
expressing the transformation as a ``RewriteRule``. The Transformer library provides |
| 304 |
functions for composing edits to source code to create rewrite rules. Unless you need |
| 305 |
to perform low-level source location manipulation, you may want to consider writing your |
| 306 |
check with the Transformer library. The `Clang Transformer Tutorial |
| 307 |
<https://clang.llvm.org/docs/ClangTransformerTutorial.html>`_ describes the Transformer |
| 308 |
library in detail. |
| 309 |
|
| 310 |
To use the Transformer library, make the following changes to the code generated by |
| 311 |
the ``add_new_check.py`` script: |
| 312 |
|
| 313 |
- Include ``../utils/TransformerClangTidyCheck.h`` instead of ``../ClangTidyCheck.h`` |
| 314 |
- Change the base class of your check from ``ClangTidyCheck`` to ``TransformerClangTidyCheck`` |
| 315 |
- Delete the override of the ``registerMatchers`` and ``check`` methods in your check class. |
| 316 |
- Write a function that creates the ``RewriteRule`` for your check. |
| 317 |
- Call the function in your check's constructor to pass the rewrite rule to |
| 318 |
``TransformerClangTidyCheck``'s constructor. |
| 319 |
|
| 320 |
Developing your check incrementally |
| 321 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 322 |
|
| 323 |
The best way to develop your check is to start with the simple test cases and increase |
| 324 |
complexity incrementally. The test file created by the ``add_new_check.py`` script is |
| 325 |
a starting point for your test cases. A rough outline of the process looks like this: |
| 326 |
|
| 327 |
- Write a test case for your check. |
| 328 |
- Prototype matchers on the test file using :program:`clang-query`. |
| 329 |
- Capture the working matchers in the ``registerMatchers`` method. |
| 330 |
- Issue the necessary diagnostics and fix-its in the ``check`` method. |
| 331 |
- Add the necessary ``CHECK-MESSAGES`` and ``CHECK-FIXES`` annotations to your |
| 332 |
test case to validate the diagnostics and fix-its. |
| 333 |
- Build the target ``check-clang-tool`` to confirm the test passes. |
| 334 |
- Repeat the process until all aspects of your check are covered by tests. |
| 335 |
|
| 336 |
The quickest way to prototype your matcher is to use :program:`clang-query` to |
| 337 |
interactively build up your matcher. For complicated matchers, build up a matching |
| 338 |
expression incrementally and use :program:`clang-query`'s ``let`` command to save named |
| 339 |
matching expressions to simplify your matcher. Just like breaking up a huge function |
| 340 |
into smaller chunks with intention-revealing names can help you understand a complex |
| 341 |
algorithm, breaking up a matcher into smaller matchers with intention-revealing names |
| 342 |
can help you understand a complicated matcher. Once you have a working matcher, the |
| 343 |
C++ API will be virtually identical to your interactively constructed matcher. You can |
| 344 |
use local variables to preserve your intention-revealing names that you applied to |
| 345 |
nested matchers. |
| 346 |
|
| 347 |
Creating private matchers |
| 348 |
^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 349 |
|
| 350 |
Sometimes you want to match a specific aspect of the AST that isn't provided by the |
| 351 |
existing AST matchers. You can create your own private matcher using the same |
| 352 |
infrastructure as the public matchers. A private matcher can simplify the processing |
| 353 |
in your ``check`` method by eliminating complex hand-crafted AST traversal of the |
| 354 |
matched nodes. Using the private matcher allows you to select the desired portions |
| 355 |
of the AST directly in the matcher and refer to it by a bound name in the ``check`` |
| 356 |
method. |
| 357 |
|
| 358 |
Unit testing helper code |
| 359 |
^^^^^^^^^^^^^^^^^^^^^^^^ |
| 360 |
|
| 361 |
Private custom matchers are a good example of auxiliary support code for your check |
| 362 |
that can be tested with a unit test. It will be easier to test your matchers or |
| 363 |
other support classes by writing a unit test than by writing a ``FileCheck`` integration |
| 364 |
test. The ``ASTMatchersTests`` target contains unit tests for the public AST matcher |
| 365 |
classes and is a good source of testing idioms for matchers. |
| 366 |
|
| 367 |
You can build the Clang-tidy unit tests by building the ``ClangTidyTests`` target. |
| 368 |
Test targets in LLVM and Clang are excluded from the "build all" style action of |
| 369 |
IDE-based CMake generators, so you need to explicitly build the target for the unit |
| 370 |
tests to be built. |
| 371 |
|
| 372 |
Making your check robust |
| 373 |
^^^^^^^^^^^^^^^^^^^^^^^^ |
| 374 |
|
| 375 |
Once you've covered your check with the basic "happy path" scenarios, you'll want to |
| 376 |
torture your check with as many edge cases as you can cover in order to ensure your |
| 377 |
check is robust. Running your check on a large code base, such as Clang/LLVM, is a |
| 378 |
good way to catch things you forgot to account for in your matchers. However, the |
| 379 |
LLVM code base may be insufficient for testing purposes as it was developed against a |
| 380 |
particular set of coding styles and quality measures. The larger the corpus of code |
| 381 |
the check is tested against, the higher confidence the community will have in the |
| 382 |
check's efficacy and false positive rate. |
| 383 |
|
| 384 |
Some suggestions to ensure your check is robust: |
| 385 |
|
| 386 |
- Create header files that contain code matched by your check. |
| 387 |
- Validate that fix-its are properly applied to test header files with |
| 388 |
:program:`clang-tidy`. You will need to perform this test manually until |
| 389 |
automated support for checking messages and fix-its is added to the |
| 390 |
``check_clang_tidy.py`` script. |
| 391 |
- Define macros that contain code matched by your check. |
| 392 |
- Define template classes that contain code matched by your check. |
| 393 |
- Define template specializations that contain code matched by your check. |
| 394 |
- Test your check under both Windows and Linux environments. |
| 395 |
- Watch out for high false positive rates. Ideally, a check would have no false |
| 396 |
positives, but given that matching against an AST is not control- or data flow- |
| 397 |
sensitive, a number of false positives are expected. The higher the false |
| 398 |
positive rate, the less likely the check will be adopted in practice. |
| 399 |
Mechanisms should be put in place to help the user manage false positives. |
| 400 |
- There are two primary mechanisms for managing false positives: supporting a |
| 401 |
code pattern which allows the programmer to silence the diagnostic in an ad |
| 402 |
hoc manner and check configuration options to control the behavior of the check. |
| 403 |
- Consider supporting a code pattern to allow the programmer to silence the |
| 404 |
diagnostic whenever such a code pattern can clearly express the programmer's |
| 405 |
intent. For example, allowing an explicit cast to ``void`` to silence an |
| 406 |
unused variable diagnostic. |
| 407 |
- Consider adding check configuration options to allow the user to opt into |
| 408 |
more aggressive checking behavior without burdening users for the common |
| 409 |
high-confidence cases. |
| 410 |
|
| 411 |
Documenting your check |
| 412 |
^^^^^^^^^^^^^^^^^^^^^^ |
| 413 |
|
| 414 |
The ``add_new_check.py`` script creates entries in the |
| 415 |
`release notes <https://clang.llvm.org/extra/ReleaseNotes.html>`_, the list of |
| 416 |
checks and a new file for the check documentation itself. It is recommended that you |
| 417 |
have a concise summation of what your check does in a single sentence that is repeated |
| 418 |
in the release notes, as the first sentence in the doxygen comments in the header file |
| 419 |
for your check class and as the first sentence of the check documentation. Avoid the |
| 420 |
phrase "this check" in your check summation and check documentation. |
| 421 |
|
| 422 |
If your check relates to a published coding guideline (C++ Core Guidelines, MISRA, etc.) |
| 423 |
or style guide, provide links to the relevant guideline or style guide sections in your |
| 424 |
check documentation. |
| 425 |
|
| 426 |
Provide enough examples of the diagnostics and fix-its provided by the check so that a |
| 427 |
user can easily understand what will happen to their code when the check is run. |
| 428 |
If there are exceptions or limitations to your check, document them thoroughly. This |
| 429 |
will help users understand the scope of the diagnostics and fix-its provided by the check. |
| 430 |
|
| 431 |
Building the target ``docs-clang-tools-html`` will run the Sphinx documentation generator |
| 432 |
and create documentation HTML files in the tools/clang/tools/extra/docs/html directory in |
| 433 |
your build tree. Make sure that your check is correctly shown in the release notes and the |
| 434 |
list of checks. Make sure that the formatting and structure of your check's documentation |
| 435 |
looks correct. |
| 436 |
|
| 437 |
|
| 438 |
Registering your Check |
| 439 |
---------------------- |
| 440 |
|
| 441 |
(The ``add_new_check.py`` script takes care of registering the check in an existing |
| 442 |
module. If you want to create a new module or know the details, read on.) |
| 443 |
|
| 444 |
The check should be registered in the corresponding module with a distinct name: |
| 445 |
|
| 446 |
.. code-block:: c++ |
| 447 |
|
| 448 |
class MyModule : public ClangTidyModule { |
| 449 |
public: |
| 450 |
void addCheckFactories(ClangTidyCheckFactories &CheckFactories) override { |
| 451 |
CheckFactories.registerCheck<ExplicitConstructorCheck>( |
| 452 |
"my-explicit-constructor"); |
| 453 |
} |
| 454 |
}; |
| 455 |
|
| 456 |
Now we need to register the module in the ``ClangTidyModuleRegistry`` using a |
| 457 |
statically initialized variable: |
| 458 |
|
| 459 |
.. code-block:: c++ |
| 460 |
|
| 461 |
static ClangTidyModuleRegistry::Add<MyModule> X("my-module", |
| 462 |
"Adds my lint checks."); |
| 463 |
|
| 464 |
|
| 465 |
When using LLVM build system, we need to use the following hack to ensure the |
| 466 |
module is linked into the :program:`clang-tidy` binary: |
| 467 |
|
| 468 |
Add this near the ``ClangTidyModuleRegistry::Add<MyModule>`` variable: |
| 469 |
|
| 470 |
.. code-block:: c++ |
| 471 |
|
| 472 |
// This anchor is used to force the linker to link in the generated object file |
| 473 |
// and thus register the MyModule. |
| 474 |
volatile int MyModuleAnchorSource = 0; |
| 475 |
|
| 476 |
And this to the main translation unit of the :program:`clang-tidy` binary (or |
| 477 |
the binary you link the ``clang-tidy`` library in) |
| 478 |
``clang-tidy/tool/ClangTidyMain.cpp``: |
| 479 |
|
| 480 |
.. code-block:: c++ |
| 481 |
|
| 482 |
// This anchor is used to force the linker to link the MyModule. |
| 483 |
extern volatile int MyModuleAnchorSource; |
| 484 |
static int MyModuleAnchorDestination = MyModuleAnchorSource; |
| 485 |
|
| 486 |
|
| 487 |
Configuring Checks |
| 488 |
------------------ |
| 489 |
|
| 490 |
If a check needs configuration options, it can access check-specific options |
| 491 |
using the ``Options.get<Type>("SomeOption", DefaultValue)`` call in the check |
| 492 |
constructor. In this case the check should also override the |
| 493 |
``ClangTidyCheck::storeOptions`` method to make the options provided by the |
| 494 |
check discoverable. This method lets :program:`clang-tidy` know which options |
| 495 |
the check implements and what the current values are (e.g. for the |
| 496 |
``-dump-config`` command line option). |
| 497 |
|
| 498 |
.. code-block:: c++ |
| 499 |
|
| 500 |
class MyCheck : public ClangTidyCheck { |
| 501 |
const unsigned SomeOption1; |
| 502 |
const std::string SomeOption2; |
| 503 |
|
| 504 |
public: |
| 505 |
MyCheck(StringRef Name, ClangTidyContext *Context) |
| 506 |
: ClangTidyCheck(Name, Context), |
| 507 |
SomeOption(Options.get("SomeOption1", -1U)), |
| 508 |
SomeOption(Options.get("SomeOption2", "some default")) {} |
| 509 |
|
| 510 |
void storeOptions(ClangTidyOptions::OptionMap &Opts) override { |
| 511 |
Options.store(Opts, "SomeOption1", SomeOption1); |
| 512 |
Options.store(Opts, "SomeOption2", SomeOption2); |
| 513 |
} |
| 514 |
... |
| 515 |
|
| 516 |
Assuming the check is registered with the name "my-check", the option can then |
| 517 |
be set in a ``.clang-tidy`` file in the following way: |
| 518 |
|
| 519 |
.. code-block:: yaml |
| 520 |
|
| 521 |
CheckOptions: |
| 522 |
my-check.SomeOption1: 123 |
| 523 |
my-check.SomeOption2: 'some other value' |
| 524 |
|
| 525 |
If you need to specify check options on a command line, you can use the inline |
| 526 |
YAML format: |
| 527 |
|
| 528 |
.. code-block:: console |
| 529 |
|
| 530 |
$ clang-tidy -config="{CheckOptions: {a: b, x: y}}" ... |
| 531 |
|
| 532 |
|
| 533 |
Testing Checks |
| 534 |
-------------- |
| 535 |
|
| 536 |
To run tests for :program:`clang-tidy`, build the ``check-clang-tools`` target. |
| 537 |
For instance, if you configured your CMake build with the ninja project generator, |
| 538 |
use the command: |
| 539 |
|
| 540 |
.. code-block:: console |
| 541 |
|
| 542 |
$ ninja check-clang-tools |
| 543 |
|
| 544 |
:program:`clang-tidy` checks can be tested using either unit tests or |
| 545 |
`lit`_ tests. Unit tests may be more convenient to test complex replacements |
| 546 |
with strict checks. `Lit`_ tests allow using partial text matching and regular |
| 547 |
expressions which makes them more suitable for writing compact tests for |
| 548 |
diagnostic messages. |
| 549 |
|
| 550 |
The ``check_clang_tidy.py`` script provides an easy way to test both |
| 551 |
diagnostic messages and fix-its. It filters out ``CHECK`` lines from the test |
| 552 |
file, runs :program:`clang-tidy` and verifies messages and fixes with two |
| 553 |
separate `FileCheck`_ invocations: once with FileCheck's directive |
| 554 |
prefix set to ``CHECK-MESSAGES``, validating the diagnostic messages, |
| 555 |
and once with the directive prefix set to ``CHECK-FIXES``, running |
| 556 |
against the fixed code (i.e., the code after generated fix-its are |
| 557 |
applied). In particular, ``CHECK-FIXES:`` can be used to check |
| 558 |
that code was not modified by fix-its, by checking that it is present |
| 559 |
unchanged in the fixed code. The full set of `FileCheck`_ directives |
| 560 |
is available (e.g., ``CHECK-MESSAGES-SAME:``, ``CHECK-MESSAGES-NOT:``), though |
| 561 |
typically the basic ``CHECK`` forms (``CHECK-MESSAGES`` and ``CHECK-FIXES``) |
| 562 |
are sufficient for clang-tidy tests. Note that the `FileCheck`_ |
| 563 |
documentation mostly assumes the default prefix (``CHECK``), and hence |
| 564 |
describes the directive as ``CHECK:``, ``CHECK-SAME:``, ``CHECK-NOT:``, etc. |
| 565 |
Replace ``CHECK`` by either ``CHECK-FIXES`` or ``CHECK-MESSAGES`` for |
| 566 |
clang-tidy tests. |
| 567 |
|
| 568 |
An additional check enabled by ``check_clang_tidy.py`` ensures that |
| 569 |
if `CHECK-MESSAGES:` is used in a file then every warning or error |
| 570 |
must have an associated CHECK in that file. Or, you can use ``CHECK-NOTES:`` |
| 571 |
instead, if you want to **also** ensure that all the notes are checked. |
| 572 |
|
| 573 |
To use the ``check_clang_tidy.py`` script, put a .cpp file with the |
| 574 |
appropriate ``RUN`` line in the ``test/clang-tidy`` directory. Use |
| 575 |
``CHECK-MESSAGES:`` and ``CHECK-FIXES:`` lines to write checks against |
| 576 |
diagnostic messages and fixed code. |
| 577 |
|
| 578 |
It's advised to make the checks as specific as possible to avoid checks matching |
| 579 |
to incorrect parts of the input. Use ``[[@LINE+X]]``/``[[@LINE-X]]`` |
| 580 |
substitutions and distinct function and variable names in the test code. |
| 581 |
|
| 582 |
Here's an example of a test using the ``check_clang_tidy.py`` script (the full |
| 583 |
source code is at `test/clang-tidy/checkers/google/readability-casting.cpp`_): |
| 584 |
|
| 585 |
.. code-block:: c++ |
| 586 |
|
| 587 |
// RUN: %check_clang_tidy %s google-readability-casting %t |
| 588 |
|
| 589 |
void f(int a) { |
| 590 |
int b = (int)a; |
| 591 |
// CHECK-MESSAGES: :[[@LINE-1]]:11: warning: redundant cast to the same type [google-readability-casting] |
| 592 |
// CHECK-FIXES: int b = a; |
| 593 |
} |
| 594 |
|
| 595 |
To check more than one scenario in the same test file use |
| 596 |
``-check-suffix=SUFFIX-NAME`` on ``check_clang_tidy.py`` command line or |
| 597 |
``-check-suffixes=SUFFIX-NAME-1,SUFFIX-NAME-2,...``. |
| 598 |
With ``-check-suffix[es]=SUFFIX-NAME`` you need to replace your ``CHECK-*`` |
| 599 |
directives with ``CHECK-MESSAGES-SUFFIX-NAME`` and ``CHECK-FIXES-SUFFIX-NAME``. |
| 600 |
|
| 601 |
Here's an example: |
| 602 |
|
| 603 |
.. code-block:: c++ |
| 604 |
|
| 605 |
// RUN: %check_clang_tidy -check-suffix=USING-A %s misc-unused-using-decls %t -- -- -DUSING_A |
| 606 |
// RUN: %check_clang_tidy -check-suffix=USING-B %s misc-unused-using-decls %t -- -- -DUSING_B |
| 607 |
// RUN: %check_clang_tidy %s misc-unused-using-decls %t |
| 608 |
... |
| 609 |
// CHECK-MESSAGES-USING-A: :[[@LINE-8]]:10: warning: using decl 'A' {{.*}} |
| 610 |
// CHECK-MESSAGES-USING-B: :[[@LINE-7]]:10: warning: using decl 'B' {{.*}} |
| 611 |
// CHECK-MESSAGES: :[[@LINE-6]]:10: warning: using decl 'C' {{.*}} |
| 612 |
// CHECK-FIXES-USING-A-NOT: using a::A;$ |
| 613 |
// CHECK-FIXES-USING-B-NOT: using a::B;$ |
| 614 |
// CHECK-FIXES-NOT: using a::C;$ |
| 615 |
|
| 616 |
There are many dark corners in the C++ language, and it may be difficult to make |
| 617 |
your check work perfectly in all cases, especially if it issues fix-it hints. The |
| 618 |
most frequent pitfalls are macros and templates: |
| 619 |
|
| 620 |
1. code written in a macro body/template definition may have a different meaning |
| 621 |
depending on the macro expansion/template instantiation; |
| 622 |
2. multiple macro expansions/template instantiations may result in the same code |
| 623 |
being inspected by the check multiple times (possibly, with different |
| 624 |
meanings, see 1), and the same warning (or a slightly different one) may be |
| 625 |
issued by the check multiple times; :program:`clang-tidy` will deduplicate |
| 626 |
_identical_ warnings, but if the warnings are slightly different, all of them |
| 627 |
will be shown to the user (and used for applying fixes, if any); |
| 628 |
3. making replacements to a macro body/template definition may be fine for some |
| 629 |
macro expansions/template instantiations, but easily break some other |
| 630 |
expansions/instantiations. |
| 631 |
|
| 632 |
If you need multiple files to exercise all the aspects of your check, it is |
| 633 |
recommended you place them in a subdirectory named for the check under the ``Inputs`` |
| 634 |
directory for the module containing your check. This keeps the test directory from |
| 635 |
getting cluttered. |
| 636 |
|
| 637 |
If you need to validate how your check interacts with system header files, a set |
| 638 |
of simulated system header files is located in the ``checkers/Inputs/Headers`` |
| 639 |
directory. The path to this directory is available in a lit test with the variable |
| 640 |
``%clang_tidy_headers``. |
| 641 |
|
| 642 |
.. _lit: https://llvm.org/docs/CommandGuide/lit.html |
| 643 |
.. _FileCheck: https://llvm.org/docs/CommandGuide/FileCheck.html |
| 644 |
.. _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 |
| 645 |
|
| 646 |
Out-of-tree check plugins |
| 647 |
------------------------- |
| 648 |
|
| 649 |
Developing an out-of-tree check as a plugin largely follows the steps |
| 650 |
outlined above. The plugin is a shared library whose code lives outside |
| 651 |
the clang-tidy build system. Build and link this shared library against |
| 652 |
LLVM as done for other kinds of Clang plugins. |
| 653 |
|
| 654 |
The plugin can be loaded by passing `-load` to `clang-tidy` in addition to the |
| 655 |
names of the checks to enable. |
| 656 |
|
| 657 |
.. code-block:: console |
| 658 |
|
| 659 |
$ clang-tidy --checks=-*,my-explicit-constructor -list-checks -load myplugin.so |
| 660 |
|
| 661 |
There is no expectations regarding ABI and API stability, so the plugin must be |
| 662 |
compiled against the version of clang-tidy that will be loading the plugin. |
| 663 |
|
| 664 |
The plugins can use threads, TLS, or any other facilities available to in-tree |
| 665 |
code which is accessible from the external headers. |
| 666 |
|
| 667 |
Running clang-tidy on LLVM |
| 668 |
-------------------------- |
| 669 |
|
| 670 |
To test a check it's best to try it out on a larger code base. LLVM and Clang |
| 671 |
are the natural targets as you already have the source code around. The most |
| 672 |
convenient way to run :program:`clang-tidy` is with a compile command database; |
| 673 |
CMake can automatically generate one, for a description of how to enable it see |
| 674 |
`How To Setup Clang Tooling For LLVM`_. Once ``compile_commands.json`` is in |
| 675 |
place and a working version of :program:`clang-tidy` is in ``PATH`` the entire |
| 676 |
code base can be analyzed with ``clang-tidy/tool/run-clang-tidy.py``. The script |
| 677 |
executes :program:`clang-tidy` with the default set of checks on every |
| 678 |
translation unit in the compile command database and displays the resulting |
| 679 |
warnings and errors. The script provides multiple configuration flags. |
| 680 |
|
| 681 |
.. _How To Setup Clang Tooling For LLVM: https://clang.llvm.org/docs/HowToSetupToolingForLLVM.html |
| 682 |
|
| 683 |
|
| 684 |
* The default set of checks can be overridden using the ``-checks`` argument, |
| 685 |
taking the identical format as :program:`clang-tidy` does. For example |
| 686 |
``-checks=-*,modernize-use-override`` will run the ``modernize-use-override`` |
| 687 |
check only. |
| 688 |
|
| 689 |
* To restrict the files examined you can provide one or more regex arguments |
| 690 |
that the file names are matched against. |
| 691 |
``run-clang-tidy.py clang-tidy/.*Check\.cpp`` will only analyze clang-tidy |
| 692 |
checks. It may also be necessary to restrict the header files that warnings |
| 693 |
are displayed from using the ``-header-filter`` flag. It has the same behavior |
| 694 |
as the corresponding :program:`clang-tidy` flag. |
| 695 |
|
| 696 |
* To apply suggested fixes ``-fix`` can be passed as an argument. This gathers |
| 697 |
all changes in a temporary directory and applies them. Passing ``-format`` |
| 698 |
will run clang-format over changed lines. |
| 699 |
|
| 700 |
|
| 701 |
On checks profiling |
| 702 |
------------------- |
| 703 |
|
| 704 |
:program:`clang-tidy` can collect per-check profiling info, and output it |
| 705 |
for each processed source file (translation unit). |
| 706 |
|
| 707 |
To enable profiling info collection, use the ``-enable-check-profile`` argument. |
| 708 |
The timings will be output to ``stderr`` as a table. Example output: |
| 709 |
|
| 710 |
.. code-block:: console |
| 711 |
|
| 712 |
$ clang-tidy -enable-check-profile -checks=-*,readability-function-size source.cpp |
| 713 |
===-------------------------------------------------------------------------=== |
| 714 |
clang-tidy checks profiling |
| 715 |
===-------------------------------------------------------------------------=== |
| 716 |
Total Execution Time: 1.0282 seconds (1.0258 wall clock) |
| 717 |
|
| 718 |
---User Time--- --System Time-- --User+System-- ---Wall Time--- --- Name --- |
| 719 |
0.9136 (100.0%) 0.1146 (100.0%) 1.0282 (100.0%) 1.0258 (100.0%) readability-function-size |
| 720 |
0.9136 (100.0%) 0.1146 (100.0%) 1.0282 (100.0%) 1.0258 (100.0%) Total |
| 721 |
|
| 722 |
It can also store that data as JSON files for further processing. Example output: |
| 723 |
|
| 724 |
.. code-block:: console |
| 725 |
|
| 726 |
$ clang-tidy -enable-check-profile -store-check-profile=. -checks=-*,readability-function-size source.cpp |
| 727 |
$ # Note that there won't be timings table printed to the console. |
| 728 |
$ ls /tmp/out/ |
| 729 |
20180516161318717446360-source.cpp.json |
| 730 |
$ cat 20180516161318717446360-source.cpp.json |
| 731 |
{ |
| 732 |
"file": "/path/to/source.cpp", |
| 733 |
"timestamp": "2018-05-16 16:13:18.717446360", |
| 734 |
"profile": { |
| 735 |
"time.clang-tidy.readability-function-size.wall": 1.0421266555786133e+00, |
| 736 |
"time.clang-tidy.readability-function-size.user": 9.2088400000005421e-01, |
| 737 |
"time.clang-tidy.readability-function-size.sys": 1.2418899999999974e-01 |
| 738 |
} |
| 739 |
} |
| 740 |
|
| 741 |
There is only one argument that controls profile storage: |
| 742 |
|
| 743 |
* ``-store-check-profile=<prefix>`` |
| 744 |
|
| 745 |
By default reports are printed in tabulated format to stderr. When this option |
| 746 |
is passed, these per-TU profiles are instead stored as JSON. |
| 747 |
If the prefix is not an absolute path, it is considered to be relative to the |
| 748 |
directory from where you have run :program:`clang-tidy`. All ``.`` and ``..`` |
| 749 |
patterns in the path are collapsed, and symlinks are resolved. |
| 750 |
|
| 751 |
Example: |
| 752 |
Let's suppose you have a source file named ``example.cpp``, located in the |
| 753 |
``/source`` directory. Only the input filename is used, not the full path |
| 754 |
to the source file. Additionally, it is prefixed with the current timestamp. |
| 755 |
|
| 756 |
* If you specify ``-store-check-profile=/tmp``, then the profile will be saved |
| 757 |
to ``/tmp/<ISO8601-like timestamp>-example.cpp.json`` |
| 758 |
|
| 759 |
* If you run :program:`clang-tidy` from within ``/foo`` directory, and specify |
| 760 |
``-store-check-profile=.``, then the profile will still be saved to |
| 761 |
``/foo/<ISO8601-like timestamp>-example.cpp.json`` |