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="[email protected]"/>
   
       <project name="project1">
           <!-- ${buildmanager} resolves to "[email protected]" -->
       </project>
   
       <project name="project2">
           <property name="buildmanager" value="[email protected]"/>
           <!-- ${buildmanager} resolves to "[email protected]" -->
       </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="[email protected]"/>
       <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="[email protected]">
                   <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="[email protected]">
               </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

Example

This example polls the file mod_file.txt every scheduled interval using <filesystem>. When a change is detected, <cvs> is used to determine the full list of modifications. If mod_file.txt is never modified, cvs is never accessed.

<modificationset quietperiod="1" >
    <compound includeTriggerChanges="false">
        <triggers>
            <filesystem folder="./mod_file.txt" />
        </triggers>
        <targets>
            <cvs
                cvsroot=":pserver:user@cvs_repo.com:/cvs"
            />
        </targets>
    </compound>
</modificationset>

<cvs>

<cruisecontrol>
  <project>
    <modificationset>
      <cvs>

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

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

cvs [-d CVSROOT] -q log|rlog [-N] -d "lastbuildtime<checktime" [-b|-rTAG] module

The following changes are made to generate the actual command:

• log is used when the localworkingcopy attribute is set, rlog otherwise.
• lastbuildtime is replaced with the date of the last build, using the date format yyyy-MM-dd HH:mm:ss 'GMT'.
• checktime is replaced with the date at which the check takes place.
• The -d option is only used when the cvsroot attribute is specified; CVSROOT is replaced by the value of that attribute.
• The -r option is only used when the tag attribute is specified; TAG is replaced by the value of that attribute. Otherwise, the -b option is used.
• The -N option is only used when the tag attribute is not specified or if it is set to HEAD.
• module is replaced with the specified module name. If a local working copy is used then the module name is left off.

Refer to the cvs log reference for further details of the cvs log command.

A notable feature of the CVS element is that it will look for the file CVSROOT/users and, if the files exists, use the information in that file to map cvs usernames to email addresses. More details are on the CVSROOT/users page of the CruiseControl Wiki.

Attributes

<filesystem>

<cruisecontrol>
  <project>
    <modificationset>
      <filesystem>

Returns all files beneath the specified folder than have been modified since the last build time. Any modified files are reported as modifications of type "changed" by user "User". Can also have folder be just a single file. Only looks at timestamp, not for actual changes to the file.

Attributes

<forceonly>

<cruisecontrol>
  <project>
    <modificationset>
      <forceonly>

Never returns any changes. Use this to define a project that only builds when forced to, like for release builds. If you also want the modifications between two forced builds to be reported, you'll have to use another solution (for instance, define a <compound> with a <filesystem> in the <triggers> and touch the specified file to force a build).

Attributes

<harvest>

<cruisecontrol>
  <project>
    <modificationset>
      <harvest>

Checks a AllFusion Harvest CM 5.1.1 repository for changes.

Attributes

 <harvest userName="myUserName" password="myPassword"
    brokerName="myHarvestBrokerName" projectName="myHarvestPackage"/>
        

<httpfile>

<cruisecontrol>
  <project>
    <modificationset>
      <httpfile>

Checks a single file on a web server supporting modification dates (such as Apache). Intended to be used in a Compound modification set as a Trigger.

Attributes

<mavensnapshotdependency>

<cruisecontrol>
  <project>
    <modificationset>
      <mavensnapshotdependency>

Triggers a build if a Maven snapshot detects a change.

Attributes

<maven2snapshotdependency>

<cruisecontrol>
  <project>
    <modificationset>
      <maven2snapshotdependency>

Triggers a build if a Maven2 snapshot detects a change.

Attributes

<mks>

<cruisecontrol>
  <project>
    <modificationset>
      <mks>

Triggers a build if there is a change within an MKS repository. Has the following prerequisites:

1. The sandbox must always exists. The MKS sourcecontrol are unable to create the sandbox for you. In principle, this is not a real problem as long as the underlying MKS command si are able to handle such a task, but in this initial version I don't create a sandbox during runtime. If you not always create your sandbox, see si createsandbox for more information.
2. You have already logged in into the MKS Server. This should be done in your bootstrap section by the ANT task siconnect. The underlying java class is situated in the mksant.jar which is available through the MKS Customer Community. Since this (and the corresponding sidisconnect) anttasks are only small wrapper for the command line call of si, this could be done in later versions by the MKS sourcecontroller itself. You should call the sidisconnect task after your build, e.g. during your publishing phase.

Attributes

<p4>

<cruisecontrol>
  <project>
    <modificationset>
      <p4>

Triggers a build if there is a change within an Perforce repository.

Attributes

<plasticscm>

<cruisecontrol>
  <project>
    <modificationset>
      <plasticscm>

Checks for changes in a Plastic SCM repository.

Attributes

Examples

1. Used to check for changes in the branch br:/main.

   <modificationset>
       <plasticscm wkpath="c:\work\cruise\plasticwks"
                   branch="br:/main" />
   <modificationset/>
               

<pvcs>

<cruisecontrol>
  <project>
    <modificationset>
      <pvcs>

Checks for changes in a PVCS repository.

