Merge pull request #2338 from akohlmey/include-cleanup

Update list of included headers for latest updates of the convention

doc/include-file-conventions.md

@@ -91,32 +91,31 @@ statements should follow the "include what you use" principle.
 
 Include files should be included in this order:
 * the header matching the implementation (`some_class.h` for file `some_class.cpp`)
-* mpi.h
-* system and library headers (anything that is using angular brackets; C-library headers first, then C++)
+* mpi.h  (only if needed)
 * LAMMPS local headers (preferably in alphabetical order)
+* system and library headers (anything that is using angular brackets; preferably in alphabetical order)
+* conditional include statements (i.e. anything bracketed with ifdefs)
 
 ### Special Cases and Exceptions
 
 #### pointers.h
 
-The `pointer.h` header file also includes `cstdio`, `cstddef`,
-`string`, `lmptype.h`, and `utils.h` (and through those indirectly
- `stdint.h`, `intttypes.h`, cstdlib, and `climits`).
+The `pointer.h` header file also includes (in this order) `lmptype.h`,
+`mpi.h`, `cstddef`, `cstdio`, `string`, `utils.h`, and `fmt/format.h`
+and through `lmptype.h` indirectly also `climits`, `cstdlib`, `cinttypes`.
 This means any header including `pointers.h` can assume that `FILE`,
-`NULL`, `INT_MAX` are defined, they may freely use std::string
-and functions from the utils namespace without including the
-corresponding header files.
+`NULL`, `INT_MAX` are defined, and the may freely use the std::string
+for arguments. Corresponding implementation files do not need to include
+those headers.
 
 ## Tools
 
 The [Include What You Use tool](https://include-what-you-use.org/)
 can be used to provide supporting information about compliance with
-the rules listed here.  There are some limitations and the IWYU tool
-may give incorrect advice.  The tools is activated by setting the
-CMake variable `CMAKE_CXX_INCLUDE_WHAT_YOU_USE` variable to the
-path of the `include-what-you-use` command.  When activated, the
-tool will be run after each compilation and provide suggestions for
-which include files should be added or removed.
+the rules listed here.  Through setting `-DENABLE_IWYU=on` when running
+CMake, a custom build target is added that will enable recording
+the compilation commands and then run the `iwyu_tool` using the
+recorded compilation commands information when typing `make iwyu`.
 
 ## Legacy Code
 

doc/src/Build_development.rst

@@ -28,6 +28,40 @@ variable VERBOSE set to 1:
 
 ----------
 
+.. _iwyu_processing:
+
+Report missing and unneeded '#include' statements
+-------------------------------------------------
+
+The conventions for how and when to use and order include statements in
+LAMMPS are `documented in a separate file <https://github.com/lammps/lammps/blob/master/doc/include-file-conventions.md>`_
+(also included in the source code distribution).  To assist with following
+these conventions one can use the `Include What You Use tool <https://include-what-you-use.org/>`_.
+This is still under development and for large and complex projects like LAMMPS
+there are some false positives, so suggested changes need to be verified manually.
+It is recommended to use at least version 0.14, which has much fewer incorrect
+reports than earlier versions.
+
+The necessary steps to generate the report can be enabled via a
+CMake variable:
+
+.. code-block:: bash
+
+   -D ENABLE_IWYU=value    # value = no (default) or yes
+
+This will check if the required binary (include-what-you-use or iwyu)
+and python script script (iwyu-tool or iwyu_tool or iwyu_tool.py) can
+be found in the path.  The analysis can then be started with:
+
+.. code-block:: bash
+
+   make iwyu
+
+This may first run some compilation, as the analysis is dependent
+on recording all commands required to do the compilation.
+
+----------
+
 .. _sanitizer:
 
 Address, Undefined Behavior, and Thread Sanitizer Support

doc/utils/sphinx-config/false_positives.txt

@@ -1355,6 +1355,7 @@ iva
 Ivanov
 Ivector
 Iw
+iwyu
 ixcm
 ixx
 Ixx