some rewording and updates for the traditional and cmake documentation
This commit is contained in:
Axel Kohlmeyer
@ -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
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
@ -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 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.
|
||||
|
||||
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.
|
||||
|
||||
After compilation, you optionally, can copy the LAMMPS executable and
|
||||
library into your system folders (by default under /usr/local) with:
|
||||
|
||||
make install # optional, copy LAMMPS executable & library elsewhere :pre
|
||||
|
||||
: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.
|
||||
|
||||
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
|
||||
|
||||
The make command will compile and link LAMMPS, producing the
|
||||
executable lmp and the library liblammps.a in mydir.
|
||||
|
||||
If your machine has multiple cores (most do), using a command like
|
||||
"make -j" will be much faster.
|
||||
|
||||
: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.
|
||||
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 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
|
||||
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/.
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
Reference in New Issue
Block a user