Attributes

<snapshotcm>

<cruisecontrol>
  <project>
    <modificationset>
      <snapshotcm>

Checks for changes in a SnapshotCM repository.

Attributes

<starteam>

<cruisecontrol>
  <project>
    <modificationset>
      <starteam>

Checks for changes in a Star Team repository.

If logged on as SERVER ADMINISTRATOR it will look up the email associated with the user account for each modification.

Attributes

<surround>

<cruisecontrol>
  <project>
    <modificationset>
      <surround>

Attributes

<svn>

<cruisecontrol>
  <project>
    <modificationset>
      <svn>

Checks for changes within a Subversion repository.

Attributes

<timebuild>

<cruisecontrol>
  <project>
    <modificationset>
      <timebuild>

Triggers a build after a particular time threshold. This will return a single modification from the (fake) user only if no successful build has happened since the last specified time threshold. Once a successful build occurs, no more modification is returned

Attributes

<ucm>

<cruisecontrol>
  <project>
    <modificationset>
      <ucm>

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

Attributes

Properties Passed to the Builders

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

<veto>

<cruisecontrol>
  <project>
    <modificationset>
      <veto>

This plugin is designed to help enforce build order between dependent projects. It will check to see if a project is up to date and vetos the build attempt if it is not. Veto is configured by defining a nested set of sourcecontrols and a buildstatus element. If project foo depends on project bar then bar may have a <veto> with triggers that are the same as the modificationset for foo and a <buildstatus> that points to the logs for foo. If there is a change that would cause foo to build but bar is first in the build queue, then the <veto> in bar will detect that foo is out of date and abort the build attempt by throwing an exception.

Unlike most source controls, Veto never returns any modifications. Its only job is to abort builds when another project is out of date with respect to some set of modifications.

Child Elements

Example

In this if there are changes in the cvs repository for foo since the last time project foo built successfully then the veto will throw an exception and abort the build attempt. If there are no changes in the repository for foo or project foo is up to date then <veto> will do nothing and the build attempt will continue as normal (building if there are modifications detected in the reposiotry for bar).

<modificationset>
    <veto>
        <triggers>
            <cvs
                cvsroot=":pserver:user@cvs_repo.com:/cvs/foo"
            />
        </triggers>
        <buildstatus logdir="logs/foo" />
    </veto>
    <cvs cvsroot=":pserver:user@cvs_repo.com:/cvs/bar"/>
</modificationset>

<vss>

<cruisecontrol>
  <project>
    <modificationset>
      <vss>

Checks for changes in a Visual SourceSafe repository.

Attributes

<vssjournal>

<cruisecontrol>
  <project>
    <modificationset>
      <vssjournal>

Checks for changes in a Visual SourceSafe repository.

This implementation doesn't require the source safe executable making it suitable for use on non-Windows machines.

Attributes

<schedule>

<cruisecontrol>
  <project>
    <schedule>

CruiseControl allows the user to schedule an arbitrary number of builds, either on interval or triggered to run at a given date/time, as well as pause intervals during which no builds will be run. Be aware that builds will only run if modifications are found (or build is forced from JMX interface). Because of this it is usually not a good idea to mix time builds and multiple builds in the same project as the multiple builds will "eat" all the changes before they can be detected by the time based builds.

Note: Only one builder is used for a given interval where modifications are found. Builds using the time attribute take precedence over builds using the multiple attribute. If no matching time builds are found the multiple builds are evaluated in the order they appear in the file, so a multiple='1' on the first builder will hide all the subsequent builders.

Attributes

Child Elements

Properties Passed to Builders

When CruiseControl runs your build script (Ant or Maven), it passes some information in the form of system properties to the script. These can be accessed in your script like any other property, using the syntax ${propertyname}.

Here's a list of all the properties that are available to your script:

Some child elements of <modificationset> also set properties for the builders. In particular:

• <buildstatus> sets specific properties.
• <clearcase> sets specific properties.
• If specified, the property or propertyondelete attribute value will be set. This feature is supported by <clearcase>, <cvs>, <filesystem>, <mavensnapshotdependency>, <maven2snapshotdependency>, <mks>, <snapshotcm>, <starteam>, <vss> and <vssjournal>.

<ant>

<cruisecontrol>
  <project>
    <schedule>
      <ant>

Specifies an Ant build to be run at a given time or build number. For instance, we can run a clean build every 5 builds, or run more comprehensive (and time intensive) system tests every 10 builds. We can also schedule an official build to run every night at midnight, if we so desire.

When a build runs, Ant is invoked in a separate Java process. There are two alternative ways in which ant may be invoked:

1. Using the antscript, or anthome, attribute (preferred) helps to ensure that builds are run completely independent of the CruiseControl distribution, and that extra jars required in the ant lib-directory need not be duplicated within CruiseControl.
2. Using the ant binaries distributed with CruiseControl. Settings for the virtual machine can be specified using the nested <jvmarg> element. This also requires that java be on the executable path.

The standard CruiseControl properties passed to builders are available from within the ant build.

See below for examples of the <ant> element.

Attributes

Child Elements

