update documentation for the changes to the build procedure

doc/src/Build_basics.rst

@@ -6,7 +6,7 @@ CMake and make:
 
 * :ref:`Serial vs parallel build <serial>`
 * :ref:`Choice of compiler and compile/link options <compile>`
-* :ref:`Build LAMMPS as an executable or a library <exe>`
+* :ref:`Build the LAMMPS executable and library <exe>`
 * :ref:`Build the LAMMPS documentation <doc>`
 * :ref:`Install LAMMPS after a build <install>`
 
@@ -28,8 +28,8 @@ MPI STUBS library.
 
 Independent of the distributed memory MPI parallelization, parts of
 LAMMPS are also written with support for shared memory parallelization
-using the OpenMP threading standard. A more detailed discussion of that
+using the `OpenMP <https://en.wikipedia.org/wiki/OpenMP>`_ threading
-is below.
+standard. A more detailed discussion of that is below.
 
 **CMake build**\ :
 
@@ -41,7 +41,7 @@ is below.
                              # no default value
 
 The executable created by CMake (after running make) is named ``lmp`` unless
-the LAMMPS_MACHINE option is set.  When setting ``LAMMPS_MACHINE=name``
+the ``LAMMPS_MACHINE`` option is set.  When setting ``LAMMPS_MACHINE=name``
 the executable will be called ``lmp_name``.  Using ``BUILD_MPI=no`` will
 enforce building a serial executable using the MPI STUBS library.
 
@@ -55,18 +55,20 @@ The build with traditional makefiles has to be done inside the source folder ``s
    make serial             # serial build, produces lmp_serial using Makefile/serial
    make mybox              # uses Makefile.mybox to produce lmp_mybox
 
-Any "make machine" command will look up the make settings from a file
+Any ``make machine`` command will look up the make settings from a file
-Makefile.machine, create a folder Obj_machine with all objects and
+``Makefile.machine`` in the folder ``src/MAKE`` or one of its
-generated files and an executable called ``lmp_machine``\ .  The standard
+subdirectories ``MINE``, ``MACHINES``, or ``OPTIONS``, create a folder
-parallel build with ``make mpi`` assumes a standard MPI installation with
+``Obj_machine`` with all objects and generated files and an executable
-MPI compiler wrappers where all necessary compiler and linker flags to
+called ``lmp_machine``\ .  The standard parallel build with ``make mpi``
-get access and link with the suitable MPI headers and libraries are set
+assumes a standard MPI installation with MPI compiler wrappers where all
-by the wrapper programs.  For other cases or the serial build, you have
+necessary compiler and linker flags to get access and link with the
-to adjust the make file variables ``MPI_INC``, ``MPI_PATH``, ``MPI_LIB``
+suitable MPI headers and libraries are set by the wrapper programs.  For
-as well as ``CC`` and ``LINK``\ .  To enable OpenMP threading usually
+other cases or the serial build, you have to adjust the make file
-a compiler specific flag needs to be added to the compile and link
+variables ``MPI_INC``, ``MPI_PATH``, ``MPI_LIB`` as well as ``CC`` and
-commands.  For the GNU compilers, this is ``-fopenmp``\ , which can be
+``LINK``\ .  To enable OpenMP threading usually a compiler specific flag
-added to the ``CC`` and ``LINK`` makefile variables.
+needs to be added to the compile and link commands.  For the GNU
+compilers, this is ``-fopenmp``\ , which can be added to the ``CC`` and
+``LINK`` makefile variables.
 
 For the serial build the following make variables are set (see src/MAKE/Makefile.serial):
 
