mongodb/buildscripts/iwyu

IWYU Analysis tool

This tool will run include-what-you-use (IWYU) analysis across the codebase via compile_commands.json.

The iwyu_config.yml file consists of the current options and automatic pragma marking. You can exclude files from the analysis here.

The tool has two main modes of operation, fix and check modes. fix mode will attempt to make changes to the source files based off IWYU's suggestions. The check mode will simply check if there are any suggestion at all.

fix mode will take a long time to run, as the tool needs to rerun any source in which a underlying header was changed to ensure things are not broken, and so therefore ends up recompile the codebase several times over.

For more information please refer the the script --help option.

Example usage:

First you must generate the compile_commands.json file via this command:

python3 buildscripts/scons.py --build-profile=compiledb compiledb

Next you can run the analysis:

python3 buildscripts/iwyu/run_iwyu_analysis.py

The default mode is fix mode, and it will start making changes to the code if any changes are found.

Debugging failures

Occasionally IWYU tool will run into problems where it is unable to suggest valid changes and the changes will cause things to break (not compile). When it his a failure it will copy the source and all the header's that were used at the time of the compilation into a directory where the same command can be run to reproduce the error.

You can examine the suggested changes in the source and headers and compare them to the working source tree. Then you can make corrective changes to allow IWYU to get past the failure.

IWYU is not perfect and it make several mistakes that a human can understand and fix appropriately.

Running the tests

This tool includes its own end to end testing. The test directory includes sub directories which contain source and iwyu configs to run the tool against. The tests will then compare the results to built in expected results and fail if the the tests are not producing the expected results.

To run the tests use the command:

cd buildscripts/iwyu/test
python3 run_tests.py