mirror of https://github.com/lammps/lammps.git
use tabs for CMake vs. GNU make in LAMMPS library linking page
This commit is contained in:
Axel Kohlmeyer
parent
d77f08d5fb
commit
19ce59ba38
|
|
@ -41,42 +41,45 @@ The benefit of linking to a static library is, that the resulting
|
|||
executable is independent of that library since all required
|
||||
executable code from the library is copied into the calling executable.
|
||||
|
||||
CMake build
|
||||
^^^^^^^^^^^
|
||||
.. tabs::
|
||||
|
||||
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:
|
||||
.. tab:: CMake build
|
||||
|
||||
.. code-block:: bash
|
||||
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:
|
||||
|
||||
mpicc -c -O $(pkgconf liblammps --cflags) caller.c
|
||||
mpicxx -o caller caller.o -$(pkgconf liblammps --libs)
|
||||
.. code-block:: bash
|
||||
|
||||
Traditional make
|
||||
^^^^^^^^^^^^^^^^
|
||||
mpicc -c -O $(pkgconf liblammps --cflags) caller.c
|
||||
mpicxx -o caller caller.o -$(pkgconf liblammps --libs)
|
||||
|
||||
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:
|
||||
.. tab:: Traditional make
|
||||
|
||||
.. code-block:: bash
|
||||
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:
|
||||
|
||||
mpicc -c -O -I${HOME}/lammps/src caller.c
|
||||
mpicxx -o caller caller.o -L${HOME}/lammps/src -llammps_mpi
|
||||
.. 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.
|
||||
mpicc -c -O -I${HOME}/lammps/src caller.c
|
||||
mpicxx -o caller caller.o -L${HOME}/lammps/src -llammps_mpi
|
||||
|
||||
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.
|
||||
|
||||
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
|
||||
|
|
@ -84,61 +87,62 @@ 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::
|
||||
|
||||
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.
|
||||
.. tab:: CMake build
|
||||
|
||||
Traditional make
|
||||
^^^^^^^^^^^^^^^^
|
||||
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.
|
||||
|
||||
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:
|
||||
.. tab:: Traditional make
|
||||
|
||||
.. code-block:: bash
|
||||
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:
|
||||
|
||||
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
|
||||
.. code-block:: bash
|
||||
|
||||
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:
|
||||
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
|
||||
|
||||
.. code-block:: bash
|
||||
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:
|
||||
|
||||
make mode=print serial
|
||||
.. code-block:: bash
|
||||
|
||||
Which should output something like:
|
||||
make mode=print serial
|
||||
|
||||
.. code-block:: bash
|
||||
Which should output something like:
|
||||
|
||||
# Compiler:
|
||||
CXX=g++
|
||||
# Linker:
|
||||
LD=g++
|
||||
# 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}/compile/lammps/src -llammps_serial -L${HOME}/compile/lammps/lib/poems -L${HOME}/compile/lammps/src/STUBS -lpoems -lmpi_stubs
|
||||
.. 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.
|
||||
# Compiler:
|
||||
CXX=g++
|
||||
# Linker:
|
||||
LD=g++
|
||||
# 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}/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
|
||||
equivalent and replace "serial" with the corresponding "machine"
|
||||
name of the makefile.
|
||||
|
||||
Link with LAMMPS as a shared library
|
||||
------------------------------------
|
||||
|
|
@ -151,35 +155,36 @@ 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
|
||||
^^^^^^^^^^^
|
||||
.. tabs::
|
||||
|
||||
The commands with a shared LAMMPS library compiled with the CMake
|
||||
build process are the same as for the static library.
|
||||
.. tab:: CMake build
|
||||
|
||||
.. code-block:: bash
|
||||
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)
|
||||
.. code-block:: bash
|
||||
|
||||
Traditional make
|
||||
^^^^^^^^^^^^^^^^
|
||||
mpicc -c -O $(pkgconf liblammps --cflags) caller.c
|
||||
mpicxx -o caller caller.o -$(pkgconf --libs)
|
||||
|
||||
The commands with a shared LAMMPS library compiled with the
|
||||
traditional make build using ``make mode=shared serial`` becomes:
|
||||
.. tab:: Traditional make
|
||||
|
||||
.. code-block:: bash
|
||||
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
|
||||
.. code-block:: bash
|
||||
|
||||
*Locating liblammps.so at runtime*\ :
|
||||
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
|
||||
|
||||
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
|
||||
Locating liblammps.so at runtime
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
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
|
||||
|
||||
|
|
@ -187,9 +192,10 @@ 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
|
||||
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:
|
||||
|
|
|
|||
Loading…
Reference in New Issue