@@ -80,18 +82,19 @@ For the serial build the following make variables are set (see src/MAKE/Makefile
 
 You also need to build the STUBS library for your platform before making
 LAMMPS itself.  A ``make serial`` build does this for you automatically,
-otherwise, type ``make mpi-stubs`` from the src directory, or ``make`` from
+otherwise, type ``make mpi-stubs`` from the src directory, or ``make``
-the src/STUBS dir.  If the build fails, you will need to edit the
+from the ``src/STUBS`` dir.  If the build fails, you may need to edit
-STUBS/Makefile for your platform.  The stubs library does not provide
+the ``STUBS/Makefile`` for your platform.  The stubs library does not
-MPI/IO functions required by some LAMMPS packages, e.g. MPIIO or USER-LB,
+provide MPI/IO functions required by some LAMMPS packages,
-and thus is not compatible with those packages.
+e.g. ``MPIIO`` or ``USER-LB``, and thus is not compatible with those
+packages.
 
 .. note::
 
    The file ``src/STUBS/mpi.c`` provides a CPU timer function called
-   MPI_Wtime() that calls gettimeofday() .  If your operating system
+   ``MPI_Wtime()`` that calls ``gettimeofday()``.  If your operating system
-   does not support gettimeofday() , you will need to insert code to
+   does not support ``gettimeofday()``, you will need to insert code to
-   call another timer.  Note that the ANSI-standard function clock()
+   call another timer.  Note that the ANSI-standard function ``clock()``
    rolls over after an hour or so, and is therefore insufficient for
    timing long LAMMPS simulations.
 
@@ -111,20 +114,22 @@ self-installed MPICH or OpenMPI, so you should study the provided
 documentation to find out how to build and link with it.
 
 The majority of OpenMP (threading) support in LAMMPS is provided by the
-USER-OMP package; see the :doc:`Speed omp <Speed_omp>` doc page for
+``USER-OMP`` package; see the :doc:`Speed omp <Speed_omp>` doc page for
-details. The USER-INTEL package also includes OpenMP threading (it is
+details. The ``USER-INTEL`` package also includes OpenMP threading (it
-compatible with USER-OMP) and adds vectorization support when compiled
+is compatible with ``USER-OMP`` and will usually fall back on styles
-with compatible compilers, in particular the Intel compilers on top of
+from that package, if a ``USER-INTEL`` does not exist) and adds
-OpenMP. Also, the KOKKOS package can be compiled to include OpenMP
+vectorization support when compiled with compatible compilers, in
-threading.
+particular the Intel compilers on top of OpenMP. Also, the ``KOKKOS``
+package can be compiled to include OpenMP threading.
 
 In addition, there are a few commands in LAMMPS that have native OpenMP
-support included as well.  These are commands in the MPIIO, SNAP,
+support included as well.  These are commands in the ``MPIIO``,
-USER-DIFFRACTION, and USER-DPD packages.  In addition some packages
+``SNAP``, ``USER-DIFFRACTION``, and ``USER-DPD`` packages.  In addition
-support OpenMP threading indirectly through the libraries they interface
+some packages support OpenMP threading indirectly through the libraries
-to: e.g. LATTE and USER-COLVARS.  See the :doc:`Packages details
+they interface to: e.g. ``LATTE``, ``KSPACE``, and ``USER-COLVARS``.
-<Packages_details>` doc page for more info on these packages and the doc
+See the :doc:`Packages details <Packages_details>` doc page for more
-pages for their respective commands for OpenMP threading info.
+info on these packages and the doc pages for their respective commands
+for OpenMP threading info.
 
 For CMake, if you use ``BUILD_OMP=yes``, you can use these packages
 and turn on their native OpenMP support and turn on their native OpenMP
@@ -158,15 +163,18 @@ this conversion.
 Choice of compiler and compile/link options
 ---------------------------------------------------------
 
-The choice of compiler and compiler flags can be important for
+The choice of compiler and compiler flags can be important for maximum
 performance.  Vendor provided compilers for a specific hardware can
 produce faster code than open-source compilers like the GNU compilers.
-On x86 hardware most popular compilers are quite similar in performance
+On the most common x86 hardware most popular C++ compilers are quite
-of C/C++ code at high optimization levels.  When using the USER-INTEL
+similar in performance of C/C++ code at high optimization levels.  When
-package, there is a distinct advantage in using the `Intel C++ compiler
+using the ``USER-INTEL`` package, there is a distinct advantage in using
-<intel_>`_ due to much improved vectorization through SSE and AVX
+the `Intel C++ compiler <intel_>`_ due to much improved vectorization
-instructions on compatible hardware as the source code includes changes
+through SSE and AVX instructions on compatible hardware as the source
-and compiler directives to enable high degrees of vectorization.
+code includes changes and Intel compiler specific directives to enable
+high degrees of vectorization.  This may change over time as equivalent
+vectorization directives are included into OpenMP standard revisions and
+other compilers adopt them.
 
 .. _intel: https://software.intel.com/en-us/intel-compilers
 
@@ -177,17 +185,20 @@ LAMMPS.
 
 **CMake build**\ :
 
-By default CMake will use a compiler it finds and it will add
+By default CMake will use a compiler it finds according to internal
-optimization flags appropriate to that compiler and any
+preferences and it will add optimization flags appropriate to that
-:doc:`accelerator packages <Speed_packages>` you have included in the
+compiler and any :doc:`accelerator packages <Speed_packages>` you have
-build.
+included in the build.
 
-You can tell CMake to look for a specific compiler with these variable
+You can tell CMake to look for a specific compiler with setting CMake
-settings.  Likewise you can specify the corresponding ``CMAKE_*_FLAGS``
+variable during configuration.  For a few common choices, there are also
-variables if you want to experiment with alternate optimization flags.
+presets in the ``cmake/presets`` folder.  For convenience, there is a
-You should specify all 3 compilers, so that the small number of LAMMPS
+``CMAKE_TUNE_FLAGS`` variable that can be set to apply global compiler
-source files written in C or Fortran are built with a compiler consistent
+options.  More on that below, but you can also specify the corresponding
-with the one used for all the C++ files:
+``CMAKE_*_FLAGS`` variables individually if you want to experiment with
+alternate optimization flags.  You should specify all 3 compilers, so
+that the (few) LAMMPS source files written in C or Fortran are built
+with a compiler consistent with the one used for the C++ files:
 
 .. code-block:: bash
 
@@ -210,16 +221,17 @@ A few example command lines are:
    # Building with LLVM/Clang Compilers:
    cmake ../cmake -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_Fortran_COMPILER=flang
 
-For compiling with the Clang/LLVM compilers a special CMake preset is
+For compiling with the Clang/LLVM compilers a CMake preset is provided that
-included that can be loaded with `-C ../cmake/presets/clang.cmake`.
+can be loaded with `-C ../cmake/presets/clang.cmake`.  Similarly,
+`-C ../cmake/presets/intel.cmake` should switch the 
 
-In addition you can set ``CMAKE_TUNE_FLAGS`` to specifically add compiler
+In addition you can set ``CMAKE_TUNE_FLAGS`` to specifically add
-flags to tune for optimal performance on given hosts. By default these are
+compiler flags to tune for optimal performance on given hosts. By
-initialized to some compiler specific flags, where known, to optimize the
+default these are initialized to some compiler specific flags, to
-LAMMPS executable with optimizations and instructions available on the host
+optimize the LAMMPS executable with optimizations and instructions
-where LAMMPS is compiled. For example, for Intel compilers this would be
+available on the host where LAMMPS is compiled. For example, for Intel
-``-xHost`` and for GNU compilers this would be ``-march=native``. To turn
+compilers this would be ``-xHost`` and for GNU compilers this would be
-these flags off, set ``-D CMAKE_TUNE_FLAGS=``.
+``-march=native``. To turn these flags off, do ``-D CMAKE_TUNE_FLAGS=``.
 
 .. note::
 
@@ -235,11 +247,11 @@ these flags off, set ``-D CMAKE_TUNE_FLAGS=``.
 The "compiler/linker settings" section of a Makefile.machine lists
 compiler and linker settings for your C++ compiler, including
 optimization flags.  For a parallel build it is recommended to use
-mpicxx or mpiCC, since these compiler wrappers will include a variety of
+``mpicxx`` or ``mpiCC``, since these compiler wrappers will include a
-settings appropriate for your MPI installation and thus avoiding the
+variety of settings appropriate for your MPI installation and thus
-guesswork of finding the right flags.
+avoiding the guesswork of finding the right flags.
 
-Parallel build (see src/MAKE/Makefile.mpi):
+Parallel build (see ``src/MAKE/Makefile.mpi``):
 
 .. code-block:: bash
 
@@ -248,7 +260,7 @@ Parallel build (see src/MAKE/Makefile.mpi):
    LINK =          mpicxx
    LINKFLAGS =     -g -O
 
-Serial build (see src/MAKE/Makefile.serial):
+Serial build with GNU gcc (see ``src/MAKE/Makefile.serial``):
 
 .. code-block:: make
 
@@ -284,69 +296,74 @@ Serial build (see src/MAKE/Makefile.serial):
 
 .. _exe:
 
-Build LAMMPS as an executable or a library
+Build the LAMMPS executable and library
-----------------------------------------------------
+---------------------------------------
 
-LAMMPS can be built as either an executable or as a static or shared
+LAMMPS is always built as a library of C++ classes plus an executable.
-library.  The LAMMPS library can be called from another application or
+The executable is a simple ``main()`` function that sets up MPI and then
-a scripting language.  See the :doc:`Howto couple <Howto_couple>` doc
+creates a LAMMPS class instance from the LAMMPS library, which
+will then process commands provided via a file or from the console
+input.  The LAMMPS library can also be called from another application
+or a scripting language.  See the :doc:`Howto couple <Howto_couple>` doc
 page for more info on coupling LAMMPS to other codes.  See the
 :doc:`Python <Python_head>` doc page for more info on wrapping and
 running LAMMPS from Python via its library interface.
 
 **CMake build**\ :
 
-For CMake builds, you can select through setting CMake variables which
+For CMake builds, you can select through setting CMake variables between
-files the compilation produces during the configuration step.  If none
+building a shared or a static LAMMPS library and what kind of suffix is
-are set, defaults are applied.
+added to them (in case you want to concurrently install multiple variants
+of binaries with different settings). If none are set, defaults are applied.
 
 .. code-block:: bash
 
-   -D BUILD_EXE=value           # yes (default) or no
-   -D BUILD_LIB=value           # yes or no (default)
    -D BUILD_SHARED_LIBS=value   # yes or no (default)
-   -D LAMMPS_LIB_SUFFIX=name    # name = mpi, serial, mybox, titan, laptop, etc
+   -D LAMMPS_MACHINE=name       # name = mpi, serial, mybox, titan, laptop, etc
                                 # no default value
 
-Setting ``BUILD_EXE=no`` will not produce an executable.  Setting
+The compilation will always produce a LAMMPS library and an executable
-``BUILD_LIB=yes`` will produce a static library named ``liblammps.a``\ .
+linked to it.  By default this will be a static library named
-Setting both ``BUILD_LIB=yes`` and ``BUILD_SHARED_LIBS=yes`` will produce a
+``liblammps.a`` and an executable named ``lmp`` Setting
-shared library named ``liblammps.so`` instead. If ``LAMMPS_LIB_SUFFIX=name``
+``BUILD_SHARED_LIBS=yes`` will instead produce a shared library called
-is set in addition, the name of the generated libraries will be changed to
+``liblammps.so`` (or ``liblammps.dylib`` or ``liblammps.dll`` depending
-either ``liblammps_name.a`` or ``liblammps_name.so``\ , respectively.
+on the platform) If ``LAMMPS_MACHINE=name`` is set in addition, the name
+of the generated libraries will be changed to either
+``liblammps_name.a`` or ``liblammps_name.so``\ , respectively and the
+executable will be called ``lmp_name``.
 
 **Traditional make**\ :
 
 With the traditional makefile based build process, the choice of
 the generated executable or library depends on the "mode" setting.
-Several options are available and ``mode=exe`` is the default.
+Several options are available and ``mode=static`` is the default.
 
 .. code-block:: bash
 
    make machine               # build LAMMPS executable lmp_machine
-   make mode=exe machine      # same as "make machine"
+   make mode=static machine   # same as "make machine"
-   make mode=lib machine      # build LAMMPS static lib liblammps_machine.a
+   make mode=shared machine   # build LAMMPS shared lib liblammps_machine.so instead
-   make mode=shlib machine    # build LAMMPS shared lib liblammps_machine.so
-   make mode=shexe machine    # same as "mode=exe" but uses objects from "mode=shlib"
 
-The two "exe" builds will generate and executable ``lmp_machine``\ ,
+The "static" build will generate a static library called
-while the two library builds will create a file ``liblammps_machine.a``
+``liblammps_machine.a`` and an executable named ``lmp_machine``\ , while
-or ``liblammps_machine.so``\ . They will also create generic soft links,
+the "shared" build will generate a shared library
-named ``liblammps.a`` and ``liblammps.so``\ , which point to the specific
+``liblammps_machine.so`` instead and ``lmp_machine`` will be linked to
+it.  The build step will also create generic soft links, named
+``liblammps.a`` and ``liblammps.so``\ , which point to the specific
 ``liblammps_machine.a/so`` files.
 
 **CMake and make info**\ :
 
-Note that for a shared library to be usable by a calling program, all
+Note that for creating a shared library, all the libraries it depends on
-the auxiliary libraries it depends on must also exist as shared
+must be compiled to be compatible with shared libraries.  This should be
-libraries.  This will be the case for libraries included with LAMMPS,
+the case for libraries included with LAMMPS, such as the dummy MPI
-such as the dummy MPI library in src/STUBS or any package libraries in
+library in ``src/STUBS`` or any package libraries in the ``lib``
-the lib/packages directory, since they are always built in a shared
+directory, since they are always built in a shared library compatible
-library compatible way using the ``-fPIC`` switch.  However, if a library
+way using the ``-fPIC`` compiler switch.  However, if an auxiliary
-like MPI or FFTW does not exist as a shared library, the shared library
+library (like MPI or FFTW) does not exist as a compatible format, the
-build may generate an error.  This means you will need to install a
+shared library linking step may generate an error.  This means you will
-shared library version of the auxiliary library.  The build instructions
+need to install a compatible version of the auxiliary library.  The
-for the library should tell you how to do this.
+build instructions for that library should tell you how to do this.
 
 As an example, here is how to build and install the `MPICH library
 <mpich_>`_, a popular open-source version of MPI, as a shared library
@@ -360,10 +377,12 @@ in the default /usr/local/lib location:
    make
    make install
 
-You may need to use ``sudo make install`` in place of the last line if you
+You may need to use ``sudo make install`` in place of the last line if
-do not have write privileges for ``/usr/local/lib``.  The end result should
+you do not have write privileges for ``/usr/local/lib`` or use the
-be the file ``/usr/local/lib/libmpich.so``.  On many Linux installations the
+``--prefix`` configuration option to select an installation folder,
-folder ``${HOME}/.local`` is an alternative to using ``/usr/local`` and does
+where you do have write access.  The end result should be the file
+``/usr/local/lib/libmpich.so``.  On many Linux installations the folder
+``${HOME}/.local`` is an alternative to using ``/usr/local`` and does
 not require superuser or sudo access.  In that case the configuration
 step becomes:
 
@@ -371,7 +390,7 @@ step becomes:
 
   ./configure --enable-shared --prefix=${HOME}/.local
 
-Avoiding using "sudo" for custom software installation (i.e. from source
+Avoiding to use "sudo" for custom software installation (i.e. from source
 and not through a package manager tool provided by the OS) is generally
 recommended to ensure the integrity of the system software installation.
 

doc/src/Build_link.rst

@@ -1,33 +1,35 @@
 Link LAMMPS as a library to another code
 ========================================
 
-LAMMPS can be used as a library by another application, including
+LAMMPS is designed as a library of C++ objects and can thus be
-Python scripts.  The files src/library.cpp and library.h define the
+integrated into other applications including Python scripts.
+The files ``src/library.cpp`` and ``src/library.h`` define a
 C-style API for using LAMMPS as a library.  See the :doc:`Howto
 library <Howto_library>` doc page for a description of the interface
 and how to extend it for your needs.
 
 The :doc:`Build basics <Build_basics>` doc page explains how to build
-LAMMPS as either a shared or static library.  This results in one of
+LAMMPS as either a shared or static library.  This results in a file
-these 2 files:
+in the compilation folder called ``liblammps.a`` or ``liblammps_<name>.a``
-
+in case of building a static library.  In case of a shared library
-.. code-block:: bash
+the name is the same only that the suffix is going to be either ``.so``
-
+or ``.dylib`` or ``.dll`` instead of ``.a`` depending on the OS.
-   liblammps.so      # shared library
+In some cases the ``.so`` file may be a symbolic link to a file with
-   liblammps.a       # static library
+the suffix ``.so.0`` (or some other number).
 
 .. note::
 
-   Care should be taken to use the same MPI library for the calling
+   Care should be taken to use the same MPI library for the calling code
-   code and the LAMMPS library.  The library.h file includes mpi.h and
+   and the LAMMPS library.  The ``library.h`` file includes ``mpi.h``
-   uses definitions from it so those need to be available and
+   and uses definitions from it so those need to be available and
-   consistent.  When LAMMPS is compiled with the MPI STUBS library,
+   consistent.  When LAMMPS is compiled with the included STUBS MPI
-   then its mpi.h file needs to be included.  While it is technically
+   library, then its ``mpi.h`` file needs to be included.  While it is
-   possible to use a full MPI library in the calling code and link to
+   technically possible to use a full MPI library in the calling code
-   a serial LAMMPS library compiled with MPI STUBS, it is recommended
+   and link to a serial LAMMPS library compiled with MPI STUBS, it is
-   to use the *same* MPI library for both, and then use MPI_Comm_split()
+   recommended to use the *same* MPI library for both, and then use
-   in the calling code to pass a suitable communicator with a subset
+   ``MPI_Comm_split()`` in the calling code to pass a suitable
-   of MPI ranks to the function creating the LAMMPS instance.
+   communicator with a subset of MPI ranks to the function creating the
+   LAMMPS instance.
 
 ----------
 
@@ -42,11 +44,11 @@ executable code from the library is copied into the calling executable.
 
 *CMake build*\ :
 
-This assumes that LAMMPS has been configured with "-D BUILD_LIB=yes"
+This assumes that LAMMPS has been configured without setting a
-and installed with "make install" and the PKG_CONFIG_PATH environment
+``LAMMPS_MACHINE`` name, installed with "make install", and the
-variable updated to include the *liblammps.pc* file installed into the
+``PKG_CONFIG_PATH`` environment variable has been updated to include the
-configured destination folder, if needed.  The commands to compile and
+``liblammps.pc`` file installed into the configured destination folder.
-link the coupled executable are then:
+The commands to compile and link a coupled executable are then:
 
 .. code-block:: bash
 
@@ -56,30 +58,35 @@ link the coupled executable are then:
 *Traditional make*\ :
 
 This assumes that LAMMPS has been compiled in the folder
-"${HOME}/lammps/src" with "make mode=lib mpi". The commands to compile
+``${HOME}/lammps/src`` with "make mpi". The commands to compile and link
-and link the coupled executable are then:
+a coupled executable are then:
 
 .. code-block:: bash
 
    mpicc -c -O -I${HOME}/lammps/src caller.c
-   mpicxx -o caller caller.o -L${HOME}/lammps/src -llammps
+   mpicxx -o caller caller.o -L${HOME}/lammps/src -llammps_mpi
 
-The *-I* argument is the path to the location of the *library.h*
+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.a*
+interface.  The *-L* argument is the path to where the ``liblammps_mpi.a``
-file is located.  The *-llammps* argument is shorthand for telling the
+file is located.  The *-llammps_mpi* argument is shorthand for telling the
-compiler to link the file *liblammps.a*\ .
+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
-(bundled or external).  Otherwise, you need to include all flags,
+(bundled or external) or when using a shared library.  Otherwise, you
-libraries, and paths for the coupled executable, that are also
+need to include all flags, libraries, and paths for the coupled
-required to link the LAMMPS executable.
+executable, that are also required to link the LAMMPS executable.
 
 *CMake build*\ :
 
 When using CMake, additional libraries with sources in the lib folder
-are built, but not included in liblammps.a and (currently) not
+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
@@ -87,23 +94,26 @@ 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.
 
+.. TODO: this needs to be updated to reflect that latest CMake changes after they are complete.
+
 *Traditional make*\ :
 
 After you have compiled a static LAMMPS library using the conventional
-build system for example with "make mode=lib serial". And you also
+build system for example with "make mode=static serial". And you also
-have installed the POEMS package after building its bundled library in
+have installed the ``POEMS`` package after building its bundled library
-lib/poems. Then the commands to build and link the coupled executable
+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 -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", since LAMMPS
+Note, that you need to link with "g++" instead of "gcc", since the
-is C++ code.  You can display the currently applied settings for building
+LAMMPS library is C++ code.  You can display the currently applied
-LAMMPS for the "serial" machine target by using the command:
+settings for building LAMMPS for the "serial" machine target by using
+the command:
 
 .. code-block:: bash
 
@@ -118,11 +128,11 @@ Which should output something like:
    # Linker: 
    LD=g++
    # Compilation: 
-   CXXFLAGS=-g -O3 -DLAMMPS_GZIP -DLAMMPS_MEMALIGN=64 -I${HOME}/lammps/lib/poems -I${HOME}/lammps/src/STUBS
+   CXXFLAGS=-g -O3 -DLAMMPS_GZIP -DLAMMPS_MEMALIGN=64 -I${HOME}/compile/lammps/lib/poems -I${HOME}/compile/lammps/src/STUBS
    # Linking: 
    LDFLAGS=-g -O
    # Libraries: 
-   LDLIBS=-L${HOME}/lammps/lib/poems -L${HOME}/lammps/src/STUBS -lpoems -lmpi_stubs
+   LDLIBS=-L${HOME}/compile/lammps/src -llammps_serial -L${HOME}/compile/lammps/lib/poems -L${HOME}/compile/lammps/src/STUBS -lpoems -lmpi_stubs
 
 From this you can gather the necessary paths and flags.  With
 makefiles for other *machine* configurations you need to do the
@@ -133,14 +143,13 @@ of the makefile.
 
 **Link with LAMMPS as a shared library**\ :
 
-When linking to LAMMPS built as a shared library, the situation
+When linking to LAMMPS built as a shared library, the situation becomes
-becomes much simpler, as all dependent libraries and objects are
+much simpler, as all dependent libraries and objects are either included
-included in the shared library, which is - technically speaking -
+in the shared library or registered as a dependent library in the shared
-effectively a regular LAMMPS executable that is missing the `main()`
+library file.  Thus those libraries need not to be specified when
-function.  Thus those libraries need not to be specified when linking
+linking the calling executable.  Only the *-I* flags are needed.  So the
-the calling executable.  Only the *-I* flags are needed.  So the
+example case from above of the serial version static LAMMPS library with
-example case from above of the serial version static LAMMPS library
+the POEMS package installed becomes:
-with the POEMS package installed becomes:
 
 *CMake build*\ :
 
@@ -155,19 +164,19 @@ build process are the same as for the static library.
 *Traditional make*\ :
 
 The commands with a shared LAMMPS library compiled with the
-traditional make build using "make mode=shlib serial" becomes:
+traditional make build using "make mode=shared serial" becomes:
 
 .. 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/src -llammps
+   g++ -o caller caller.o -L${HOME}/lammps/src -llammps_serial
 
 *Locating liblammps.so at runtime*\ :
 
-However, now the `liblammps.so` file is required at runtime and needs
+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"
+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
+or ``${HOME}/.local/lib64`` or a folder pointed to by the ``LD_LIBRARY_PATH``
 environment variable. You can type
 
 .. code-block:: bash
@@ -177,11 +186,11 @@ environment variable. You can type
 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
+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.
 
 For the Bourne or Korn shells (/bin/sh, /bin/ksh, /bin/bash etc.), you
-would add something like this to your ~/.profile file:
+would add something like this to your ``${HOME}/.profile`` file:
 
 .. code-block:: bash
 
@@ -189,14 +198,14 @@ would add something like this to your ~/.profile file:
    export LD_LIBRARY_PATH
 
 For the csh or tcsh shells, you would equivalently add something like this
-to your ~/.cshrc file:
+to your ``${HOME}/.cshrc`` file:
 
 .. code-block:: csh
 
    setenv LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:${HOME}/lammps/src
 
 You can verify whether all required shared libraries are found with the
-`ldd` tool.  Example:
+``ldd`` tool.  Example:
 
 .. code-block:: bash
 
@@ -229,20 +238,20 @@ If a required library is missing, you would get a 'not found' entry:
 Either flavor of library (static or shared) allows one or more LAMMPS
 objects to be instantiated from the calling program. When used from a
 C++ program, most of the symbols and functions in LAMMPS are wrapped
-in a LAMMPS_NS namespace; you can safely use any of its classes and
+in a ``LAMMPS_NS`` namespace; you can safely use any of its classes and
 methods from within the calling code, as needed, and you will not incur
 conflicts with functions and variables in your code that share the name.
 This, however, does not extend to all additional libraries bundled with
 LAMMPS in the lib folder and some of the low-level code of some packages.
 
 To be compatible with C, Fortran, Python programs, the library has a simple
-C-style interface, provided in src/library.cpp and src/library.h.
+C-style interface, provided in ``src/library.cpp`` and ``src/library.h``.
 
 See the :doc:`Python library <Python_library>` doc page for a
 description of the Python interface to LAMMPS, which wraps the C-style
 interface from a shared library through the `ctypes python module <ctypes_>`_.
 
-See the sample codes in examples/COUPLE/simple for examples of C++ and
+See the sample codes in ``examples/COUPLE/simple`` for examples of C++ and
 C and Fortran codes that invoke LAMMPS through its library interface.
 Other examples in the COUPLE directory use coupling ideas discussed on
 the :doc:`Howto couple <Howto_couple>` doc page.