From e843394b381d843db596613585cf8919ac506440 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?V=C3=ADt=20Ku=C4=8Dera?= <26327373+vkucera@users.noreply.github.com> Date: Thu, 9 Apr 2026 16:08:53 +0200 Subject: [PATCH] Tools: Extend instructions for Clang-Tidy. Add more links. --- docs/tools/README.md | 29 +++++++++++++++++++---------- 1 file changed, 19 insertions(+), 10 deletions(-) diff --git a/docs/tools/README.md b/docs/tools/README.md index 1e5bcaef..13e295b7 100644 --- a/docs/tools/README.md +++ b/docs/tools/README.md @@ -59,34 +59,43 @@ To use Clang-Tidy, you need to have O2Physics compiled and a valid symbolic link The [`readability-identifier-naming`](https://clang.llvm.org/extra/clang-tidy/checks/readability/identifier-naming.html) check can fix deviations from the [naming conventions](https://rawgit.com/AliceO2Group/CodingGuidelines/master/naming_formatting.html). -### Cleaning `#include`s +### Cleaning `#include` statements and `using` statements -The [`misc-include-cleaner`](https://clang.llvm.org/extra/clang-tidy/checks/misc/include-cleaner.html) check can fix missing and unused `#include`s. -This helps to apply the [Include What You Use](https://github.com/AliceO2Group/O2Physics/issues/8357) principle which allows to maintain header dependencies clean. +```danger +Incorrect usage of `#include` statements and `using` statements causes [unnecessary recompilations](https://github.com/include-what-you-use/include-what-you-use/blob/master/docs/WhyIWYU.md#fewer-recompiles) and can [break compilation](https://github.com/include-what-you-use/include-what-you-use/blob/master/docs/WhyIWYU.md#allow-refactoring) of other parts of the project! (See also [Management of header dependencies](https://indico.cern.ch/event/1513750/#29-management-of-header-depend).) +``` + +The [`misc-include-cleaner`](https://clang.llvm.org/extra/clang-tidy/checks/misc/include-cleaner.html) check can fix missing and unused `#include` statements. +This helps to apply the [Include What You Use](https://github.com/AliceO2Group/O2Physics/issues/8357) (IWYU) principle which allows to maintain header dependencies clean. +The behaviour of the check can be tuned manually using [IWYU pragmas](https://github.com/include-what-you-use/include-what-you-use/blob/master/docs/IWYUPragmas.md). + +The [`google-global-names-in-headers`](https://clang.llvm.org/extra/clang-tidy/checks/google/global-names-in-headers.html) check finds `using` declarations and directives in headers, which cause [global namespace pollution](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#rs-using-directive) that can be difficult to fix. + +The [`misc-unused-using-decls`](https://clang.llvm.org/extra/clang-tidy/checks/misc/unused-using-decls.html) check finds unused `using` declarations in source files, which create fake dependencies that hamper IWYU. ### Testing (and fixing) many files at once -Here is an example of how to run the `misc-include-cleaner` check in parallel on all `.h`, `.cxx`, `.C` files in the current directory. +Here is an example of how to run selected checks in parallel on all `.h`, `.cxx`, `.C` files in the current directory (`.`). ```bash -find . -name "*.h" -o -name "*.cxx" -o -name "*.C" | parallel "clang-tidy --fix -checks=-*,misc-include-cleaner {}; echo \"{} \$?\"" > "clang-tidy.log" +find . -name "*.h" -o -name "*.cxx" -o -name "*.C" | parallel "clang-tidy -fix -checks=-*,misc-include-cleaner,google-global-names-in-headers,misc-unused-using-decls {}; echo \"{} \$?\"" > "clang-tidy.log" ``` The [`parallel`](https://www.gnu.org/software/parallel/) command is used to parallelise the execution of the `clang-tidy` command for all files. -For each file, Clang-Tidy will first try to compile it and then run the enabled check(s) and fix found problems (the `--fix` option). +For each file, Clang-Tidy will first try to compile it and then run the enabled check(s) and fix found problems (the `-fix` option). The messages are redirected into `clang-tidy.log`. The file name and the exit code are printed below the output of Clang-Tidy so that you can get the list of files for which Clang-Tidy failed with `grep " 1$" "clang-tidy.log"`. ## Fixing include format Headers from the same project should be included using quotation marks (`#include "path/header.h"`), all other headers should be included using angle brackets (`#include `). -Failing to do so can result in picking a wrong header. -See more details in the [C++ Core Guidelines](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#sf12-prefer-the-quoted-form-of-include-for-files-relative-to-the-including-file-and-the-angle-bracket-form-everywhere-else). +Failing to do so points the preprocessor to a [wrong location](https://gcc.gnu.org/onlinedocs/cpp/Include-Syntax.html) and can result in picking a wrong header. +See also the [C++ Core Guidelines](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#sf12-prefer-the-quoted-form-of-include-for-files-relative-to-the-including-file-and-the-angle-bracket-form-everywhere-else). The [`format_includes.awk`](https://github.com/AliceO2Group/O2Physics/blob/master/Scripts/format_includes.awk) script allows to fix the include format in a provided O2Physics file. -To fix the include format in all `.h`, `.cxx` files in the current directory, execute: +To fix the include format in all `.h`, `.cxx` files in the current directory (`.`), execute: ```bash find . -name "*.h" -o -name "*.cxx" | parallel "awk -f Scripts/format_includes.awk \"{}\" > \"{}.tmp\" && mv \"{}.tmp\" \"{}\"" @@ -111,7 +120,7 @@ cppcheck --language=c++ --std=c++20 --enable=style --check-level=exhaustive --su The report will be stored in the `err.log` file. -To run a parallelised analysis of all `.h`, `.cxx`, `.C` files in the current directory, execute: +To run a parallelised analysis of all `.h`, `.cxx`, `.C` files in the current directory (`.`), execute: ```bash find . -name "*.h" -o -name "*.cxx" -o -name "*.C" | parallel "cppcheck --language=c++ --std=c++20 --enable=style --check-level=exhaustive --suppressions-list=cppcheck_config {}" 2> "err.log"