Tool for analyzing includes in C++. One of the problems in C++ is that if a header file was changed all files that include that file will be recompiled and sometime it takes a lot of time.

• Examples
• Settings
  • All arguments
  • report
    • unresolved
    • most_impact
    • unincluded
    • different_type
  • configuration_file
  • compile_commands
  • project_dir
  • file_extensions
  • analyze_without_extension
  • include_dirs
  • ignore_dirs
  • ignore_system_includes
  • ignore_files
  • report_limit
  • report_details_limit
  • show_std_files
  • show_only_std_headers
  • show_details
  • thousands_separator
  • verbose_ignore
• Build
• Docker image
• Presentations
• Tips for optimization includes
• Third-party libraries
• Support

Example from docs/examples/simple_example/

• file base_char_factory.hpp

#pragma once
#include "base_char.hpp"
#include <memory>

class BaseCharFactory
{
public:
    virtual ~BaseCharFactory() = default;
    virtual std::unique_ptr< BaseChar > createObject() = 0;
};

• file base_char.hpp

#pragma once
#include "char_kind.hpp"

class BaseChar
{
public:
    virtual ~BaseChar() = default;
    virtual CharKind getKind() const noexcept = 0;
};

If file char_kind.hpp is changed all files that include base_char_factory.hpp and base_char.hpp will be recompiled and it will take time. This tool helps to find the file at the top of the include hierarchy:

cppinclude
...
Most impact files:
1 : "char_kind.hpp" impact on 11 files
Included by:
   1 : "base_char.hpp" line 3, impact on 10 files
2 : "base_char.hpp" impact on 10 files
Included by:
    1 : "base_char_factory.hpp" line 3, impact on 5 files
    2 : "char_a.hpp" line 3, impact on 2 files
    3 : "char_b.hpp" line 3, impact on 2 files
3 : "base_char_factory.hpp" impact on 5 files
Included by:
    1 : "char_a_factory.hpp" line 3, impact on 2 files
    2 : "char_b_factory.hpp" line 3, impact on 2 files
...

See more examples in docs/examples/

Back to top

Back to top

The tool reads settings from .cppinclude.json located in the work directory or you can pass a configuration file in the argument configuration_file. For example:

cppinclude --configuration_file=project.json

Back to top

Path to generated compile_commands.json file by CMake with argument -DCMAKE_EXPORT_COMPILE_COMMANDS=ON, for example:

cmake .. -DCMAKE_EXPORT_COMPILE_COMMANDS=ON

You can set the path for the compile_command.json file in the configuration file:

{
    "compile_commands" : "build/compile_commands.json"
}

or, pass as an argument:

cppinclude --compile_commands=build/compile_commands.json

Back to top

PPath to a folder that contains sources. Often source files are located in src or sources folder, not in the root folder of project. You can set it in configuration file with:

{
    "project_dir" : "src"
}

or, pass as an argument:

cppinclude --project_dir=src

Back to top

If you use other file extensions than default values file_extensions for C++ sources you can specify them in the configuration file with:

{
    "file_extensions" : ["*.cc", "*.hh"]
}

or, pass as an argument:

cppinclude --file_extensions=*.cc,*hh

Back to top

Analyze files without extension in the project directory, default: false. You can set this option in the configuration file with:

{
    "analyze_without_extension" : true
}

or, pass as an argument:

cppinclude --analyze_without_extension=true

Back to top

Add paths to the header search directories. Default value is project folder. You can set it in the configuration file with:

{
    "include_dirs" : [ "lib1", "lib2"]
}

or, pass as an argument:

cppinclude --include_dirs=lib1,lib2

Back to top

Folders to be ignored during project analysis. For example: third-party libraries that are located under the project directory but should not be analyzed. You can set it in the configuration file with:

{
    "ignore_dirs" : ["./3rd-part", "gtest"]
}

or, pass as an argument:

cppinclude --ignore_dirs=./3rd-part,gtest

Back to top

Ignore includes with <>, example #include <iostream> will be ignored. You can set it in the configuration file with:

{
    "ignore_system_includes" : true
}

or, pass as an argument:

cppinclude --ignore_system_includes=true

Back to top

Ignore files by regexp. The tool will ignore files in project’s directory and files in includes. For example, ignore all boost files or generated files (*.gen). You can set in configuration file

{
    "ignore_files" : [ "boost/.*", ".*\\.def"]
}

or, pass as an argument:

cppinclude --ignore_files=boost/.*,.*\\.def

Back to top

Name of report. Possible values:

• unresolved -- show included files that are not found within the project folder;
• most_impact -- show files that most impact on other files;
• unincluded -- show unincluded headers;
• different_type -- show headers that are included in #include <...> and #include "..." .

As arguments:

cppinclude --report=unresolved
cppinclude --report=most_impact
cppinclude --report=unresolved,most_impact

As a configuration file setting:

{
    "report" : [ "unresolved", "most_impact"]
}

Back to top

Show headers that are included but not found in the given search paths. One possible reason is missing include files, for example: iven a main.cpp file and a include folder that stores the header.hpp header:

tree
.
├── include
│   └── header.hpp
└── main.cpp

When cppinclude is run, the result will be:

cppinclude --report=unresolved
Start initialization project ...
Start analyze sources ...
Start report results ...
Unresolved files:
1. "header.hpp" isn't resolved in:
    1. "main.cpp" line: 1

Adding the include folder to include_dirs will remove the unresolved files entry:

cppinclude --report=unresolved --include_dirs=include

Back to top

Show how many files will be recompiled when a given header is changed. Example from docs/examples/simple_example/

