use tabs for CMake vs. GNU make in LAMMPS library linking page

executable is independent of that library since all required

executable code from the library is copied into the calling executable.

CMake build

^^^^^^^^^^^

.. tabs::

   .. tab:: CMake build

      This assumes that LAMMPS has been configured without setting a

      ``LAMMPS_MACHINE`` name, installed with "make install", and the

``PKG_CONFIG_PATH`` environment variable has been updated to include the

``liblammps.pc`` file installed into the configured destination folder.

The commands to compile and link a coupled executable are then:

      ``PKG_CONFIG_PATH`` environment variable has been updated to

      include the ``liblammps.pc`` file installed into the configured

      destination folder.  The commands to compile and link a coupled

      executable are then:

      .. code-block:: bash

         mpicc -c -O $(pkgconf liblammps --cflags) caller.c

         mpicxx -o caller caller.o -$(pkgconf liblammps --libs)

Traditional make

^^^^^^^^^^^^^^^^

   .. tab:: Traditional make

      This assumes that LAMMPS has been compiled in the folder

``${HOME}/lammps/src`` with "make mpi". The commands to compile and link

a coupled executable are then:

      ``${HOME}/lammps/src`` with "make mpi". The commands to compile

      and link a coupled executable are then:

      .. code-block:: bash

      The *-I* argument is the path to the location of the ``library.h``

      header file containing the interface to the LAMMPS C-style library

interface.  The *-L* argument is the path to where the ``liblammps_mpi.a``

file is located.  The *-llammps_mpi* argument is shorthand for telling the

compiler to link the file ``liblammps_mpi.a``.  If LAMMPS has been

built as a shared library, then the linker will use ``liblammps_mpi.so``

instead.  If both files are available, the linker will usually prefer

the shared library.  In case of a shared library, you may need to update

the ``LD_LIBRARY_PATH`` environment variable or running the ``caller``

executable will fail since it cannot find the shared library at runtime.

      interface.  The *-L* argument is the path to where the

      ``liblammps_mpi.a`` file is located.  The *-llammps_mpi* argument

      is shorthand for telling the compiler to link the file

      ``liblammps_mpi.a``.  If LAMMPS has been built as a shared

      library, then the linker will use ``liblammps_mpi.so`` instead.

      If both files are available, the linker will usually prefer the

      shared library.  In case of a shared library, you may need to

      update the ``LD_LIBRARY_PATH`` environment variable or running the

      ``caller`` executable will fail since it cannot find the shared

      library at runtime.

However, it is only as simple as shown above for the case of a plain

LAMMPS library without any optional packages that depend on libraries

need to include all flags, libraries, and paths for the coupled

executable, that are also required to link the LAMMPS executable.

CMake build

^^^^^^^^^^^

.. tabs::

   .. tab:: CMake build

When using CMake, additional libraries with sources in the lib folder

are built, but not included in ``liblammps.a`` and (currently) not

installed with ``make install`` and not included in the ``pkgconfig``

configuration file.  They can be found in the top level build folder,

but you have to determine the necessary link flags manually.  It is

therefore recommended to either use the traditional make procedure to

build and link with a static library or build and link with a shared

library instead.

      When using CMake, additional libraries with sources in the lib

      folder are built, but not included in ``liblammps.a`` and

      (currently) not installed with ``make install`` and not included

      in the ``pkgconfig`` configuration file.  They can be found in the

      top level build folder, but you have to determine the necessary

      link flags manually.  It is therefore recommended to either use

      the traditional make procedure to build and link with a static

      library or build and link with a shared library instead.

Traditional make

^^^^^^^^^^^^^^^^

   .. tab:: Traditional make

After you have compiled a static LAMMPS library using the conventional

build system for example with "make mode=static serial". And you also

have installed the ``POEMS`` package after building its bundled library

in ``lib/poems``. Then the commands to build and link the coupled executable

change to:

      After you have compiled a static LAMMPS library using the

      conventional build system for example with "make mode=static

      serial". And you also have installed the ``POEMS`` package after

      building its bundled library in ``lib/poems``. Then the commands

      to build and link the coupled executable change to:

      .. code-block:: bash

         gcc -c -O -I${HOME}/lammps/src/STUBS -I${HOME}/lammps/src -caller.c

         g++ -o caller caller.o -L${HOME}/lammps/lib/poems \

     -L${HOME}/lammps/src/STUBS -L${HOME}/lammps/src -llammps_serial -lpoems -lmpi_stubs

                      -L${HOME}/lammps/src/STUBS -L${HOME}/lammps/src \

                      -llammps_serial -lpoems -lmpi_stubs

Note, that you need to link with ``g++`` instead of ``gcc`` even if you have

written your code in C, since LAMMPS itself is C++ code.  You can display the

currently applied settings for building LAMMPS for the "serial" machine target

by using the command:

      Note, that you need to link with ``g++`` instead of ``gcc`` even

      if you have written your code in C, since LAMMPS itself is C++

      code.  You can display the currently applied settings for building

      LAMMPS for the "serial" machine target by using the command:

      .. code-block:: bash

      From this you can gather the necessary paths and flags.  With

      makefiles for other *machine* configurations you need to do the

equivalent and replace "serial" with the corresponding "machine" name

of the makefile.

      equivalent and replace "serial" with the corresponding "machine"

      name of the makefile.

Link with LAMMPS as a shared library

------------------------------------

example case from above of the serial version static LAMMPS library with

the POEMS package installed becomes:

CMake build

^^^^^^^^^^^

.. tabs::

   .. tab:: CMake build

      The commands with a shared LAMMPS library compiled with the CMake

      build process are the same as for the static library.

         mpicc -c -O $(pkgconf liblammps --cflags) caller.c

         mpicxx -o caller caller.o -$(pkgconf --libs)

Traditional make

^^^^^^^^^^^^^^^^

   .. tab:: Traditional make

      The commands with a shared LAMMPS library compiled with the

      traditional make build using ``make mode=shared serial`` becomes:

         gcc -c -O -I${HOME}/lammps/src/STUBS -I${HOME}/lammps/src -caller.c

         g++ -o caller caller.o -L${HOME}/lammps/src -llammps_serial

*Locating liblammps.so at runtime*\ :

Locating liblammps.so at runtime

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

However, now the ``liblammps.so`` file is required at runtime and needs

to be in a folder, where the shared linker program of the operating

system can find it.  This would be either a folder like ``/usr/local/lib64``

or ``${HOME}/.local/lib64`` or a folder pointed to by the ``LD_LIBRARY_PATH``

environment variable. You can type

Unlike with a static link, now the ``liblammps.so`` file is required at

runtime and needs to be in a folder, where the shared linker program of

the operating system can find it.  This would be either a folder like

``/usr/local/lib64`` or ``${HOME}/.local/lib64`` or a folder pointed to

by the ``LD_LIBRARY_PATH`` environment variable. You can type

.. code-block:: bash

to see what directories are in that list.

Or you can add the LAMMPS src directory (or the directory you performed

a CMake style build in) to your ``LD_LIBRARY_PATH``, so that the current

version of the shared library is always available to programs that use it.

Or you can add the LAMMPS src directory or the directory you performed a

CMake style build in to your ``LD_LIBRARY_PATH`` environment variable,

so that the current version of the shared library is always available to

programs that use it.

For the Bourne or Korn shells (/bin/sh, /bin/ksh, /bin/bash etc.), you

would add something like this to your ``${HOME}/.profile`` file: