<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
<head>
<title>CruiseControl Configuration Reference</title>
<style type="text/css" media="all">
@import "../cruisecontrol.css";
.index h2 {
margin-top: 1em;
}
#alphabetical {
float: right;
width: 43%;
}
#hierarchical {
float: left;
width: 55%;
}
a.toplink {
float: right;
font-size: smaller;
font-weight: bold;
}
@media print {
.elementdocumentation p,
.hierarchy {
page-break-inside: avoid;
}
#alphabetical,
#hierarchical,
a.toplink {
display: none;
}
}
</style>
<link href="../print.css" type="text/css" rel="stylesheet" media="print"/>
<script type="text/javascript" src="../tables.js"></script>
</head>
<body>
<div class="header">
<a name="top"/>
<div class="hostedby">
Hosted By:<br/>
<a href="http://sourceforge.net"><img src="http://sourceforge.net/sflogo.php?group_id=23523&type=1" width="88" height="31" alt="SourceForge"/></a>
</div>
<div class="logo"><img alt="CruiseControl" src="../banner.png"/></div>
</div>
<div class="container">
<div id="menu">
<ul id="menulist">
<li class="top"><a href="../index.html">home</a></li>
<li><a href="../download.html">download</a></li>
<li><a href="../license.html">license</a></li>
<li><h2>documentation</h2></li>
<li><a href="../overview.html">overview</a></li>
<li><a class="expandmenu" href="index.html">build loop</a></li>
<li><a class="expandmenu" href="../reporting/jsp/index.html">results jsp</a></li>
<li><a class="expandmenu" href="../dashboard.html">dashboard</a></li>
<li><a class="expandmenu" href="../gettingstarted.html">getting started</a></li>
<li><p id="menuselected">config ref</p></li>
<li><a href="../faq.html">faq</a></li>
<li><a class="external" href="http://confluence.public.thoughtworks.org/display/CC/Home">wiki</a></li>
<li><h2>contributing</h2></li>
<li><a class="expandmenu" href="../developers.html">developers</a></li>
<li><a href="../contact.html">mailing lists</a></li>
<li><a href="../svn.html">source repository</a></li>
<li><p id="menubottom">Release: 2.7.3</p></li>
</ul>
</div>
<div class="content">
<h1><span class="printonly">CruiseControl</span> Configuration Reference</h1>
<p>CruiseControl configuration files are written in XML. This document
describes the XML elements and attributes for a valid configuration
file.</p>
<p>The use of <a href="plugins.html">plugins</a> means that other
elements not documented here can also be used in the configuration.
At a minimum, though, the config file contains a single top level
<code><cruisecontrol></code> element, with one or more child
<code><project></code> elements.</p>
<div>
<div id="alphabetical" class="index">
<h2>Alphabetical Index</h2>
<pre style="font-size: smaller;">
<a href="#accurev"><accurev></a>
<a href="#accurevbootstrapper"><accurevbootstrapper></a>
<a href="#alienbrain"><alienbrain></a>
<a href="#alienbrainbootstrapper"><alienbrainbootstrapper></a>
<a href="#alwaysbuild"><alwaysbuild></a>
<a href="#ant"><ant></a>
<a href="#antbootstrapper"><antbootstrapper></a>
<a href="#antpublisher"><antpublisher></a>
<a href="#artifactspublisher"><artifactspublisher></a>
<a href="#bootstrappers"><bootstrappers></a>
<a href="#composite"><composite></a>
<a href="#buildstatus"><buildstatus></a>
<a href="#clearcase"><clearcase></a>
<a href="#clearcasebaselinepublisher"><clearcasebaselinepublisher></a>
<a href="#clearcasebootstrapper"><clearcasebootstrapper></a>
<a href="#clearcaseviewstrapper"><clearcaseviewstrapper></a>
<a href="#cmsynergy"><cmsynergy></a>
<a href="#cmsynergybaselinepublisher"><cmsynergybaselinepublisher></a>
<a href="#cmsynergybootstrapper"><cmsynergybootstrapper></a>
<a href="#cmsynergysessionmonitor"><cmsynergysessionmonitor></a>
<a href="#cmsynergytaskpublisher"><cmsynergytaskpublisher></a>
<a href="#compound"><compound></a>
<a href="#compoundpublisher"><compoundpublisher></a>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#currentbuildstatusbootstrapper"><currentbuildstatusbootstrapper></a>
<a href="#currentbuildstatusftpbootstrapper"><currentbuildstatusftpbootstrapper></a>
<a href="#currentbuildstatusftplistener"><currentbuildstatusftplistener></a>
<a href="#currentbuildstatusftppublisher"><currentbuildstatusftppublisher></a>
<a href="#currentbuildstatuslistener"><currentbuildstatuslistener></a>
<a href="#currentbuildstatuspagelistener"><currentbuildstatuspagelistener></a>
<a href="#currentbuildstatuspublisher"><currentbuildstatuspublisher></a>
<a href="#cvs"><cvs></a>
<a href="#cvsbootstrapper"><cvsbootstrapper></a>
<a href="#darcs"><darcs></a>
<a href="#dashboard"><dashboard></a>
<a href="#dateformat"><dateformat></a>
<a href="#delete"><delete></a>
<a href="#deleteartifacts"><deleteartifacts></a>
<a href="#email"><email></a>
<a href="#exec"><exec></a>
<a href="#execbootstrapper"><execbootstrapper></a>
<a href="#execute"><execute></a>
<a href="#filesystem"><filesystem></a>
<a href="#forceonly"><forceonly></a>
<a href="#ftppublisher"><ftppublisher></a>
<a href="#git"><git></a>
<a href="#gitbootstrapper"><gitbootstrapper></a>
<a href="#gzip"><gzip></a>
<a href="#harvest"><harvest></a>
<a href="#harvestbootstrapper"><harvestbootstrapper></a>
<a href="#htmlemail"><htmlemail></a>
<a href="#http"><http></a>
<a href="#httpfile"><httpfile></a>
<a href="#include.projects"><include.projects></a>
<a href="#jabber"><jabber></a>
<a href="#labelincrementer"><labelincrementer></a>
<a href="#listeners"><listeners></a>
<a href="#lockfilebootstrapper"><lockfilebootstrapper></a>
<a href="#lockfilelistener"><lockfilelistener></a>
<a href="#log"><log></a>
<a href="#maven"><maven></a>
<a href="#maven2"><maven2></a>
<a href="#mavensnapshotdependency"><mavensnapshotdependency></a>
<a href="#maven2snapshotdependency"><maven2snapshotdependency></a>
<a href="#mercurial"><mercurial></a>
<a href="#mercurialbootstrapper"><mercurialbootstrapper/></a>
<a href="#merge"><merge></a>
<a href="#mks"><mks></a>
<a href="#modificationset"><modificationset></a>
<a href="#nant"><nant></a>
<a href="#phing"><phing></a>
<a href="#onfailure"><onfailure></a>
<a href="#onsuccess"><onsuccess></a>
<a href="#origo"><origo></a>
<a href="#p4"><p4></a>
<a href="#p4bootstrapper"><p4bootstrapper></a>
<a href="#pause"><pause></a>
<a href="#plasticscm"><plasticscm></a>
<a href="#plasticscmbootstrapper"><plasticscmbootstrapper></a>
<a href="#plugin"><plugin></a>
<a href="#plugin"><plugin></a>
<a href="#project"><project></a>
<a href="#property"><property></a>
<a href="#publishers"><publishers></a>
<a href="#pvcs"><pvcs></a>
<a href="#rake"><rake></a>
<a href="#rss"><rss></a>
<a href="#sametimeannouncement"><sametimeannouncement></a>
<a href="#schedule"><schedule></a>
<a href="#scp"><scp></a>
<a href="#sfeedocman"><sfeedocman></a>
<a href="#sfeefrs"><sfeefrs></a>
<a href="#sfeetracker"><sfeetracker></a>
<a href="#snapshotcm"><snapshotcm></a>
<a href="#snapshotcmbootstrapper"><snapshotcmbootstrapper></a>
<a href="#socket"><socket></a>
<a href="#starteam"><starteam></a>
<a href="#starteambootstrapper"><starteambootstrapper></a>
<a href="#store"><store></a>
<a href="#surround"><surround></a>
<a href="#surroundbootstrapper"><surroundbootstrapper></a>
<a href="#svn"><svn></a>
<a href="#svnbootstrapper"><svnbootstrapper></a>
<a href="#compound"><targets></a>
<a href="#tfs"><tfs></a>
<a href="#tfsbootstrapper"><tfsbootstrapper></a>
<a href="#timebuild"><timebuild></a>
<a href="#threads"><threads></a>
<a href="#compound"><triggers></a>
<a href="#ucm"><ucm></a>
<a href="#veto"><veto></a>
<a href="#vss"><vss></a>
<a href="#vssbootstrapper"><vssbootstrapper></a>
<a href="#vssjournal"><vssjournal></a>
<a href="#weblogpublisher"><weblog></a>
<a href="#x10"><x10></a>
<a href="#xsltlogpublisher"><xsltlogpublisher></a>
<a href="#yahoopublisher"><yahoopublisher></a>
</pre>
</div>
<div id="hierarchical" class="index">
<h2>Hierarchical Index</h2>
<pre style="font-size: smaller;">
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#property"><property/></a>
<a href="#dashboard"><dashboard/></a>
<a href="#include.projects"><include.projects/></a>
<system>
<configuration>
<a href="#threads"><threads/></a>
</configuration>
</system>
<a href="#plugin"><plugin/></a>
<a href="#project"><project></a>
<a href="#property"><property/></a>
<a href="#plugin"><plugin/></a>
<a href="#dateformat"><dateformat/></a>
<a href="#labelincrementer"><labelincrementer/></a>
<a href="#listeners"><listeners></a>
<a href="#cmsynergysessionmonitor"><cmsynergysessionmonitor/></a>
<a href="#currentbuildstatusftplistener"><currentbuildstatusftplistener/></a>
<a href="#currentbuildstatuslistener"><currentbuildstatuslistener/></a>
<a href="#currentbuildstatuspagelistener"><currentbuildstatuspagelistener/></a>
<a href="#lockfilelistener"><lockfilelistener/></a>
</listeners>
<a href="#bootstrappers"><bootstrappers></a>
<a href="#accurevbootstrapper"><accurevbootstrapper/></a>
<a href="#alienbrainbootstrapper"><alienbrainbootstrapper/></a>
<a href="#antbootstrapper"><antbootstrapper/></a>
<a href="#clearcasebootstrapper"><clearcasebootstrapper/></a>
<a href="#clearcaseviewstrapper"><clearcaseviewstrapper/></a>
<a href="#cmsynergybootstrapper"><cmsynergybootstrapper/></a>
<a href="#currentbuildstatusbootstrapper"><currentbuildstatusbootstrapper/></a>
<a href="#currentbuildstatusftpbootstrapper"><currentbuildstatusftpbootstrapper/></a>
<a href="#cvsbootstrapper"><cvsbootstrapper/></a>
<a href="#execbootstrapper"><execbootstrapper/></a>
<a href="#gitbootstrapper"><gitbootstrapper/></a>
<a href="#harvestbootstrapper"><harvestbootstrapper/></a>
<a href="#lockfilebootstrapper"><lockfilebootstrapper/></a>
<a href="#mercurialbootstrapper"><mercurialbootstrapper/></a>
<a href="#p4bootstrapper"><p4bootstrapper/></a>
<a href="#plasticscmbootstrapper"><plasticscmbootstrapper/></a>
<a href="#snapshotcmbootstrapper"><snapshotcmbootstrapper/></a>
<a href="#starteambootstrapper"><starteambootstrapper/></a>
<a href="#surroundbootstrapper"><surroundbootstrapper/></a>
<a href="#svnbootstrapper"><svnbootstrapper/></a>
<a href="#tfsbootstrapper"><tfsbootstrapper/></a>
<a href="#vssbootstrapper"><vssbootstrapper/></a>
</bootstrappers>
<a href="#modificationset"><modificationset></a>
<a href="#accurev"><accurev></a>
<a href="#alienbrain"><alienbrain/></a>
<a href="#alwaysbuild"><alwaysbuild/></a>
<a href="#buildstatus"><buildstatus/></a>
<a href="#clearcase"><clearcase/></a>
<a href="#cmsynergy"><cmsynergy/></a>
<a href="#compound"><compound></a>
<a href="#compound"><targets/></a>
<a href="#compound"><triggers/></a>
</compound>
<a href="#cvs"><cvs/></a>
<a href="#darcs"><darcs/></a>
<a href="#filesystem"><filesystem/></a>
<a href="#forceonly"><forceonly/></a>
<a href="#git"><git/></a>
<a href="#harvest"><harvest/></a>
<a href="#httpfile"><httpfile/></a>
<a href="#mavensnapshotdependency"><mavensnapshotdependency/></a>
<a href="#maven2snapshotdependency"><maven2snapshotdependency/></a>
<a href="#mercurial"><mercurial/></a>
<a href="#mks"><mks/></a>
<a href="#p4"><p4/></a>
<a href="#plasticscm"><plasticscm/></a>
<a href="#pvcs"><pvcs/></a>
<a href="#snapshotcm"><snapshotcm/></a>
<a href="#starteam"><starteam/></a>
<a href="#store"><store/></a>
<a href="#surround"><surround/></a>
<a href="#svn"><svn/></a>
<a href="#tfs"><tfs/></a>
<a href="#timebuild"><timebuild></a>
<a href="#ucm"><ucm></a>
<a href="#veto"><veto/></a>
<a href="#vss"><vss/></a>
<a href="#vssjournal"><vssjournal/></a>
</modificationset>
<a href="#schedule"><schedule></a>
<a href="#ant"><ant/></a>
<a href="#maven"><maven/></a>
<a href="#maven2"><maven2/></a>
<a href="#pause"><pause/></a>
<a href="#nant"><nant/></a>
<a href="#phing"><phing/></a>
<a href="#rake"><rake/></a>
<a href="#exec"><exec/></a>
<a href="#composite"><composite/></a>
</schedule>
<a href="#log"><log></a>
<a href="#merge"><merge/></a>
<a href="#gzip"><gzip/></a>
<a href="#delete"><delete/></a>
<a href="#deleteartifacts"><deleteartifacts/></a>
</log>
<a href="#publishers"><publishers></a>
<a href="#antpublisher"><antpublisher/></a>
<a href="#artifactspublisher"><artifactspublisher/></a>
<a href="#clearcasebaselinepublisher"><clearcasebaselinepublisher/></a>
<a href="#cmsynergybaselinepublisher"><cmsynergybaselinepublisher/></a>
<a href="#cmsynergytaskpublisher"><cmsynergytaskpublisher/></a>
<a href="#compoundpublisher"><compoundpublisher/></a>
<a href="#currentbuildstatuspublisher"><currentbuildstatuspublisher/></a>
<a href="#currentbuildstatusftppublisher"><currentbuildstatusftppublisher/></a>
<a href="#email"><email/></a>
<a href="#execute"><execute/></a>
<a href="#ftppublisher"><ftppublisher/></a>
<a href="#htmlemail"><htmlemail/></a>
<a href="#http"><http></a>
<a href="#jabber"><jabber/></a>
<a href="#onfailure"><onfailure/></a>
<a href="#onsuccess"><onsuccess/></a>
<a href="#origo"><origo/></a>
<a href="#rss"><rss/></a>
<a href="#sametimeannouncement"><sametimeannouncement/></a>
<a href="#scp"><scp/></a>
<a href="#sfeedocman"><sfeedocman/></a>
<a href="#sfeefrs"><sfeefrs/></a>
<a href="#sfeetracker"><sfeetracker/></a>
<a href="#socket"><socket/></a>
<a href="#weblogpublisher"><weblog></a>
<a href="#x10"><x10/></a>
<a href="#xsltlogpublisher"><xsltlogpublisher/></a>
<a href="#yahoopublisher"><yahoopublisher/></a>
</publishers>
</project>
</cruisecontrol></pre>
</div>
</div>
<p style="clear: both"> </p>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="cruisecontrol"><cruisecontrol></a></h2>
<div class="hierarchy">
<pre>
<cruisecontrol></pre>
</div>
<p>The <code><cruisecontrol></code> element is the root element
of the configuration, and acts as a container to the rest of the
configuration elements.</p>
<h3>Child Elements</h3>
<table class="documentation">
<thead>
<tr>
<th>Element</th>
<th>Cardinality</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><system></td>
<td>0 .. 1</td>
<td>Currently just a placeholder for the <configuration> element,
which in its turn is just a placeholder for the <a href="#threads"><threads></a> element.<br />
We expect that in the future, more system-level features can be configured under this element.
</td>
</tr>
<tr>
<td><a href="#project"><project></a></td>
<td>1 .. *</td>
<td>Defines a basic unit of work.</td>
</tr>
<tr>
<td><a href="#plugin"><plugin></a></td>
<td>0 .. *</td>
<td>Registers a classname with an alias.</td>
</tr>
<tr>
<td><a href="#property"><property></a></td>
<td>0 .. *</td>
<td>Defines a name/value pair used in configuration.</td>
</tr>
<tr>
<td><a href="#include.projects"><include.projects></a></td>
<td>0 .. *</td>
<td>Add projects defined in other configuration files.</td>
</tr>
<tr>
<td><a href="#dashboard"><dashboard></a></td>
<td>0 .. 1</td>
<td>Configure dashboard related settings.</td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="threads"><threads></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<system>
<configuration>
<threads></pre>
</div>
<p>The <code><threads></code> element can be used to configure the number of threads that CruiseControl can use
simultaneously to build projects. This is done through the <code>count</code> 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.</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>count</td>
<td>Yes</td>
<td>Maximum number of threads to be in use simultaneously to build projects</td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="property"><property></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<property></pre>
</div>
<p>The <code><property></code> 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:</p>
<ol>
<li>By supplying both the name and value attributes.</li>
<li>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.</li>
<li>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.</li>
</ol>
<p>Properties in CruiseControl are <i>not entirely</i> immutable: whoever sets a property <i>last</i>
will freeze it's value <i>within the scope in which the property was set</i>. 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.</p>
<p>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.</p>
<p>Also note that the property <code>${project.name}</code> 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.</p>
<p>Finally, note that properties bring their best when combined with
<a href="plugins.html#preconfiguration">plugin preconfigurations</a>.
</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>name</td>
<td rowspan="3">Exactly one of name, environment, or file.</td>
<td>The name of the property to set.</td>
</tr>
<tr>
<td>environment</td>
<td>The prefix to use when retrieving environment variables.
Thus if you specify environment="myenv" you will be able
to access OS-specific environment variables via property
names such as "myenv.PATH" or "myenv.MAVEN_HOME".</td>
</tr>
<tr>
<td>file</td>
<td>The filename of the property file to load.</td>
</tr>
<tr>
<td>value</td>
<td>Yes, if name was set.</td>
<td>The value of the property. This may contain any previously
defined properties.</td>
</tr>
<tr>
<td>toupper</td>
<td>No</td>
<td>Used in conjunction with environment. If set to true, all
environment variable names will be converted to upper case.</td>
</tr>
</tbody>
</table>
<h3>Examples</h3>
<ol>
<li>Set a couple of global properties using name/value pairs:
<pre>
<cruisecontrol>
<property name="cruisedir" value="/home/cruise"/>
<property name="logdir" value="${cruisedir}/logs"/>
...
<cruisecontrol>
</pre>
</li>
<li>Set a collection of global properties from the properties file "config.properties":
<pre>
<cruisecontrol>
<property file="config.properties"/>
...
<cruisecontrol>
</pre>
</li>
<li>Load the system's environment into a collection of global properties.
Uppercase all environment variable names:
<pre>
<cruisecontrol>
<property environment="env" toupper="true"/>
<property name="logdir" value="${env.CCDIR}/logs"/>
...
<cruisecontrol>
</pre>
</li>
<li>Define a global property called "buildmanager". Override it's value
only within the scope of the project called "project2".
<pre>
<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>
</pre>
</li>
<li>As demonstrated here, properties and
<a href="plugins.html#preconfiguration">plugin pre-configuration</a>
can be an extremely powerful combination.
<pre>
<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>
</pre>
</li>
</ol>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="include.projects"><include.projects></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<include.projects></pre>
</div>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>file</td>
<td>Yes</td>
<td>Relative path from current configuration file to the configuration file to process.</td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="dashboard"><dashboard></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<dashboard></pre>
</div>
<p>The <dashboard> tag is used to set the configuration for build loop posting builds information to the dashboard.</p>
<p>If this element is not specified in config.xml, CruiseControl will first check <a href="install.html#startupcruisecontrol">command-line</a>. If neither of this set, then CruiseControl will use default.</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>url</td>
<td>No</td>
<td>Home page address of your dashboard. The default value is http://localhost:8080/dashboard.</td>
</tr>
<tr>
<td>postinterval</td>
<td>No</td>
<td>The interval [in seconds] that build loop post builds information to the dashboard. The default value is 5 seconds.</td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="project"><project></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<project></pre>
</div>
<p>A <code><project></code> is the basic unit of work — it
will handle checking for modifications, building, and publishing the
results of your project.</p>
<p><i>Note</i>: one config.xml file can contain several
<code><project></code> elements; these projects will all run in
a shared build queue (see the <a href="#threads"><threads></a> element
if you want to build multiple projects at the same time).</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>name</td>
<td>Yes</td>
<td>Unique identifier for this project</td>
</tr>
<tr>
<td>buildafterfailed</td>
<td>No (defaults to true)</td>
<td>Should CruiseControl keep on building even though it has
failed and no new modifications are detected? This feature is
useful if you want CruiseControl to detect situations where a
build fails because of outside dependencies (like temporary
failing database connection).</td>
</tr>
<tr>
<td>forceBuildNewProject</td>
<td>No (defaults to true)</td>
<td>Should CruiseControl force a project to build if the serial
file (project.SER) is not found, typically this is when the
project is first added. This feature is useful for
projects that have or use dependencies.
</td>
</tr>
<tr>
<td>requireModification</td>
<td>No (defaults to true)</td>
<td>Is a modification required for the build to continue?
Default value is true. Useful to set to false when the schedule
has only time based builds or if you want to run tests to verify
an external resource (such as a database).<br /></td>
</tr>
<tr>
<td>forceOnly</td>
<td>No (defaults to false)</td>
<td>Indicate that the build for the project only occurs when forced. Note that if the buildAfterFailed attribute is true, then
builds will continue to occur based upon the the rules on <a href="#schedule"><schedule></a> until the build is successful.</td>
</tr>
</tbody>
</table>
<h3>Child Elements</h3>
<table class="documentation">
<thead>
<tr>
<th>Element</th>
<th>Cardinality</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><a href="#listeners"><listeners></a></td>
<td>0 .. 1</td>
<td>Container element for Listener plugin instances.</td>
</tr>
<tr>
<td><a href="#bootstrappers"><bootstrappers></a></td>
<td>0 .. 1</td>
<td>Container element for Bootstrapper plugin instances.</td>
</tr>
<tr>
<td><a href="#modificationset"><modificationset></a></td>
<td>1</td>
<td>Container element for SourceControl plugin instances.</td>
</tr>
<tr>
<td><a href="#schedule"><schedule></a></td>
<td>1</td>
<td>Specifies the SourceControl poll interval, and is a parent
element for Builder plugin instances.</td>
</tr>
<tr>
<td><a href="#log"><log></a></td>
<td>0 .. 1</td>
<td>Specifies where project log files are stored.</td>
</tr>
<tr>
<td><a href="#publishers"><publishers></a></td>
<td>0 .. 1</td>
<td>Container element for Publisher plugin instances.</td>
</tr>
<tr>
<td><a href="#dateformat"><dateformat></a></td>
<td>0 .. 1</td>
<td>Overrides the default date format for presentation.</td>
</tr>
<tr>
<td><a href="#plugin"><plugin></a></td>
<td>0 .. *</td>
<td>Registers a classname with an alias.</td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="listeners"><listeners></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<listeners></pre>
</div>
<p>The <code><listeners></code> element is a container element
for Listener plugin instances.</p>
<p>Listeners are notified with every ProjectEvent but most Listeners
are designed to handle a specific subclass of ProjectEvent.</p>
<h3>Child Elements</h3>
<table class="documentation">
<thead>
<tr>
<th>Element</th>
<th>Cardinality</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><a href="#currentbuildstatusftplistener"><currentbuildstatusftplistener></a></td>
<td>0 .. *</td>
<td>Writes a build status snippet to the filesystem and to an FTP server</td>
</tr>
<tr>
<td><a href="#currentbuildstatuslistener"><currentbuildstatuslistener></a></td>
<td>0 .. *</td>
<td>Writes a build status snippet to the filesystem</td>
</tr>
<tr>
<td><a href="#currentbuildstatuspagelistener"><currentbuildstatuspagelistener></a></td>
<td>0 .. *</td>
<td>Writes build status to the filesystem using by replacing values in a template</td>
</tr>
<tr>
<td><a href="#cmsynergysessionmonitor"><cmsynergysessionmonitor></a></td>
<td>0 .. *</td>
<td>Monitors and starts CM Synergy sessions as needed</td>
</tr>
<tr>
<td><a href="#lockfilelistener"><lockfilelistener></a></td>
<td>0 .. *</td>
<td>Responsible for deleting the lock file when a project goes IDLE</td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="cmsynergysessionmonitor"><cmsynergysessionmonitor></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#listeners"><listeners></a>
<cmsynergysessionmonitor></pre>
</div>
<p>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").</p>
<p>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:</p>
<ol>
<li>If the session file does not exist, it will be created.</li>
<li>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.</li>
<li>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.</li>
</ol>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>ccmexe</td>
<td>No</td>
<td>The name of the CM Synergy command line client. If not provided, the
plugin will search the system path for an executable called "ccm"
(or "ccm.exe" for Windows).</td>
</tr>
<tr>
<td>sessionfile</td>
<td>No</td>
<td>The session file used to persist the CM Synergy session information.
If not provided, it defaults to a file called ".ccmsessionmap" located
in your home directory.</td>
</tr>
</tbody>
</table>
<h3>Child Elements</h3>
<table class="documentation">
<thead>
<tr>
<th>Element</th>
<th>Cardinality</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><session></td>
<td>1 .. *</td>
<td><p>Defines a CM Synergy session you wish to monitor. The session
information may be provided in one of two ways.</p>
<ol>
<li>You may provide each individual attribute directly in the config file.</li>
<li>You may specify the name attribute as well as an "attributefile"
which contains the remainder of the required attributes. This allows
you to place sensitive information - such as the password - into an
external file with the appropriate permissions. The file referenced here
should use the standard properties file format of "attribute=value" pairs.</li>
</ol>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>name</td>
<td>Yes</td>
<td>The name of the CM Synergy session. This value will be used in the
"sessionname" attributes of the other CM Synergy plugins.</td>
</tr>
<tr>
<td>attributefile</td>
<td>No</td>
<td>The properties file which will be read to set the remainder of the
session's attributes.</td>
</tr>
<tr>
<td>database</td>
<td>Yes</td>
<td>The CM Synergy database with which this session will communicate
(e.g. /ccmdb/mydb).</td>
</tr>
<tr>
<td>user</td>
<td>Yes</td>
<td>The CM Synergy user account under which the session will run.</td>
</tr>
<tr>
<td>password</td>
<td>Yes</td>
<td>The password for the specified user.</td>
</tr>
<tr>
<td>role</td>
<td>Yes</td>
<td>The role under which the CM Synergy session will run
(e.g. build_mgr).</td>
</tr>
<tr>
<td>host</td>
<td>No</td>
<td>If you wish the CM Synergy session to run on a host other than the
current machine, you may set the host name here.</td>
</tr>
</tbody>
</table>
</td>
</tr>
</tbody>
</table>
<h3>Examples</h3>
<ol>
<li>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.
<pre>
<listeners>
<cmsynergysessionmonitor>
<session name="session1"
database="/ccmdb/product1"
user="buildmgr"
role="build_mgr"
password="P@ssW0rd!"/>
<session name="session2"
attributefile="session2.properties"/>
<cmsynergysessionmonitor/>
<listeners/>
</pre>
Session 2 would then use a properties file as follows:
<pre>
#CM Synergy session properties for "session2"
database=/ccmdb/product2
user=buildmgr
role=build_mgr
password=P@ssW0rd!
</pre>
</li>
</ol>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="compoundpublisher"><compoundpublisher></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#publishers"><publishers></a>
<compoundpublisher></pre>
</div>
<p>Provides the means to execute another publisher (or set of publishers).
This is accomplished by simply adding any desired publishers as child
elements.</p>
<p>All child elements must meet the following criteria:</p>
<ol>
<li>
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
<a href="#plugin"><plugin></a> element within your config file.
</li>
<li>
They must validate successfully regardless of whether or not
the build was successful.
</li>
</ol>
<h3>Child Elements</h3>
<table class="documentation">
<thead>
<tr>
<th>Element</th>
<th>Cardinality</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>Any defined publisher</td>
<td>1 .. *</td>
<td>You may use any defined publisher as a child element.</td>
</tr>
</tbody>
</table>
<h3>Examples</h3>
<ol>
<li>After a build, use the x10 publisher to light up a lamp,
and call an Ant script to do some cleanup.
<pre>
<compoundpublisher>
<x10 houseCode="A" deviceCode="3"/>
<antpublisher antscript="/opt/apache-ant-1.6.1/bin/ant"
target="cleanupafterfailure">
</antpublisher>
</compoundpublisher>
</pre>
</li>
</ol>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="currentbuildstatuslistener"><currentbuildstatuslistener></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#listeners"><listeners></a>
<currentbuildstatuslistener></pre>
</div>
<p>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
<code><currentbuildstatuslistener></code> 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
<a href="#dateformat">dateformat</a> element.</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>file</td>
<td>Yes</td>
<td>The filename to write, including path</td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="currentbuildstatuspagelistener"><currentbuildstatuspagelistener></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#listeners"><listeners></a>
<currentbuildstatuspagelistener></pre>
</div>
<p>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:</p>
<ul>
<li>{Project} - Project Name.</li>
<li>{State.Name} - Name of current project state.</li>
<li>{State.Description} - Description of current project state.</li>
<li>{State.Date} - Date/time the current state happened</li>
<li>{State.Duration} - How long since this state was in effect. (Only useful in {History} line.)</li>
<li>{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.</li>
</ul>
<p>A default template is provided of the form "{Project}: {State.Date} - {State.Name}: {State.Description}"</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>file</td>
<td>Yes</td>
<td>The filename to write, including path</td>
</tr>
<tr>
<td>sourceFile</td>
<td>No</td>
<td>The file with the template to use for subtitution</td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="currentbuildstatusftplistener"><currentbuildstatusftplistener></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#listeners"><listeners></a>
<currentbuildstatusftplistener></pre>
</div>
<p>This plugin is mostly identical to the <a href="#currentbuildstatuslistener">
<code><currentbuildstatuslistener></code></a>, to which it adds sending the HTML
snippet to a remote FTP server.</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>filename</td>
<td>Yes</td>
<td>The filename to write, including path</td>
</tr>
<tr>
<td>destdir</td>
<td>Yes</td>
<td>The remote directory in which the file will be sent to.</td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="lockfilelistener"><lockfilelistener></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#listeners"><listeners></a>
<lockfilelistener></pre>
</div>
<p>This plugin works in conjunction with a <a href="#lockfilebootstrapper"><code><lockfilebootstrapper></code></a> 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.</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>lockfile</td>
<td>Yes</td>
<td>The name (and path) of the file to serve as the lock between multiple projects.</td>
</tr>
<tr>
<td>projectname</td>
<td>Yes</td>
<td>Lockfile only deleted when contents match the value set for project name.</td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="bootstrappers"><bootstrappers></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<bootstrappers></pre>
</div>
<p>The <code><bootstrappers></code> element is a container element
for Bootstrapper plugin instances.</p>
<p>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.</p>
<h3>Child Elements</h3>
<table class="documentation">
<thead>
<tr>
<th>Element</th>
<th>Cardinality</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><a href="#accurevbootstrapper"><accurevbootstrapper></a></td>
<td>0 .. *</td>
<td>Updates the resources of an Accurev workspace</td>
</tr>
<tr>
<td><a href="#alienbrainbootstrapper"><alienbrainbootstrapper></a></td>
<td>0 .. *</td>
<td>Bootstraps resources from AlienBrain</td>
</tr>
<tr>
<td><a href="#antbootstrapper"><antbootstrapper></a></td>
<td>0 .. *</td>
<td>Executes an Ant script which implements a custom bootstrapper</td>
</tr>
<tr>
<td><a href="#clearcasebootstrapper"><clearcasebootstrapper></a></td>
<td>0 .. *</td>
<td>Bootstraps resources from ClearCase</td>
</tr>
<tr>
<td><a href="#clearcaseviewstrapper"><clearcaseviewstrapper></a></td>
<td>0 .. *</td>
<td>Bootstraps View and VOB resources from ClearCase</td>
</tr>
<tr>
<td><a href="#cmsynergybootstrapper"><cmsynergybootstrapper></a></td>
<td>0 .. *</td>
<td>Bootstraps resources from CM Synergy</td>
</tr>
<tr>
<td><a href="#currentbuildstatusbootstrapper"><currentbuildstatusbootstrapper></a></td>
<td>0 .. *</td>
<td>Writes a build status snippet to the filesystem</td>
</tr>
<tr>
<td><a href="#currentbuildstatusftpbootstrapper"><currentbuildstatusftpbootstrapper></a></td>
<td>0 .. *</td>
<td>Transfers a build status snippet via FTP</td>
</tr>
<tr>
<td><a href="#cvsbootstrapper"><cvsbootstrapper></a></td>
<td>0 .. *</td>
<td>Bootstraps resources from CVS</td>
</tr>
<tr>
<td><a href="#execbootstrapper"><execbootstrapper></a></td>
<td>0 .. *</td>
<td>Execute a command for bootstrapping</td>
</tr>
<tr>
<td><a href="#gitbootstrapper"><gitbootstrapper></a></td>
<td>0 .. *</td>
<td>Bootstraps resources from git</td>
</tr>
<tr>
<td><a href="#harvestbootstrapper"><harvestbootstrapper></a></td>
<td>0 .. *</td>
<td>Bootstraps resources from AllFusion Harvest</td>
</tr>
<tr>
<td><a href="#lockfilebootstrapper"><lockfilebootstrapper></a></td>
<td>0 .. *</td>
<td>Creates the lock file if it doesn't already exist</td>
</tr>
<tr>
<td><a href="#mercurialbootstrapper"><mercurialbootstrapper></a></td>
<td>0 .. *</td>
<td>Bootstraps resources from Mercurial</td>
</tr>
<tr>
<td><a href="#p4bootstrapper"><p4bootstrapper></a></td>
<td>0 .. *</td>
<td>Bootstraps resources from Perforce</td>
</tr>
<tr>
<td><a href="#plasticscmbootstrapper"><plasticscmbootstrapper></a></td>
<td>0 .. *</td>
<td>Bootstraps resources from Plastic SCM</td>
</tr>
<tr>
<td><a href="#snapshotcmbootstrapper"><snapshotcmbootstrapper></a></td>
<td>0 .. *</td>
<td>Bootstraps resources from SnapshotCM</td>
</tr>
<tr>
<td><a href="#starteambootstrapper"><starteambootstrapper></a></td>
<td>0 .. *</td>
<td>Bootstraps resources from Star Team</td>
</tr>
<tr>
<td><a href="#surroundbootstrapper"><surroundbootstrapper></a></td>
<td>0 .. *</td>
<td>Bootstraps resources from Surround SCM</td>
</tr>
<tr>
<td><a href="#svnbootstrapper"><svnbootstrapper></a></td>
<td>0 .. *</td>
<td>Bootstraps resources from Subversion</td>
</tr>
<tr>
<td><a href="#tfsbootstrapper"><tfsbootstrapper></a></td>
<td>0 .. *</td>
<td>Bootstraps resources from Microsoft Visual Studio Team Foundation Server</td>
</tr>
<tr>
<td><a href="#vssbootstrapper"><vssbootstrapper></a></td>
<td>0 .. *</td>
<td>Bootstraps resources from Visual Source Safe</td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="accurevbootstrapper"><accurevbootstrapper></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#bootstrappers"><bootstrappers></a>
<accurevbootstrapper></pre>
</div>
<p>Automatically updates an accurev workspace. The selected workspace must already exist on the local filesystem.</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>keep</td>
<td>No (defaults to "false")</td>
<td>If true, the plugin runs "accurev keep -m" before trying to update the workspace, to keep all modified elements.</td>
</tr>
<tr>
<td>synctime</td>
<td>No (defaults to "false")</td>
<td>If true, the plugin runs "accurev synctime" before trying to update the workspace, to synchronize the local clock with the Accurev server's.</td>
</tr>
<tr>
<td>verbose</td>
<td>No (defaults to "false")</td>
<td>Enables detailed logging.</td>
</tr>
<tr>
<td>workspace</td>
<td>No (defaults to the current dir)</td>
<td>The local path containing the working copy of the desired workspace.</td>
</tr>
</tbody>
</table>
<h3>Examples</h3>
<ol>
<li>Updates the workspace locally stored on <code>D:\accurev\workspace_user\MyProject</code>,
after synchronizing the local clock with the autokeeping all the modified files.
<pre>
<bootstrappers>
<accurevbootstrapper workspace="D:\accurev\workspace_user\MyProject"
synctime="true"
keep="true"
verbose="true"/>
<bootstrappers>
</pre>
</li>
</ol>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="alienbrainbootstrapper"><alienbrainbootstrapper></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#bootstrappers"><bootstrappers></a>
<alienbrainbootstrapper></pre>
</div>
<p>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.</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>server</td>
<td>No</td>
<td>The name of the machine hosting the AlienBrain repository. If specified, it will override the value in the NXN_AB_SERVER environment variable.</td>
</tr>
<tr>
<td>database</td>
<td>No</td>
<td>The name of the project in the AlienBrain repository. If specified, it will override the value in the NXN_AB_DATABASE environment variable.</td>
</tr>
<tr>
<td>user</td>
<td>No</td>
<td>The AlienBrain user account name to use when querying for modifications. If specified, it will override the value in the NXN_AB_USERNAME environment variable.</td>
</tr>
<tr>
<td>password</td>
<td>No</td>
<td>The password of the AlienBrain user account to use when querying for modifications. If specified, it will override the value in the NXN_AB_PASSWORD environment variable.</td>
</tr>
<tr>
<td>path</td>
<td>Yes</td>
<td>The path to the item that will be retrieved from AlienBrain. Typically a path like 'alienbrain://Project/SubProject/build.xml' If the path is a file, that file will be retrieved. If the path is a directory, the directory will be retrieved recursively.</td>
</tr>
<tr>
<td>branch</td>
<td>No</td>
<td>The branch of the project from which to retrieve the path.</td>
</tr>
<tr>
<td>forcefileupdate</td>
<td>No (defaults to false)</td>
<td>If set to true, the local file is always updated with the file on the server. This is not the same as overwritewritable="replace". It means that the file will be retrieved even if it has not been modified in the repository.</td>
</tr>
<tr>
<td>overwritewritable</td>
<td>No (defaults to 'skip')</td>
<td>Must be either 'skip' or 'replace'. 'ask' is not an option as no one is around to answer the question.
<dl>
<dt>skip:</dt>
<dd>do not touch the file</dd>
<dt>replace:</dt>
<dd>replace the file with the version on the server</dd>
</dl>
</td>
</tr>
<tr>
<td>localpath</td>
<td>No</td>
<td>If localpath is specified the item is copied to the specified local path.</td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="antbootstrapper"><antbootstrapper></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#bootstrappers"><bootstrappers></a>
<antbootstrapper></pre>
</div>
<p>Executes an Ant script which implements a custom bootstrapper.</p>
<h3>Attributes</h3>
The antbootstrapper uses the same <a href="#ant-attributes">attributes</a>
as the <a href="#ant"><ant></a> builder.
<h3>Child Elements</h3>
The antbootstrapper supports the same set of
<a href="#ant-elements">child elements</a> as the
<a href="#ant"><ant></a> builder.
<h3>Examples</h3>
<ol>
<li>Invoke the ant.bat script distributed with ant, specifying the
working directory as <code>D:\workspace\MyProject</code> and the
ant build file as <code>MyProject-nightlybuild.xml</code> and the
ant target as <code>bootstrap</code>.
<pre><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></pre>
</li>
</ol>
For <a href="#ant-examples">additional examples</a>, please
see the <a href="#ant"><ant></a> builder.
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="clearcasebootstrapper"><clearcasebootstrapper></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#bootstrappers"><bootstrappers></a>
<clearcasebootstrapper></pre>
</div>
<p>Can be used to pull a single file (usually build.xml and/or
build.properties) from ClearCase prior to building.</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>file</td>
<td>Yes</td>
<td>The filename to write</td>
</tr>
<tr>
<td>viewPath</td>
<td>No</td>
<td>local path to the file</td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="clearcaseviewstrapper"><clearcaseviewstrapper></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#bootstrappers"><bootstrappers></a>
<clearcaseviewstrapper></pre>
</div>
<p>Can be used to automate the start-up of ClearCase
Views and VOBs prior to building in dynamic views.</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>viewpath</td>
<td>Yes</td>
<td>A path into the dynamic view to start-up, i.e. M:\someview\somevob\somepath (Windows) or
/view/someview/vobs/somevob/somepath (Linux/Unix). A path is specified rather than a view tag
so that you can re-use a CruiseControl property definition.</td>
</tr>
<tr>
<td>voblist</td>
<td>No</td>
<td>A comma separated list of VOBs to mount, i.e. "\VOB1,\VOB2" (Windows) or
"/vobs/VOB1,/vobs/VOB2" (Linux/Unix).</td>
</tr>
</tbody>
</table>
<h3>Examples</h3>
<ol>
<li>Start the Windows view "j2ee_bld" and mount the VOBs "\J2EE_Sources" and "\J2EE_Binaries":
<pre>
<property name="dir.j2ee" value="M:\j2ee_bld\J2EE_Sources\src"/>
<bootstrappers>
<clearcaseviewstrapper viewpath="${dir.j2ee}" voblist="\J2EE_Sources,\J2EE_Binaries"/>
<bootstrappers></pre>
</li>
</ol>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="cmsynergybootstrapper"><cmsynergybootstrapper></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#bootstrappers"><bootstrappers></a>
<cmsynergybootstrapper></pre>
</div>
<p>Used to reconfigure a CM Synergy project or project hierarchy</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>ccmexe</td>
<td>No</td>
<td>The name of the CM Synergy command line client. If not provided, the
plugin will search the system path for an executable called "ccm"
(or "ccm.exe" for Windows).</td>
</tr>
<tr>
<td>sessionfile</td>
<td>No</td>
<td>The session file used by the
<a href="#cmsynergysessionmonitor"><cmsynergysessionmonitor></a>
to persist your CM Synergy session information. If this attribute is
not set, it defaults to the file ".ccmsessionmap" in your home directory.</td>
</tr>
<tr>
<td>sessionname</td>
<td>No</td>
<td>The session name of the CM Synergy session you wish to use. This name
must appear in the session file. If not set, the plugin will attempt
to use the default (current) session as returned by the "ccm status"
command.</td>
</tr>
<tr>
<td>project</td>
<td>Yes</td>
<td>The project spec (two part name) of the project you wish to reconfigure.</td>
</tr>
<tr>
<td>recurse</td>
<td>No</td>
<td>If set to true, all subprojects will also be reconfigured. Defaults to
<i>true</i></td>
</tr>
</tbody>
</table>
<h3>Examples</h3>
<ol>
<li>Reconfigure the "j2ee~1.0_int" project (but <i>not</i> it's subprojects) using
the CM Synergy session named "j2ee_session".
<pre>
<bootstrappers>
<cmsynergybootstrapper project="j2ee~1.0_int"
sessionname="j2ee_session"
recurse="false"/>
<bootstrappers></pre>
</li>
</ol>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="currentbuildstatusbootstrapper"><currentbuildstatusbootstrapper></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#bootstrappers"><bootstrappers></a>
<currentbuildstatusbootstrapper></pre>
</div>
<p>Note: this plugin has been made obsolete by the
<a href="#currentbuildstatuslistener"><code>currentbuildstatuslistener</code></a>.</p>
<p>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
<code><currentbuildstatusbootstrapper></code> 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
<a href="#dateformat">dateformat</a> element.</p>
<p>This plugin is used in tandem with the
<a href="#currentbuildstatuspublisher"><code>currentbuildstatuspublisher</code></a>.</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>file</td>
<td>Yes</td>
<td>The filename to write, including path</td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="currentbuildstatusftpbootstrapper"><currentbuildstatusftpbootstrapper></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#bootstrappers"><bootstrappers></a>
<currentbuildstatusftpbootstrapper></pre>
</div>
<p>Note: this plugin has been made obsolete by the
<a href="#currentbuildstatusftplistener"><code>currentbuildstatusftplistener</code></a>.</p>
<p>This performs the same action as <a href="#currentbuildstatusbootstrapper"><code><currentbuildstatusbootstrapper></code></a>,
except that the status file is sent to the remote site via FTP, instead
of being stored locally.</p>
<h3>Attributes</h3>
<p>In addition to the <a href="#ftpattributes">common FTP attributes</a>,
<code><currentbuildstatusbootstrapper></code> uses the following
attributes.</p>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>file</td>
<td>Yes</td>
<td>The filename to write.</td>
</tr>
<tr>
<td>destDir</td>
<td>Yes</td>
<td>The remote directory (relative to <code>targetDir</code>)
to write the file.</td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="cvsbootstrapper"><cvsbootstrapper></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#bootstrappers"><bootstrappers></a>
<cvsbootstrapper></pre>
</div>
<p>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. <code><cvsbootstrapper></code>
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.</p>
<h3>Attributes</h3>
<p><code><cvsbootstrapper></code> requires at least one of its
attributes to be set.</p>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>localWorkingCopy</td>
<td>No</td>
<td>Path (absolute or relative to Build Loop execution
directory) to the local copy of the CVS module which contains
the target file. CVSBootstrapper will execute the update
command from this directory if specified. Defaults to Build
Loop execution directory.</td>
</tr>
<tr>
<td>cvsroot</td>
<td>No</td>
<td>The CVSROOT. Not required if the current working directory
is in the cvs project or if the localWorkingCopy attribute is
set.</td>
</tr>
<tr>
<td>file</td>
<td>No</td>
<td>The file to update from CVS, relative to localworkingcopy.
If not specified either the current working directory must be
in the local cvs project or the localWorkingCopy must be
set.</td>
</tr>
<tr>
<td>overwriteChanges</td>
<td>No</td>
<td>If set to true the update command will include the -C option
which will overwrite local changes.</td>
</tr>
<tr>
<td>resetStickyTags</td>
<td>No</td>
<td>If set to true the update command will include the -A option
which will reset any sticky tags, dates, or -k options.</td>
</tr>
<tr>
<td>compression</td>
<td>No</td>
<td>Sets the compression level used for the call to cvs, corresponding to the "-z" command line
parameter. When not set, the command line parameter is NOT included. Valid levels are 1 (high speed,
low compression) to 9 (low speed, high compression), or 0 to disable compression.</td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="execbootstrapper"><execbootstrapper></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#bootstrappers"><bootstrappers></a>
<execbootstrapper></pre>
</div>
<p>This bootstrapper executes a command. As it is based on the <a href="#exec">ExecBuilder</a>, it has the same
attributes</p>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="gitbootstrapper"><gitbootstrapper></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#bootstrappers"><bootstrappers></a>
<gitbootstrapper></pre>
</div>
<p>Handles updating from a git repository before the build
begins.</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>localWorkingCopy</td>
<td>Yes</td>
<td>the relative or absolute path to the local working copy of
the git repository on which to execute the update
command.</td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="harvestbootstrapper"><harvestbootstrapper></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#bootstrappers"><bootstrappers></a>
<harvestbootstrapper></pre>
</div>
<p>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. <code><harvestbootstrapper></code>
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.</p>
<p>In order to use this element, you must have the AllFusion Harvest
client installed on the CruiseControl machine. Additionally, the
<code>HARVESTHOME</code> environment variable should be set (this
should happen during installation of AllFusion Harvest) and you
should copy <code>jhsdk.jar</code> from your Harvest installation
into the CruiseControl <code>lib</code> directory. If you do not do
this, you will see an error indicating that the JHSDK is not installed.</p>
<h3>Attributes</h3>
<p><code><harvestbootstrapper></code> requires at least one of its
attributes to be set.</p>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>username</td>
<td>Yes</td>
<td>Usename to use in connecting to the Harvest Broker.</td>
</tr>
<tr>
<td>password</td>
<td>Yes</td>
<td>Password to use in connecting to the Harvest Broker.</td>
</tr>
<tr>
<td>broker</td>
<td>Yes</td>
<td>The name of the Harvest Broker to connect to.</td>
</tr>
<tr>
<td>project</td>
<td>Yes</td>
<td>The name of the project containing the file you wish to
bootstrap. Can be different from the cruisecontrol project
name.</td>
</tr>
<tr>
<td>state</td>
<td>Yes</td>
<td>The name of the state containing the file you wish to bootstrap.</td>
</tr>
<tr>
<td>viewpath</td>
<td>Yes</td>
<td>The Harvest view path of the file you wish to bootstrap.</td>
</tr>
<tr>
<td>clientpath</td>
<td>Yes</td>
<td>The Harvest client path to use when checking out the bootstrap file.</td>
</tr>
<tr>
<td>process</td>
<td>Yes</td>
<td>The name of the Harvest checkout process to use.</td>
</tr>
<tr>
<td>file</td>
<td>Yes</td>
<td>The name of the file to be bootstrapped.</td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="lockfilebootstrapper"><lockfilebootstrapper></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#bootstrappers"><bootstrappers></a>
<lockfilebootstrapper></pre>
</div>
<p>This plugin works in conjunction with a <a href="#lockfilelistener"><code><lockfilelistener></code></a> 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.</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>lockfile</td>
<td>Yes</td>
<td>The name (and path) of the file to serve as the lock between multiple projects.</td>
</tr>
<tr>
<td>projectname</td>
<td>Yes</td>
<td>The project name is written to the lockfile so that the LockFileListener knows which to delete.</td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="mercurialbootstrapper"><mercurialbootstrapper></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#bootstrappers"><bootstrappers></a>
<mercurialbootstrapper></pre>
</div>
<p>Handles updating from a Mercurial repository before the build
begins.</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>localWorkingCopy</td>
<td>Yes</td>
<td>the relative or absolute path to the local working copy of
the Mercurial repository on which to execute the update
command.</td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="p4bootstrapper"><p4bootstrapper></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#bootstrappers"><bootstrappers></a>
<p4bootstrapper></pre>
</div>
<p>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.</p>
<p>Setting the path to a complete P4 depot ending with a typical
triple dot (...) will synch all the files, e.g. <code>//depot/myproject/...</code></p>
<p>Note that the attributes path, p4Port, p4User, and p4Client are deprecated.
Please use the attributes listed below.</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>view</td>
<td>Yes</td>
<td>Valid Perforce path (a.k.a. 'view')</td>
</tr>
<tr>
<td>port</td>
<td>No</td>
<td>Perforce Server connection to use (host:port)</td>
</tr>
<tr>
<td>user</td>
<td>No</td>
<td>Perforce User name to use</td>
</tr>
<tr>
<td>passwd</td>
<td>No</td>
<td>Perforce password to use</td>
</tr>
<tr>
<td>client</td>
<td>No</td>
<td>Perforce Client name to use</td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="plasticscmbootstrapper"><plasticscmbootstrapper></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#bootstrappers"><bootstrappers></a>
<plasticscmbootstrapper></pre>
</div>
<p>Automatically updates the workspace before the build begins.
The selected workspace must already exist on the local filesystem.</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>wkspath</td>
<td>Yes</td>
<td>Valid Plastic SCM workspace path. </td>
</tr>
<tr>
<td>branch</td>
<td>No</td>
<td>The branch from which to get the source. If none has been specified, it updates the workspace according to its configuration.</td>
</tr>
<tr>
<td>repository</td>
<td>No</td>
<td>The repository from which to get the source. If none has been specified, it updates the workspace according to its configuration.</td>
</tr>
<tr>
<td>pathtoupdate</td>
<td>No</td>
<td>A path under the workspace path which will be updated. If none is specied, it updates all the workspace.</td>
</tr>
<tr>
<td>forced</td>
<td>No (defaults to "false")</td>
<td>Do the update with the "--forced" option</td>
</tr>
</tbody>
</table>
<h3>Examples</h3>
<ol>
<li>Update the workspace (using the option forced) in the path in c:\work\cruise\plasticwks setting the branch "br:/main" as working branch.
<pre>
<bootstrappers>
<plasticscmbootstrapper wkspath="c:\work\cruise\plasticwks"
branch="br:/main"
forced="yes" />
<bootstrappers></pre>
</li>
</ol>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="snapshotcmbootstrapper"><snapshotcmbootstrapper></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#bootstrappers"><bootstrappers></a>
<snapshotcmbootstrapper></pre>
</div>
<p>Can be used to pull a single file (usually build.xml and/or
build.properties) or directory from SnapshotCM prior to building.</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>file</td>
<td>Yes</td>
<td>Name of the file or directory to fetch from the SnapshotCM
repository. Updates from SnapshotCM repository will be
recursive and forced (over-writing any local changes).</td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="starteambootstrapper"><starteambootstrapper></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#bootstrappers"><bootstrappers></a>
<starteambootstrapper></pre>
</div>
<p>Handles updating multiple files (space separated list) from StarTeam
before the build begins.</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>files</td>
<td>Yes</td>
<td>Space separated list of files to retrieve</td>
</tr>
<tr>
<td>folder</td>
<td>Yes</td>
<td>The repository folder</td>
</tr>
<tr>
<td>localfolder</td>
<td>No</td>
<td>Path to the folder on the local file system</td>
</tr>
<tr>
<td>password</td>
<td>Yes</td>
<td> </td>
</tr>
<tr>
<td>port</td>
<td>Yes</td>
<td>Port StarTeam server is using</td>
</tr>
<tr>
<td>project</td>
<td>Yes</td>
<td>StarTeam project</td>
</tr>
<tr>
<td>server</td>
<td>Yes</td>
<td>Hostname for StarTeam server</td>
</tr>
<tr>
<td>username</td>
<td>Yes</td>
<td> </td>
</tr>
<tr>
<td>view</td>
<td>Yes</td>
<td>StarTeam view</td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="surroundbootstrapper"><surroundbootstrapper></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#bootstrappers"><bootstrappers></a>
<surroundbootstrapper></pre>
</div>
<p>Fetches a single repository (and optionally it's sub-repositories)
from Surround SCM before starting the build.</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>branch</td>
<td>No</td>
<td>Surround SCM branch name. The default is pulled from the local working directory.</td>
</tr>
<tr>
<td>repository</td>
<td>No</td>
<td>Surround SCM repository path. The default is pulled from the local working directory.</td>
</tr>
<tr>
<td>label</td>
<td>No</td>
<td>Enter a label to search for when getting files.</td>
</tr>
<tr>
<td>includeremovedfiles</td>
<td>No</td>
<td>Include removed files when getting files by label or timestamp. Default is true.
Ignored if a label is not specified. Options are <strong>1</strong> or <strong>0</strong> (default).</td>
</tr>
<tr>
<td>overwrite</td>
<td>No</td>
<td>Enter how to handle a local writable file.
Options are <strong>1</strong> to overwrite or <strong>0</strong> (default) to skip.</td>
</tr>
<tr>
<td>recursive</td>
<td>No</td>
<td>Recursively get files and sub-repositories. Options are <strong>1</strong> or <strong>0</strong> (default).</td>
</tr>
<tr>
<td>forcefetch</td>
<td>No</td>
<td>Force file retrieval from server regardless of the local copy status.
Options are <strong>1</strong> or <strong>0</strong> (default).</td>
</tr>
<tr>
<td>makewritable</td>
<td>No</td>
<td>Make local file editable or writable. Default is read-only.
Options are <strong>1</strong> or <strong>0</strong> (default).</td>
</tr>
<tr>
<td>serverconnect</td>
<td>No</td>
<td>Enter the address and port number of the Surround SCM server host computer.
Format is server:port. If not entered, the last saved connection parameters are used.</td>
</tr>
<tr>
<td>serverlogin</td>
<td>No</td>
<td>Enter the username and password used to login to the Surround SCM server.
Format is username:password. If not entered, the last saved login parameters are used.</td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="svnbootstrapper"><svnbootstrapper></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#bootstrappers"><bootstrappers></a>
<svnbootstrapper></pre>
</div>
<p>Handles updating a single file (typically build.xml and/or
build.properties) from a Subversion repository before the build
begins.</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>localWorkingCopy</td>
<td rowspan="2">One of these</td>
<td>the relative or absolute path to the local working copy of
the Subversion repository on which to execute the update
command.</td>
</tr>
<tr>
<td>file</td>
<td>file to update from the Subversion repository.</td>
</tr>
<tr>
<td>username</td>
<td>No</td>
<td>used for authentication.</td>
</tr>
<tr>
<td>password</td>
<td>No</td>
<td>used for authentication.</td>
</tr>
<tr>
<td>configDir</td>
<td>No</td>
<td>Instructs Subversion to read configuration information from the specified directory instead of the default location (.subversion in the user's home directory).</td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="tfsbootstrapper"><tfsbootstrapper></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#bootstrappers"><bootstrappers></a>
<tfsbootstrapper></pre>
</div>
<p>Gets a single path from Visual Studio Team Foundation Server before the build begins.</p>
<p>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
<a href="http://www.codeplex.com/CodePlex/Wiki/View.aspx?title=Obtaining%20the%20Team%20Explorer%20Client&referringTitle=Source%20control%20clients">
CodePlex wiki</a>.
<a href="http://www.teamprise.com/">Teamprise</a> 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
<a href="http://www.teamprise.com/">Teamprise</a> command line client, visit the
<a href="http://www.teamprise.com/download/index.html">Teamprise download site</a>
(fully functional evaluation licenses
<a href="http://www.teamprise.com/download/evaluate.html">are available</a>).
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 <a href="http://kb.teamprise.com/article/view/40">
Teamprise Knowledgebase</a>. </p>
<p>Gets are performed by executing a command similar to the following</p>
<pre>tf get //build/path/to.get
-recursive -force -noprompt
-login:DOMAIN\name,password</pre>
<p>For further details regarding the tf get command, consult the
<a href="http://msdn2.microsoft.com/en-us/library/fx7sdeyf(VS.80).aspx">
MSDN documentation</a>.</p>
<p>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.</p>
<p>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
<code>/cruisecontrol/projects/myproject</code> and the files are stored in TFS at
<code>$/MyTeamProject/trunk</code> you would have first needed to execute
the following commands on the machine running cruisecontrol</p>
<pre>tf workspace /server:http://tfsserver:8080 /login:user@DOMAIN,password /new buildWorkspace<br/>
tf workfold /server:http://tfsserver:8080 /login:user@DOMAIN,password /workspace:buildWorkspace /map $/MyTeamProject/trunk //cruisecontrol/projects/myproject
</pre>
<p>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 <code>set TFSPROXY=http://tfsproxy:8081</code>.
If you are using the Teamprise command line client, then you may pass "-proxy:http://tfsproxy:8081" in the options attribute.</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>itemSpec</td>
<td>Yes</td>
<td>The path to perform a get for. This may be a local or server path as defined by the Item Specification.
For more information on valid item specification see <a href="http://msdn2.microsoft.com/en-us/library/56f7w6be(VS.80).aspx#sectionToggle3">http://msdn2.microsoft.com/en-us/library/56f7w6be(VS.80).aspx#sectionToggle3</a></td>
</tr>
<tr>
<td>username</td>
<td>no</td>
<td>The username to use when connection to Team Foundation
Server. This user must have read permissions to the
version control repository for the projectPath. When using
the Microsoft client, if no username is passed then the user
that the CruiseControl process is running as will be used.
Note that is a username is provided then a password must be
provided in order for the credentials to be used.<br />
<br />
The username should be passed in the form <code>DOMAIN\username</code>.
From unix systems the name can be passed in the <code>username@DOMAIN</code>
format if preferred as that removes confusion over escaping of
the <code>\</code> character which should not be required.<br/>
<br/>
It is possible for the command line client to determine the credentials automatically
if they were allowed to be cached during the creation of the workspace and working folder
mapping - however the credentials of the local process will usually override those
in the case of the Microsoft command line client.</td>
</tr>
<tr>
<td>password</td>
<td>no</td>
<td>The password to use with the username when authenticating
with the server.</td>
</tr>
<tr>
<td>tfPath</td>
<td>No (defaults to "tf")</td>
<td>Specify the full path to the tf command being used. If
not supplied then the plug-in will try to locate a command
called "tf" in the cruise control system path. By default,
the Microsoft client is installed into <code>C:\Program Files\Microsoft Visual Studio 8\Common7\IDE\TF.exe</code>
</td>
</tr>
<tr>
<td>recursive</td>
<td>no (defaults to false)</td>
<td>Flag to indicate if a recursive get should be performed.</td>
</tr>
<tr>
<td>force</td>
<td>no (defaults to false)</td>
<td>Flag to indicate of the tf get command should be performed using the /force
switch. By default, TFS will only download files that the server thinks have
changed since the last time you told it you were modifying or geting files
into your local TFS workspace. It will also not overwrite locally writable
files. Setting the force option will make TFS always download the files and
overwrite any that happen to be locally writable - however this has the expense
of significantly increasing the network traffic and increasing the time to perform
the bootstrap process.
</td>
</tr>
<tr>
<td>options</td>
<td>no</td>
<td>An optional string that may be passed as part of the command
line. The contents of the options tag are passed as an
argument to the tf get command.</td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="vssbootstrapper"><vssbootstrapper></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#bootstrappers"><bootstrappers></a>
<vssbootstrapper></pre>
</div>
<p>Handles updating a single file (typically build.xml and/or
build.properties) from VSS before the build begins.</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>vsspath</td>
<td>Yes</td>
<td>Fully qualified VSS path to the target file. If the leading
dollar-sign ['$'] is omitted, one will be prepended
automatically.<br/>
<b>Example:</b> /Project/subproject/filename.ext</td>
</tr>
<tr>
<td>localdirectory</td>
<td>Yes</td>
<td>Fully qualified path for the destination directory.<br/>
<b>Example:</b> c:\directory\subdirectory\</td>
</tr>
<tr>
<td>login</td>
<td>No</td>
<td>VSS login information in the form <i>username,password</i></td>
</tr>
<tr>
<td>ssdir</td>
<td>No</td>
<td>Path to the directory containing ss.exe. By default, ss.exe
is assumed to be in the path.<br/>
Note: should not contain whitespace.</td>
</tr>
<tr>
<td>serverpath</td>
<td>No</td>
<td>Path to the directory containing srcsafe.ini.</td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="modificationset"><modificationset></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<modificationset></pre>
</div>
<p>A container element for a set of modifications collected from all
included SourceControl elements. <code><modificationset></code>
can contain multiple elements which can be useful to check only parts
of a large project rather than checking all files every time.</p>
<p>Most SourceControl elements support the <code>property</code>
/<code>propertyOnDelete</code> attributes which can allow for
conditional building that may greatly speed the feedback cycle.</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>requiremodification</td>
<td>No (defaults to true)</td>
<td>Is a modification required for the build to continue?
Default value is true. Useful to set to false when the schedule
has only time based builds or if you want to run tests to verify
an external resource (such as a database). <b>NOTE - This attribute
will be going away.</b> Use the requireModification attribute that is on the
project tag instead.<br /></td>
</tr>
<tr>
<td>quietperiod</td>
<td>No (defaults to 60)</td>
<td>The number of seconds required to have passed since the last
modification before a build can commence. This attribute is used
to avoid starting a build while someone is in mid-checkin. If a
modification is detected to be within the quiet period then CC
will sleep until the quiet period is finished and then recheck
for modifications. Small values recommended if you use a
bootstrapper to sync files (as opposed to getting updates as part
of the build). 0 is a valid value and recommended for version
control systems such as Perforce and Subversion with atomic commits.</td>
</tr>
<tr>
<td>ignoreFiles</td>
<td>No</td>
<td>Specify a comma separated list of glob-patterns identify files to be ignored in modificationsets.
Each pattern is matched against the complete path.
Example: <code>*.txt,*/build/build.xml</code><br/> This is useful if you want to update and commit files during your CC build.</td>
</tr>
</tbody>
</table>
<h3>Child Elements</h3>
<table class="documentation">
<thead>
<tr>
<th>Element</th>
<th>Cardinality</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><a href="#accurev"><accurev></a></td>
<td>0 .. *</td>
<td>Checks for changes in an AccuRev stream.</td>
</tr>
<tr>
<td><a href="#alienbrain"><alienbrain></a></td>
<td>0 .. *</td>
<td>Checks for changes in an AlienBrain repository.</td>
</tr>
<tr>
<td><a href="#alwaysbuild"><alwaysbuild></a></td>
<td>0 .. *</td>
<td>Always returns a single modification so the build will be run.</td>
</tr>
<tr>
<td><a href="#buildstatus"><buildstatus></a></td>
<td>0 .. *</td>
<td>Checks for a successful build in another project.</td>
</tr>
<tr>
<td><a href="#clearcase"><clearcase></a></td>
<td>0 .. *</td>
<td>Checks for changes in a ClearCase repository.</td>
</tr>
<tr>
<td><a href="#cmsynergy"><cmsynergy></a></td>
<td>0 .. *</td>
<td>Checks for changes in a CM Synergy repository.</td>
</tr>
<tr>
<td><a href="#compound"><compound></a></td>
<td>0 .. *</td>
<td>Checks for changes from a list of trigger source controls,
and if modification are detected, returns changes from a list
of target source controls.</td>
</tr>
<tr>
<td><a href="#cvs"><cvs></a></td>
<td>0 .. *</td>
<td>Checks for changes in a CVS repository.</td>
</tr>
<tr>
<td><a href="#darcs"><darcs></a></td>
<td>0 .. *</td>
<td>Checks for changes in a Darcs repository.</td>
</tr>
<tr>
<td><a href="#filesystem"><filesystem></a></td>
<td>0 .. *</td>
<td>Checks for changes in a file system.</td>
</tr>
<tr>
<td><a href="#forceonly"><forceonly></a></td>
<td>0 .. *</td>
<td>Never returns any changes. Deprecated: use forceonly attribute on <a href="#project"><project></a> instead.</td>
</tr>
<tr>
<td><a href="#git"><git></a></td>
<td>0 .. *</td>
<td>Checks for changes in a git repository.</td>
</tr>
<tr>
<td><a href="#git"><git></a></td>
<td>0 .. *</td>
<td>Checks for changes in a git repository.</td>
</tr>
<tr>
<td><a href="#harvest"><harvest></a></td>
<td>0 .. *</td>
<td>Checks for changes in an All Fusion Harvest repository.</td>
</tr>
<tr>
<td><a href="#httpfile"><httpfile></a></td>
<td>0 .. *</td>
<td>Checks for changes in a remote file via http.</td>
</tr>
<tr>
<td><a href="#mercurial"><mercurial></a></td>
<td>0 .. *</td>
<td>Checks for changes in a Mercurial repository.</td>
</tr>
<tr>
<td><a href="#mks"><mks></a></td>
<td>0 .. *</td>
<td>Checks for changes in a MKS repository.</td>
</tr>
<tr>
<td><a href="#p4"><p4></a></td>
<td>0 .. *</td>
<td>Checks for changes in a Perforce repository.</td>
</tr>
<tr>
<td><a href="#plasticscm"><plasticscm></a></td>
<td>0 .. *</td>
<td>Checks for changes in a Plastic SCM branch.</td>
</tr>
<tr>
<td><a href="#pvcs"><pvcs></a></td>
<td>0 .. *</td>
<td>Checks for changes in a PVCS repository.</td>
</tr>
<tr>
<td><a href="#snapshotcm"><snapshotcm></a></td>
<td>0 .. *</td>
<td>Checks for changes in a SnapshotCM repository.</td>
</tr>
<tr>
<td><a href="#starteam"><starteam></a></td>
<td>0 .. *</td>
<td>Checks for changes in a Star Team repository.</td>
</tr>
<tr>
<td><a href="#store"><store></a></td>
<td>0 .. *</td>
<td>Checks for changes in a Cincom Smalltalk VisualWorks
Store repository.</td>
</tr>
<tr>
<td><a href="#surround"><surround></a></td>
<td>0 .. *</td>
<td>Checks for changes in a Surround SCM repository.</td>
</tr>
<tr>
<td><a href="#svn"><svn></a></td>
<td>0 .. *</td>
<td>Checks for changes in a Subversion repository.</td>
</tr>
<tr>
<td><a href="#tfs"><tfs></a></td>
<td>0 .. *</td>
<td>Checks for changes in a Microsoft Visual Studio Team Foundation Server repository.</td>
</tr>
<tr>
<td><a href="#timebuild"><timebuild></a></td>
<td>0 .. *</td>
<td>Triggers a build after a particular time threshold.</td>
</tr>
<tr>
<td><a href="#veto"><veto></a></td>
<td>0 .. *</td>
<td>Checks for changes in another project and will veto a build if changes are found.</td>
</tr>
<tr>
<td><a href="#vss"><vss></a></td>
<td>0 .. *</td>
<td>Checks for changes in a Visual SourceSafe repository.</td>
</tr>
<tr>
<td><a href="#vssjournal"><vssjournal></a></td>
<td>0 .. *</td>
<td>Checks for changes in a Visual SourceSafe, Journal File
Implementation.</td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="accurev"><accurev></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#modificationset"><modificationset></a>
<accurev></pre>
</div>
<p>Checks for modifications in an AccuRev stream.</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>stream</td>
<td>Yes</td>
<td>The name of the AccuRev stream where the plugin looks for Modification(s).</td>
</tr>
<tr>
<td>verbose</td>
<td>No (defaults to "false")</td>
<td>Set to "true" to enable a more verbose logging style.</td>
</tr>
<tr>
<td>property</td>
<td>No</td>
<td>Will set this property if a modification has occurred. For
use in conditionally controlling the build later.</td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="alienbrain"><alienbrain></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#modificationset"><modificationset></a>
<alienbrain></pre>
</div>
<p>Triggers a build if there is a change in an AlienBrain repository.</p>
<p>Changes are detected by running a command similar to the following:</p>
<pre>ab find <i>PathToProject</i> -regex "SCIT > <i>lastbuildtime</i>" </pre>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>server</td>
<td>No</td>
<td>The name of the machine hosting the AlienBrain repository. If specified, it will override the value in the NXN_AB_SERVER environment variable.</td>
</tr>
<tr>
<td>database</td>
<td>No</td>
<td>The name of the project in the AlienBrain repository. If specified, it will override the value in the NXN_AB_DATABASE environment variable.</td>
</tr>
<tr>
<td>user</td>
<td>No</td>
<td>The AlienBrain user account name to use when querying for modifications. If specified, it will override the value in the NXN_AB_USERNAME environment variable.</td>
</tr>
<tr>
<td>password</td>
<td>No</td>
<td>The password of the AlienBrain user account to use when querying for modifications. If specified, it will override the value in the NXN_AB_PASSWORD environment variable.</td>
</tr>
<tr>
<td>path</td>
<td>Yes</td>
<td>The path to the item that will be queried for modifications Typically a path like 'alienbrain://Project/SubProject'</td>
</tr>
<tr>
<td>branch</td>
<td>No</td>
<td>The branch of the project to check for modifications.</td>
</tr>
<tr>
<td>property</td>
<td>No</td>
<td>Will set this property if a modification has occurred. For
use in conditionally controlling the build later.</td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="alwaysbuild"><alwaysbuild></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#modificationset"><modificationset></a>
<alwaysbuild></pre>
</div>
<p>Used to always trigger a build by returning a single modification.</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>username</td>
<td>No (defaults to "User")</td>
<td>The username to use for the single reported (fake) Modification.</td>
</tr>
<tr>
<td>property</td>
<td>No</td>
<td>Set this property if a modification has occurred. For use in conditionally controlling the build later.</td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="buildstatus"><buildstatus></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#modificationset"><modificationset></a>
<buildstatus></pre>
</div>
<p>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 <a href="#email"><email></a>
publisher.
</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>logdir</td>
<td>Yes</td>
<td>Path to CruiseControl log directory for the project to
monitor.</td>
</tr>
<tr>
<td>property</td>
<td>No</td>
<td>Will set this property if a modification has occurred. For
use in conditionally controlling the build later.</td>
</tr>
</tbody>
</table>
<h3>Properties Passed to the Builders</h3>
<p>In addition to the standard CruiseControl <a href="#buildproperties">
properties passed to builders</a>, <buildstatus> sets the
following properties:</p>
<table class="documentation">
<thead>
<tr>
<th>Property Name</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>most.recent.logdir</td>
<td>The location being checked for new log files</td>
</tr>
<tr>
<td>most.recent.logfile</td>
<td>The name of the newest logfile included in the
modification set</td>
</tr>
<tr>
<td>most.recent.logtime</td>
<td>The timestamp of the newest build included in the
modification set, using the format
<code>yyyyMMddHHmmss</code></td>
</tr>
<tr>
<td>most.recent.loglabel</td>
<td>The label of the newest build included in the
modification set</td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="clearcase"><clearcase></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#modificationset"><modificationset></a>
<clearcase></pre>
</div>
<p>Triggers a build if there is a change within a ClearCase repository.</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>branch</td>
<td>Yes</td>
<td>The ClearCase branch</td>
</tr>
<tr>
<td>recursive</td>
<td>No (defaults to true)</td>
<td>Whether to check sub-folders in the viewpath.</td>
</tr>
<tr>
<td>all</td>
<td>No (defaults to false)</td>
<td>Set when checking the entire view path.
When checking the entire view path this option invokes 'lshistory -all'
instead of 'lshistory -recursive', which is much faster.<br/><br/>
This option is mutually exclusive with the recursive property.<br/><br/>
Note that 'all' does not use your view's config-spec rules. It behaves
like having a single line config-spec that selects just ELEMENT * /<branch>/LATEST
(i.e. 'lshistory -all' results that contain @@ are discarded). This differs from
'recurse', which only shows items selected by your current view.<br/><br/>
</td>
</tr>
<tr>
<td>viewpath</td>
<td>Yes</td>
<td>Local working copy to use when making queries</td>
</tr>
<tr>
<td>property</td>
<td>No</td>
<td>Will set this property if a modification has occurred. For
use in conditionally controlling the build later.</td>
</tr>
</tbody>
</table>
<h3>Properties Passed to the Builders</h3>
<p>In addition to the standard CruiseControl <a href="#buildproperties">
properties passed to builders</a>, <clearcase> sets the
following properties:</p>
<table class="documentation">
<thead>
<tr>
<th>Property Name</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>clearcaselastbuild</td>
<td>Timestamp representing the last built time, using the
format <code>dd-MMMM-yyyy.HH:mm:ss</code></td>
</tr>
<tr>
<td>clearcasenow</td>
<td>Timestamp representing the time the current build
started, using the format <code>dd-MMMM-yyyy.HH:mm:ss</code></td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="cmsynergy"><cmsynergy></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#modificationset"><modificationset></a>
<cmsynergy></pre>
</div>
<p>Triggers a build if tasks have been added to any folder within a
CM Synergy project's reconfigure properties since the last build.</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>ccmexe</td>
<td>No</td>
<td>The name of the CM Synergy command line client. If not provided, the
plugin will search the system path for an executable called "ccm"
(or "ccm.exe" for Windows).</td>
</tr>
<tr>
<td>sessionfile</td>
<td>No</td>
<td>The session file used by the
<a href="#cmsynergysessionmonitor"><cmsynergysessionmonitor></a>
to persist your CM Synergy session information. If this attribute is
not set, it defaults to the file ".ccmsessionmap" in your home directory.</td>
</tr>
<tr>
<td>sessionname</td>
<td>No</td>
<td>The session name of the CM Synergy session you wish to use. This name
must appear in the session file. If not set, the plugin will attempt
to use the default (current) session as returned by the "ccm status"
command.</td>
</tr>
<tr>
<td>project</td>
<td>Yes</td>
<td>The project spec (two part name) of the CM Synergy project in which
you wish to search for changes.</td>
</tr>
<tr>
<td>instance</td>
<td>No</td>
<td>Used to set the project's instance value. As CM Synergy only allows a
single instance of a project object in any given database, this attribute
defaults to "1", and should not need to be changed by most users. <b>You
might, however, need to set this value when using the DCM (Distributed
Change Management) feature of the tool - which appends the DB name to
the instance value.</b></td>
</tr>
<tr>
<td>ccmdateformat</td>
<td>No</td>
<td>The default (output) date format used by CM Synergy is
"EEE MMM dd HH:mm:ss yyyy" If you have customized this for your installation,
you must provide the correct format here. The format should follow the
standard defined in Java's SimpleDateFormat class.</td>
</tr>
<tr>
<td>updatefolders</td>
<td>No</td>
<td>By default, the plugin will always refresh the reconfigure properties of
the given project before searching for changes. This allows any query
based folders to update themselves with new tasks. If you wish to disable
this feature (not recommended), you may set this attribute to false.
<b>This feature will only work with CM Synergy version 6.3 and above. If
you are using an older version, you <i>must</i> set this option to false. In this
case, you'll want to use the
<a href="#cmsynergybootstrapper"><cmsynergybootstrapper></a>
as a workaround. Please see example 2 below as well as the Wiki site for
more information.</b></td>
</tr>
<tr>
<td>reconfigure</td>
<td>No</td>
<td>Disabled by default. If you set this option to true, the project (and
optionally any subprojects) will be automatically reconfigured when changes
are detected. This eliminates the need to handle this from within your build
scripts.</td>
</tr>
<tr>
<td>recurse</td>
<td>No</td>
<td>Used in conjunction with the reconfigure option. If set to true (which is
the default) all subprojects will also be reconfigured.</td>
</tr>
<tr>
<td>usebindtime</td>
<td>No</td>
<td>If set to true, the time a task came into the reconfigure folder is used
to determine modified tasks instead of the tasks completion date. This is
a more precise query to find modifications since the last build when the
reconfiguration rules are based on other criteria e.g. the status of a Change
Synergy change request. <strong>This feature will only work with CM Synergy version
6.3SP1 and above. If you are using an older version, you <i>must</i> set this
option to false (default).</strong>
</td>
</tr>
<tr>
<td>ignoreworkarea</td>
<td>No</td>
<td>By default, the plugin will query CM Synergy to determine the work area
location of the project. This location is then passed to the builders in
the property "cc.ccm.workarea". If you wish to disable this feature
(not recommended), you can set this attribute to <i>true</i>.</td>
</tr>
<tr>
<td>changesynergyurl</td>
<td>No</td>
<td>If provided, an active link will be created from
the build results web page to any change requests
associated with any new tasks. The format should be
"http://server:port". If you wish to use this option,
you must also set the ccmdb attribute.</td>
</tr>
<tr>
<td>ccmdb</td>
<td>No</td>
<td>Used in conjunction with changesynergyurl. This
should be set to the location of the database on
the CM Synergy server. (e.g. "/ccmdb/mydb")</td>
</tr>
<tr>
<td>language</td>
<td>No</td>
<td>If you have a non U.S. English installation of CM Synergy, you may
specify the ISO language code here. (e.g. fr, de, etc.)</td>
</tr>
<tr>
<td>country</td>
<td>No</td>
<td>If you have a non U.S. English installation of CM Synergy, you may
specify the ISO country code here. (e.g. FR, DE, etc.)</td>
</tr>
<tr>
<td>property</td>
<td>No</td>
<td>Added for compliance with the CruiseControl API. A property of
this name will be provided to the builders if any CM Synergy
object has changed since the last build. The default is
cc.ccm.haschanged, and probably shouldn't be altered.</td>
</tr>
</tbody>
</table>
<h3>Properties Passed to the Builders</h3>
<p>In addition to the standard CruiseControl <a href="#buildproperties">
properties passed to builders</a>, <cmsynergy> sets the
following properties:</p>
<table class="documentation">
<thead>
<tr>
<th>Property Name</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>cc.ccm.session</td>
<td>The CM Synergy session ID used to check for modifications.</td>
</tr>
<tr>
<td>cc.ccm.dateformat</td>
<td>The date format used to convert CM Synergy dates into Java dates.</td>
</tr>
<tr>
<td>cc.ccm.project</td>
<td>The two part name of the project (as provided in the project attribute).</td>
</tr>
<tr>
<td>cc.ccm.workarea</td>
<td>The file system location of the CM Synergy work area for the project
(unless the ignoreworkarea attribute was set).</td>
</tr>
<tr>
<td>cc.ccm.haschanged (or the value specified by the property attribute)</td>
<td>Set to true if any CM Synergy objects have changed since the last build.</td>
</tr>
</tbody>
</table>
<h3>Examples</h3>
<ol>
<li>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.
<pre>
<modificationset>
<cmsynergy project="j2ee~1.0_int"
sessionname="j2ee_session"
reconfigure="true"/>
<modificationset/>
</pre>
</li>
<li>For users of CM Synergy older than version 6.3 only. Use the
<a href="#cmsynergybootstrapper"><cmsynergybootstrapper></a>
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 <i>must</i> set the "updatefolder" attribute to false.
<pre>
<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/>
</pre>
</li>
</ol>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="compound"><compound></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#modificationset"><modificationset></a>
<compound></pre>
</div>
<p>Contains two separate lists of source controls:
<code><triggers></code> and <code><targets></code>. Triggers
are checked for modifications every scheduled poll. Targets are
only checked for modifications if there was any modifications detected
in the triggers.</p>
<p>Arbitrary nesting of source controls under <code><triggers></code>
and <code><targets></code> is possible.</p>
<p>The <code><compound></code> 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.</p>
<p>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.</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>includeTriggerChanges</td>
<td>No (defaults to false)</td>
<td>Add the trigger modifications to the list of returned
modifications? By default, the list of returned modifications
only includes the source controls from the
<code><targets></code> element. By setting this attribute
to true, the list of modifications will include both
<code><triggers></code> and <code><targets></code>
modifications.</td>
</tr>
<tr>
<td>property</td>
<td>No</td>
<td>Set this property if a modification has occurred. For use
in conditionally controlling the build later.</td>
</tr>
</tbody>
</table>
<h3>Child Elements</h3>
<table class="documentation">
<thead>
<tr>
<th>Element</th>
<th>Cardinality</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code><triggers></code></td>
<td>1</td>
<td>A container for one or more source control elements that
trigger a full check of the targets. Any child element of
<a href="#modificationset"><code><modificationset></code></a>
can be used as a child element of <code><triggers></code>.</td>
</tr>
<tr>
<td><code><targets></code></td>
<td>1</td>
<td>A container for one or more source control elements that
collectively represent the modificationset of the
<code><compound></code> element. Any child element of
<a href="#modificationset"><code><modificationset></code></a>
can be used as a child element of <code><targets></code>.</td>
</tr>
</tbody>
</table>
<h3>Example</h3>
<p>This example polls the file <code>mod_file.txt</code> every
scheduled interval using
<a href="#filesystem"><code><filesystem></code></a>. When a change
is detected, <a href="#cvs"><code><cvs></code></a> is used to
determine the full list of modifications. If <code>mod_file.txt</code>
is never modified, cvs is never accessed.</p>
<pre><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></pre>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="cvs"><cvs></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#modificationset"><modificationset></a>
<cvs></pre>
</div>
<p>Triggers a build if there is a change within a CVS repository.</p>
<p>Changes are detected by running a command similar to the following:</p>
<pre>cvs [-d <i>CVSROOT</i>] -q log|rlog [-N] -d "<i>lastbuildtime</i><<i>checktime</i>" [-b|-r<i>TAG</i>] <i>module</i></pre>
<p>The following changes are made to generate the actual command:</p>
<ul>
<li><code>log</code> is used when the localworkingcopy attribute is set,
<code>rlog</code> otherwise.</li>
<li><code><i>lastbuildtime</i></code> is replaced with the date of
the last build, using the date format
<code>yyyy-MM-dd HH:mm:ss 'GMT'</code>.</li>
<li><code><i>checktime</i></code> is replaced with the date at which
the check takes place.</li>
<li>The <code>-d</code> option is only used when the cvsroot
attribute is specified; <code><i>CVSROOT</i></code> is replaced by
the value of that attribute.</li>
<li>The <code>-r</code> option is only used when the tag attribute
is specified; <code><i>TAG</i></code> is replaced by the value of
that attribute. Otherwise, the <code>-b</code> option is used.</li>
<li>The <code>-N</code> option is only used when the tag attribute
is not specified or if it is set to <code>HEAD</code>.</li>
<li><code>module</code> is replaced with the specified module
name. If a local working copy is used then the module name is
left off.</li>
</ul>
<p>Refer to the <a class="external"
href="http://www.cvsnt.org/manual/html/log.html">cvs log</a> reference for
further details of the <code>cvs log</code> command.</p>
<p>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 <a class="external"
href="http://confluence.public.thoughtworks.org/display/CC/CvsrootUsers">
CVSROOT/users</a> page of the CruiseControl Wiki.</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>localworkingcopy</td>
<td rowspan="3">Either localworkingcopy or both cvsroot
and module.</td>
<td>Relative or absolute path to the local working copy.
Directory must exist and should have files from a previous
checkout.</td>
</tr>
<tr>
<td>cvsroot</td>
<td>Specifies the location of the CVS repository. This should
be of the form<br/>
<i><code>:pserver:username@cvs.example.com:/cvsroot/reponame</code></i>
</td>
</tr>
<tr>
<td>module</td>
<td>The name of the CVS module that should be used.
This is passed as the last parameter to the cvs rlog command.
Refer to the <code>rlog</code> command in the
<a class="external" href="http://www.cvsnt.org/manual/html/log.html">
cvs log</a> reference for further details.</td>
</tr>
<tr>
<td>tag</td>
<td>No (defaults to <code>HEAD</code>)</td>
<td>Specify the cvs tag. The value of this attribute is passed
directly to <code>cvs log</code> using the <code>-r</code>
option. Numeric revision numbers, tags, branch tags, or ranges of
revisions are valid (when a non branch tag is used, a single modification
per file will be listed). Refer to the <code>-r</code> option in the
<a class="external" href="http://www.cvsnt.org/manual/html/log.html">
cvs log</a> reference for further details.</td>
</tr>
<tr>
<td>property</td>
<td>No</td>
<td>Set this property if a modification has occurred. For use
in conditionally controlling the build later.</td>
</tr>
<tr>
<td>propertyondelete</td>
<td>No</td>
<td>Set this property if a file has been deleted. For use in
conditionally controlling the build later.</td>
</tr>
<tr>
<td>reallyQuiet</td>
<td>No</td>
<td>Sets whether to use "-Q", instead of the default "-q" for the cvs log command. Setting this
attribute to true can help to reduce CruiseControl log file size, especially when using branches.
Defaults to false.</td>
</tr>
<tr>
<td>compression</td>
<td>No</td>
<td>Sets the compression level used for the call to cvs, corresponding to the "-z" command line
parameter. When not set, the command line parameter is NOT included. Valid levels are 1 (high speed,
low compression) to 9 (low speed, high compression), or 0 to disable compression.</td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="darcs"><darcs></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#modificationset"><modificationset></a>
<darcs></pre>
</div>
<p>Triggers a build if there is a change within a <a href="http://darcs.net" class="external">Darcs</a>
repository.</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>workingdir</td>
<td rowspan="2">Either workingdir or repository location.</td>
<td>Relative or absolute path to the workingdir. Directory must exist.</td>
</tr>
<tr>
<td>repositorylocation</td>
<td>Specifies the location of the Darcs repository.</td>
</tr>
<tr>
<td>property</td>
<td>No</td>
<td>Set this property if a modification has occurred. For use
in conditionally controlling the build later.</td>
</tr>
<tr>
<td>propertyondelete</td>
<td>No</td>
<td>Set this property if a file has been deleted. For use in
conditionally controlling the build later.</td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="filesystem"><filesystem></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#modificationset"><modificationset></a>
<filesystem></pre>
</div>
<p>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.</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>folder</td>
<td>Yes</td>
<td>Root folder of the directories to scan, or path to file to
check for modifications.</td>
</tr>
<tr>
<td>property</td>
<td>No</td>
<td>Set this property if a modification has occurred. For use
in conditionally controlling the build later.</td>
</tr>
<tr>
<td>username</td>
<td>No (defaults to "User")</td>
<td>The username to use for the reported Modifications.</td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="forceonly"><forceonly></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#modificationset"><modificationset></a>
<forceonly></pre>
</div>
<p>Deprecated. Use forceonly attribute on <a href="#project"><project></a> instead.</p>
<p>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 <a href="#compound"><compound></a> with a
<a href="#filesystem"><filesystem></a> in the <triggers>
and touch the specified file to force a build).</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>property</td>
<td>No</td>
<td>Set this property if a modification has occurred. For use
in conditionally controlling the build later.</td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="git"><git></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#modificationset"><modificationset></a>
<git></pre>
</div>
<p>Checks for changes within a git repository.</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>LocalWorkingCopy</td>
<td>Yes</td>
<td>Relative or absolute path to the local working copy of the
git repository of which to find the log history.</td>
</tr>
<tr>
<td>property</td>
<td>No</td>
<td>Set this property if a modification has occurred. For use
in conditionally controlling the build later.</td>
</tr>
<tr>
<td>propertyondelete</td>
<td>No</td>
<td>Set this property if a file has been deleted. For use in
conditionally controlling the build later.</td>
</tr>
</tbody>
</table>
<h3>Properties Passed to the Builders</h3>
<p>In addition to the standard CruiseControl <a href="#buildproperties">
properties passed to builders</a>, <git> sets the
following properties:</p>
<table class="documentation">
<thead>
<tr>
<th>Property Name</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>gitcommitid</td>
<td>The commit id of the latest commit</td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="harvest"><harvest></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#modificationset"><modificationset></a>
<harvest7></pre>
</div>
<p>Triggers a build if there is a change within an AllFusion Harvest
repository.</p>
<p>In order to use this element, you must have the AllFusion Harvest
client installed on the CruiseControl machine. Additionally, the
<code>HARVESTHOME</code> environment variable should be set (this
should happen during installation of AllFusion Harvest) and you
should copy <code>jhsdk.jar</code> from your Harvest installation
into the CruiseControl <code>lib</code> directory. If you do not do
this, you will see an error indicating that the JHSDK is not installed.</p>
<p>See the <a href="http://www3.ca.com/solutions/Product.aspx?ID=255">AllFusion
Harvest product page</a> for more information.</p>
<p>This implementation has only been tested against All Fusion Harvest
version 7.0.131.</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>username</td>
<td>Yes</td>
<td>The username to connect as.</td>
</tr>
<tr>
<td>password</td>
<td>Yes</td>
<td>The password to connect with.</td>
</tr>
<tr>
<td>broker</td>
<td>Yes</td>
<td>The name of the Harvest broker to connect to.</td>
</tr>
<tr>
<td>state</td>
<td>Yes</td>
<td>The state in which you want to search for changes.</td>
</tr>
<tr>
<td>project</td>
<td>Yes</td>
<td>The name of the project in AllFusion Harvest that you want
to watch. Note that this can be different than the
CruiseControl project name.</td>
</tr>
<tr>
<td>property</td>
<td>No</td>
<td>Set this property if a modification has occurred. For use
in conditionally controlling the build later.</td>
</tr>
<tr>
<td>propertyondelete</td>
<td>No</td>
<td>Set this property if a file has been deleted. For use in
conditionally controlling the build later.</td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="httpfile"><httpfile></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#modificationset"><modificationset></a>
<httpfile></pre>
</div>
<p>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.</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>url</td>
<td>Yes</td>
<td>The HTTP URL of a file to check the modification date of</td>
</tr>
<tr>
<td>username</td>
<td>No (defaults to "User")</td>
<td>The username to use for the reported Modification.</td>
</tr>
<tr>
<td>property</td>
<td>No</td>
<td>Set this property if a modification has occurred. For use
in conditionally controlling the build later.</td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="mavensnapshotdependency"><mavensnapshotdependency></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#modificationset"><modificationset></a>
<mavensnapshotdependency></pre>
</div>
<p>Triggers a build if a Maven snapshot detects a change.</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>projectFile</td>
<td>Yes</td>
<td>Maven POM file.</td>
</tr>
<tr>
<td>user</td>
<td>Yes</td>
<td>The username to use when reporting modifications.</td>
</tr>
<tr>
<td>localRepository</td>
<td>No</td>
<td>Local Maven JAR repository. Defaults to <code>{user.home}/.maven/repository</code>.</td>
</tr>
<tr>
<td>propertiesFile</td>
<td>No</td>
<td>Sets the .properties file which contains overriding tags for POM. Default is build.properties.</td>
</tr>
<tr>
<td>property</td>
<td>No</td>
<td>
Set this property if a modification has occurred. For use in conditionally
controlling the build later.
</td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="maven2snapshotdependency"><maven2snapshotdependency></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#modificationset"><modificationset></a>
<maven2snapshotdependency></pre>
</div>
<p>Triggers a build if a Maven2 snapshot detects a change.</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>pomfile</td>
<td>Yes</td>
<td>maven2 POM file.</td>
</tr>
<tr>
<td>user</td>
<td>Yes</td>
<td>The username to use when reporting modifications.</td>
</tr>
<tr>
<td>localRepository</td>
<td>No (Not available until after maven v2.0.4+)</td>
<td>Local Maven2 JAR repository. Defaults to <code>{user.home}/.m2/repository</code>.</td>
</tr>
<tr>
<td>property</td>
<td>No</td>
<td>
Set this property if a modification has occurred. For use in conditionally
controlling the build later.
</td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="mks"><mks></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#modificationset"><modificationset></a>
<mks></pre>
</div>
<p>Triggers a build if there is a change within an MKS repository. Has the following prerequisites:</p>
<ol>
<li>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.</li>
<li>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.</li>
</ol>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>doNothing</td>
<td>No</td>
<td>If this attribute is set to true, no mks command is executed.
This is for testing purposes, if a potentially slow MKS server
connection should avoid</td>
</tr>
<tr>
<td>localworkingdir</td>
<td>Yes</td>
<td>Local directory for the sandbox.</td>
</tr>
<tr>
<td>project</td>
<td>Yes</td>
<td>The name of the MKS project file (mostly project.pj).</td>
</tr>
<tr>
<td>property</td>
<td>No</td>
<td>Set this property if a modification has occurred. For use
in conditionally controlling the build later.</td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="mercurial"><mercurial></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#modificationset"><modificationset></a>
<mercurial></pre>
</div>
<p>Triggers a build if there is a change within an Mercurial repository.</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>localworkingdir</td>
<td>Yes</td>
<td>Local directory for the sandbox.</td>
</tr>
</tbody>
</table>
<h3>Properties Passed to the Builders</h3>
<p>In addition to the standard CruiseControl <a href="#buildproperties">
properties passed to builders</a>, <mercurial> sets the
following properties:</p>
<table class="documentation">
<thead>
<tr>
<th>Property Name</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>hgrevision</td>
<td>The latest revision number</td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="p4"><p4></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#modificationset"><modificationset></a>
<p4></pre>
</div>
<p>Triggers a build if there is a change within an Perforce repository.</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>correctForServerTime</td>
<td>No</td>
<td>Should CruiseControl correct for time differences between the Perforce server and the CruiseControl server? Defaults to true.</td>
</tr>
<tr>
<td>port</td>
<td>Yes</td>
<td>Perforce Server connection to use (host:port)</td>
</tr>
<tr>
<td>client</td>
<td>Yes</td>
<td>Perforce Client name to use</td>
</tr>
<tr>
<td>user</td>
<td>Yes</td>
<td>Perforce User name to use</td>
</tr>
<tr>
<td>passwd</td>
<td>No</td>
<td>Perforce password to use</td>
</tr>
<tr>
<td>view</td>
<td>Yes</td>
<td>Valid Perforce view (i.e. a depot path)</td>
</tr>
<tr>
<td>property</td>
<td>No</td>
<td>Set this property if a modification has occurred. For use
in conditionally controlling the build later.</td>
</tr>
<tr>
<td>usep4email</td>
<td>No</td>
<td>Should the Email address for the users be retrieved from Perforce if possible. Defaults to true.</td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="plasticscm"><plasticscm></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#modificationset"><modificationset></a>
<plasticscm></pre>
</div>
<p>Checks for changes in a Plastic SCM repository.</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>wkspath</td>
<td>Yes</td>
<td>Valid Plastic SCM workspace path. </td>
</tr>
<tr>
<td>branch</td>
<td>Yes</td>
<td>The branch in which changes will be looked for.</td>
</tr>
<tr>
<td>repository</td>
<td>No</td>
<td>The repository in which changes will be looked for.</td>
</tr>
</tbody>
</table>
<h3>Examples</h3>
<ol>
<li>Used to check for changes in the branch br:/main.
<pre>
<modificationset>
<plasticscm wkpath="c:\work\cruise\plasticwks"
branch="br:/main" />
<modificationset/>
</pre>
</li>
</ol>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="pvcs"><pvcs></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#modificationset"><modificationset></a>
<pvcs></pre>
</div>
<p>Checks for changes in a PVCS repository.</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>archivefilesuffix</td>
<td>no</td>
<td>Standard suffix for archive set when the repository is created. Default value is "-arc".</td>
</tr>
<tr>
<td>loginid</td>
<td>no</td>
<td>Used to supply a user and password. Example: loginid="sampleuser:samplepassword" or loginid="sampleuser"</td>
</tr>
<tr>
<td>pvcsproject</td>
<td>Yes</td>
<td>Project name.</td>
</tr>
<tr>
<td>pvcssubproject</td>
<td>Yes</td>
<td>Subproject name.</td>
</tr>
<tr>
<td>pvcsbin</td>
<td>No</td>
<td>Path to directory with pcli.</td>
</tr>
<tr>
<td>pvcsversionlabel</td>
<td>No</td>
<td>The version label for the PVCS builder to check against. Example: pvcsVersionLabel="SampleVersionLabel"</td>
</tr>
<tr>
<td>pvcspromotiongroup</td>
<td>No</td>
<td>The promotion group for the PVCS builder to check against. Example: pvcspromotiongroup="SampleGroup"</td>
</tr>
<tr>
<td>outdateformat</td>
<td>No (defaults to "MMM dd yyyy HH:mm:ss")</td>
<td>The format to use to parse the LastModified entry as
produced by your pvcs system</td>
</tr>
<tr>
<td>indateformat</td>
<td>No (defaults to "MM/dd/yyyy hh:mm:ss aa")</td>
<td>The format used to format the lastbuild date for pvcs commands.</td>
</tr>
<tr>
<td>property</td>
<td>No</td>
<td>Set this property if a modification has occurred. For use
in conditionally controlling the build later.</td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="snapshotcm"><snapshotcm></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#modificationset"><modificationset></a>
<snapshotcm></pre>
</div>
<p>Checks for changes in a SnapshotCM repository.</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>sourcepaths</td>
<td>Yes</td>
<td>A semi-colon-separated list of source paths to check
for modifications. All paths will be checked recursively.</td>
</tr>
<tr>
<td>property</td>
<td>No</td>
<td>Property to be set if a modification has occurred. For use
in conditionally controlling the build later.</td>
</tr>
<tr>
<td>propertyondelete</td>
<td>No</td>
<td>Property to be set if a file has been deleted. For use in
conditionally controlling the build later.</td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="starteam"><starteam></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#modificationset"><modificationset></a>
<starteam></pre>
</div>
<p>Checks for changes in a Star Team repository.</p>
<p>If logged on as SERVER ADMINISTRATOR it will look up the email
associated with the user account for each modification.</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>folder</td>
<td>Yes</td>
<td>The repository folder</td>
</tr>
<tr>
<td>password</td>
<td>Yes</td>
<td>Password for the StarTeam user</td>
</tr>
<tr>
<td>starteamurl</td>
<td>Yes</td>
<td></td>
</tr>
<tr>
<td>username</td>
<td>Yes</td>
<td>StarTeam user name</td>
</tr>
<tr>
<td>preloadFileInformation</td>
<td>No (defaults to true)</td>
<td>When set to true can make the modification check much
faster.</td>
</tr>
<tr>
<td>property</td>
<td>No</td>
<td>Property to be set if a modification has occurred. For use
in conditionally controlling the build later.</td>
</tr>
<tr>
<td>propertyondelete</td>
<td>No</td>
<td>Property to be set if a file has been deleted. For use in
conditionally controlling the build later.</td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="store"><store></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#modificationset"><modificationset></a>
<store></pre>
</div>
<p>Checks for changes within a Cincom Smalltalk VisualWorks
Store repository.</p>
<p>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.</p>
<p>The latest version of the CruiseControl package is
available in the <a
href="http://www.cincomsmalltalk.com/CincomSmalltalkWiki/PostgreSQL+Access+Page">Cincom
Public Store Repository</a>.</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>workingDirectory</td>
<td>Yes</td>
<td>Relative or absolute path to the directory in
which to run the Store script.</td>
</tr>
<tr>
<td>script</td>
<td>Yes</td>
<td>The name of the script to run to access the Store repository.
The script should 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.</td>
</tr>
<tr>
<td>profile</td>
<td>Yes</td>
<td>The name of the Store connection profile for the repository
to check.</td>
</tr>
<tr>
<td>packages</td>
<td>Yes</td>
<td>A comma-separated list of package names. These packages and
their pre-requisites will be checked for modifications.</td>
</tr>
<tr>
<td>versionRegex</td>
<td>No</td>
<td>A Regex11-style regular expression. Only package versions that
match the regular expression will be considered. By default, all
package versions are considered.</td>
</tr>
<tr>
<td>minimumBlessingLevel</td>
<td>No</td>
<td>A Store blessing level string. Package versions with a lower
blessing level will not be considered. Default: Development.</td>
</tr>
<tr>
<td>parcelBuilderFile</td>
<td>No</td>
<td>Relative or absolute path to a file which will contain a list of
packages and version numbers for later use as input to a build
script. By default, no parcel builder file will be created.</td>
</tr>
<tr>
<td>property</td>
<td>No</td>
<td>Set this property if a modification has occurred. For use
in conditionally controlling the build later.</td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="surround"><surround></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#modificationset"><modificationset></a>
<surround></pre>
</div>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>branch</td>
<td>No</td>
<td>Surround SCM branch name. The default is pulled from the local working directory.</td>
</tr>
<tr>
<td>repository</td>
<td>No</td>
<td>Surround SCM repository path. The default is pulled from the local working directory.</td>
</tr>
<tr>
<td>file</td>
<td>No</td>
<td>Enter a file or repository name or a searchable pattern. Can be / or empty, which means the repository specified by the repository option or the default repository.</td>
</tr>
<tr>
<td>searchregexp</td>
<td>No</td>
<td>If set to <strong>1</strong>, the <strong>file</strong> parameter will be interpreted as a regular expression. Options are <strong>1</strong> or <strong>0</strong> (default).</td>
</tr>
<tr>
<td>recursive</td>
<td>No</td>
<td>Recursively check files and sub-repositories. Options are <strong>1</strong> or <strong>0</strong> (default).</td>
</tr>
<tr>
<td>serverconnect</td>
<td>No</td>
<td>Enter the address and port number of the Surround SCM server host computer. Format is server:port. If not entered, the last saved connection parameters are used.</td>
</tr>
<tr>
<td>serverlogin</td>
<td>No</td>
<td>Enter the username and password used to login to the Surround SCM server. Format is username:password. If not entered, the last saved login parameters are used.</td>
</tr>
<tr>
<td>property</td>
<td>No</td>
<td>Set this property if a modification has occurred. For use
in conditionally controlling the build later.</td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="svn"><svn></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#modificationset"><modificationset></a>
<svn></pre>
</div>
<p>Checks for changes within a Subversion repository.</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>LocalWorkingCopy</td>
<td rowspan="2">One of these</td>
<td>Relative or absolute path to the local working copy of the
Subversion repository of which to find the log history.</td>
</tr>
<tr>
<td>RepositoryLocation</td>
<td>The url to the Subversion repository on which to find the
log history.</td>
</tr>
<tr>
<td>username</td>
<td>No</td>
<td>used for authentication.</td>
</tr>
<tr>
<td>password</td>
<td>No</td>
<td>used for authentication.</td>
</tr>
<tr>
<td>configDir</td>
<td>No</td>
<td>Instructs Subversion to read configuration information from the specified directory instead of the default location (.subversion in the user's home directory).</td>
</tr>
<tr>
<td>property</td>
<td>No</td>
<td>Set this property if a modification has occurred. For use
in conditionally controlling the build later.</td>
</tr>
<tr>
<td>propertyondelete</td>
<td>No</td>
<td>Set this property if a file has been deleted. For use in
conditionally controlling the build later.</td>
</tr>
<tr>
<td>checkExternals</td>
<td>No</td>
<td>Whether any subversion externals this project uses should also
be checked for modifications.</td>
</tr>
<tr>
<td>useLocalRevision</td>
<td>false</td>
<td>Optionally allows the user to get the modifications made between the last build time and the localworkingcopy's revision number.</td>
</tr>
</tbody>
</table>
<h3>Properties Passed to the Builders</h3>
<p>In addition to the standard CruiseControl <a href="#buildproperties">
properties passed to builders</a>, <svn> sets the
following properties:</p>
<table class="documentation">
<thead>
<tr>
<th>Property Name</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>svnrevision</td>
<td>The repository revision number</td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="tfs"><tfs></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#modificationset"><modificationset></a>
<svn></pre>
</div>
<p>Triggers a build if there is a change within a Microsoft Visual Studio Team Foundation Server (TFS) repository.</p>
<p>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 <a href="http://www.codeplex.com/CodePlex/Wiki/View.aspx?title=Obtaining%20the%20Team%20Explorer%20Client&referringTitle=Source%20control%20clients"> CodePlex wiki</a>. <a href="http://www.teamprise.com/">Teamprise</a> 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 <a href="http://www.teamprise.com/">Teamprise</a> command line client, visit the <a href="http://www.teamprise.com/download/index.html">Teamprise download site</a> (fully functional evaluation licenses <a href="http://www.teamprise.com/download/evaluate.html">are available</a>).
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 <a href="http://kb.teamprise.com/article/view/40"> Teamprise Knowledgebase</a>. </p>
<p>Changes in TFS are detected by running a command similar to the following:</p>
<pre>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</pre>
<p>For further details regarding the tf history command, consult the <a href="http://msdn2.microsoft.com/en-us/library/yxtbh4yh(VS.80).aspx"> MSDN documentation</a>.</p>
<p>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.</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>tfPath</td>
<td>No (defaults to "tf")</td>
<td>Specify the full path to the tf command being used. If
not supplied then the plug-in will try to locate a command
called "tf" in the cruise control system path. By default,
the Microsoft client is installed into <code>C:\Program Files\Microsoft Visual Studio 8\Common7\IDE\TF.exe</code> </td>
</tr>
<tr>
<td>server</td>
<td>yes</td>
<td>URL to access the Team Foundation Server including port, for
example <code><a href="http://tfserver:8080">http://tfserver:8080</a></code></td>
</tr>
<tr>
<td><p>projectPath</p></td>
<td>yes</td>
<td>Path i<span class="style1">n the TFS repository that is
recursively checked for modifications. Any changes under
that path will trigger a build.</span></td>
</tr>
<tr>
<td>username</td>
<td>no</td>
<td>The username to use when connection to Team Foundation
Server. This user must have read permissions to the
version control repository for the projectPath. When using
the Microsoft client, if no username is passed then the user
that the CruiseControl process is running as will be used.
Note that is a username is provided then a password must be
provided in order for the credentials to be used.<br />
<br />
The username should be passed in the form <code>DOMAIN\username</code>.
From unix systems the name can be passed in the <code>username@DOMAIN</code> format if preferred as that removes confusion over escaping of
the <code>\</code> character which should not be required.</td>
</tr>
<tr>
<td>password</td>
<td>no</td>
<td>The password to use with the username when authenticating
with the server.</td>
</tr>
<tr>
<td>options</td>
<td>no</td>
<td>An optional string that may be passed as part of the command
line. The contents of the options tag are passed as an
argument to the tf history command.</td>
</tr>
</tbody>
</table>
<h3>Properties Passed to the Builders</h3>
<p>In addition to the standard CruiseControl <a href="#buildproperties"> properties passed to builders</a>, <svn> sets the
following properties:</p>
<table class="documentation">
<thead>
<tr>
<th>Property Name</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>tfschangeset</td>
<td>The maximum changeset number in the modifications detected</td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="timebuild"><timebuild></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#modificationset"><modificationset></a>
<timebuild></pre>
</div>
<p>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</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>username</td>
<td>No (defaults to "User")</td>
<td>The username to use for the single reported (fake) Modification.</td>
</tr>
<tr>
<td>time</td>
<td>Yes</td>
<td>The threshold time to cross that starts triggering a build, specified
as <code>hhmm</code> format.</td>
</tr>
<tr>
<td>property</td>
<td>No</td>
<td>Set this property if a modification has occurred. For use
in conditionally controlling the build later.</td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="ucm"><ucm></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#modificationset"><modificationset></a>
<ucm></pre>
</div>
<p>Triggers a build if there is a change within a ClearCase UCM repository.</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>stream</td>
<td>Yes</td>
<td>The ClearCase UCM stream (actually, the <i>branch</i>, so make sure to
enter the branch type if it is named differently than your UCM stream)</td>
</tr>
<tr>
<td>rebases</td>
<td>No (defaults to false)</td>
<td>Whether rebases of the integration stream are reported as changes.</td>
</tr>
<tr>
<td>pvob</td>
<td>No (unless rebases is true)</td>
<td>The name of the pvob to use for queries. Required if rebases = true</td>
</tr>
<tr>
<td>contributors</td>
<td>No (defaults to true)</td>
<td>Whether to check for and log contributor activities</td>
</tr>
<tr>
<td>viewpath</td>
<td>Yes</td>
<td>Local working copy to use when making queries</td>
</tr>
<tr>
<td>property</td>
<td>No</td>
<td>Set this property if a modification has occurred. For use
in conditionally controlling the build later.</td>
</tr>
<tr>
<td>multiVob</td>
<td>No</td>
<td>Set whether the view contains multiple vobs. Defaults to false.</td>
</tr>
</tbody>
</table>
<h3>Properties Passed to the Builders</h3>
<p>In addition to the standard CruiseControl <a href="#buildproperties">
properties passed to builders</a>, <ucm> sets the following
properties:</p>
<table class="documentation">
<thead>
<tr>
<th>Property Name</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>ucmlastbuild</td>
<td>Timestamp representing the last built time, using the format <code>dd-MMMM-yyyy.HH:mm:ss</code></td>
</tr>
<tr>
<td>ucmnow</td>
<td>Timestamp representing the time the current build started, using
the format <code>dd-MMMM-yyyy.HH:mm:ss</code></td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="veto"><veto></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#modificationset"><modificationset></a>
<veto></pre>
</div>
<p>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.</p>
<p>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.</p>
<h3>Child Elements</h3>
<table class="documentation">
<thead>
<tr>
<th>Element</th>
<th>Cardinality</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code><triggers></code></td>
<td>1</td>
<td>A container for one or more source control elements that
trigger a full check of the targets. Any child element of
<a href="#modificationset"><code><modificationset></code></a>
can be used as a child element of <code><triggers></code>.</td>
</tr>
<tr>
<td><code><a href="#buildstatus"><buildstatus></a></code></td>
<td>1</td>
<td>Points at the logs for the project that is checked to see if it is up to date with the modifications detected by the <triggers>.</td>
</tr>
</tbody>
</table>
<h3>Example</h3>
<p>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).</p>
<pre><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></pre>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="vss"><vss></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#modificationset"><modificationset></a>
<vss></pre>
</div>
<p>Checks for changes in a Visual SourceSafe repository.</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>dateformat</td>
<td>No (defaults to default is <i>MM/dd/yy</i>)</td>
<td>The date format to use for querying VSS and processing
reports. If your computer is set to a different region, you
may wish to use a format such as <i>dd/MM/yy</i>.</td>
</tr>
<tr>
<td>timeformat</td>
<td>No (default is <i>hh:mma</i>)</td>
<td>The time format to use for querying VSS and processing
reports. If your VSS is configured differently you may need a
different format such as <i>HH:mm:ss</i>.</td>
</tr>
<tr>
<td>vsspath</td>
<td>Yes</td>
<td>The VSS project to get history from.<br/>
<b>Example:</b> /Project/subproject</td>
</tr>
<tr>
<td>login</td>
<td>Yes</td>
<td>The VSS login to use, in the form
<i><code>username,password</code></i></td>
</tr>
<tr>
<td>ssdir</td>
<td>No</td>
<td>Path to the directory containing ss.exe. By default,
ss.exe is assumed to be in the path.<br/>
Note: should not contain whitespace.</td>
</tr>
<tr>
<td>serverpath</td>
<td>No</td>
<td>Path to the directory containing srcsafe.ini.</td>
</tr>
<tr>
<td>property</td>
<td>No</td>
<td>Set this property if a modification has occurred. For use
in conditionally controlling the build later.</td>
</tr>
<tr>
<td>propertyondelete</td>
<td>No</td>
<td>Set this property if a file has been deleted. For use in
conditionally controlling the build later.</td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="vssjournal"><vssjournal></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#modificationset"><modificationset></a>
<vssjournal></pre>
</div>
<p>Checks for changes in a Visual SourceSafe repository.</p>
<p>This implementation doesn't require the source safe executable making
it suitable for use on non-Windows machines.</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>journalfile</td>
<td>Yes</td>
<td>Full path to journal file. Example: <i>c:/vssdata/journal/journal.txt</i></td>
</tr>
<tr>
<td>ssdir</td>
<td>Yes</td>
<td>The VSS project to get history from</td>
</tr>
<tr>
<td>property</td>
<td>No</td>
<td>Set this property if a modification has occurred. For use
in conditionally controlling the build later.</td>
</tr>
<tr>
<td>propertyondelete</td>
<td>No</td>
<td>Set this property if a file has been deleted. For use in
conditionally controlling the build later.</td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="schedule"><schedule></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<schedule></pre>
</div>
<p>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.</p>
<p><b>Note:</b> 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 <em>in the order they appear in
the file</em>, so a multiple='1' on the first builder will hide all the
subsequent builders.</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>interval</td>
<td>No</td>
<td>Interval period in seconds. Default value is 300 (five
minutes). Maximum value is 31536000 (one year), but for the
builders that ship with CruiseControl the maximum practical
value is 604800 (one week). Minimum value is 1. Zero and
negative values are not allowed. Ignored if schedule only has time
based builders.</td>
</tr>
<tr>
<td>showProgress</td>
<td>No (defaults to true)</td>
<td>If true or omitted, the scheduled builder will provide progress messages if the builder supports this
feature and the builder's own showProgress setting is not false.
If false, no progress messages will be shown - regardless of the scheduled builder's
showProgress setting.
</td>
</tr>
</tbody>
</table>
<h3>Child Elements</h3>
<table class="documentation">
<thead>
<tr>
<th>Element</th>
<th>Cardinality</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><a href="#ant"><ant></a></td>
<td>0 .. *</td>
<td>Builds the project using Ant.</td>
</tr>
<tr>
<td><a href="#composite"><composite></a></td>
<td>0 .. *</td>
<td>Executes a list of builds.</td>
</tr>
<tr>
<td><a href="#maven"><maven></a></td>
<td>0 .. *</td>
<td>Builds the project using Maven.</td>
</tr>
<tr>
<td><a href="#maven2"><maven2></a></td>
<td>0 .. *</td>
<td>Builds the project using Maven2.</td>
</tr>
<tr>
<td><a href="#pause"><pause></a></td>
<td>0 .. *</td>
<td>Pauses the build.</td>
</tr>
<tr>
<td><a href="#nant"><nant></a></td>
<td>0 .. *</td>
<td>Builds the project using NAnt.</td>
</tr>
<tr>
<td><a href="#phing"><phing></a></td>
<td>0 .. *</td>
<td>Builds the project using Phing.</td>
</tr>
<tr>
<td><a href="#rake"><rake></a></td>
<td>0 .. *</td>
<td>Builds the project using Rake.</td>
</tr>
<tr>
<td><a href="#exec"><exec></a></td>
<td>0 .. *</td>
<td>Builds the project using the ExecBuilder.</td>
</tr>
</tbody>
</table>
<h3><a name="buildproperties">Properties Passed to Builders</a></h3>
<p>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}.</p>
<p>Here's a list of all the properties that are available to your
script:</p>
<table class="documentation">
<thead>
<tr>
<th>Property Name</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>projectname</td>
<td>The name of the CruiseControl project.</td>
</tr>
<tr>
<td>label</td>
<td>The build label determined by the labelincrementer</td>
</tr>
<tr>
<td>cvstimestamp</td>
<td>Timestamp that indicates when the build started, using the
format <code>yyyy-MM-dd HH:mm:ss 'GMT'</code> so it
can be used as a CVS argument</td>
</tr>
<tr>
<td>cctimestamp</td>
<td>Timestamp that indicates when the build started, using the
format <code>yyyyMMddHHmmss</code></td>
</tr>
<tr>
<td>cclastgoodbuildtimestamp</td>
<td>Timestamp that indicates when the last successful build was
run, using the format <code>yyyyMMddHHmmss</code></td>
</tr>
<tr>
<td>cclastbuildtimestamp</td>
<td>Timestamp that indicates when the last build was run, using
the format <code>yyyyMMddHHmmss</code></td>
</tr>
<tr>
<td>lastbuildsuccessful</td>
<td>indicates if the last build was successful; either "true"
or "false"</td>
</tr>
<tr>
<td>buildforced</td>
<td>indicates if the build was forced; either "true" or "false"</td>
</tr>
</tbody>
</table>
<p>Some child elements of <a href="#modificationset"><modificationset></a>
also set properties for the builders. In particular:</p>
<ul>
<li><a href="#buildstatus"><buildstatus></a> sets specific
properties.</li>
<li><a href="#clearcase"><clearcase></a> sets specific
properties.</li>
<li>If specified, the <code>property</code> or
<code>propertyondelete</code> attribute value will be set. This
feature is supported by <a href="#clearcase"><clearcase></a>,
<a href="#cvs"><cvs></a>,
<a href="#filesystem"><filesystem></a>,
<a href="#mavensnapshotdependency"><mavensnapshotdependency></a>,
<a href="#maven2snapshotdependency"><maven2snapshotdependency></a>,
<a href="#mks"><mks></a>,
<a href="#snapshotcm"><snapshotcm></a>,
<a href="#starteam"><starteam></a>,
<a href="#vss"><vss></a> and
<a href="#vssjournal"><vssjournal></a>.</li>
</ul>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="ant"><ant></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#schedule"><schedule></a>
<ant></pre>
</div>
<p>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.</p>
<p>When a build runs, Ant is invoked in a separate Java process. There
are two alternative ways in which ant may be invoked:</p>
<ol>
<li>Using the <b><code>antscript</code></b>, or <b><code>anthome</code></b>, 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.</li>
<li>Using the ant binaries distributed with CruiseControl. Settings
for the virtual machine can be specified using the nested <code>
<jvmarg></code> element. This also requires that java be on
the executable path.</li>
</ol>
<p>The standard CruiseControl <a href="#buildproperties">properties
passed to builders</a> are available from within the ant build.</p>
<p>See below for <a href="#ant-examples">examples</a> of the
<code><ant></code> element.</p>
<h3><a name="ant-attributes">Attributes</a></h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>buildfile</td>
<td>No (defaults to build.xml)</td>
<td>Path to Ant build file.</td>
</tr>
<tr>
<td>target</td>
<td>No</td>
<td>Ant target(s) to run. Default is "", or the default target
for the build file.</td>
</tr>
<tr>
<td>multiple</td>
<td>No</td>
<td>Build index used to run different builders. For example,
if this is set to 3, the builder will be run every 3 builds.
Default value is 1. Can't be set if time is set.</td>
</tr>
<tr>
<td>time</td>
<td>No</td>
<td>Time in the form HHmm. Can't be set if multiple is set.</td>
</tr>
<tr>
<td>day</td>
<td>No</td>
<td>Valid values are (case-insensitive) the English names for
the days of the week (Sunday, Monday, Tuesday, etc). Does not
support multiple days except for the default of every day.</td>
</tr>
<tr>
<td>tempfile</td>
<td>No</td>
<td>Name of temp file. Defaults to log.xml</td>
</tr>
<tr>
<td>antscript</td>
<td>No, but recommended. Cannot be specified if <code>anthome</code> attribute is also specified</td>
<td>Absolute filename of script (shell script or bat file) used
to start Ant. You can use this to make CruiseControl use your own
Ant installation. If this is not specified, the AntBuilder uses
the Ant distribution that ships with CruiseControl. See below
for <a href="#ant-examples">examples</a>.</td>
</tr>
<tr>
<td>anthome</td>
<td>No. Cannot be specified if <code>antscript</code> attribute is also specified.</td>
<td>Directory in which Ant is installed. CruiseControl will attempt to use the standard
Ant execution scripts (i.e. ant.bat or ant). See below
for <a href="#ant-examples">examples</a>.</td>
</tr>
<tr>
<td>antWorkingDir</td>
<td>No</td>
<td>Will invoke ant in the specified directory.</td>
</tr>
<tr>
<td>saveLogDir</td>
<td>No</td>
<td>If supplied a copy of the ant log will be saved in the specified directory. Example:
saveLogDir="/usr/local/dev/projects/cc/logs"</td>
</tr>
<tr>
<td>timeout</td>
<td>No</td>
<td>Ant build will be halted if it continues longer than the
specified timeout. Value in seconds.</td>
</tr>
<tr>
<td>uselogger</td>
<td>No</td>
<td>'true' if CruiseControl should call Ant using -logger;
'false' to call Ant using '-listener', thus using the
loggerclass as a Listener. uselogger="true" will make Ant
log its messages using the class specified by loggerclassname
as an Ant Logger, which can make for smaller log files since
it doesn't log DEBUG messages (see useDebug and useQuiet
attributes below, and the
<a href="http://ant.apache.org/manual/listeners.html">Ant manual</a>).
Set to false to have Ant echo ant messages to console using its
DefaultLogger, which is useful when debugging your ant build.
Defaults to 'false' to make initial setup easier but setting it to
'true' is recommended for production situations.</td>
</tr>
<tr>
<td>loggerclassname</td>
<td>No (defaults to org.apache.tools.ant.XmlLogger)</td>
<td>If you want to use another logger (or listener, when
uselogger="false") than Ant's XmlLogger,
you can specify the classname of the logger here. The logger
needs to output compatible XML, and the class needs to be
available on the classpath at buildtime.</td>
</tr>
<tr>
<td>usedebug</td>
<td>No</td>
<td>If true will invoke ant with -debug, which can be
useful for debugging your ant build. Defaults to 'false',
cannot be set to 'true' if usequiet is also set to 'true'.
When used in combination with uselogger="true", this will
result in bigger XML log files; otherwise, it will cause
more output to be written to the console by Ant's
DefaultLogger.</td>
</tr>
<tr>
<td>usequiet</td>
<td>No</td>
<td>If true will invoke ant with -quiet, which can be
useful for creating smaller log files since messages with
a priority of INFO will not be logged. Defaults to 'false',
cannot be set to 'true' if usedebug is also set to 'true'.
Smaller logfiles are only achieved when used in combination
with uselogger="true", otherwise there will just be less
output echoed to the console by Ant's DefaultLogger.</td>
</tr>
<tr>
<td>keepgoing</td>
<td>No</td>
<td>If true will invoke ant with -keep-going, which can be
useful for performing build steps after an optional step
fails. Defaults to 'false'.</td>
</tr>
<tr>
<td>propertyfile</td>
<td>No</td>
<td>Load all properties from file with -D properties
(like child <code><a href="#antbuilderchildprop"><property></a></code> elements)
taking precedence. Useful when the propertyfile content can change for every build.</td>
</tr>
<tr>
<td>progressLoggerLib</td>
<td>No</td>
<td>Overrides the default -lib search path used to add support for showProgress features
in the ant builder. This search path ensures customized ant Loggers/Listeners
are available on the classpath of the ant builder VM. You should not normally
set this value. If you do set this value, you should use the full path (including filename)
to cruisecontrol-antprogresslogger.jar. This setting has no effect if showProgress=false.
</td>
</tr>
<tr>
<td>showProgress</td>
<td>No (defaults to true)</td>
<td>If true or omitted, this builder will provide progress messages.
If false, no progress messages will be shown. If any parent showProgress is false,
then no progress will be shown, regardless of this builder's settings.<br/>
NOTE: In order to show progress, the AntBuilder uses custom Build Loggers and Listeners.
If these interfere with your Ant build, set showProgress=false (and please report the problem).
</td>
</tr>
<tr>
<td>showAntOutput</td>
<td>No (defaults to true)</td>
<td>If true AND uselogger=true, this builder will write the ant output to a file (antBuilderOutput.log)
that can be read by the Dashboard reporting application. This setting has no effect if uselogger=false.
<a href="#antbootstrapper">AntBootstrapper</a> and <a href="#antpublisher">AntPublisher</a> do not
provide access to showAntOutput, and operate as if showAntOutput=false.<br/>
NOTE: In order to show ant output while uselogger=true, the AntBuilder uses a custom Build Listener.
If this interferes with your Ant build, set showAntOutput=false (and please report the problem).
</td>
</tr>
</tbody>
</table>
<h3><a name="ant-elements">Child Elements</a></h3>
<table class="documentation">
<thead>
<tr>
<th>Element</th>
<th>Cardinality</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><jvmarg></td>
<td>0 .. *</td>
<td>Pass specified argument to the jvm used to invoke ant.
Ignored if using anthome or antscript. The element has a single required
attribute: "arg".<br/>
<b>Example:</b> <code><jvmarg arg="-Xmx120m"/></code></td>
</tr>
<tr>
<td><a name="antbuilderchildprop"><property></a> </td>
<td>0 .. *</td>
<td>Used to define properties for the ant build. The element
has two required attributes: "name" and "value". These will
be passed on the ant command-line as "-Dname=value"<br/>
<b>Example:</b> <code><property name="foo" value="bar"/></code></td>
</tr>
<tr>
<td><lib></td>
<td>0 .. *</td>
<td>Used to define additional <a href="http://ant.apache.org/manual/running.html#libs">library directories</a> for the ant build. The element
has one required attribute: "searchPath".<br/>
<b>Example:</b> <code><lib searchPath="/home/me/myantextensions"/></code></td>
</tr>
<tr>
<td><listener></td>
<td>0 .. *</td>
<td>Used to define additional <a href="http://ant.apache.org/manual/listeners.html">listeners</a> for the ant build. The element
has one required attribute: "classname".<br/>
<b>Example:</b> <code><listener classname="org.apache.tools.ant.listener.Log4jListener"/></code></td>
</tr>
</tbody>
</table>
<h3><a name="ant-examples">Examples</a></h3>
<ol>
<li>Invoke the ant.bat script distributed with ant using the <code>antscript</code> attribute,
specifying the working directory as <code>D:\workspace\MyProject</code> and the
ant build file as <code>MyProject-nightlybuild.xml</code> using the default target.
<pre><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></pre>
Or equivalently, using the <code>anthome</code> attribute
<pre><schedule>
<ant anthome="C:\Java\apache-ant-1.6.1"
antworkingdir="D:\workspace\MyProject"
buildfile="MyProject-nightlybuild.xml"
uselogger="true"
usedebug="false"/>
<schedule></pre>
</li>
<li>Invoke a custom ant script <code>/home/cc/workspace/build.sh</code>,
specifying the working directory as <code>/home/cc/workspace</code>
and the ant target as <code>smoketest</code>.
<pre><schedule>
<ant antscript="/home/cc/workspace/build.sh"
antworkingdir="/home/cc/workspace"
target="smoketest"
uselogger="true"/>
<schedule></pre>
<p>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:</p>
<pre>#!/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" "$@"</pre>
<p>Note the double quotes around $@: this ensures that all arguments
will be quoted, which is necessary for arguments containing spaces.</p>
<p>An example of a Windows batch file to invoke ant:</p>
<pre>@echo off
setlocal
set PROJECT_HOME=%~dp0
call %PROJECT_HOME%..\devtools\env.bat
call ant.bat %*
endlocal</pre>
<p>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.</p>
</li>
</ol>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="maven"><maven></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#schedule"><schedule></a>
<maven></pre>
</div>
<p>Specify a <a href="http://maven.apache.org">Maven</a> 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.</p>
<p>The <code>goal</code> attribute has the following usage examples:</p>
<ul>
<li>"clean" will run 'clean' goal on the project</li>
<li>"clean java:compile" will run 'clean' goal then 'java:compile'
goal on the project, within the <b>same</b> Maven session run</li>
<li>"clean my-cvs-update|java:compile" will run 'clean' goal then
'my-cvs-update' goal on the project, within the <b>same</b> Maven
session run, then it will run Maven <b>again</b> 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 '|'.
</li>
</ul>
<p>The standard CruiseControl <a href="#buildproperties">properties
passed to builders</a> are available from within the maven build.</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>mavenscript</td>
<td>Yes</td>
<td>Absolute filename of maven startup script (maven.bat or
maven.sh).</td>
</tr>
<tr>
<td>projectfile</td>
<td>Yes</td>
<td>Path to Maven's "project.xml" file</td>
</tr>
<tr>
<td>goal</td>
<td>Yes</td>
<td>Maven goal, "set of goals" or "set of set of goals" to run.
(see above Note2)</td>
</tr>
<tr>
<td>multiple</td>
<td>No</td>
<td>Build index used to run different builders. For example,
if this is set to 3, the builder will be run every 3 builds.
Default value is 1. Can't be set if time is set.</td>
</tr>
<tr>
<td>time</td>
<td>No</td>
<td>Time in the form HHmm. Can't be set if multiple is set.</td>
</tr>
<tr>
<td>day</td>
<td>No</td>
<td>Valid values are (case-insensitive) the English names for
the days of the week (Sunday, Monday, Tuesday, etc). Does not
support multiple days except for the default of every day.</td>
</tr>
<tr>
<td>timeout</td>
<td>No</td>
<td>Build will be halted if it continues longer than the specified timeout. Value in seconds.</td>
</tr>
<tr>
<td>showProgress</td>
<td>No (defaults to true)</td>
<td>If true or omitted, this builder will provide progress messages.
If false, no progress messages will be shown. If any parent showProgress is false,
then no progress will be shown, regardless of this builder's settings.
</td>
</tr>
</tbody>
</table>
<h2><a name="maven2"><maven2></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#schedule"><schedule></a>
<maven2></pre>
</div>
<p>Specify a <a href="http://maven.apache.org">Maven2</a> 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.</p>
<p>The <code>goal</code> attribute has the following usage examples:</p>
<ul>
<li>"clean" will run 'clean' goal on the project</li>
</ul>
<a name="maven2-goal-note">Goals</a>
<ul>
<li>"clean compile" will run 'clean' goal then 'compile'
goal on the project, within the <b>same</b> Maven2 session run</li>
</ul>
<a name="maven2-session-note">Sessions</a>
<ul>
<li>"clean scm:update|deploy" will run 'clean' goal then
'scm:update' goal on the project, within the <b>same</b> Maven
session run, then it will run Maven <b>again</b> 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 '|'.
</li>
</ul>
<p>The standard CruiseControl <a href="#buildproperties">properties
passed to builders</a> are available from within the maven build, with one exception: The
"cvstimestamp" property contains spaces in its value, like:
<code>-Dcvstimestamp=2006-11-29 03:41:04 GMT</code>. To avoid problems when maven2 parses
this property from the command line, spaces in build property values will be replaced
with underscores, like: <code>-Dcvstimestamp=2006-11-29_03:41:04_GMT</code>.</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>mvnscript</td>
<td rowspan="2">One of these</td>
<td>Path to maven startup script (.../bin/mvn.bat or mvn.sh).</td>
</tr>
<tr>
<td>mvnhome</td>
<td>Path to Maven2's home directory (M2_HOME). Maven script will be found
by appending "/bin/mvn" (or "/bin/mvn.bat") to this directory.</td>
</tr>
<tr>
<td>pomfile</td>
<td>Yes</td>
<td>Path to Maven2's "pom.xml" file</td>
</tr>
<tr>
<td>goal</td>
<td>Yes</td>
<td>Maven2 goal, "set of goals" or "set of set of goals" to run.
(see <a href="#maven2-goal-note">Goals</a> note above)</td>
</tr>
<tr>
<td>settingsfile</td>
<td>No</td>
<td>Alternate path for the user settings file.</td>
</tr>
<tr>
<td>activateprofiles</td>
<td>No</td>
<td>Comma-delimited list of profiles to activate.</td>
</tr>
<tr>
<td>flags</td>
<td>No</td>
<td>Command line flags to be passed to maven. For example:
'-U -Dmaven.test.skip=true'. The flags will be passed to each session
invocation (see <a href="#maven2-session-note">Sessions</a> note above).</td>
</tr>
<tr>
<td>multiple</td>
<td>No</td>
<td>Build index used to run different builders. For example,
if this is set to 3, the builder will be run every 3 builds.
Default value is 1. Can't be set if time is set.</td>
</tr>
<tr>
<td>time</td>
<td>No</td>
<td>Time in the form HHmm. Can't be set if multiple is set.</td>
</tr>
<tr>
<td>day</td>
<td>No</td>
<td>Valid values are (case-insensitive) the English names for
the days of the week (Sunday, Monday, Tuesday, etc). Does not
support multiple days except for the default of every day.</td>
</tr>
<tr>
<td>timeout</td>
<td>No</td>
<td>Build will be halted if it continues longer than the specified timeout. Value in seconds.</td>
</tr>
<tr>
<td>showProgress</td>
<td>No (defaults to true)</td>
<td>If true or omitted, this builder will provide progress messages.
If false, no progress messages will be shown. If any parent showProgress is false,
then no progress will be shown, regardless of this builder's settings.
</td>
</tr>
</tbody>
</table>
<h3><a name="maven2-elements">Child Elements</a></h3>
<table class="documentation">
<thead>
<tr>
<th>Element</th>
<th>Cardinality</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><property></td>
<td>0 .. *</td>
<td>Used to define properties for the maven2 build. The element
has two required attributes: "name" and "value". These will
be passed on the maven2 command-line as "-Dname=value" to each session
invocation (see <a href="#maven2-session-note">Sessions </a> note above).<br/>
<b>Example:</b> <code><property name="foo" value="bar"/></code></td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="composite"><composite></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#schedule"><schedule></a>
<composite></pre>
</div>
<p>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) </p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>multiple</td>
<td>No</td>
<td>Build index used to run different builders. For example,
if this is set to 3, the builder will be run every 3 builds.
Default value is 1. Can't be set if time is set.</td>
</tr>
<tr>
<td>time</td>
<td>No</td>
<td>Time in the form HHmm. Can't be set if multiple is set.</td>
</tr>
<tr>
<td>day</td>
<td>No</td>
<td>Valid values are (case-insensitive) the English names for
the days of the week (Sunday, Monday, Tuesday, etc). Does not
support multiple days except for the default of every day.</td>
</tr>
<tr>
<td>timeout</td>
<td>No</td>
<td>Composite Build will be halted if it continues longer than the specified timeout. Value in seconds.</td>
</tr>
<tr>
<td>showProgress</td>
<td>No (defaults to true)</td>
<td>If true or omitted, the composite builder will provide progress messages, as will any child builders that support this
feature (assuming the child builder's own showProgress setting is true).
If false, no progress messages will be shown by the composite builder or child builders - regardless of child builder
showProgress settings. If any parent showProgress is false, then no progress will be shown, regardless
of the composite or child builder settings.
</td>
</tr>
</tbody>
</table>
<h3>Child Elements</h3>
<table class="documentation">
<thead>
<tr>
<th>Element</th>
<th>Cardinality</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><a href="#ant"><ant></a></td>
<td>0 .. *</td>
<td>Builds the project using Ant.</td>
</tr>
<tr>
<td><a href="#maven"><maven></a></td>
<td>0 .. *</td>
<td>Builds the project using Maven.</td>
</tr>
<tr>
<td><a href="#maven2"><maven2></a></td>
<td>0 .. *</td>
<td>Builds the project using Maven2.</td>
</tr>
<tr>
<td><a href="#pause"><pause></a></td>
<td>0 .. *</td>
<td>Pauses the build.</td>
</tr>
<tr>
<td><a href="#nant"><nant></a></td>
<td>0 .. *</td>
<td>Builds the project using NAnt.</td>
</tr>
<tr>
<td><a href="#phing"><phing></a></td>
<td>0 .. *</td>
<td>Builds the project using Phing.</td>
</tr>
<tr>
<td><a href="#rake"><rake></a></td>
<td>0 .. *</td>
<td>Builds the project using Rake.</td>
</tr>
<tr>
<td><a href="#exec"><exec></a></td>
<td>0 .. *</td>
<td>Builds the project using the ExecBuilder.</td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="pause"><pause></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#schedule"><schedule></a>
<pause></pre>
</div>
<p>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.</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>day</td>
<td>No</td>
<td>Day when the pause should take place (Sunday, Monday, etc).
Does not support multiple days except for the default of every
day.</td>
</tr>
<tr>
<td>starttime</td>
<td>Yes</td>
<td>Start of the pause in HHmm format</td>
</tr>
<tr>
<td>endtime</td>
<td>Yes</td>
<td>End of the pause in HHmm format</td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="nant"><nant></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#schedule"><schedule></a>
<nant></pre>
</div>
<p>Specifies a <a href="http://nant.sourceforge.net/">NAnt</a> 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.</p>
<p>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. </p>
<p>The standard CruiseControl <a href="#buildproperties">properties
passed to builders</a> are available from within the NAnt build.</p>
<p>See below for <a href="#nant-examples">examples</a> of the
<code><nant></code> element.</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>buildfile</td>
<td>No (defaults to default.build)</td>
<td>Path to NAnt build file.</td>
</tr>
<tr>
<td>target</td>
<td>No</td>
<td>NAnt target(s) to run. Default is "", or the default target
for the build file.</td>
</tr>
<tr>
<td>multiple</td>
<td>No</td>
<td>Build index used to run different builders. For example,
if this is set to 3, the builder will be run every 3 builds.
Default value is 1. Can't be set if time is set.</td>
</tr>
<tr>
<td>time</td>
<td>No</td>
<td>Time in the form HHmm. Can't be set if multiple is set.</td>
</tr>
<tr>
<td>day</td>
<td>No</td>
<td>Valid values are (case-insensitive) the English names for
the days of the week (Sunday, Monday, Tuesday, etc). Does not
support multiple days except for the default of every day.</td>
</tr>
<tr>
<td>tempfile</td>
<td>No</td>
<td>Name of temp file. Defaults to log.xml</td>
</tr>
<tr>
<td>targetFramework</td>
<td>No, but recommended</td>
<td>Specifies the framework to target. Typical values are
"net-1.1" and "mono-1.0".</td>
</tr>
<tr>
<td>nantWorkingDir</td>
<td>No</td>
<td>Will invoke NAnt in the specified directory.</td>
</tr>
<tr>
<td>timeout</td>
<td>No</td>
<td>NAnt build will be halted if it continues longer than the
specified timeout. Value in seconds.</td>
</tr>
<tr>
<td>uselogger</td>
<td>No</td>
<td>'true' if CruiseControl should call NAnt using -logger;
'false' to call NAnt without '-logger', thus using the
loggerclass as a Listener. uselogger="true" will make NAnt
log its messages using the class specified by loggerclassname
as a NAnt Logger, which can make for smaller log files since
it doesn't log DEBUG messages (see useDebug and useQuiet
attributes below, and the
<a href="http://nant.sourceforge.net/release/0.85-rc1/help/fundamentals/listeners.html">
NAnt documentation</a>).
Listener will echo NAnt messages to console which is
useful when debugging your NAnt build. Defaults to 'false'
for historical reasons, but setting it to 'true' is recommended
for production situations.</td>
</tr>
<tr>
<td>loggerclassname</td>
<td>No (defaults to NAnt.Core.XmlLogger)</td>
<td>If you want to use another logger than NAnt's XmlLogger,
you can specify the classname of the logger here. The logger
needs to output compatible XML, and the class needs to be
available on the classpath at buildtime.</td>
</tr>
<tr>
<td>usedebug</td>
<td>No</td>
<td>If true will invoke NAnt with -debug, which can be
useful for debugging your NAnt build. Defaults to 'false',
cannot be set to 'true' if usequiet is also set to 'true'.
Is only effective when used in combination with uselogger="true"!</td>
</tr>
<tr>
<td>usequiet</td>
<td>No</td>
<td>If true will invoke NAnt with -quiet, which can be
useful for creating smaller log files since messages with
a priority of INFO will not be logged. Defaults to 'false',
cannot be set to 'true' if usedebug is also set to 'true'.
Is only effective when used in combination with uselogger="true"!</td>
</tr>
</tbody>
</table>
<h3>Child Elements</h3>
<table class="documentation">
<thead>
<tr>
<th>Element</th>
<th>Cardinality</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><property></td>
<td>0 .. *</td>
<td>Used to define properties for the NAnt build. The element
has two required attributes: "name" and "value". These will
be passed on the NAnt command-line as "-D:name=value"<br/>
<b>Example:</b> <code><property name="foo" value="bar"/></code></td>
</tr>
</tbody>
</table>
<h3><a name="nant-examples">Examples</a></h3>
<ol>
<li>Invoke NAnt, specifying the
working directory as <code>D:\workspace\MyProject</code> and the
NAnt build file as <code>MyProject-nightly.build</code> using the default target.
<pre><schedule>
<nant nantworkingdir="D:\workspace\MyProject"
buildfile="MyProject-nightly.build"
uselogger="true"
usedebug="false"/>
<schedule></pre>
</li>
<li>Invoke NAnt, specifying the working directory as <code>/home/cc/workspace</code>,
the build file as <code>default.build</code>, the nant target as <code>smoketest</code>,
and the targetframework as .NET version 1.1.
<pre><schedule>
<nant targetframework="net-1.1"
nantworkingdir="/home/cc/workspace"
target="smoketest"
uselogger="true"/>
<schedule></pre>
</li>
</ol>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="phing"><phing></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#schedule"><schedule></a>
<phing></pre>
</div>
<p>Specifies a <a href="http://phing.info">Phing</a> 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.</p>
<p>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.</p>
<p>The standard CruiseControl <a href="#buildproperties">properties
passed to builders</a> are available from within the Phing build.</p>
<p>See below for <a href="#phing-examples">examples</a> of the
<code><phing></code> element.</p>
<h3><a name="phing-attributes">Attributes</a></h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>buildfile</td>
<td>No (defaults to build.xml)</td>
<td>Path to Phing build file.</td>
</tr>
<tr>
<td>target</td>
<td>No</td>
<td>Phing target(s) to run. Default is "", or the default target
for the build file.</td>
</tr>
<tr>
<td>multiple</td>
<td>No</td>
<td>Build index used to run different builders. For example,
if this is set to 3, the builder will be run every 3 builds.
Default value is 1. Can't be set if time is set.</td>
</tr>
<tr>
<td>time</td>
<td>No</td>
<td>Time in the form HHmm. Can't be set if multiple is set.</td>
</tr>
<tr>
<td>day</td>
<td>No</td>
<td>Valid values are (case-insensitive) the English names for
the days of the week (Sunday, Monday, Tuesday, etc). Does not
support multiple days except for the default of every day.</td>
</tr>
<tr>
<td>tempfile</td>
<td>No</td>
<td>Name of temp file. Defaults to log.xml</td>
</tr>
<tr>
<td>phingscript</td>
<td>No. Cannot be specified if <code>phinghome</code> attribute is also specified</td>
<td>Absolute filename of script (shell script or bat file) used
to start Phing. If this is not specified, the PhingBuilder assumes that phing (or phing.bat)
is installed on your path.</td>
</tr>
<tr>
<td>phinghome</td>
<td>No. Cannot be specified if <code>phingscript</code> attribute is also specified.</td>
<td>Directory in which Phing is installed. CruiseControl will attempt to use the standard
Phing execution scripts (i.e. phing.bat or phing). See below for <a href="#phing-examples">examples</a>.</td>
</tr>
<tr>
<td>phingWorkingDir</td>
<td>No</td>
<td>Will invoke phing in the specified directory.</td>
</tr>
<tr>
<td>saveLogDir</td>
<td>No</td>
<td>If supplied a copy of the phing log will be saved in the specified directory. Example:
saveLogDir="/usr/local/dev/projects/cc/logs"</td>
</tr>
<tr>
<td>timeout</td>
<td>No</td>
<td>Phing build will be halted if it continues longer than the
specified timeout. Value in seconds.</td>
</tr>
<tr>
<td>uselogger</td>
<td>No</td>
<td>'true' if CruiseControl should call Phing using -logger; 'false' to call Phing using '-listener',
thus using the loggerclass as a Listener. uselogger="true" will make Phing log its messages using the
class specified by loggerclassname as a Phing Logger, which can make for smaller log files since it
doesn't log DEBUG messages (see useDebug and useQuiet attributes below, and the Phing manual). Set to false
to have Phing echo messages to console using its DefaultLogger, which is useful when debugging your Phing
build. Defaults to 'false' to make initial setup easier but setting it to 'true' is recommended for
production situations.</td>
</tr>
<tr>
<td>loggerclassname</td>
<td>No (defaults to phing.listener.XmlLogger)</td>
<td>If you want to use another logger (or listener, when uselogger="false") than Phing's XmlLogger,
you can specify the classname of the logger here. The logger needs to output compatible XML, and
the class needs to be available on the classpath at buildtime.</td>
</tr>
<tr>
<td>usedebug</td>
<td>No</td>
<td>If true will invoke phing with -debug, which can be
useful for debugging your phing build. Defaults to 'false',
cannot be set to 'true' if usequiet is also set to 'true'.
When used in combination with uselogger="true", this will
result in bigger XML log files; otherwise, it will cause
more output to be written to the console by Phing's
DefaultLogger.</td>
</tr>
<tr>
<td>usequiet</td>
<td>No</td>
<td>If true will invoke phing with -quiet, which can be
useful for creating smaller log files since messages with
a priority of INFO will not be logged. Defaults to 'false',
cannot be set to 'true' if usedebug is also set to 'true'.
Smaller logfiles are only achieved when used in combination
with uselogger="true", otherwise there will just be less
output echoed to the console by Phing's DefaultLogger.</td>
</tr>
</tbody>
</table>
<h3><a name="phing-elements">Child Elements</a></h3>
<table class="documentation">
<thead>
<tr>
<th>Element</th>
<th>Cardinality</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><property></td>
<td>0 .. *</td>
<td>Used to define properties for the phing build. The element
has two required attributes: "name" and "value". These will
be passed on the phing command-line as "-Dname=value"<br/>
<b>Example:</b> <code><property name="foo" value="bar"/></code></td>
</tr>
</tbody>
</table>
<h3><a name="phing-examples">Examples</a></h3>
<ol>
<li>Invoke the phing.bat script distributed with phing using the <code>phingscript</code> attribute,
specifying the working directory as <code>D:\workspace\MyProject</code> and the
phing build file as <code>MyProject-nightlybuild.xml</code> using the default target.
<pre><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></pre>
Or equivalently, using the <code>phinghome</code> attribute
<pre><schedule>
<phing phinghome="C:\PHP\applications\phing-2.3.0\bin\"
phingworkingdir="D:\workspace\MyProject"
buildfile="MyProject-nightlybuild.xml"
uselogger="true"
usedebug="false"/>
<schedule></pre>
</li>
</ol>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="rake"><rake></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#schedule"><schedule></a>
<rake></pre>
</div>
<p>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.</p>
<p>When a build runs, Rake is invoked in a separate Java process.</p>
<h3><a name="rake-attributes">Attributes</a></h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>buildfile</td>
<td>No (defaults to rakefile.rb)</td>
<td>Path to Rake build file. If the rakefile is not found in the current directory,
rake will search parent directories for a match. The directory where the
Rakefile is found will become the current directory for the actions executed
in the Rakefile</td>
</tr>
<tr>
<td>target</td>
<td>No</td>
<td>Rake target(s) to run. Default is "", or the default target
for the rake file.</td>
</tr>
<tr>
<td>multiple</td>
<td>No</td>
<td>Build index used to run different builders. For example,
if this is set to 3, the builder will be run every 3 builds.
Default value is 1. Can't be set if time is set.</td>
</tr>
<tr>
<td>time</td>
<td>No</td>
<td>Time in the form HHmm. Can't be set if multiple is set.</td>
</tr>
<tr>
<td>day</td>
<td>No</td>
<td>Valid values are (case-insensitive) the English names for
the days of the week (Sunday, Monday, Tuesday, etc). Does not
support multiple days except for the default of every day.</td>
</tr>
<tr>
<td>workingDir</td>
<td>No</td>
<td>Will invoke rake in the specified directory. The directory can
be relative (to the cruisecontrol current working directory) or absolute.</td>
</tr>
<tr>
<td>timeout</td>
<td>No</td>
<td>Rake build will be halted if it continues longer than the
specified timeout. Value in seconds.</td>
</tr>
<tr>
<td>showProgress</td>
<td>No (defaults to true)</td>
<td>If true or omitted, this builder will provide progress messages.
If false, no progress messages will be shown. If any parent showProgress is false,
then no progress will be shown, regardless of this builder's settings.
</td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="exec"><exec></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#schedule"><schedule></a>
<exec></pre>
</div>
<p>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 <a href="#buildproperties">
properties passed to builders</a> substitued at runtime.</p>
<p>See below for <a href="#exec-examples">examples</a> of the
<code><exec></code> element.</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>command</td>
<td>Yes</td>
<td>The command or script to be executed.</td>
</tr>
<tr>
<td>args</td>
<td>No</td>
<td>Set of arguments (as a single string) to be passed to the command or script.</td>
</tr>
<tr>
<td>workingdir</td>
<td>No</td>
<td>The directory in which the script or command is to be
executed. Defaults to the Java temporary directory.</td>
</tr>
<tr>
<td>errorstr</td>
<td>No</td>
<td>String which is to be searched for in the output of the
command or script. If it is found then the build will return
an error.</td>
</tr>
<tr>
<td>multiple</td>
<td>No</td>
<td>Build index used to run different builders. For example,
if this is set to 3, the builder will be run every 3 builds.
Default value is 1. Can't be set if time is set.</td>
</tr>
<tr>
<td>time</td>
<td>No</td>
<td>Time in the form HHmm. Can't be set if multiple is set.</td>
</tr>
<tr>
<td>day</td>
<td>No</td>
<td>Valid values are (case-insensitive) the English names for
the days of the week (Sunday, Monday, Tuesday, etc). Does not
support multiple days except for the default of every day.</td>
</tr>
<tr>
<td>timeout</td>
<td>No</td>
<td>Build will be halted if the script or command continues longer
than the specified timeout. Value in seconds.</td>
</tr>
<tr>
<td>showProgress</td>
<td>No (defaults to true)</td>
<td>If true or omitted, this builder will provide progress messages.
If false, no progress messages will be shown. If any parent showProgress is false,
then no progress will be shown, regardless of this builder's settings.
</td>
</tr>
</tbody>
</table>
<h3><a name="exec-examples">Examples</a></h3>
<ol>
<li>Invoke execbuilder, specifying the
working directory as <code>/workspace/myproject</code> using property substitution and
executing the Perl script <code>backup.pl</code>.
<pre><schedule>
<exec workingdir="/workspace/${projectname}"
command="/usr/local/bin/Perl"
args="backup.pl"/>
</schedule></pre>
</li>
<li>Invoke execbuilder, specifying the working directory as <code>D:\Workspace\MyProject</code>,
the script file as <code>build.bat</code>, its arguments as <code>smoketest</code>,
and the error message to be search for as <code>build failed</code>.
<pre><schedule>
<exec command="build.bat"
workingdir="D:\Workspace\MyProject"
args="smoketest"
errorstr="build failed"/>
</schedule></pre>
</li>
</ol>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="log"><log></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<log></pre>
</div>
<p>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.</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>dir</td>
<td>No</td>
<td>The cruisecontrol log directory. Default is "logs/[projectname]".</td>
</tr>
<tr>
<td>encoding</td>
<td>No</td>
<td>Encoding for CruiseControl's XML log file.</td>
</tr>
</tbody>
</table>
<h3>Child Elements</h3>
<table class="documentation">
<thead>
<tr>
<th>Element</th>
<th>Cardinality</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><a href="#merge"><code><merge></code></a></td>
<td>0 .. *</td>
<td>Merges log file together.</td>
</tr>
<tr>
<td><a href="#gzip"><code><gzip></code></a></td>
<td>0 .. 1</td>
<td>GZips old log files</td>
</tr>
<tr>
<td><a href="#delete"><code><delete></code></a></td>
<td>0 .. 1</td>
<td>Deletes old log files.</td>
</tr>
<tr>
<td><a href="#deleteartifacts"><code><deleteartifacts></code></a></td>
<td>0 .. 1</td>
<td>Deletes old artifact directories.</td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="merge"><merge></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#log"><log></a>
<merge></pre>
</div>
<p>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.</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>file</td>
<td rowspan="2">One of file or dir.</td>
<td>path to file to merge into build log</td>
</tr>
<tr>
<td>dir</td>
<td>all files matching the specified pattern will be merged into the build log.</td>
</tr>
<tr>
<td>removeproperties</td>
<td>No (defaults to true)</td>
<td>when merging a JUnit xml file should the properties section be removed.</td>
</tr>
<tr>
<td>pattern</td>
<td>No</td>
<td>Specifies the pattern which matches the filenames to merge. This pattern should be a valid Jakarta-ORO Glob pattern. Defaults to "*.xml".</td>
</tr>
</tbody>
</table>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="gzip"><gzip></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#log"><log></a>
<gzip></pre>
</div>
<p>After the build-file is written, this manipulator gzips all old log files
that may exist.</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>every</td>
<td>true</td>
<td>Sets the amount of Units after which the logfiles are backuped.</td>
</tr>
<tr>
<td>unit</td>
<td>true</td>
<td>The Unit for backups. Valid Units are DAY, WEEK, MONTH or YEAR</td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="delete"><delete></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#log"><log></a>
<delete></pre>
</div>
<p>After the build-file is written, this manipulator deletes all old log files
that may exist.</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>every</td>
<td>true</td>
<td>Sets the amount of Units after which the logfiles are deleted.</td>
</tr>
<tr>
<td>unit</td>
<td>true</td>
<td>The Unit for deletions. Valid Units are DAY, WEEK, MONTH or YEAR</td>
</tr>
<tr>
<td>ignoreSuffix</td>
<td>true</td>
<td>Ignores default xml-suffix when deleting files, so other logfiles could be deleted</td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="deleteartifacts"><deleteartifacts></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#log"><log></a>
<deleteartifacts></pre>
</div>
<p>After the build-file is written, this manipulator deletes all old artifact directories
that may exist.</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>every</td>
<td>true</td>
<td>Sets the amount of Units after which the artifact directories are deleted.</td>
</tr>
<tr>
<td>unit</td>
<td>true</td>
<td>The Unit for deletions. Valid Units are DAY, WEEK, MONTH or YEAR</td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="publishers"><publishers></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<publishers></pre>
</div>
<p>Publishers are run after a build has completed. They will be run
regardless of whether the build was successful or not.</p>
<h3>Child Elements</h3>
<table class="documentation">
<thead>
<tr>
<th>Element</th>
<th>Cardinality</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><a href="#antpublisher"><code><antpublisher></code></a></td>
<td>0 .. *</td>
<td>Executes an Ant script which implements a custom publisher.</td>
</tr>
<tr>
<td><a href="#artifactspublisher"><code><artifactspublisher></code></a></td>
<td>0 .. *</td>
<td>Copies build products to a directory</td>
</tr>
<tr>
<td><a href="#clearcasebaselinepublisher"><code><clearcasebaselinepublisher></code></a></td>
<td>0 .. *</td>
<td>Creates a ClearCase UCM baseline.</td>
</tr>
<tr>
<td><a href="#cmsynergybaselinepublisher"><code><cmsynergybaselinepublisher></code></a></td>
<td>0 .. *</td>
<td>Creates an intermediate baseline in a CM Synergy database.</td>
</tr>
<tr>
<td><a href="#cmsynergytaskpublisher"><code><cmsynergytaskpublisher></code></a></td>
<td>0 .. *</td>
<td>Copies all new CM Synergy tasks into a shared folder.</td>
</tr>
<tr>
<td><a href="#compoundpublisher"><code><compoundpublisher></code></a></td>
<td>0 .. *</td>
<td>Executes all publishers specified as child elements.</td>
</tr>
<tr>
<td><a href="#currentbuildstatuspublisher"><code><currentbuildstatuspublisher></code></a></td>
<td>0 .. *</td>
<td>Writes the time of the next build to a file</td>
</tr>
<tr>
<td><a href="#email"><code><email></code></a></td>
<td>0 .. *</td>
<td>Sends an email with a URL to the build results JSP</td>
</tr>
<tr>
<td><a href="#execute"><code><execute></code></a></td>
<td>0 .. *</td>
<td>Execute a command as part of the publishing phase</td>
</tr>
<tr>
<td><a href="#ftppublisher"><code><ftppublisher></code></a></td>
<td>0 .. *</td>
<td>Copies the log file and build artifacts to an FTP server</td>
</tr>
<tr>
<td><a href="#htmlemail"><code><htmlemail></code></a></td>
<td>0 .. *</td>
<td>Sends an email with the build results embedded as HTML</td>
</tr>
<tr>
<td><a href="#http"><code><http></code></a></td>
<td>0 .. *</td>
<td>Connects to an HTTP URL and sends the build results as parameters</td>
</tr>
<tr>
<td><a href="#jabber"><code><jabber></code></a></td>
<td>0 .. *</td>
<td>Sends an instant message with a link to the build results
via a Jabber server using XMPP</td>
</tr>
<tr>
<td><a href="#onfailure"><code><onfailure></code></a></td>
<td>0 .. 1</td>
<td>Executes all publishers specified as child elements if and only
if the current build failed.</td>
</tr>
<tr>
<td><a href="#onsuccess"><code><onsuccess></code></a></td>
<td>0 .. 1</td>
<td>Executes all publishers specified as child elements if and only
if the current build was successful.</td>
</tr>
<tr>
<td><a href="#origo"><code><origo></code></a></td>
<td>0 .. *</td>
<td>Creates/closes an issue in an Origo project.</td>
</tr>
<tr>
<td><a href="#sametimeannouncement"><code><sametimeannouncement></code></a></td>
<td>0 .. *</td>
<td>Sends Sametime announcements with the result of the build</td>
</tr>
<tr>
<td><a href="#scp"><code><scp></code></a></td>
<td>0 .. *</td>
<td>Copies a file using SCP</td>
</tr>
<tr>
<td><a href="#sfeedocman"><code><sfeedocman></code></a></td>
<td>0 .. *</td>
<td>Uploads a document to a SourceForge Enterprise Edition project's Document Manager.</td>
</tr>
<tr>
<td><a href="#sfeefrs"><code><sfeefrs></code></a></td>
<td>0 .. *</td>
<td>Uploads a file to a SourceForge Enterprise Edition project's file release system (FRS).</td>
</tr>
<tr>
<td><a href="#sfeetracker"><code><sfeetracker></code></a></td>
<td>0 .. *</td>
<td>Creates a Tracker artifact in a SourceForge Enterprise Edition project.</td>
</tr>
<tr>
<td><a href="#socket"><code><socket></code></a></td>
<td>0 .. *</td>
<td>Writes "Success" or "Failure" to a socket</td>
</tr>
<tr>
<td><a href="#x10"><code><x10></code></a></td>
<td>0 .. *</td>
<td>Controls an x10 electronic device</td>
</tr>
<tr>
<td><a href="#xsltlogpublisher"><code><xsltlogpublisher></code></a></td>
<td>0 .. *</td>
<td>Performs a transformation of the log file</td>
</tr>
<tr>
<td><a href="#yahoopublisher"><code><yahoopublisher></code></a></td>
<td>0 .. *</td>
<td>Sends an instant message with a link to the build results
via a Yahoo IM message</td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="antpublisher"><antpublisher></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#publishers"><publishers></a>
<antpublisher></pre>
</div>
<p>Executes an Ant script which implements a custom publisher.</p>
<h3>Attributes</h3>
The antpublisher uses the same <a href="#ant-attributes">attributes</a>
as the <a href="#ant"><ant></a> builder.
<h3>Child Elements</h3>
The antpublisher supports the same set of
<a href="#ant-elements">child elements</a> as the
<a href="#ant"><ant></a> builder.
<h3>Properties Passed to the Publisher</h3>
<p>In addition to the standard CruiseControl <a href="#buildproperties">
properties</a>, <code><antpublisher></code> passes the following
properties to Ant, which can be accessed in your script like any other
property, using the syntax <code>${propertyname}</code>.
</p>
<table class="documentation">
<thead>
<tr>
<th>Property Name</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>thisbuildsuccessful</td>
<td>Set to true if the current build was successful, false
otherwise. See also the <a href="#onsuccess"><onsuccess></a>
and <a href="#onfailure"><onfailure></a>.
</td>
</tr>
<tr>
<td>projectname</td>
<td>The name of the CruiseControl project.</td>
</tr>
<tr>
<td>lastbuild</td>
<td>The timestamp of the last attempted build, using the format
<code>yyyyMMddHHmmss</code>.</td>
</tr>
<tr>
<td>lastsuccessfulbuild</td>
<td>The timestamp of the last successful build, using the format
<code>yyyyMMddHHmmss</code>.</td>
</tr>
<tr>
<td>builddate</td>
<td>The date of the last build, formatted using the default or
specified <a href="#dateformat"><dateformat></a>.</td>
</tr>
<tr>
<td>interval</td>
<td>The time interval between builds.</td>
</tr>
<tr>
<td>logdir</td>
<td>The directory containing the log file from the last build.</td>
</tr>
<tr>
<td>logfile</td>
<td>The name of the log file from the last build.</td>
</tr>
</tbody>
</table>
<h3>Examples</h3>
<ol>
<li>Invoke the ant.bat script distributed with ant, specifying the
working directory as <code>D:\workspace\MyProject</code> and the
ant build file as <code>MyProject-nightlybuild.xml</code> and the
ant target as <code>publish</code>. Pass in the property "custom"
with a value of "true".
<pre><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></pre>
<p>You could then do something like the following in
<code>MyProject-nightlybuild.xml</code>:</p>
<pre><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></pre>
</li>
</ol>
For <a href="#ant-examples">additional examples</a>, please
see the <a href="#ant"><ant></a> builder.
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="artifactspublisher"><artifactspublisher></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#publishers"><publishers></a>
<artifactspublisher></pre>
</div>
<p>Copies build products to unique destination directory based on the
build timestamp.</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>file</td>
<td rowspan="2">one of file or dir</td>
<td>will copy specified file</td>
</tr>
<tr>
<td>dir</td>
<td>will copy all files from this directory</td>
</tr>
<tr>
<td>dest</td>
<td>Yes</td>
<td>parent directory of actual destination directory; actual destination directory name will be the build timestamp.</td>
</tr>
<tr>
<td>subdirectory</td>
<td>No</td>
<td>subdirectory under the unique (timestamp) directory to contain artifacts</td>
</tr>
<tr>
<td>publishOnFailure</td>
<td>No (defaults to true)</td>
<td><b>Deprecated. Use <a href="#onsuccess"><onsuccess></a> and
<a href="#onfailure"><onfailure></a> instead.</b><br/>
set this attribute to false to stop the publisher from running when the build fails.</td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="clearcasebaselinepublisher"><clearcasebaselinepublisher></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#publishers"><publishers></a>
<clearcasebaselinepublisher>
</pre>
</div>
<p>Creates a ClearCase UCM baseline for the specified view's integration stream.
Uses the value of the CruiseControl generated <code>${label}</code> property
as well as the value of the <code>baselineprefix</code> 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).</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>viewtag</td>
<td>Yes</td>
<td>The view tag of the UCM view that you wish to create the baseline in.
The baseline is created in the stream that the view is attached to.</td>
</tr>
<tr>
<td>full</td>
<td>No</td>
<td>Boolean value indicating whether a "Fully Labelled" or "Incremental"
baseline should be created. Default is false, i.e. "Incremental".</td>
</tr>
<tr>
<td>baselineprefix</td>
<td>No</td>
<td>A prefix which should be applied together with the CruiseControl
<code>${label}</code> property, for example specifying "EXAMPLE_"
with a CruiseControl generated label of "1_INT" would create a
baseline called "EXAMPLE_1_INT".</td>
</tr>
<tr>
<td>component</td>
<td>No</td>
<td>The component to restrict the baseline creation to. By default the baseline
is applied to all of the stream's changed components.</td>
</tr>
</tbody>
</table>
<h3>Examples</h3>
<ol>
<li>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.
<pre>
<publishers>
<clearcasebaselinepublisher viewtag = "j2ee_int"
baselineprefix = "J2EE_"
component = "J2EE_SRC"/>
</publishers>
</pre>
</li>
</ol>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="cmsynergybaselinepublisher"><cmsynergybaselinepublisher></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#publishers"><publishers></a>
<cmsynergybaselinepublisher></pre>
</div>
<p>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. <b>This publisher will <i>only</i> work with CM Synergy version 6.3
or later.</b></p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>ccmexe</td>
<td>No</td>
<td>The name of the CM Synergy command line client. If not provided, the
plugin will search the system path for an executable called "ccm"
(or "ccm.exe" for Windows).</td>
</tr>
<tr>
<td>sessionfile</td>
<td>No</td>
<td>The session file used by the
<a href="#cmsynergysessionmonitor"><cmsynergysessionmonitor></a>
to persist your CM Synergy session information. If this attribute is
not set, it defaults to the file ".ccmsessionmap" in your home directory.</td>
</tr>
<tr>
<td>sessionname</td>
<td>No</td>
<td>The session name of the CM Synergy session you wish to use. This name
must appear in the session file. If not set, the plugin will attempt
to use the default (current) session as returned by the "ccm status"
command.</td>
</tr>
<tr>
<td>project</td>
<td>Yes</td>
<td>The project spec (two part name) of the project you wish to form the top
level project of the baseline. Note that all subprojects will also be
included.</td>
</tr>
<tr>
<td>purpose</td>
<td>No</td>
<td>The purpose of the baseline. If not specified, this will default to
"Integration Testing".</td>
</tr>
<tr>
<td>description</td>
<td>No</td>
<td>An optional description of the baseline.</td>
</tr>
<tr>
<td>baselinename</td>
<td>No</td>
<td>An optional name for the baseline. If not provided, CM Synergy will assign
a default name based upon the current date. You may incorporate the value
of any property set by CruiseControl (in the "info" section of the log)
by using the macro "@{property}".</td>
</tr>
</tbody>
</table>
<h3>Examples</h3>
<ol>
<li>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.
<pre>
<publishers>
<cmsynergybaselinepublisher sessionname = "j2ee_session"
project = "j2ee~1.0_int"
baselinename = "BUILD_@{cctimestamp}"/>
</publishers>
</pre>
</li>
</ol>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="cmsynergytaskpublisher"><cmsynergytaskpublisher></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#publishers"><publishers></a>
<cmsynergytaskpublisher></pre>
</div>
<p>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.</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>ccmexe</td>
<td>No</td>
<td>The name of the CM Synergy command line client. If not provided, the
plugin will search the system path for an executable called "ccm"
(or "ccm.exe" for Windows).</td>
</tr>
<tr>
<td>sessionfile</td>
<td>No</td>
<td>The session file used by the
<a href="#cmsynergysessionmonitor"><cmsynergysessionmonitor></a>
to persist your CM Synergy session information. If this attribute is
not set, it defaults to the file ".ccmsessionmap" in your home directory.</td>
</tr>
<tr>
<td>sessionname</td>
<td>No</td>
<td>The session name of the CM Synergy session you wish to use. This name
must appear in the session file. If not set, the plugin will attempt
to use the default (current) session as returned by the "ccm status"
command.</td>
</tr>
<tr>
<td>foldernumber</td>
<td rowspan="3">Either foldernumber <i>or</i> foldername and project</td>
<td>The number of the target folder.</td>
</tr>
<tr>
<td>foldername</td>
<td>A <i>substring</i> of the name of the target folder (i.e. "Integration
tested tasks"). If this attribute is set, you <i>must</i> also set the
project attribute.</td>
</tr>
<tr>
<td>project</td>
<td>The two part name of the project which contains the named folder.</td>
</tr>
</tbody>
</table>
<h3>Examples</h3>
<ol>
<li>Publish all new tasks into folder number 203 using the CM Synergy session
named "j2ee_session".
<pre>
<publishers>
<cmsynergytaskpublisher sessionname = "j2ee_session"
foldernumber = "203"/>
</publishers>
</pre>
</li>
<li>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".
<pre>
<publishers>
<cmsynergytaskpublisher sessionname = "j2ee_session"
project = "j2ee~1.0_int"
foldername = "Integration tested tasks"/>
</publishers>
</pre>
</li>
</ol>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="currentbuildstatuspublisher"><currentbuildstatuspublisher></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#publishers"><publishers></a>
<currentbuildstatuspublisher></pre>
</div>
<p>Note: this plugin has been made obsolete by the
<a href="#currentbuildstatuslistener"><code>currentbuildstatuslistener</code></a>.</p>
<p>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.</p>
<p>This plugin is used in tandem with the
<a href="#currentbuildstatusbootstrapper"><code>currentbuildstatusbootstrapper</code></a>.</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>file</td>
<td>Yes</td>
<td>The filename to write</td>
</tr>
<tr>
<td>dateformat</td>
<td>No</td>
<td>Optionally customize the dateformat used in this file</td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="execute"><execute></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#publishers"><publishers></a>
<execute></pre>
</div>
<p>Execute a command as part of the publishing phase.</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>command</td>
<td>Yes</td>
<td>The command to execute</td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="scp"><scp></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#publishers"><publishers></a>
<scp></pre>
</div>
<p>SCP a file as part of the publishing process.</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>executableName</td>
<td>No</td>
<td>Specify the name of the executable to invoke. Default is "scp".</td>
</tr>
<tr>
<td>sourceuser</td>
<td>Yes if sourcehost is specified</td>
<td>Log in to the sourcemachine as this user.</td>
</tr>
<tr>
<td>sourcehost</td>
<td>Yes if sourceuser is specified</td>
<td>SCP from this machine.</td>
</tr>
<tr>
<td>sourcedir</td>
<td>No (defaults to '.')</td>
<td>The directory to copy from.</td>
</tr>
<tr>
<td>targetuser</td>
<td>Yes if targethost is specified</td>
<td>Log in to the target machine as this user.</td>
</tr>
<tr>
<td>targethost</td>
<td>Yes if targetuser is specified</td>
<td>SCP to this machine.</td>
</tr>
<tr>
<td>targetdir</td>
<td>No (defaults to '.')</td>
<td>The directory to copy to.</td>
</tr>
<tr>
<td>targetseparator</td>
<td>No (defaults to File.separator on the source machine)</td>
<td>The file separator on the target machine.</td>
</tr>
<tr>
<td>sourceseparator</td>
<td>No (defaults to File.separator on the source machine)</td>
<td>The file separator on the source machine. Useful when using an alternate shell
environment, e.g. Cygwin, that expects a separator that differs from the native OS.</td>
</tr>
<tr>
<td>ssh</td>
<td>No (defaults to 'ssh')</td>
<td>The ssh application.</td>
</tr>
<tr>
<td>options</td>
<td>No</td>
<td>Additional options to pass to SCP.</td>
</tr>
<tr>
<td>file</td>
<td>No (defaults to the current logfile)</td>
<td>The filename to copy.</td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="sfeedocman"><sfeedocman></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#publishers"><publishers></a>
<sfeedocman></pre>
</div>
<p>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.</p>
<p>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
(<code>inmemorysfee-x.x.x.jar</code>) and put the SDK jars in its place and make them available in
CruiseControl's classpath.
</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>serverurl</td>
<td>Yes</td>
<td>URL for the SFEE instance.</td>
</tr>
<tr>
<td>username</td>
<td>Yes</td>
<td>Valid username for the specified SFEE instance.</td>
</tr>
<tr>
<td>password</td>
<td>Yes</td>
<td>Password for the specified username.</td>
</tr>
<tr>
<td>document</td>
<td>Yes</td>
<td>The path to the document to publish.</td>
</tr>
<tr>
<td>folder</td>
<td>Yes</td>
<td>The Document Manager folder in which to publish.</td>
</tr>
<tr>
<td>projectName</td>
<td>Yes</td>
<td>The name of the SFEE project where the Document Manager folder specified exists.</td>
</tr>
</tbody>
</table>
<h3>Child Elements</h3>
<table class="documentation">
<thead>
<tr>
<th>Element</th>
<th>Cardinality</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code><description></code></td>
<td>1</td>
<td>The description for the Document. This child element is required and is an
<a href="#xpathawarechildattributes">XPath Aware Child</a>. Look there for attribute details.
</td>
</tr>
<tr>
<td><code><status></code></td>
<td>1</td>
<td>The status for the Document. This child element is required and is an
<a href="#xpathawarechildattributes">XPath Aware Child</a>. Look there for attribute details.
</td>
</tr>
<tr>
<td><code><documentname></code></td>
<td>0..1</td>
<td>The name for the Document within the Document Manager. If a Document Manager entry already exists
in the specified folder with the same name, then the document being published will be added as a new
version. If this child is not included, it will default to the name of the file being published.
This child element is optional and is a
<a href="#xpathawarechildattributes">XPath Aware Child</a>. Look there for attribute details.
</td>
</tr>
<tr>
<td><code><versioncomment></code></td>
<td>0..1</td>
<td>The version comment for the Document. This child element is optional and is a
<a href="#xpathawarechildattributes">XPath Aware Child</a>. Look there for attribute details.
</td>
</tr>
</tbody>
</table>
<h3>Examples</h3>
<pre>
<!-- 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></pre>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="sfeefrs"><sfeefrs></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#publishers"><publishers></a>
<sfeefrs></pre>
</div>
<p>Uploads a file to a SourceForge Enterprise Edition project's file release system (FRS).</p>
<p>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
(<code>inmemorysfee-x.x.x.jar</code>) and put the SDK jars in its place and make them available in
CruiseControl's classpath.
</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>file</td>
<td>Yes</td>
<td>Path to a file on the local filesystem that should be uploaded.</td>
</tr>
<tr>
<td>serverurl</td>
<td>Yes</td>
<td>URL for the SFEE instance.</td>
</tr>
<tr>
<td>username</td>
<td>Yes</td>
<td>Valid username for the specified SFEE instance.</td>
</tr>
<tr>
<td>password</td>
<td>Yes</td>
<td>Password for the specified username.</td>
</tr>
<tr>
<td>releaseid</td>
<td>Yes</td>
<td>The SFEE id for the FRS release, e.g. rel2509.</td>
</tr>
<tr>
<td>uploadname</td>
<td>No (defaults to the same name as the local file)</td>
<td>The name to be used for the file in the FRS.</td>
</tr>
</tbody>
</table>
<h3>Examples</h3>
<pre>
<!-- 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"/></pre>
<pre>
<!-- 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"/></pre>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="sfeetracker"><sfeetracker></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#publishers"><publishers></a>
<sfeetracker></pre>
</div>
<p>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.</p>
<p>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
(<code>inmemorysfee-x.x.x.jar</code>) and put the SDK jars in its place and make them available in
CruiseControl's classpath.
</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>trackerName</td>
<td>Yes</td>
<td>The name of the Tracker within the specified SFEE project.</td>
</tr>
<tr>
<td>projectName</td>
<td>Yes</td>
<td>The name of the SFEE project where the tracker specified exists.</td>
</tr>
<tr>
<td>serverurl</td>
<td>Yes</td>
<td>URL for the SFEE instance.</td>
</tr>
<tr>
<td>username</td>
<td>Yes</td>
<td>Valid username for the specified SFEE instance.</td>
</tr>
<tr>
<td>password</td>
<td>Yes</td>
<td>Password for the specified username.</td>
</tr>
</tbody>
</table>
<h3>Child Elements</h3>
<table class="documentation">
<thead>
<tr>
<th>Element</th>
<th>Cardinality</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code><title></code></td>
<td>1</td>
<td>The title for the tracker artifact. This child element is required and is an
<a href="#xpathawarechildattributes">XPath Aware Child</a>. Look there for attribute details.
</td>
</tr>
<tr>
<td><code><description></code></td>
<td>1</td>
<td>The description for the tracker artifact. This child element is required and is an
<a href="#xpathawarechildattributes">XPath Aware Child</a>. Look there for attribute details.
</td>
</tr>
<tr>
<td><code><status></code></td>
<td>1</td>
<td>The status for the tracker artifact. This child element is required and is an
<a href="#xpathawarechildattributes">XPath Aware Child</a>. Look there for attribute details.
</td>
</tr>
<tr>
<td><code><field></code></td>
<td>0..*</td>
<td>Sets a field that exists in the tracker artifact. This child element is optional and is a
<a href="#namedxpathawarechildattributes">Named XPath Aware Child</a>. Look there for attribute details.
</td>
</tr>
</tbody>
</table>
<h3>Examples</h3>
<pre>
<!-- 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></pre>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="email"><email></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#publishers"><publishers></a>
<email></pre>
</div>
<p>Sends an email with a URL to the build results JSP.</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>buildresultsurl</td>
<td>Yes</td>
<td>URL to the build results JSP</td>
</tr>
<tr>
<td>defaultsuffix</td>
<td>No</td>
<td>Default e-mail suffix to append to user names to build
valid e-mail addresses. This defaults to an empty string if
not specified.</td>
</tr>
<tr>
<td>failasimportant</td>
<td>No</td>
<td>Flag emails about failed builds as important? Default is 'true'.</td>
</tr>
<tr>
<td>mailhost</td>
<td>Yes</td>
<td>Mail server address</td>
</tr>
<tr>
<td>mailport</td>
<td>No</td>
<td>Mail server port</td>
</tr>
<tr>
<td>username</td>
<td>if password is specified</td>
<td>Username for smtp server</td>
</tr>
<tr>
<td>password</td>
<td>if username is specified</td>
<td>Password for smtp server</td>
</tr>
<tr>
<td>reportsuccess</td>
<td>No (defaults to <i>always</i></td>
<td>Valid values:
<dl>
<dt>always:</dt>
<dd>publishes (<i>i.e.</i>, e-mails) results on every
successful build.</dd>
<dt>fixes:</dt>
<dd>publishes results only on the first successful build
and the first successful build after a failed build.</dd>
<dt>never:</dt>
<dd>only publishes on failed builds</dd>
</dl></td>
</tr>
<tr>
<td>returnaddress</td>
<td>Yes</td>
<td>E-mail address that will appear in the sent email's From field</td>
</tr>
<tr>
<td>returnname</td>
<td>No</td>
<td>A name to match to the return address</td>
</tr>
<tr>
<td>skipusers</td>
<td>No (defaults to false)</td>
<td>Controls if the users who made changes in this build get
email. Useful to set to "true" while configuring or debugging
your system. Users specified by the failure or always nested
elements will still receive email.</td>
</tr>
<tr>
<td>spamwhilebroken</td>
<td>No (defaults to true)</td>
<td>Whether or not e-mail reports on failed builds will continue
for subsequent failed builds.</td>
</tr>
<tr>
<td>subjectprefix</td>
<td>No</td>
<td>Prefix for subject line of email. Useful for easily
filtering email.</td>
</tr>
<tr>
<td>usessl</td>
<td>No</td>
<td>"true" to connect to the smtp server using SSL.
Do not forget to set the corresponding mailport.</td>
</tr>
</tbody>
</table>
<h3>Child Elements</h3>
<table class="documentation">
<thead>
<tr>
<th>Element</th>
<th>Cardinality</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><a name="always"><code><always></code></a></td>
<td>0 .. *</td>
<td>Mail address to be emailed notification after all builds.
<code><always></code> has the following attributes:
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>address</td>
<td>Yes</td>
<td>e-mail address</td>
</tr>
</tbody>
</table>
</td>
</tr>
<tr>
<td><a name="failure"><code><failure></code></a></td>
<td>0 .. *</td>
<td>Mail address to be emailed notification after failed builds.
<code><failure></code> has the following attributes:
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>address</td>
<td>Yes</td>
<td>e-mail address</td>
</tr>
<tr>
<td>reportWhenFixed</td>
<td>No</td>
<td>either true or false; defaults to false</td>
</tr>
</tbody>
</table>
</td>
</tr>
<tr>
<td><a name="ignore"><code><ignore></code></a></td>
<td>0 .. *</td>
<td>User name to be removed from the user list, thus not sent any email.
Useful for removing the fake user names created by some sourcecontrols.
<code><ignore></code> has the following attributes:
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>user</td>
<td>Yes</td>
<td>user name from modification to be ignored</td>
</tr>
</tbody>
</table>
</td>
</tr>
<tr>
<td><a name="success"><code><success></code></a></td>
<td>0 .. *</td>
<td>Mail address to be emailed notification after successful builds.
<code><success></code> has the following attributes:
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>address</td>
<td>Yes</td>
<td>e-mail address</td>
</tr>
</tbody>
</table>
</td>
</tr>
<tr>
<td><a name="alert"><code><alert></code></a></td>
<td>0 .. *</td>
<td>Mail address to be emailed notification if any of the build's
modified files match the supplied regular expression.
<code><alert></code> has the following attributes:
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>fileRegExpr</td>
<td>Yes</td>
<td>A regular expression indicating which modified
files you are interested in</td>
</tr>
<tr>
<td>address</td>
<td>Yes</td>
<td>e-mail address</td>
</tr>
</tbody>
</table>
</td>
</tr>
<tr>
<td><a name="map"><code><map></code></a></td>
<td>0 .. *</td>
<td>Maps a source control user id to an email address.
<code><map></code> has the following attributes:
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>alias</td>
<td>Yes</td>
<td>alias (username) as it appears on modifications</td>
</tr>
<tr>
<td>address</td>
<td>Yes</td>
<td>e-mail address</td>
</tr>
</tbody>
</table>
</td>
</tr>
<tr>
<td><a name="propertiesmapper"><code><propertiesmapper></code></a></td>
<td>0 .. *</td>
<td>map source control user names to either valid email names
or complete email addresses. <code><propertiesmapper></code>
has the following attributes:
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>file</td>
<td>Yes</td>
<td>Full path to a java properties file where each
property key is assumed to be a user name that is
mapped to the property value, which is assumed to
be valid email name or a complete email address.</td>
</tr>
</tbody>
</table>
</td>
</tr>
<tr>
<td><a name="mavenmapper"><code><mavenmapper></code></a></td>
<td>0 .. *</td>
<td>Map source control user names to their respective email address as
configured in Maven's POM (suitable for Maven 1 and 2). Used for the mapping
is the <code><id></code> element of the <code><developer></code> entry.
<code><mavenmapper></code> has the following attributes:
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>projectfile</td>
<td>Yes</td>
<td>Full path to Maven's <code>project.xml</code> (Maven 1) or <code>pom.xml</code> (Maven 2) file.</td>
</tr>
</tbody>
</table>
</td>
</tr>
<tr>
<td><a name="ldapmapper"><code><ldapmapper></code></a></td>
<td>0 .. *</td>
<td>map source control user names to either valid email names
or complete email addresses. <code><ldapmapper></code>
has the following attributes:
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>url</td>
<td>Yes</td>
<td>URL used to connect to an LDAP server</td>
</tr>
<tr>
<td>rootdn</td>
<td>Yes</td>
<td></td>
</tr>
<tr>
<td>binddn</td>
<td>no</td>
<td>DN to bind to the LDAP</td>
</tr>
<tr>
<td>bindpassword</td>
<td>if binddn is specified</td>
<td>password to bind to the LDAP</td>
</tr>
<tr>
<td>searchtmpl</td>
<td>No</td>
<td>Default: (cn=?). The ? character in the template is
replaced by the user id to be mapped into an email address</td>
</tr>
<tr>
<td>searchattr</td>
<td>No</td>
<td>Default: mail. The LDAP attribute that is searched
to retrieve the email address of the user id used in the search.</td>
</tr>
<tr>
<td>ctxfactory</td>
<td>No</td>
<td>Default: com.sun.jndi.ldap.LdapCtxFactory. LDAP Context Factory to be used.</td>
</tr>
</tbody>
</table>
</td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="htmlemail"><htmlemail></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#publishers"><publishers></a>
<htmlemail></pre>
</div>
<p>Sends an email with the build results embedded as HTML. By default
the same information as the JSP build results page is sent.</p>
<p>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.</p>
<h3>Attributes</h3>
<p>All of the attributes and child elements of <a href="#email"><code><email></code></a>
apply to <code><htmlemail></code> as well. The following table
specifies the additional or changed attributes.</p>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>buildresultsurl</td>
<td>No</td>
<td>Email will include link to the build results JSP if this
URL is provided.</td>
</tr>
<tr>
<td>charset</td>
<td>No</td>
<td>If not set the content type will be set to 'text/html'. If
set the content type will be 'text/html;charset="value"'.</td>
</tr>
<tr>
<td>css</td>
<td><i>versions up to 2.3:</i> unless xslfile specified<br/>
<i>versions 2.3 and greater:</i> no</td>
<td>Path to cruisecontrol.css. Used only if xsldir set and
not xslfile. Starting with version 2.3, the HTMLEmailPublisher
will try to determine the correct value itself when it's not
specified and xslfile isn't used.</td>
</tr>
<tr>
<td>logdir</td>
<td>No (Yes for versions < 2.2)</td>
<td>Path to the log directory as set in the log element of
the configuration xml file.
Follows default of <a href="#log">log</a>'s dir-attribute since version 2.2</td>
</tr>
<tr>
<td>xsldir</td>
<td><i>versions up to 2.3:</i> unless xslfile specified<br />
<i>versions 2.3 and greater:</i> no</td>
<td>Directory where standard CruiseControl xsl files are
located. Starting with version 2.3, the HTMLEmailPublisher
will try to determine the correct value itself when it's not
specified and xslfile isn't used.</td>
</tr>
<tr>
<td>xslfile</td>
<td>No</td>
<td>If specified, xsldir, xslfilelist, and css are ignored. Must
handle the entire document.</td>
</tr>
<tr>
<td>xslfilelist</td>
<td>No</td>
<td>Works with xsldir and css. String, representing ordered list of xsl files
located in xsldir, which are used to format HTML email. List is comma
or space separated. If first character of list is plus sign ("+"), the listed
file(s) are added to existing set of xsl files used by HTMLEmailPublisher. If
xslfilelist is not specified, email is published using hard-coded list of
xsl files.
</td>
</tr>
</tbody>
</table>
<h3>Child Elements</h3>
<table class="documentation">
<thead>
<tr>
<th>Element</th>
<th>Cardinality</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><a name="parameter"><code><parameter></code></a></td>
<td>0 .. *</td>
<td>Parameters passed to the XSL files before transforming them to HTML. Check
the Reporting application's <a href="../reporting/jsp/custom.html#XSLT_parameters">
documentation</a> for parameters used in the standard XSL files.
<code><parameter/></code> has the following attributes:
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>name</td>
<td>Yes</td>
<td>the name of the XSLT parameter</td>
</tr>
<tr>
<td>value</td>
<td>Yes</td>
<td>the parameter's value</td>
</tr>
</tbody>
</table>
</td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="http"><http></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#publishers"><publishers></a>
<http></pre>
</div>
<p>Connects to an HTTP URL and sends the build results as parameters</p>
<p>Build results can be sent to a URL using any of the HTTP methods</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>url</td>
<td>Yes</td>
<td>The URL to connect to. Must be of the HTTP protocol.</td>
</tr>
<tr>
<td>requestMethod</td>
<td>Yes</td>
<td>HTTP request method. POST, GET etc.</td>
</tr>
</tbody>
</table>
<h3>Child Elements</h3>
<table class="documentation">
<thead>
<tr>
<th>Element</th>
<th>Cardinality</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code><parameter></code></td>
<td>0..*</td>
<td>Sets an HTTP attribute-value parameter. If the request method is GET, the attribute-value pairs are
added to the URL string. Otherwise they are included in the message body. This child element is optional and is a
<a href="#namedxpathawarechildattributes">Named XPath Aware Child</a>. Look there for attribute details.
</td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="jabber"><jabber></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#publishers"><publishers></a>
<jabber></pre>
</div>
<p>Sends an instant message with a link to the build results via a Jabber server
using XMPP.</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>host</td>
<td>Yes</td>
<td>The host of the Jabber server.</td>
</tr>
<tr>
<td>port</td>
<td>No</td>
<td>Port of the Jabber server. Defaults to 5222. Note: SSL typically
runs on port 5223.</td>
</tr>
<tr>
<td>username</td>
<td>Yes</td>
<td>Username of the account used to send the instant message. For individuals,
this is typically of the form 'foo' as opposed to 'foo@bar.com'</td>
</tr>
<tr>
<td>password</td>
<td>Yes</td>
<td>Password of the sender account</td>
</tr>
<tr>
<td>recipient</td>
<td>Yes</td>
<td>Username of the recipient of the instant message. Recipient username
is typically fully qualified: foo@bar.com</td>
</tr>
<tr>
<td>chatroom</td>
<td>No</td>
<td>Whether the recipient is a group/chat (true) versus an individual (false). Defaults to false.</td>
</tr>
<tr>
<td>ssl</td>
<td>No</td>
<td>Whether the XMPP connection on host:port is using SSL.</td>
</tr>
<tr>
<td>buildresultsurl</td>
<td>Yes</td>
<td>Email will include link to the build results.</td>
</tr>
<tr>
<td>service</td>
<td>No</td>
<td>Service to use.</td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="onfailure"><onfailure></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#publishers"><publishers></a>
<onfailure></pre>
</div>
<p>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.</p>
<p>All child elements must meet the following criteria:</p>
<ol>
<li>
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
<a href="#plugin"><plugin></a> element within your config file.
</li>
<li>
They must validate successfully regardless of whether or not
the build was successful.
</li>
</ol>
<h3>Child Elements</h3>
<table class="documentation">
<thead>
<tr>
<th>Element</th>
<th>Cardinality</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>Any defined publisher</td>
<td>1 .. *</td>
<td>You may use any defined publisher as a child element.</td>
</tr>
</tbody>
</table>
<h3>Examples</h3>
<ol>
<li>After a failed build, use the x10 publisher to light up a lamp,
and call an Ant script to do some cleanup.
<pre>
<onfailure>
<x10 houseCode="A" deviceCode="3"/>
<antpublisher antscript="/opt/apache-ant-1.6.1/bin/ant"
target="cleanupafterfailure">
</antpublisher>
</onfailure>
</pre>
</li>
</ol>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="onsuccess"><onsuccess></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#publishers"><publishers></a>
<onsuccess></pre>
</div>
<p>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.</p>
<p>All child elements must meet the following criteria:</p>
<ol>
<li>
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
<a href="#plugin"><plugin></a> element within your config file.
</li>
<li>
They must validate successfully regardless of whether or not
the build was successful.
</li>
</ol>
<h3>Child Elements</h3>
<table class="documentation">
<thead>
<tr>
<th>Element</th>
<th>Cardinality</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>Any defined publisher</td>
<td>1 .. *</td>
<td>You may use any defined publisher as a child element.</td>
</tr>
</tbody>
</table>
<h3>Examples</h3>
<ol>
<li>After a successful build, use the x10 publisher to light up a lamp,
and run the artifacts publisher to save the build artifacts.
<pre>
<onsuccess>
<x10 houseCode="A" deviceCode="7"/>
<artifactspublisher dir="checkout/project1/dist"
dest="artifacts/project1">
</artifactspublisher>
</onsuccess>
</pre>
</li>
</ol>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="origo"><origo></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#publishers"><publishers></a>
<origo></pre>
</div>
<p>Creates a new issue in an Origo system if a build fails and closes
the issue after the build has been fixed.</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>apiurl</td>
<td>No (defaults to http://api.origo.ethz.ch/api/xmlrpc)</td>
<td>URL to Origo API</td>
</tr>
<tr>
<td>buildresultsurl</td>
<td>No (defaults to http://localhost:8180/)</td>
<td>URL to the build results JSP</td>
</tr>
<tr>
<td>issueprivate</td>
<td>No (defaults to true)</td>
<td>Should the issue be private</td>
</tr>
<tr>
<td>issuesubject</td>
<td>No (defaults to Cruisecontrol failed)</td>
<td>Subject for newly created issue</td>
</tr>
<tr>
<td>issuetag</td>
<td>No (defaults to cruisecontrol::failed)</td>
<td>Tag for newly created issue, must be unique in the project</td>
</tr>
<tr>
<td>projectname</td>
<td>Yes</td>
<td>Name of the origo project</td>
</tr>
<tr>
<td>userkey</td>
<td>Yes</td>
<td>Origo user key to report/update the issue</td>
</tr>
</tbody>
</table>
<h3>Examples</h3>
<ol>
<li>Create/update an issue in the ethz Origo instance for the project Connectfour.
<pre>
<origo userkey="SOMEVERYSECRETKEY"
projectname="connectfour"
buildresultsurl="http://somehost.tld//buildresults/${project.name}"
issuetag="cruisecontrol::${project.name}::failed"/>
</pre>
</li>
</ol>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="rss"><rss></a></h2>
<div class="hierarchy">
<pre><a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#publishers"><publishers></a>
<rss></pre>
</div>
<p>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.</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>buildresultsurl</td>
<td>yes</td>
<td>RSS item will include a link to the build results page. Build results URL should look like 'http://MACHINENAME/cruisecontrol/buildresults/PROJECTNAME'.</td>
</tr>
<tr>
<td>channellinkurl</td>
<td>No</td>
<td>The primary URL associated with the RSS feed.</td>
</tr>
<tr>
<td>file</td>
<td>Yes</td>
<td>The location to which the RSS file should be published. If an RSS file already exists in this location,
existing RSS attributes (title, description, channel link URL, news items) will be preserved.</td>
</tr>
<tr>
<td>maxlength</td>
<td>No</td>
<td>The maximum number of items to maintain in the RSS file. Defaults to 10.</td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="sametimeannouncement"><sametimeannouncement></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#publishers"><publishers></a>
<sametimeannouncement></pre>
</div>
<p>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 <a href="#email"><code><email></code></a>
apply to <code><sametimeannouncement></code> as well.</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>buildresultsurl</td>
<td>No</td>
<td>URL to include with the build results.</td>
</tr>
<tr>
<td>host</td>
<td>Yes</td>
<td>Synonym for mailHost.</td>
</tr>
<tr>
<td>username</td>
<td>Yes</td>
<td>User name to login to the Sametime community.</td>
</tr>
<tr>
<td>password</td>
<td>No</td>
<td>Password used to login to the Sametime community. If not
specified, an anonymous login (using username) will be
attempted.</td>
</tr>
<tr>
<td>community</td>
<td>No</td>
<td>Sametime community to login to. Default is null —
appropriate for single community servers.</td>
</tr>
<tr>
<td>resolveusers</td>
<td>No (defaults to true)</td>
<td>Whether addresses should be resolved as users.</td>
</tr>
<tr>
<td>resolvegroups</td>
<td>No (defaults to true)</td>
<td>Whether addresses should be resolved as groups.</td>
</tr>
<tr>
<td>usegroupcontent</td>
<td>No (defaults to true)</td>
<td>Whether to send announcements to the content (members) of a
group instead of the group directly.</td>
</tr>
<tr>
<td>handleresolveconflicts</td>
<td>No (defaults to recipient)</td>
<td>How to handle address resolution conflicts. Valid values:
<dl>
<dt>error:</dt>
<dd>abort the announcement</dd>
<dt>warn:</dt>
<dd>log a warning, ignoring the conflicting addresses</dd>
<dt>ignore:</dt>
<dd>ignore the conflicting addresses</dd>
<dt>recipient:</dt>
<dd>treat all conflicting addresses as recipients of the
announcement</dd>
</dl></td>
</tr>
<tr>
<td>handleresolvefails</td>
<td>No (defaults to error)</td>
<td>How to handle address resolution failures. Valid values:
<dl>
<dt>error:</dt>
<dd>abort the announcement</dd>
<dt>warn:</dt>
<dd>log a warning and proceed</dd>
<dt>ignore:</dt>
<dd>ignore the failure</dd>
</dl></td>
</tr>
<tr>
<td>handlequerygroupcontentfails</td>
<td>No (defaults to error)</td>
<td>How to handle group content query failures. Valid values:
<dl>
<dt>error:</dt>
<dd>abort the announcement</dd>
<dt>warn:</dt>
<dd>log a warning and proceed</dd>
<dt>ignore:</dt>
<dd>ignore the failure</dd>
</dl></td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="socket"><socket></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#publishers"><publishers></a>
<socket></pre>
</div>
<p>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.</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>socketServer</td>
<td>Yes</td>
<td>Hostname (i.e., first argument for constructing a Java socket)</td>
</tr>
<tr>
<td>port</td>
<td>Yes</td>
<td>Port number for the listening socket</td>
</tr>
<tr>
<td>sendProjectName</td>
<td>No (defaults to true)</td>
<td>Whether the project name should be appended to the result string.</td>
</tr>
<tr>
<td>sendFixed</td>
<td>No (defaults to false)</td>
<td>Whether the publisher should send "Fixed" instead of "Success" after "Failure".</td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="weblogpublisher"><weblog></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#publishers"><publishers></a>
<weblog></pre>
</div>
<p>Posts the build results to a weblog using the
<a href="http://www.blogger.com/developers/api">Blogger API</a>,
the <a href="http://www.xmlrpc.com/metaWeblogApi">MetaWeblog API</a>
or the <a href="http://www.livejournal.com/doc/server/ljp.csp.xml-rpc.postevent.html">LiveJournal API</a>.
</p>
<h3>Examples</h3>
<pre><!-- 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"/></pre>
<pre><!-- 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"/></pre>
<pre><!-- 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"/></pre>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr class="oddrow">
<td>api</td>
<td>No</td>
<td>The API to use for posting to the blog. Accepted
values include <i>blogger</i> and <i>metaWeblog</i>. Defaults to
<i>metaWeblog</i>.</td>
</tr>
<tr>
<td>blogurl</td>
<td>Yes</td>
<td>The URL where your blog receives XML-RPC requests.</td>
</tr>
<tr class="oddrow">
<td>blogid</td>
<td>Yes</td>
<td>The "identifier" for your blog. See your blog's
documentation for the correct value.</td>
</tr>
<tr>
<td>username</td>
<td>Yes</td>
<td>The username for authentication.</td>
</tr>
<tr class="oddrow">
<td>password</td>
<td>Yes</td>
<td>The password for authentication.</td>
</tr>
<tr>
<td>logdir</td>
<td>Yes</td>
<td>The CruiseControl log directory.</td>
</tr>
<tr class="oddrow">
<td>xslfile</td>
<td>Yes, unless <i>xsldir</i> is used.</td>
<td>The XSL stylesheet used for transforming
the build results into the message being posted to the blog.</td>
</tr>
<tr>
<td>xsldir</td>
<td>Yes, unless <i>xslfile</i> is used.</td>
<td>The directory containing the XSL stylesheets
used for transforming the build results into the message being
posted to the blog. You can use the CruiseControl distribution's
XSL directory, "${CC_HOME}/reporting/jsp/xsl", or use your
custom stylesheets.
</td>
</tr>
<tr class="oddrow">
<td>css</td>
<td>Yes, if <i>xsldir</i> is used.</td>
<td>The path to cruisecontrol.css to be
used for styling the generated HTML. You can use the CruiseControl
distribution's 'cruisecontrol.css' file from
"${CC_HOME}/reporting/jsp/css" or use a custom stylesheet.
</td>
</tr>
<tr>
<td>buildresultsurl</td>
<td>No</td>
<td>The base URL for the CruiseControl reporting
web application. Usually of the form
"http://buildserver/cruisecontrol/<projectname>". If this
URL is provided, the resulting blog entry will include a link
to the build results.</td>
</tr>
<tr class="oddrow">
<td>category</td>
<td>No</td>
<td>The category to which the blog entries
should be added. For the Blogger API, only one category name
is allowed. For the MetaWeblog API, a comma-separated list of
category names is also possible.</td>
</tr>
<tr>
<td>reportsuccess</td>
<td>No</td>
<td>The rule for reporting successful builds.
Accepted values are "always", "never", and "fixes" (only post
the results for the first successful build after a failed one).
</td>
</tr>
<tr class="oddrow">
<td>subjectprefix</td>
<td>No</td>
<td>The prefix to use for blog entries' title.</td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="x10"><x10></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#publishers"><publishers></a>
<x10></pre>
</div>
<p>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.</p>
<h3>Quick Start</h3>
<ol>
<li>Buy the home automation kit found at <a
href="http://www.x10.com/automation/x10_ck11a_1.htm">http://www.x10.com/automation/x10_ck11a_1.htm</a>.</li>
<li>Plug the computer interface to your serial port (for
example, COM1 or /dev/ttyS0), and your powerline</li>
<li>Set the lamp module's house and device code such as A3
and plug it into your powerline.</li>
<li>Plug in an electronic device to the lamp module like a
lava lamp or flashing red light found at <a
href="http://www.bwild.com/redsiren.html">http://www.bwild.com/redsiren.html</a>.</li>
<li>Install the Java Communications API on your
CruiseControl machine. On Windows, copy win32com.dll from
the CruiseControl lib directory to
your <code>JAVA_HOME/bin</code> directory. On Linux, first
obtain the Linux zip file from
<a
href="http://www.sun.com/download/products.xml?id=43208d3d">http://www.sun.com/download/products.xml?id=43208d3d</a>.
At the time of this writing, the name of the file
was <code>comm3.0_u1_linux.zip</code>. Extract
<code>commapi/jar/comm.jar</code> and
<code>commapi/docs/javax.comm.properties</code> into the
CruiseControl lib directory, overwriting the
existing <code>comm.jar</code> file.Then
extract <code>commapi/lib/libLinuxSerialParallel.so</code>
and point <code>LD_LIBRARY_PATH</code> to it, like so:
<pre><code>export LD_LIBRARY_PATH=$HOME/commapi/lib${LD_LIBRARY_PATH+:$LD_LIBRARY_PATH}</code></pre></li>
<li>Add the x10 publisher to CruiseControl's config.xml.
For example, on Windows:
<pre><code><x10 houseCode="A" deviceCode="3" port="COM1" /></code></pre>
On Linux:
<pre><code><x10 houseCode="A" deviceCode="1" interfaceModel="cm17a" port="/dev/ttyS0" /></code></pre></li>
</ol>
<p>For more information about the CM11A controller, see <a
href="http://www.smarthome.com/1140.html">http://www.smarthome.com/1140.html</a>
or <a
href="http://www.x10.com/automation/x10_ck11a_1.htm">http://www.x10.com/automation/x10_ck11a_1.htm</a>.
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 <a
href="http://www.x10.com/support/basicx10.htm">http://www.x10.com/support/basicx10.htm</a>.</p>
<p>This module uses a pure Java implementation of the CM11A and CM17A
communication protocol as implemented by Jesse Peterson,
<a href="http://www.jpeterson.com/">http://www.jpeterson.com/</a>. To read
more about his library, see <a
href="http://www.jpeterson.com/rnd/x101.0.1/Readme.html">http://www.jpeterson.com/rnd/x101.0.1/Readme.html</a>.</p>
<p>The jpeterson library requires that the Java Communications API be
installed. For more information on the COMM API, see <a
href="http://java.sun.com/products/javacomm/index.jsp">http://java.sun.com/products/javacomm/index.jsp</a>.
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 <code>JAVA_HOME/bin</code> directory.</p>
<p>NOTE: If you receive the following error:</p>
<p><code>Error loading win32com: java.lang.UnsatisfiedLinkError: no
win32com in java.library.path</code></p>
<p>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).</p>
<p>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.</p>
<p>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.</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>houseCode</td>
<td>Yes</td>
<td>The house code for the device to control, A through P case insensitive</td>
</tr>
<tr>
<td>deviceCode</td>
<td>Yes</td>
<td>The device code for the device to control, 1 -> 16</td>
</tr>
<tr>
<td>port</td>
<td>No (defaults to COM2)</td>
<td>Serial port to which the computer interface controller is connected, e.g. COM1</td>
</tr>
<tr>
<td>onWhenBroken</td>
<td>No (defaults to true)</td>
<td>Set to false if the device should turn on when the build is successful and off when failed</td>
</tr>
<tr>
<td>interfaceModel</td>
<td>No (defaults to CM11A)</td>
<td>Model number for the computer interface controller being used, either CM11A or CM17A (case
insensitive).</td>
</tr>
</tbody>
</table>
<h3>Examples</h3>
<pre><!--Turn on X10 device(s) A3 using a CM11A computer interface on COM2
whenever the build breaks.-->
<x10 houseCode="A" deviceCode="3"/></pre>
<pre><!--Turn on X10 device(s) P12 using a CM11A computer interface on COM2
whenever the build breaks.-->
<x10 houseCode="P" deviceCode="12"/></pre>
<pre><!--Turn on X10 device(s) A3 using a CM11A computer interface on COM1
whenever the build breaks.-->
<x10 houseCode="A" deviceCode="3" port="COM1"/></pre>
<pre><!--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"/></pre>
<pre><!--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"/></pre>
<pre><!--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"/></pre>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="xsltlogpublisher"><xsltlogpublisher></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#publishers"><publishers></a>
<xsltlogpublisher></pre>
</div>
<p>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.</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>directory</td>
<td>Yes</td>
<td>Directory for output file</td>
</tr>
<tr>
<td>outfilename</td>
<td>No</td>
<td>Name for the output file. Default uses the build label, 'label.log'</td>
</tr>
<tr>
<td>publishonfail</td>
<td>No (defaults to true)</td>
<td><b>Deprecated. Use <a href="#onsuccess"><onsuccess></a> and
<a href="#onfailure"><onfailure></a> instead.</b><br/>
Generate file if the build failed?</td>
</tr>
<tr>
<td>xsltfile</td>
<td>Yes</td>
<td>XSL file to used for the transform.</td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="yahoopublisher"><yahoopublisher></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#publishers"><publishers></a>
<yahoopublisher></pre>
</div>
<p>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
<a href="http://jymsg9.sourceforge.net/">http://jymsg9.sourceforge.net/</a>.
</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>username</td>
<td>Yes</td>
<td>Username of the account used to send the instant message. For individuals,
this is typically of the form 'foo' as opposed to 'foo@yahoo.com'</td>
</tr>
<tr>
<td>password</td>
<td>Yes</td>
<td>Password of the sender account</td>
</tr>
<tr>
<td>recipient</td>
<td>Yes</td>
<td>Username of the recipient of the instant message. Recipient username
is typically of the form 'foo' as opposed to 'foo@yahoo.com'</td>
</tr>
<tr>
<td>buildresultsurl</td>
<td>Yes</td>
<td>Email will include link to the build results.</td>
</tr>
<tr>
<td>proxyHost</td>
<td>No</td>
<td>HTTP proxy to use.</td>
</tr>
<tr>
<td>proxyPort</td>
<td>No</td>
<td>HTTP proxy port to use.</td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="dateformat"><dateformat></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<dateformat></pre>
</div>
<p>The optional <code><dateformat></code> element overrides the
default date format for presentation. If this element is not specified,
the default date format is "<code>MM/dd/yyyy HH:mm:ss</code>".</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>format</td>
<td>Yes</td>
<td>A DateFormat String that specifies the date format for
presentation.</td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="plugin"><plugin></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<plugin>
<a href="#project"><project></a>
<plugin></pre>
</div>
<p>A <code><plugin></code> element registers a classname with an
alias for use within the configuration file.</p>
<p>Plugins can also be <a href="plugins.html#preconfiguration">pre-configured</a>
at registration time. This can greatly reduce the configuration file size.</p>
<p>The <a href="plugins.html">plugins</a> page contains a discussion of
the plugin architecture used with CruiseControl.</p>
<h3>Attributes</h3>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>name</td>
<td>Yes</td>
<td>The alias used to refer to the plugin elsewhere in the
configuration file.</td>
</tr>
<tr>
<td>classname</td>
<td>Yes</td>
<td>The class that implements the plugin.</td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="labelincrementer"><labelincrementer></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<labelincrementer></pre>
</div>
<p>Handle incrementing the label used to tag each build.</p>
<h3>Attributes</h3>
<p>The following attributes are valid for the default label incrementer.
If the label incrementer plugin is overridden, other attributes may be
applicable.</p>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>defaultLabel</td>
<td>No (default to "build.1")</td>
<td>set label to use if there is no saved label.</td>
</tr>
<tr>
<td>preBuildIncrementer</td>
<td>No (defaults to false)</td>
<td>if <code>true</code> the build number will be incremented
prior to the build attempt and thus each build attempt will have
a unique build number.</td>
</tr>
<tr>
<td>separator</td>
<td>No (defaults to period <code>'.'</code>)</td>
<td>specifies the separator to use between label and build
count.</td>
</tr>
</tbody>
</table>
<h3>Overriding the Default Label Incrementer</h3>
<p>If this element is not specified, the default label incrementer will
use the format <code>string.number</code>, providing the default label of
<code>build.1</code>.</p>
<p>To override the label incrementer used in a given project all you
need to do is register a different class as a <a href="#plugin">plugin</a>
with the name <code>labelincrementer</code>. Alternate label incrementer plugins distributed with
CruiseControl include:</p>
<h4>CVSLabelIncrementer</h4>
<p>An extension of the default label incrementer but with the separator
set to "-" by default. Provides default label of "build-1".</p>
<pre>
<plugin name="labelincrementer"
classname="net.sourceforge.cruisecontrol.labelincrementers.CVSLabelIncrementer"/></pre>
<h4>EmptyLabelIncrementer</h4>
<p>Always returns a label of "" (empty string).</p>
<pre>
<plugin name="labelincrementer"
classname="net.sourceforge.cruisecontrol.labelincrementers.EmptyLabelIncrementer"/></pre>
<h4>FormattedLabelIncrementer</h4>
<p>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.</p>
<pre>
<plugin name="labelincrementer"
classname="net.sourceforge.cruisecontrol.labelincrementers.FormattedLabelIncrementer"/></pre>
<h4>P4ChangelistLabelIncrementer</h4>
<p>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.</p>
<p>Even though the <a href="#p4bootstrapper">Perforce Bootstrapper</a>
handles synchronizing, this will execute before the <a href="#p4">p4
modification check</a> 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 <code>noSync</code> to <code>true</code>.</p>
<p>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
<code>changelist</code> attribute to the desired number. Whichever
of these is chosen, the synchronize step (if enabled) will sync
to this changelist number.</p>
<p>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 <code>delete</code> to <code>true</code>.
This will force the local clients to be removed first (ala
<code>sync <em>view</em>#0</code>), and after deleting the files will
perform the above synchronize.</p>
<p>Removing the local client files (sync #0) can be done without
deleting the files by setting the <code>clean</code> attribute
to <code>true</code>.</p>
<h5>Attributes</h5>
<pre>
<plugin name="labelincrementer"
classname="net.sourceforge.cruisecontrol.labelincrementers.P4ChangelistLabelIncrementer"/></pre>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>changelist</td>
<td>No</td>
<td>set the changelist number to sync to. Not specifying this
value will sync to the most recently committed changelist.</td>
</tr>
<tr>
<td>port</td>
<td>Yes</td>
<td>Perforce Server connection to use (host:port)</td>
</tr>
<tr>
<td>client</td>
<td>Yes</td>
<td>Perforce Client name to use</td>
</tr>
<tr>
<td>user</td>
<td>Yes</td>
<td>Perforce User name to use</td>
</tr>
<tr>
<td>passwd</td>
<td>No</td>
<td>Perforce password to use</td>
</tr>
<tr>
<td>view</td>
<td>Yes</td>
<td>Valid Perforce view (i.e. a depot path)</td>
</tr>
<tr>
<td>separator</td>
<td>No (defaults to period <code>'.'</code>)</td>
<td>specifies the separator to use between label and build
count.</td>
</tr>
<tr>
<td>noSync</td>
<td>No (defaults to <code>false</code>)</td>
<td>enable to turn off synchronizing the depot to the
label (changelist) number.</td>
</tr>
<tr>
<td>clean</td>
<td>No (defaults to <code>false</code>)</td>
<td>syncs the view to revision 0, which removes the current
files from the local hard drive and also tells the server that
the client no longer has those files. Enabling this will
also force the noSync to be false.</td>
</tr>
<tr>
<td>delete</td>
<td>No (defaults to <code>false</code>)</td>
<td>deletes any remaining files from the view that the clean
step missed. Enabling this will also force the clean to occur,
and the noSync to be false.</td>
</tr>
</tbody>
</table>
<h4>PropertyFileLabelIncrementer</h4>
<p>Returns a value for the label from a property file.</p>
<h5>Attributes</h5>
<pre>
<plugin name="labelincrementer"
classname="net.sourceforge.cruisecontrol.labelincrementers.PropertyFileLabelIncrementer"/></pre>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>defaultlabel</td>
<td>No</td>
<td>value to return if property file doesn't exist. if not specified and file doesn't exist
an exception is thrown.</td>
</tr>
<tr>
<td>propertyfile</td>
<td>Yes</td>
<td>the property file to read.</td>
</tr>
<tr>
<td>propertyname</td>
<td>Yes</td>
<td>the name of the property to read for the value of the label.</td>
</tr>
</tbody>
</table>
<h4>SVNLabelIncrementer</h4>
<p>Returns a value for the label based on the SVN revision number.</p>
<h5>Attributes</h5>
<pre>
<plugin name="labelincrementer"
classname="net.sourceforge.cruisecontrol.labelincrementers.SVNLabelIncrementer"/></pre>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>workingcopypath</td>
<td>No (defaults to <code>.</code>)</td>
<td>Path to the SVN working copy</td>
</tr>
<tr>
<td>labelprefix</td>
<td>No (defaults to <code>svn</code>)</td>
<td>Prefix for the label</td>
</tr>
<tr>
<td>separator</td>
<td>No (defaults to <code>.</code>)</td>
<td>The separator to use between label and build count</td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="currentbuildstatusftppublisher"><currentbuildstatusftppublisher></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#publishers"><publishers></a>
<currentbuildstatusftppublisher></pre>
</div>
<p>Note: this plugin has been made obsolete by the
<a href="#currentbuildstatusftplistener"><code>currentbuildstatusftplistener</code></a>.</p>
<p>This performs the same action as
<a href="#currentbuildstatuspublisher"><code><currentbuildstatuspublisher></code></a>,
except that the status file is sent to the remote site via FTP, instead
of being stored locally.</p>
<h3>Attributes</h3>
<p>In addition to the <a href="#ftpattributes">common FTP attributes</a>,
<code><currentbuildstatusbootstrapper></code> uses the following
attributes.</p>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>file</td>
<td>Yes</td>
<td>The filename to write.</td>
</tr>
<tr>
<td>destDir</td>
<td>Yes</td>
<td>The remote directory (relative to <code>targetDir</code>) to write the file.</td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="ftppublisher"><ftppublisher></a></h2>
<div class="hierarchy">
<pre>
<a href="#cruisecontrol"><cruisecontrol></a>
<a href="#project"><project></a>
<a href="#publishers"><publishers></a>
<ftppublisher></pre>
</div>
<p>Copies the XML log file from the build, and all files published by
<a href="#artifactspublisher"><code><artifactspublisher></code></a>,
onto the FTP server. To publish the artifacts, the
<code><artifactspublisher></code> element must occur before this
publisher in the configuration file.</p>
<h3>Attributes</h3>
<p>In addition to the <a href="#ftpattributes">common FTP attributes</a>,
<code><ftppublisher></code> uses the following
attributes.</p>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>destDir</td>
<td>Yes</td>
<td>The remote directory (relative to <code>targetDir</code>)
to publish the files.</td>
</tr>
<tr>
<td>srcDir</td>
<td>Yes</td>
<td>To publish the XML log file, this must be the same as the <code>dir</code> attribute of the
<a href="#log"><code><log></code></a> element. To publish
the artifacts, this must be the same as the
<a href="#artifactspublisher"><code><artifactspublisher></code></a>
directory.</td>
</tr>
<tr>
<td>deleteArtifacts</td>
<td>No (defaults to false)</td>
<td>If <code>true</code>, then all files successfully sent to
the FTP server will be deleted locally.</td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="ftpattributes">Common FTP Attributes</a></h2>
<p>The following attributes are common to the
<a href="#currentbuildstatusftpbootstrapper"><code><currentbuildstatusftpbootstrapper></code></a>,
<a href="#currentbuildstatusftppublisher"><code><currentbuildstatusftppublisher></code></a> and the
<a href="#ftppublisher"><code><ftppublisher></code></a>.</p>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>targetHost</td>
<td>Yes</td>
<td>Host name of the FTP server.</td>
</tr>
<tr>
<td>targetUser</td>
<td>No (defaults to <code>anonymous</code>)</td>
<td>The user used for logging into the FTP site.</td>
</tr>
<tr>
<td>targetPasswd</td>
<td>No (default to <code>eat@joes.com</code>)</td>
<td>The password used during FTP log in for the
<code>targetUser</code>.</td>
</tr>
<tr>
<td>targetPort</td>
<td>No (defaults to 21)</td>
<td>Port number of the FTP server.</td>
</tr>
<tr>
<td>targetDir</td>
<td>No (defaults to <code>'.'</code>)</td>
<td>Base directory in the FTP server to put the files.</td>
</tr>
<tr>
<td>targetSeparator</td>
<td>No (defaults to '<code>/</code>'.</td>
<td>Directory separator character used by the FTP server.</td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="xpathawarechildattributes">XPath Aware Child Attributes</a></h2>
<p>The following attributes are common to the xpath aware children found in
<a href="#sfeetracker"><code><sfeetracker></code></a> and
<a href="#sfeedocman"><code><sfeedocman></code></a>.</p>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>value</td>
<td>One of <code>value</code> or <code>xpathExpression</code> must be specified. </td>
<td>A fixed value that will not change at runtime.</td>
</tr>
<tr>
<td>xpathExpression</td>
<td>One of <code>value</code> or <code>xpathExpression</code> must be specified. </td>
<td>An xpath expression to evaluate against the CruiseControl log file, or the xml file
as specified by <code>xmlFile</code> attribute. The result of the expression will be
used as the value.</td>
</tr>
<tr>
<td>xmlFile</td>
<td>No (defaults to the CruiseControl build log). </td>
<td>Path to a file on the local filesystem against which the
<code>xpathExpression</code> will be evaluated.</td>
</tr>
</tbody>
</table>
</div>
<div class="elementdocumentation">
<a class="toplink" href="#top">top</a>
<h2><a name="namedxpathawarechildattributes">Named XPath Aware Child Attributes</a></h2>
<p>The same attributes as found in the <a href="#xpathawarechildattributes">XPath Aware Child Attributes</a>
and one additional attribute to specify a name.
</p>
<table class="documentation">
<thead>
<tr>
<th>Attribute</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>name</td>
<td>Yes </td>
<td>The name of a field in the tracker artifact.</td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
</body>
</html>
