more updates to Build doc page

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

                          # no default value :pre

The executable CMake creates (after running make) is lmp_name.  If the

LAMMPS_MACHINE variable is not specified, the executable is just lmp.

Using BUILD_MPI=no will produce a serial executable.

The executable created by CMake (after running make) is lmp_name.  If

the LAMMPS_MACHINE variable is not specified, the executable is just

lmp.  Using BUILD_MPI=no will produce a serial executable.

[Traditional make]:

cd lammps/src

make mpi                # parallel build, produces lmp_mpi using Makefile.mpi

make serial             # serial build, produces lmp_serial using Makefile/serial

make mybox :pre         # uses Makefile.mybox, produces lmp_mybox :pre

make mybox :pre         # uses Makefile.mybox to produce lmp_mybox :pre

Serial build (see src/MAKE/Makefile.serial):

[CMake and make info]:

If you are installing MPI yourself, we recommend Argonne's MPICH2 or

OpenMPI.  MPICH can be downloaded from the "Argonne MPI

site"_http://www.mcs.anl.gov/research/projects/mpich2/.  OpenMPI can

be downloaded from the "OpenMPI site"_http://www.open-mpi.org.  Other

MPI packages should also work.  If you are running on a large parallel

machine, your system admins or the vendor should have already

installed a version of MPI, which is likely to be faster than a

self-installed MPICH or OpenMPI, so find out how to build and link

with it.

If you are installing MPI yourself, we recommend MPICH2 from Argonne

National Laboratory or OpenMPI.  MPICH can be downloaded from the

"Argonne MPI site"_http://www.mcs.anl.gov/research/projects/mpich2/.

OpenMPI can be downloaded from the "OpenMPI

site"_http://www.open-mpi.org.  Other MPI packages should also work.

If you are running on a large parallel machine, your system admins or

the vendor should have already installed a version of MPI, which is

likely to be faster than a self-installed MPICH or OpenMPI, so 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 "Speed omp"_Speed_omp.html doc page for

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

support.  These are commands in the MPIIO, SNAP, USER-DIFFRACTION, and

USER-DPD packages.  In addition some commands support OpenMP threading

not directly, but through the libraries they are interfacing to:

e.g. LATTE and USER-COLVARS. See the "Packages

details"_Packages_details.html 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, then you can use these packages

and turn on their native OpenMP support at run time, by first setting

the OMP_NUM_THREADS environment variable.

For the conventional makefiles, the CCFLAGS and LINKFLAGS variables

need to include the compiler flag, that enables OpenMP. For GNU

compilers, this flag is -fopenmp, for (recent) Intel compilers,

it is -qopenmp. Please refer to the documentation of your compiler,

if you are using a different compiler to compile LAMMPS.

USER-DPD packages.  In addition some packages support OpenMP threading

indirectly through the libraries they interface to: e.g. LATTE and

USER-COLVARS.  See the "Packages details"_Packages_details.html 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

variable before you launch LAMMPS.

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,

please refer to its documentation.

:line

-D CMAKE_C_FlAGS=string               # flags to use with C compiler

-D CMAKE_Fortran_FlAGS=string         # flags to use with Fortran compiler :pre

By default CMake will use a compiler it finds and it will use

By default CMake will use a compiler it finds and it will add

optimization flags appropriate to that compiler and any "accelerator

packages"_Speed_packages.html you have included in the build.

cmake ../cmake -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_Fortran_COMPILER=flang :pre

NOTE: When the cmake command completes, it prints info to the screen

as to what compilers it is using, and what flags will be used in the

as to which compilers it is using, and what flags will be used in the

compilation.  Note that if the top-level compiler is mpicxx, it is

simply a wrapper on a real compiler.  The low-level compiler info is

also in the output.  You should check to insure you are using the

compiler and optimization flags that are the ones you want.

also in the Cmake output.  You should check to insure you are using

the compiler and optimization flags are the ones you want.

[Makefile.machine settings]:

Makefile.kokkos_omp            # KOKKOS package for CPUs (OpenMP)

Makefile.kokkos_phi            # KOKKOS package for KNLs (OpenMP) :pre

NOTE: When you build LAMMPS for the first time, a long list of *.d

files will be printed out rapidly.  This is not an error; it is the

Makefile doing its normal creation of dependencies.

:line

Build LAMMPS as an executable or a library :h3,link(exe)

LAMMPS can be built as either an executable or as a static or shared

library.  The library can be called from another application or a

scripting language.  See the "Howto couple"_Howto_couple.html doc page

for more info on coupling LAMMPS to other codes.  See the

library.  The LAMMPS library can be called from another application or

