CruiseControl Components

In this section, we cover the standard components that come with CruiseControl, and describe in general the architecture of CruiseControl. Instructions on how to configure each component are included in the tool's documentation.

Source Control Systems

CruiseControl uses components called source control systems to detect changes to projects. These components go into the <modificationset> element in the CruiseControl configuration file. Not all of these components actually talk to version control systems, but most do and so the name has stuck.

BuildStatus: Used to watch the status of another project. It allows builds of one project to trigger another; very useful when dealing with related projects.
ClearCase: Monitors a ClearCase repository for changes. It uses the cleartool lshistory command to obtain the list of changes.
CVS: Monitors a CVS repository for changes. It uses the cvs log command to obtain the list of changes.
FileSystem: Watches a specified file or directory for changes. Changing the modification date of the file(s) (e.g., by editing it) triggers a new build. One limitation of this method is that it is unknown who changed the file.
MKS: Monitors an MKS repository for changes. It uses the rlog command to obtain the list of changes.
P4: Monitors a Perforce repository for changes. It uses the p4 changes command to obtain the list of changes.
PVCS: Monitors a PVCS repository for changes. It uses the vlog command to obtain the list of changes.
StarTeam: Monitors a StarTeam repository for changes. It uses the StarTeam Java API to obtain the required information. This requires the StarTeam SDK to be present when building CruiseControl as well as when running it.
VSS: Monitors a Visual SourceSafe repository for changes. It uses the ss history command to obtain the list of changes.
VSSJournal: Monitors a Visual SourceSafe repository for changes, using the Visual SourceSafe journaling facility. This works by reading the journal file directly.
SVN: Monitors a Subversion repository for changes. It uses the svn log command to obtain the list of changes. This component is not enabled in the default distribution of CruiseControl, because Subversion had not been finalized. In future releases, it will be enabled. In the interim, to enable it you need to enter the following into your configuration file, inside a <project> element:
```
 <plugin name="svn" classname=:"net.sourceforge.cruisecontrol.sourceontrols.SVN" /> 
```

Bootstrappers

Bootstrappers are components used to update some or all of your project before the build officially kicks off. They were introduced to get around a significant problem: if you use the build script to obtain the latest version of your project, what do you do when the build script changes?

At the very least, you should use a bootstrapper to update your build script. Bootstrappers also provide a convenient way to perform any other "pre-build" activity.

You enter bootstrappers within the <bootstrappers> element.

The word "bootstrapper" is a common term used in computing to describe a process that is done to enable another process. The term comes from the phrase "to pull yourself up by your bootstraps."

In theory, there should be a bootstrapper to match each supported version control system. However, only some of the version control systems have bootstrappers at this time.

ClearCaseBootStrapper: Uses ClearCase to update the specified files or directory.
CurrentBuildStatusBootStrapper: Not really a bootstrapper, this component updates the specified status file to indicate that a build is starting.
CVSBootStrapper: Uses CVS to update the specified files or directory.
P4BootStrapper: Uses Perforce to update the specified files or directory.
StarTeamBootStrapper: Uses StarTeam to update the specified files or directory. It requires the StarTeam SDK, just like the StarTeam source control component.
VSSBootStrapper: Uses Visual SourceSafe to update the specified files or directory.
CurrentBuildStatusFTPBootStrapper: Similar to the CurrentBuildStatusBootStrapper; however, this component then transfers the status file to a remote server via FTP. This component is not enabled in the default distribution of CruiseControl. In future releases, it will be enabled. In the interim, to enable it you must enter the following into your configuration file, inside a <project> element:
```
 <plugin name="currentbuildstatusftpbootstrapper" classname="net.sourceforge.cruisecontrol.bootstrappers.CurrentBuildStatusFTPBootStrapper.SVN" /> 
```
SVNBootStrapper: Uses Subversion to update the specified files or directory. This component is also not enabled in the default distribution of CruiseControl, since Subversion had not been finalized. In future releases, it will be enabled. In the interim, to enable it you must enter the following into your configuration file, inside a <project> element:
```
 <plugin name="svn" classname="net.sourceforge.cruisecontrol.bootstrappers.SVNBootStrapper" /> 
```

Builders

Builder components are what CruiseControl actually uses to build the project. In theory, any sort of mechanism could be used to build a project, but in practice it is only feasible to make a builder for a mechanism that can produce an XML log file. There is no requirement that the build mechanism be Java based; for example, both the Ant and Maven builders can (and should) be run by a supplied batch script.

Although a CruiseControl configuration file can define many projects within it, at this time there is support for only one project to be built at a time. As such, there is only one active builder.

In addition to building at regular intervals, as already demonstrated, builders can be supplied for timed builds or to be run at particular intervals. For example, a common usage is to supply a <schedule> element like this:

 <schedule interval="30" >     <ant antscript="build.sh" target="cruise-build" multiple="1" />     <ant antscript="build.sh" target="full-cruise-build" multiple="5" />     <ant antscript="build.sh" target="nightly-cruise-build" time="0830" />     <ant antscript="build.sh" target="weekly-cruise-build" time="0305" day="Saturday" />     <pause startTime="2100" endTime="0300" /> </schedule>

