Debian Codegraph @

clang-tools-extra/docs/clang-tidy/checks/misc/header-include-cycle.rst

raw
1 .. title:: clang-tidy - misc-header-include-cycle
2
3 misc-header-include-cycle
4 =========================
5
6 Check 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
24 Header files are a crucial part of many C++ programs as they provide a way to
25 organize declarations and definitions shared across multiple source files.
26 However, header files can also create problems when they become entangled
27 in complex dependency cycles. Such cycles can cause issues with compilation
28 times, unnecessary rebuilds, and make it harder to understand the overall
29 structure of the code.
30
31 To address these issues, a check has been developed to detect cyclic
32 dependencies between header files, also known as "include cycles".
33 An include cycle occurs when a header file `A` includes header file `B`,
34 and `B` (or any subsequent included header file) includes back header file `A`,
35 resulting in a circular dependency cycle.
36
37 This check operates at the preprocessor level and specifically analyzes
38 user-defined headers and their dependencies. It focuses solely on detecting
39 include cycles while disregarding other types or function dependencies.
40 This specialized analysis helps identify and prevent issues related to header
41 file organization.
42
43 By detecting include cycles early in the development process, developers can
44 identify and resolve these issues before they become more difficult and
45 time-consuming to fix. This can lead to faster compile times, improved code
46 quality, and a more maintainable codebase overall. Additionally, by ensuring
47 that header files are organized in a way that avoids cyclic dependencies,
48 developers can make their code easier to understand and modify over time.
49
50 It's worth noting that only user-defined headers their dependencies are analyzed,
51 System includes such as standard library headers and third-party library headers
52 are excluded. System includes are usually well-designed and free of include
53 cycles, and ignoring them helps to focus on potential issues within the
54 project's own codebase. This limitation doesn't diminish the ability to detect
55 ``#include`` cycles within the analyzed code.
56
57 Developers should carefully review any warnings or feedback provided by this
58 solution. While the analysis aims to identify and prevent include cycles, there
59 may be situations where exceptions or modifications are necessary. It's
60 important to exercise judgment and consider the specific context of the codebase
61 when making adjustments.
62
63 Options
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.