Examples

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

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

   Or equivalently, using the anthome attribute

   <schedule>
       <ant anthome="C:\Java\apache-ant-1.6.1"
            antworkingdir="D:\workspace\MyProject"
            buildfile="MyProject-nightlybuild.xml"
            uselogger="true"
            usedebug="false"/>
   <schedule>

2. Invoke a custom ant script /home/cc/workspace/build.sh, specifying the working directory as /home/cc/workspace and the ant target as smoketest.

   <schedule>
       <ant antscript="/home/cc/workspace/build.sh"
            antworkingdir="/home/cc/workspace"
            target="smoketest"
            uselogger="true"/>
   <schedule>

   The custom build script can be any shell script, batch file or program that understands how to invoke ant. Here is an example that would be appropriate under Unix:

   #!/bin/sh
   PROJECT_HOME=`dirname "$0"`
   ANT_HOME=${PROJECT_HOME}/tools/ant
   chmod 0755 ${ANT_HOME}/bin/ant
   ANT_CMD=${ANT_HOME}/bin/ant
   exec "$ANT_CMD" "$@"

   Note the double quotes around $@: this ensures that all arguments will be quoted, which is necessary for arguments containing spaces.

   An example of a Windows batch file to invoke ant:

   @echo off
   setlocal
   set PROJECT_HOME=%~dp0
   call %PROJECT_HOME%..\devtools\env.bat
   call ant.bat %*
   endlocal

   The %* as a param to ant.bat is important — it means that all the arguments to build.bat are passed along to ant.bat. If this is skipped then CruiseControl wouldn't work properly.

<maven>

<cruisecontrol>
  <project>
    <schedule>
      <maven>

Specify a Maven build to be run at a given time or build number. Basically, it behaves like the AntBuilder, with some differences noted below. MavenBuilder runs (an already installed copy of) Maven over the specified project. Due to the current status of Maven (in heavy development) only the "script" start mode is supported.

The goal attribute has the following usage examples:

• "clean" will run 'clean' goal on the project
• "clean java:compile" will run 'clean' goal then 'java:compile' goal on the project, within the same Maven session run
• "clean my-cvs-update|java:compile" will run 'clean' goal then 'my-cvs-update' goal on the project, within the same Maven session run, then it will run Maven again with goal 'java:compile'. Handy behavior for running update goals that update the "project.xml" itself (or the like). Arbitrary number of subsets allowed . Subset separator is '|'.

The standard CruiseControl properties passed to builders are available from within the maven build.

Attributes

<maven2>

<cruisecontrol>
  <project>
    <schedule>
      <maven2>

Specify a Maven2 build to be run at a given time or build number. Basically, it behaves like the AntBuilder, with some differences noted below. Maven2Builder runs (an already installed copy of) Maven2 over the specified project. Due to the current status of Maven (in heavy development) only the "script" start mode is supported.

The goal attribute has the following usage examples:

• "clean" will run 'clean' goal on the project

• "clean compile" will run 'clean' goal then 'compile' goal on the project, within the same Maven2 session run

• "clean my-cvs-update|compile" will run 'clean' goal then 'my-cvs-update' goal on the project, within the same Maven session run, then it will run Maven again with goal 'compile'. Handy behavior for running update goals that update the "pom.xml" itself (or the like). Arbitrary number of subsets allowed . Subset separator is '|'.

The standard CruiseControl properties passed to builders are available from within the maven build, with one exception: The "cvstimestamp" property contains spaces in its value, like: -Dcvstimestamp=2006-11-29 03:41:04 GMT. To avoid problems when maven2 parses this property from the command line, spaces in build property values will be replaced with underscores, like: -Dcvstimestamp=2006-11-29_03:41:04_GMT.

Attributes

Child Elements

<composite>

<cruisecontrol>
  <project>
    <schedule>
      <composite>

The CompositeBuilder executes a list of builders. This is necessary for builds in an empty directory (see keyword CRISP-builds in Pragmatic Project Automation from Mike Clark)

Child Elements

<pause>

<cruisecontrol>
  <project>
    <schedule>
      <pause>

It may be necessary for CruiseControl to halt executing in some circumstances. A disk backup could lock the source control repository, causing CruiseControl to return errors. Rather than deal with these errors all the time, we can specify a time period for CruiseControl to not attempt any builds.

Attributes

<nant>

<cruisecontrol>
  <project>
    <schedule>
      <nant>

Specifies a NAnt build to be run at a given time or build number. For instance, we can run a clean build every 5 builds, or run more comprehensive (and time intensive) system tests every 10 builds. We can also schedule an official build to run every night at midnight, if we so desire.

When a build runs, NAnt is invoked in a separate Java process. NAnt and the .NET Framework or Mono need to be installed for this builder to function. See NAnt's documentation for details on configuration and compatibility with .NET implementations.

The standard CruiseControl properties passed to builders are available from within the NAnt build.

See below for examples of the <nant> element.

Attributes

Child Elements

Examples

1. Invoke NAnt, specifying the working directory as D:\workspace\MyProject and the NAnt build file as MyProject-nightly.build using the default target.

   <schedule>
       <nant nantworkingdir="D:\workspace\MyProject"
            buildfile="MyProject-nightly.build"
            uselogger="true"
            usedebug="false"/>
   <schedule>

