Merge branch 'master' into collected-small-changes

  endif()

endif()

#######################################

# add custom target for IWYU analysis

#######################################

set(ENABLE_IWYU OFF CACHE BOOL "Add 'iwyu' build target to call the include-what-you-use tool")

mark_as_advanced(ENABLE_IWYU)

if(ENABLE_IWYU)

  find_program(IWYU_EXE NAMES include-what-you-use iwyu)

  find_program(IWYU_TOOL NAMES iwyu_tool iwyu-tool iwyu_tool.py)

  if (IWYU_EXE AND IWYU_TOOL)

    add_custom_target(

      iwyu

      ${IWYU_TOOL} -o clang -p ${CMAKE_CURRENT_BINARY_DIR} -- -Xiwyu --mapping_file=${CMAKE_CURRENT_SOURCE_DIR}/iwyu/iwyu-extra-map.imp

      COMMENT "Running IWYU")

    add_dependencies(iwyu lammps)

  else()

    message(FATAL_ERROR "To use IWYU you need the include-what-you-use/iwyu executable"

      "and the iwyu-tool/iwyu_tool script installed in your PATH")

  endif()

endif()

set(ENABLE_SANITIZER "none" CACHE STRING "Select a code sanitizer option (none (default), address, leak, thread, undefined)")

mark_as_advanced(ENABLE_SANITIZER)

set(ENABLE_SANITIZER_VALUES none address leak thread undefined)

  endif()

endif()

find_package(JPEG QUIET)

option(WITH_JPEG "Enable JPEG support" ${JPEG_FOUND})

if(WITH_JPEG)

[

  { include: [ "<bits/types/struct_rusage.h>", private, "<sys/resource.h>", public ] },

  { include: [ "<bits/exception.h>", public, "<exception>", public ] },

  { include: [ "@<Eigen/.*>", private, "<Eigen/Eigen>", public ] },

  { include: [ "@<gtest/.*>", private, "\"gtest/gtest.h\"", public ] },

  { include: [ "@<gmock/.*>", private, "\"gmock/gmock.h\"", public ] },

]

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

documentation to find out how to build and link with it.

The majority of OpenMP (threading) support in LAMMPS is provided by the

``USER-OMP`` package; see the :doc:`Speed omp <Speed_omp>` doc page for

details. The ``USER-INTEL`` package also includes OpenMP threading (it

is compatible with ``USER-OMP`` and will usually fall back on styles

from that package, if a ``USER-INTEL`` does not exist) and adds

vectorization support when compiled with compatible compilers, in

particular the Intel compilers on top of OpenMP. Also, the ``KOKKOS``

``USER-OMP`` package; see the :doc:`Speed_omp`

page for details. The ``USER-INTEL`` package also includes OpenMP

threading (it is compatible with ``USER-OMP`` and will usually fall

back on styles from that package, if a ``USER-INTEL`` does not exist)

and adds vectorization support when compiled with compatible compilers,

in particular the Intel compilers on top of OpenMP. Also, the ``KOKKOS``

package can be compiled to include OpenMP threading.

In addition, there are a few commands in LAMMPS that have native OpenMP

   compiler that supports C++11; either as a binary package or through

   compiling from source.

If you build LAMMPS with any :doc:`accelerator packages

<Speed_packages>` included, there may be specific optimization flags

If you build LAMMPS with any :doc:`Speed_packages` included, there may

be specific compiler or linker flags

that are either required or recommended to enable required features and

to achieve optimal performance.  You need to include these in the

CCFLAGS and LINKFLAGS settings above.  For details, see the individual

package doc pages listed on the :doc:`Speed packages <Speed_packages>`

doc page.  Or examine these files in the src/MAKE/OPTIONS directory.

package doc pages listed on the :doc:`Speed_packages`

page.  Or examine these files in the src/MAKE/OPTIONS directory.

They correspond to each of the 5 accelerator packages and their hardware

variants:

.. _debug:

Excluding or removing debug support

Including or removing debug support

-----------------------------------

By default the compilation settings will include the *-g* flag which

tool.  The actual translation is then done via make commands.

.. _rst: https://docutils.readthedocs.io/en/sphinx-docs/user/rst/quickstart.html

.. _sphinx: https://sphinx-doc.org

.. _sphinx: https://www.sphinx-doc.org

Documentation make option

^^^^^^^^^^^^^^^^^^^^^^^^^

----------

.. _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

which use different sanitizer libraries to detect problems in the code

during run-time. They can detect issues like:

 - `memory leaks <https://clang.llvm.org/docs/AddressSanitizer.html>`_

 - `memory leaks <https://clang.llvm.org/docs/AddressSanitizer.html#memory-leak-detection>`_

 - `undefined behavior <https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html>`_

 - `data races <https://clang.llvm.org/docs/ThreadSanitizer.html>`_

Please note that this kind of instrumentation usually comes with a

performance hit (but much less than using tools like `Valgrind

<https://valgrind.org>`_ with a more low level approach).  The to enable

these features additional compiler flags need to be added to the

<https://valgrind.org>`_ with a more low level approach).  To enable

these features, additional compiler flags need to be added to the

compilation and linking stages.  This is done through setting the

``ENABLE_SANITIZER`` variable during configuration. Examples:

The unit testing facility is integrated into the CMake build process

of the LAMMPS source code distribution itself.  It can be enabled by

setting ``-D ENABLE_TESTING=on`` during the CMake configuration step.

It requires the `YAML <http://pyyaml.org/>`_ library and development

It requires the `PyYAML <http://pyyaml.org/>`_ library and development

headers to compile and will download and compile a recent version of the

`Googletest <https://github.com/google/googletest/>`_ C++ test framework

for implementing the tests.