Query Based Custom Clang-Tidy Checks — Extra Clang Tools 22.0.0git documentation (original) (raw)

Introduction¶

This page provides examples of how to add query based custom checks forclang-tidy.

Custom checks are based on clang-query syntax. Every custom checks will be registered in custom module to avoid name conflict. They can be enabled or disabled by the checks option like the built-in checks.

Custom checks support inheritance from parent configurations like other configuration items.

Goals: easy to write, cross platform, multiple versions supported toolkit for custom clang-tidy rules. Non-Goals: complex checks, performance, fix-its, etc.

Configuration¶

CustomChecks is a list of custom checks. Each check must contain

• Name: check name can be used in -checks option.
• Query: clang-query string
• Diagnostic: list of diagnostics to be reported. - BindName: name of the node to be bound in Query. - Message: message to be reported. - Level: severity of the diagnostic, the possible values are Note, Warning.

CustomChecks can be configured by Checks option in the configuration file.

Example¶

Checks: -*,custom-call-main-function CustomChecks:

• Name: call-main-function Query: | match callExpr( callee( functionDecl(isMain()).bind("fn") ) ).bind("callee") Diagnostic:
  • BindName: fn Message: main function. Level: Note
  • BindName: callee Message: call to main function. Level: Warning

int main(); // note: main function.

void bar() { main(); // warning: call to main function. [custom-call-main-function] }

Matters Need Attention¶

This feature needs to be explicitly enabled by –experimental-custom-checksbecause it is currently in the experimental stage. Welcome to submit any suggestions in the link.

During the experimental stage, the required configuration structure of this feature may be changed in the future. Future changes will be as forward-compatible as possible, but this is not a guarantee.

In subsequent versions, including non-experimental stage, the query statements will change at any time. The essence of clang-query is to parse the query string and dynamically generate the corresponding AST matcher. Therefore, its functionality is entirely dependent on the functions provided by the AST matcher library. The ast matcher will change along with the changes in the clang AST. Please refer to ast matcher reference.