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.

If you are planning to run Cruisecontrol as a headless scheduled task, you may encounter an error stating "Cannot open logfile 'C:\\ccm_ui.log'" in the log file. This issue can be worked around by setting the following system environment variables:

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>

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

<darcsbootstrapper>

<cruisecontrol>
  <project>
    <bootstrappers>
      <darcsbootstrapper>

Handles updating from a darcs repository before the build begins.

Attributes

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

<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. If used to check for modifications to a System Testing or Insulated Development project, this will also check for any completed tasks included in the latest baseline for the projects release value 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

<darcs>

<cruisecontrol>
  <project>
    <modificationset>
      <darcs>

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

Attributes

<filesystem>

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

Returns all files beneath the specified path 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. If includedirectories is set it detects changes to directory timestamps, and will show modification if any files were deleted

Attributes

<forceonly>

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

Deprecated. Use forceonly attribute on <project> instead.

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

<git>

<cruisecontrol>
  <project>
    <modificationset>
      <git>

Checks for changes within a git repository.

Attributes

Properties Passed to the Builders

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

<harvest>

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

Triggers a build if there is a change within an AllFusion Harvest repository. Can be set to monitors for either new versions being checked in or for packages being promoted and demoted.

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

See the AllFusion Harvest product page for more information.

This implementation has only been tested against All Fusion Harvest version 7.0.131.

Attributes

<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

<mercurial>

<cruisecontrol>
  <project>
    <modificationset>
      <mercurial>

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

Attributes

Properties Passed to the Builders

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

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

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

<store>

<cruisecontrol>
  <project>
    <modificationset>
      <store>

Checks for changes within a Cincom Smalltalk VisualWorks Store repository.

In order to use this element, you must set up a script or batch file that will launch a VisualWorks Smalltalk image with the CruiseControl package loaded. The image must be configured so that the only output on standard output is that produced by the CruiseControl package itself.

The latest version of the CruiseControl package is available in the Cincom Public Store Repository.

Attributes

<surround>

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

Attributes

<svn>

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

Checks for changes within a Subversion repository.

Attributes

Properties Passed to the Builders

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

<tfs>

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

Triggers a build if there is a change within a Microsoft Visual Studio Team Foundation Server (TFS) repository.

Changes are detected 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.

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

tf history $/TeamProjectName/path
           -version:D2006-12-01T01:01:01Z~D2006-12-13T20:00:00Z
           -recursive -format:detailed -noprompt
           -server:http://tfsserver:8080
           -login:DOMAIN\name,password

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

It is worth noting that this implementation of integration with TFS works with both the Microsoft tf.exe and the Teamprise tf command line client using the same command strings.  There are some small differences in the output of the two commands, however this is taken into account in the parsing logic contained within this integration.

Attributes

Properties Passed to the Builders

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

<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 bar depends on project foo 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. Builds will only run if modifications are found, a build is forced from JMX interface, or the <project> has requireModifications set to false. 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 by the value of their multiple from high to low. If there are multiple Builders with the same multiple only one will build but which one is undefined.

Attributes

Child Elements

Common Builder Attributes

Properties Passed to Builders

