docs/dev-manual/tools.rst

   1 Development-time tools
   2 ======================
   3
   4 .. toctree::
   5    :maxdepth: 2
   6
   7    doxygen
   8    jenkins
   9    gmxtree
  10    uncrustify
  11    testutils
  12
  13 .. TODO: Consider what is the most reasonable structure; currently, this list
  14    here does not make much sense in the overall organization and creates a
  15    confusing TOC for the developer guide.
  16
  17 .. TODO: Add details for most of the tools, either in the form of links to wiki,
  18    or to a separate page that explains more details.
  19
  20 Change management
  21 -----------------
  22
  23 git
  24   |Gromacs| uses git as the version control system.
  25   Instructions for setting up git for |Gromacs|, as well as tips and tricks for
  26   its use, can be found on the wiki: `Git Tips & Tricks`_
  27
  28   Other basic tutorial material for ``git`` can be found on the web.
  29
  30 Gerrit
  31   All code changes go through a code review system at
  32   http://gerrit.gromacs.org.
  33
  34 Jenkins
  35   All changes pushed to Gerrit are automatically compiled and otherwise
  36   checked on various platforms using a continuous integration system at
  37   http://jenkins.gromacs.org.
  38   :doc:`jenkins` documents how Jenkins interacts with the build system,
  39   providing information on how to replicate the builds Jenkins does (e.g., to
  40   diagnose issues).
  41
  42 Redmine
  43   Bugs and issues, as well as some random features and discussions,
  44   are tracked at http://redmine.gromacs.org.
  45
  46 .. _Git Tips & Tricks: http://www.gromacs.org/index.php?title=Developer_Zone/Git/Git_Tips_%26_Tricks
  47
  48 Build system
  49 ------------
  50
  51 .. TODO: details, ASAN, others?
  52
  53 CMake
  54   Main tool used in the build system.
  55
  56 packaging for distribution (CPack)
  57
  58 unit testing (CTest)
  59   |Gromacs| uses a unit testing framework based on Google C++ Testing
  60   Framework (gtest) and CTest.  All unit tests are automatically run on Jenkins
  61   for each commit.
  62   Details can be found on a separate page on :doc:`testutils`.
  63
  64 regression tests
  65
  66 cppcheck
  67   `cppcheck <http://cppcheck.sourceforge.net>`_ is used for static code
  68   analysis, and is run automatically on Jenkins for each commit.  Different rules
  69   are used for C and C++ code (with stricter checking for C++ code, as that is
  70   newer).  The build system provides a ``cppcheck`` target (produced from
  71   ``tests/CppCheck.cmake``) to run the tool.  This target is used also by Jenkins.
  72
  73 clang static analyzer
  74
  75 .. _dev-formatting-tools:
  76
  77 Code formatting and style
  78 -------------------------
  79
  80 The tools and scripts listed below are used to automatically check/apply
  81 formatting that follows |Gromacs| style guidelines described on a separate page:
  82 :doc:`style`.
  83
  84 uncrustify
  85   `uncrustify <http://uncrustify.sourceforge.net>`_ is used for automatic
  86   indentation and other formatting of the source code to follow
  87   :doc:`formatting`.  All code must remain invariant under uncrustify
  88   with the config at ``admin/uncrustify.cfg``.  A patched version of uncrustify is
  89   used.  See :doc:`uncrustify` for details.
  90
  91 ``admin/copyright.py``
  92   This Python script adds and formats copyright headers in source files.
  93   ``uncrustify.sh`` (see below) uses the script to check/update copyright years on
  94   changed files automatically.
  95
  96 ``admin/uncrustify.sh``
  97   This ``bash`` script runs uncrustify and ``copyright.py`` for all
  98   files that have local changes and checks that they conform to the prescribed
  99   style.  Optionally, the script can also apply changes to make the files
 100   conform.
 101   This script is automatically run by Jenkins to ensure that all commits adhere
 102   to :doc:`formatting`.  If the uncrustify job does not succeed, it
 103   means that this script has something to complain.
 104   See :doc:`uncrustify` for details.
 105
 106 ``admin/git-pre-commit``
 107   This sample git pre-commit hook can be used if one wants to apply
 108   ``uncrustify.sh`` automatically before every commit to check for formatting
 109   issues.  See :doc:`uncrustify` for details.
 110
 111 ``docs/doxygen/includesorter.py``
 112   This Python script sorts and reformats #include directives according to
 113   the guidelines at :doc:`includestyle`.  Details are documented on a
 114   separate page (with the whole suite of Python scripts used for source code
 115   checks): :ref:`dev-include-sorter`.
 116
 117 include directive checker
 118   In its present form, the above include sorter script cannot be conveniently
 119   applied in ``uncrustify.sh``.  To check for issues, it is instead integrated into
 120   a ``check-source`` build target.  When this target is built, it also checks for
 121   include formatting issues.  Internally, it uses the sorter script.  This check
 122   is run in Jenkins as part of the Documentation job.
 123   Details for the checking mechanism are on a separate page (common for several
 124   checkers): :doc:`gmxtree`.
 125
 126 ``admin/reformat_all.sh``
 127   This ``bash`` script runs uncrustify/``copyright.py``/include sorter
 128   on all relevant files in the source tree (or in a particular directory).
 129   The script can also produce the list of files where these scripts are applied,
 130   for use with other scripts.  See :doc:`uncrustify` for details.
 131
 132 git attributes
 133   git attributes (specified in ``.gitattributes`` files) are used to annotate
 134   which files are subject to automatic formatting checks (and for automatic
 135   reformatting by the above scripts).  See ``man gitattributes`` for an overview of
 136   the mechanism.  We use the ``filter`` attribute to specify the type of automatic
 137   checking/formatting to apply.  Custom attributes are used for specifying some
 138   build system dependencies for easier processing in CMake.
 139
 140 include-what-you-use
 141
 142 Documentation generation
 143 ------------------------
 144
 145 Building the |Gromacs| documentation
 146 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 147
 148 .. TODO: Move this onto a separate page
 149
 150 For now, there are multiple components, formats and tools for the
 151 |Gromacs| documentation, which is aimed primarily at version-specific
 152 deployment of the complete documentation on the website.
 153
 154 This is quite complex, because the dependencies for building the
 155 documentation must not get in the way of building the code
 156 (particularly when cross-compiling), and yet the code must build and
 157 run in order for some documentation to be generated. Also, man page
 158 documentation (and command-line completions) must be built from the
 159 wrapper binary, in order to be bundled into the tarball.
 160
 161 The outputs of interest to most developers are generally produced in the
 162 ``docs/html/`` subdirectory of the build tree.
 163
 164 You need to enable at least some of the following CMake options:
 165
 166 ``GMX_BUILD_MANUAL``
 167   Option needed for trying to build the PDF reference manual
 168   (requires LaTeX and ImageMagick)
 169 ``GMX_BUILD_HELP``
 170   Option that controls 1) whether shell completions are built automatically,
 171   and 2) whether built man pages are installed if available (the user still needs
 172   to build the ``man`` target manually before installing)
 173
 174 Some documentation cannot be built if the CMake option
 175 ``GMX_BUILD_MDRUN_ONLY`` is enabled, or when cross-compiling, as it
 176 requires executing the ``gmx`` binary.
 177
 178 The following make targets are the most useful:
 179
 180 ``manual``
 181   Builds the PDF reference manual
 182 ``man``
 183   Makes man pages from the wrapper binary with Sphinx
 184 ``doxygen-all``
 185   Makes the code documentation with Doxygen
 186 ``install-guide``
 187   Makes the INSTALL file for the tarball with Sphinx
 188 ``webpage-sphinx``
 189   Makes all the components of the GROMACS webpage that require Sphinx,
 190   including install guide and user guide.
 191 ``webpage``
 192   Makes the complete GROMACS webpage, requires everything. When complete,
 193   you can browse ``docs/html/index.html`` to find everything.
 194
 195   If built from a release tarball, the ``SOURCE_MD5SUM``,
 196   ``SOURCE_TARBALL``, ``REGRESSIONTESTS_MD5SUM``, and
 197   ``REGRESSIONTESTS_TARBALL`` CMake variables can be set to pass in
 198   the md5sum values and names of those tarballs, for embedding into the
 199   final deployment to the |Gromacs| website.
 200
 201 The following tools are used in building parts of the documentation.
 202
 203 Doxygen
 204   `Doxygen <http://www.doxygen.org>`_ is used to extract documentation from
 205   source code comments.  Also some other overview
 206   content is laid out by Doxygen from Markdown source files.  Currently, version
 207   |EXPECTED_DOXYGEN_VERSION| is required for a warning-free build.  Thorough
 208   explanation of the Doxygen setup and instructions for documenting the source
 209   code can be found on a separate page: :doc:`doxygen`.
 210
 211 graphviz (dot)
 212   The Doxygen documentation uses ``dot`` from `graphviz
 213   <http://www.graphviz.org>`_ for building some graphs.  The tool is not
 214   mandatory, but the Doxygen build will produce warnings if it is not
 215   available, and the graphs are omitted from the documentation.
 216
 217 mscgen
 218   The Doxygen documentation uses `mscgen
 219   <http://www.mcternan.me.uk/mscgen/>`_ for building some graphs.  As with ``dot``,
 220   the tool is not mandatory, but not having it available will result in warnings
 221   and missing graphs.
 222
 223 Doxygen issue checker
 224   Doxygen produces warnings about some incorrect uses and wrong
 225   documentation, but there are many common mistakes that it does not detect.
 226   |Gromacs| uses an additional, custom Python script to check for such issues.
 227   This is most easily invoked through a ``check-source`` target in the build system.
 228   The script also checks that documentation for a header matches its use in the
 229   source code (e.g., that a header documented as internal to a module is not
 230   actually used from outside the module).  These checks are run in Jenkins as
 231   part of the Documentation job.  Details for the custom checker are on a
 232   separate page (common for several checkers): :doc:`gmxtree`.
 233
 234 module dependency graphs
 235   |Gromacs| uses a custom Python script to generate an annotated dependency
 236   graph for the code, showing #include dependencies between modules.
 237   The generated graph is embedded into the Doxygen documentation:
 238   `Module dependency graph`__
 239   This script shares most of its implementation with the custom checkers, and is
 240   documented on the same page: :doc:`gmxtree`.
 241
 242 __ doxygen-page-modulegraph_
 243
 244 Sphinx
 245   `Sphinx <http://sphinx-doc.org/>`_; at least version 1.2.3) is used
 246   for building some parts of the documentation from reStructuredText
 247   source files.
 248
 249 LaTeX
 250   Also requires ImageMagick for converting graphics file formats.
 251
 252 linkchecker
 253
 254 documentation exported from source files
 255   For man pages, HTML documentation of command-line options for executables,
 256   and for shell completions, the ``gmx`` binary has explicit C++ code to export
 257   the information required.  The build system provides targets that then invoke
 258   the built ``gmx`` binary to produce these documentation items.  The generated
 259   items are packaged into source tarballs so that this is not necessary when
 260   building from a source distribution (since in general, it will not work in
 261   cross-compilation scenarios).  To build and install these from a git
 262   distribution, explicit action is required.
 263   See `Doxygen documentation on the wrapper binary`__
 264   for some additional details.
 265
 266 __ doxygen-page-wrapperbinary_
 267
 268 .. include:: /fragments/doxygen-links.rst