Include-What-You-Use

Header file checker

• https://include-what-you-use.org/

iwyu is a tool for deciding which #includes are needed, or not. Including the right files, and no more, can speed up builds. It also helps to show the dependencies of a file.

iwyu uses clang to create an AST for the code.

Example

A sample call and its output.

iwyu -I. -Xiwyu --no_comments -Xiwyu --pch_in_code -Xiwyu --mapping_file=neomutt.imp thread.c

thread.c should remove these lines:
- #include "globals.h"

The full include-list for thread.c:
#include "config.h"
#include "thread.h"
#include <limits.h>
#include <stdlib.h>
#include <time.h>
#include "body.h"
#include "header.h"
#include "mutt/mutt.h"
#include "sort.h"

Common options used are:

Option	Description	Notes
-I.	Add an include dir .	Passed to clang
-DSYMBOL	Define a SYMBOL	Passed to clang
-Xiwyu --no_comments	Don’t add notes to the output	IWYU option
-Xiwyu --pch_in_code	The file has an important header first	IWYU option
-Xiwyu --mapping_file=FILE	Use this lookup file	IWYU option

Mapping File

It’s hard for iwyu to work out which header files the developers think are important. For example, in NeoMutt, you can replace lots of library headers:

#include "mutt/message.h"
#include "mutt/address.h"
#include "mutt/rfc2047.h"
#include "mutt/mapping.h"
#include "mutt/hash.h"

with one helper header

#include "mutt/mutt.h"

The mapping file also provides fixes for some header files in glibc that cause confusion. It looks like this:

# Include one library header rather than the individual headers.
{ include: [ '@"mutt/.*"', private, '"mutt/mutt.h"', public ] },
{ include: [ '@"conn/.*"', private, '"conn/conn.h"', public ] },