Development Guide

Setting up Jenkins CI

ILIAS uses continuous integration to get a clear impression on issues in the code based on metrics gathered.
The popular tool Jenkins CI was chosen to support this task. This guide explains how to setup a Jenkins instance for your development.

Overview

The ILIAS build is - where possible - following the best practices lined out by Sebastian Bergmanns Template for Jenkins Jobs for PHP Projects.
 
First you need to install Jenkins, which is available at the website or via the package manager of your choice.
 
In the next step, install the following plugins for Jenkins through its administration interface:
 

  • Checkstyle
  • Clover PHP
  • DRY
  • HTML Publisher
  • JDepend
  • Plot
  • PMD
  • Violations
  • xUnit
The plugin list offers a "PHP Plugin", which is captioned as "This plugin installs jenkins plugins suggested by [http://jenkins-php.org/] for PHP developers". You may use this, but please verify the above mentioned plugins are installed afterwards.
 

The next step is the installation of the tools, that run on the ILIAS code during the build. Jenkins PHP recommends the following list:

  • PHPUnit
  • PHP_CodeSniffer
  • PHPLOC
  • PHP_Depend
  • PHPMD
  • PHPCPD
  • phpDox
  • PHPCB
Please note that some of these tools have a higher PHP version requirement as the ILIAS codebase.
You can get these tools and their installation instructions at http://phpqatools.org/. It is highly recommended to get the full toolchain for your local development environment as well.

The actual build process

Before we jump into setting up the job, we'll have a look at how things are organized in the build.
 
The jenkins-php.org-Template assumes that the software to be inspected lives in a subdirectory of the checkout, src/, and the all the build information is contained in the checkout. This is currently not the case with ILIAS, so we have to do the following:
 
First, we checkout the build information and tool configs from the CI-repository, then the system under test is checked out into the src/-directory.
Since the build is currently very basic and generic, we can always use the builds trunk and any desired ILIAS branch to build.
 
During the build, information and metrics are collected. This is where the build itself stops once it's finished. To make these information accessible, a job configuration for jenkins is necessary, which controls the checkouts, runs the build and then puts the result to the screen.
 
The build.xml that comes with the checkout contains a selection of targets for you to use as well as some "meta-targets", that simply bundle dependent targets into a complete build.
 
E.g. the "build-full" target depends on the targets "prepare, lint, phploc, pdepend, phpmd, phpcpd, legacyconstructors, inefficientsql, phpunit and phpcb". The "prepare" target depends on the "clean" target and so on. Once a target is called, the dependencies are resolved and everything is done in the correct order.
 
You do not need to use a meta-target, you can - without touching the build.xml - call other targets that you want to see built. It all comes down to you generate some diagnostic data and then visualize it.