1. Each *source* file should include ``gmxpre.h`` first.
2. If a *source* file has a corresponding header, it should be included next.
If the header is in the same directory as the source, then it is included
- without any path (i.e., relative to the source), otherwise relative to
- ``src/`` (the latter case should be rare).
+ without any path (i.e., relative to the source). Otherwise, the canonical
+ include path of ``libraryname/modulename/header.h`` is used.
3. If the file depends on defines from ``config.h``, that comes next.
4. This is followed by standard C/C++ headers, grouped as follows:
``<gtest/gtest.h>``.
6. |Gromacs|-specific libraries from ``src/external/``, such as
``"thread_mpi/threads.h"``.
-7. |Gromacs|-specific headers that are not internal to the including module,
- included with a path relative to ``src/``.
-8. In *test* files, headers not internal to the module, but specific to
- testing code, are in a separate block at this point, paths relative to
- ``src/``.
-9. Finally, |Gromacs| headers that are internal to the including module are
- included using a relative path (but never with a path starting with ``../``;
- such headers go into group 7 instead). For test files, this group contains
- headers that are internal to tests for that module.
+7. |Gromacs| headers that are not part of the including module.
+8. Public |Gromacs| headers that are part of the including module.
+9. Finally, |Gromacs| headers that are internal to the including module,
+ executable, or test target
+ (typically at the same path as the source file).
All |Gromacs| headers are included with quotes (``"gromacs/utility/path.h"``),
other headers with angle brackets (``<stdio.h>``). Headers under ``src/external/``
cases. Trailing comments on the same line as #include statements are
preserved and do not affect the checker/sorter.
-The includestyle used to differentiate between header files that were declared
-to be part of the module and not used outside the module, and those that were
-either not part of a module, used in other modules, or installed.
-As the possibility of installation has been removed (for now), changes to the
-previous organization might occur where such installed files were implicitly
-marked as being used outside of a module even though they were not used within
-|Gromacs| outside their module.
-
As part of the effort to build a proper API, a new scheme of separating between
public, library and module functionality in header files is planned.
-
-The guidelines are enforced by an automatic checker script that can also
-sort/reformat include statements to follow the guidelines.
-See :doc:`gmxtree` for details.
+See also :doc:`gmxtree` and
+`API restructuring issues <https://gitlab.com/gromacs/gromacs/-/issues?label_name%5B%5D=API+restructuring>`__
+for details.
Enforcing a consistent order and style has a few advantages:
first. With this order, the person working on the header is most likely to
see these problems instead of someone else seeing them later when
refactoring unrelated code.
-* Consistent usage of paths in #include directives makes it easy to use
+* Consistent usage of paths in ``#include`` directives makes it easy to use
``grep`` to find all uses of a header, as well as all include dependencies
between two modules.
* An automatic script can be used to re-establish clean code after
biod.pnpi.spb.ru / alexxy / gromacs.git / blobdiff