2. Invoke NAnt, specifying the working directory as /home/cc/workspace, the build file as default.build, the nant target as smoketest, and the targetframework as .NET version 1.1.

   <schedule>
       <nant targetframework="net-1.1"
            nantworkingdir="/home/cc/workspace"
            target="smoketest"
            uselogger="true"/>
   <schedule>

<phing>

<cruisecontrol>
  <project>
    <schedule>
      <phing>

Specifies a Phing build to be run at a given time or build number. For instance, we can run a clean build every 5 builds, or run more comprehensive (and time intensive) system tests every 10 builds. We can also schedule an official build to run every night at midnight, if we so desire.

When a build runs, Phing is invoked in a separate Java process. Phing and the PHP requisites need to be installed for this builder to function. See Phing's documentation for details on installation and configuration.

The standard CruiseControl properties passed to builders are available from within the Phing build.

See below for examples of the <phing> element.

Attributes

Child Elements

Examples

1. Invoke the phing.bat script distributed with phing using the phingscript attribute, specifying the working directory as D:\workspace\MyProject and the phing build file as MyProject-nightlybuild.xml using the default target.

   <schedule>
       <phing phingscript="C:\PHP\applications\phing-2.3.0\bin\phing.bat"
            phingworkingdir="D:\workspace\MyProject"
            buildfile="MyProject-nightlybuild.xml"
            uselogger="true"
            usedebug="false"/>
   <schedule>

   Or equivalently, using the phinghome attribute

   <schedule>
       <phing phinghome="C:\PHP\applications\phing-2.3.0\bin\"
            phingworkingdir="D:\workspace\MyProject"
            buildfile="MyProject-nightlybuild.xml"
            uselogger="true"
            usedebug="false"/>
   <schedule>

<exec>

<cruisecontrol>
  <project>
    <schedule>
      <exec>

Runs a specified command or script as part of the build. Reports build failure if the command cannot be run or returns an error. There is also a capability to search for a user defined string in the command output, for example, "build failed" and if so return an error.

See below for examples of the <exec> element.

Attributes

Examples

1. Invoke execbuilder, specifying the working directory as /workspace/myproject and executing the Perl script backup.pl.

   <schedule>
       <exec workingdir="/workspace/myproject"
            command="/usr/local/bin/Perl"
            args="backup.pl"/>
   </schedule>

2. Invoke execbuilder, specifying the working directory as D:\Workspace\MyProject, the script file as build.bat, its arguments as smoketest, and the error message to be search for as build failed.

   <schedule>
       <exec command="build.bat"
            workingdir="D:\Workspace\MyProject"
            args="smoketest"
            errorstr="build failed"/>
   </schedule>

<log>

<cruisecontrol>
  <project>
    <log>

Optional element specifies where cruisecontrol log files are stored and, via the nested merge element, specifies what xml files created by the build process should be merged into the CruiseControl build log.

Attributes

Child Elements

<merge>

<cruisecontrol>
  <project>
    <log>
      <merge>

After the build is complete, there may be other xml artifacts to merge into the cruisecontrol log. The most common of these is the junit test results that the Ant <junit> task creates. We can add a merge entry for these files so that we have one comprehensive log at the end of a cruisecontrol build.

Attributes

<cruisecontrol>
  <project>
    <log>
      <gzip>

<cruisecontrol>
  <project>
    <log>
      <delete>

<publishers>

<cruisecontrol>
  <project>
    <publishers>

Publishers are run after a build has completed. They will be run regardless of whether the build was successful or not.

Child Elements

<antpublisher>

<cruisecontrol>
  <project>
    <publishers>
      <antpublisher>

Executes an Ant script which implements a custom publisher.

Attributes

Child Elements

Properties Passed to the Publisher

In addition to the standard CruiseControl properties, <antpublisher> passes the following properties to Ant, which can be accessed in your script like any other property, using the syntax ${propertyname}.

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 publish. Pass in the property "custom" with a value of "true".

   <publishers>
       <antpublisher antscript="C:\Java\apache-ant-1.6.1\bin\ant.bat"
            antworkingdir="D:\workspace\MyProject"
            buildfile="MyProject-nightlybuild.xml"
            uselogger="true"
            usedebug="false"
            target="publish">
           <property name="custom" value="true"/>
       </antpublisher>
   </publishers>

   You could then do something like the following in MyProject-nightlybuild.xml:

   <project name="MyProject-nightlybuild" default="publish">
       <target name="publish">
           <echo>custom is set to ${custom}</echo>
           <concat>
               <filelist dir="${logdir}" files="${logfile}"/>
           </concat>
       </target>
   </project>

<artifactspublisher>

<cruisecontrol>
  <project>
    <publishers>
      <artifactspublisher>

Copies build products to unique destination directory based on the build timestamp.

Attributes

<clearcasebaselinepublisher>

 <cruisecontrol>
   <project>
     <publishers>
       <clearcasebaselinepublisher>
                

