108 lines
3.7 KiB
ReStructuredText
108 lines
3.7 KiB
ReStructuredText
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
|