ICODE-ADC/lammps
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update traditional make info and synchronize information provided with CMake version

Browse Source
This commit is contained in:
Axel Kohlmeyer
2020-04-12 11:03:17 -04:00
parent 111ceb24cf
commit 5584bd1106
2 changed files with 69 additions and 42 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
doc/src/Build_cmake.rst
View File

@ -86,12 +86,20 @@ options and settings will be printed at the end. The ``cmake --build
ultimately produce a library ``liblammps.a`` and the LAMMPS executable ultimately produce a library ``liblammps.a`` and the LAMMPS executable
``lmp`` inside the ``build`` folder. ``lmp`` inside the ``build`` folder.
If your machine has multiple CPU cores (most do these days), you can Compilation can take a long time, since LAMMPS is a large project with
speed this up by compiling sources in parallel with ``make -j N`` (with many features. If your machine has multiple CPU cores (most do these
N being the maximum number of concurrently executed tasks). Also days), you can speed this up by compiling sources in parallel with
installation of the `ccache <https://ccache.dev/>`_ (= Compiler Cache) ``make -j N`` (with N being the maximum number of concurrently executed
software may speed up repeated compilation significantly, e.g. during code tasks). Also installation of the `ccache <https://ccache.dev/>`_ (=
development. Compiler Cache) software may speed up repeated compilation even more,
e.g. during code development.
After the initial build, whenever you edit LAMMPS source files, add
or remove packages, change compiler flags or build options,
you must re-compile and relink the LAMMPS executable with ``cmake --build .``.
If the compilation fails for some reason, try running ``cmake .`` and
then compile again. The included dependency tracking of should insure
that only the necessary subset of files are re-compiled.
After compilation, you may optionally install the LAMMPS executable into After compilation, you may optionally install the LAMMPS executable into
your system with: your system with:

91
doc/src/Build_make.rst
View File

