Repository files navigation

Tool for analyzing includes in C++.One of the problems in C++ is that if a header file was changed all files thatinclude 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 fromdocs/examples/simple_example/

• filebase_char_factory.hpp

#pragma once#include"base_char.hpp"#include<memory>classBaseCharFactory{public:virtual~BaseCharFactory() =default;virtual std::unique_ptr< BaseChar >createObject() = 0;};

• filebase_char.hpp

#pragma once#include"char_kind.hpp"classBaseChar{public:virtual~BaseChar() =default;virtual CharKindgetKind()constnoexcept = 0;};

If filechar_kind.hpp is changed all files thatincludebase_char_factory.hpp andbase_char.hpp will be recompiled andit will take time. This tool helps to find the file at the top ofthe include hierarchy:

cppinclude...Most impact files:1 : "char_kind.hpp" impact on 11 filesIncluded by:   1 : "base_char.hpp" line 3, impact on 10 files2 : "base_char.hpp" impact on 10 filesIncluded 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 files3 : "base_char_factory.hpp" impact on 5 filesIncluded 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 indocs/examples/

Back to top

Back to top

The tool reads settings from.cppinclude.json located in the work directory oryou can pass a configuration file in the argumentconfiguration_file.For example:

cppinclude --configuration_file=project.json

Back to top

Path to generatedcompile_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 locatedinsrc orsources 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 valuesfile_extensionsfor 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 directorybut 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 directoryand files in includes. For example, ignore all boost filesor 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=unresolvedcppinclude --report=most_impactcppinclude --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 amain.cpp file and ainclude folder that storestheheader.hpp header:

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

Whencppinclude is run, the result will be:

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

Adding theinclude folder toinclude_dirs will remove theunresolved 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 fromdocs/examples/simple_example/

cppinclude --report=most_impact...Most impact files:1 : "char_kind.hpp" impact on 11 filesIncluded by:   1 : "base_char.hpp" line 3, impact on 10 files2 : "base_char.hpp" impact on 10 filesIncluded 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 files3 : "base_char_factory.hpp" impact on 5 filesIncluded 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 11files to recompile.

Back to top

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

cppinclude --report=unincludedStart 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 oneoccurrence will be counted.only first header and other will be unincluded.For example:lib1/header.hpp,lib2/header.hpp andmain.cpp :

#include"header.hpp"...

The result will be:

cppinclude --include_dirs=lib1,lib2 --report=unincludedStart 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 specifiedin compile_commands.json or that are found on the filesystem.

• Header files are files that have extension started withh 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 fromdocs/examples/simple_example_for_different_type_report/

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

Examplelua :

cppinclude --show_details=false...Most impact files:1 : "luaconf.h" impact on 62 files2 : "lua.h" impact on 61 files3 : "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 files2 : "config.h" impact on 12,345 files3 : "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_ignorePath "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 scripton 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 bashcppinclude --version

Analyze your sources in docker image:

docker run -v /tmp/project_src:/src/project_src -it cppinclude/cppincludecd /src/project_srccppinclude

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 pleasewrite email tocppinclude@yandex.com

Back to top