docs/dev-manual/jenkins.rst

   1 Understanding Jenkins builds
   2 ============================
   3
   4 This page documents what different Jenkins builds actually run at
   5 http://jenkins.gromacs.org/ from the |Gromacs| source tree.
   6 The purpose is two-fold:
   7
   8 * Provide information on how to interpret Jenkins failures and how to run the
   9   same tasks locally to diagnose issues (in most cases, referring to the
  10   special targets described in :doc:`build-system`).
  11 * Provide information on what changes in the build system (or other parts of
  12   the repository) need special care to not break Jenkins builds.
  13
  14 .. todo:: Add a link to a wiki page about general Jenkins documentation, once
  15    there is more of that.
  16
  17 Pre-submit verification
  18 -----------------------
  19
  20 The following builds are triggered for each patch set uploaded to Gerrit.
  21
  22 Compilation and tests
  23 ^^^^^^^^^^^^^^^^^^^^^
  24
  25 The main build compiles |Gromacs| with different configurations and runs the
  26 tests.  The configurations used for Jenkins verification are specified in
  27 :file:`admin/builds/pre-submit-matrix.txt`.
  28
  29 The exact build sequence can be found in :file:`admin/builds/gromacs.py`,
  30 including the logic that translates the build options in the matrix file to
  31 CMake options.
  32
  33 Documentation
  34 ^^^^^^^^^^^^^
  35
  36 This build builds various types of documentation:
  37
  38 * PDF reference manual using LaTeX
  39 * Doxygen documentation extracted from the source code
  40 * Set of HTML pages containing an installation guide, a user guide, and a
  41   developer guide, as well as links to the above.  This set of HTML pages can
  42   be browsed from Jenkins.
  43 * Man pages
  44 * INSTALL text file
  45
  46 The last three require building the :file:`gmx` binary and running it, so
  47 compilation failures will also show in this build.
  48 All log files that contain warnings are archived as artifacts in the build, and
  49 presence of any warnings marks the build unstable.  Brief description of which
  50 part failed is reported back to Gerrit.
  51
  52 Additionally, the build runs some source code checks that rely on the Doxygen
  53 documentation.  See the description of the ``check-source`` target in
  54 :doc:`gmxtree`.
  55
  56 :doc:`doxygen` provides general guidelines for Doxygen usage, which can be
  57 helpful in understanding and solving Doxygen warnings and some of the
  58 ``check-source`` issues.
  59 :doc:`includestyle` provides guidelines for #include order and style, which is
  60 another part of ``check-source`` checks.
  61
  62 The exact build sequence is in :file:`admin/builds/documentation.py`.
  63 See that file for details of what it exactly builds and how.  Most changes in the
  64 documentation build system will require changes in this script, but Jenkins
  65 configuration should be more static.
  66
  67 clang static analysis
  68 ^^^^^^^^^^^^^^^^^^^^^
  69
  70 The file :file:`admin/builds/clang-analyzer.py` specifies the exact build
  71 sequence and the CMake cache variables used for clang static analysis.  This
  72 file also specifies the clang version used for the analysis, as well as the C++
  73 compiler used (``clang-static-analyzer-<version>``).
  74
  75 To run the analysis outside Jenkins, you should run both ``cmake`` and ``make``
  76 under ``scan-build`` command using the same CMake cache variables as in the
  77 build script. When you do the initial CMake configuration with ``scan-build``,
  78 it sets the C++ compiler to the analyzer. Note that using ``scan-build`` like
  79 this will also analyze C code, but Jenkins ignores C code for analysis. This
  80 can result in extra warnings, which can be suppressed by manually setting
  81 CMAKE_C_COMPILER to a value other than Clang static analyzer.
  82
  83 uncrustify
  84 ^^^^^^^^^^
  85
  86 This build checks for source code formatting issues with uncrustify, and enforces
  87 the copyright style.  See :doc:`formatting` for the guidelines that are enforced.
  88
  89 The exact build sequence is in :file:`admin/builds/uncrustify.py`, which
  90 essentially just runs ::
  91
  92   admin/uncrustify.sh check --rev=HEAD^
  93
  94 If the any changes are required, the build is marked unstable.
  95 If the script completely fails (should be rare), the build fails.
  96 A file with issues found by the script is archived as an artifact in the build,
  97 and a summary is reported back to Gerrit (or the actual issues if there are
  98 only a few).
  99 See :doc:`code-formatting` for more details on code-formatting tools
 100 and on scripts to run them.
 101
 102 clang-format
 103 ^^^^^^^^^^^^
 104
 105 This build checks and enforces code formatting, e.g.,  indentation.
 106 Also, a second part of the build enforces the source code formatting.
 107 As above, see :doc:`formatting` for the style guidelines.
 108
 109 The build runs according to :file:`admin/builds/clang-format.py`, resulting
 110 in running ::
 111
 112  admin/clang-format.sh check --rev=HEAD^
 113
 114 The build is marked unstable if the code formatting resulted in
 115 any changes to the source code.
 116
 117 On-demand builds
 118 ----------------
 119
 120 These builds can be triggered on request for certain changes in Gerrit, or
 121 manually from Jenkins.  See :ref:`releng-triggering-builds` for details on
 122 how to trigger these.
 123
 124 Coverage
 125 ^^^^^^^^
 126
 127 This build compiles one configuration of |Gromacs| with instrumentation for
 128 coverage, runs the tests, and produces a coverage report using gcovr.
 129 The report can be browsed on Jenkins.
 130
 131 The exact build sequence is in :file:`admin/builds/coverage.py`, including
 132 specification of the configuration tested.
 133
 134 Source tarball
 135 ^^^^^^^^^^^^^^
 136
 137 This build creates the source tarball for distribution.  Some of the content
 138 that is put into the tarball is generated by executing the :command:`gmx`
 139 binary, so this build also compiles the source code (with a minimal set of
 140 options).
 141
 142 The build compiles the code and those targets that generate content necessary
 143 for the tarball, followed by building the ``package_source`` target.
 144 After that, it just generates a file that is used by other builds.
 145
 146 The exact build sequence is in :file:`admin/builds/source-package.py`.
 147
 148 Release workflow
 149 ^^^^^^^^^^^^^^^^
 150
 151 This build creates source and regressiontest tarballs, builds, installs, and
 152 tests a few configuration using those, and builds documentation to be placed on
 153 the documentation web site for a new release.  The set of configurations tested
 154 is specified in :file:`admin/builds/release-matrix.txt`.
 155
 156 The exact build sequence is desribed in :ref:`releng-workflow-release`.
 157 The build uses the source tarball build as a subbuild, and parts of the build
 158 are executed using :file:`admin/builds/gromacs.py` and
 159 :file:`admin/builds/documentation.py`.
 160
 161 :file:`admin/builds/get-version-info.py` is used for getting the version
 162 information from the source tree as part of this workflow.
 163
 164 :file:`admin/builds/update-regtest-hash.py` has logic to update the
 165 regressiontests tarball MD5 sum for the released tarball automatically.
 166
 167 Updating regressiontests data
 168 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 169
 170 Sometimes we add new tests to the regressiontests repository. Also, as
 171 the source code or data files change, it is sometimes necessary to
 172 update regressiontests. This requires a particular CMake build type
 173 and both a single and double-precision build of |Gromacs| to generate
 174 all the data. Jenkins can automate much of the tedium here.
 175
 176 * Upload a regressiontests change that lacks the relevant reference
 177   data (either because you deleted the outdated data, or because the
 178   test is new). Jenkins will do the normal thing, which we ignore.
 179   There is now a Gerrit patch number for that change, symbolized here
 180   with ``MMMM``.
 181
 182 * Go to change ``MMMM`` on gerrit, select the patch set you want to
 183   update with new reference data (usually the latest one), and comment
 184
 185     ``[JENKINS] Update``
 186
 187   to update against the HEAD of the matching source-code branch, or
 188
 189     ``[JENKINS] Cross-verify NNNN update``
 190
 191   to update from builds of |Gromacs| from the latest version of
 192   Gerrit source-code patch ``NNNN``. You will need to do this when
 193   functionality changes in ``NNNN`` affect either the layout of
 194   the files in the reference data, or the results of the simulation,
 195   or the results of the subsequent analysis.
 196
 197 * Eventually, Jenkins will upload a new version of the regressiontests
 198   patch to Gerrit, which will contain the updated regressiontest data.
 199   That upload will again trigger Jenkins to do the normal pre-submit
 200   verify, which will now pass (but perhaps will only pass under
 201   cross-verify with patch ``NNNN``, as above).
 202
 203 * Later, if you later need to verify an updated version of source-code
 204   patch ``NNNN`` against the newly generated reference data, go to the
 205   source-code patch ``NNNN`` and comment
 206
 207     ``[JENKINS] Cross-verify MMMM``