include-what-you-use (IWYU) support

include-what-you-use (IWYU) is a tool built on top of Clang and LLVM that analyzes #include directives in C and C++ source files. For every translation unit it reports headers that are included but not used, and symbols that are used but whose defining header is only included transitively. Acting on its suggestions keeps the set of includes minimal and explicit.

Installing include-what-you-use

include-what-you-use is distributed by most Linux distributions, on ubuntu:

sudo apt-get install iwyu

Make sure the include-what-you-use binary is available in your PATH.

Run include-what-you-use

Note

IWYU is built on Clang, so building with the LLVM toolchain produces the most accurate results.

To run include-what-you-use, west build should be called with a -DZEPHYR_SCA_VARIANT=iwyu parameter, e.g.

west build -b native_sim samples/hello_world -- -DZEPHYR_SCA_VARIANT=iwyu

The analysis runs alongside the compilation of each source file, and the suggested include changes are printed to the build output (stderr).

Configuring include-what-you-use

include-what-you-use can be controlled using specific options. Refer to the IWYU documentation for the full list of options.

Parameter	Description
IWYU_OPTS	A semicolon separated list of include-what-you-use options. Each option is forwarded to the tool with the required -Xiwyu prefix automatically.

These parameters can be passed on the command line, or be set as environment variables.

west build -b native_sim samples/hello_world -- -DZEPHYR_SCA_VARIANT=iwyu -DIWYU_OPTS="--no_comments;--verbose=3"