219 lines
9.5 KiB
ReStructuredText
219 lines
9.5 KiB
ReStructuredText
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 :doc:`Build <Build>` 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.
|
|
|
|
----------
|
|
|
|
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:
|
|
|
|
.. code-block:: bash
|
|
|
|
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:
|
|
|
|
.. code-block:: bash
|
|
|
|
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 :doc:`Build <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 :doc:`perform a conventional LAMMPS build <Build_make>`. 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 3.10 or later on your system to build
|
|
LAMMPS. 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**\ :
|
|
|
|
.. code-block:: bash
|
|
|
|
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 prefixed or followed by various CMake
|
|
command-line options. Several useful ones are:
|
|
|
|
.. code-block:: bash
|
|
|
|
-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 :doc:`Build <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**\ :
|
|
|
|
.. code-block:: bash
|
|
|
|
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 <https://cmake.org/cmake/help/latest/manual/ccmake.1.html>`_ for
|
|
more information.
|
|
|
|
----------
|
|
|
|
**GUI version of CMake**\ :
|
|
|
|
.. code-block:: bash
|
|
|
|
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 <https://cmake.org/cmake/help/latest/manual/cmake-gui.1.html>`_
|
|
for more information.
|
|
|
|
----------
|
|
|
|
**Installing CMake**
|
|
|
|
Check if your machine already has CMake installed:
|
|
|
|
.. code-block:: bash
|
|
|
|
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:
|
|
|
|
.. code-block:: bash
|
|
|
|
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/ <https://cmake.org/download/>`_.
|
|
Instructions on how to install it on various platforms can be found
|
|
`on this page <https://cmake.org/install/>`_.
|