From bc67cecb483881fe140dda7efb286404c382676b Mon Sep 17 00:00:00 2001 From: Teemu Murtola Date: Fri, 5 Jun 2015 14:20:41 +0300 Subject: [PATCH] Initial docs for Jenkins integration Add basic documentation for (some) of the Jenkins builds from the perspective of how they interact with the build system. This part cannot change without changes in the build system and so can be documented in the same repository as the build system. And the developer guide is a place where people would (hopefully) first look for this kind of information. Links can be provided to more documentation on Jenkins usage and other configuration (e.g., on the wiki), once that stabilizes. Related to #1731. Change-Id: I87e180d12a77c692ac4594b6c062fb6ca150aa5d --- docs/CMakeLists.txt | 1 + docs/dev-manual/jenkins.rst | 81 +++++++++++++++++++++++++++++++++++++ docs/dev-manual/tools.rst | 8 ++++ 3 files changed, 90 insertions(+) create mode 100644 docs/dev-manual/jenkins.rst diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt index 9f08d24e69..9c39281249 100644 --- a/docs/CMakeLists.txt +++ b/docs/CMakeLists.txt @@ -104,6 +104,7 @@ if (SPHINX_FOUND) dev-manual/formatting.rst dev-manual/gmxtree.rst dev-manual/includestyle.rst + dev-manual/jenkins.rst dev-manual/naming.rst dev-manual/overview.rst dev-manual/relocatable-binaries.rst diff --git a/docs/dev-manual/jenkins.rst b/docs/dev-manual/jenkins.rst new file mode 100644 index 0000000000..13d0cc94e4 --- /dev/null +++ b/docs/dev-manual/jenkins.rst @@ -0,0 +1,81 @@ +Understaning Jenkins builds +=========================== + +This page documents what different Jenkins builds actually run from the +|Gromacs| source tree. The purpose is two-fold: + +* Provide information on how to interpret Jenkins failures and how to run the + same tasks locally to diagnose issues. +* Provide information on what changes in the build system (or other parts of + the repository) need special care to not break Jenkins builds. + +.. TODO: Add a link to a wiki page about general Jenkins documentation, once + there is more of that. + +cppcheck build +-------------- + +This build runs the :command:`cppcheck` static analysis tool. Any issues found +mark the build unstable, and can be browsed in Jenkins. + +It runs :command:`cmake` to generate the build system, and then builds the +``cppcheck`` target. Nothing is compiled by this target, it only runs +:command:`cppcheck` for the designated source files. The CMake configuration +options do not affect the set of files checked, but they do affect the checked +code through :file:`config.h` and such. + +Documentation build +------------------- + +This build builds various types of documentation: + +* PDF reference manual using LaTeX +* Doxygen documentation extracted from the source code +* Set of HTML pages containing an installation guide, a user guide, and a + developer guide, as well as links to the above. This set of HTML pages can + be browsed from Jenkins. +* Man pages +* INSTALL text file + +The last three require building the :file:`gmx` binary and running it, so +compilation failures will also show in this build. +All log files that contain warnings are archived as artifacts in the build, and +presence of any warnings marks the build unstable. Brief description of which +part failed is reported back to Gerrit. + +Additionally, the build runs some source code checks that rely on the Doxygen +documentation. See the description of the ``check-source`` target in +:doc:`gmxtree`. + +:doc:`doxygen` provides general guidelines for Doxygen usage, which can be +helpful in understanding and solving Doxygen warnings and some of the +``check-source`` issues. +:doc:`includestyle` provides guidelines for #include order and style, which is +another part of ``check-source`` checks. + +Technically, the documentation build runs :file:`admin/build-docs.sh`. +See that file for details of what it exactly builds and how. Most changes in the +documentation build system will require changes in this script, but Jenkins +configuration should be more static. + +uncrustify build +---------------- + +This build checks the source code for formatting such as consistent indentation +and use of braces, as well as for copyright headers. See :doc:`formatting` for +the guidelines that are enforced. + +Technically, the build simply runs :file:`admin/uncrustify.sh` as :: + + admin/uncrustify.sh check --rev=HEAD^ + +to check the formatting in the changes for the commit. +If the return value is non-zero (i.e., any changes would be required), the +build is marked unstable. +Currently, only the console log of the build shows what actually was the issue. +See :doc:`uncrustify` for more details on the script and uncrustify. + +.. TODO: Provide links to the build system page, once there are on the git + commit chain... + +.. TODO: Document all the rest. diff --git a/docs/dev-manual/tools.rst b/docs/dev-manual/tools.rst index 43bce33b84..08a77a6312 100644 --- a/docs/dev-manual/tools.rst +++ b/docs/dev-manual/tools.rst @@ -5,10 +5,15 @@ Development-time tools :maxdepth: 2 doxygen + jenkins gmxtree uncrustify testutils +.. TODO: Consider what is the most reasonable structure; currently, this list + here does not make much sense in the overall organization and creates a + confusing TOC for the developer guide. + .. TODO: Add details for most of the tools, either in the form of links to wiki, or to a separate page that explains more details. @@ -30,6 +35,9 @@ Jenkins All changes pushed to Gerrit are automatically compiled and otherwise checked on various platforms using a continuous integration system at http://jenkins.gromacs.org. + :doc:`jenkins` documents how Jenkins interacts with the build system, + providing information on how to replicate the builds Jenkins does (e.g., to + diagnose issues). Redmine Bugs and issues, as well as some random features and discussions, -- 2.22.0