83 lines · plain
1====================================2Query Based Custom Clang-Tidy Checks3====================================4 5Introduction6============7 8This page provides examples of how to add query based custom checks for9:program:`clang-tidy`.10 11Custom checks are based on :program:`clang-query` syntax. Every custom checks12will be registered in `custom` module to avoid name conflict. They can be13enabled or disabled by the checks option like the built-in checks.14 15Custom checks support inheritance from parent configurations like other16configuration items.17 18Goals: easy to write, cross platform, multiple versions supported toolkit for19custom clang-tidy rules.20Non-Goals: complex checks, performance, fix-its, etc.21 22Configuration23=============24 25`CustomChecks` is a list of custom checks. Each check must contain26 - Name: check name can be used in `-checks` option.27 - Query: `clang-query` string28 - Diagnostic: list of diagnostics to be reported.29 - BindName: name of the node to be bound in `Query`.30 - Message: message to be reported.31 - Level: severity of the diagnostic, the possible values are `Note`, `Warning`.32 33`CustomChecks` can be configured by `Checks` option in the configuration file.34 35Example36=======37 38.. code-block:: yaml39 40 Checks: -*,custom-call-main-function41 CustomChecks:42 - Name: call-main-function43 Query: |44 match callExpr(45 callee(46 functionDecl(isMain()).bind("fn")47 )48 ).bind("callee")49 Diagnostic:50 - BindName: fn51 Message: main function.52 Level: Note53 - BindName: callee54 Message: call to main function.55 Level: Warning56 57.. code-block:: c++58 59 int main(); // note: main function.60 61 void bar() {62 main(); // warning: call to main function. [custom-call-main-function]63 }64 65Matters Need Attention66======================67 68This feature needs to be explicitly enabled by `--experimental-custom-checks`69because it is currently in the experimental stage. Welcome to submit any70suggestions in the `link <https://discourse.llvm.org/t/support-query-based-clang-tidy-external-check/85331>`_.71 72During the experimental stage, the required configuration structure of this73feature may be changed in the future. Future changes will be as74forward-compatible as possible, but this is not a guarantee.75 76In subsequent versions, including non-experimental stage, the query statements77will change at any time. The essence of :program:`clang-query` is to parse the78query string and dynamically generate the corresponding AST matcher.79Therefore, its functionality is entirely dependent on the functions provided by80the AST matcher library.81The ast matcher will change along with the changes in the clang AST.82Please refer to `ast matcher reference <https://clang.llvm.org/docs/LibASTMatchersReference.html>`_.83