docs/dev-manual/tools.rst

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