Edit wiki page
You do not have sufficant permissions to edit or create the wiki page.
===========================================================
Setting up an Continuous Integration Environment with Arbit
===========================================================
.. warning:: 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.
__ InstallationGuide
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.
__ http://phpunit.de
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.
__ http://pdepend.org
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.
__ http://pear.php.net/package/PHP_CodeSniffer
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.
__ http://github.com/sebastianbergmann/phploc
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.