574e4067dc
This is the first step for moving the documentation format from *.txt to the *.rst format. In the last years we've been automatically converting txt files from Steve's markup into RST to generate the documentation pages via Sphinx. The decision has now been made to fully migrate to RST and avoid the conversion in the future. This will enable us to fully use RST and Sphinx to improve the documentation. For the intermediate period, while there are still pending PRs with documentation changes, we will keep both source files and update the RST files accordingly.
121 lines
3.6 KiB
ReStructuredText
121 lines
3.6 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.
|
|
|
|
|
|
.. parsed-literal::
|
|
|
|
-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:
|
|
|
|
|
|
.. parsed-literal::
|
|
|
|
make VERBOSE=1
|
|
|
|
|
|
----------
|
|
|
|
|
|
.. _sanitizer:
|
|
|
|
Address, Undefined Behavior, and Thread Sanitizer Support
|
|
-------------------------------------------------------------------------
|
|
|
|
Compilers such as GCC and Clang support generating binaries which use different
|
|
sanitizers to detect problems in code during run-time. They can detect `memory leaks <https://clang.llvm.org/docs/AddressSanitizer.html>`_,
|
|
code that runs into `undefined behavior <https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html>`_ of the
|
|
language and `data races <https://clang.llvm.org/docs/ThreadSanitizer.html>`_ in threaded code.
|
|
|
|
The following settings allow you enable these features if your compiler supports
|
|
it. Please note that they come with a performance hit. However, they are
|
|
usually faster than using tools like Valgrind.
|
|
|
|
|
|
.. parsed-literal::
|
|
|
|
-D ENABLE_SANITIZE_ADDRESS=value # enable Address Sanitizer, value = no (default) or yes
|
|
-D ENABLE_SANITIZE_UNDEFINED=value # enable Undefined Behaviour Sanitizer, value = no (default) or yes
|
|
-D ENABLE_SANITIZE_THREAD=value # enable Thread Sanitizer, value = no (default) or yes
|
|
|
|
|
|
----------
|
|
|
|
|
|
.. _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
|
|
|
|
|
|
.. parsed-literal::
|
|
|
|
-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:
|
|
|
|
|
|
.. parsed-literal::
|
|
|
|
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.
|
|
|
|
|
|
.. parsed-literal::
|
|
|
|
-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:
|
|
|
|
|
|
.. parsed-literal::
|
|
|
|
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:
|
|
|
|
|
|
.. parsed-literal::
|
|
|
|
pip install git+https://github.com/gcovr/gcovr.git
|
|
|
|
|
|
|
|
.. _lws: http://lammps.sandia.gov
|
|
.. _ld: Manual.html
|
|
.. _lc: Commands_all.html
|