Arbit - project tracking

Setting up an Continuous Integration Environment with Arbit

This howto currently only works with the current trunk/ of arbit. The features documented here are not yet officially released.

First you should ensure that you already got a working installation of arbit, including a set up project. In this example we will set up a continuous integration environment for PHPillow, that PHP CouchDB library used by arbit.

To setup up continuous integration you should have:

• A shell on the server, to execute the build scripts

• Access to the project configuration files

• Optionally the ability to install further pear packages on the server, if they are not yet available.

This example will configure all available modules, which offer code analysis and similar features, you may of course only use a subset of those. All modules need to be registered in the main configuration, which is the case, by default. The [modules] section therefore should contain at least those modules:

module[]=source
module[]=phpdoc
module[]=pdepend
module[]=phpunit
module[]=phpcs
module[]=phploc
module[]=ci

The other modules are not required for setting up a CI environment. Each module in this listing, except for the source and the CI module, is also optional.

Configure the project

The main configuration only defines which modules are available in whole system, but not which modules are activated for a given project. Therefor you also need to enable those modules for the project you want to enable CI for. The file $project/project.ini should therefore contain:

module[API]=phpdoc
module[CI]=ci
module[Metrics]=pdepend
module[Browse code]=source

# Headless modules
module[phpunit]=phpunit
module[phpcs]=phpcs
module[phploc]=phploc

The last three modules are not directly accessible in the webinterface, so they are considered "headless". Their name is important anyways, since the module name (and not the type) defines the name of the associated configuration file. So the configuration file for the source modules is browse_code.ini and not something like source.ini.

Configuring the source checkout

Configuring the source checkout is very important, since it defines where your repository resides and how to access it. To configure the URL of your repository you should open (or create) the configuration file for the source module in your project configuration folder, which should be something like config/phpillow/browse_code.ini. You can copy the example configuration file from the example project, to get an initial configuration file with documented configuration settings. The most important settings are the URL and the checkout type in the repository section:

[repository]
type=vcsSvnCliCheckout
url=svn://arbitracker.org/phpillow/trunk

You may optionally also specify a user and a password, if the repository is not accessible to anonymous users. A list of currently available checkout types is available in the documented example configuration file. Currently supported are Git, SVN, CVS and plain source archives.

Initialize source checkout

The source checkout will not be initialized automatically, so you need to perform the first checkout manually. You can do this using the manage command from the source module. To get an overview of its options, execute:

./modules/source/scripts/manage --help

In this case we want to perform the initial checkout, so that we execute:

./modules/source/scripts/manage -p phpillow -v checkout

Where "phpillow" should be replaced by the name of your project. The execution of the command may, of course, take some time. You should receive a message like the following, telling about a successful repository initialization:

Repository checkout at version #143.

You can now also browse the source checkout in the webinterface.

Configure PHPUnit

To use PHPUnit with your project you need to have PHPUnit installed on the Continuous Integration server. If you have a working pear environment, which you should, you can install it using:

pear channel-discover pear.phpunit.de
pear install phpunit/PHPUnit

For additional functions you should also install XDebug und add it in you cli-php.ini:

pear install pecl/xdebug

The phpunit executable should be available in your path, or you should link it to some directory in your $PATH. All tests and tests suites should be contained in the checkout configured above. You can specify the executed phpunit command in the project specific phpunit.ini which should be available somewhere like config/phpillow/phpunit.ini. For PHPillow this looks like:

[main]
cli_options[]=phpillowTestSuite
cli_options[]=tests/suite.php

Arbit will itself append the required options for the generation of code coverage and test statistics to paths, which are then used by arbit. You can test the execution then using the provided module scripts:

./modules/phpunit/scripts/manage -v -p phpillow runtests

This command will report that no source checkout has been reported, because the source module only did an initial checkout, but did not report a source update yet. We can fake this for debugging by executing:

./modules/source/scripts/manage -v -p phpillow emit

And after that we can run the unit tests:

./modules/phpunit/scripts/manage -v -p phpillow runtests

Because of the -v parameter, you can see the whole output of PHPUnit. If errors occur during the test run, tune your configuration and repeat the emit, runtests process until it works.

Configure PDepend

The process of configuring PDepend is very similar to configuring PHPUnit. First ensure PDepend is installed on your server:

pear channel-discover pear.pdepend.org
pear install pdepend/PHP_Depend-beta
pear install pdepend/PHP_Depend_Log_Arbit

The configure PDepend to only analyze your source directory, as usual in the config/phpillow/metrics.ini. For PHPillow this looks like:

[main]
ignore="libraries,external,templates"
subdir="src/"

After that you can test PDepend, using the module command:

./modules/pdepend/scripts/manage -v -p phpillow analyze

If an error occurs, fix it an rerun the command, optionally after re-emitting the source update signal, like shown for the configuration of PHPUnit. After the generation of the PDepend results, the webinterface should also offer you an overview on the metrics.

Configure CodeSniffer

CodeSniffer performs simple static source code analyzes, which focus on Coding standards. It is a pear package, and can therefor be installed using:

pear install PHP_CodeSniffer

You might optionally need to install you own coding standards. For arbit related packages this would be the arbit coding standard, which can be installed like:

pear channel-discover pear.xplib.de
pear install xplib/PHP_CodeSniffer_Standards_Arbit-beta

This will of course be different, depending on the coding standard you are using in your team. After that you should again configure the phpcs module, to analyze only the source dirs you want to be analyzed - otherwise it might produce a lot of errors. For PHPillow the configuration file config/phpillow/phpcs.ini looks like:

[main]
cli_options[]="--ignore=libraries,tests"
cli_options[]="--extensions=php"
standards="Arbit"
subdir="src/"

Now you can check the source using the module command:

./modules/phpcs/scripts/manage -v -p phpillow check

If an error occurs, fix it an rerun the command, optionally after re-emitting the source update signal, like shown for the configuration of PHPUnit.

Configure PHPLOC

PHPLOC is a simple tool to provide you with basic metrics counting the lines of code, classes and similar in your checkout. It can be installed with pear using:

pear channel-discover pear.phpunit.de
pear channel-discover components.ez.no
pear install phpunit/phploc

The configuration of PHPLOC is contained in the usual configuration file, like config/phpillow/phplog.ini, and for PHPillow it looks as simple as:

[main]
subdir="./"

The initial test can be performed using the common command:

./modules/phploc/scripts/manage -v -p phpillow count

If an error occurs, fix it an rerun the command, optionally after re-emitting the source update signal, like shown for the configuration of PHPUnit.

Configure automatic analysis

After you ensured each command runs properly, you should setup that all these commands will be run on each source code update. This is quite easy, since arbit implements its own cronrunner, with a custom crontab, which is available at ./crontab. You can edit it, but the default version should be fine for most applications. The module commands will only be run, after a source code update happened. The used syntax is the same as used by vixie-cron for its crontabs.

The only thing you need to do is run the arbit cron runner in regular intervals, like adding the following command to your "real" crontab:

* * * * * ./scripts/usr/cron execute

You can of course execute this command manually, as well. The command will only output something, if errors occur. If you run it manually, you might want to append the -v switch for verbose output. Since all errors are also logged to var/logs/error.log you might also use -q for quite output, if you don't like to receive any cron mails. More details are available using ./scripts/usr/cron --help, as always.

We will support web-triggered cron execution and a custom cron daemon in the near future, too, but for now you require an external cron daemon to trigger the builds.