How IncludeChecker works

How IncludeChecker works

IncludeChecker is based on a simple principle: only include what you need. To determine if a source file is actually needing something from a header file, ctags is used. Ctags is used to generate a list of all tags (classes, structs, typedefs, functions etc.) that are declared within a source file. Simple regular expressions are then used to check each tag to see if it's being used in the source file. If none of the tags of a header are used in the source file, the header file is regarded as being unused.

Constructs that are not supported by IncludeChecker

Because IncludeChecker does not completely parse a source file like the compiler does, it will miss certain unused includes, or incorrectly regard some includes as unused. The latter can be fixed by adding exclude paths or ignored headers, see Command line options or Configuration XML.

These constructs are not supported by IncludeChecker:

• Using macro's in includes, for example #include MYHEADER. IncludeChecker has no way of finding out which header is included by such a statement.
• enum values used as variable names. If you declare a variable with the same name as one of the enum values from a header file, IncludeChecker will always regard that header file is used, even if actually nothing is being used from that header file.
• Using partial type declarations in macros, for example #define START_CLASS(x) class x: public Object. In the header the class declaration will start with START_CLASS(MyClass) and ctags has no way of knowing that it's in fact a class declaration. Therefor it will not find MyClass as a tag, and IncludeChecker may regard the header file containing MyClass as unused, even when it is using MyClass.