Automated builds
================

The software is automatically built and tested on both SLC6 and CentOS7 for the latest of each set of commits pushed to the GitHub repo. These automated build/test jobs update the commit's ``gitlab-ci`` "status" field on GitHub, which is used to determine if pull requests can be merged into protected branches (e.g. ``master``).

These automated build and test jobs are currently implemented using the GitLab CI (continuous integration) framework. The GitHub ``ipbus-software`` repository is mirrored on the CERN GitLab instance, at https://gitlab.cern.ch/ipbus/ipbus-software.

.. contents:: Contents
  :local:


Structure
---------

The build and test jobs are defined in the ``.gitlab-ci.yml`` configuration file in the repository's root directory; an introduction to the syntax of this file can be found at https://gitlab.cern.ch/help/ci/yaml/README.md

The automated jobs are organised into 4 stages (all build jobs in any single stage are run in parallel):

1. **Initial report** 

  * Update commit's ``gitlab-ci`` status field on GitHub to ``pending``

2. **Build** - 3 jobs:

  * Compile and build RPMs on SLC6
  * Compile and build RPMs on CERN CentOS7
  * Create doxygen pages

3. **Test** - 5 jobs for each of SLC6 and CC7:

  * Core uHAL functionality in C++ (also tests ControlHub)
  * Core uHAL functionality in Python
  * uHAL tools package
  * uHAL GUI
  * ControlHub (starting & stopping)

4. **Final report**

  * Update commit's ``gitlab-ci`` status field on GitHub to ``success``, or ``failure`` in case any of the build/test jobs fail

In order to ensure reproducibility of each automated job, each build/test job is run in a docker container.


Accessing the results
---------------------

The output of the commands that are run within the automated build/test jobs are stored on the CERN GitLab instance, and can be viewed by navigating from the links on the `pipelines summary page <https://gitlab.cern.ch/ipbus/ipbus-software/pipelines>`__. Once the pipeline for any given commit has started, it is also linked from that commit on GitHub, as well as from any corresponding GitHub pull request page.

If the jobs from the builds run successfully, then the resulting YUM repositories and doxygen pages can be accessed through the following URLs:

* ``http://ipbus.web.cern.ch/ipbus/sw/ci/commits/<pipeline_id>_<commit_sha>/api_uhal/html/``
* ``http://ipbus.web.cern.ch/ipbus/sw/ci/commits/<pipeline_id>_<commit_sha>/slc6_x86_64``
* ``http://ipbus.web.cern.ch/ipbus/sw/ci/commits/<pipeline_id>_<commit_sha>/centos7_x86_64``


Installing the RPMs created by the automatd builds
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

1. Uninstall release / previous nightly build if already installed on your machine - ``sudo yum groupremove ipbus-sw``
2. Remove the existing IPbus software repo files from ``/etc/yum.repos.d``, and clean the yum cache

  .. code-block:: sh

    sudo yum clean all

3. Download this :download:`template automated-build repo file <ipbus-sw-autobuild.repo>`, and move it under ``/etc/yum.repos.d``
4. Open this file and change the following parts of the ``baseurl`` line:

  * ``<platform>`` - should be ``slc6_x86_64`` or ``centos7_x86_64``
  * ``<pipeline-id>``
  * ``<commit-sha>``

5. Install the software:

  .. code-block:: sh

    sudo yum groupinstall ipbus-sw