document coding style and sanitizing options

doc/src/Build_development.rst

@@ -8,8 +8,8 @@ useful during development, testing or debugging.
 
 .. _compilation:
 
-Verify compilation flags
-------------------------
+Monitor compilation flags
+-------------------------
 
 Sometimes it is necessary to verify the complete sequence of compilation flags
 generated by the CMake build. To enable a more verbose output during
@@ -19,7 +19,8 @@ compilation you can use the following option.
 
    -D CMAKE_VERBOSE_MAKEFILE=value    # value = no (default) or yes
 
-Another way of doing this without reconfiguration is calling make with variable VERBOSE set to 1:
+Another way of doing this without reconfiguration is calling make with
+variable VERBOSE set to 1:
 
 .. code-block:: bash
 
@@ -33,25 +34,26 @@ Address, Undefined Behavior, and Thread Sanitizer Support
 ---------------------------------------------------------
 
 Compilers such as GCC and Clang support generating instrumented binaries
-which use different sanitizer libraries to detect problems in code
+which use different sanitizer libraries to detect problems in the code
 during run-time. They can detect issues like:
 
  - `memory leaks <https://clang.llvm.org/docs/AddressSanitizer.html>`_
  - `undefined behavior <https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html>`_
  - `data races <https://clang.llvm.org/docs/ThreadSanitizer.html>`_
 
-Please note that this kind of instrumentation usually comes with a small
-performance hit (much less than using tools like `Valgrind
-<https://valgrind.org>`_).  The to enable these features additional
-compiler flags need to be added to the compilation and linking stages.
-This is most easily done through setting the ``CMAKE_TUNE_FLAGS``
-variable during configuration. Examples:
+Please note that this kind of instrumentation usually comes with a
+performance hit (but much less than using tools like `Valgrind
+<https://valgrind.org>`_ with a more low level approach).  The to enable
+these features additional compiler flags need to be added to the
+compilation and linking stages.  This is done through setting the
+``ENABLE_SANITIZER`` variable during configuration. Examples:
 
 .. code-block:: bash
 
-   -D CMAKE_TUNE_FLAGS=-fsanitize=address    # enable address sanitizer / memory leak checker
-   -D CMAKE_TUNE_FLAGS=-fsanitize=undefined  # enable undefined behavior sanitizer
-   -D CMAKE_TUNE_FLAGS=-fsanitize=thread     # enable thread sanitizer
+   -D ENABLE_SANITIZER=none       # no sanitizer active (default)
+   -D ENABLE_SANITIZER=address    # enable address sanitizer / memory leak checker
+   -D ENABLE_SANITIZER=undefined  # enable undefined behavior sanitizer
+   -D ENABLE_SANITIZER=thread     # enable thread sanitizer
 
 ----------
 
@@ -86,19 +88,21 @@ The output of this command will be looking something like this::
    [...]$ ctest
    Test project /home/akohlmey/compile/lammps/build-testing
          Start  1: MolPairStyle:hybrid-overlay
-    1/26 Test  #1: MolPairStyle:hybrid-overlay .........   Passed    0.02 sec
+   1/109 Test  #1: MolPairStyle:hybrid-overlay .........   Passed    0.02 sec
          Start  2: MolPairStyle:hybrid
-    2/26 Test  #2: MolPairStyle:hybrid .................   Passed    0.01 sec
+   2/109 Test  #2: MolPairStyle:hybrid .................   Passed    0.01 sec
          Start  3: MolPairStyle:lj_class2
     [...]
-         Start 25: AngleStyle:harmonic
-   25/26 Test #25: AngleStyle:harmonic .................   Passed    0.01 sec
-         Start 26: AngleStyle:zero
-   26/26 Test #26: AngleStyle:zero .....................   Passed    0.01 sec
+         Start 107: PotentialFileReader
+ 107/109 Test #107: PotentialFileReader ................   Passed    0.04 sec
+         Start 108: EIMPotentialFileReader
+ 108/109 Test #108: EIMPotentialFileReader .............   Passed    0.03 sec
+         Start 109: TestSimpleCommands
+ 109/109 Test #109: TestSimpleCommands .................   Passed    0.02 sec
 
    100% tests passed, 0 tests failed out of 26
 
-   Total Test time (real) =   0.27 sec
+   Total Test time (real) =  25.57 sec
 
 
 The ``ctest`` command has many options, the most important ones are:
@@ -193,8 +197,8 @@ In this particular case, 5 out of 6 sets of tests were conducted, the
 tests for the ``lj/cut/opt`` pair style was skipped, since the tests
 executable did not include it.  To learn what individual tests are performed,
 you (currently) need to read the source code.  You can use code coverage
-recording (see next section) to confirm how well the tests cover the individual
-source files.
+recording (see next section) to confirm how well the tests cover the code
+paths in the individual source files.
 
 The force style test programs have a common set of options:
 
@@ -211,6 +215,14 @@ The force style test programs have a common set of options:
    * - -v
      - verbose output: also print the executed LAMMPS commands
 
+The ``ctest`` tool has no mechanism to directly pass flags to the individual
+test programs, but a workaround has been implmented where these flags can be
+set in an environment variable ``TEST_ARGS``. Example:
+
+.. code-block:: bash
+
+   env TEST_ARGS=-s ctest -V -R BondStyle
+
 To add a test for a style that is not yet covered, it is usually best
 to copy a YAML file for a similar style to a new file, edit the details
 of the style (how to call it, how to set its coefficients) and then
@@ -244,6 +256,16 @@ and working.
      of mis-compiled code (or an undesired large loss of precision due
      to significant reordering of operations and thus less error cancellation).
 
+Tests for other components and utility functions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Additional tests that validate utility functions or specific components
+of LAMMPS are implemented as standalone executable which may, or may not
+require creating a suitable LAMMPS instance.  These tests are more specific
+and do not require YAML format input files.  To add a test, either an
+existing source file needs to be extended or a new file added, which in turn
+requires additions to the ``CMakeLists.txt`` file in the source folder.
+
 Collect and visualize code coverage metrics
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -306,3 +328,23 @@ The images below illustrate how the data is presented.
              :target: JPG/coverage-file-branches.png
 
           Source page with branches
+
+Coding style utilities
+----------------------
+
+To aid with enforcing some of the coding style conventions in LAMMPS
+some additional build targets have been added. These require Python 3.5
+or later and will only work on Unix-like operating and file systems.
+The following options are available.
+
+.. code-block:: bash
+
+   make check-whitespace    # generate coverage report in HTML format
+   make fix-whitespace      # generate coverage report in XML format
+   make check-permissions   # delete folder with HTML format coverage report
+   make fix-permissions     # delete all collected coverage data and HTML output
+
+For the code in the ``unittest`` tree we are using the `clang-format`
+tool (Clang version 8.0 or later is required). If available, the source
+code files in the ``unittest`` tree can be updated to conform to the
+formatting settings using ``make format-tests``.