cppinclude --report=most_impact
...
Most impact files:
1 : "char_kind.hpp" impact on 11 files
Included by:
   1 : "base_char.hpp" line 3, impact on 10 files
2 : "base_char.hpp" impact on 10 files
Included by:
    1 : "base_char_factory.hpp" line 3, impact on 5 files
    2 : "char_a.hpp" line 3, impact on 2 files
    3 : "char_b.hpp" line 3, impact on 2 files
3 : "base_char_factory.hpp" impact on 5 files
Included by:
    1 : "char_a_factory.hpp" line 3, impact on 2 files
    2 : "char_b_factory.hpp" line 3, impact on 2 files
...

The above output means that a change in char_kind.hpp will force 11 files to recompile.

Back to top

Show headers that are found in the search directories but that were not included in the source code. It often happens after refactoring when headers when include directives were removed from code and thefiles remained in place. Example from docs/examples/simple_example_with_unincluded_headers/

cppinclude --report=unincluded
Start initialization project ...
Start analyze sources ...
Start report results ...
Unincluded headers:
1 : "config.hpp"
2 : "settings.hpp"

Limitations:

• Headers with same names:

If headers have the same name but are located in different paths only one occurrence will be counted. only first header and other will be unincluded. For example: lib1/header.hpp, lib2/header.hpp and main.cpp :

#include "header.hpp"
...

The result will be:

cppinclude --include_dirs=lib1,lib2 --report=unincluded

Start initialization project ...
Start analyze sources ...
Start report results ...
Unincluded headers:
1 : "lib2/header.hpp"

• Empty result for CMake project:

The current implementation ignores CMake project files. Only source files are analyzed currently that are either specified in compile_commands.json or that are found on the filesystem.

• Header files are files that have extension started with h letter

All limitations will be fixed in future releases

Back to top

Show headers that are included in different ways. It helps to follow code styles in project, for example include third party libraries in <...> and project header in "...". Example from docs/examples/simple_example_for_different_type_report/

cppinclude --report=different_type
Start initialization project ...
Start analyze sources ...
Start report results ...
Files that are included by different ways:
1. base_char.hpp
With double quotation marks ( #include "..." ) in files:
    1. base_char_factory.hpp line 3
    2. char_b.hpp line 3
With angle brackets ( #include <...> ) in files:
    1. char_a.hpp line 3
2. base_char_factory.hpp
With double quotation marks ( #include "..." ) in files:
    1. char_b_factory.hpp line 3
With angle brackets ( #include <...> ) in files:
    1. char_a_factory.hpp line 3

Back to top

Maximum number of files in report. For example, only 5 unresolved files will be in report:

cppinclude --report=unresolved --report_limit=5

Also you can set in configuration file:

{
    "report_limit" : 5
}

Back to top

Maximum number of detail in report. For example, only 3 files will be in report that include unresolved file

cppinclude --report=unresolved --report_details_limit=3

Also you can set in configuration file:

{
    "report_details_limit" : 3
}

Back to top

Enable showing standard library headers in output.

cppinclude --show_std_files=true

Also you can set in configuration file:

{
    "show_std_files" : true
}

Back to top

Show only standard library headers in output.

cppinclude --show_only_std_headers=true

Also you can set in configuration file:

{
    "show_only_std_headers" : true
}

Show or hide details

cppinclude --show_details=false

Also you can set in configuration file:

{
    "show_details" : false
}

Example lua :

cppinclude --show_details=false

...
Most impact files:
1 : "luaconf.h" impact on 62 files
2 : "lua.h" impact on 61 files
3 : "llimits.h" impact on 40 files
...

Don't show where files are included

Back to top

You can change default thousands separator (space) to your separator

For example:

cppinclude --thousands_separator=,

Also you can set in configuration file:

{
    "thousands_separator" : ","
}

Result:

...
Most impact files:
1 : "supper_header.h" impact on 123,456 files
2 : "config.h" impact on 12,345 files
3 : "limits.h" impact on 1,234 files
...

Note: you can use only one character

Don't show where files are included

Back to top

Show ignored files and folders. For example:

cppinclude --verbose_ignore

Path "sys/types.h" was ignored by "sys/.*.h"
Path "mach/mach_init.h" was ignored by "mach/.*.h"
Folder ".../3rdparty" was ignored
...

Back to top

Requirements:

• C++17
• CMake
• Compilers:
  • GCC ( tested on 7.5 and 10.1 versions )
  • Visual Studio ( tested on 2017 and 2019 community edition versions )
  • Clang ( tested on 10.0 version )
  • Apple Clang ( tested on 12.0 version )

Build script on Windows:

.\build.bat

on Unix:

./build.sh

Back to top

Pull image:

docker pull cppinclude/cppinclude

Or build docker image from source:

docker build -t cppinclude/cppinclude .

Test image:

docker run -it cppinclude/cppinclude bash
cppinclude --version

Analyze your sources in docker image:

docker run -v /tmp/project_src:/src/project_src -it cppinclude/cppinclude
cd /src/project_src
cppinclude

Back to top

• 2020, Lightning Talk on CppCon 2020, cppinclude - Tool for analyzing includes in C++
  • Video : https://www.youtube.com/watch?v=DXil_ahLTyg
  • Slides: 2020_cppcon2020_small_talk.pdf
• 2020, internal talk - 2020_internal_talk.pdf

Back to top

• use forward declaration
• split big header
• Pointer to implementation

Back to top

• stdfwd
• cxxopts
• {fmt}
• json for modern C++
• Boost.Test
• RE2

Back to top

If you need help with your project or need some feature please write email to [email protected]

Back to top