Skip to content
Snippets Groups Projects
Commit 0b523cb4 authored by Axel Kohlmeyer's avatar Axel Kohlmeyer
Browse files

some rewording and updates for the traditional and cmake documentation

parent 76289cd9
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
doc/src/Build.txt
+ 5
− 3
View file @ 0b523cb4
......@@ -10,9 +10,11 @@ Documentation"_ld - "LAMMPS Commands"_lc - "Next Section"_Run.html :c
Build LAMMPS :h2
LAMMPS can be built as an executable or library from source code via
either CMake or traditional make. As an alternative you can download
a pre-built executable file as described on the "Install"_Install.html
doc page.
either traditional makefiles (which may require manual editing)
for use with GNU make or gmake, or a build environment generated by CMake
(Unix Makefiles, Xcode, Visual Studio, KDevelop or more). As an
alternative you can download a package with pre-built executables
as described on the "Install"_Install.html doc page.
<!-- RST
......
doc/src/Build_basics.txt
+ 1
− 1
View file @ 0b523cb4
......@@ -301,7 +301,7 @@ want to copy files to is protected.
[CMake variable]:
cmake -D CMAKE_INSTALL_PREFIX=path \[options ...\] ~/lammps/cmake
cmake -D CMAKE_INSTALL_PREFIX=path \[options ...\] ../cmake
make # perform make after CMake command
make install # perform the installation into prefix :pre
......
doc/src/Build_cmake.txt
+ 84
− 54
View file @ 0b523cb4
......@@ -18,32 +18,42 @@ 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/rbberger/lammps/tree/cmake_documentation/cmake
CMake"_https://github.com/lammps/lammps/blob/master/cmake/README.md
:line
Building LAMMPS with CMake is a two-step process. First use CMake to
create a Makefile. Then use the standard make command to build
LAMMPS, which uses the created Makefile.
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.
mkdir mydir; cd mydir # create a new dir for build
cmake ~/lammps/cmake \[options ...\] # command-line version
ccmake ~/lammps/cmake # curses version (terminal-style menu)
cmake-gui ~/lammps/cmake # GUI version
make # traditional make command
make install # optional, copy LAMMPS executable & library elsewhere :pre
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.
The make command will compile and link LAMMPS, producing the
executable lmp and the library liblammps.a in mydir.
After compilation, you optionally, can copy the LAMMPS executable and
library into your system folders (by default under /usr/local) with:
If your machine has multiple cores (most do), using a command like
"make -j" will be much faster.
make install # optional, copy LAMMPS executable & library elsewhere :pre
:line
There are 3 variants of CMake: a command-line verison, a curses
version (teminal-style menu), and a GUI version. You can use any of
them to build LAMMPS. All the versions produce a Makefile as their
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
......@@ -51,39 +61,41 @@ 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.
Perform the build in a new directory you create. It can be a sub-dir
within lammps/cmake or anywhere you wish. You can perform separate
builds, with different options, in as many 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 can be installed in the
LAMMPS src dir. Likewise no style*.h or a lmpinstalledpkgs.h file can
exist, which are auto-generated by "building LAMMPS via traditional
make"_Build_make.html. CMake detects if this is not the case and
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 package, version 3.2 or later is
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 remove the
cache file CMakeCache.txt in the build directory and start over. Or
you can run cmake again from the same build directory and alter
various options; see details below.
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 ...\] ~/lammps/cmake # build from any dir
cmake \[options ...\] .. # build from lammps/cmake/newdir :pre
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.
......@@ -103,20 +115,23 @@ 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. Type "cmake --help" to see
the "Generator" styles of output your system supports.
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 scan this to verify all the features you requested were
enabled, including packages. You can also see what compiler and
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 running CMake again from the same directory will
inherit those settings.
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
......@@ -125,15 +140,28 @@ usually better to start with a fresh build directory.
[Curses version (terminal-style menu) of CMake]:
ccmake ~/lammps/cmake :pre
ccmake ../cmake :pre
Please see the "ccmake manual"_https://cmake.org/cmake/help/latest/manual/ccmake.1.html for more information.
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 ~/lammps/cmake :pre
cmake-gui ../cmake :pre
Please see the "cmake-gui manual"_https://cmake.org/cmake/help/latest/manual/cmake-gui.1.html for more information.
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
......@@ -145,14 +173,16 @@ 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 modules to manage software
packages, do this:
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
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
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/.
doc/src/Build_make.txt
+ 31
− 17
View file @ 0b523cb4
......@@ -9,15 +9,18 @@ Documentation"_ld - "LAMMPS Commands"_lc :c
Build LAMMPS with make :h3
Building LAMMPS with traditional make requires you have a
Makefile.machine file in the src/MAKE directory appropriate for your
system (see below). It can list various options for what to
include/exclude in a LAMMPS build. To include LAMMPS packages you
must install them first, as discussed on the "Build
package"_Build_package.html doc page. If the packages use provided or
external libraries, you must build those libraries before building
LAMMPS. Building "LAMMPS with CMake"_Build_cmake.html can automate
all of this, so we suggest you try it first.
Building LAMMPS with traditional makefiles requires, that you have a
Makefile."machine" file in the src/MAKE, src/MAKE/MACHINES,
src/MAKE/OPTIONS, or src/MAKE/MINE directory, which is appropriate
for your system (see below). It can list various options for
customizing your LAMMPS build with a number of global compilation
options and features. To include LAMMPS packages (i.e. optional
commands and styles) you must install them first, as discussed on
the "Build package"_Build_package.html doc page. If the packages
use provided or external libraries, you must build those libraries
before building LAMMPS. Building "LAMMPS with CMake"_Build_cmake.html
can automate all of this for many types of machines, especially
workstations, desktops and laptops, so we suggest you try it first.
These commands perform a default LAMMPS build, producing the LAMMPS
executable lmp_serial or lmp_mpi in lammps/src:
......@@ -27,23 +30,31 @@ make serial # build a serial LAMMPS executable
make mpi # build a parallel LAMMPS executable with MPI
make # see a variety of make options :pre
If your machine has multiple cores (most do), using a command like
"make -j mpi" will be much faster.
This initial compilation can take a long time, since LAMMPS is a large
project with many features. If your machine has multiple CPU cores (most
do these days), using a command like "make -jN mpi" (with N being to 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 the initial build, if you edit LAMMPS source files, or add new
files to the source directory, you can re-type make and it will only
re-compile the files that have changed.
After the initial build, whenever you edit LAMMPS source files, or
add or remove new files to the source directory (e.g. by installing or
uninstalling packages), you must recompile and relink the LAMMPS executable
with the same command line, but the makefiles will make certain, that
only files that need to be recompiled will be compiled (because they
were changed or depend on files, that were changed).
:line
The lammps/src/MAKE directory contains all the Makefile.machine files
The lammps/src/MAKE tree contains all the Makefile.machine files
included in the LAMMPS distribution. Typing "make machine" uses
Makefile.machine. Thus the "make serial" or "make mpi" lines above
use Makefile.serial and Makefile.mpi. Others are in these dirs:
OPTIONS # Makefiles which enable specific options
MACHINES # Makefiles for specific machines
MINE # customized Makefiles you create :pre
MINE # customized Makefiles you create (you may need to create this folder) :pre
Typing "make" lists all the available Makefile.machine files. A file
with the same name can appear in multiple dirs (not a good idea). The
......@@ -53,7 +64,10 @@ customized file you put in src/MAKE/MINE.
Makefiles you may wish to try include these (some require a package
first be installed). Many of these include specific compiler flags
for optimized performance:
for optimized performance. Please note, however, that most of these
customized machine Makefile are contributed and since both, compilers
and also OS configs, as well as LAMMPS itself keep changing all the
time, some of these settings and recommendations may be outdated:
make mac # build serial LAMMPS on a Mac
make mac_mpi # build parallel LAMMPS on a Mac
......
doc/src/Run_basics.txt
+ 13
− 11
View file @ 0b523cb4
......@@ -9,23 +9,25 @@ Documentation"_ld - "LAMMPS Commands"_lc :c
Basics of running LAMMPS :h3
LAMMPS is run from the command line, reading commands from standard
input, which are typically listed in an input script:
LAMMPS is run from the command line, reading commands from a
file via the -in command line flag, or from standard input.
Using the "-in in.file" variant is recommended:
lmp_serial < in.file
lmp_serial -in in.file
~/lammps/src/lmp_serial < in.file
/path/to/lammps/src/lmp_serial < in.file
mpirun -np 4 lmp_mpi -in in.file
mpirun -np 8 ~/lammps/src/lmp_mpi -in in.file
mpirun -np 6 /usr/local/bin/lmp_mpi -in in.file :pre
mpirun -np 8 /path/to//lammps/src/lmp_mpi -in in.file
mpirun -np 6 /usr/local/bin/lmp -in in.file :pre
You normally run from the directory your input script is in. That is
also where output files are produced, unless you specify otherwise in
your input script. As in some of the examples above, the LAMMPS
executable can be elsewhere.
You normally run the LAMMPS command in the directory where your
input script is located. That is also where output files are
produced by default, unless you provide specific other paths in
your input script or on the command line. As in some of the
examples above, the LAMMPS executable itself can be placed elsewhere.
NOTE: The redirection operator "<" can often be used with mpirun, but
some systems require the -in form.
NOTE: The redirection operator "<" will not always work when running
in parallel with mpirun; for those systems the -in form is required.
As LAMMPS runs it prints info to the screen and a logfile named
log.lammps. More info about output is given on the "Run
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment