Include packages in build
=========================

In LAMMPS, a package is a group of files that enable a specific set of
features.  For example, force fields for molecular systems or
rigid-body constraints are in packages.  In the src directory, each
package is a sub-directory with the package name in capital letters.

An overview of packages is given on the :doc:`Packages <Packages>` doc
page.  Brief overviews of each package are on the :doc:`Packages details <Packages_details>` doc page.

When building LAMMPS, you can choose to include or exclude each
package.  In general there is no need to include a package if you
never plan to use its features.

If you get a run-time error that a LAMMPS command or style is
"Unknown", it is often because the command is contained in a package,
and your build did not include that package.  Running LAMMPS with the
:doc:`-h command-line switch <Run_options>` will print all the included
packages and commands for that executable.

For the majority of packages, if you follow the single step below to
include it, you can then build LAMMPS exactly the same as you would
without any packages installed.  A few packages may require additional
steps, as explained on the :doc:`Build extras <Build_extras>` doc page.

These links take you to the extra instructions for those select
packages:

+----------------------------------+----------------------------------+------------------------------------+------------------------------+--------------------------------+--------------------------------------+
| :ref:`COMPRESS <compress>`       | :ref:`GPU <gpu>`                 | :ref:`KIM <kim>`                   | :ref:`KOKKOS <kokkos>`       | :ref:`LATTE <latte>`           | :ref:`MESSAGE <message>`             |
+----------------------------------+----------------------------------+------------------------------------+------------------------------+--------------------------------+--------------------------------------+
| :ref:`MSCG <mscg>`               | :ref:`OPT <opt>`                 | :ref:`POEMS <poems>`               | :ref:`PYTHON <python>`       | :ref:`VORONOI <voronoi>`       | :ref:`USER-ADIOS <user-adios>`       |
+----------------------------------+----------------------------------+------------------------------------+------------------------------+--------------------------------+--------------------------------------+
| :ref:`USER-ATC <user-atc>`       | :ref:`USER-AWPMD <user-awpmd>`   | :ref:`USER-COLVARS <user-colvars>` | :ref:`USER-H5MD <user-h5md>` | :ref:`USER-INTEL <user-intel>` | :ref:`USER-MOLFILE <user-molfile>`   |
+----------------------------------+----------------------------------+------------------------------------+------------------------------+--------------------------------+--------------------------------------+
| :ref:`USER-NETCDF <user-netcdf>` | :ref:`USER-PLUMED <user-plumed>` | :ref:`USER-OMP <user-omp>`         | :ref:`USER-QMMM <user-qmmm>` | :ref:`USER-QUIP <user-quip>`   | :ref:`USER-SCAFACOS <user-scafacos>` |
+----------------------------------+----------------------------------+------------------------------------+------------------------------+--------------------------------+--------------------------------------+
| :ref:`USER-SMD <user-smd>`       | :ref:`USER-VTK <user-vtk>`       |                                    |                              |                                |                                      |
+----------------------------------+----------------------------------+------------------------------------+------------------------------+--------------------------------+--------------------------------------+

The mechanism for including packages is simple but different for CMake
versus make.

**CMake variables**\ :


.. parsed-literal::

   -D PKG_NAME=value          # yes or no (default)

Examples:


.. parsed-literal::

   -D PKG_MANYBODY=yes
   -D PKG_USER-INTEL=yes

All standard and user packages are included the same way.  Note that
USER packages have a hyphen between USER and the rest of the package
name, not an underscore.

See the shortcut section below for how to install many packages at
once with CMake.

.. note::

   If you toggle back and forth between building with CMake vs
   make, no packages in the src directory can be installed when you
   invoke cmake.  CMake will give an error if that is not the case,
   indicating how you can un-install all packages in the src dir.

**Traditional make**\ :


.. parsed-literal::

   cd lammps/src
   make ps                    # check which packages are currently installed
   make yes-name              # install a package with name
   make no-name               # un-install a package with name
   make mpi                   # build LAMMPS with whatever packages are now installed

Examples:


.. parsed-literal::

   make no-rigid
   make yes-user-intel

All standard and user packages are included the same way.

See the shortcut section below for how to install many packages at
once with make.

.. note::

   You must always re-build LAMMPS (via make) after installing or
   un-installing a package, for the action to take effect.

.. note::

   You cannot install or un-install packages and build LAMMPS in a
   single make command with multiple targets, e.g. make yes-colloid mpi.
   This is because the make procedure creates a list of source files that
   will be out-of-date for the build if the package configuration changes
   within the same command.  You can include or exclude multiple packages
   in a single make command, e.g. make yes-colloid no-manybody.

**CMake and make info**\ :

Any package can be included or excluded in a LAMMPS build, independent
of all other packages.  However, some packages include files derived
from files in other packages.  LAMMPS checks for this and does the
right thing.  Individual files are only included if their dependencies
are already included.  Likewise, if a package is excluded, other files
dependent on that package are also excluded.

When you download a LAMMPS tarball or download LAMMPS source files
from the Git or SVN repositories, no packages are pre-installed in the
src directory.

.. note::

   Prior to Aug 2018, if you downloaded a tarball, 3 packages
   (KSPACE, MANYBODY, MOLECULE) were pre-installed in the src directory.
   That is no longer the case, so that CMake will build as-is without the
   need to un-install those packages.


----------


**CMake shortcuts for installing many packages**\ :

Instead of specifying all the CMake options via the command-line,
CMake allows initializing the variable cache using script files. These
are regular CMake files which can manipulate and set variables, and
can also contain control flow constructs.

LAMMPS includes several of these files to define configuration
"presets", similar to the options that exist for the Make based
system. Using these files you can enable/disable portions of the
available packages in LAMMPS. If you need a custom preset you can take
one of them as a starting point and customize it to your needs.

+-------------------------------------------------------------+-----------------------------------------------------------+
| cmake -C ../cmake/presets/all\_on.cmake  [OPTIONS] ../cmake | enable all packages                                       |
+-------------------------------------------------------------+-----------------------------------------------------------+
| cmake -C ../cmake/presets/all\_off.cmake [OPTIONS] ../cmake | disable all packages                                      |
+-------------------------------------------------------------+-----------------------------------------------------------+
| cmake -C ../cmake/presets/minimal.cmake [OPTIONS] ../cmake  | enable just a few core packages                           |
+-------------------------------------------------------------+-----------------------------------------------------------+
| cmake -C ../cmake/presets/most.cmake    [OPTIONS] ../cmake  | enable most common packages                               |
+-------------------------------------------------------------+-----------------------------------------------------------+
| cmake -C ../cmake/presets/nolib.cmake   [OPTIONS] ../cmake  | disable packages that do require extra libraries or tools |
+-------------------------------------------------------------+-----------------------------------------------------------+
| cmake -C ../cmake/presets/clang.cmake   [OPTIONS] ../cmake  | change settings to use the Clang compilers by default     |
+-------------------------------------------------------------+-----------------------------------------------------------+
| cmake -C ../cmake/presets/mingw.cmake [OPTIONS] ../cmake    | enable all packages compatible with MinGW compilers       |
+-------------------------------------------------------------+-----------------------------------------------------------+

.. note::

   Running cmake this way manipulates the variable cache in your
   current build directory. You can combine multiple presets and options
   in a single cmake run, or change settings incrementally by running
   cmake with new flags.

**Example:**


.. parsed-literal::

   # build LAMMPS with most commonly used packages, but then remove
   # those requiring additional library or tools, but still enable
   # GPU package and configure it for using CUDA. You can run.
   mkdir build
   cd build
   cmake -C ../cmake/presets/most.cmake -C ../cmake/presets/nolib.cmake -D PKG_GPU=on -D GPU_API=cuda ../cmake

   # to add another package, say BODY to the previous configuration you can run:
   cmake -D PKG_BODY=on .

   # to reset the package selection from above to the default of no packages
   # but leaving all other settings untouched. You can run:
   cmake -C ../cmake/presets/no_all.cmake .


----------


**Make shortcuts for installing many packages**\ :

The following commands are useful for managing package source files
and their installation when building LAMMPS via traditional make.
Just type "make" in lammps/src to see a one-line summary.

These commands install/un-install sets of packages:

+-----------------------------------+-----------------------------------------------------+
| make yes-all                      | install all packages                                |
+-----------------------------------+-----------------------------------------------------+
| make no-all                       | un-install all packages                             |
+-----------------------------------+-----------------------------------------------------+
| make yes-standard or make yes-std | install standard packages                           |
+-----------------------------------+-----------------------------------------------------+
| make no-standard or make no-std   | un-install standard packages                        |
+-----------------------------------+-----------------------------------------------------+
| make yes-user                     | install user packages                               |
+-----------------------------------+-----------------------------------------------------+
| make no-user                      | un-install user packages                            |
+-----------------------------------+-----------------------------------------------------+
| make yes-lib                      | install packages that require extra libraries       |
+-----------------------------------+-----------------------------------------------------+
| make no-lib                       | un-install packages that require extra libraries    |
+-----------------------------------+-----------------------------------------------------+
| make yes-ext                      | install packages that require external libraries    |
+-----------------------------------+-----------------------------------------------------+
| make no-ext                       | un-install packages that require external libraries |
+-----------------------------------+-----------------------------------------------------+

which install/un-install various sets of packages.  Typing "make
package" will list all the these commands.

.. note::

   Installing or un-installing a package works by simply copying
   files back and forth between the main src directory and
   sub-directories with the package name (e.g. src/KSPACE, src/USER-ATC),
   so that the files are included or excluded when LAMMPS is built.

The following make commands help manage files that exist in both the
src directory and in package sub-directories.  You do not normally
need to use these commands unless you are editing LAMMPS files or are
:doc:`installing a patch <Install_patch>` downloaded from the LAMMPS web
site.

Type "make package-status" or "make ps" to show which packages are
currently installed.  For those that are installed, it will list any
files that are different in the src directory and package
sub-directory.

Type "make package-installed" or "make pi" to show which packages are
currently installed, without listing the status of packages that are
not installed.

Type "make package-update" or "make pu" to overwrite src files with
files from the package sub-directories if the package is installed.
It should be used after a :doc:`patch has been applied <Install_patch>`,
since patches only update the files in the package sub-directory, but
not the src files.

Type "make package-overwrite" to overwrite files in the package
sub-directories with src files.

Type "make package-diff" to list all differences between pairs of
files in both the src dir and a package dir.


.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html
