1.. title:: clang-tidy - misc-header-include-cycle 2 3misc-header-include-cycle 4========================= 5 6Check detects cyclic ``#include`` dependencies between user-defined headers. 7 8.. code-block:: c++ 9 10 // Header A.hpp 11 #pragma once 12 #include "B.hpp" 13 14 // Header B.hpp 15 #pragma once 16 #include "C.hpp" 17 18 // Header C.hpp 19 #pragma once 20 #include "A.hpp" 21 22 // Include chain: A->B->C->A 23 24Header files are a crucial part of many C++ programs as they provide a way to 25organize declarations and definitions shared across multiple source files. 26However, header files can also create problems when they become entangled 27in complex dependency cycles. Such cycles can cause issues with compilation 28times, unnecessary rebuilds, and make it harder to understand the overall 29structure of the code. 30 31To address these issues, a check has been developed to detect cyclic 32dependencies 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 analyzes 38user-defined headers and their dependencies. It focuses solely on detecting 39include cycles while disregarding other types or function dependencies. 40This specialized analysis helps identify and prevent issues related to header 41file organization. 42 43By detecting include cycles early in the development process, developers can 44identify and resolve these issues before they become more difficult and 45time-consuming to fix. This can lead to faster compile times, improved code 46quality, and a more maintainable codebase overall. Additionally, by ensuring 47that 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 are analyzed, 51System includes such as standard library headers and third-party library headers 52are excluded. System includes are usually well-designed and free of include 53cycles, and ignoring them helps to focus on potential issues within the 54project's own codebase. This limitation doesn't diminish the ability to detect 55``#include`` cycles within the analyzed code. 56 57Developers should carefully review any warnings or feedback provided by this 58solution. While the analysis aims to identify and prevent include cycles, there 59may be situations where exceptions or modifications are necessary. It's 60important to exercise judgment and consider the specific context of the codebase 61when making adjustments. 62 63Options 64------- 65 66.. option:: IgnoredFilesList 67 68 Provides a way to exclude specific files/headers from the warnings raised by 69 a check. This can be achieved by specifying a semicolon-separated list of 70 regular expressions or filenames. This option can be used as an alternative 71 to ``//NOLINT`` when using it is not possible. 72 The default value of this option is an empty string, indicating that no 73 files are ignored by default. 74