jianmu
/
lammps
forked from lijiext/lammps
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
lammps/doc/include-file-conventions.md

6.0 KiB
Raw Blame History

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

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 are 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 <cstring> or #include <mpi.h>) 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 <cstdlib> or #include <cctypes>). 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 <stdint.h> versus #include <cstdint> or #include <inttypes.h> versus #include <cinttypes>).

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. References to other classes inside the class should be make through pointers, for which forward declarations (inside the LAMMPS_NS or the new class' 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 statements 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 through 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 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.

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.