update documentation for the fact that exceptions in LAMMPS are always used

doc/src/Developer_unittest.rst

@@ -180,19 +180,11 @@ discarded but by setting the verbose flag (via setting the ``TEST_ARGS``
 environment variable, ``TEST_ARGS=-v``) it can be printed and used to
 understand why tests fail unexpectedly.
 
-Another complexity of these tests stems from the need to capture
+The specifics of so-called "death tests", i.e. conditions where LAMMPS
-situations where LAMMPS will stop with an error, i.e. handle so-called
+should fail and throw an exception, are implemented in the
-"death tests".  Here the LAMMPS code will operate differently depending
+``TEST_FAILURE()`` macro. These tests operate by capturing the screen
-on whether it was configured to throw C++ exceptions on errors or call
+output when executing the failing command and then comparing that with a
-either ``exit()`` or ``MPI_Abort()``.  In the latter case, the test code
+provided regular expression string pattern.  Example:
-also needs to detect whether LAMMPS was compiled with the OpenMPI
-library, as OpenMPI is **only** compatible the death test options of the
-GoogleTest library when C++ exceptions are enabled; otherwise those
-"death tests" must be skipped to avoid reporting bogus failures.  The
-specifics of this step are implemented in the ``TEST_FAILURE()``
-macro. These tests operate by capturing the screen output when executing
-the failing command and then comparing that with a provided regular
-expression string pattern.  Example:
 
 .. code-block:: c++
 

doc/src/Fortran.rst

@@ -3038,14 +3038,6 @@ Procedures Bound to the :f:type:`lammps` Derived Type
    This function can be used to query if an error inside of LAMMPS
    has thrown a :ref:`C++ exception <exceptions>`.
 
-   .. note::
-
-      This function will always report "no error" when the LAMMPS library
-      has been compiled without ``-DLAMMPS_EXCEPTIONS``, which turns fatal
-      errors aborting LAMMPS into C++ exceptions. You can use the library
-      function :cpp:func:`lammps_config_has_exceptions` to check if this is
-      the case.
-
    :to: :cpp:func:`lammps_has_error`
    :r has_error: ``.TRUE.`` if there is an error.
    :rtype has_error: logical
@@ -3068,13 +3060,6 @@ Procedures Bound to the :f:type:`lammps` Derived Type
    would happen only in a single MPI rank and thus may not be recoverable, as
    other MPI ranks may be waiting on the failing MPI rank(s) to send messages.
 
-   .. note::
-
-      This function will do nothing when the LAMMPS library has been
-      compiled without ``-DLAMMPS_EXCEPTIONS``, which turns errors aborting
-      LAMMPS into C++ exceptions.  You can use the function
-      :f:func:`config_has_exceptions` to check whether this is the case.
-
    :p character(len=\*) buffer: string buffer to copy the error message into
    :o integer(c_int) status [optional]: 1 when all ranks had the error,
     2 on a single-rank error.

doc/src/Library.rst

@@ -80,13 +80,15 @@ run LAMMPS in serial mode.
    :class: note
 
    If the LAMMPS executable encounters an error condition, it will abort
-   after printing an error message. For a library interface this is
+   after printing an error message.  It does so by catching the
-   usually not desirable.  Thus LAMMPS can be compiled to to :ref:`throw
+   exceptions that LAMMPS could throw.  For a C library interface this
-   a C++ exception <exceptions>` instead.  If enabled, the library
+   is usually not desirable since the calling code might lack the
-   functions will catch those exceptions and return.  The error status
+   ability to catch such exceptions.  Thus, the library functions will
-   :cpp:func:`can be queried <lammps_has_error>` and an :cpp:func:`error
+   catch those exceptions and return from the affected functions.  The
-   message retrieved <lammps_get_last_error_message>`.  We thus
+   error status :cpp:func:`can be queried <lammps_has_error>` and an
-   recommend enabling C++ exceptions when using the library interface,
+   :cpp:func:`error message retrieved <lammps_get_last_error_message>`.
+   This is, for example used by the :doc:`LAMMPS python module
+   <Python_module>` and then a suitable Python exception is thrown.
 
 .. admonition:: Using the C library interface as a plugin
    :class: note

