1 files changed, 64 insertions, 0 deletions
diff --git a/buildscripts/iwyu/README.md b/buildscripts/iwyu/README.md
new file mode 100644
index 00000000000..2e925d7500a
--- /dev/null
+++ b/buildscripts/iwyu/README.md
@@ -0,0 +1,64 @@
+# IWYU Analysis tool
+
+This tool will run 
+[include-what-you-use](https://github.com/include-what-you-use/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
+```