test for exceptions add example

doc/src/pg_lib_config.rst

@@ -1,9 +1,41 @@
 Retrieving LAMMPS configuration information
 ===========================================
 
-The following library functions can be used to query the
-LAMMPS library about compile time settings and included
-packages and styles.
+The following library functions can be used to query the LAMMPS library
+about compile time settings and included packages and styles.  This
+enables programs that use the library interface to run LAMMPS
+simulations to determine, whether the linked LAMMPS library is compatible
+with the requirements of the application without crashing during the
+LAMMPS functions (e.g. due to missing pair styles from packages) or to
+choose between different options (e.g. whether to use ``lj/cut``,
+``lj/cut/opt``, ``lj/cut/omp`` or ``lj/cut/intel``).  Most of the
+functions can be called directly without first creating a LAMMPS
+instance.  While crashes within LAMMPS may be recovered from through
+enabling :ref:`exceptions <exceptions>`, avoiding them proactively is
+a safer approach.
+
+.. code-block:: C
+   :caption: Handle errors using a LAMMPS library with exceptions
+
+   #include "library.h"
+   #include <stdio.h>
+
+   int main(int argc, char **argv)
+   {
+     void *handle;
+
+     handle = lammps_open_no_mpi(0, NULL, NULL);
+     lammps_file(handle, "in.missing");
+     if (lammps_has_error(handle)) {
+       char errmsg[256];
+       int errtype;
+       errtype = lammps_get_last_error_message(handle, errmsg, 256);
+       fprintf(stderr, "LAMMPS failed with error: %s\n", errmsg);
+       return 1;
+     }
+     lammps_close(handle);
+     return 0;
+   }
 
 -----------------------
 

unittest/c-library/CMakeLists.txt

@@ -35,6 +35,13 @@ else()
 endif()
 list(APPEND TEST_CONFIG_DEFS -DLAMMPS_HAS_MPI=${HAS_MPI})
 
+if(LAMMPS_EXCEPTION)
+  set(HAS_EXCEPTIONS 1)
+else()
+  set(HAS_EXCEPTIONS 0)
+endif()
+list(APPEND TEST_CONFIG_DEFS -DLAMMPS_HAS_EXCEPTIONS=${HAS_EXCEPTIONS})
+
 foreach(WITH "JPEG" "PNG" "GZIP" "FFMPEG")
   if(WITH_${WITH})
     set(HAS_${WITH} 1)

unittest/c-library/test_library_config.cpp

@@ -118,6 +118,11 @@ TEST_F(LibraryConfig, style_name)
     EXPECT_THAT(buf, StrEq(""));
 };
 
+TEST(LAMMPSConfig, exceptions)
+{
+    EXPECT_EQ(lammps_config_has_exceptions(), LAMMPS_HAS_EXCEPTIONS);
+};
+
 TEST(LAMMPSConfig, mpi_support)
 {
     EXPECT_EQ(lammps_config_has_mpi_support(), LAMMPS_HAS_MPI);