doc/src/Python_error.rst

@@ -15,9 +15,7 @@ Python exception handling mechanism.
 
    try:
       # LAMMPS will normally terminate itself and the running process if an error
-      # occurs. This would kill the Python interpreter. To avoid this, make sure to
+      # occurs. This would kill the Python interpreter.  The library wrapper will
-      # compile with LAMMPS_EXCEPTIONS enabled. This ensures the library API calls
-      # will not terminate the parent process. Instead, the library wrapper will
       # detect that an error has occured and throw a Python exception
 
       lmp.command('unknown')

doc/src/Python_install.rst

@@ -5,8 +5,7 @@ The LAMMPS Python module enables calling the :ref:`LAMMPS C library API
 <lammps_c_api>` from Python by dynamically loading functions in the
 LAMMPS shared library through the Python `ctypes <ctypes_>`_
 module.  Because of the dynamic loading, it is required that LAMMPS is
-compiled in :ref:`"shared" mode <exe>`.  It is also recommended to
+compiled in :ref:`"shared" mode <exe>`.
-compile LAMMPS with :ref:`C++ exceptions <exceptions>` enabled.
 
 Two components are necessary for Python to be able to invoke LAMMPS code:
 

doc/src/variable.rst

@@ -1044,10 +1044,9 @@ to built-in commands.  For all of these styles except *command*,
 appending of active suffixes is also tried before reporting failure.
 
 The *feature* category checks the availability of the following
-compile-time enabled features: GZIP support, PNG support, JPEG
+compile-time enabled features: GZIP support, PNG support, JPEG support,
-support, FFMPEG support, and C++ exceptions for error
+FFMPEG support, and C++ exceptions for error handling. Corresponding
-handling. Corresponding names are *gzip*, *png*, *jpeg*, *ffmpeg* and
+names are *gzip*, *png*, *jpeg*, *ffmpeg* and *exceptions*\ .
-*exceptions*\ .
 
 Example: Only dump in a given format if the compiled binary supports it.
 

src/library.cpp

@@ -481,7 +481,7 @@ void lammps_error(void *handle, int error_type, const char *error_text)
   }
   END_CAPTURE
 
-    // with enabled exceptions the above code will simply throw an
+    // in case of an error the above code will simply throw an
     // exception and record the error message. So we have to explicitly
     // stop here like we do in main.cpp
   if (lammps_has_error(handle)) {
@@ -6608,13 +6608,6 @@ has thrown a :ref:`C++ exception <exceptions>`.
    instance, but instead would check the global error buffer of the
    library interface.
 
-.. note::
-
-   This function will always report "no error" when the LAMMPS library
-   has been compiled without ``-DLAMMPS_EXCEPTIONS``, which turns fatal
-   errors aborting LAMMPS into C++ exceptions. You can use the library
-   function :cpp:func:`lammps_config_has_exceptions` to check whether this is
-   the case.
 \endverbatim
  *
  * \param handle   pointer to a previously created LAMMPS instance cast to ``void *`` or NULL
@@ -6663,12 +6656,6 @@ the failing MPI ranks to send messages.
    The *buffer* pointer may be ``NULL``.  This will clear any error
    status without copying the error message.
 
-.. note::
-
-   This function will do nothing when the LAMMPS library has been
-   compiled without ``-DLAMMPS_EXCEPTIONS``, which turns errors aborting
-   LAMMPS into C++ exceptions.  You can use the library function
-   :cpp:func:`lammps_config_has_exceptions` to check whether this is the case.
 \endverbatim
  *
  * \param  handle    pointer to a previously created LAMMPS instance cast to ``void *`` or NULL.