74 lines · plain
1.. title:: clang-tidy - misc-header-include-cycle2 3misc-header-include-cycle4=========================5 6Check detects cyclic ``#include`` dependencies between user-defined headers.7 8.. code-block:: c++9 10 // Header A.hpp11 #pragma once12 #include "B.hpp"13 14 // Header B.hpp15 #pragma once16 #include "C.hpp"17 18 // Header C.hpp19 #pragma once20 #include "A.hpp"21 22 // Include chain: A->B->C->A23 24Header files are a crucial part of many C++ programs as they provide a way to25organize declarations and definitions shared across multiple source files.26However, header files can also create problems when they become entangled27in complex dependency cycles. Such cycles can cause issues with compilation28times, unnecessary rebuilds, and make it harder to understand the overall29structure of the code.30 31To address these issues, a check has been developed to detect cyclic32dependencies between header files, also known as "include cycles".33An include cycle occurs when a header file `A` includes header file `B`,34and `B` (or any subsequent included header file) includes back header file `A`,35resulting in a circular dependency cycle.36 37This check operates at the preprocessor level and specifically analyzes38user-defined headers and their dependencies. It focuses solely on detecting39include cycles while disregarding other types or function dependencies.40This specialized analysis helps identify and prevent issues related to header41file organization.42 43By detecting include cycles early in the development process, developers can44identify and resolve these issues before they become more difficult and45time-consuming to fix. This can lead to faster compile times, improved code46quality, and a more maintainable codebase overall. Additionally, by ensuring47that header files are organized in a way that avoids cyclic dependencies,48developers can make their code easier to understand and modify over time.49 50It's worth noting that only user-defined headers their dependencies are51analyzed, system includes such as standard library headers and third-party52library headers are excluded. System includes are usually well-designed and53free of include cycles, and ignoring them helps to focus on potential issues54within the project's own codebase. This limitation doesn't diminish the55ability to detect ``#include`` cycles within the analyzed code.56 57Developers should carefully review any warnings or feedback provided by this58solution. While the analysis aims to identify and prevent include cycles, there59may be situations where exceptions or modifications are necessary. It's60important to exercise judgment and consider the specific context of the61codebase when making adjustments.62 63Options64-------65 66.. option:: IgnoredFilesList67 68 Provides a way to exclude specific files/headers from the warnings raised by69 a check. This can be achieved by specifying a semicolon-separated list of70 regular expressions or filenames. This option can be used as an alternative71 to ``//NOLINT`` when using it is not possible.72 The default value of this option is an empty string, indicating that no73 files are ignored by default.74