When CruiseControl runs your build script (e.g. Ant, 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

See also the common attributes for builders.

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

See also the common attributes for builders.

<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 scm:update|deploy" will run 'clean' goal then 'scm:update' goal on the project, within the same Maven session run, then it will run Maven again with goal 'deploy'. 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

See also the common attributes for builders.

Child Elements

<composite>

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

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

Attributes

See also the common attributes for builders.

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

See also the common attributes for builders.

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

See also the common attributes for builders.

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>

<rake>

<cruisecontrol>
  <project>
    <schedule>
      <rake>

Specifies a Ruby Rake 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, Rake is invoked in a separate Java process.

Attributes

See also the common attributes for builders.

<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. Arguments will have any properties passed to builders substitued at runtime.

See below for examples of the <exec> element.

Attributes

See also the common attributes for builders.

Examples

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

   <schedule>
       <exec workingdir="/workspace/${projectname}"
            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>

3. Invoke execbuilder to call a function of the shell, in this case copy.

   <schedule>
       <exec command="cmd.exe"
            workingdir="D:\Workspace\MyProject"
            args="copy foo.txt bar.txt"
   </schedule>

<pipedexec>

<cruisecontrol>
  <project>
    <schedule>
      <pipedexec>

Piped exec builder executes a list of <exec> builders (commands or scripts), where the STDIN of any number of the builders may be fed by STDOUT of a builder running under the piped exec builder. All the child builders are started in parallel, and those requiring data on STDIN are blocked by the OS until their STDINs are filled by data. The PipedExecBuilder captures the STDOUTs of the running child builders, caches the data, and distributes them as soon as possible to the children waiting for them.

To prevent memory exhaustion when several large-memory-consuming builders are running at the same time, the builders may be set to wait for each other. Still, they may be piped from the same builder, even if the builder was already finished (because the data are cached).

The whole piped exec builder finishes when all its child builders are finished. When any of children fails, the piped exec builder terminates all the running commands or scripts, and the piped exec builder reports build failure. Let us note here the scripts used in this builder must be ready for piping - for example: they must use STDERR for state/error reporting.

The child <exec> builders have the same capabilities as the original <exec> builders.

See below for examples of the <pipedexec> element.

Attributes

See also the common attributes for builders.

Child Elements

Examples

1. Invoke piped exec builder, specifying the working directory as /workspace/myproject using property substitution and executing the sequence of Perl scripts first.pl -i data.txt | second.pl -o result.txt.

   <schedule>
       <pipedexec workingdir="/workspace/${projectname}">
           <exec id="1"
                command="/usr/local/bin/Perl"
                args="first.pl -i data.txt" />
           <exec id="2"
                pipefrom="1"
                command="/usr/local/bin/Perl"
                args="second.pl -o result.txt" />
       </pipedexec>
   </schedule>

2. Invoke piped exec builder, specifying another working directory for the last script, and an independent timeout for the first script. An error in the first script is signalled by an error occurred message instead of the script's return error code. The sequence is now first.pl -i data.txt | tee >(second.pl -o result.txt) | third.pl -o result.txt.

   <schedule>
       <pipedexec workingdir="/workspace/${projectname}">
           timeout="60"
           <exec id="1"
                command="/usr/local/bin/Perl"
                args="first.pl -i data.txt" />
                timeout="10" />
                errorstr="error occurred" />
           <exec id="2"
                pipefrom="1"
                command="/usr/local/bin/Perl"
                args="second.pl -o results.txt" />
           <exec id="3"
                pipefrom="1"
                command="/usr/local/bin/Perl"
                args="third.pl -o result.txt"
                workingdir="/distribution/${projectname}" />
       </pipedexec>
   </schedule>

3. Invoke more complicated piped exec builder, where 5th script required data generated by 2nd and 4th scripts, and 6th script requires data generated by 2th and 5th script. Therefore, scripts must wait for each other.

   <schedule>
       <pipedexec workingdir="/workspace/${projectname}">
           <exec id="1"
                command="/usr/local/bin/Perl"
                args="first.pl -i data.txt" />
           <exec id="2"
                pipefrom="1"
                command="/usr/local/bin/Perl"
                args="second.pl" />
           <exec id="3"
                pipefrom="2"
                command="/usr/local/bin/Perl"
                args="third.pl" />
           <exec id="4"
                pipefrom="3"
                command="/usr/local/bin/Perl"
                args="fourth.pl -o 4out.txt" />
           <!-- must not start until 4out.txt is ready. Without 'waitfor' it would be started
                before 4 is finished! -->
           <exec id="5"
                pipefrom="2"
                waitfor="4"
                command="/usr/local/bin/Perl"
                args="fiveth.pl -e 4out.txt -o 5out.txt" />
           <!-- The same here -->
           <exec id="6"
                pipefrom="2"
                waitfor="5"
                command="/usr/local/bin/Perl"
                args="sixth.pl -e 5out.txt" />
           <exec id="7"
                pipefrom="6"
                command="/usr/local/bin/Perl"
                args="seventh.pl -o results.txt" />
       </pipedexec>
   </schedule>

<xcode>

<cruisecontrol>
  <project>
    <schedule>
      <xcode>

Builds projects for Apple's Xcode IDE using the xcodebuild command-line tool.

Attributes

See also the common attributes for builders.

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

<cruisecontrol>
  <project>
    <log>
      <deleteartifacts>

<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

The <antpublisher> passes all of the same properties that are passed by <ant> and the other builders. Those properties are augmented by <antpublisher> to include the following additional properties:

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. The build and state attributes are only used if Synergy 6.4+ is detected

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>
               

<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

<http>

<cruisecontrol>
  <project>
    <publishers>
      <http>

Connects to an HTTP URL and sends the build results as parameters

Build results can be sent to a URL using any of the HTTP methods

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>
               

<origo>

<cruisecontrol>
  <project>
    <publishers>
      <origo>

Creates a new issue in an Origo system if a build fails and closes the issue after the build has been fixed.

Attributes

Examples

1. Create/update an issue in the ethz Origo instance for the project Connectfour.

   <origo userkey="SOMEVERYSECRETKEY"
           projectname="connectfour"
           buildresultsurl="http://somehost.tld//buildresults/${project.name}"
           issuetag="cruisecontrol::${project.name}::failed"/>
               

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

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

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

<twitter>

<cruisecontrol>
  <project>
    <publishers>
      <twitter>

Will send a tweet with a message of the format "projectname buildmessage", where the build message is one of successful, failed or fixed.

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.Then extract commapi/lib/libLinuxSerialParallel.so and point LD_LIBRARY_PATH to it, like so:

   export LD_LIBRARY_PATH=$HOME/commapi/lib${LD_LIBRARY_PATH+:$LD_LIBRARY_PATH}

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. To use this plugin you'll need to build the plugin.

You'll need files ymsg_network_v0_6.jar and ymsg_support_v0_6.jar which can be downloaded at http://jymsg9.sourceforge.net/. To build the plugin read the directions for Building Plugins That Need External Libraries

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>

LabelIncrementers handle incrementing the label used to tag each build. Only one LabelIncrementer can be used at a time per project.

The default label incrementer (<labelincrementer>) uses the format string.number, providing the initial default label of build.1.

Attributes

<cvslabelincrementer>

<cruisecontrol>
  <project>
    <cvslabelincrementer>

<cvslabelincrementer> is an extension of the default label incrementer but with the separator set to "-" by default. Provides default label of "build-1". Has all the same attributes as <labelincrementer>.

<emptylabelincrementer>

<cruisecontrol>
  <project>
    <emptylabelincrementer>

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

<formattedlabelincrementer>

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

Attributes

<p4changelistlabelincrementer>

<cruisecontrol>
  <project>
    <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

<propertyfilelabelincrementer>

<cruisecontrol>
  <project>
    <propertyfilelabelincrementer>

Returns a value for the label from a property file.

Note: If you use the Ant <buildnumber> task to increment your build number, and also use Cruisecontrol <propertyfilelabelincrementer>, you may find the build number reported by Ant and the label seen in Cruisecontrol are different after certain builds fail. This can happen if the Ant build fails after the <buildnumber> task has run. The build number is incremented in the property file by Ant, but Cruisecontrol retains the build number of the last failed build and re-uses it until the build succeeds. The label/buildnumber will be out-of-sync by 1 for every concurrent Ant build failure, i.e., after 3 concurrent failures Cruisecontrol will have label X, but the propertyfile will actually have the value X+3. The recommendation is therefore to force Cruisecontrol to re-read the property file for all builds by setting the value of the preBuildIncrementer attribute to true.

Attributes

<svnlabelincrementer>

<cruisecontrol>
  <project>
    <svnlabelincrementer>

Returns a value for the label based on the SVN revision number.

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, <ftppublisher> uses the following attributes.

Common FTP Attributes

The following attributes are common to 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.

Building Plugins That Need External Libraries

Several plugins require libraries to build that can't be distributed with CruiseControl. To use these plugins you'll need to acquire the required libraries and build them. The source for these plugins is available in the source distribution of in the repository at cruisecontrol/contrib/plugin/.

To build the plugin you'll need to put the required jars for the plugin into the [name]/lib directory then run the build file [name]/build.xml. After you've built the plugin you'll need to move all the files in [name]/target/dist into the library path of CruiseControl — which means just copying them to the cruisecontrol/lib — and restart the server.