Creates a ClearCase UCM baseline for the specified view's integration stream. Uses the value of the CruiseControl generated ${label} property as well as the value of the baselineprefix attribute (if specified) to name the baseline. A baseline is only created if UCM modifications are recorded in the build log. By default an incremental baseline is created although a full baseline can be created too (incremental baselines are recommended for Continuous Integration).

Attributes

Examples

1. Create a baseline with the name "J2EE_" followed by the CruiseControl generated build label using the view tag "j2ee_int" and restricting the baseline to the "J2EE_SRC" component.

    <publishers>
        <clearcasebaselinepublisher viewtag        = "j2ee_int"
                                    baselineprefix = "J2EE_"
                                    component      = "J2EE_SRC"/>
    </publishers>
                       

<cmsynergybaselinepublisher>

<cruisecontrol>
  <project>
    <publishers>
      <cmsynergybaselinepublisher>

Creates an intermediate baseline which encompass the specified project and all of it's subprojects. This publisher will only run if the build was successful and the modification set contains at least one new CM Synergy task. This publisher will only work with CM Synergy version 6.3 or later.

Attributes

Examples

1. Create a baseline with the name "BUILD_" followed by the CC timestamp for the purpose of "Integration Testing" using the session called "j2ee_session" incorporating the "j2ee~1.0_int" project and all subprojects.

   <publishers>
       <cmsynergybaselinepublisher sessionname  = "j2ee_session"
                                   project      = "j2ee~1.0_int"
                                   baselinename = "BUILD_@{cctimestamp}"/>
   </publishers>
               

<cmsynergytaskpublisher>

<cruisecontrol>
  <project>
    <publishers>
      <cmsynergytaskpublisher>

The <cmsynergytaskpublisher> is used to copy tasks into a shared folder. The folder may be specified by number, or by providing the 2 part name of the project as well as a substring of the folder's name. This publisher will only run if the build was successful and the modification set contains at least one new CM Synergy task.

Attributes

Examples

1. Publish all new tasks into folder number 203 using the CM Synergy session named "j2ee_session".

   <publishers>
       <cmsynergytaskpublisher sessionname  = "j2ee_session"
                               foldernumber = "203"/>
   </publishers>
               

2. Publish all new tasks into the folder called "Integration tested tasks for release j2ee/1.0" found in the project "j2ee~1.0_int" using the CM Synergy session named "j2ee_session".

   <publishers>
       <cmsynergytaskpublisher sessionname  = "j2ee_session"
                               project      = "j2ee~1.0_int"
                               foldername   = "Integration tested tasks"/>
   </publishers>
               

<currentbuildstatuspublisher>

<cruisecontrol>
  <project>
    <publishers>
      <currentbuildstatuspublisher>

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

The CruiseControl Build Results JSP will indicate whether or not CruiseControl is currently building a project. To get this information to the JSP, we write an HTML snippet to disk in a location where the JSP can read it. This file will consist of the time the next build attempt will take place, so there is an optional attribute to customize the dateformat.

This plugin is used in tandem with the currentbuildstatusbootstrapper.

Attributes

<execute>

<cruisecontrol>
  <project>
    <publishers>
      <execute>

Execute a command as part of the publishing phase.

Attributes

<scp>

<cruisecontrol>
  <project>
    <publishers>
      <scp>

SCP a file as part of the publishing process.

Attributes

<sfeedocman>

<cruisecontrol>
  <project>
    <publishers>
      <sfeedocman>

Creates a Document Manager document in a SourceForge Enterprise Edition project. All child elements may include either hardcoded values, or use an xpath expression to define the value at runtime.

NOTE: To use this publisher, you must supply the jars included in the SourceForge SOAP SDK. The publisher is compiled against a stub implementation of that SDK. Remove the stub jar (inmemorysfee-x.x.x.jar) and put the SDK jars in its place and make them available in CruiseControl's classpath.

Attributes

Child Elements

Examples

<!-- Upload Project.xls to SFEE, using XPath to set
   the description to the date and time of each build. -->
<sfeedocman file="target/myapp-1.0.0.jar"
   serverurl="http://mysfeeinstance.com"
   username="sfeeuser"
   password="mypassword"
   projectname="myproject"
   folder="/Root Folder/"
   document="projects/myproject/Project.xls">
       <description xpathexpression="/cruisecontrol/info/property[@name='builddate']/@value"/>
       <status value="final"/>
</sfeedocman>

<sfeefrs>

<cruisecontrol>
  <project>
    <publishers>
      <sfeefrs>

Uploads a file to a SourceForge Enterprise Edition project's file release system (FRS).

NOTE: To use this publisher, you must supply the jars included in the SourceForge SOAP SDK. The publisher is compiled against a stub implementation of that SDK. Remove the stub jar (inmemorysfee-x.x.x.jar) and put the SDK jars in its place and make them available in CruiseControl's classpath.

Attributes

Examples

<!-- Upload myapp-1.0.0.jar to SFEE using the same filename. -->
<sfeefrs file="target/myapp-1.0.0.jar"
    serverurl="http://mysfeeinstance.com"
    username="sfeeuser"
    password="mypassword"
    releaseid="rel2509"/>

<!-- Upload myapp-1.0.0.jar to SFEE, but call it myapp-current.jar
    in the FRS. -->
