PackageDescription: CruiseControl


Cruise Control

Last published: December 21, 2010 by 'randy'

Defines 2 Classes
Extends 4 Classes


This package provides the VW side of a CruiseControl (http://cruisecontrol.sourceforge.net) source control.
It produces an XML report of all changes detected in one or more packages (and their prerequisites) that
can then be parsed by the corresponding Java plugin in CruiseControl.

I have submitted the Java plugin as a patch to the CruiseControl maintainers. It was integrated as part of
CruiseControl 2.7.2.

Normally, this code will be called from the Java plugin. It can also be run from the command line as follows:

-profile -packages -versionRegex -blessedAtLeast -lastBuild -now -parcelBuilderFile -check

The command line options are:
-profile Required The name of a Store repository profile. This is the repository that will be checked for changes.
-packages Required A space-separate list of package names. All packages in this list and their prerequisites will be checked.
-versionRegex Optional A Regex11-style regex that specifies the pattern of version numbers to check. Any versions not matching the regex will not be considered. By default, all versions are considered.
-blessedAtLeast Optional The minimum blessing level to consider. Only packages with this blessing level or higher are considered. Default: Development.
-lastBuild Required The UTC time of the last build in mm/dd/yyyy hh:mm:ss.fff format.
-now Required The UTC time the current build started in mm/dd/yyyy hh:mm:ss.fff format.
-parcelBuilderFile Optional The name of a file to use as input to the ParcelBuilder package. By default, no ParcelBuilder file is produced.
-check Required This option actually performs the modification check; it must be the last option on the command line.

Use -profile to specify the repository of interest and -packages to list the top-level packages to be checked. Note that Bundles are not supported at this time.

If you only want to consider packages (and prerequisites) of a certain blessing level or higher, use -blessedAtLeast to specify that. If you have a version numbering scheme and only want to consider versions that match a certain pattern, use -versionRegex to specify the pattern to use. For example, we use integral version numbers to represent our "trunk". Anything with a . or other non-digit characters is considered to be on a branch, and we don't want our automated builds to consider those versions. Thus, our versionRegex is "[0-9]+".

When CruiseControl processes a project, it snapshots the start time of that processing. That is considered to be the "current build time" for all subsequent operations. This provides an "atomic" view of the source code repository so that changes that are published while a build is running do not affect that build, but are considered for the next cycle. After the time snapshot, CruiseControl checks for any changes since the last build (using the code in this package), but before the "current build time". If there are any, it will then trigger an automated build. The -lastBuild and -now options specify the timestamp range to be considered.

When looking for changes, blessing changes are also considered. If a package is published to a repository and then later replicated to the repository being checked by CruiseControl, it will be picked up by this code, even if it was originally published prior to the "last build time".

There is another command-line that is supported if you don't care about modifications and just want to generate a ParcelBuilder input file. It takes the same arguments as above, but defaults both -lastBuild and -now to the current time. If -parcelBuilderFile is not specified, it defaults to 'parcelsToBuild' in the current directory. Use -generate instead of -check for this option.

The automated build is not part of this package. One option is to use ParcelBuilder to load packages from Store and write them out to disk as parcels that can then be loaded into a base image at a later time (to run tests or to run the deployed application). The -parcelBuilderFile option, if specified, will write out a file specifying the latest version of each package that was checked for modifications. This way, the automated build will use the package version that was the latest at the time of the build snapshot. This file could be used as input to other automated build systems as well. Each line of the file is of the format "\t".

When running the Java plugin from CruiseControl, it is necessary to have a working directory for the build. There is a "state" file stored in this directory that remembers the list of packages that were processed during the last build so that new packages are recognized and reported as such. For example, you might add a pre-requisite on some package that hasn't changed for a while. So, the new package wouldn't show up as a modification, but will show up as an added package. The first time you run a build, all packages will show as added packages. Also, if you use the -parcelBuilderFile option, that file will be written into the working directory (unless an absolute path is specified).

If you want to run SUnitToo tests as part of your automated build, you might want to try the TestLogger package. It will run all SUnitToo tests and log the results in the JUnit-compatible XML format that CruiseControl uses to report test results.

This package uses StoreForGlorp to do its thing.

I'd like to thank: Alan Knight for Glorp and StoreForGlorp; Travis Griggs for figuring out how to do a lot of this stuff in a home-grown package we used until I wrote this; Russel Hill for comments and suggestions along the way.

For more information or if you have problems or questions, contact me at rcoulman _at_ gmail.com.