docs/dev-manual/tools.rst

   1 Development-time tools
   2 ======================
   3
   4 Several tools have their own individual pages and are listed below.
   5
   6 .. toctree::
   7    :maxdepth: 2
   8
   9    doxygen
  10    change-management
  11    infrastructure
  12    releng/index
  13    gmxtree
  14    code-formatting
  15    testutils
  16    physical_validation
  17
  18 .. todo:: :issue:`3032`
  19
  20    Consider what is the most reasonable structure; currently, this list
  21    here does not make much sense in the overall organization and creates a
  22    confusing TOC for the developer guide.
  23
  24 .. todo:: :issue:`3267`
  25
  26    Add details for most of the tools, either in the form of links to wiki,
  27    or to a separate page that explains more details.
  28
  29 Change management
  30 -----------------
  31
  32 |Gromacs| change management uses git and `GitLab`_ for code uploading and testing as well as issues tracking.
  33 (For change submission guidelines, refer to :doc:`contribute`.)
  34
  35 git
  36   |Gromacs| uses `git <https://git-scm.com/>`__ as the version control system.
  37   Instructions for setting up git for |Gromacs|, as well as tips and tricks for
  38   its use, can be found in :doc:`change-management`.
  39
  40   Other basic tutorial material for ``git`` can be found on the `web <https://git-scm.com/doc/ext>`__.
  41
  42 GitLab
  43   Bugs and issues, as well as some random features and discussions,
  44   are tracked, and all code changes go through a code review system at
  45   https://gitlab.com/gromacs/gromacs.
  46
  47 Build testing
  48   All changes pushed to GitLab are automatically compiled and otherwise
  49   checked on various platforms.
  50   :doc:`infrastructure` documents how builds are automated,
  51   providing information on how to replicate the builds (e.g., to
  52   diagnose issues).
  53   :doc:`releng/index` provides more information on the technical implementation
  54   of the builds.
  55
  56 .. _Git Tips & Tricks: http://www.gromacs.org/index.php?title=Developer_Zone/Git/Git_Tips_%26_Tricks
  57
  58 Build system
  59 ------------
  60
  61 .. todo:: details, ASAN, others?
  62
  63 CMake
  64   Main tool used in the build system.
  65
  66 packaging for distribution (CPack)
  67
  68 unit testing (CTest)
  69   |Gromacs| uses a unit testing framework based on Google C++ Testing
  70   Framework (gtest) and CTest.  All unit tests are automatically run in GitLab CI
  71   for each commit.
  72   Details can be found on a separate page on :doc:`testutils`.
  73
  74 clang static analyzer
  75
  76 coverage
  77
  78 regression tests
  79
  80 floating-point exceptions
  81   In debug builds, floating-point exceptions (FPEs) are generated whenever one of the
  82   following operations is encountered: division by zero, floating-point overflow,
  83   invalid operation (e.g., taking sqrt of a negative number).
  84   Such checks are *not* performed in the following configurations:
  85
  86   - release build,
  87   - any build by GCC 7.x or Clang with optimizations,
  88   - build with SYCL support.
  89
  90   In these configurations, FPEs can be enabled by adding ``-fpexcept`` flag to ``gmx``
  91   invocation. However, FPEs are not supported on Windows and non-x86 Apple hardware.
  92   See ``api/legacy/include/gromacs/math/utilities.h`` for more details.
  93
  94 .. _dev-formatting-tools:
  95
  96 Code formatting and style
  97 -------------------------
  98
  99 The tools and scripts listed below are used to automatically check/apply
 100 formatting that follows |Gromacs| style guidelines described on a separate page:
 101 :doc:`style`.
 102
 103 clang-format
 104   We use clang-format to enforce a consistent coding style, with the
 105   settings recorded in ``.clang-format`` in the main tree.
 106   See :ref:`gmx-clang-format` for details.
 107
 108 clang-tidy
 109   The source code linter clang-tidy is used to enforce common restrictions to the
 110   code, with the checks collected under ``.clang-tidy`` at the top of the main tree.
 111   See :ref:`gmx-clang-tidy` for details.
 112
 113 ``admin/copyright.py``
 114   This Python script adds and formats copyright headers in source files.
 115   ``copyright.sh`` (see below) uses the script to check/update copyright years on
 116   changed files automatically.
 117
 118 ``admin/copyright.sh``
 119   This ``bash`` script runs the ``copyright.py`` python script to enforce
 120   correct copyright information in all files that have local changes
 121   and checks that they conform to the prescribed
 122   style.  Optionally, the script can also apply changes to make the files
 123   conform.
 124   This script is automatically run by the CI to ensure that all commits adhere
 125   to :doc:`formatting`.  If the copyright job does not succeed, it
 126   means that this script has something to complain.
 127   See :doc:`code-formatting` for details.
 128
 129 ``admin/clang-format.sh``
 130   This script enforces coding style using clang-format.
 131   This script is automatically run by our CI to ensure that all commits adhere
 132   to :doc:`formatting`.
 133
 134 ``admin/clang-tidy.sh``
 135   The clang-tidy code correctness restrictions are enforced by this script.
 136   The script is also used by the CI to verify the code, in addition to nightly
 137   compilations using clang-tidy on the whole tree.
 138
 139 ``admin/git-pre-commit``
 140   This sample git pre-commit hook can be used if one wants to apply
 141   ``clang-tidy.sh``, ``copyright.sh`` and ``clang-format.sh`` automatically
 142   before every commit to check for formatting
 143   issues.  See :doc:`code-formatting` for details.
 144
 145 ``docs/doxygen/includesorter.py``
 146   This Python script sorts and reformats #include directives according to
 147   the guidelines at :doc:`includestyle`.  Details are documented on a
 148   separate page (with the whole suite of Python scripts used for source code
 149   checks): :ref:`dev-include-sorter`.
 150
 151 include directive checker
 152   In its present form, the above include sorter script cannot be conveniently
 153   applied in the formatting script.  To check for issues, it is instead integrated into
 154   a ``check-source`` build target.  When this target is built, it also checks for
 155   include formatting issues.  Internally, it uses the sorter script.  This check
 156   is run in the CI as part of the Documentation job.
 157   Details for the checking mechanism are on a separate page (common for several
 158   checkers): :doc:`gmxtree`.
 159
 160 ``admin/reformat_all.sh``
 161   This ``bash`` script runs clang-format/``copyright.py``/include sorter
 162   on all relevant files in the source tree (or in a particular directory).
 163   The script can also produce the list of files where these scripts are applied,
 164   for use with other scripts.  See :doc:`code-formatting` for details.
 165
 166 git attributes
 167   git attributes (specified in ``.gitattributes`` files) are used to annotate
 168   which files are subject to automatic formatting checks (and for automatic
 169   reformatting by the above scripts).  See ``man gitattributes`` for an overview of
 170   the mechanism.  We use the ``filter`` attribute to specify the type of automatic
 171   checking/formatting to apply.  Custom attributes are used for specifying some
 172   build system dependencies for easier processing in CMake.
 173