574e4067dc
This is the first step for moving the documentation format from *.txt to the *.rst format. In the last years we've been automatically converting txt files from Steve's markup into RST to generate the documentation pages via Sphinx. The decision has now been made to fully migrate to RST and avoid the conversion in the future. This will enable us to fully use RST and Sphinx to improve the documentation. For the intermediate period, while there are still pending PRs with documentation changes, we will keep both source files and update the RST files accordingly.
246 lines
9.7 KiB
ReStructuredText
246 lines
9.7 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:
|
|
|
|
|
|
.. parsed-literal::
|
|
|
|
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:
|
|
|
|
|
|
.. parsed-literal::
|
|
|
|
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 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**\ :
|
|
|
|
|
|
.. parsed-literal::
|
|
|
|
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:
|
|
|
|
|
|
.. parsed-literal::
|
|
|
|
-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**\ :
|
|
|
|
|
|
.. parsed-literal::
|
|
|
|
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**\ :
|
|
|
|
|
|
.. parsed-literal::
|
|
|
|
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:
|
|
|
|
|
|
.. parsed-literal::
|
|
|
|
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:
|
|
|
|
|
|
.. parsed-literal::
|
|
|
|
module list # is a cmake module already loaded?
|
|
module avail # is a cmake module 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/>`_.
|
|
|
|
|
|
.. _lws: http://lammps.sandia.gov
|
|
.. _ld: Manual.html
|
|
.. _lc: Commands_all.html
|