Merge pull request #1938 from akohlmey/doc-remove-backslash-underscore

   -D LAMMPS_MACHINE=name    # name = mpi, serial, mybox, titan, laptop, etc

                             # no default value

The executable created by CMake (after running make) is named *lmp* unless

the LAMMPS\_MACHINE option is set.  When setting `LAMMPS_MACHINE=name`

the executable will be named *lmp\_name*\.  Using `BUILD\_MPI=no` will

The executable created by CMake (after running make) is named ``lmp`` unless

the LAMMPS_MACHINE option is set.  When setting ``LAMMPS_MACHINE=name``

the executable will be called ``lmp_name``.  Using ``BUILD_MPI=no`` will

enforce building a serial executable using the MPI STUBS library.

**Traditional make**\ :

The build with traditional makefiles has to be done inside the source folder `src`.

The build with traditional makefiles has to be done inside the source folder ``src``.

.. code-block:: bash

   make mybox              # uses Makefile.mybox to produce lmp_mybox

Any "make machine" command will look up the make settings from a file

Makefile.machine, create a folder Obj\_machine with all objects and

generated files and an executable called *lmp\_machine*\ .  The standard

parallel build with `make mpi` assumes a standard MPI installation with

Makefile.machine, create a folder Obj_machine with all objects and

generated files and an executable called ``lmp_machine``\ .  The standard

parallel build with ``make mpi`` assumes a standard MPI installation with

MPI compiler wrappers where all necessary compiler and linker flags to

get access and link with the suitable MPI headers and libraries are set

by the wrapper programs.  For other cases or the serial build, you have

to adjust the make file variables MPI\_INC, MPI\_PATH, MPI\_LIB as well

as CC and LINK.  To enable OpenMP threading usually a compiler specific

flag needs to be added to the compile and link commands.  For the GNU

compilers, this is *-fopenmp*\ , which can be added to the CC and LINK

makefile variables.

to adjust the make file variables ``MPI_INC``, ``MPI_PATH``, ``MPI_LIB``

as well as ``CC`` and ``LINK``\ .  To enable OpenMP threading usually

a compiler specific flag needs to be added to the compile and link

commands.  For the GNU compilers, this is ``-fopenmp``\ , which can be

added to the ``CC`` and ``LINK`` makefile variables.

For the serial build the following make variables are set (see src/MAKE/Makefile.serial):

   MPI_LIB =       -lmpi_stubs

You also need to build the STUBS library for your platform before making

LAMMPS itself.  A "make serial" build does this for you automatically,

otherwise, type "make mpi-stubs" from the src directory, or "make" from

LAMMPS itself.  A ``make serial`` build does this for you automatically,

otherwise, type ``make mpi-stubs`` from the src directory, or ``make`` from

the src/STUBS dir.  If the build fails, you will need to edit the

STUBS/Makefile for your platform.  The stubs library does not provide

MPI/IO functions required by some LAMMPS packages, e.g. MPIIO or USER-LB,

.. note::

   The file STUBS/mpi.c provides a CPU timer function called

   MPI\_Wtime() that calls gettimeofday() .  If your operating system

   The file ``src/STUBS/mpi.c`` provides a CPU timer function called

   MPI_Wtime() that calls gettimeofday() .  If your operating system

   does not support gettimeofday() , you will need to insert code to

   call another timer.  Note that the ANSI-standard function clock()

   rolls over after an hour or so, and is therefore insufficient for

