# Outline of include file conventions in LAMMPS This purpose of this document is to provide a point of reference for LAMMPS developers and contributors as to what include files and definitions to put where into LAMMPS source. Last change 2019-06-27 ## Table of Contents * [Motivation](#motivation) * [Rules](#rules) * [Tools](#tools) * [Legacy Code](#legacy-code) ## Motivation The conventions outlined in this document are supposed to help making maintenance of the LAMMPS software easier. By trying to achieve consistency across files contributed by different developers, it will become easier to modify and adjust files by the code maintainers, and overall the chance for errors or portability issues will be reduced. Also the rules employed are supposed to minimize naming conflicts and simplify dependencies between files (and thus speed up compilation), as well as make otherwise hidden dependencies visible. ## Rules Below are the various rules that are applied. Not all a enforced strictly and automatically. If there are no significant side effects, exceptions may be possible for cases, where a full compliance to the rules may require a large effort compared to the benefit. ### Core Files Versus Package Files All rules listed below are most strictly observed for core LAMMPS files. Which are the files that are not part of a package and files of the packages MOLECULE, MANYBODY, KSPACE, and RIGID. On the other end of the spectrum are USER packages and legacy packages that predate these rules and thus may not be fully compliant. Also new contributions will be checked more closely, while existing code is incrementally adapted to the rules as time and required effort permits. ### System Versus Local Header Files All system or library provided include files are included with angular brackets (examples: `#include ` or `#include `) while include files provided with LAMMPS are included with double quotes (examples: `#include "pointers.h"` or `#include "compute_temp.h"`). For headers declaring functions of the C-library, the corresponding C++ versions should be included (examples: `#include ` or `#include `). However, those are limited to those defined in the C++98 standard. Some files thus must use the older style unless the minimum C++ standard requirement of LAMMPS is lifted to C++11 or even beyond (examples: `#include ` versus `#include ` or `#include ` versus `#include `). ### C++ Standard Compliance LAMMPS core files currently correspond to the C++98 standard. Files requiring C++11 or later are only permitted in (optional) packages and particularly packages that are not part of the list of commonly used packages like MOLECULE, KSPACE, MANYBODY, or RIGID. Also, LAMMPS uses the C-style stdio library for I/O instead of iostreams. Since using both at the same time can cause problems, iostreams should be avoided where possible. ### Lean Header Files Header files will typically contain the definition of a (single) class. These header files should have as few include statements as possible. This is particularly important for classes that implement a "style" and thus use a macro of the kind `SomeStyle(some/name,SomeName)`. These will be all included in the auto-generated `"some_style.h"` files which will result in a high potential for direct or indirect symbol name clashes. In the ideal case, the header would only include one file defining the parent class. That would typically be either `#include "pointers.h"` for the `Pointers` class, or a header of a class derived from it like `#include "pair.h"` for the `Pair` class and so on. Referenced to other classes inside the class should be make through pointers, for which forward declarations (inside the `LAMMPS_NS` or the new class'es namespace) can be employed. The full definition will then be included into the corresponding implementation file. In the given example from above, the header file would be called `some_name.h` and the implementation `some_name.cpp` (all lower case with underscores, while the class itself would be in camel case and no underscores, and the style name with lower case names separated by a forward slash). ### Implementation Files In the implementation files (typically, those would have the same base name as the corresponding header with a .cpp extension instead of .h) include statments should follow the "include what you use" principle. ### Order of Include Statements Include files should be included in this order: * lmptype.h (should only be included if `MPI_LMP_XXX` data types are used) * mpi.h * system and library headers (anything that is using angular brackets; C-library headers first, then C++) * LAMMPS local headers (first the header matching the implementation file, the rest in mostly alphabetical order) ### Special Cases and Exceptions #### pointers.h The `pointer.h` header file also includes `cstdio` and `lmptype.h` (and throught it `stdint.h`, `intttypes.h`, and `climits`). This means any header including `pointers.h` can assume that `FILE`, `NULL`, `INT_MAX` are defined. ## 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 IWWU 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. ## Legacy Code A lot of code predates the application of the rules in this document, and those rules are a moving target as well. So there is going to be significant chunks of code, that does not fully comply. This applies for example to the USER-REAXC, or the USER-ATC package. The LAMMPS developers are dedicated to make an effort to improve the compliance and welcome volunteers wanting to help with the process.