@ -2,10 +2,14 @@ Build LAMMPS with make
====================== ======================
Building LAMMPS with traditional makefiles requires that you have a Building LAMMPS with traditional makefiles requires that you have a
Makefile."machine" file appropriate for your system in the src/MAKE, ``Makefile.<machine>`` file appropriate for your system in either the
src/MAKE/MACHINES, src/MAKE/OPTIONS, or src/MAKE/MINE directory (see ``src/MAKE``, ``src/MAKE/MACHINES``, ``src/MAKE/OPTIONS``, or
below). It can include various options for customizing your LAMMPS ``src/MAKE/MINE`` directory (see below). It can include various options
build with a number of global compilation options and features. for customizing your LAMMPS build with a number of global compilation
options and features.
Requirements
^^^^^^^^^^^^
Those makefiles are written for and tested with GNU make and may not Those makefiles are written for and tested with GNU make and may not
be compatible with other make programs. In most cases, if the "make" be compatible with other make programs. In most cases, if the "make"
@ -16,44 +20,52 @@ with :doc:`CMake <Build_cmake>`. The makefiles of the traditional
make based build process and the scripts they are calling expect a few make based build process and the scripts they are calling expect a few
additional tools to be available and functioning. additional tools to be available and functioning.
* a Bourne shell compatible "Unix" shell program (often this is bash) * a working C/C++ compiler toolchain; on Linux these are often the GNU compilers
* a few shell utilities: ls, mv, ln, rm, grep, sed, tr, cat, touch, diff, dirname * a Bourne shell compatible "Unix" shell program (often this is ``bash``)
* python (optional, required for "make lib-XXX" in the src folder) * a few shell utilities: ``ls``, ``mv``, ``ln``, ``rm``, ``grep``, ``sed``, ``tr``, ``cat``, ``touch``, ``diff``, ``dirname``
* python (optional, required for ``make lib-<pkg>`` in the src folder).
python scripts are currently tested with python 2.7 and 3.6. The procedure
for :doc:`building the documentation <Manual_build>` requires python 3.
To include LAMMPS packages (i.e. optional commands and styles) you Getting started
must enable them first, as discussed on the :doc:`Build package ^^^^^^^^^^^^^^^
<Build_package>` doc page. If a packages requires (provided or
To include LAMMPS packages (i.e. optional commands and styles) you must
enable (or "install") them first, as discussed on the :doc:`Build
package <Build_package>` doc page. If a packages requires (provided or
external) libraries, you must configure and build those libraries external) libraries, you must configure and build those libraries
**before** building LAMMPS itself and especially **before** enabling **before** building LAMMPS itself and especially **before** enabling
such a package with "make yes-<package>". Building :doc:`LAMMPS such a package with ``make yes-<package>``. Building :doc:`LAMMPS with
with CMake <Build_cmake>` can automate much of this for many types of CMake <Build_cmake>` can automate much of this for many types of
machines, especially workstations, desktops, and laptops, so we suggest machines, especially workstations, desktops, and laptops, so we suggest
you try it first when building LAMMPS in those cases. you try it first when building LAMMPS in those cases.
The commands below perform a default LAMMPS build, producing the LAMMPS The commands below perform a default LAMMPS build, producing the LAMMPS
executable lmp_serial and lmp_mpi in lammps/src: executable ``lmp_serial`` and ``lmp_mpi`` in ``lammps/src``:
.. code-block:: bash .. code-block:: bash
cd lammps/src cd lammps/src # change to main LAMMPS source folder
make serial # build a serial LAMMPS executable make serial # build a serial LAMMPS executable using GNU g++
make mpi # build a parallel LAMMPS executable with MPI make mpi # build a parallel LAMMPS executable with MPI
make # see a variety of make options make # see a variety of make options
This initial compilation can take a long time, since LAMMPS is a large Compilation can take a long time, since LAMMPS is a large project with
project with many features. If your machine has multiple CPU cores many features. If your machine has multiple CPU cores (most do these
(most do these days), using a command like "make -jN mpi" (with N = days), you can speed this up by compiling sources in parallel with
the number of available CPU cores) can be much faster. If you plan to ``make -j N`` (with N being the maximum number of concurrently executed
do development on LAMMPS or need to re-compile LAMMPS repeatedly, the tasks). Also installation of the `ccache <https://ccache.dev/>`_ (=
installation of the ccache (= Compiler Cache) software may speed up Compiler Cache) software may speed up repeated compilation even more,
compilation even more. e.g. during code development.
After the initial build, whenever you edit LAMMPS source files, or add 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 or remove new files to the source directory (e.g. by installing or
uninstalling packages), you must re-compile and relink the LAMMPS uninstalling packages), you must re-compile and relink the LAMMPS
executable with the same "make" command. This makefiles dependencies executable with the same ``make <machine>`` command. The makefile's
should insure that only the subset of files that need to be are dependency tracking should insure that only the necessary subset of
re-compiled. files are re-compiled. If you change settings in the makefile, you have
to recompile *everything*. To delete all objects you can use ``make
clean-<machine>``.
.. note:: .. note::
@ -65,13 +77,15 @@ re-compiled.
correctly detect which parts need to be recompiled after changes correctly detect which parts need to be recompiled after changes
were made to the sources. were made to the sources.
---------- Customized builds and alternate makefiles
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The lammps/src/MAKE tree contains the Makefile.machine files included The ``src/MAKE`` directory tree contains the ``Makefile.<machine>``
in the LAMMPS distribution. Typing "make machine" uses files included in the LAMMPS distribution. Typing ``make example`` uses
*Makefile.machine*\ . Thus the "make serial" or "make mpi" lines above ``Makefile.example`` from one of those folders, if available. Thus the
use Makefile.serial and Makefile.mpi, respectively. Other makefiles ``make serial`` and ``make mpi`` lines above use
are in these directories: ``src/MAKE/Makefile.serial`` and ``src/MAKE/Makefile.mpi``,
respectively. Other makefiles are in these directories:
.. code-block:: bash .. code-block:: bash
@ -79,11 +93,16 @@ are in these directories:
MACHINES # Makefiles for specific machines MACHINES # Makefiles for specific machines
MINE # customized Makefiles you create (you may need to create this folder) MINE # customized Makefiles you create (you may need to create this folder)
Typing "make" lists all the available Makefile.machine files. A file Simply typing ``make`` lists all the available ``Makefile.<machine>``
with the same name can appear in multiple folders (not a good idea). files with a single line description toward the end of the output. A
The order the directories are searched is as follows: src/MAKE/MINE, file with the same name can appear in multiple folders (not a good
src/MAKE, src/MAKE/OPTIONS, src/MAKE/MACHINES. This gives preference idea). The order the directories are searched is as follows:
to a customized file you put in src/MAKE/MINE. ``src/MAKE/MINE``, ``src/MAKE``, ``src/MAKE/OPTIONS``,
``src/MAKE/MACHINES``. This gives preference to a customized file you
put in ``src/MAKE/MINE``. If you create your own custom makefile under
a new name, please edit the first line with the description and machine
name, so you will not confuse yourself, when looking at the machine
summary.
Makefiles you may wish to try include these (some require a package Makefiles you may wish to try include these (some require a package
first be installed). Many of these include specific compiler flags first be installed). Many of these include specific compiler flags