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 ``GMX_BUILD_WEBPAGE``
 166   Option needed for compiling all the documentation into the webpage
 167
 168 Some documentation cannot be built if the CMake option
 169 ``GMX_BUILD_MDRUN_ONLY`` is enabled, or when cross-compiling, as it
 170 requires executing the ``gmx`` binary.
 171
 172 The following make targets are the most useful:
 173
 174 ``manual``
 175   Builds the PDF reference manual
 176 ``man``
 177   Makes man pages from the wrapper binary with Sphinx
 178 ``doxygen-all``
 179   Makes the code documentation with Doxygen
 180 ``install-guide``
 181   Makes the INSTALL file for the tarball with Sphinx
 182 ``webpage-sphinx``
 183   Makes all the components of the GROMACS webpage that require Sphinx,
 184   including install guide and user guide.
 185 ``webpage``
 186   Makes the complete GROMACS webpage, requires everything. When complete,
 187   you can browse ``docs/html/index.html`` to find everything.
 188
 189   If built from a release tarball, the ``SOURCE_MD5SUM``,
 190   ``SOURCE_TARBALL``, ``REGRESSIONTESTS_MD5SUM``, and
 191   ``REGRESSIONTESTS_TARBALL`` CMake variables can be set to pass in
 192   the md5sum values and names of those tarballs, for embedding into the
 193   final deployment to the |Gromacs| website.
 194
 195 The following tools are used in building parts of the documentation.
 196
 197 Doxygen
 198   `Doxygen <http://www.doxygen.org>`_ is used to extract documentation from
 199   source code comments.  Also some other overview
 200   content is laid out by Doxygen from Markdown source files.  Currently, version
 201   1.8.5 is required for a warning-free build.  Thorough explanation of the
 202   Doxygen setup and instructions for documenting the source code can be found on
 203   a separate page: :doc:`doxygen`.
 204
 205 graphviz (dot)
 206   The Doxygen documentation uses ``dot`` from `graphviz
 207   <http://www.graphviz.org>`_ for building some graphs.  The tool is not
 208   mandatory, but the Doxygen build will produce warnings if it is not
 209   available, and the graphs are omitted from the documentation.
 210
 211 mscgen
 212   The Doxygen documentation uses `mscgen
 213   <http://www.mcternan.me.uk/mscgen/>`_ for building some graphs.  As with ``dot``,
 214   the tool is not mandatory, but not having it available will result in warnings
 215   and missing graphs.
 216
 217 Doxygen issue checker
 218   Doxygen produces warnings about some incorrect uses and wrong
 219   documentation, but there are many common mistakes that it does not detect.
 220   |Gromacs| uses an additional, custom Python script to check for such issues.
 221   This is most easily invoked through a ``check-source`` target in the build system.
 222   The script also checks that documentation for a header matches its use in the
 223   source code (e.g., that a header documented as internal to a module is not
 224   actually used from outside the module).  These checks are run in Jenkins as
 225   part of the Documentation job.  Details for the custom checker are on a
 226   separate page (common for several checkers): :doc:`gmxtree`.
 227
 228 module dependency graphs
 229   |Gromacs| uses a custom Python script to generate an annotated dependency
 230   graph for the code, showing #include dependencies between modules.
 231   The generated graph is embedded into the Doxygen documentation:
 232   `Module dependency graph`__
 233   This script shares most of its implementation with the custom checkers, and is
 234   documented on the same page: :doc:`gmxtree`.
 235
 236 __ doxygen-page-modulegraph_
 237
 238 Sphinx
 239   `Sphinx <http://sphinx-doc.org/>`_; at least version 1.2.3) is used
 240   for building some parts of the documentation from reStructuredText
 241   source files.
 242
 243 LaTeX
 244   Also requires ImageMagick for converting graphics file formats.
 245
 246 linkchecker
 247
 248 documentation exported from source files
 249   For man pages, HTML documentation of command-line options for executables,
 250   and for shell completions, the ``gmx`` binary has explicit C++ code to export
 251   the information required.  The build system provides targets that then invoke
 252   the built ``gmx`` binary to produce these documentation items.  The generated
 253   items are packaged into source tarballs so that this is not necessary when
 254   building from a source distribution (since in general, it will not work in
 255   cross-compilation scenarios).  To build and install these from a git
 256   distribution, explicit action is required.
 257   See `Doxygen documentation on the wrapper binary`__
 258   for some additional details.
 259
 260 __ doxygen-page-wrapperbinary_
 261
 262 .. include:: doxygen-links.rst