Development-time tools
======================

Several tools have their own individual pages and are listed below.

.. toctree::
   :maxdepth: 2

   doxygen
   change-management
   infrastructure
   releng/index
   gmxtree
   code-formatting
   testutils
   physical_validation

.. todo:: :issue:`3032`

   Consider what is the most reasonable structure; currently, this list
   here does not make much sense in the overall organization and creates a
   confusing TOC for the developer guide.

.. todo:: :issue:`3267`

   Add details for most of the tools, either in the form of links to wiki,
   or to a separate page that explains more details.

Change management
-----------------

|Gromacs| change management uses git and `GitLab`_ for code uploading and testing as well as issues tracking.
(For change submission guidelines, refer to :doc:`contribute`.)

git
  |Gromacs| uses `git <https://git-scm.com/>`__ as the version control system.
  Instructions for setting up git for |Gromacs|, as well as tips and tricks for
  its use, can be found in :doc:`change-management`.

  Other basic tutorial material for ``git`` can be found on the `web <https://git-scm.com/doc/ext>`__.

GitLab
  Bugs and issues, as well as some random features and discussions,
  are tracked, and all code changes go through a code review system at
  https://gitlab.com/gromacs/gromacs.

Build testing
  All changes pushed to GitLab are automatically compiled and otherwise
  checked on various platforms.
  :doc:`infrastructure` documents how builds are automated,
  providing information on how to replicate the builds (e.g., to
  diagnose issues).
  :doc:`releng/index` provides more information on the technical implementation
  of the builds.

Build system
------------

.. todo:: details, ASAN, others?

CMake
  Main tool used in the build system.

packaging for distribution (CPack)

unit testing (CTest)
  |Gromacs| uses a unit testing framework based on Google C++ Testing
  Framework (gtest) and CTest.  All unit tests are automatically run in GitLab CI
  for each commit.
  Details can be found on a separate page on :doc:`testutils`.

clang static analyzer

coverage

regression tests

floating-point exceptions
  In debug builds, floating-point exceptions (FPEs) are generated whenever one of the
  following operations is encountered: division by zero, floating-point overflow,
  invalid operation (e.g., taking sqrt of a negative number).
  Such checks are *not* performed in the following configurations:

  - release build,
  - any build by GCC 7.x or Clang with optimizations,
  - build with SYCL support.

  In these configurations, FPEs can be enabled by adding ``-fpexcept`` flag to ``gmx``
  invocation. However, FPEs are not supported on Windows and non-x86 Apple hardware.
  See ``api/legacy/include/gromacs/math/utilities.h`` for more details.

.. _dev-formatting-tools:

Code formatting and style
-------------------------

The tools and scripts listed below are used to automatically check/apply
formatting that follows |Gromacs| style guidelines described on a separate page:
:doc:`style`.

clang-format
  We use clang-format to enforce a consistent coding style, with the
  settings recorded in ``.clang-format`` in the main tree.
  See :ref:`gmx-clang-format` for details.

clang-tidy
  The source code linter clang-tidy is used to enforce common restrictions to the
  code, with the checks collected under ``.clang-tidy`` at the top of the main tree.
  See :ref:`gmx-clang-tidy` for details.

``admin/copyright.py``
  This Python script adds and formats copyright headers in source files.
  ``copyright.sh`` (see below) uses the script to check/update copyright years on
  changed files automatically.

``admin/copyright.sh``
  This ``bash`` script runs the ``copyright.py`` python script to enforce
  correct copyright information in all files that have local changes
  and checks that they conform to the prescribed
  style.  Optionally, the script can also apply changes to make the files
  conform.
  This script is automatically run by the CI to ensure that all commits adhere
  to :doc:`formatting`.  If the copyright job does not succeed, it
  means that this script has something to complain.
  See :doc:`code-formatting` for details.

``admin/clang-format.sh``
  This script enforces coding style using clang-format.
  This script is automatically run by our CI to ensure that all commits adhere
  to :doc:`formatting`.

``admin/clang-tidy.sh``
  The clang-tidy code correctness restrictions are enforced by this script.
  The script is also used by the CI to verify the code, in addition to nightly
  compilations using clang-tidy on the whole tree.

``admin/git-pre-commit``
  This sample git pre-commit hook can be used if one wants to apply
  ``clang-tidy.sh``, ``copyright.sh`` and ``clang-format.sh`` automatically
  before every commit to check for formatting
  issues.  See :doc:`code-formatting` for details.

``docs/doxygen/includesorter.py``
  This Python script sorts and reformats #include directives according to
  the guidelines at :doc:`includestyle`.  Details are documented on a
  separate page (with the whole suite of Python scripts used for source code
  checks): :ref:`dev-include-sorter`.

include directive checker
  In its present form, the above include sorter script cannot be conveniently
  applied in the formatting script.  To check for issues, it is instead integrated into
  a ``check-source`` build target.  When this target is built, it also checks for
  include formatting issues.  Internally, it uses the sorter script.  This check
  is run in the CI as part of the Documentation job.
  Details for the checking mechanism are on a separate page (common for several
  checkers): :doc:`gmxtree`.

``admin/reformat_all.sh``
  This ``bash`` script runs clang-format/``copyright.py``/include sorter
  on all relevant files in the source tree (or in a particular directory).
  The script can also produce the list of files where these scripts are applied,
  for use with other scripts.  See :doc:`code-formatting` for details.

git attributes
  git attributes (specified in ``.gitattributes`` files) are used to annotate
  which files are subject to automatic formatting checks (and for automatic
  reformatting by the above scripts).  See ``man gitattributes`` for an overview of
  the mechanism.  We use the ``filter`` attribute to specify the type of automatic
  checking/formatting to apply.  Custom attributes are used for specifying some
  build system dependencies for easier processing in CMake.

