diff --git a/doc/src/Build_basics.rst b/doc/src/Build_basics.rst index 8ad48b0810..8a81836614 100644 --- a/doc/src/Build_basics.rst +++ b/doc/src/Build_basics.rst @@ -6,7 +6,7 @@ CMake and make: * :ref:`Serial vs parallel build ` * :ref:`Choice of compiler and compile/link options ` -* :ref:`Build LAMMPS as an executable or a library ` +* :ref:`Build the LAMMPS executable and library ` * :ref:`Build the LAMMPS documentation ` * :ref:`Install LAMMPS after a build ` @@ -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 -is below. +using the `OpenMP `_ threading +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 -Makefile.machine, create a folder Obj_machine with all objects and -generated files and an executable called ``lmp_machine``\ . The standard -parallel build with ``make mpi`` assumes a standard MPI installation with -MPI compiler wrappers where all necessary compiler and linker flags to -get access and link with the suitable MPI headers and libraries are set -by the wrapper programs. For other cases or the serial build, you have -to adjust the make file variables ``MPI_INC``, ``MPI_PATH``, ``MPI_LIB`` -as well as ``CC`` and ``LINK``\ . To enable OpenMP threading usually -a compiler specific flag 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. +Any ``make machine`` command will look up the make settings from a file +``Makefile.machine`` in the folder ``src/MAKE`` or one of its +subdirectories ``MINE``, ``MACHINES``, or ``OPTIONS``, create a folder +``Obj_machine`` with all objects and generated files and an executable +called ``lmp_machine``\ . The standard parallel build with ``make mpi`` +assumes a standard MPI installation with MPI compiler wrappers where all +necessary compiler and linker flags to get access and link with the +suitable MPI headers and libraries are set by the wrapper programs. For +other cases or the serial build, you have to adjust the make file +variables ``MPI_INC``, ``MPI_PATH``, ``MPI_LIB`` as well as ``CC`` and +``LINK``\ . To enable OpenMP threading usually a compiler specific flag +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 -the src/STUBS dir. If the build fails, you will need to edit the -STUBS/Makefile for your platform. The stubs library does not provide -MPI/IO functions required by some LAMMPS packages, e.g. MPIIO or USER-LB, -and thus is not compatible with those packages. +otherwise, type ``make mpi-stubs`` from the src directory, or ``make`` +from the ``src/STUBS`` dir. If the build fails, you may need to edit +the ``STUBS/Makefile`` for your platform. The stubs library does not +provide MPI/IO functions required by some LAMMPS 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 - does not support gettimeofday() , you will need to insert code to - call another timer. Note that the ANSI-standard function clock() + ``MPI_Wtime()`` that calls ``gettimeofday()``. If your operating system + does not support ``gettimeofday()``, you will need to insert code to + 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 ` doc page for -details. The USER-INTEL package also includes OpenMP threading (it is -compatible with USER-OMP) and adds vectorization support when compiled -with compatible compilers, in particular the Intel compilers on top of -OpenMP. Also, the KOKKOS package can be compiled to include OpenMP -threading. +``USER-OMP`` package; see the :doc:`Speed omp ` doc page for +details. The ``USER-INTEL`` package also includes OpenMP threading (it +is compatible with ``USER-OMP`` and will usually fall back on styles +from that package, if a ``USER-INTEL`` does not exist) and adds +vectorization support when compiled with compatible compilers, in +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, -USER-DIFFRACTION, and USER-DPD packages. In addition some packages -support OpenMP threading indirectly through the libraries they interface -to: e.g. LATTE and USER-COLVARS. See the :doc:`Packages details -` doc page for more info on these packages and the doc -pages for their respective commands for OpenMP threading info. +support included as well. These are commands in the ``MPIIO``, +``SNAP``, ``USER-DIFFRACTION``, and ``USER-DPD`` packages. In addition +some packages support OpenMP threading indirectly through the libraries +they interface to: e.g. ``LATTE``, ``KSPACE``, and ``USER-COLVARS``. +See the :doc:`Packages details ` doc page for more +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 -of C/C++ code at high optimization levels. When using the USER-INTEL -package, there is a distinct advantage in using the `Intel C++ compiler -`_ due to much improved vectorization through SSE and AVX -instructions on compatible hardware as the source code includes changes -and compiler directives to enable high degrees of vectorization. +On the most common x86 hardware most popular C++ compilers are quite +similar in performance of C/C++ code at high optimization levels. When +using the ``USER-INTEL`` package, there is a distinct advantage in using +the `Intel C++ compiler `_ due to much improved vectorization +through SSE and AVX instructions on compatible hardware as the source +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 -optimization flags appropriate to that compiler and any -:doc:`accelerator packages ` you have included in the -build. +By default CMake will use a compiler it finds according to internal +preferences and it will add optimization flags appropriate to that +compiler and any :doc:`accelerator packages ` you have +included in the build. -You can tell CMake to look for a specific compiler with these variable -settings. Likewise you can specify the corresponding ``CMAKE_*_FLAGS`` -variables if you want to experiment with alternate optimization flags. -You should specify all 3 compilers, so that the small number of LAMMPS -source files written in C or Fortran are built with a compiler consistent -with the one used for all the C++ files: +You can tell CMake to look for a specific compiler with setting CMake +variable during configuration. For a few common choices, there are also +presets in the ``cmake/presets`` folder. For convenience, there is a +``CMAKE_TUNE_FLAGS`` variable that can be set to apply global compiler +options. More on that below, but you can also specify the corresponding +``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 -included that can be loaded with `-C ../cmake/presets/clang.cmake`. +For compiling with the Clang/LLVM compilers a CMake preset is provided that +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 -flags to tune for optimal performance on given hosts. By default these are -initialized to some compiler specific flags, where known, to optimize the -LAMMPS executable with optimizations and instructions available on the host -where LAMMPS is compiled. For example, for Intel compilers this would be -``-xHost`` and for GNU compilers this would be ``-march=native``. To turn -these flags off, set ``-D CMAKE_TUNE_FLAGS=``. +In addition you can set ``CMAKE_TUNE_FLAGS`` to specifically add +compiler flags to tune for optimal performance on given hosts. By +default these are initialized to some compiler specific flags, to +optimize the LAMMPS executable with optimizations and instructions +available on the host where LAMMPS is compiled. For example, for Intel +compilers this would be ``-xHost`` and for GNU compilers this would be +``-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 -settings appropriate for your MPI installation and thus avoiding the -guesswork of finding the right flags. +``mpicxx`` or ``mpiCC``, since these compiler wrappers will include a +variety of settings appropriate for your MPI installation and thus +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 -library. The LAMMPS library can be called from another application or -a scripting language. See the :doc:`Howto couple ` doc +LAMMPS is always built as a library of C++ classes plus an executable. +The executable is a simple ``main()`` function that sets up MPI and then +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 ` doc page for more info on coupling LAMMPS to other codes. See the :doc:`Python ` 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 -files the compilation produces during the configuration step. If none -are set, defaults are applied. +For CMake builds, you can select through setting CMake variables between +building a shared or a static LAMMPS library and what kind of suffix is +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 -``BUILD_LIB=yes`` will produce a static library named ``liblammps.a``\ . -Setting both ``BUILD_LIB=yes`` and ``BUILD_SHARED_LIBS=yes`` will produce a -shared library named ``liblammps.so`` instead. If ``LAMMPS_LIB_SUFFIX=name`` -is set in addition, the name of the generated libraries will be changed to -either ``liblammps_name.a`` or ``liblammps_name.so``\ , respectively. +The compilation will always produce a LAMMPS library and an executable +linked to it. By default this will be a static library named +``liblammps.a`` and an executable named ``lmp`` Setting +``BUILD_SHARED_LIBS=yes`` will instead produce a shared library called +``liblammps.so`` (or ``liblammps.dylib`` or ``liblammps.dll`` depending +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=lib machine # build LAMMPS static lib liblammps_machine.a - 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" + make mode=static machine # same as "make machine" + make mode=shared machine # build LAMMPS shared lib liblammps_machine.so instead -The two "exe" builds will generate and executable ``lmp_machine``\ , -while the two library builds will create a file ``liblammps_machine.a`` -or ``liblammps_machine.so``\ . They will also create generic soft links, -named ``liblammps.a`` and ``liblammps.so``\ , which point to the specific +The "static" build will generate a static library called +``liblammps_machine.a`` and an executable named ``lmp_machine``\ , while +the "shared" build will generate a shared library +``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 -the auxiliary libraries it depends on must also exist as shared -libraries. This will be the case for libraries included with LAMMPS, -such as the dummy MPI library in src/STUBS or any package libraries in -the lib/packages directory, since they are always built in a shared -library compatible way using the ``-fPIC`` switch. However, if a library -like MPI or FFTW does not exist as a shared library, the shared library -build may generate an error. This means you will need to install a -shared library version of the auxiliary library. The build instructions -for the library should tell you how to do this. +Note that for creating a shared library, all the libraries it depends on +must be compiled to be compatible with shared libraries. This should be +the case for libraries included with LAMMPS, such as the dummy MPI +library in ``src/STUBS`` or any package libraries in the ``lib`` +directory, since they are always built in a shared library compatible +way using the ``-fPIC`` compiler switch. However, if an auxiliary +library (like MPI or FFTW) does not exist as a compatible format, the +shared library linking step may generate an error. This means you will +need to install a compatible version of the auxiliary library. The +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 `_, 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 -do not have write privileges for ``/usr/local/lib``. 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 +You may need to use ``sudo make install`` in place of the last line if +you do not have write privileges for ``/usr/local/lib`` or use the +``--prefix`` configuration option to select an installation folder, +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. diff --git a/doc/src/Build_link.rst b/doc/src/Build_link.rst index b18dc49e38..39fc4fe40a 100644 --- a/doc/src/Build_link.rst +++ b/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 -Python scripts. The files src/library.cpp and library.h define the +LAMMPS is designed as a library of C++ objects and can thus be +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 ` doc page for a description of the interface and how to extend it for your needs. The :doc:`Build basics ` doc page explains how to build -LAMMPS as either a shared or static library. This results in one of -these 2 files: - -.. code-block:: bash - - liblammps.so # shared library - liblammps.a # static library +LAMMPS as either a shared or static library. This results in a file +in the compilation folder called ``liblammps.a`` or ``liblammps_.a`` +in case of building a static library. In case of a shared library +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. +In some cases the ``.so`` file may be a symbolic link to a file with +the suffix ``.so.0`` (or some other number). .. note:: - Care should be taken to use the same MPI library for the calling - code and the LAMMPS library. The library.h file includes mpi.h and - uses definitions from it so those need to be available and - consistent. When LAMMPS is compiled with the MPI STUBS library, - then its mpi.h file needs to be included. While it is technically - possible to use a full MPI library in the calling code and link to - a serial LAMMPS library compiled with MPI STUBS, it is recommended - to use the *same* MPI library for both, and then use MPI_Comm_split() - in the calling code to pass a suitable communicator with a subset - of MPI ranks to the function creating the LAMMPS instance. + Care should be taken to use the same MPI library for the calling code + and the LAMMPS library. The ``library.h`` file includes ``mpi.h`` + and uses definitions from it so those need to be available and + consistent. When LAMMPS is compiled with the included STUBS MPI + library, then its ``mpi.h`` file needs to be included. While it is + technically possible to use a full MPI library in the calling code + and link to a serial LAMMPS library compiled with MPI STUBS, it is + recommended to use the *same* MPI library for both, and then use + ``MPI_Comm_split()`` in the calling code to pass a suitable + 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" -and installed with "make install" and the PKG_CONFIG_PATH environment -variable updated to include the *liblammps.pc* file installed into the -configured destination folder, if needed. The commands to compile and -link the coupled executable are then: +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: .. 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 -and link the coupled executable are then: +``${HOME}/lammps/src`` with "make mpi". The commands to compile and link +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* -file is located. The *-llammps* argument is shorthand for telling the -compiler to link the file *liblammps.a*\ . +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 -(bundled or external). Otherwise, you need to include all flags, -libraries, and paths for the coupled executable, that are also -required to link the LAMMPS executable. +(bundled or external) or when using a shared library. Otherwise, you +need to include all flags, libraries, and paths for the coupled +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 -have installed the POEMS package after building its bundled library in -lib/poems. Then the commands to build and link the coupled executable +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 -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 -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", since the +LAMMPS library 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 @@ -113,16 +123,16 @@ Which should output something like: .. code-block:: bash - # Compiler: + # Compiler: CXX=g++ - # Linker: + # Linker: LD=g++ - # Compilation: - CXXFLAGS=-g -O3 -DLAMMPS_GZIP -DLAMMPS_MEMALIGN=64 -I${HOME}/lammps/lib/poems -I${HOME}/lammps/src/STUBS - # Linking: + # Compilation: + 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 + # Libraries: + 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 -becomes much simpler, as all dependent libraries and objects are -included in the shared library, which is - technically speaking - -effectively a regular LAMMPS executable that is missing the `main()` -function. Thus those libraries need not to be specified when linking -the calling executable. Only the *-I* flags are needed. So the -example case from above of the serial version static LAMMPS library -with the POEMS package installed becomes: +When linking to LAMMPS built as a shared library, the situation becomes +much simpler, as all dependent libraries and objects are either included +in the shared library or registered as a dependent library in the shared +library file. Thus those libraries need not to be specified when +linking the calling executable. Only the *-I* flags are needed. So the +example case from above of the serial version static LAMMPS library 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" -or "${HOME}/.local/lib64" or a folder pointed to by the LD_LIBRARY_PATH +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 @@ -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 ` 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 `_. -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 ` doc page.