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

<dashboard>

<cruisecontrol>
  <dashboard>

The <dashboard> tag is used to set the configuration for build loop posting builds information to the dashboard.

If this element is not specified in config.xml, CruiseControl will first check command-line. If neither of this set, then CruiseControl will use default.

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!
               

<compoundpublisher>

<cruisecontrol>
  <project>
    <publishers>
      <compoundpublisher>

Provides the means to execute another publisher (or set of publishers). This is accomplished by simply adding any desired publishers as child elements.

All child elements must meet the following criteria:

1. They must be registered as publishers. If you are adding a publisher which ships with CruiseControl, this will be done for you automatically. If you are adding a custom publisher, you must remember to register it with CruiseControl using a <plugin> element within your config file.
2. They must validate successfully regardless of whether or not the build was successful.

Child Elements

Examples

1. After a build, use the x10 publisher to light up a lamp, and call an Ant script to do some cleanup.

   <compoundpublisher>
       <x10 houseCode="A" deviceCode="3"/>
       <antpublisher antscript="/opt/apache-ant-1.6.1/bin/ant"
                     target="cleanupafterfailure">
       </antpublisher>
   </compoundpublisher>
               

<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.

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>

<cmsynergybaselinebootstrapper>

<cruisecontrol>
  <project>
    <bootstrappers>
      <cmsynergybaselinebootstrapper>

Due to the nature of certain Synergy project types basing their reconfigure on baselines it may sometimes be necessary to create a baseline prior to the build. This bootstrapper works almost identically to the cmsynergybaselinepublisher with the exception that is will not depend on modifications being found due to its execution before any modificationset is run.

Attributes

Examples

1. Create a baseline called "test_baseline" for project "test_project_1~dev410" with purpose "System Testing", status "released" and build "QA432", re-using existing Synergy session "cc_session"

   <bootstrappers>
       <cmsynergybootstrapper project="test_project~dev410"
                              sessionname="cc_session"
                              build="QA432"
                              purpose="System Testing"
                              state="released"
                              baselinename="test_baseline"/>
   <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.

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

<gitbootstrapper>

<cruisecontrol>
  <project>
    <bootstrappers>
      <gitbootstrapper>

Handles updating from a git repository before the build begins.

Attributes

<harvestbootstrapper>

<cruisecontrol>
  <project>
    <bootstrappers>
      <harvestbootstrapper>

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. <harvestbootstrapper> 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.

In order to use this element, you must have the AllFusion Harvest client installed on the CruiseControl machine. Additionally, the HARVESTHOME environment variable should be set (this should happen during installation of AllFusion Harvest). And you'll need to build the plugin.

The jar you'll need to build the plugin is jhsdk.jar from your Harvest installation. To build the plugin read the directions for Building Plugins That Need External Libraries

Attributes

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

<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

<mercurialbootstrapper>

<cruisecontrol>
  <project>
    <bootstrappers>
      <mercurialbootstrapper>

Handles updating from a Mercurial repository before the build begins.

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.

To use this plugin you'll need to build it. The jar you'll need to build the plugin is starteam-sdk.jar. To build the plugin read the directions for Building Plugins That Need External Libraries

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

<tfsbootstrapper>

		<cruisecontrol>
		  <project>
			<bootstrappers>
			  <tfsbootstrapper>

Gets a single path from Visual Studio Team Foundation Server before the build begins.

Gets are performed by calling out to the TFS command line (tf). Microsoft provide the tf.exe command line tool as part of the Team Explorer client installation on Windows platforms. For information on obtaining the Microsoft Team Explorer client, visit CodePlex wiki. Teamprise also provide a tf command that works cross-platform including GNU/Linux, Mac, MP-UX and Solaris platforms as well as Windows.  To download the Teamprise command line client, visit the Teamprise download site (fully functional evaluation licenses are available).  Note that the Teamprise client requires activation when using it with a purchased license, for instructions on how to activate from the command line consult the Teamprise Knowledgebase.

Gets are performed by executing a command similar to the following

tf get //build/path/to.get
           -recursive -force -noprompt
           -login:DOMAIN\name,password

For further details regarding the tf get command, consult the MSDN documentation.

Setting the path to a folder and setting the recursive option to true will get all the files in that folder and subfolders. This is useful if you want to leave the SCM up to CruiseControl. Allowing the bootstrapper to perform a get latest does make for a simplified build.xml, but it allows a window where a file can be checked in after this get but before the modification check.

For this to work, you must have an existing TFS workspace created for the user on the build server and a working folder mapping created. For example, in the case where the project location is /cruisecontrol/projects/myproject and the files are stored in TFS at $/MyTeamProject/trunk you would have first needed to execute the following commands on the machine running cruisecontrol

tf workspace /server:http://tfsserver:8080 /login:user@DOMAIN,password /new buildWorkspace

tf workfold /server:http://tfsserver:8080 /login:user@DOMAIN,password /workspace:buildWorkspace /map $/MyTeamProject/trunk //cruisecontrol/projects/myproject
        

If you would like gets to be performed using a TFS Version Control Proxy and you are using the Microsoft tf.exe command line then you should set the environment variable TFSPROXY (for example set TFSPROXY=http://tfsproxy:8081. If you are using the Teamprise command line client, then you may pass "-proxy:http://tfsproxy:8081" in the options attribute.

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