<sfeefrs file="target/myapp-1.0.0.jar"
    serverurl="http://mysfeeinstance.com"
    username="sfeeuser"
    password="mypassword"
    releaseid="rel2509"
    uploadname="myapp-current.jar"/>

<sfeetracker>

<cruisecontrol>
  <project>
    <publishers>
      <sfeetracker>

Creates a Tracker artifact in a SourceForge Enterprise Edition project. Artifact fields are defined as subelements, where the always mandatory fields title, description and status are required children. Other fields with arbitrary names and values are defined as "field" subelements. All fields may include either hardcoded values, or use an xpath expression to define the value at runtime.

NOTE: To use this publisher, you must supply the jars included in the SourceForge SOAP SDK. The publisher is compiled against a stub implementation of that SDK. Remove the stub jar (inmemorysfee-x.x.x.jar) and put the SDK jars in its place and make them available in CruiseControl's classpath.

Attributes

Child Elements

Examples

<!-- Creates a new SFEE tracker entry for monitoring unit test statistics. -->
<sfeetracker serverurl="http://my.sourceforge.instance"
   username="user"
   password="pass"
   trackerName="UnitTestStatistics"
   projectName="mysfeeproject">
        <title value="Unit Tests" />
        <description value="The test statistics from my SFEE project." />
        <status value="Closed" />
        <field name="TotalNumberOfUnitTests" xpathExpression="sum(cruisecontrol/testsuite/@tests)" />
</sfeetracker>

<email>

<cruisecontrol>
  <project>
    <publishers>
      <email>

Sends an email with a URL to the build results JSP.

Attributes

Child Elements

<htmlemail>

<cruisecontrol>
  <project>
    <publishers>
      <htmlemail>

Sends an email with the build results embedded as HTML. By default the same information as the JSP build results page is sent.

Typical usage is to define xsldir and css to point to cruisecontrol locations. This publisher creates HTML email by transforming information based on a set of internally pre-defined xsl files. (Currently "header.xsl", and "buildresults.xsl") This list can be changed, or appended to, using xslfilelist attribute. Alternatively, you can specify a single xsl file to handle the full transformation using the xslfile attribute.

Attributes

All of the attributes and child elements of <email> apply to <htmlemail> as well. The following table specifies the additional or changed attributes.

Child Elements

<jabber>

<cruisecontrol>
  <project>
    <publishers>
      <jabber>

Sends an instant message with a link to the build results via a Jabber server using XMPP.

Attributes

<onfailure>

<cruisecontrol>
  <project>
    <publishers>
      <onfailure>

Provides the means to execute another publisher (or set of publishers) if and only if the current build has failed. 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 failed build, use the x10 publisher to light up a lamp, and call an Ant script to do some cleanup.

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

<onsuccess>

<cruisecontrol>
  <project>
    <publishers>
      <onsuccess>

Provides the means to execute another publisher (or set of publishers) if and only if the current build was successful. 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 successful build, use the x10 publisher to light up a lamp, and run the artifacts publisher to save the build artifacts.

   <onsuccess>
       <x10 houseCode="A" deviceCode="7"/>
       <artifactspublisher dir="checkout/project1/dist"
                           dest="artifacts/project1">
       </artifactspublisher>
   </onsuccess>
               

<rss>

<cruisecontrol>
  <project>
    <publishers>
      <rss>

Publishes an Really Simple Syndication (RSS) feed of build results. Multiple CruiseControl projects can publish into the same RSS feed provided that the "file" attribute point to the same location.

Attributes

<sametimeannouncement>

<cruisecontrol>
  <project>
    <publishers>
      <sametimeannouncement>

A publisher that sends Sametime announcements (optionally with a URL to the build results JSP) with the overall result of the build. Almost all of the attributes of <email> apply to <sametimeannouncement> as well.

Attributes

<socket>

<cruisecontrol>
  <project>
    <publishers>
      <socket>

Simply writes "Success" or "Failure", followed by the project name, to a socket. Note that you will need to write a socket listener that does something.

Attributes

<weblog>

<cruisecontrol>
  <project>
    <publishers>
      <weblog>

Posts the build results to a weblog using the Blogger API, the MetaWeblog API or the LiveJournal API.

Examples

<!-- Post the build results to your project blog
     under the category 'cruisecontrol' using the Blogger API.
  -->
<weblog api="blogger"
        blogurl="http://blogserver/blog/xmlrpc"
        blogid="blog"
        username="lasse"
        password="secret"
        category="cruisecontrol"
        reportsuccess="fixes"
        subjectprefix="[CC]"
        buildresultsurl="http://buildserver/cruisecontrol/myproject"
        logdir="/var/cruisecontrol/logs/myproject"
        xsldir="/opt/cruisecontrol/reporting/jsp/xsl"
        css="/opt/cruisecontrol/reporting/css/cruisecontrol.css"/>

<!-- Post the build results to your project blog
     under the category 'cruisecontrol' using the MetaWeblog API.
  -->