a scripting language.  See the "Howto couple"_Howto_couple.html doc

page for more info on coupling LAMMPS to other codes.  See the

"Python"_Python doc page for more info on wrapping and running LAMMPS

from Python.

from Python via its library interface.

[CMake variables]:

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

static library named liblammps.so.

shared library named liblammps.so.

[Traditional make]:

make mode=lib machine      # build LAMMPS static lib liblammps_machine.a

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

The two library builds also create generic links liblammps.a and

liblammps.so which point to the liblammps_machine files.

The two library builds also create generic soft links, named

liblammps.a and liblammps.so, which point to the liblammps_machine

files.

[CMake and make info]:

the auxiliary libraries it depends on must also exist as shared

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

lib/packages, since they are always built as shared libraries using

the -fPIC switch.  However, if a library like MPI or FFTW does not

exist as a shared library, the shared library build will generate an

error.  This means you will need to install a shared library version

of the auxiliary library.  The build instructions for the library

should tell you how to do this.

the lib/packages directroy, since they are always built as shared

libraries using the -fPIC switch.  However, if a library like MPI or

FFTW does not exist as a shared library, the shared library build will

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

library version of the auxiliary library.  The build instructions for

the library should tell you how to do this.

As an example, here is how to build and install the "MPICH

library"_mpich, a popular open-source version of MPI, distributed by

Argonne National Labs, as a shared library in the default

Argonne National Lab, as a shared library in the default

/usr/local/lib location:

