Development build options (CMake only)
======================================

The CMake build of LAMMPS has a few extra options which are useful during
development, testing or debugging.

----------

.. _compilation:

Verify 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
compilation you can use the following option.

.. code-block:: bash

   -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:

.. code-block:: bash

   make VERBOSE=1

----------

.. _sanitizer:

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
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 <valgrind_>`_).
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:

.. 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

.. _valgrind: https://valgrind.org

----------

.. _testing:

Code Coverage and Testing
---------------------------------------

We do extensive regression testing of the LAMMPS code base on a continuous
basis. Some of the logic to do this has been added to the CMake build so
developers can run the tests directly on their workstation.

.. note::

   this is incomplete and only represents a small subset of tests that we run

.. code-block:: bash

   -D ENABLE_TESTING=value               # enable simple run tests of LAMMPS, value = no (default) or yes
   -D LAMMPS_TESTING_SOURCE_DIR=path     # path to lammps-testing repository (option if in custom location)
   -D LAMMPS_TESTING_GIT_TAG=value       # version of lammps-testing repository that should be used, value = master (default) or custom git commit or tag

If you enable testing in the CMake build it will create an additional target called "test". You can run them with:

.. code-block:: bash

   make test

The test cases used come from the lammps-testing repository. They are
derivatives of the examples folder with some modifications to make the run
faster.

You can also collect code coverage metrics while running the tests by enabling
coverage support during building.

.. code-block:: bash

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

This will also add the following targets to generate coverage reports after running the LAMMPS executable:

.. code-block:: bash

   make test               # run tests first!
   make gen_coverage_html  # generate coverage report in HTML format
   make gen_coverage_xml   # generate coverage report in XML format

These reports require GCOVR to be installed. The easiest way to do this to install it via pip:

.. code-block:: bash

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