<Packages_details>` doc page for more info on these packages and the doc

pages for their respective commands for OpenMP threading info.

For CMake, if you use BUILD\_OMP=yes, you can use these packages and

turn on their native OpenMP support and turn on their native OpenMP

support at run time, by setting the OMP\_NUM\_THREADS environment

For CMake, if you use ``BUILD_OMP=yes``, you can use these packages

and turn on their native OpenMP support and turn on their native OpenMP

support at run time, by setting the ``OMP_NUM_THREADS`` environment

variable before you launch LAMMPS.

For building via conventional make, the CCFLAGS and LINKFLAGS

For building via conventional make, the ``CCFLAGS`` and ``LINKFLAGS``

variables in Makefile.machine need to include the compiler flag that

enables OpenMP. For GNU compilers it is -fopenmp.  For (recent) Intel

compilers it is -qopenmp.  If you are using a different compiler,

enables OpenMP. For GNU compilers it is ``-fopenmp``\ .  For (recent) Intel

compilers it is ``-qopenmp``\ .  If you are using a different compiler,

please refer to its documentation.

.. _default-none-issues:

**OpenMP Compiler compatibility info**\ :

Some compilers do not fully support the 'default(none)' directive

Some compilers do not fully support the ``default(none)`` directive

and others (e.g. GCC version 9 and beyond) may implement OpenMP 4.0

semantics, which are incompatible with the OpenMP 3.1 directives used

semantics, which are incompatible with the OpenMP 3.1 semantics used

in LAMMPS (for maximal compatibility with compiler versions in use).

In those case, all 'default(none)' directives (which aid in detecting

incorrect and unwanted sharing) can be replaced with 'default(shared)'

while dropping all 'shared()' directives. The script

'src/USER-OMP/hack\_openmp\_for\_pgi\_gcc9.sh' can be used to automate

In those case, all ``default(none)`` directives (which aid in detecting

incorrect and unwanted sharing) can be replaced with ``default(shared)``

while dropping all ``shared()`` directives. The script

'src/USER-OMP/hack_openmp_for_pgi_gcc9.sh' can be used to automate

this conversion.

----------

build.

You can tell CMake to look for a specific compiler with these variable

settings.  Likewise you can specify the FLAGS variables if you want to

experiment with alternate optimization flags.  You should specify all

3 compilers, so that the small number of LAMMPS source files written

in C or Fortran are built with a compiler consistent with the one used

for all the C++ files:

settings.  Likewise you can specify the corresponding ``CMAKE_*_FLAGS``

variables if you want to experiment with alternate optimization flags.

You should specify all 3 compilers, so that the small number of LAMMPS

source files written in C or Fortran are built with a compiler consistent

with the one used for all the C++ files:

.. code-block:: bash

   -D LAMMPS_LIB_SUFFIX=name    # name = mpi, serial, mybox, titan, laptop, etc

                                # no default value

Setting BUILD\_EXE=no will not produce an executable.  Setting

BUILD\_LIB=yes will produce a static library named *liblammps.a*\ .

Setting both BUILD\_LIB=yes and BUILD\_SHARED\_LIBS=yes will produce a

shared library named *liblammps.so* instead. If LAMMPS\_LIB\_SUFFIX is

set to *name* in addition, the name of the generated libraries will be

changed to either *liblammps\_name.a* or *liblammps\_name.so*\ ,

respectively.

Setting ``BUILD_EXE=no`` will not produce an executable.  Setting

``BUILD_LIB=yes`` will produce a static library named ``liblammps.a``\ .

Setting both ``BUILD_LIB=yes`` and ``BUILD_SHARED_LIBS=yes`` will produce a

shared library named ``liblammps.so`` instead. If ``LAMMPS_LIB_SUFFIX=name``

is set in addition, the name of the generated libraries will be changed to

either ``liblammps_name.a`` or ``liblammps_name.so``\ , respectively.

**Traditional make**\ :

With the traditional makefile based build process, the choice of

the generated executable or library depends on the "mode" setting.

Several options are available and "mode=exe" is the default.

Several options are available and ``mode=exe`` is the default.

.. code-block:: bash

   make mode=shlib machine    # build LAMMPS shared lib liblammps_machine.so

   make mode=shexe machine    # same as "mode=exe" but uses objects from "mode=shlib"

The two "exe" builds will generate and executable *lmp\_machine*\ ,

while the two library builds will create a file *liblammps\_machine.a*

or *liblammps\_machine.so*\ . They will also create generic soft links,

named *liblammps.a* and *liblammps.so*\ , which point to the specific

*liblammps\_machine.a/so* files.

The two "exe" builds will generate and executable ``lmp_machine``\ ,

while the two library builds will create a file ``liblammps_machine.a``

or ``liblammps_machine.so``\ . They will also create generic soft links,

named ``liblammps.a`` and ``liblammps.so``\ , which point to the specific

``liblammps_machine.a/so`` files.

**CMake and make info**\ :

libraries.  This will be the case for libraries included with LAMMPS,

such as the dummy MPI library in src/STUBS or any package libraries in

the lib/packages directory, since they are always built in a shared

library compatible way using the -fPIC switch.  However, if a library

library compatible way using the ``-fPIC`` switch.  However, if a library

like MPI or FFTW does not exist as a shared library, the shared library

build may generate an error.  This means you will need to install a

shared library version of the auxiliary library.  The build instructions

   make

   make install

You may need to use "sudo make install" in place of the last line if you

do not have write privileges for /usr/local/lib.  The end result should

be the file /usr/local/lib/libmpich.so.  On many Linux installations the

folder "${HOME}/.local" is an alternative to using /usr/local and does

You may need to use ``sudo make install`` in place of the last line if you

do not have write privileges for ``/usr/local/lib``.  The end result should

be the file ``/usr/local/lib/libmpich.so``.  On many Linux installations the

folder ``${HOME}/.local`` is an alternative to using ``/usr/local`` and does

not require superuser or sudo access.  In that case the configuration

step becomes:

the :doc:`CMake build directory <Build_cmake>`.  The reason for this

option is to include the installation of the HTML manual pages into

the "install" step when installing LAMMPS after the CMake build via

"make install".

``make install``.

.. code-block:: bash

**Traditional make**\ :

There is no "install" option in the src/Makefile for LAMMPS.  If you

wish to do this you will need to first build LAMMPS, then manually

There is no "install" option in the ``src/Makefile`` for LAMMPS.  If

you wish to do this you will need to first build LAMMPS, then manually

copy the desired LAMMPS files to the appropriate system directories.

Building LAMMPS with CMake is a two-step process.  First you use CMake

to create a build environment in a new directory.  On Linux systems,

this will be based on makefiles for use with make.  Then you use the

make command to build LAMMPS, which uses the created

this will be by default based on Unix-style makefiles for use with make.

Then you use the *make* command to build LAMMPS, which uses the created

Makefile(s). Example:

.. code-block:: bash

packages and options, and will generate the build environment.  By default

this build environment will be created for "Unix Makefiles" on most

platforms and particularly on Linux.  However, alternate build tools

(e.g. Ninja) and support files for Integrated Development Environments

(IDE) like Eclipse, CodeBlocks, or Kate can be generated, too. This is

(e.g. Ninja) and project files for Integrated Development Environments

(IDEs) like Eclipse, CodeBlocks, or Kate can be generated, too. This is

selected via the "-G" command line flag. For the rest of the documentation

we will assume that the build environment is generated for makefiles

and thus the make command will be used to compile and link LAMMPS as

This will install the lammps executable and library (if requested), some

tools (if configured) and additional files like library API headers,

manpages, potential and force field files. The location of the installation

tree is set by the CMake variable "CMAKE\_INSTALL\_PREFIX" which defaults

tree is set by the CMake variable "CMAKE_INSTALL_PREFIX" which defaults

to ${HOME}/.local

----------

There are 3 variants of CMake: a command-line version (cmake), a text mode

UI version (ccmake), and a graphical GUI version (cmake-GUI).  You can use

any of them interchangeably to configure and create the LAMMPS build

environment.  On Linux all the versions produce a Makefile as their

output.  See more details on each below.

There are 3 variants of the CMake command itself: a command-line version

(*cmake* or *cmake3*), a text mode UI version (*ccmake* or *ccmake3*),

and a graphical GUI version (*cmake-gui*).  You can use any of them

interchangeably to configure and create the LAMMPS build environment.

On Linux all the versions produce a Makefile as their output by default.

See more details on each below.

You can specify a variety of options with any of the 3 versions, which

affect how the build is performed and what is included in the LAMMPS

.. note::

   To perform a CMake build, no packages can be installed or a

   build been previously attempted in the LAMMPS src directory by using

   "make" commands to :doc:`perform a conventional LAMMPS build <Build_make>`.  CMake detects if this is the case and

   generates an error, telling you to type "make no-all purge" in the src

   directory to un-install all packages.  The purge removes all the \*.h

   files auto-generated by make.

   To perform a CMake build, no packages can be installed or a build

   been previously attempted in the LAMMPS src directory by using "make"

   commands to :doc:`perform a conventional LAMMPS build <Build_make>`.

   CMake detects if this is the case and generates an error, telling you

   to type "make no-all purge" in the src directory to un-install all

   packages.  The purge removes all the \*.h files auto-generated by

   make.

You must have CMake version 3.10 or later on your system to build

LAMMPS.  Installation instructions for CMake are below.

   cmake  [options ...] /path/to/lammps/cmake  # build from any dir

   cmake  [options ...] ../cmake               # build from lammps/build

   cmake3 [options ...] ../cmake               # build from lammps/build

The cmake command takes one required argument, which is the LAMMPS

cmake directory which contains the CMakeLists.txt file.

   -D CMAKE_INSTALL_PREFIX=path  # where to install LAMMPS executable/lib if desired

   -D CMAKE_BUILD_TYPE=type      # type = RelWithDebInfo (default), Release, MinSizeRel, or Debug

   -G output                     # style of output CMake generates

   -G output                     # style of output CMake generates (e.g. "Unix Makefiles" or "Ninja")

   -D CMAKE_MAKE_PROGRAM=builder # name of the builder executable (e.g. set to "gmake" instead of "make")

   -DVARIABLE=value              # setting for a LAMMPS feature to enable

   -D VARIABLE=value             # ditto, but cannot come after CMakeLists.txt dir

   -C path/to/preset/file        # load some CMake settings before configuring

All the LAMMPS-specific -D variables that a LAMMPS build supports are

described on the pages linked to from the :doc:`Build <Build>` doc page.

All of these variable names are upper-case and their values are

lower-case, e.g. -D LAMMPS\_SIZES=smallbig.  For boolean values, any of

lower-case, e.g. -D LAMMPS_SIZES=smallbig.  For boolean values, any of

these forms can be used: yes/no, on/off, 1/0.

On Unix/Linux machines, CMake generates a Makefile by default to