<weblog api="metaweblog"
        blogurl="http://blogserver/blog/xmlrpc"
        blogid="blog"
        username="lasse"
        password="secret"
        category="cruisecontrol,java"
        reportsuccess="fixes"
        subjectprefix="[CC]"
        buildresultsurl="http://buildserver/cruisecontrol/myproject"
        logdir="/var/cruisecontrol/logs/myproject"
        xsldir="/opt/cruisecontrol/reporting/jsp/xsl"
        css="/opt/cruisecontrol/reporting/css/cruisecontrol.css"/>

<!-- Post the build results to your project blog
     under the category 'cruisecontrol' using the LiveJournal API.
  -->
<weblog api="metaweblog"
        blogurl="http://www.livejournal.com/interface/xmlrpc"
        blogid="blog"
        username="lasse"
        password="secret"
        category="cruisecontrol"
        reportsuccess="fixes"
        subjectprefix="[CC]"
        buildresultsurl="http://buildserver/cruisecontrol/myproject"
        logdir="/var/cruisecontrol/logs/myproject"
        xsldir="/opt/cruisecontrol/reporting/jsp/xsl"
        css="/opt/cruisecontrol/reporting/css/cruisecontrol.css"/>

Attributes

<x10>

<cruisecontrol>
  <project>
    <publishers>
      <x10>

This Publisher implementation sends a on/off signal to a X10 capable device via an X10 computer interface, model CM11A or CM17A. This allows you to control an electronic device when the build breaks. For example, use a flashing red light to indicate a broken build.

Quick Start

1. Buy the home automation kit found at http://www.x10.com/automation/x10_ck11a_1.htm.
2. Plug the computer interface to your serial port (for example, COM1 or /dev/ttyS0), and your powerline
3. Set the lamp module's house and device code such as A3 and plug it into your powerline.
4. Plug in an electronic device to the lamp module like a lava lamp or flashing red light found at http://www.bwild.com/redsiren.html.
5. Install the Java Communications API on your CruiseControl machine. On Windows, copy win32com.dll from the CruiseControl lib directory to your JAVA_HOME/bin directory. On Linux, first obtain the Linux zip file from http://www.sun.com/download/products.xml?id=43208d3d. At the time of this writing, the name of the file was comm3.0_u1_linux.zip. Extract commapi/jar/comm.jar and commapi/docs/javax.comm.properties into the CruiseControl lib directory, overwriting the existing comm.jar file.
6. Add the x10 publisher to CruiseControl's config.xml. For example, on Windows:

   <x10 houseCode="A" deviceCode="3" port="COM1" />

   On Linux:

   <x10 houseCode="A" deviceCode="1" interfaceModel="cm17a" port="/dev/ttyS0" />

For more information about the CM11A controller, see http://www.smarthome.com/1140.html or http://www.x10.com/automation/x10_ck11a_1.htm. The controller connects to the computer via a serial port, e.g. COM1, and allows the computer to send (and receive) X10 signals on the power line. For more information on X10 in general, see http://www.x10.com/support/basicx10.htm.

This module uses a pure Java implementation of the CM11A and CM17A communication protocol as implemented by Jesse Peterson, http://www.jpeterson.com/. To read more about his library, see http://www.jpeterson.com/rnd/x101.0.1/Readme.html.

The jpeterson library requires that the Java Communications API be installed. For more information on the COMM API, see http://java.sun.com/products/javacomm/index.jsp. For convenience, the Java COMM API is included with the CruiseControl distribution. On windows, copy the win32com.dll from CruiseControl's lib directory to your JAVA_HOME/bin directory.

NOTE: If you receive the following error:

Error loading win32com: java.lang.UnsatisfiedLinkError: no win32com in java.library.path

it probably means that the Windows DLL named win32com.dll needs to be copied from CruiseControl's lib directory into your JDK (or JRE) bin directory (that is, the same directory that java.exe is found).

If you don't know what interface your device uses, try the default. If the publisher hangs, try a different value for the interfaceModel parameter.

The standard behavior for this publisher is to send the device the "on" signal when the build breaks and then the "off" signal when the build is successful. If you want the opposite, i.e. on when successful and off when broken, set the onWhenBroken attribute to false.

Attributes

Examples

<!--Turn on X10 device(s) A3 using a CM11A computer interface on COM2
    whenever the build breaks.-->
<x10 houseCode="A" deviceCode="3"/>

<!--Turn on X10 device(s) P12 using a CM11A computer interface on COM2
    whenever the build breaks.-->
<x10 houseCode="P" deviceCode="12"/>

<!--Turn on X10 device(s) A3 using a CM11A computer interface on COM1
    whenever the build breaks.-->
<x10 houseCode="A" deviceCode="3" port="COM1"/>

<!--Turn on X10 device(s) A3 using a CM11A computer interface on COM1
    whenever the build is successful.-->
<x10 houseCode="A" deviceCode="3" port="COM1" onWhenBroken="false"/>

<!--Same as the previous, only explicitly indicating which X10 computer
    interface is being used.-->
<x10 houseCode="A" deviceCode="3" port="COM1"
    onWhenBroken="false" interfaceModel="CM11A"/>

<!--Turn on X10 device(s) A3 using a CM17A computer interface on COM1
    whenever the build is successful.-->
<x10 houseCode="A" deviceCode="3" port="COM1"
    onWhenBroken="false" interfaceModel="CM17A"/>

