Instructions

Download IncludeGuardian v0.0.8 for Windows x64 or IncludeGuardian v0.0.8 for Linux x64.

IncludeGuardian can either be run specifying a compilation database with -p and a list of source files,

  1. includeguardian.exe -p compile_commands.json main.cpp my_other_source.cpp
  2. includeguardian.exe -p compile_commands.json **/*.cpp (with shopt -s globstar enabled)

or by specifying the directory containing all source files (either directly or within subdirectories) with --dir,

  1. includeguardian.exe --dir .

When using a compilation database, this should already include all of your additional include directories and compilation flags. However, if you are using --dir then most likely you will need to specify additional directories with --I and --isystem. Both of these will specify include directories, but files found with --isystem will be considered to be external and analysis will not recommend editting these files.

  1. includeguardian.exe --dir . --I include
  2. includeguardian.exe --dir . --isystem thirdparty/boost/include --I mylib/include
  3. includeguardian.exe -p compile_commands.json **/*.cpp --I override/mylib/include

IncludeGuardian can serialize the graph of your solution and load it back up for analysis later on with the --save <file path> argument (you may want to run with --analyze=false to avoid running the analysis immediately after writing the file).

  1. includeguardian.exe --dir . --I include --save out.igg --analyze=false

Then we can load it up to run analysis with --load <file path>

  1. includeguardian.exe --load out.igg

This will allow you to rerun analysis with different options such as --cutoff [percentage] that controls the minimum saving required to show a recommendation. The default is --cutoff 1 to only show recommendations for changes that will give at least a 1% saving. Lowering the cutoff will increase the number of recommendations but will take additional time.

Understanding the Results

unguarded files

This section lists files that have been included more than once, but do not have a strict enough include guard in order to achieve the multiple-inclusion optimization implemented in most compilers that avoid reopening a file and parsing it if that file is included multiple times within the same translation unit.

A file is properly guarded if it includes #pragma once or an include guard that wraps all non-comment, non-whitespace text within the file.

For more detail on include guards, #pragma once, and the multiple-include optimization see the article Include Guards and their Optimzations.

unreferenced components

This section lists source files that have a corresponding header that is not included by any other file. These files may be candidates for removal.

include directives

This section lists individual include directives (e.g. #include <string>) that are the most expensive. Sometimes these directives can be

  • removed completely as they are no longer needed,
  • replaced with forward declarations,
  • replaced with smaller headers (e.g. <iostream> with <ostream>).

make private

This section lists expensive header files that are included by other headers, and the saving if these includes could be moved to the corresponding source files. Sometimes a large header (such as <algorithm>) is an implementation detail and does not need to be included in the header. Or perhaps the pimpl idiom could be used to hide member variables of a class so that they do not need to be included in the header.

pch additions

This section lists external files (those found in include directories specified with --isystem) that would save the most time if added to a precompiled header. The --pch-ratio flag can change

large files

This sections lists header files that are comparatively large and would benefit from being split into smaller headers or made smaller by removing unnecessary code.

inline sources

This sections lists sources files that are comparatively small compared to their header files. The overall build may be faster if these sources were removed and their content inlined into their respective header files.

Note that this may be a pessimization if you are running IncludeGuardian on a commonly used library. You may speed up the build of this library, but slow down builds of other dependent libraries/applications.