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 is supported by the following tools.
  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 Gerrit
  43   All code changes go through a code review system at
  44   http://gerrit.gromacs.org.
  45
  46 Build testing
  47   All changes pushed to Gerrit are automatically compiled and otherwise
  48   checked on various platforms.
  49   :doc:`infrastructure` documents how builds are automated,
  50   providing information on how to replicate the builds (e.g., to
  51   diagnose issues).
  52   :doc:`releng/index` provides more information on the technical implementation
  53   of the builds.
  54
  55 Redmine
  56   Bugs and issues, as well as some random features and discussions,
  57   are tracked at http://redmine.gromacs.org.
  58
  59 .. _Git Tips & Tricks: http://www.gromacs.org/index.php?title=Developer_Zone/Git/Git_Tips_%26_Tricks
  60
  61 Build system
  62 ------------
  63
  64 .. todo:: details, ASAN, others?
  65
  66 CMake
  67   Main tool used in the build system.
  68
  69 packaging for distribution (CPack)
  70
  71 unit testing (CTest)
  72   |Gromacs| uses a unit testing framework based on Google C++ Testing
  73   Framework (gtest) and CTest.  All unit tests are automatically run on Jenkins
  74   for each commit.
  75   Details can be found on a separate page on :doc:`testutils`.
  76
  77 clang static analyzer
  78
  79 coverage
  80
  81 regression tests
  82
  83 .. _dev-formatting-tools:
  84
  85 Code formatting and style
  86 -------------------------
  87
  88 The tools and scripts listed below are used to automatically check/apply
  89 formatting that follows |Gromacs| style guidelines described on a separate page:
  90 :doc:`style`.
  91
  92 uncrustify
  93   `uncrustify <http://uncrustify.sourceforge.net>`_ is used for automatic
  94   indentation and other formatting of the source code to follow
  95   :doc:`formatting`.  All code must remain invariant under uncrustify
  96   with the config at ``admin/uncrustify.cfg``.  A patched version of uncrustify is
  97   used.  See :ref:`gmx-uncrustify` for details.
  98
  99 clang-format
 100   We use clang-format to enforce a consistent coding style, with the
 101   settings recorded in ``.clang-format`` in the main tree.
 102   See :ref:`gmx-clang-format` for details.
 103
 104 ``admin/copyright.py``
 105   This Python script adds and formats copyright headers in source files.
 106   ``copyright.sh`` (see below) uses the script to check/update copyright years on
 107   changed files automatically.
 108
 109 ``admin/uncrustify.sh``
 110   This ``bash`` script runs uncrustify for all
 111   files that have local changes and checks that they conform to the prescribed
 112   style.  Optionally, the script can also apply changes to make the files
 113   conform. It is included only for historical reasons.
 114   See :doc:`formatting` for details.
 115
 116 ``admin/copyright.sh``
 117   This ``bash`` script runs the ``copyright.py`` python script to enforce
 118   correct copyright information in all files that have local changes
 119   and checks that they conform to the prescribed
 120   style.  Optionally, the script can also apply changes to make the files
 121   conform.
 122   This script is automatically run by Jenkins to ensure that all commits adhere
 123   to :doc:`formatting`.  If the copyright job does not succeed, it
 124   means that this script has something to complain.
 125   See :doc:`code-formatting` for details.
 126
 127 ``admin/clang-format.sh``
 128   This script enforces coding style using clang-format.
 129   This script is automatically run by Jenkins to ensure that all commits adhere
 130   to :doc:`formatting`.
 131
 132 ``admin/git-pre-commit``
 133   This sample git pre-commit hook can be used if one wants to apply
 134   ``uncrustify.sh`` and ``clang-format.sh`` automatically before every commit to check for formatting
 135   issues.  See :doc:`code-formatting` for details.
 136
 137 ``docs/doxygen/includesorter.py``
 138   This Python script sorts and reformats #include directives according to
 139   the guidelines at :doc:`includestyle`.  Details are documented on a
 140   separate page (with the whole suite of Python scripts used for source code
 141   checks): :ref:`dev-include-sorter`.
 142
 143 include directive checker
 144   In its present form, the above include sorter script cannot be conveniently
 145   applied in the formatting script.  To check for issues, it is instead integrated into
 146   a ``check-source`` build target.  When this target is built, it also checks for
 147   include formatting issues.  Internally, it uses the sorter script.  This check
 148   is run in Jenkins as part of the Documentation job.
 149   Details for the checking mechanism are on a separate page (common for several
 150   checkers): :doc:`gmxtree`.
 151
 152 ``admin/reformat_all.sh``
 153   This ``bash`` script runs uncrustify/clang-format/``copyright.py``/include sorter
 154   on all relevant files in the source tree (or in a particular directory).
 155   The script can also produce the list of files where these scripts are applied,
 156   for use with other scripts.  See :doc:`code-formatting` for details.
 157
 158 git attributes
 159   git attributes (specified in ``.gitattributes`` files) are used to annotate
 160   which files are subject to automatic formatting checks (and for automatic
 161   reformatting by the above scripts).  See ``man gitattributes`` for an overview of
 162   the mechanism.  We use the ``filter`` attribute to specify the type of automatic
 163   checking/formatting to apply.  Custom attributes are used for specifying some
 164   build system dependencies for easier processing in CMake.
 165
 166 include-what-you-use