Using CruiseControl to configure a Perforce-stored build

If you're familiar with perforce and already have a working build, the following steps will show you how to get that build working in CruiseControl.  You should be able to write down a similar sequence describing how you would do the build manually before you try to get it working in CruiseControl (lest a typo cause problems!)

 The basic build sequence

This will vary depending on how your project works outside CruiseControl, but essentially, it looks something like this:

1. Find out if something has changed (no change, no build, after all!)
2. Obtain the source required to do a build (this may require "cleaning" the build environment or other changes as well)
3. Run the build
4. Report on the results

CruiseControl has multiple ways of handling each of these steps, and because of its plugin nature you can configure it to match your needs!

Step 0: Configure CruiseControl to know your Perforce settings.

I set things up like this in my CruiseControl config.xml file:

<!-- Perforce settings -->
  <property name="P4_PORT" value="perforce.domain.com:1666" />
  <property name="P4_CLIENT" value="CruiseControl-Server" />
  <property name="P4_USER" value="CruiseControl" />
  <property name="P4_PASSWD" value="Password" />

Step 1: Find out what has changed

This step is very simple: CruiseControl checks with the Perforce server, finding out if there are any submitted changelists since the last build.  Note that this step does NOT sync your source tree in any way!  It only checks to see what has changed.  Note also that it doesn't check what files you _have_ : it compares changelists submitted to the server to the view selected.  For this reason, the view should include only server-based filespecs (//depot/...) and not client-based filespecs (//clientspec/...).

<modificationset>
  <p4 view="//depot/Project/SharedFiles/..." port="${P4_PORT}" user="${P4_USER}" passwd="${P4_PASSWD}" client="${P4_CLIENT}" usep4email="true" />
  <p4 view="//depot/Project/ServerFiles/..." port="${P4_PORT}" user="${P4_USER}" passwd="${P4_PASSWD}" client="${P4_CLIENT}" usep4email="true" />
</modificationset>

Step 2: Obtain the source

The CruiseControl mechanisms to do this (and the ways Cruise Control users have come up with) vary greatly, but there are a couple of mechanisms available:

• CruiseControl bootstrap: A bootstrap is, in general build terminology, a way to update the build script itself, so that the build script can run.  Traditionally, one would "bootstrap" their "master" build script (build.xml in Ant, project.xml or pom.xml in Maven) and then that build script would take care of the rest.  CruiseControl's bootstrap is more powerful, in that you can tell it to clean, delete, and sync your entire project rather than simply the master build script.  The only caveat is that the bootstrap (logically) always runs (every time that CruiseControl checks for a build, it runs the bootstrap) and the bootstrap runs first.  So if you have a 500MB project with 10,000 files, you probably don't want to use the bootstrap functionality to delete and resync: it will run every time, even if there are no changes.  If you do wish to run the bootstrap to grab your files, this should work :
  

  <bootstrappers>
      <p4bootstrapper view="//ClientSpecName/..." port="${P4_PORT}" user="${P4_USER}" passwd="${P4_PASSWD}" client="${P4_CLIENT}" />
  </bootstrappers>

• Manual bootstrap: This method calls the bootstrap process from CruiseControl using another format (generally ant and/or ant-exec style calls.)  This allows you to have more fine-tuned control of the bootstrap, but if you put it in the "bootstrappers" section remember that it will run always and before everything else.  That being said, this is probably the easiest way to import an existing build process (manual or otherwise) into CruiseControl.
• As part of the build: Your build process can call its own Perforce sync commands.  For example, Maven has built-in bootstrap functionality that can check out Perforce source into a new directory and run the build from there.  This is probably the best way to handle any complex operations that must be done to prepare your source (that is, doing your source checkout as part of the build).  The Maven bootstrap Perforce integration isn't really "best": it has some severe limitations

Step 3: Run the build

This is the command you would need to run the build.  I can't really help you with this one: I don't know what your build is like .  There are a couple of things to note, however, that might make your build easier to work with:

• CruiseControl Properties Passed to Buildershas some extra variables that are available to your build that can help you figure out what's going on.
• There is a Perforce label incrementer that makes the build label (which CruiseControl uses to identify the build) the same as the Perforce changelist number.
• There doesn't appear to be a way to find out what the latest changelist number was in a modificationset.  Although this is available in the label incrementer, it's not readily available elsewhere.

Step 4: Report on the results

If you set the "usep4email" attribute in your p4modificationset in step 1, then all you need to do is create an "email" or "htmlemail" publisher and set "skipusers" to false: the email notifier will include all of those who made a change (using the email address from their Perforce user spec) in the email.

That's about it, really!  If you have any questions, feel free to post them to the CruiseControl user's list!

Perforce Config of P4Bootstrapper

Setting the path to a complete P4 depot ending with a a typical tripple dot (...) will synch the files for you. IE; you don't have to specify anything in build.xml, saving you some troubble.

--NiclasOlofsson

Perforce XSLT in versions of CC prior to 2.3

this is no longer required for current versions of CC

This showed up on the user list on 1-6-03, and specifically relates to getting CC to pass along Perforce change summaries. The following information is very much the kind of tool-specific configuration stuff that would be nice to grow here at CCDocs - RandyNovick

Problem:

Using the 'hello world' example with Perforce, you can get CC to properly run a build when a change is submitted, but the summary web page doesn't show the submitted change.

Resolution:

Perforce uses a different class to keep track of modifications, so the .xsl needs to be slightly different. To view the changes on the web page you'll need to replace header.xsl and modificaitons.xsl in the xsl directory with the files in the xsl/changelists directory. When you do that, rename changelists.xsl to modifications.xsl.

Alternatively, you can edit buildresults.jsp to use the header.xsl and changelists.xsl in the xsl/changelists directory. Something like:

<cruisecontrol:xsl xslFile="/xsl/header.xsl"/>
 -->
  <cruisecontrol:xsl xslFile="/xsl/changelists/header.xsl"/>

... and ...

<cruisecontrol:xsl xslFile="/xsl/modifications.xsl"/>
 -->
  <cruisecontrol:xsl xslFile="/xsl/changelists/changelists.xsl"/>

This second option isn't recommended because it won't work with the HTMLEmailPublisher.