From 8e6c7fa4164a966d4870f256486c3f4d205f2df8 Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Mon, 31 Oct 2022 14:42:12 -0400 Subject: [PATCH] add note about the plugin version of the C library interface --- doc/src/Library.rst | 25 ++++++++++++++++++------- 1 file changed, 18 insertions(+), 7 deletions(-) diff --git a/doc/src/Library.rst b/doc/src/Library.rst index 05b652f7a7..3533c347c8 100644 --- a/doc/src/Library.rst +++ b/doc/src/Library.rst @@ -2,12 +2,13 @@ LAMMPS Library Interfaces ************************* As described on the :doc:`library interface to LAMMPS ` -page, LAMMPS can be built as a library (static or shared), so that -it can be called by another code, used in a :doc:`coupled manner +page, LAMMPS can be built as a library (static or shared), so that it +can be called by another code, used in a :doc:`coupled manner ` with other codes, or driven through a :doc:`Python -script `. Even the LAMMPS standalone executable is -essentially a thin wrapper on top of the LAMMPS library, creating a -LAMMPS instance, processing input and then existing. +script `. The LAMMPS standalone executable itself is +essentially a thin wrapper on top of the LAMMPS library, which creates a +LAMMPS instance, passes the input for processing to that instance, and +then exits. Most of the APIs described below are based on C language wrapper functions in the files ``src/library.h`` and ``src/library.cpp``, but @@ -87,6 +88,18 @@ run LAMMPS in serial mode. message retrieved `. We thus recommend enabling C++ exceptions when using the library interface, +.. admonition:: Using the C library interface as a plugin + :class: note + + Rather than including the C library directly and link to the LAMMPS + library at compile time, you can use the ``liblammpsplugin.h`` header + file and the ``liblammpsplugin.c`` C code in the + ``examples/COUPLE/plugin`` folder for an interface to LAMMPS that is + largely identical to the regular library interface, only that it will + load a LAMMPS shared library file at runtime. This can be useful for + applications where the interface to LAMMPS would be an optional + feature. + .. warning:: No checks are made on the arguments of the function calls of the C @@ -163,5 +176,3 @@ The following links provide some examples and references to the C++ API. :maxdepth: 1 Cplusplus - -