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    jenkins
  12    releng/index
  13    gmxtree
  14    uncrustify
  15    testutils
  16    physical_validation
  17
  18 .. TODO: Consider what is the most reasonable structure; currently, this list
  19    here does not make much sense in the overall organization and creates a
  20    confusing TOC for the developer guide.
  21
  22 .. TODO: Add details for most of the tools, either in the form of links to wiki,
  23    or to a separate page that explains more details.
  24
  25 Change management
  26 -----------------
  27
  28 |Gromacs| change management is supported by the following tools.
  29 (For change submission guidelines, refer to :doc:`contribute`.)
  30
  31 git
  32   |Gromacs| uses `git <https://git-scm.com/>`__ as the version control system.
  33   Instructions for setting up git for |Gromacs|, as well as tips and tricks for
  34   its use, can be found in :doc:`change-management`.
  35
  36   Other basic tutorial material for ``git`` can be found on the `web <https://git-scm.com/doc/ext>`__.
  37
  38 Gerrit
  39   All code changes go through a code review system at
  40   http://gerrit.gromacs.org.
  41
  42 Jenkins
  43   All changes pushed to Gerrit are automatically compiled and otherwise
  44   checked on various platforms using a continuous integration system at
  45   http://jenkins.gromacs.org.
  46   :doc:`jenkins` documents how Jenkins interacts with the build system,
  47   providing information on how to replicate the builds Jenkins does (e.g., to
  48   diagnose issues).
  49   :doc:`releng/index` provides more information on the technical implementation
  50   of the builds.
  51
  52 Redmine
  53   Bugs and issues, as well as some random features and discussions,
  54   are tracked at http://redmine.gromacs.org.
  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 ccache
  67   When the `ccache <https://ccache.samba.org>`_ caching compiler wrapper is
  68   found on the PATH, we attempt to set up a caching compiler wrapper for CMake
  69   builds. Not all compilers are supported. Refer to the ``ENABLE_CCACHE``
  70   option in ``CMakeLists.txt`` and to ``cmake/gmxCcache.cmake``
  71   for details. Please submit updates if you find that the current
  72   configuration is too conservative.
  73
  74 packaging for distribution (CPack)
  75
  76 unit testing (CTest)
  77   |Gromacs| uses a unit testing framework based on Google C++ Testing
  78   Framework (gtest) and CTest.  All unit tests are automatically run on Jenkins
  79   for each commit.
  80   Details can be found on a separate page on :doc:`testutils`.
  81
  82 regression tests
  83
  84 clang-tidy
  85   `clang-tidy <http://releases.llvm.org/6.0.0/tools/clang/tools/extra/docs/clang-tidy/index.html>`_
  86   is used for static code analysis. clang-tidy is easy to install. It is contained in
  87   the llvm binary `package <http://releases.llvm.org/download.html#6.0.0>`_. Only
  88   version 6.0.* is supported. Others might miss tests or give false positives.
  89   It is run automatically on Jenkins for each commit. Many checks have fixes which can automatically be
  90   applied. To run it, the build has to be configured with
  91   ``cmake -DGMX_CLANG_TIDY=ON -DGMX_OPENMP=no -DCMAKE_BUILD_TYPE=Debug -DCMAKE_EXPORT_COMPILE_COMMANDS=on``.
  92   Any ``CMAKE_BUILD_TYPE`` which enables asserts (e.g. ASAN) works. Such a configured build will
  93   run both the compiler as well as clang-tidy when building. The name of the clang-tidy executable is set with
  94 ``-DCLANG_TIDY=...``, and the full path to it can be set with ``-DCLANG_TIDY_EXE=...``.
  95   To apply the automatic fixes to the issue identified clang-tidy should be run sepereately (running clang-tidy
  96   with ``-fix`` as part of the build can corrupt header files). To fix a specific file run
  97   ``clang-tidy -fix -header-filter '.*' {file}``, to fix all files in parallel
  98   ``run-clang-tidy.py -fix -header-filter '.*' '(?<!/selection/parser\.cpp|selection/scanner\.cpp)$'``,
  99   and to fix all modified files ``run-clang-tidy.py -fix -header-filter '.*' $(git diff HEAD --name-only)``.
 100   The run-clang-tidy.py script is in the
 101   ``share/clang/`` subfolder of the llvm distribution. ``clang-tidy`` has to be able to find the
 102   ``compile_commands.json`` file. Eithe run from the build folder or add a symlink to the source folder.
 103
 104 clang static analyzer
 105
 106 coverage
 107
 108 .. _dev-formatting-tools:
 109
 110 Code formatting and style
 111 -------------------------
 112
 113 The tools and scripts listed below are used to automatically check/apply
 114 formatting that follows |Gromacs| style guidelines described on a separate page:
 115 :doc:`style`.
 116
 117 uncrustify
 118   `uncrustify <http://uncrustify.sourceforge.net>`_ is used for automatic
 119   indentation and other formatting of the source code to follow
 120   :doc:`formatting`.  All code must remain invariant under uncrustify
 121   with the config at ``admin/uncrustify.cfg``.  A patched version of uncrustify is
 122   used.  See :doc:`uncrustify` for details.
 123
 124 ``admin/copyright.py``
 125   This Python script adds and formats copyright headers in source files.
 126   ``uncrustify.sh`` (see below) uses the script to check/update copyright years on
 127   changed files automatically.
 128
 129 ``admin/uncrustify.sh``
 130   This ``bash`` script runs uncrustify and ``copyright.py`` for all
 131   files that have local changes and checks that they conform to the prescribed
 132   style.  Optionally, the script can also apply changes to make the files
 133   conform.
 134   This script is automatically run by Jenkins to ensure that all commits adhere
 135   to :doc:`formatting`.  If the uncrustify job does not succeed, it
 136   means that this script has something to complain.
 137   See :doc:`uncrustify` for details.
 138
 139 ``admin/git-pre-commit``
 140   This sample git pre-commit hook can be used if one wants to apply
 141   ``uncrustify.sh`` automatically before every commit to check for formatting
 142   issues.  See :doc:`uncrustify` for details.
 143
 144 ``docs/doxygen/includesorter.py``
 145   This Python script sorts and reformats #include directives according to
 146   the guidelines at :doc:`includestyle`.  Details are documented on a
 147   separate page (with the whole suite of Python scripts used for source code
 148   checks): :ref:`dev-include-sorter`.
 149
 150 include directive checker
 151   In its present form, the above include sorter script cannot be conveniently
 152   applied in ``uncrustify.sh``.  To check for issues, it is instead integrated into
 153   a ``check-source`` build target.  When this target is built, it also checks for
 154   include formatting issues.  Internally, it uses the sorter script.  This check
 155   is run in Jenkins as part of the Documentation job.
 156   Details for the checking mechanism are on a separate page (common for several
 157   checkers): :doc:`gmxtree`.
 158
 159 ``admin/reformat_all.sh``
 160   This ``bash`` script runs uncrustify/``copyright.py``/include sorter
 161   on all relevant files in the source tree (or in a particular directory).
 162   The script can also produce the list of files where these scripts are applied,
 163   for use with other scripts.  See :doc:`uncrustify` for details.
 164
 165 git attributes
 166   git attributes (specified in ``.gitattributes`` files) are used to annotate
 167   which files are subject to automatic formatting checks (and for automatic
 168   reformatting by the above scripts).  See ``man gitattributes`` for an overview of
 169   the mechanism.  We use the ``filter`` attribute to specify the type of automatic
 170   checking/formatting to apply.  Custom attributes are used for specifying some
 171   build system dependencies for easier processing in CMake.
 172
 173 include-what-you-use