Unverified Commit c2ab177c authored by Axel Kohlmeyer's avatar Axel Kohlmeyer
Browse files

add some explanations and figures for code coverage

parent 30020594
Loading
Loading
Loading
Loading
+43 −6
Original line number Diff line number Diff line
@@ -244,17 +244,28 @@ and working.
     of mis-compiled code (or undesired large of precision due to
     reordering of operations).

------------
Collect and visualize code coverage metrics
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You can also collect code coverage metrics while running the tests by
enabling coverage support during building.
You can also collect code coverage metrics while running LAMMPS or the
tests by enabling code coverage support during the CMake configuration:

.. code-block:: bash

   -D ENABLE_COVERAGE=value  # enable coverage measurements, value = no (default) or yes
   -D ENABLE_COVERAGE=on  # enable coverage measurements (off by default)

This will also add the following targets to generate coverage reports
after running the LAMMPS executable or the unit tests:
This will instrument all object files to write information about which
lines of code were accessed during execution in files next to the
corresponding object files.  These can be post-processed to visually
show the degree of coverage and which code paths are accessed and which
are not taken.  When working on unit tests (see above), this can be
extremely helpful to determine which parts of the code are not executed
and thus what kind of tests are still missing. The coverage data is
cumulative, i.e. new data is added with each new run.

Enabling code coverage will also add the following build targets to
generate coverage reports after running the LAMMPS executable or the
unit tests:

.. code-block:: bash

@@ -267,3 +278,29 @@ to do this to install it via pip:
.. code-block:: bash

   pip install git+https://github.com/gcovr/gcovr.git

After post-processing with ``gen_coverage_html`` the results are in
a folder ``coverage_html`` and can be viewed with a web browser.
The images below illustrate how the data is presented.

.. list-table::

      * - .. figure:: JPG/coverage-overview-top.png
             :target: JPG/coverage-overview-top.png

          Top of the overview page

        - .. figure:: JPG/coverage-overview-manybody.png
             :target: JPG/coverage-overview-manybody.png

          Styles with good coverage

        - .. figure:: JPG/coverage-file-top.png
             :target: JPG/coverage-file-top.png

          Top of individual source page

        - .. figure:: JPG/coverage-file-branches.png
             :target: JPG/coverage-file-branches.png

          Source page with branches
+153 KiB
Loading image diff...
+110 KiB
Loading image diff...
+302 KiB
Loading image diff...
+238 KiB
Loading image diff...