Tracking build status with Pulse

Pulse is a build server that can monitor your source repository and trigger a build and test cycle every time somebody does a commit. With Pulse you will always know if the most recent sources in your revision control system compile and if they pass your unit and system tests. Better yet, Pulse allows you to build and test your current working copy of checked-out source, during a so-called Personal Build, so you can see if your code breaks things before you commit your changes to the central repository.

Some developers dislike services like Pulse because if they check in code they might break one of the regression tests and have to hear about it publicly. Being able to run a project’s regression test before you commit your sources lets developers find regressions before they commit to the main source tree.

Installation of Pulse is well detailed on the Pulse Web site so I won’t replicate the details here. I tried to use both the beta version 2.x and version 1.2.59 of Pulse on a 64-bit Fedora 9 machine, but I could not manage to get version 2.x to create its database during installation. When you start Pulse it offers a Web interface on port 8080 that is used for all tasks apart from triggering a personal build.

Pulse offers free licenses to small teams and open source projects. The open source license allows a project to have an unlimited number of users. I was hoping to see support out of the box for building with autotools and testing with DejaGnu, but Pulse offers no explicit support for either of these projects.

Pulse supports Ant, Boost Jam, GNU make, Maven, Xcode, and custom build setups. For testing, it supports boost regression, CppUnit, OCUnit, CUnit, JUnit, UnitTest++, and Maven.

To get Pulse to build an autotools project from CVS took a bit of experimentation. I based my Pulse setup on a GNU Make build and converted it into a custom build type in the projects -> ferrisloki -> configuration window. Note that the previous sequence is selecting projects from the top level menu, libferrisloki as one of the known projects, and then configuration from the submenu. For my testing I chose to build libferrisloki because it is a codebase I am familiar with, it is quick to build, already in my local CVS repository, and follows the standard autotools conventions.

The custom Pulse build file used to build libferrisloki is shown below. The bootstrap file referenced performs a similar role to the autogen.sh file that is included in many open source repositories. I added the first two command elements and the artifact element to a normal GNU make Pulse build file. Pulse calls an artifact a file or directory from your build which is to be collected and made available through the Web interface. By capturing artifacts you can later investigate what has changed or examine the raw output of certain tests.

I found that the default working directory (current directory) was wherever the source code was checked out to — that is, the parent of the directory containing configure.ac.

Two additional commands run the bootstrap script (which is like autogen.sh) and then execute the generated ./configure script. I added the artifact line to capture the distribution tarball for each build. My changes are shown in bold.

<?xml version="1.0" encoding="UTF-8"?>
<project defaultRecipe="make build">
    <recipe name="make build">


        <command name="autotools-bootstrap">
            <executable exe="./bootstrap" args="" working-dir="libferrisloki" />
        </command>

        <command name="autotools-configure">
            <executable exe="./configure" args="" working-dir="libferrisloki" />
        </command>

        <command name="build">
            <make makefile="Makefile" targets="all dist" working-dir="libferrisloki" > </make>
            <artifact name="tarball" file="libferrisloki/ferrisloki*.tar.bz2"/>

        </command>
    </recipe>
</project>

One downside of converting a GNU make build into a custom build like this is that once you have done so you cannot use Pulse’s Web interface to specify artifacts anymore. To capture an artifact you must edit your Pulse build file (through the Web interface) and include the artifact element manually.

The contents of the bootstrap script, which is based on the one from autobook, are shown below.

$ cat bootstrap
#!/bin/bash

mkdir -p macros
libtoolize --force
aclocal -I macros 
automake --gnu --add-missing 
autoconf 

With the above Pulse custom project in place and the bootstrap file in CVS, I could happily build libferrisloki. The make dist tarball was captured as an artifact that I could download at any time.

To start a personal build, you need to perform some configuration steps. Configuration is straightforward, with global settings stored in a dot-file under your home directory and project-specific options stored to the current directory. The latter means you should invoke the pulse personal command from the top directory of your working source code checkout.

$ ~/pulse-1.2.59/bin/pulse personal
No pulse server configured.  Configure one now?
Yes/No [default: Yes]> 
Pulse URL [e.g. http://pulse:8080]: http://localhost:8080
Pulse user [default: ben]: 
Storing Pulse server details in '/home/ben/.pulse.properties'.
No pulse project configured.  Configure one now?
Yes/No [default: Yes]> 
Pulse project: ferrisloki
Build specification: default
Storing project details in '/tmp/cvstest/libferrisloki/.pulse.properties'.
Pulse password: 

After you have configured Pulse for personal builds of a checked-out source tree, you can issue another personal build simply by invoking pulse personal. Before I ran the command below, I added #warning to the Extensions.hh header file and started a personal build to see whether everything would still compile.

$ ~/pulse-1.2.59/bin/pulse personal
Pulse password: 
Updating working copy...
  ?     .pulse.properties
  M     src/Extensions.hh
Update complete.
Getting working copy status...
  MODIFIED       src/Extensions.hh
Status retrieved.
Creating patch archive...
  meta.xml
  files/libferrisloki/src/Extensions.hh
Patch created.
Sending patch to pulse server...
Patch accepted: personal build 1.

Once you have triggered a personal build with the pulse personal command, you can monitor things and see the results from the dashboard -> my builds page in the Pulse Web interface. The presentation through the my builds page is the same as for regular systemwide builds in the build window reached through the choices projects -> ferrisloki -> home -> current. So for each personal build you can see the full build log, the configured artifacts, and which tests (if any) failed.

Final words

Having to use a custom project just to support building with autotools makes using Pulse for many open source projects a lot more difficult than it needs to be. Some parts of the Pulse documentation would be much clearer if they included a few complete examples. Running into only configuration fragments is a highly frustrating situation when you are just trying to get the configure stage generated and run.

However, the personal build option is a wonderful thing to have in a group development environment. It is generally good practice to update your working copy and make sure the latest version of the sources do not conflict with your changes, and that everything still compiles before you commit your changes to the main source repository. With a Pulse personal build, you can also make sure that the system and regression tests still pass before you commit your code for everyone else. One word of warning here though: Pulse will update your current working copy with any changes from the main repository at the start of a personal build. I would have liked the working copy to remain as it was so you can manually update your working copy independent of Pulse.