Don't use include-what-you-use.

It produces a LOT of output for a project where it's first added, so it takes quite a lot of work to adapt because all of the work has to be reviewed (especially on the first run).

After actually doing all that work in a couple of Sound Radix's projects, the end result was that it made almost no difference to the CI build time.

Running IWYU's analysis slows down compilation considerably, so even for already-adapted projects it doesn't make sense to run by default either locally or in CI, since one of the main goals of applying IWYU in the first place is making builds faster!

It requires separately testing debug, release, and any other build configurations with differing macro definitions.

It requires making manual fixes to accommodate changes incompatible with build platforms other than the one you run IWYU on.

It can't take expanded macros into account, so header files defining utility macros have to be manually marked to keep.

It sometimes just wrongly removes needed includes, requiring manual fixes.

Running multiple iterations might be needed to get to a stable state where no more warnings are found.

It requires writing extra mappings for system headers it isn't aware of (was missing a few on macOS), as well as for 3rd-party frameworks such as JUCE.

It sometimes crashes.

For C headers, it seems to randomly decide whether to include the <cxxx> or <xxx.h> version. This one isn't important at all, except if you're running IWYU you're probably somewhat pedantic? So just know it wouldn't get you those pristine includes you might be looking for.

For all these reasons, I stopped after integrating support on macOS, not bothering to add support on Linux, and definitely not bothering to add it on Windows (which IWYU appears to have limited support for).

In short, include-what-you-use is alpha quality, which is what the repo also clearly states.

In conclusion, IWYU probably isn't worth your time, except maybe in extreme cases, e.g., if your codebase makes no use of forward declarations and you want to change that. Wait for modules to become mainstream instead.

...Still want to run it anyway? OK.