docs/dev-manual/jenkins.rst

   1 Understanding Jenkins builds
   2 ============================
   3
   4 This page documents what different Jenkins builds actually run from the
   5 |Gromacs| source tree.  The purpose is two-fold:
   6
   7 * Provide information on how to interpret Jenkins failures and how to run the
   8   same tasks locally to diagnose issues.
   9 * Provide information on what changes in the build system (or other parts of
  10   the repository) need special care to not break Jenkins builds.
  11
  12 .. TODO: Add a link to a wiki page about general Jenkins documentation, once
  13    there is more of that.
  14
  15 cppcheck build
  16 --------------
  17
  18 This build runs the :command:`cppcheck` static analysis tool.  Any issues found
  19 mark the build unstable, and can be browsed in Jenkins.
  20
  21 It runs :command:`cmake` to generate the build system, and then builds the
  22 ``cppcheck`` target.  Nothing is compiled by this target, it only runs
  23 :command:`cppcheck` for the designated source files.  The CMake configuration
  24 options do not affect the set of files checked, but they do affect the checked
  25 code through :file:`config.h` and such.
  26
  27 Documentation build
  28 -------------------
  29
  30 This build builds various types of documentation:
  31
  32 * PDF reference manual using LaTeX
  33 * Doxygen documentation extracted from the source code
  34 * Set of HTML pages containing an installation guide, a user guide, and a
  35   developer guide, as well as links to the above.  This set of HTML pages can
  36   be browsed from Jenkins.
  37 * Man pages
  38 * INSTALL text file
  39
  40 The last three require building the :file:`gmx` binary and running it, so
  41 compilation failures will also show in this build.
  42 All log files that contain warnings are archived as artifacts in the build, and
  43 presence of any warnings marks the build unstable.  Brief description of which
  44 part failed is reported back to Gerrit.
  45
  46 Additionally, the build runs some source code checks that rely on the Doxygen
  47 documentation.  See the description of the ``check-source`` target in
  48 :doc:`gmxtree`.
  49
  50 :doc:`doxygen` provides general guidelines for Doxygen usage, which can be
  51 helpful in understanding and solving Doxygen warnings and some of the
  52 ``check-source`` issues.
  53 :doc:`includestyle` provides guidelines for #include order and style, which is
  54 another part of ``check-source`` checks.
  55
  56 Technically, the documentation build runs :file:`admin/build-docs.sh`.
  57 See that file for details of what it exactly builds and how.  Most changes in the
  58 documentation build system will require changes in this script, but Jenkins
  59 configuration should be more static.
  60
  61 uncrustify build
  62 ----------------
  63
  64 This build checks the source code for formatting such as consistent indentation
  65 and use of braces, as well as for copyright headers.  See :doc:`formatting` for
  66 the guidelines that are enforced.
  67
  68 Technically, the build simply runs :file:`admin/run-uncrustify.sh` to check the
  69 formatting in the changes for the commit.
  70 If the any changes are required, the build is marked unstable.
  71 If the script completely fails (should be rare), the build fails.
  72 A file with issues found by the script is archived as an artifact in the build,
  73 and a summary is reported back to Gerrit (or the actual issues if there are
  74 only a few).
  75 See :doc:`uncrustify` for more details on uncrustify and on scripts to run it.
  76
  77 .. TODO: Provide links to the build system page, once there are on the git
  78    commit chain...
  79
  80 .. TODO: Document all the rest.