CruiseControl Configuration Reference

<cruisecontrol>

<cruisecontrol>

The <cruisecontrol> element is the root element of the configuration, and acts as a container to the rest of the configuration elements.

Child Elements

<threads>

<cruisecontrol>
  <system>
    <configuration>
      <threads>

The <threads> element can be used to configure the number of threads that CruiseControl can use simultaneously to build projects. This is done through the count attribute. If this element (or one of its parent elements) is not specified, this defaults to 1. This means that only one project will be built at a time. Raise this number if your server has enough resources to build multiple projects simultaneously (especially useful on multi-processor systems). If more projects than the maximum number of threads are scheduled to run at a given moment, the extra projects will be queued.

Attributes

<property>

<cruisecontrol>
  <property>

The <property> element is used to set a property (or set of properties) within the CruiseControl configuration file. Properties may be set at the global level and/or within the scope of a project. There are three ways to set properties within CruiseControl:

1. By supplying both the name and value attributes.
2. By setting the file attribute with the filename of the property file to load. This property file must follow the format defined by the class java.util.Properties, with the same rules about how non-ISO8859-1 characters must be escaped.
3. By setting the environment attribute with a prefix to use. Properties will be defined for every environment variable by prefixing the supplied name and a period to the name of the variable.

Properties in CruiseControl are not entirely immutable: whoever sets a property last will freeze it's value within the scope in which the property was set. In other words, you may define a property at the global level, then eclipse this value within the scope of a single project by redefining the property within that project. You may not, however, set a property more than once within the same scope. If you do so, only the last assignment will be used.

Just as in Ant, the value part of a property being set may contain references to other properties. These references are resolved at the time these properties are set. This also holds for properties loaded from a property file, or from the environment.

Also note that the property ${project.name} is set for you automatically and will always resolve to the name of the project currently being serviced - even outside the scope of the project definition.

Finally, note that properties bring their best when combined with plugin preconfigurations.

Attributes

Examples

1. Set a couple of global properties using name/value pairs:

   <cruisecontrol>
       <property name="cruisedir" value="/home/cruise"/>
       <property name="logdir"    value="${cruisedir}/logs"/>
       ...
   <cruisecontrol>
               

2. Set a collection of global properties from the properties file "config.properties":

   <cruisecontrol>
       <property file="config.properties"/>
       ...
   <cruisecontrol>
               

3. Load the system's environment into a collection of global properties. Uppercase all environment variable names:

   <cruisecontrol>
       <property environment="env" toupper="true"/>
       <property name="logdir"     value="${env.CCDIR}/logs"/>
       ...
   <cruisecontrol>
               

4. Define a global property called "buildmanager". Override it's value only within the scope of the project called "project2".

   <cruisecontrol>
   
       <property name="buildmanager" value="buildmgr@here.com"/>
   
       <project name="project1">
           <!-- ${buildmanager} resolves to "buildmgr@here.com" -->
       </project>
   
       <project name="project2">
           <property name="buildmanager" value="someoneelse@here.com"/>
           <!-- ${buildmanager} resolves to "someoneelse@here.com" -->
       </project>
   
   <cruisecontrol>
               

5. As demonstrated here, properties and plugin pre-configuration can be an extremely powerful combination.

   <cruisecontrol>
   
       <!-- Load environment variables -->
       <property environment="env" toupper="true"/>
   
       <!-- Commonly used directories -->
       <property name="reportdir"  value="${env.CCDIR}/report"/>
       <property name="projectdir" value="${env.CCDIR}/checkout/${project.name}"/>
       <property name="testdir" value="${projectdir}/build/junit-reports"/>
       <property name="logdir" value="${env.CCDIR}/logs/${project.name}"/>
   
       <!-- Defaults for email -->
       <property name="buildmaster.email"  value="buildmaster@example.com"/>
       <property name="buildmaster.name"  value="Buildmaster"/>
   
       <!-- Preconfigure our plugins -->
       <plugin name="log"
               dir="${logdir}"/>
   
       <plugin name="currentbuildstatuslistener"
               file="${logdir}/buildstatus.html"/>
   
       <plugin name="cvs"
               localworkingcopy="${projectdir}"/>
   
       <plugin name="ant"
               antscript="${env.ANT_HOME}/bin/ant"
               antWorkingDir="${projectdir}"
               target="cruise"/>
   
       <plugin name="htmlemail"
               buildresultsurl="http://servername/cruisecontrol/buildresults/${project.name}"
               mailhost="smtp.example.com"
               returnaddress="${buildmaster.email}"
               returnname="${buildmaster.name}"
               subjectprefix="[BUILD ${project.name}]"
               xsldir="${reportdir}/jsp/webcontent/xsl"
               css="${reportdir}/jsp/webcontent/css/cruisecontrol.css"/>
   
       <project name="project1"/>
           <listeners>
               <currentbuildstatuslistener/>
           </listeners>
           <log>
               <merge dir="${testdir}">
           </log>
           <modificationset>
               <cvs/>
           </modificationset>
           <schedule>
               <ant/>
           </schedule>
           <publishers>
               <htmlemail>
                   <always  address="${buildmaster.email}">
                   <failure address="proj1dev@example.com">
                   <ignore address="buildmaster">
               </htmlemail>
           </publishers>
       </project>
   
       <project name="project2"/>
           <listeners>
               <currentbuildstatuslistener/>
           </listeners>
           <log>
               <merge dir="${testdir}">
           </log>
           <modificationset>
               <cvs/>
           </modificationset>
           <schedule>
               <ant/>
           </schedule>
           <publishers>
               <htmlemail>
                   <always  address="${buildmaster.email}">
                   <failure address="proj2dev@example.com">
               </htmlemail>
           </publishers>
       </project>
   
   </cruisecontrol>
               

