lammps/doc/txt/Build_cmake.txt

"Higher level section"_Build.html - "LAMMPS WWW Site"_lws - "LAMMPS
Documentation"_ld - "LAMMPS Commands"_lc :c

:link(lws,http://lammps.sandia.gov)
:link(ld,Manual.html)
:link(lc,Commands_all.html)

:line

Build LAMMPS with CMake :h3

This page is a short summary of how to use CMake to build LAMMPS.
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"_https://github.com/lammps/lammps/blob/master/cmake/README.md
for how to use CMake to build LAMMPS.  If you are new to CMake it is a
good place to start.

:line

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
Makefile(s). Example:

cd lammps                        # change to the LAMMPS distribution directory
mkdir build; cd build            # create a new directory (folder) for build
cmake \[options ...\] ../cmake     # configuration with (command-line) cmake
make                             # compilation :pre

The cmake command will detect available features, enable selected
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
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
indicated above, producing (by default) an executable called "lmp" and
a library called "liblammps.a" in the "build" folder.  When generating
a build environment for the "Ninja" build tool, the build command would
be "ninja" instead of "make".

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 need to re-compile LAMMPS repeatedly, installation of the
ccache (= Compiler Cache) software may speed up repeated compilation
even more.

After compilation, you may optionally install the LAMMPS executable into
your system with:

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

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
to $\{HOME\}/.local

:line

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.

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
executable.  Links to pages explaining all the options are listed on
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 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 *.h
files auto-generated by make.

You must have CMake version 2.8 or later on your system to build
LAMMPS.  A handful of LAMMPS packages (KOKKOS, LATTE, MSCG) require a
later version.  CMake will print a message telling you if a later
version 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
your build directory and it will re-compile only the files that have
changed.  If you want to change CMake options you can run cmake (or
ccmake or cmake-gui) again from the same build directory and alter
various options; see details below.  Or you can remove the entire build
folder, recreate the directory and start over.

:line

[Command-line version of CMake]:

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

The cmake command takes one required argument, which is the LAMMPS
cmake directory which contains the CMakeLists.txt file.

The argument can be preceeded or followed by various CMake
command-line options.  Several useful ones are:

-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
-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 :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.
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
these forms can be used: yes/no, on/off, 1/0.

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 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
folder '.' instead of the path to the LAMMPS cmake folder as the
required argument to the CMake command. Either way the existing
settings will be inherited unless the CMakeCache.txt file is removed.

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

:line

[Installing CMake]

Check if your machine already has CMake installed:

which cmake             # do you have it?
which cmake3            # version 3 may have this name
cmake --version         # what specific version you have :pre

On clusters or supercomputers which use environment modules to manage
software packages, do this:

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 pre-compiled 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/.