As you can see, this schedule runs the cruise-build task normally, but every fifth build will run the full-cruise-build. The nightly and weekly tasks provide for still more flexibility. These tasks are useful for running Ant tasks that are not desirable to run every build (presumably because they take too long to complete).

You enter builder components within the <schedule> element.

Ant: Invokes an Ant build script.
Maven: Invokes a Maven build script.
Pause: Forces the project to pause during the specified hours.

BuildLoggers

BuildLoggers are used to supplement the log file that CruiseControl produces. By default, CruiseControl includes information on the build, along with information supplied by the source control components and the builder components.

You enter BuildLoggers components within the <log> element.

The only BuildLogger to ship with CruiseControl is the Merge logger. This component merges the specified XML file (or XML files in the specified directory) into the log file.

LabelIncrementers

LabelIncrementers are used to determine the next label to be used on a project. You enter them within the <project> element. If you do not include one, the default incrementer is used.

Getting the Build Label

The build label that will be applied to the project (if it is successfully built) is available to the build scripts as a property called label. However, it will be applied only if the build is successful. Other properties of interest are cctimestamp (the time of this build), cclastbuildtimestamp (the time of the last build), and cclastgoodbuildtimestamp (the time of the last known good build).

LabelIncrementer: The default label incrementer. It produces labels like Project.1. By default, the last numeric component is incremented following a successful build (which means that there may be a number of failed builds between Project.1 and Project.2), but it can be configured to increment before the build. If it increments before the build, the build number will increase even if the build fails, thus reflecting build attempts.
CVSLabelIncrementer: This is exactly like the default label incrementer, except that it uses a - character instead of a period to separate the text of the label from the numeric extension. This allows the label to be used as a CVS tag. By default, it is not enabled. To enable it, simply register the label as follows :
```
 <plugin name="cvslabelincrementer" classname="net.sourceforge.cruisecontrol.labelincrementers.CVSLabelIncrementer" /> 
```
EmptyLabelIncrementer: This incrementer always returns an empty string for the label. By default, it is not enabled. To enable it, simply register the label as follows:
```
 <plugin name="emptylabelincrementer" classname="net.sourceforge.cruisecontrol.labelincrementers.EmptyLabelIncrementer" /> 
```

When you're registering a LabelIncrementer, it is possible to set it as the default incrementer (thus allowing it to be omitted, if you're happy with its default behavior). To do this, simply name the plug-in labelincrementer. This trick works for overriding the behavior of any component; however, it is normally more sensible to use a different name for the overriding component. The LabelIncrementer is a special case, due to the fact that it can be omitted.

Publishers

Publisher components are run after the build is complete, and after the resulting log file is finalized. The intent of these components is to publish the results of the build.

You enter publisher components within the <publishers> element.

ArtifactsPublisher: Copies build products to a unique destination directory based on the build timestamp. This publisher is good for preserving the results of builds (such as the distributable files).
CurrentBuildStatusPublisher: Updates the build status file with an indicator of when the next build attempt will be made.
Email: Sends an e-mail to the list of users detected by the source control components. In addition, users can be entered to receive notification of successful or failed builds, or both. The e-mail will consist of a link to the reporting application, plus a subject line indicating the success or failure of the build. Successful builds will include the build label in the subject line.
Execute: Executes a shell command.
HTMLEmail: Sends an e-mail to the list of users detected by the source control components. In addition, users can be entered to receive notification of successful or failed builds, or both. The e-mail will contain the XML log file, after selected style sheets have been applied to it. The default style sheets result in an HTML message, similar to the Web application report. The subject of the e-mail will indicate success or failure, and successful builds will include the build label in the subject.
SCP: This uses SCP (Secure Copy Protocol) to transfer a selected file to another machine.
XSLTLogPublisher: Applies an XSLT style sheet to the log file, and saves the result.
CurrentBuildStatusFTPPublisher: This is similar to the CurrentBuildStatusPublisher, but it will then transfer the status file via FTP to another server. By default, it is not enabled. To enable it, simply register the component as follows:
```
 <plugin name="currentbuildstatusftppublisher" classname="net.sourceforge.cruisecontrol.publishers.CurrentBuildStatusFTPPublisher" /> 
```
FTPPublisher: This is similar to the SCP publisher, but it uses FTP to transfer the file. By default, it is not enabled. To enable it, simply register the component as follows:
```
 <plugin name="ftppublisher" classname="net.sourceforge.cruisecontrol.publishers.FTPPublisher" /> 
```
SameTimeAnnouncementPublisher: This works similar to the Email publisher, but instead of sending an e-mail, it sends a SameTime announcement ( SameTime is an instant messaging product from IBM). By default, it is not enabled. To enable it, simply register the component as follows:
```
 <plugin name="sametimeannouncementpublisher" classname="net.sourceforge.cruisecontrol.publishers.SameTimeAnnouncementPublisher" /> 
```