<include.projects>

<cruisecontrol>
  <include.projects>

The <include.projects> tag is used to consolidate several configuration files into a single configuration. One advantage over using XML includes are that the target files are valid configuration files in their own right and not just XML fragments. Also, including projects using the tag is less fragile as an error in one file will not keep the rest of the projects for building.

Configuration files included this way are processed with the properties and plugins defined in the main configuration file, which easily allows per instance configuration. Properties and plugins defined in the processed files are not made available outside the scope of that file.

Project names must still remain unique. The first project with a given name will be loaded and any subsequent projects attempting to use the same name will be skipped.

Changes to any of the included file with be detected and cause the configuration to be reload, just as if they had been made to the parent file.

Attributes

<project>

<cruisecontrol>
  <project>

A <project> is the basic unit of work — it will handle checking for modifications, building, and publishing the results of your project.

Note: one config.xml file can contain several <project> elements; these projects will all run in a shared build queue (see the <threads> element if you want to build multiple projects at the same time).

Attributes

Child Elements

<listeners>

<cruisecontrol>
  <project>
    <listeners>

The <listeners> element is a container element for Listener plugin instances.

Listeners are notified with every ProjectEvent but most Listeners are designed to handle a specific subclass of ProjectEvent.

Child Elements

<cmsynergysessionmonitor>

<cruisecontrol>
  <project>
    <listeners>
      <cmsynergysessionmonitor>

The <cmsynergysessionmonitor> listener will monitor and start CM Synergy sessions as needed. It is triggered with each build loop (before the bootstrappers are run) and can monitor any number of CM Synergy sessions. The <cmsynergysessionmonitor> also provides a mapping between a simple "nick-name" for a session (which is referred to as the "sessionname") and the full CM Synergy session ID. This map is persisted in a simple properties file (referred to as the "session file").

Each time the <cmsynergysessionmonitor> runs, it will load the persisted information from the session file and attempt to verify that each monitored session is, in fact, still running. It does this according to the following rules:

1. If the session file does not exist, it will be created.
2. If an entry for the session name does not exist in the session file, a new CM Synergy session will be started and an entry recorded in the file.
3. If an entry for the session name does exist in the file, it will check that the CM Synergy session ID associated with the session name is still running. If it is, no further action is taken. If it is not, a new CM Synergy session is started, and the new ID recorded in the file.

Attributes

Child Elements

Examples

1. Monitor two sessions. The first will be associated with the database /ccmdb/product1, the second will use the database /ccmdb/product2. We will specify all attributes in the config file for the first session, and use an attribute file called "session2.properties" for the second. We will accept the default session file location of ".ccmsessionmap" in our home directory. Both sessions will run on the local host machine.

   <listeners>
       <cmsynergysessionmonitor>
           <session name="session1"
                    database="/ccmdb/product1"
                    user="buildmgr"
                    role="build_mgr"
                    password="P@ssW0rd!"/>
           <session name="session2"
                    attributefile="session2.properties"/>
       <cmsynergysessionmonitor/>
   <listeners/>
               

   Session 2 would then use a properties file as follows:

   #CM Synergy session properties for "session2"
   database=/ccmdb/product2
   user=buildmgr
   role=build_mgr
   password=P@ssW0rd!
               

<currentbuildstatuslistener>

<cruisecontrol>
  <project>
    <listeners>
      <currentbuildstatuslistener>

