Skip to content
Snippets Groups Projects
Select Git revision
  • mui-unknown
  • mui-sequence
  • mui
  • compute_momentum
  • master default protected
5 results
Blame Permalink
Build_cmake.txt 8.33 KiB 
"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.
Specific details on CMake variables that enable 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
for how to use CMake to build LAMMPS.  If you are new to CMake it is a
good place to start:

"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:

cd lammps                        # change to the folder with the LAMMPS sources
mkdir build; cd build            # create a new dir for build          
cmake ../cmake \[options ...\]   # 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.  The make
command will then compile and link LAMMPS, producing (by default) an
executable called "lmp" and a library called "liblammps.a" in the
"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.

After compilation, you optionally, can 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

:line

There are 3 variants of CMake: a command-line verison (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 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
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.

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

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

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. In these cases it is
usually better to start with a fresh build directory.

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

[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 is 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/.