Sebastian Nohn

Continuous Builds with CruiseControl, Ant and PHPUnit

Let me start with a quote:

An important part of any software development process is getting reliable builds of the software. Despite it's importance, we are often surprised when this isn't done. We stress a fully automated and reproducible build, including testing, that runs many times a day. This allows each developer to integrate daily thus reducing integration problems.

This blog posting will show you how to enable continuous builds with CruiseControl, Ant and PHPUnit. But be warned: Continuous builds are addicting.

Install the required packages

First you need to get the required tools (like always). This guide refers to JRE 5.0 Update 6, CruiseControl 2.4.1 and PHPUnit 2.2.1. CruiseControl 2.4.1 includes ANT 1.6.5, so we don't need to think further about this.

You already have installed PHPUnit (pear install -a phpunit2). CruiseControl and Ant are still missing. I assume, you install them according to the FHS in /opt:

$ unzip cruisecontrol-bin-2.4.1.zip -d /opt

For convenience in case of upgrades, you should create this symlink:

$ ln -s /opt/cruisecontrol-bin-2.4.1 /opt/cruisecontrol
Getting started with Ant

Ant may be new to you. If you know Make, this is cool, because you already know some build tool. Ant is Make with all that Java bloat you hate about Java. If you know Phing, this is even cooler, because Phing is Ant written in PHP, so you are already familiar with that bloat.

I have two reasons for choosing Ant over Phing or Make:

The disadvantage is, that PHPUnit does not integrate into Ant out of the box. This integration issue is the one point of this posting.

The main thing you need to know about Ant is a file called build.xml. Locate it where you like. For a good start, it does (1) Delete the old CVS checkout. (2) Checkout a clean new version:

<project name="my-project" default="build" basedir="checkout">
  <target name="build">
    <delete dir="My_Project" />
    <cvs cvsRoot=":ext:cruise@cvs:/var/opt/cvs"
         command="co My_Project" reallyquiet="true" />
  </target>
</project>

The ones of you that are known to build tools may ask why I put the "checkout" task into the build task. The answer is simple: I like to keep this little howto simple, so I do not introduce dependencies here.

Start to cruise

Like for Ant, for CruiseControl everything is configured in an XML file. This time it's called config.xml:

<cruisecontrol>
  <project name="my-project">

    <bootstrappers>
      <currentbuildstatusbootstrapper file="logs/my-project/buildstatus.txt" />
    </bootstrappers>

    <modificationset quietperiod="60">
      <cvs localworkingcopy="checkout/My_Project"/>
    </modificationset>

    <schedule interval="60">
      <ant buildfile="build.xml"
           target="build"
           uselogger="true"
           usedebug="false" />
    </schedule>

    <log dir="logs/my-project/" />

    <publishers>
      <currentbuildstatuspublisher file="logs/my-project/buildstatus.txt" />
      <email mailhost="localhost"
           returnaddress="cruise@mailserver"
           buildresultsurl="http://cruisecontrol:8080/buildresults/my-project"
           skipusers="true" spamwhilebroken="true">
        <always address="developer@mailserver" />
      </email>
    </publishers>

  </project>
</cruisecontrol>

Forget about the bootstrappers. The most interesting part is modificationset and schedule. The scheduler looks every 60 seconds, if something has changed in CVS and if so it would start Ant with our well know build.xml. I said, it would and I meant it would if there were not that modification set:

CVS commits are not atomic, this means, you can't be sure to have a working checkout, because there may be still some - yet uncommited - files in the commit pipeline. Our modification set tries to workaround that problem by only starting the build if the last commit was 60 seconds ago.

The publisher does what you most likely think, it publishes the build report into various channels.

So far so senseless: We do a regular checkout. Nevertheless, management may like the results, because we do a successful build after every commit.

Just start cruisecontrol in your cwd to get it working:

$ /opt/cruisecontrol/cruisecontrol.sh

The output should look something like this:

[cc]Mar-07 11:34:29 Main          - CruiseControl Version 2.4.1 Compiled on February 28 2006 1809
[cc]Mar-07 11:34:30 HttpServer    - Version Jetty/5.1.3
[cc]Mar-07 11:34:30 Credential    - Checking Resource aliases
[cc]Mar-07 11:34:30 LConfigManager- reading settings from config file [/my/path/config.xml]
[cc]Mar-07 11:34:30 usBootstrapper- CurrentBuildStatusBootstrapper was obsoleted by CurrentBuildStatusListener
[cc]Mar-07 11:34:30 tatusPublisher- CurrentBuildStatusPublisher was obsoleted by CurrentBuildStatusListener
[cc]Mar-07 11:34:30 trolController- projectName = [my-project]
[cc]Mar-07 11:34:30 LConfigManager- using settings from config file [/my/path/config.xml]
[cc]Mar-07 11:34:30 Project       - Project PEAR_Net_DNSBL: starting
[cc]Mar-07 11:34:30 Project       - Project PEAR_Net_DNSBL:  idle
[cc]Mar-07 11:34:30 Project       - Project PEAR_Net_DNSBL: started
[cc]Mar-07 11:34:30 Project       - Project PEAR_Net_DNSBL:  next build in 1 minutes 
[cc]Mar-07 11:34:30 Project       - Project PEAR_Net_DNSBL:  waiting for next time to build
Integrate PHPUnit

The goal is to integrate PHPUnit into build.xml and config.xml so that a build fails when the unit tests fail and some nice lists (sorry, no graphs so far) are included to the CruiseControl results (remember the management).

Achieving this is very easy. Integrate this into your build.xml, just before the </target> tag:

    <exec dir="${basedir}/My_Project/test/" executable="phpunit" failonerror="true">
        <arg line="--log-xml ${basedir}/logs/phpunit_all.xml AllTest" />
    </exec>

Replace the <log />-Part in your config.xml with this:

    <log dir="logs/my-project/" />
      <merge dir="checkout/logs/" />
    </log>

To get the changes working you need to stip CruiseControl (CTRL-C) and start it again like before.

Start to SPAM

Finally we modify our publishers to notify the management anytime, the developers on build failures and QA on successful builds:

    <publishers>
      <currentbuildstatuspublisher file="logs/my-project/buildstatus.txt" />
      <email mailhost="localhost"
           returnaddress="cruise@mailserver"
           buildresultsurl="http://cruisecontrol:8080/buildresults/my-project"
           skipusers="true" spamwhilebroken="true">
        <map alias="management" address="management@mailserver" />
        <map alias="qa" address="qa@mailserver" />
        <map alias="developer" address="developer@mailserver" />
        <always address="management" />
        <success address="qa" />
        <failure address="developer" reportWhenFixed="true" />
      </email>
    </publishers>
Next Steps

Posted Mar 07, 2006 by Sebastian Nohn
Tagged as: Ant, CruiseControl, PHP, PHPUnit, Software Development, Software Quality