Note: You can find the source code for Include Detective on Github.

This weekend I wrote a little Bash script to investigate include chains of some system headers, and it turned out to be pretty useful, so that’s what I’ll talk about in this post.

This is what Include Detective looks like in action:

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.

The source of the preprocessed file can be dumped by passing the -p (for print) before the filename. The following is the output from running include-detective -p assert.h:

# 1 "<stdin>"
# 1 "<built-in>"
# 1 "<command-line>"
# 31 "<command-line>"
# 1 "/usr/include/stdc-predef.h" 1 3 4
# 32 "<command-line>" 2
# 1 "<stdin>"
# 1 "/usr/include/assert.h" 1 3 4
# 35 "/usr/include/assert.h" 3 4
# 1 "/usr/include/features.h" 1 3 4
# 368 "/usr/include/features.h" 3 4
# 1 "/usr/include/sys/cdefs.h" 1 3 4
# 415 "/usr/include/sys/cdefs.h" 3 4
# 1 "/usr/include/bits/wordsize.h" 1 3 4
# 416 "/usr/include/sys/cdefs.h" 2 3 4
# 369 "/usr/include/features.h" 2 3 4
# 392 "/usr/include/features.h" 3 4
# 1 "/usr/include/gnu/stubs.h" 1 3 4
# 10 "/usr/include/gnu/stubs.h" 3 4
# 1 "/usr/include/gnu/stubs-64.h" 1 3 4
# 11 "/usr/include/gnu/stubs.h" 2 3 4
# 393 "/usr/include/features.h" 2 3 4
# 36 "/usr/include/assert.h" 2 3 4
# 64 "/usr/include/assert.h" 3 4
# 67 "/usr/include/assert.h" 3 4
extern void __assert_fail (const char *__assertion, const char *__file,
      unsigned int __line, const char *__function)
     __attribute__ ((__nothrow__ , __leaf__)) __attribute__ ((__noreturn__));
extern void __assert_perror_fail (int __errnum, const char *__file,
      unsigned int __line, const char *__function)
     __attribute__ ((__nothrow__ , __leaf__)) __attribute__ ((__noreturn__));
extern void __assert (const char *__assertion, const char *__file, int __line)
     __attribute__ ((__nothrow__ , __leaf__)) __attribute__ ((__noreturn__));
# 1 "<stdin>" 2

The lines beginning with # are special directives that the compiler inserts for debug purposes. You can read more about them on the GCC man page.

Why is it useful?

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.

Some headers are fine, because you end up using most of the symbols they define.

Other headers not so much. Maybe they are huge and you only need the prototypes of a couple of functions; or maybe they recursively include many other headers, unnecessarily slowing down compile times.

In cases like this, it may be worth the effort to create your own minimal header that contains only the declarations you care about.

A word of caution: removing a header and replacing it with your own slimmed-out version, requires you to make sure that the function prototypes or preprocessor defines are correct for all the architectures you are shipping to.

A simple example of “debloating”

Here is a simple example of how you would go about eliminating a header dependency with your own slim version using the classic “Hello World, using both plain C and C++.

// C++
#include <iostream>

int main()
{
  std::cout << "Hello World!" << std::endl;
}

As you can see, the C++ program gets expanded into more than 17000 lines of code, included from 134 files. This process has to be done every time you compile. Quite crazy, if you only need a small subset of what’s declared in the header.

// C
#include <stdio.h>
int main()
{
  printf("Hello World!\n");
}

The C equivalent is much saner, with only 295 lines of code and 16 includes. Still, we are only calling a function, do we really need all that noise?

Removing the header in plain C

When coding in plain C the process is very easy, you just have to run Include Detective on the header you are interested in removing, and grep for the functions or #defines that you need:

include-detective -p stdio.h | grep printf -A 1

Notice that I used the -p flag, meaning the preprocessed header will be prited to stdout. Next I pipe the result to grep searching for printf and using the -A 1 option, to tell grep that I want one line of context after each match, because I know that most function declarations in GCC’s headers span two or three lines.

This is the relevant output is:

extern int printf (const char *__restrict __format, ...);

Now all you have to do is copy and paste that line into the source file like so:

extern int printf (const char *__restrict __format, ...);
int main()
{
  printf("Hello World!\n");
}

No more #include <stdio.h> and this will compile just fine.

Obviously you are not getting rid of the Standard Library, because the linker will still link to it, but the preprocessor stage of the compilation will be faster. In this simple case the speed increase is irrelevant, but as the number of includes grows, you will see a much larger benefit.

Removing the header in C++

Well… Doing the same for the C++ example is quite a nightmare, as you can imagine from the fact that #include <iostream> brings in 17k lines of code.

I wouldn’t recommend doing it manually but if you figure out a smart way to automate it you can follow this process:

1. output the preprocessed header with the -p option and using MODE=cxx to tell Include Detective that it’s working with C++ like so:

   MODE=c++ include-detective -p iostream > iostream-dump.cc

2. using iostream-dump.cc reconstruct the chain of class/template/typedef that make cout and endl possible, and copy them in your minimal include header

The resulting header will not be a one-liner like in the C case, but it will certainly not be 17000 lines of code!