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