| 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. |