3.1. Build LAMMPS with CMake
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 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.
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
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
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
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 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. 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.
Command-line version of CMake:
cmake [options ...] /path/to/lammps/cmake # build from any dir
cmake [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.
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
All the LAMMPS-specific -D variables that a LAMMPS build supports are described on the pages linked to from the 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 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.
Curses version (terminal-style menu) of CMake:
ccmake ../cmake
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 for more information.
GUI version of CMake:
cmake-gui ../cmake
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 for more information.
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
On clusters or supercomputers which use environment modules to manage software packages, do this:
module list # is a module for cmake already loaded?
module avail # is a module for cmake available?
module load cmake3 # load cmake module with appropriate name
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/. Instructions on how to install it on various platforms can be found on this page.