Analyze the include chain of a C/C++ file or system header
Clone or download
Type Name Latest commit message Commit time
Failed to load latest commit information.
images Added GIFs Oct 6, 2016
LICENSE Initial commit Oct 5, 2016 Add sample to readme Oct 6, 2016
include-detective Support CC enviroment variable that contains spaces in the path May 21, 2017

Include Detective

Simple shell script that analyzes the include chain of a C/C++ file or system header.

How does it work?

Include Detective is a bash script that runs the compiler on a dummy C or C++ file with just an #include directive. The #include points to the path or system header specified as argument to the script.

The compiler (GCC and Clang family of compilers) is invoked twice with flags -E and -dM.

The -E flag stops compilation after the preprocessing stage, resulting in an output where all headers have been inlined and preprocessor directives and macros expanded.

The -dM flag tells the compiler to dump all preprocessor defines (both builtin and the ones defined in the included files).

These outputs are then parsed and statistics printed as you can see above.

How to use

Usage: include-detective [options] <file>
Print include statistics about a C/C++ file or system header

  -p     print the preprocessed source instead of
          computing stats
  -d     print the preprocessor defines
  -i     print nested includes
  -h     show this help
  -x     <file> is a C++ file

Environment variables:
  CC     path to the compiler executable
  CFLAGS compilation flags to pass to the compiler.
          these flags cannot contain filenames or
          output specifiers (e.g. -o)
  MODE   specify MODE=c++ to process as C++

Environment variables can be set on a per-command basis by prefixing the command like so: CC=clang CFLAGS="-std=c99 -fno-builtin" stdio.h

Why should I use it?

Include Detective can be useful when you are looking to eliminate headers in order to speed up compile times when using single translation unit builds, in favor of precompiled headers.

Take a look at the blog post Include Detective: Keep An Eye on Those Includes for more details.



  1. Clone the repository and chmod +x the script to make it executable.
  2. Run it passing the path to a source file or a system header file.


Haven't tried, but you can probably run it on a Linux-like environment like Cygwin or using the Windows Subsystem for Linux if you are on Windows 10.


The following is an example of a small console program before and after includes to system headers have been removed. Only the symbols actually used by the program have been kept (e.g. externs, typedefs and defines).

Compile time went from 0.8s to 0.5s after the trimming process.


Public Domain