The CruiseControl Build Results JSP can indicate whether or not CruiseControl is currently building a project. To get this information to the JSP, we can use the optional <currentbuildstatuslistener> to write an HTML snippet to disk in a location where the JSP can read it. This file will consist of the current status of the build and the last time the status changed, with the formatting set by the dateformat element.

Attributes

<currentbuildstatuspagelistener>

<cruisecontrol>
  <project>
    <listeners>
      <currentbuildstatuspagelistener>

Updates replaceable text in a pattern file each time the Project status changes. Can show full project status history. The following items will be replaced with their values each time they occur in the source file:

• {Project} - Project Name.
• {State.Name} - Name of current project state.
• {State.Description} - Description of current project state.
• {State.Date} - Date/time the current state happened
• {State.Duration} - How long since this state was in effect. (Only useful in {History} line.)
• {History} - Historical states. Must be first on line. This line will be processed and output once for each state the project has previously been in. The {History} tag will be deleted from the line.

A default template is provided of the form "{Project}: {State.Date} - {State.Name}: {State.Description}"

Attributes

<currentbuildstatusftplistener>

<cruisecontrol>
  <project>
    <listeners>
      <currentbuildstatusftplistener>

This plugin is mostly identical to the <currentbuildstatuslistener>, to which it adds sending the HTML snippet to a remote FTP server.

Attributes

<lockfilelistener>

<cruisecontrol>
  <project>
    <listeners>
      <lockfilelistener>