<xsltlogpublisher>

<cruisecontrol>
  <project>
    <publishers>
      <xsltlogpublisher>

Performs an transformation of the log file. The obvious use is to generate HTML files to a website, but could be used to generate other sorts of output files as well.

Attributes

<yahoopublisher>

<cruisecontrol>
  <project>
    <publishers>
      <yahoopublisher>

Sends an instant message with a link to the build results via a Yahoo IM message. You need to put the files ymsg_network_v0_6.jar and ymsg_support_v0_6.jar into the library path of CC. These can be downloaded at http://jymsg9.sourceforge.net/.

Attributes

<dateformat>

<cruisecontrol>
  <project>
    <dateformat>

The optional <dateformat> element overrides the default date format for presentation. If this element is not specified, the default date format is "MM/dd/yyyy HH:mm:ss".

Attributes

<plugin>

<cruisecontrol>
  <plugin>
  <project>
    <plugin>

A <plugin> element registers a classname with an alias for use within the configuration file.

Plugins can also be pre-configured at registration time. This can greatly reduce the configuration file size.

The plugins page contains a discussion of the plugin architecture used with CruiseControl.

Attributes

<labelincrementer>

<cruisecontrol>
  <project>
    <labelincrementer>

Handle incrementing the label used to tag each build.

Attributes

The following attributes are valid for the default label incrementer. If the label incrementer plugin is overridden, other attributes may be applicable.

Overriding the Default Label Incrementer

If this element is not specified, the default label incrementer will use the format string.number, providing the default label of build.1.

To override the label incrementer used in a given project all you need to do is register a different class as a plugin with the name labelincrementer. Alternate label incrementer plugins distributed with CruiseControl include:

CVSLabelIncrementer

An extension of the default label incrementer but with the separator set to "-" by default. Provides default label of "build-1".

<plugin name="labelincrementer"
        classname="net.sourceforge.cruisecontrol.labelincrementers.CVSLabelIncrementer"/>

EmptyLabelIncrementer

Always returns a label of "" (empty string).

<plugin name="labelincrementer"
        classname="net.sourceforge.cruisecontrol.labelincrementers.EmptyLabelIncrementer"/>

FormattedLabelIncrementer

A label incrementer for creating consistent, formatted upper case labels. This plugin expects the label format to be either "x_y_z" or "y_z" where x is any String, y is an integer and z is one of REL, INT or BLD, i.e. MYPROJ_1_INT or 1_REL.

<plugin name="labelincrementer"
        classname="net.sourceforge.cruisecontrol.labelincrementers.FormattedLabelIncrementer"/>

P4ChangelistLabelIncrementer

Creates a label from either a given Perforce changelist number, or the most recently submitted changelist. A changelist number can be a good choice for labeling builds from Perforce, because a changelist indicates a particular state of the depot at a moment of time which will never change. This class also has features for cleaning up and synchronizing the local client. This incrementer will always run before the build executes.

Even though the Perforce Bootstrapper handles synchronizing, this will execute before the p4 modification check runs. Putting the synchronization after the modification check saves us a bit of time by only requesting the server's files when needed. This feature can be turned off by setting the attribute noSync to true.

By default, the class will use to the most currently submitted changelist as the label. If you wish to use a specific changelist number (say, for rerunning an old build), you can set the changelist attribute to the desired number. Whichever of these is chosen, the synchronize step (if enabled) will sync to this changelist number.

A good habit of build environments entails ensuring that the local environment comes only from the source control system, meaning that files haven't been modified without the source control system's knowledge, and that other files haven't been added. To support that, this class can delete the directories under Perforce view by setting the attribute delete to true. This will force the local clients to be removed first (ala sync view#0), and after deleting the files will perform the above synchronize.

Removing the local client files (sync #0) can be done without deleting the files by setting the clean attribute to true.

Attributes

<plugin name="labelincrementer"
        classname="net.sourceforge.cruisecontrol.labelincrementers.P4ChangelistLabelIncrementer"/>

PropertyFileLabelIncrementer

Returns a value for the label from a property file.

Attributes

<plugin name="labelincrementer"
        classname="net.sourceforge.cruisecontrol.labelincrementers.PropertyFileLabelIncrementer"/>

<currentbuildstatusftppublisher>

<cruisecontrol>
  <project>
    <publishers>
      <currentbuildstatusftppublisher>

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

This performs the same action as <currentbuildstatuspublisher>, 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.

<ftppublisher>

<cruisecontrol>
  <project>
    <publishers>
      <ftppublisher>

Copies the XML log file from the build, and all files published by <artifactspublisher>, onto the FTP server. To publish the artifacts, the <artifactspublisher> element must occur before this publisher in the configuration file.

Attributes

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

Common FTP Attributes

The following attributes are common to the <currentbuildstatusftpbootstrapper>, <currentbuildstatusftppublisher> and the <ftppublisher>.

XPath Aware Child Attributes

The following attributes are common to the xpath aware children found in <sfeetracker> and <sfeedocman>.

Named XPath Aware Child Attributes

The same attributes as found in the XPath Aware Child Attributes and one additional attribute to specify a name.