:link(mpich,http://www-unix.mcs.anl.gov/mpi)

-D BUILD_DOC=value       # yes or no (default) :pre

This will create the HTML doc pages within the CMake build dir.  The

reason to do this is if you want to "install" LAMMPS on a system after

the CMake build, and include the doc pages in the install.

This will create the HTML doc pages within the CMake build directory.

The reason to do this is if you want to "install" LAMMPS on a system

after the CMake build via "make install", and include the doc pages in

the install.

[Traditional make]:

make pdf        # single Manual.pdf file :pre

This will create a lammps/doc/html dir with the HTML doc pages so that

you can browse them locally on your system.  Type "make" from the the

you can browse them locally on your system.  Type "make" from the

lammps/doc dir to see other options.

:line

After building LAMMPS, you may wish to copy the LAMMPS executable of

library, along with other LAMMPS files (library header, doc files) to

a globally visible place on your system, for others to access.  Note

that you may need super-user priveleges (e.g. sudo) if the place you

want to copy files to is protected.

that you may need super-user priveleges (e.g. sudo) if the directory

you want to copy files to is protected.

[CMake variable]:

[Traditional make]:

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

wish to do this you will need to build, then manually copy the

desired LAMMPS files to the appopriate system directories.

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

copy the desired LAMMPS files to the appropriate system directories.

Build LAMMPS with CMake :h3

This page is a short summary of how to use CMake to build LAMMPS.

Specific details on CMake variables that enable LAMMPS build options

Details on CMake variables that enable specific LAMMPS build options

are given on the pages linked to from the "Build"_Build.html doc page.

Richard Berger (Temple U) has also written a more comprehensive guide

"Bulding LAMMPS using

CMake"_https://github.com/lammps/lammps/blob/master/cmake/README.md

:line

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

to create a build environment in a new folder.  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 Makefile(s). Example:

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

Makefile(s). Example:

cd lammps                        # change to the folder with the LAMMPS sources

mkdir build; cd build            # create a new dir for build          

cd lammps                        # change to the LAMMPS distribution directory

mkdir build; cd build            # create a new directory (folder) for build       

cmake ../cmake \[options ...\]   # configuration with (command-line) cmake

make                             # compilation :pre

"build" folder.

If your machine has multiple CPU cores (most do these days), using a

command like "make -jN" (with N being the number of available local CPU

cores) can be much faster.  If you plan to do development on LAMMPS or

may need to recompile LAMMPS repeatedly, the installation of the ccache

(= Compiler Cache) software may speed up compilation even more.

command like "make -jN" (with N being the number of available local

CPU cores) can be much faster.  If you plan to do development on

LAMMPS or need to recompile LAMMPS repeatedly, installation of the

ccache (= Compiler Cache) software may speed up compilation even more.

After compilation, you optionally, can copy the LAMMPS executable and

After compilation, you can optionally copy the LAMMPS executable and

library into your system folders (by default under /usr/local) with:

make install    # optional, copy LAMMPS executable & library elsewhere :pre

the "Build"_Build.html doc page.

You must perform the CMake build system generation and compilation in

a new directory you create.  It can be anywhere on your local machine;

in the following, we will assume, that you are building in the folder

"lammps/build".  You can perform separate builds independently at the

same time and with different options, for as long as you put each of

them into a separate directory. There can be as many build directories

as you like. All the auxiliary files created by the build (executable,

object files, log files, etc) are stored in that directory or

sub-directories within it that CMake creates.

NOTE: To perform a CMake build, no packages may be installed or a build

attempted in the LAMMPS src folder using the "conventional build

procedure"_Build_make.html.  CMake detects if this is the case and

a new directory you create.  It can be anywhere on your local machine.

In these Build pages we assume that you are building in a directory

called "lammps/build".  You can perform separate builds independently

with different options, so long as you perform each of them in a

separate directory you create.  All the auxiliary files created by one

build process (executable, object files, log files, etc) are stored in

this directory or sub-directories within it that CMake creates.

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 "perform a conventional LAMMPS

build"_Build_make.html.  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

auto-generated *.h files.

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

files auto-generated by make.

You must have CMake version 2.8 or later on your system to build LAMMPS.

If you include the GPU or KOKKOS packages, CMake version 3.2 or later is

required.  Installation instructions for CMake are below.

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

LAMMPS.  If you include the GPU or KOKKOS packages, CMake version 3.2

or later is required.  Installation instructions for CMake are below.

After the initial build, if you edit LAMMPS source files, or add your

own new files to the source directory, you can just re-type make from

-D CMAKE_BUILD_TYPE=type      # type = Release or Debug

-G output                     # style of output CMake generates

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

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

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

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

described on the pages linked to from the "Build"_Build.html doc page.

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 CMake generates a Makefile by default to perform the

LAMMPS build.  Alternate forms of build info can be generated via the 

-G switch, e.g. Visual Studio on a Windows machine, Xcode on MacOS or

KDevelop on Linux.  Type "cmake --help" to see the "Generator" styles

of output your system supports.

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

perform the LAMMPS build.  Alternate forms of build info can be

generated via the -G switch, e.g. Visual Studio on a Windows machine,

Xcode on MacOS, or KDevelop on Linux.  Type "cmake --help" to see the

"Generator" styles of output your system supports.

NOTE: When CMake runs, it prints configuration info to the screen.

You should review this to verify all the features you requested were

enabled, including packages.  You can also see what compilers and

compile options will be used for the build.  Any errors will also be

flagged, e.g. mis-typed variable names or variable values.

compile options will be used for the build.  Any errors in CMake

variable syntax will also be flagged, e.g. mis-typed variable names or

variable values.

CMake creates a CMakeCache.txt file when it runs.  This stores all the

settings, so that when running CMake again you can use the current

If you later want to change a setting you can rerun cmake in the build

directory with different setting. Please note that some automatically

detected variables will not change their value. In these cases it is

usually better to start with a fresh build directory.

detected variables will not change their value when you rerun cmake.

In these cases it is usually better to first remove all the

files/directories in the build directory, or start with a fresh build

directory.

:line

[Curses version (terminal-style menu) of CMake]:

ccmake ../cmake :pre

You initiate the configuration and build environment generation steps

separately. For the first you have to type [c], for the second you have

to type [g]. You may need to type [c] multiple times, and may be

required to edit some of the entries of CMake configuration variables in

between.  Please see the "ccmake

separately. For the first you have to type [c], for the second you

have to type [g]. You may need to type [c] multiple times, and may be

required to edit some of the entries of CMake configuration variables

in between.  Please see the "ccmake

manual"_https://cmake.org/cmake/help/latest/manual/ccmake.1.html for

more information.

:line

[GUI version of CMake]:

cmake-gui ../cmake :pre

You initiate the configuration and build environment generation steps

separately. For the first you have to click on the [Configure] button,

for the second you have to click on the [Generate] button.  You may need

to click on [Configure] multiple times, and may be required to edit some

of the entries of CMake configuration variables in between.  Please see

the "cmake-gui

manual"_https://cmake.org/cmake/help/latest/manual/cmake-gui.1.html for

more information.

for the second you have to click on the [Generate] button.  You may

need to click on [Configure] multiple times, and may be required to

edit some of the entries of CMake configuration variables in between.

Please see the "cmake-gui

manual"_https://cmake.org/cmake/help/latest/manual/cmake-gui.1.html

for more information.

:line

On clusters or supercomputers which use environment modules to manage

software packages, do this:

module list            # is a cmake module is already loaded

module list            # is a cmake module already loaded?

module avail           # is a cmake module available?

module load cmake3     # load cmake module with appropriate name :pre

Most Linux distributions offer precompiled cmake packages through their

package management system. If you do not have CMake or a new enough

version, you can download the latest version at

"https://cmake.org/download/"_https://cmake.org/download/.  Instructions

on how to install it on various platforms can be found

"here"_https://cmake.org/install/.

Most Linux distributions offer precompiled cmake packages through

their package management system. If you do not have CMake or a new

enough version, you can download the latest version at

"https://cmake.org/download/"_https://cmake.org/download/.

Instructions on how to install it on various platforms can be found

"on this page"_https://cmake.org/install/.

Build LAMMPS with make :h3

Building LAMMPS with traditional makefiles requires, that you have a

Makefile."machine" file in the src/MAKE, src/MAKE/MACHINES,

src/MAKE/OPTIONS, or src/MAKE/MINE directory, which is appropriate

for your system (see below).  It can list various options for

customizing your LAMMPS build with a number of global compilation

options and features.  To include LAMMPS packages (i.e. optional

commands and styles) you must install them first, as discussed on

the "Build package"_Build_package.html doc page.  If the packages

use provided or external libraries, you must build those libraries

before building LAMMPS.  Building "LAMMPS with CMake"_Build_cmake.html

can automate all of this for many types of machines, especially

Building LAMMPS with traditional makefiles requires that you have a

Makefile."machine" file appropriate for your system in the src/MAKE,

src/MAKE/MACHINES, src/MAKE/OPTIONS, or src/MAKE/MINE directory (see

below).  It can include various options for customizing your LAMMPS

build with a number of global compilation options and features.

To include LAMMPS packages (i.e. optional commands and styles) you

must install them first, as discussed on the "Build

package"_Build_package.html doc page.  If the packages require

provided or external libraries, you must build those libraries before

building LAMMPS.  Building "LAMMPS with CMake"_Build_cmake.html can

automate all of this for many types of machines, especially

workstations, desktops and laptops, so we suggest you try it first.

These commands perform a default LAMMPS build, producing the LAMMPS

make            # see a variety of make options :pre

This initial compilation can take a long time, since LAMMPS is a large

project with many features. If your machine has multiple CPU cores (most

do these days), using a command like "make -jN mpi" (with N being to the

number of available local CPU cores) can be much faster. If you plan to

do development on LAMMPS or may need to recompile LAMMPS repeatedly, the

project with many features. If your machine has multiple CPU cores

(most do these days), using a command like "make -jN mpi" (with N =

the number of available CPU cores) can be much faster.  If you plan to

do development on LAMMPS or need to recompile LAMMPS repeatedly, the

installation of the ccache (= Compiler Cache) software may speed up

compilation even more.

After the initial build, whenever you edit LAMMPS source files, or 

add or remove new files to the source directory (e.g. by installing or

uninstalling packages), you must recompile and relink the LAMMPS executable

with the same command line, but the makefiles will make certain, that

only files that need to be recompiled will be compiled (because they

were changed or depend on files, that were changed). 

After the initial build, whenever you edit LAMMPS source files, or add

or remove new files to the source directory (e.g. by installing or

uninstalling packages), you must recompile and relink the LAMMPS

executable with the same "make" command.  This makefiles dependencies

should insure that only the subset of files that need to be are

recompiled.

NOTE: When you build LAMMPS for the first time, a long list of *.d

files will be printed out rapidly.  This is not an error; it is the

Makefile doing its normal creation of dependencies.

:line

MINE         # customized Makefiles you create (you may need to create this folder) :pre

Typing "make" lists all the available Makefile.machine files.  A file

with the same name can appear in multiple dirs (not a good idea).  The

order the dirs are searched is as follows: src/MAKE/MINE, src/MAKE,

src/MAKE/OPTIONS, src/MAKE/MACHINES.  This gives preference to a

customized file you put in src/MAKE/MINE.

with the same name can appear in multiple folders (not a good idea).

The order the dirs are searched is as follows: src/MAKE/MINE,

src/MAKE, src/MAKE/OPTIONS, src/MAKE/MACHINES.  This gives preference

to a customized file you put in src/MAKE/MINE.

Makefiles you may wish to try include these (some require a package

first be installed).  Many of these include specific compiler flags

for optimized performance.  Please note, however, that most of these

customized machine Makefile are contributed and since both, compilers

and also OS configs, as well as LAMMPS itself keep changing all the

time, some of these settings and recommendations may be outdated:

for optimized performance.  Please note, however, that some of these

customized machine Makefile are contributed by users.  Since both

compilers, OS configs, and LAMMPS itself keep changing, their settings

may become outdated:

make mac             # build serial LAMMPS on a Mac

make mac_mpi         # build parallel LAMMPS on a Mac