LAMMPS recently acquired support for building with CMake thanks to the efforts of Christoph Junghans (LANL) and Richard Berger (Temple U). One of the key strengths of CMake is that it can generate the necessary build system files of your own personal preference. It also enables using common development IDEs such as Eclipse, Visual Studio, QtCreator, Xcode and many more for LAMMPS development.

CMake can both be used as a command-line (CLI) utility cmake or through one of its GUIs. ccmake is a text-based ui to configure and build CMake projects. cmake-gui is a graphical frontend for running CMake operations that works on Linux desktop environments, Windows and MacOS X.

The following is a tutorial-style introduction in using the CMake system. It should give you the necessary foundation to understand how to do the most common tasks, act as a reference and provide examples of typical use cases.

• Quick Start for the Impatient
• Building LAMMPS using cmake
  • Prerequisites
  • Build directory vs. Source Directory
• Defining and using presets
• Reference
  • Common CMAKE Configuration Options
  • LAMMPS Configuration Options
  • Parallelization and Accelerator Packages
  • Default Packages
  • Other Packages
  • User Packages
  • Package-Specific Configuration Options
    • KSPACE Package
    • MKL
    • FFTW2
    • FFTW3
    • LAPACK
    • PYTHON Package
    • GPU Package
    • VORONOI Package
    • USER-SMD Package
  • Optional Features
    • zlib support
    • JPEG support
    • PNG support
    • GZIP support
    • FFMPEG support
  • Compilers
    • Building with GNU Compilers
    • Building with Intel Compilers
    • Building with LLVM/Clang Compilers
  • Examples

If you want to skip ahead and just run the compilation using cmake, please find a minimal example below. Together with the options reference below, this should get you started.

git clone https://github.com/lammps/lammps.git
mkdir lammps/build
cd lammps/build
cmake [-D OPTION_A=VALUE_A -D OPTION_B=VALUE_B ...] ../cmake
make

This tutorial assumes you are running in a command-line environment using a shell like Bash.

• Linux: any terminal window will work
• MacOS X: launch the Terminal app
• Windows 10: install and run "Bash on Windows" (aka Ubuntu on Windows)

Before we start, please download the latest and greatest version of LAMMPS from GitHub. You can either download it as a tarball or ZIP file, or via git. When you start with a fresh lammps directory, the contents should look like this:

$ ls
bench  doc       lib      potentials  README  tools
cmake  examples  LICENSE  python      src

By using CMake we separate building LAMMPS into multiple phases:

1. Configuration: define which features we want to enable/disable and how it should be compiled
2. Compilation: compile each source file and generate binaries and libraries based on the configuration
3. Installation (Optional): finally we can install the generated binaries on our system

In the GNU Make based build system of LAMMPS, configuration occurs by running special make targets like make yes-MOLECULAR. These targets modify the source directory (src/) directory by copying package files and patching Makefile. In some cases you are force to manually edit Makefiles to add compiler options and/or correct include directory and library paths.

These edits and copy operations are no longer necessary when compiling with CMake. The source directory stays untouched, so you compile LAMMPS in many different variants using the same source code checkout. It enables true out-of-source builds.

When using Cmake, you can compile in any folder outside of the source directory. Any working directory you choose becomes a so-called build directory. All configuration files and compilation results are stored in this folder. We recommend calling it something like build/.

Let's have a look a quick example, where we get the greatest and latest version of LAMMPS from GitHub via git:

git clone https://github.com/lammps/lammps.git

We then create a new build folder and make it our current working directory:

mkdir lammps/build
cd lammps/build

To configure LAMMPS we run cmake inside of this folder. However it requires at least one argument. cmake needs to read the LAMMPS CMakeLists.txt file to know what to do. This file is located in the cmake/ subdirectory of the lammps checkout. To run cmake add the relative or absolute path to the cmake/ directory as first argument.

E.g., if the current working directory is lammps/build you can specify the relative path to lammps/cmake as follows:

cmake ../cmake

You could also specify the absolute path:

cmake /path/to/my/lammps/folder/cmake

Please note: This does NOT compile the code! Running cmake only configures the next build. It generates the necessary files to compile the code. On Unix/Linux it defaults to generating Makefiles. You can also choose other output formats to generate files for Eclipse, Xcode or Visual Studio which are supported on other platorms.

To compile LAMMPS once the Makefiles are generated, simply type make in the build directory.

make

The CMake build exposes a lot of different options. In the old build system some of the package selections were possible by using special make target like make yes-std or make no-lib. Achieving the same result with cmake requires specifying all options manually. This can quickly become a very long command line that is hard to handle. While these could be stored in a simple script file, there is another way of defining "presets" to compile LAMMPS in a certain way.

A preset is a regular CMake script file that can use constructs such as variables, lists and for-loops to manipulate configuration options and create an initial cache. Options must be set with the CACHE and FORCE flag to ensure they are considered even during a second cmake run.

Such a file can then be passed to cmake via the -C flag. Several examples of presets can be found in the cmake/presets folder.

# build LAMMPS with all "standard" packages which don't use libraries and enable GPU package
mkdir build
cd build
cmake -C ../cmake/presets/std_nolib.cmake -D PKG_GPU=on ../cmake

TODO static vs dynamic linking

TODO

The GPU package builds a support library which can either use OpenCL or CUDA as target API.

TODO

Requires a Eigen3 installation

(requires zlib support)

requires gzip to be in your PATH

requires ffmpeg to be in your PATH

By default, cmake will use your environment C/C++/Fortran compilers for a build. It uses the CC, CXX and FC environment variables to detect which compilers should be used. However, these values will be cached after the first run of cmake. Subsequent runs of cmake will ignore changes in these environment variables. To ensure the correct values are used you avoid the cache by setting the CMAKE_C_COMPILER, CMAKE_CXX_COMPILER, CMAKE_Fortran_COMPILER options directly.

cmake -D CMAKE_C_COMPILER=gcc -D CMAKE_CXX_COMPILER=g++ -D CMAKE_Fortran_COMPILER=gfortran ../cmake

cmake -D CMAKE_C_COMPILER=icc -D CMAKE_CXX_COMPILER=icpc -D CMAKE_Fortran_COMPILER=ifort ../cmake

cmake -D CMAKE_C_COMPILER=clang -D CMAKE_CXX_COMPILER=clang++ -D CMAKE_Fortran_COMPILER=flang ../cmake