This plugin works in conjunction with a <lockfilebootstrapper> to define a set of projects that will not build simultaneously in a multithreaded build environment. This plugin is responsible for deleting the lock file when a project goes IDLE (but only if the lock was created by the same project.

Attributes

<bootstrappers>

<cruisecontrol>
  <project>
    <bootstrappers>

The <bootstrappers> element is a container element for Bootstrapper plugin instances.

Bootstrappers are run before a build takes place, regardless of whether a build is necessary or not, but not if the build is paused. Each bootstrapper element is independent of the others so it is quite possible to have multiple bootstrappers of the same time, say 3 CVS or VssBootstrappers to update 3 different files.

Child Elements

<accurevbootstrapper>

<cruisecontrol>
  <project>
    <bootstrappers>
      <accurevbootstrapper>

Automatically updates an accurev workspace. The selected workspace must already exist on the local filesystem.

Attributes

Examples

1. Updates the workspace locally stored on D:\accurev\workspace_user\MyProject, after synchronizing the local clock with the autokeeping all the modified files.

   <bootstrappers>
       <accurevbootstrapper workspace="D:\accurev\workspace_user\MyProject"
           synctime="true"
           keep="true"
           verbose="true"/>
   <bootstrappers>
   

<alienbrainbootstrapper>

<cruisecontrol>
  <project>
    <bootstrappers>
      <alienbrainbootstrapper>

Syncs a single path from AlienBrain before the build begins. Useful if you want to leave all SCM up to CruiseControl. Allowing the bootstrapper to update the project makes for a simpler build.xml but allows a window where a file can be committed after the update and before the modification check.

Attributes

<antbootstrapper>

<cruisecontrol>
  <project>
    <bootstrappers>
      <antbootstrapper>

Executes an Ant script which implements a custom bootstrapper.

Attributes

Child Elements

Examples

1. Invoke the ant.bat script distributed with ant, specifying the working directory as D:\workspace\MyProject and the ant build file as MyProject-nightlybuild.xml and the ant target as bootstrap.

   <bootstrappers>
       <antbootstrapper antscript="C:\Java\apache-ant-1.6.1\bin\ant.bat"
            antworkingdir="D:\workspace\MyProject"
            buildfile="MyProject-nightlybuild.xml"
            uselogger="true"
            usedebug="false"
            target="bootstrap"/>
   <bootstrappers>

<clearcasebootstrapper>

<cruisecontrol>
  <project>
    <bootstrappers>
      <clearcasebootstrapper>

Can be used to pull a single file (usually build.xml and/or build.properties) from ClearCase prior to building.

Attributes

<clearcaseviewstrapper>

<cruisecontrol>
  <project>
    <bootstrappers>
      <clearcaseviewstrapper>

Can be used to automate the start-up of ClearCase Views and VOBs prior to building in dynamic views.

Attributes

Examples

1. Start the Windows view "j2ee_bld" and mount the VOBs "\J2EE_Sources" and "\J2EE_Binaries":

   <property name="dir.j2ee" value="M:\j2ee_bld\J2EE_Sources\src"/>            
   <bootstrappers>
       <clearcaseviewstrapper viewpath="${dir.j2ee}" voblist="\J2EE_Sources,\J2EE_Binaries"/>
   <bootstrappers>

<cmsynergybootstrapper>

<cruisecontrol>
  <project>
    <bootstrappers>
      <cmsynergybootstrapper>

Used to reconfigure a CM Synergy project or project hierarchy

Attributes

Examples

1. Reconfigure the "j2ee~1.0_int" project (but not it's subprojects) using the CM Synergy session named "j2ee_session".

   <bootstrappers>
       <cmsynergybootstrapper project="j2ee~1.0_int"
                              sessionname="j2ee_session"
                              recurse="false"/>
   <bootstrappers>

<currentbuildstatusbootstrapper>

<cruisecontrol>
  <project>
    <bootstrappers>
      <currentbuildstatusbootstrapper>

Note: this plugin has been made obsolete by the currentbuildstatuslistener.

The CruiseControl Build Results JSP can indicate whether or not CruiseControl is currently building a project. To get this information to the JSP, we can use the optional <currentbuildstatusbootstrapper> to write an HTML snippet to disk in a location where the JSP can read it. This file will consist of the time the build was started with the formatting set by the dateformat element.

This plugin is used in tandem with the currentbuildstatuspublisher.

Attributes

<currentbuildstatusftpbootstrapper>

<cruisecontrol>
  <project>
    <bootstrappers>
      <currentbuildstatusftpbootstrapper>

Note: this plugin has been made obsolete by the currentbuildstatusftplistener.

This performs the same action as <currentbuildstatusbootstrapper>, except that the status file is sent to the remote site via FTP, instead of being stored locally.

Attributes

In addition to the common FTP attributes, <currentbuildstatusbootstrapper> uses the following attributes.

<cvsbootstrapper>

<cruisecontrol>
  <project>
    <bootstrappers>
      <cvsbootstrapper>

Since there can be a reliance on the build.xml to handle updating the source code, there has always been a problem with what happens when the build.xml file itself changes. <cvsbootstrapper> can solve this problem either by pulling a single file (such as build.xml) or by updating the entire project. Allowing the bootstrapper to update the project makes for a simpler build.xml but allows a window where a file can be committed after the update and before the modification check.

Attributes

<cvsbootstrapper> requires at least one of its attributes to be set.

<execbootstrapper>

<cruisecontrol>
  <project>
    <bootstrappers>
      <execbootstrapper>

This bootstrapper executes a command. As it is based on the ExecBuilder, it has the same attributes

<lockfilebootstrapper>

<cruisecontrol>
  <project>
    <bootstrappers>
      <lockfilebootstrapper>

This plugin works in conjunction with a <lockfilelistener> to define a set of projects that will not build simultaneously in a multithreaded build environment. This plugin is responsible for creating the lock file if it doesn't already exist, or if it does, to throw an exception to abort the build attempt. When a build attempt is aborted the project will not be retried until the next build time as determined by the schedule interval or the schedule build time.

Attributes

<p4bootstrapper>

<cruisecontrol>
  <project>
    <bootstrappers>
      <p4bootstrapper>

Syncs a single path from Perforce before the build begins. Useful if you want to leave all SCM up to CruiseControl. Allowing the bootstrapper to update the project makes for a simpler build.xml but allows a window where a file can be committed after the update and before the modification check.

Setting the path to a complete P4 depot ending with a typical triple dot (...) will synch all the files, e.g. //depot/myproject/...

Note that the attributes path, p4Port, p4User, and p4Client are deprecated. Please use the attributes listed below.

Attributes

<plasticscmbootstrapper>

<cruisecontrol>
  <project>
    <bootstrappers>
      <plasticscmbootstrapper>

Automatically updates the workspace before the build begins. The selected workspace must already exist on the local filesystem.

Attributes

Examples

1. Update the workspace (using the option forced) in the path in c:\work\cruise\plasticwks setting the branch "br:/main" as working branch.

   <bootstrappers>
       <plasticscmbootstrapper wkspath="c:\work\cruise\plasticwks"
   		            branch="br:/main"
   		            forced="yes" />
   <bootstrappers>

<snapshotcmbootstrapper>

<cruisecontrol>
  <project>
    <bootstrappers>
      <snapshotcmbootstrapper>

Can be used to pull a single file (usually build.xml and/or build.properties) or directory from SnapshotCM prior to building.

Attributes

<starteambootstrapper>

<cruisecontrol>
  <project>
    <bootstrappers>
      <starteambootstrapper>

Handles updating multiple files (space separated list) from StarTeam before the build begins.

Attributes

<surroundbootstrapper>

<cruisecontrol>
  <project>
    <bootstrappers>
      <surroundbootstrapper>

Fetches a single repository (and optionally it's sub-repositories) from Surround SCM before starting the build.

Attributes

<svnbootstrapper>

<cruisecontrol>
  <project>
    <bootstrappers>
      <svnbootstrapper>

Handles updating a single file (typically build.xml and/or build.properties) from a Subversion repository before the build begins.

Attributes

<vssbootstrapper>

<cruisecontrol>
  <project>
    <bootstrappers>
      <vssbootstrapper>

Handles updating a single file (typically build.xml and/or build.properties) from VSS before the build begins.

Attributes

<modificationset>

<cruisecontrol>
  <project>
    <modificationset>

A container element for a set of modifications collected from all included SourceControl elements. <modificationset> can contain multiple elements which can be useful to check only parts of a large project rather than checking all files every time.

Most SourceControl elements support the property /propertyOnDelete attributes which can allow for conditional building that may greatly speed the feedback cycle.

Attributes

Child Elements

<accurev>

<cruisecontrol>
  <project>
    <modificationset>
       <accurev>

Checks for modifications in an AccuRev stream.

Attributes

<alienbrain>

<cruisecontrol>
  <project>
    <modificationset>
      <alienbrain>

Triggers a build if there is a change in an AlienBrain repository.

Changes are detected by running a command similar to the following:

ab find PathToProject -regex "SCIT > lastbuildtime" 

Attributes

<alwaysbuild>

<cruisecontrol>
  <project>
    <modificationset>
      <alwaysbuild>

Used to always trigger a build by returning a single modification.

Attributes

<buildstatus>

<cruisecontrol>
  <project>
    <modificationset>
      <buildstatus>

Used to trigger a build when another CruiseControl project has a successful build. When triggered, this will report a modification with action "add", the successfully built project's logfile, the name of the successfully built project's log directory (the final component of attribute logdir), and the username set to "cc-" + name of the successfully built project. You may need make an alias for this username if you are using an <email> publisher.

Attributes

Properties Passed to the Builders

In addition to the standard CruiseControl properties passed to builders, <buildstatus> sets the following properties:

<clearcase>

<cruisecontrol>
  <project>
    <modificationset>
      <clearcase>

Triggers a build if there is a change within a ClearCase repository.

Attributes

Properties Passed to the Builders

In addition to the standard CruiseControl properties passed to builders, <clearcase> sets the following properties:

<cmsynergy>

<cruisecontrol>
  <project>
    <modificationset>
      <cmsynergy>

Triggers a build if tasks have been added to any folder within a CM Synergy project's reconfigure properties since the last build.

Attributes

Properties Passed to the Builders

In addition to the standard CruiseControl properties passed to builders, <cmsynergy> sets the following properties:

Examples

1. Use the session named "j2ee_session" to check for changes within the "j2ee~1.0_int" project. If any changes are detected, reconfigure the project and all of it's subprojects.

   <modificationset>
       <cmsynergy project="j2ee~1.0_int"
                  sessionname="j2ee_session"
                  reconfigure="true"/>
   <modificationset/>
               

2. For users of CM Synergy older than version 6.3 only. Use the <cmsynergybootstrapper> to reconfigure only the top level "j2ee~1.0_int" project. This will update the folders within that project's reconfigure properties. We can then check for changes just as we did in the first example. Notice that we must set the "updatefolder" attribute to false.

   <bootstrappers>
       <cmsynergybootstrapper project="j2ee~1.0_int"
                              sessionname="j2ee_session"
                              recurse="false"/>
   <bootstrappers>
   <modificationset>
       <cmsynergy project="j2ee~1.0_int"
                  updatefolders="false"
                  sessionname="j2ee_session"
                  reconfigure="true"/>
   <modificationset/>
               

<compound>

<cruisecontrol>
  <project>
    <modificationset>
      <compound>

Contains two separate lists of source controls: <triggers> and <targets>. Triggers are checked for modifications every scheduled poll. Targets are only checked for modifications if there was any modifications detected in the triggers.

Arbitrary nesting of source controls under <triggers> and <targets> is possible.

The <compound> element allows optimized access to source repositories, avoiding a full scan of the repository every scheduled interval. A typical usage scenario is to configure the source repository to update a single file after a commit, meaning that only a single file need be checked in the triggers section.

In addition to the modifications returned by the target source controls all of their properties are returned as well. If includeTriggerChanges is set then the properties returned by the triggers are returned as well.

Attributes

Child Elements