CC.net===============cc.net is having following :build loop and result jsp and dash board and distributed.

Build loopInstall

If you examine the code you just downloaded, there will be a build.bat (for Windows users) and a build.sh (for UNIX users) present in the cruisecontrol/main directory. Execute the appropriate script, and CruiseControl should compile. Look in the dist directory, and you should find cruisecontrol.jar, cruisecontrol-launcher.jar, and cruisecontrol-antprogresslogger.jar files if the build was successful.

All of the cruisecontrol configuration exists in a single config file. If you're new to cruisecontrol, you'll have to create this file;

CruiseControl can be started using two approaches:

Scripts. bin/cruisecontrol.bat or bin/cruisecontrol.sh.This is the preferred approach, since the scripts will take care of providing you with the correct classpath and such.

Executable jar. Type the following command: java -jar dist/cruisecontrol-launcher.jar

Plugins:

Plugins

Introduction

It's tough to imagine all of the ways that CruiseControl can be used. Different tools and subtle nuances in team style make it difficult to code a "one-size-fits-all" solution. As a result, CruiseControl has been designed as a small core with a very high-level implementation of continuous integration, with most of the implementation details delegated to plugins. This makes it easy to create new functionality, modify existing functionality, or remove unwanted functionality. Plugins also create a shallower learning curve when digging in the codebase, as you can be assured that all of the cvs functionality, for example, exists in one place. Encapsulating all of the functionality into plugins also makes testing easier.

1. Design overview 2. Types 3. Initialization

o Plugin configuration o Plugin validation

4. Execution 5. Registration

6.o Preconfiguration

7. Plugin XML Documentation 8. Default Registry

Plugin Design Overview

Plugins are represented by beans. Plugin classes are mapped to element names in the XML config file thanks to a process known as registration. Plugins distributed with cruisecontrol are all registered by default.

The configuration will be initiated by the ProjectXMLHelper class which handles the mapping of the registered plugin and delegates the plugin initialization to the PluginXMLHelper class. Once configured, the plugin is validated, and executed at the appropriate time in the build cycle. This execution time will depend on the plugin type.

Plugin Types

There are currently six different types of plugins that CruiseControl supports. Each has a slightly different role, but all are designed similarly. While they all implement different interfaces and have slightly different method names, we will refer to them collectively as plugins when discussing their similarities. The plugin types are:

Bootstrapper : run before the build SourceControl : poll a code repository and determine if anything has changed Builder : perform the actual building and testing of your code LabelIncrementer : handles incrementing the label for you to use to tag your

source Publisher : publish the results of your build, via email for example Listener : handles project events

Plugin Initialization

The PluginXMLHelper will use introspection to configure the bean.

Plugin configuration

In the case of normal initialization, the PluginXMLHelper will call setter methods that correspond to attributes on your xml tag in the config file. For example, the method setTarget(String target) on the AntBuilder class corresponds to the attribute target on the <ant/> element in the config file. The parser is case insensitive, so the case need not match from your attributes to your method names, so the standard capitalization rules should apply.

It is possible for you to declare nested elements within your plugin's declaration in the config file. In this case, CruiseControl will expect your plugin class to implement an add or create method for each nested element, depending whether your nested element is itself a plugin or not:

for nested elements that are also plugins, the PluginXMLHelper doesn't know to which class the element should map and then asks the ProjectXMLHelper to configure the element.

for simple (non plugins) nested elements, the plugin knows the type that will map to the config element name. Returning to our example AntBuilder class, we will see a createJVMArg() method. We'll also see that AntBuilder has a nested JVMArg class. This create method is responsible for creating an instance of JVMArg and keeping a reference to that object for AntBuilder to use later. It returns a reference to the newly created JVMArg object, so that PluginXMLHelper can configure the nested element in the same way as the parent element. In theory, there is no limit to the depth of your nesting, as long as the appropriate create methods have been written.

Plugin Validation

Immediately after the parser has configured your plugin, we will validate the plugin using it's own validate() method. This will enable us to fail quickly if your plugin has been incorrectly configured, saving you the time of waiting for your plugin to execute to determine whether your CruiseControl installation has been successful.

Plugin Execution

After we have configured and validated all of the plugins, we will begin executing them according to their type. Each plugin has an "action" method that is the one method that CruiseControl will call when executing your plugin. Let's take the example of the bootstrappers. At the beginning of the build cycle, the first thing that we need to do is to run the bootstrappers. We've already initialized and validated each of these, so now we will just call the bootstrap() method as we iterate over the list of registered bootstrappers. It's fairly similar for each of the other types of plugins.

Plugin Registration

The registration of plugins is a simple and straightforward task. Directly under the <cruisecontrol> element, or within a <project> element, simply add a <plugin name="" classname=""/> element, where the name corresponds to the name you wish to use within the config file, and the classname corresponds to the actual plugin Java class.

Plugins specified directly under the root element will be available to all your projects, plugins under a project element will be only available within that project. This is useful to override a plugin like the labelincrementer for a single project.

In the interest of keeping config file sizes to a minimum, all plugins that ship with CruiseControl will be automatically registered. Should you wish to use one of the registered plugin names with your own custom plugin class, you can just explicitly register the plugin name and that will override the default registration.

Plugin Preconfiguration

On registering plugins, you can also define default values for some of the properties and nested elements of the plugins. You can do this by simply using the same attributes and child nodes as you would when using the plugin itself.

Defaults can be overridden when you actually use the plugin within a project. Note: when nested elements have a multiple cardinality, overriding an already pre-configured child element might accumulate them.

If you want to preconfigure an already registered plugin (whether default plugin, or plugin registered at the root of the config), you may leave out the classname attribute of the plugin element.

An example: to define some default values for the htmlemail publisher, you can specify something like this in your config file:

<plugin name="htmlemail" mailhost="smtp.example.com" returnaddress="buildmaster@example.com" subjectprefix="[CC]" xsldir="C:\java\cruisecontrol-2.2.1\report\jsp\webcontent\xsl" css="C:\java\cruisecontrol-2.2.1\report\jsp\webcontent\css\cruisecontrol.css"> <always address="project-dev@domain.com"/> <plugin/>

Combined with ant style properties this can greatly reduce the size of your config files. In the extreme case you can create a template project where all that needs to be supplied is the project name:

<cruisecontrol> <plugin name="project"> <bootstrappers> <cvsbootstrapper localworkingcopy="projects/${project.name}"/> </bootstrappers> ... </plugin>

<project name="foo" /> <project name="bar" /> ...</cruisecontrol>

More information and examples can be found on the wiki.

Plugin XML Documentation

The config reference is automatically generated from comments and tags contained in the plugins code.

Here's a simple self-commented example: /** * This will make it into the plugin description. * <p>You can also have HTML code </p> * @cc-plugin * @see other javadoc tags are not taken into account. */public class MyPlugin { /** The default value is automatically identified whenever possible */ private String myField = "defaultValue";

/** * A comment that will describe the entry in the parameter table for the plugin. * @required "the comment that will make it into the required column" * @defaultValue "forceDefaultValue" */ public void setMyField(String myField) { this.myField = myField; }

/** * A comment that will describe the entry in the Child table for the plugin. * @cardinality 0..* */ public void addObject(Object object) { ... }}

Build Results JSP Installation Guide

Note that this is a brief guide to installation from the source code. For basic CruiseControl installation, go to the Getting Started page.

Getting The Source

If you have Subversion installed, you can get the entire CruiseControl source by running: svn checkout https://cruisecontrol.svn.sourceforge.net/svnroot/cruisecontrol/trunk/cruisecontrol

Once you have obtained the source, you should have a reporting/jsp directory that contains the following:src - The source for the JSP custom tagstest - JUnit Tests for the JSP custom tagsdocs - This manualdist - Output directory for the cruisecontrol.war distributableimages - Images used by the buildresults.jsplib - 3rd party libraries

Configuring

The WEB-INF/web.xml file holds the required configuration for the JSP. There are currently 2 parameters that need to be set. The first is the path to the log directory. This is required so that the JSP can read the CruiseControl log files to build the left-hand navigation. The second is the path to the current build status file. This is the file that is written by the CruiseControl build loop to let the JSP know whether it is currently building, or when the next build will occur.

You can edit them directly in the WEB-INF/web.xml file, or you can set them when you build the WAR file

Depending on the version of the JSP specification that is implemented by your app server, you may need to make one minor edit to the buildresults.jsp file. If you are using a server that is JSP 1.2 compliant, you will need to change the second line after the license text from:

<%@ taglib uri="/WEB-INF/cruisecontrol-jsp11.tld" prefix="cruisecontrol"%>to: <%@ taglib uri="/WEB-INF/cruisecontrol-jsp12.tld" prefix="cruisecontrol"%>

It is also possible to configure the date format used in the navigation links. To change this, we'll need to edit the navigation.jsp itself. On the <cruisecontrol:nav> tag, we can add the dateFormat attribute. Then we can set this value to be whatever we choose, as long as it's a valid date format as recognized by Java.

Building

CruiseControl uses Ant to build and package the build results web application. Everything you need to build has been included with the source that you obtained from Subversion. There is a batch file and a shell script (build.bat and build.sh respectively) provided to make building the CruiseControl web application as easy as possible. The configured cruisecontrol.war file has been created in the dist directory.

You can include options to configure the log directory, status file, and artifacts directory that you wish to use. The properties to set are user.log.dir, user.build.status.file, and cruise.build.artifacts.dir. An example (for Windows) of doing this would be:

build.bat -Duser.log.dir=C:\Cruise\logs -Duser.build.status.file=status.txt-Dcruise.build.artifacts.dir=C:\Cruise\logs

For repeated builds a more convenient method of supplying the values you wish to use is to supply them in a file named override.properties. If a file with this name exists the properties defined within will be used when building the war file.

Deploying

Tomcat

Copy the cruisecontrol.war file from the dist directory to the %TOMCAT_HOME%/webapps directory. Then startup the server by going to the %TOMCAT_HOME%/bin directory and using the startup script. The cruisecontrol web application should deploy and you should be able to test it out by opening a web browser and going to:

http://localhost:8080/cruisecontrol/buildresults

Build Results JSP Customization

Build parameters

Three configuration settings are specified when building the reporting applications. See the Building section of the Installation Guide

System properties

The binary release uses System properties to pass the value of commandline arguments from the main CruiseControl process to the Reporting application.

ccnameName for this CruiseControl instanceThe binaryrelease sets this to the -ccname value given as a commandline argument

cruisecontrol.jmxportport where the CruiseControl JMX agent's HTTP adaptor is listening.Default value is 8000. The binaryrelease sets this to the -jmxport value given as a commandline argument (by default 8000)

cruisecontrol.jmxhosthost where the CruiseControl JMX agent's HTTP adaptor is listeningIf not specified CruiseControl will trying to guess the host name running the reporting application

cruisecontrol.rmiportport where CruiseControl JMX agent's RMI adaptor is listening. If specified enables the experimental configuration editor.The binaryrelease sets this to the -rmiport value given as a commandline argument

Deployment descriptor (web.xml)

The JSP reporting application uses context parameters and servlet init parameters configuration and customization. These parameters can be edited in the web.xml file directly. Some Web Containers like Tomcat allow the default values to be override without changing the web.xml or the war file.

Context parameters

cacheRootFull path to a directory where caches of XSL transformations are written. The web context must have permission to write to this directory. If not specified, caches will be written in a subdir called _cache of the logDirThe binaryrelease does not specify this parameter

logDirThis should be the full path to your CruiseControl log directory. If you are in single project mode, this will contain only the logs for your project. If you are in multi-project mode, it is expected that you will have multiple sub-directories inside this log directory, one for each project.The default default value is the build parameter user.log.dir. The binary release sets this to logs

singleProject

Indicates if the CruiseControl instance is to report on only one project. If it is, then you should set this to true.The default value is false

currentBuildStatusFileThis should be the name to your current build status file as generated by the currentbuildstatuslistener, which is located to the projects log directory.The default default value is the build parameter user.build.status.file. The binary release sets this to status.txt

fileServlet.welcomeFilesThe list of space separated index files that should be automatically displayed when browsing a directory displayed by the file servlet. The order matters. Let empty or comment out to disable indexes.The default values are: index.htm index.html

cruisecontrol.jmxhostThe host for the JMX HttpAdaptor to which CruiseControl will connect for forcing builds and viewing the control panel. The parameter may be overridden using the system property with the same name.The default value is: localhost

cruisecontrol.jmxportThe port for the JMX HttpAdaptor to which CruiseControl will connect for forcing builds and viewing the control panel. The parameter may be overridden using the system property with the same name.The default value is: 8000

xslt.*any context parameter that starts with xslt. will be pass to the XSL stylesheets as a XSLT parameter without the xslt. prefix. See XSLT parameters

Servlet init-param

Beside the context parameters the ArtifactServlet takes an init parameter

rootDirThe absolute path to the directory where additional build artifacts are stored. If this is not specified the logDir context parameter will be usedThe default default value is the build parameter cruise.build.artifacts.dir. The binary release sets this to artifacts

XSLT parameters

Some of the XSL stylesheets can be configured using XSLT parameters. These parameters are configured as context parameters with a xslt. prefix, that is XSLT Parameter viewcvs.url is configured a context parameter xslt.viewcvs.url

pmd.warning.thresholdPMD violations with a priority below this threshold are considered warnings and are only reported by the total count on the build results page. This is not specified by default

viewcvs.urlThe URL of the ViewCVS website used by cvstagdiff.xsl, checkstyle-details.xsl and pmd-details.xslThis is not specified by default

cvstagdiff.success.showControls whether the ViewCVS differences report should be shown when the build was successful. The default is to only show the modifications report for broken buildstrue

checkstyle.hide.warningsControls whether only CheckStyle errors or all CheckStyle errors and warnings should be listed on the build results page. Set to 'true' for hiding the warnings. The default is to list all errors and warnings.

This is not specified by default

==

Dash board

How to create a build grid with CruiseControl

What is a build grid?

A build grid consists of several independent build loops reporting to a single dashboard application. It is not a true distributed CruiseControl -- for this, see the page on the distributed builder or check out the various distributed solutions on the CruiseControl Wiki. See 'Requirements and limitations' below for more on what you can and can't do with a build grid as described in this section.

Requirements and limitations

In order to use this functionality, you need CruiseControl 2.7.2 or higher. This version of CruiseControl contains functionality that enables the build loops to post their status to the dashboard via HTTP, and which allows the dashboard to talk to multiple build loops via JMX.

Limitations: You will have to set up some form of shared filesystem to allow the build

loops to write their logs and artifacts to a single directory structure. This directory structure will also be used by the dashboard to read the log files that the build loops create. You could use a Windows share or a Samba server (SMB/CIFS), or an NFS mount to do this.

You must configure each build loop separately. Each build loop needs its own configuration file with the projects that that specific build loop will be building.

For the force build, remote JMX console and active build output functionality to work, all the build loops must have their hostname resolve correctly from the computer the dashboard is on. However the dashboard will still be able to report the status of the build loops even if it cannot resolve their hostnames.

Deploying the dashboard and build loop

First you will need to set up the dashboard. You have two options for this: you can either have it on its own server, or you can have one of the build loop servers host the dashboard. In either case, the simplest option is just to deploy CruiseControl the way you would normally. Follow the instructions in the Getting Started section.

Once you have CruiseControl installed on all your servers, you will need to make sure the shared filesystem is mounted and accessible on all of them.

Configuration

The first job is to configure the projects on the various CruiseControl build loops. This includes making sure that logs and artifacts are published to the shared filesystem.

Once you've done this, you need to tell the build loop which dashboard to send information to. You do this by setting the -dashboardurl command-line parameter as described here. Any problems connecting will be logged to the build loop's console. Assuming everything goes to plan, the dashboard that you specify using this url should start picking up information from the build loops straight away.

Common problems and how to solve them

I can't force build or access the JMX console from the dashboard

In order for force build and the JMX console to work, the dashboard must be able to connect to the build loops using the host information sent to the build loop by the dashboard. To check whether this is the case, you can hover over the project in question on the dashboard, and see the hostname that the build loop is advertising. You should then log in to the dashboard server and check to see if that hostname resolves correctly. If not, you will need to fix this problem by updating your server's DNS server, or by editing the server's hosts file.

On Debian and Ubuntu systems, there is a problem whereby if a build loop has its hostname set to 127.0.0.1, the dashboard remote control (force build and active build output) won't work. In order to resolve this problem, you need to edit the hosts file to put the machine's actual IP address with its hostname, and ensure this is the first entry in the hosts file.

The dashboard indicates that my projects are still running, but they seem to be 'stuck'

If an entire build loop crashes, or its posts stop reaching the dashboard due to a network problem, the dashboard will simply wait until the next post, even if it never comes. Once you re-start the build loop, you need to take no further action. If you actually want to remove a whole build loop, you will need to re-start the dashboard in order to reset it.

Developer Guide: How to write a Widget?

What is a CruiseControl Widget?

A CruiseControl Widget is a customized component for displaying arbitrary build result in the detail page of a build.

The CruiseControl binary build ships with a Panopticode Widget which allows SVG results generated by Panopticode to be displayed.

Widget Setup

To enable a widget, you should edit the widget's configuration file located at CRUISE_HOME/widgets.cfg.

#simply type the name of widget classnet.sourceforge.cruisecontrol.dashboard.service.PanopticodeWidget

Make sure that you configure CruiseControl properly that it can copy the svg files into desired location as artifact: $ARTIFACTS_ROOT/{project name}/{build}/interactive-complexity-treemap.svg and $ARTIFACTS_ROOT/{project name}/{build}/interactive-coverage-treemap.svg

Using Widgets

From the build detail page you can see an additional tab named Panopticode Summary. If the project build has Panopticode output, charts will be shown as below.

Note that we are now only providing an SVG formatted report so you will need to have an SVG browser plugin installed. Firefox supports SVG by default. You may need to setup adobe SVG viewer for IE.

Implement your own Widget

You can also implement your own favourite widgets by implementing the following interface:

package net.sourceforge.cruisecontrol.dashboard.widgets;

import java.util.Map;

/** * <pre> * Widget is designed to help faciliate developers to contribute new output services, * like emma, checkstyle, panopticode. the main function is getOutput which takes Map as parameter, * CruiseControl reporting will pass in embedded values with keys: * * PARAM_PJT_ARTIFACTS_ROOT : Artifacts root of project, e.g. artifacts/project1 * PARAM_BUILD_ARTIFACTS_ROOT : Artifacts root of build, e.g. artifacts/project1/20051209122103 * PARAM_CC_ROOT : Parent folder of config.xml * PARAM_PJT_NAME : Name of project e.g. project1 * PARAM_PJT_LOG_ROOT : Root of project log e.g.logs/project1 * PARAM_BUILD_LOG_FILE : Log file of build e.g. log20051209122103.xml * * <p> In order to enable your service in the system, go to the root directory of cruisecontrol, * and simply add/edit widgets.cfg to include the class name. e.g. com.foo.Class <p> * </pre> */

public interface Widget { /** * Widgets framework will associate artifacts root path with the following key.

*/ public static final String PARAM_PJT_ARTIFACTS = "PJT_ARTIFACTS"; /** * Widgets framework will associate artifacts root path of the build with the following key. */ public static final String PARAM_BUILD_ARTIFACTS_ROOT = "BUILD_ARTIFACTS_ROOT";

/** * Widgets framework will associate CruiseControl root path with the following key. */ public static final String PARAM_CC_ROOT = "CC_ROOT";

/** * Widgets framework will associate project name with the following key. */ public static final String PARAM_PJT_NAME = "PJT_NAME";

/** * Widgets framework will associate log root path with the following key. */ public static final String PARAM_PJT_LOG_ROOT = "PJT_LOG_ROOT";

/** * Widgets framework will associate log file name with the following key. */ public static final String PARAM_BUILD_LOG_FILE = "BUILD_LOG_FILE";

/** * CC Reporting system will pass in its web context root e.g. "/dashboard" */ public static final String PARAM_WEB_CONTEXT_PATH = "WEB_CONTEXT_ROOT";

/** * @param parameters all the parameters user defined in widget, besides the embedded values. * @return the Object to be displayed in the tab of build detail page */ public Object getOutput(Map parameters);

/** * The displayed title in tab view in build detail page. * * @return the name displaied in tab view. */ public String getDisplayName();

}

Distributed extensions

The distributed package is in the process of being merged into the core product.

Introduction

This "distributed" contrib package for CruiseControl allows a master build machine to distribute build requests to other physical machines on which the builds are performed and to return the results to the master.

In order to extend CruiseControl without requiring that our distributed extensions be merged in with the core CruiseControl code, we decided to add our code as a new contrib package. This complicates configuration a bit, but carefully following the following steps should have you distributing builds in no time. You should, however, already be familiar with CruiseControl if you expect to succeed with this more complex arrangement.

Overview

The distributed extensions make use of Jini for the service lookup and RMI features it provides. In addition to the usual CruiseControl startup the user will have to start up a Jini service registrar and HTTP class server. Also, each build agent machine will need to have code installed locally and will need to start up and register their availability with the registrar. Once a federation of one or more agents is registered with a running registrar, CruiseControl has the ability to distribute builds through a new DistributedMasterBuilder that wraps an existing Builder in the CC configuration file. Examples are given below. Doing distributed builds is seamless in CruiseControl and the user has the option of only distributing builds for projects they choose to distribute.

Compatibility with Prior Releases

If you will be distributing builds in an environment which includes Build Agents from CruiseControl version 2.6 or earlier, please see Upgrade Notes.

How-To

I. Building the codeA. Build CruiseControl in the usual way. (See getting started -> source

distribution to build from source.)B. In the contrib/distributed directory, run ant. The default target will

build the distributed extensions.

You need the ANT_HOME environment variable set, and a junit.jar available to to ant. Junit ant tasks don't work unless junit.jar is on ant's "boot" classpath. You can either copy a junit.jar file into your ANT_HOME/lib directory, or define the ANT_ARGS environment variable with a "-lib" directive pointing to a junit.jar. For example:

C. export ANT_HOME=~/devtools/apache-ant-1.6.5D. export ANT_ARGS="-lib ~/devtools/cruisecontrol/main/lib/junit-

3.8.2.jar"

You might need to set the JAVA_HOME environment variable if the JNLP API (javaws.jar) can not be located otherwise.

A new directory will be created called dist that contains a number of subdirectories (agent, builder, core, lookup, and util). Also, a file will be created called cc-agent.zip. The zip file contents are identical to the agent subdirectory. The zip file can easily be transferred to any machine you wish to serve as a build agent while the agent subdirectory can be used for testing by running a build agent locally. (Also see Java Web Start deployment of build agents.) After building, the distributed extensions tree will look similar to the example below. Directory comments prefixed with '*' will contain copies of some shared configuration files.

contrib/

conf/... (Shared configuration files - some of which are copied into dist sub dirs) dist/ (New directory created by builing distributed extensions)

agent/... (*Build Agent) builder/... (DistributedMasterBuilder class, used by master build loop). core/... lookup/... (*Lookup Service - aka: Registrar) util/... (*General utilites, including Agent Utility)

II. Basic Configuration

If you plan to rebuild the distributed extensions, note that any configuration files under the contrib/distributed/dist directory are liable to be cleaned and replaced. The originals reside in contrib/distributed/conf and you may find it preferable to change them there before you build the distributed extensions. In most cases, you should not have to edit any of these configuration files.

A. (Optional) In the contrib/distributed/conf directory there is a file entitled agent.properties. Though the default typically works, one property may need to be set in this file: cruise.build.dir should be set to the directory the build agent should consider its build directory. It will be treated as a temporary directory, though some caching may occur.

B. (Optional) In the contrib/distributed/conf directory you'll find the cruise.properties file. The default value of cruise.run.dir typically works, but can be set to the root directory for the master copy of the code and build results. That is, if you follow the canonical CC configuration, this should be the parent directory of your checkout, logs, and output directories. The logs and output directories will be automatically populated by the results sent back from the build agents.

C. Pre-populate your checkout directory with the projects you want to do distributed builds on, just as you would in a non-distributed CruiseControl scenario. Note that each agent must have all projects pre-populated unless you have configured specific builds to go to specific agents (more below). This is a limitation of the current architecture that would be nice to fix, possibly via distributed versions of Bootstrapper and/or Project plugins.

D. Register the Distributed Plugin - You must "register" the Distributed plugin in your config.xml as shown below. (If you forget to do this, while starting CC, you will see an error about no plugin registered for "distributed").

<plugin name="distributed" classname="net.sourceforge.cruisecontrol.builders.DistributedMasterBuilder"/>

E. Now change your CruiseControl configuration (config.xml) to do distributed builds for a project (see <distributed> and examples below).

top

<distributed>

<cruisecontrol> <project> <schedule> <distributed>

Execute the nested Builder on a remote Build Agent and optionally return build artifacts after the build completes.

The standard CruiseControl properties passed to builders are available from within the nested Builder

Attributes

Attribute Required Description

entries No

A semicolon-delimited list (key1=value1;key2=value2) used to find a matching agent on which to perform this build.

agentlogdir No

Build artifacts directory on remote Agent. All content of this directory is returned to the Master, and deleted after the build completes.

masterlogdir NoBuild artifacts directory on Master into which Agent artifacts will be moved. Typically included in log merge

agentoutputdir No

Another artifacts directory on the remote Agent. All content of this directory is returned to the Master, and deleted after the build completes.

masteroutputdir NoAnother artifacts directory on Master into which Agent artifacts will be moved. Typically included in log merge

showProgressNo (defaults to true)

If true or omitted, the distributed builder will provide progress messages, as will the nested builder if it supports this feature (assuming the nested builder's own showProgress setting is not false). If false, no progress messages will be shown by the distributed builder or nested builder - regardless of the nested builder's showProgress setting. If any parent showProgress is false, then no progress will be shown, regardless of the distributed or nested builder settings.

Child Elements

Element Cardinality Description

<builder> 1The nested <builder> to be executed on the remote Build Agent. See <composite> to execute multiple Builders.

<remoteResult> 0 .. *

Specifies additional artifacts directory. All content of this directory is returned to the Master, and deleted from the Agent after the build completes. The element has two required attributes: "agentDir" and "masterDir". The "masterDir" is typically included in log mergeExample: <remoteResult agentDir="target/site" masterDir="target/site"/>

Examples

1. Given an existing configuration snippet:

2.<schedule interval="30">3. <ant antscript="ant.bat"4. antworkingdir="C:/cruise-control/checkout/BasicJavaProject"

>5. </ant>

</schedule>

wrap the ant builder configuration with a <distributed> tag like this:

<schedule interval="30"> <distributed> <ant antscript="ant.bat" antworkingdir="C:/cruise-control-agent/checkout/BasicJavaProject" > </ant> </distributed></schedule>

Note: antscript and antworkingdir attributes now refer to locations on your agent. All agents must conform to these same settings.

The Project Name value determines where Build Agent work directories are created. These defaults can be overridden by setting 'agentlogdir' and 'agentoutputdir' attribs.

6. You may have noticed the user-defined.properties file in the conf directory for the agent. These properties are, as you might expect, user-defined. Any unique properties you would like to indicate characteristics of THIS SPECIFIC agent should be added here in canonical property form (i.e. "key=value", without the quotes). In the CC configuration file an attribute can be added to the <distributed> tag containing semicolon-delimited entries used to match this agent with the projects that should be built on it. For instance, changing the example above to:

7.<schedule interval="30">8. <distributed entries="agent.name=number2">

<ant antscript="ant.bat" ...

will ensure an agent with agent.name=number2 in its user-defined.properties file will be the recipient of this project's build requests. If multiple agents match a given set of entries, it is indeterminate which will receive the build request. For an agent to be considered a match, the agent must have at least all the entries defined for <distributed entries="...">. A matching agent may have more entries than those defined for <distributed entries="...">.

Even if no entries are listed in the user-defined.properties file, four entries are programatically registered with every agent. These are os.name, java.vm.version (which may show the hotspot version in java 1.6.0_04+), and java.version, containing the Java system properties of the same names, and hostname containing the hostname on which the agent is running. A more useful example than the previous one might be:

<distributed entries="os.name=Windows XP">

or

<distributed entries="os.name=Linux">

By configuring one project twice, with two different os.name properties, you could ensure that your project builds correctly on two different operating systems with only one instance of CruiseControl running. This requires two <project> configurations in your config.xml. Here's a more complex example:

<distributed entries="os.name=Windows XP;dotnet.version=1.1;fixpack=SP2">

9. Using the <composite> tag in your config.xml file allows multiple builders to run for a single <project>. The <composite> tag is a "composite builder" which defines a list of builders that will be executed sequentially and treated as a single build. The config below causes a set of ant builds to be performed sequentially on the same Build Agent:

10.<project ...>11. <schedule ...>12. <distributed entries="...">13. <composite>14. <ant (build 1)...>

<ant (build 2)...>

The exampe below will cause a set of builds to be performed sequentially on the different agents (each with a different OS). Both the Windows and Linux builds must complete successfully before the entire Composite Build is considered successful.

<project ...> <schedule ...> <composite> <distributed entries="os.name=Windows XP"> <ant (build 1)...> <distributed entries="os.name=Linux"> <ant (build 1)...>

15. By default, the canonical locations for log and output files are used on both the remote agents and the master. These can be overridden using the following attributes on the <distributed> tag:

16.<distributed17. agentlogdir="agent/log" masterlogdir="master/log"18. agentoutputdir="agent/output" masteroutputdir="master/output">19....

</distributed>

After a remote build, any files on the agent machine in dir "agent/log" will be copied back to the master machine into dir "master/log". The "logs" and "output" dirs will be deleted on the Agent after the build finishes.

NOTE: You may have problems when running a BuildAgent on the same machine as the main CC server due to the removal of the log/output dirs by the BuildAgent (if the main CC server needs the deleted directories). In such cases, you should override the cannonical artifact dirs using these tags.

III. Doing distributed builds

Linux Note: Many Linux distros include the hostname in /etc/hosts for the "127.0.0.1" address on the same line as "localhost.localdomain" and "localhost". This interferes with the operation of Jini (an Agent finds the Lookup Service, but the MasterBuilder or Agent Utility can not find the Agent). You may need to edit the /etc/hosts file as shown below to list the actual hostname and ip address:

# This is NOT jini friendly. #127.0.0.1 localhost.localdomain localhost ubuntudan

127.0.0.1 localhost.localdomain localhost # actual host ip address and host name 10.6.18.51 ubuntudan

A. Start the Lookup Service by navigating to the contrib/distributed/dist/lookup directory and running ant. The default target should start the registrar and class server.

B. Start the agent by navigating to the contrib/distributed/dist/agent directory and running ant. The default target should start the build agent and register it with the Lookup Service. Note: while there is no reason you couldn't have an agent running in your build master, additional agents will require you to copy the cc-agent.zip to each machine, unzipping and configuring for each of them. Another option is to use the webstart BuildAgent features - see Java Web Start deployment of build agents for details.

C. Test that Jini is running and your agent(s) is/are registered using the JiniLookUpUtility. In contrib/distributed/dist/util run ant test-jini. After 5 seconds you should see a list of services that have been registered with Jini. Since the Jini Lookup Service itself is a Jini service you should have com.sun.jini.reggie.ConstrainableRegistrarProxy listed even if you have no agents running. If you do have agents running, however, you should see a Proxy service listed for each of them, with BuildAgentService listed as the type. You can also test the availability of services (Lookup and BuildAgents) by using the Agent Utility

D. You can manually run a build using the InteractiveBuildUtility. This allows you to test your configuration without starting CruiseControl. In contrib/distributed/dist/util run ant manual-build. If the distributed tag in your configuration file does not contain any entries, you'll be prompted to enter them. These are optional, however, and pressing ENTER at the prompt will pick up whatever agent is available. Note that you can pass in the path to your CruiseControl configuration file as an argument to the InteractiveBuildUtility and save a step when running it. (Note: This ant target is not working [reading input from the command prompt isn't working in ant - any fixes?], but the class should work outside of ant.)

E. Start CruiseControl using the startup scripts (cruisecontrol.sh or cruisecontrol.bat) in: contrib/distributed. Any builds that are queued for a distributed builder should be sent to your running agent. Typically, CruiseControl is run from the /contrib/distributed directory (not main/bin), but this is not required. If CruiseControl can't find required jars, config files, etc, you may need to set the CCDIR environment variable to your CruiseControl/main directory before launching the contrib/distributed/cruisecontrol.bat/.sh file.

IV. Advanced configuration

A. If you plan to rebuild the distributed extensions, note that any configuration files under the contrib/distributed/dist directory are liable to be cleaned and replaced. The originals reside in contrib/distributed/conf and you may find it preferable to change them

there before you build the distributed extensions. Since user-defined.properties and agent.properties are copied into the cc-agent.zip you'll need to unzip and make your changes locally on the agent.

B. Jini as used in these distributed extensions has several configuration options. Beware of the start-jini.config, however--it is not likely you will need to make changes to it.1. As delivered, Jini uses an insecure security policy. Should you

choose to change this, create your own policy file(s) and change cruise.properties and agent.properties to reference your own versions. Note that the one copy of insecure.policy in contrib/distributed/conf is copied to the agent, lookup, and util subdirectories during the build.

2. Jini, being a Sun product, uses Java's native logging, not Log4j or Commons-Logging. Jini logging configuration is via the jini.logging file. As with insecure.policy, one copy of jini.logging is duplicated for the agent, lookup, and util. Either independently change these copies or change the original once. Note: The jini logging settings do not work when runing a Build Agent via Webstart.

3. If your local network does not have DNS services setup properly (ie: LAN hostnames are not resolved correctly), see the note: BAD DNS HACK in start-jini.config and transient-reggie.config. It is far better to fix your LAN DNS issues, check out other things (like the localhost issue), and only use the mentioned hard-coded DNS hack as a last resort. If you find no agents (including local ones) are being discovered, it is far more likely you have a mismatch between your Agent and config.xml entries settings.

C. To keep track of problems on remote Build Agents, you may want to alter the main CruiseControl log4j.properties file main/log4j.properties to use an "Email" logger to notify you of errors via email. For example:

D. log4j.rootCategory=INFO,A1,FILE,MailE. ...F.G. # Mail is set to be a SMTPAppenderH. log4j.appender.Mail=org.apache.log4j.net.SMTPAppenderI. log4j.appender.Mail.BufferSize=100J. log4j.appender.Mail.From=ccbuild@yourdomain.comK. log4j.appender.Mail.SMTPHost=yoursmtp.mailhost.comL. log4j.appender.Mail.Subject=CC has had an error!!!M. log4j.appender.Mail.To=youremail@yourdomain.comN. log4j.appender.Mail.layout=org.apache.log4j.PatternLayoutO. log4j.appender.Mail.layout.ConversionPattern=%d{dd.MM.yyyy HH:mm:ss}

%-5p [%x] [%c{3}] %m%nP. CruiseControl manages its own thread count for simultaneous builds.

While this makes sense when the build master is the only machine performing builds (normal CruiseControl use), it's nearly useless to do distributed builds without being able to do them simultaneously. As such, you will want to configure CruiseControl to run using approximately as many threads as you'll have running agents. For complicated reasons this may not be the best solution, but it should be adequate until a more sophisticated thread-count mechanism can be added to CruiseControl. In your CC configuration file, add a <threads> tag under the <cruisecontrol> tag at the top:

Q. <system>R. <configuration>S. <threads count="5" />T. </configuration>

</system>

where 5 would be replaced with your expected number of build agents.

U. Java Web Start deployment of build agents : The command contrib/distributed/ant war-agent will use the file contrib/distributed/build-sign.properties to sign agent jars and bundle them into a deployable .war file (dist/cc-agent.war). Be sure you update build-sign.properties appropriately to use your signing information/certificate.

V. Agent Utility : Running contrib/distributed/dist/util/ant agent-util (from inside the contrib/distributed/dist/util dir) will launch a Build Agent monitoring utility. The Agent Utility can also be used to kill (and if the agent was launched via webstart - restart) Build Agents. As of version 2.8, CruiseControl will automatically load a JMX Build Agent Utility into the JMX Control Panel if CCDist classes are available. See the -agentutil command line argument to disable the JMX Build Agent Utility if needed.

W. Build Agent UI: Build Agents default to showing a simple User Interface. The Build Agent will detect if it is running in a headless environment and automatically bypass the UI. This UI can be manually bypassed by adding: -Djava.awt.headless=true or -skipUI to the Build Agent during startup (either via command line or as a webstart jnlp parameter).

X. Build Agent Unicast Lookup URL(s): To make BuildAgents find a Lookup Service via unicast, create the property: registry.url in the agent.properties file and set it's value to the url of the Lookup Service. If you need multiple unicast URL's, use a comma separated list of Unicast Lookup Locaters (URL's) as the property value (see example below). This can be useful in environments where multicast is not working or practical, or if multicasts are disabled, but should be used only after checking out other things (like the localhost issue).

registry.url=jini://ubuntudan,jini://10.6.18.51Y. Build Agent Entry Overrides: Build Agents support the assignment of

'EntryOverrides' that can be set at runtime. This allows you to add new 'entries' to certain agents while they are running. NOTE: If your are running multiple Agents on the same machine, they will share their EntryOverride settings.

Use Case: You have a Project that must only be built on machines with specific audio hardware. You can add a new "entries" value to the <distributed> tag of this Project in your config.xml, like:

Z. <distributed entries="sound=hardwaremixable">AA. ...

</distributed>

Deploy and launch all your agents, without modifying entries in user-defined.properties. You can now add a new 'Entry Override' (ie: sound=hardwaremixable) to only those agents running on the correct hardware. Do this via the Build Agent UI or the Build Agent Utility. This new Agent entry will persist across Agent restarts.

NOTE: Be aware there is a bug in the Preferences API implementation in JRE 6.0 on non-Windows OS's that prevents these settings from persisting. See Sun Bug ID: 6568540 "(prefs) Preferences not saved in Webstart app, even after synch()" - you might want to vote for it.To workaround this bug, the saxon jars are no longer used in the agent.jnlp file. If this workaround causes problems for you, you can uncomment these jars in the agent.jnlp file (and the "ps.jarnames-xml-libs" patternset in CCDist build.xml).

Todo for this implementation

A. A default cruise.build.dir could be used on the agent, removing the requirement for any user configuration. The agent.properties file could have

cruise.build.dir commented out so users would see they had the option to configure their own build location.

B. Should we package the master like we do the agent? We shouldn't expect to run from a dist directory. It'd be nice if it were configurable to start up CruiseControl with or without Jini, or perhaps even to bring Jini up or down automatically given the presence of distributed tags in the configuration.

C. More secure default Jini policy files.D. The agent busy state logic is kludgy. Jini contains a transaction framework

(mahalo) and a mailbox service (mercury), either of which might be a way of managing busy state. Or the attempted RMI method could be utilized. A solution should be chosen and pursued to completion.

E. The code to start/stop the Jini Lookup Service during CCDist unit tests is pretty ugly. Any suggestions to improve it are welcome. (Maybe Jeff's JiniStarter...)

F. Add the following optional attributes to the <distributed> tag to support failing a build if an Agent can not be found in a timely fashion:

1. AgentSearchRetryDelay - Corresponds directly to the message you see in the logs about "Couldn't find available agent. Waiting 30 seconds before retry.". There's a @todo comment on the field (DEFAULT_CACHE_MISS_WAIT). See usages of DistributedMasterBuilder.DEFAULT_CACHE_MISS_WAIT for more info in the source.

2. AgentSearchRetryLimit - Defines how many times to perform the AgentSearchRetry loop (described in item 1). When the number of times through that retry loop exceeds the limit, a build failure would be thrown.

3. AgentFindWaitDuration - The amount of time (seconds) to wait for a direct query of the Jini lookup cache to return a matching (and "non-busy") agent. The "find" returns immediately if an available agent is cached, but there can be cases where the current default delay (5 seconds) is not enough. See usages of MulticastDiscovery.DEFAULT_FIND_WAIT_DUR_MILLIS for more info

G. More unit tests!

Limitations of this approach

A. CruiseControl doesn't allow for a varying thread count. It would be useful to allow the build thread count to vary according to the number of active agents. The CC administrator shouldn't have to change the thread count when agents come and go. On the other hand, varying thread count directly with agent-count is unsophisticated as some of the active agents may not match the entries for a given build and thus will be idle. Perhaps there should be a change in build queuing where as long as an agent is able to take a build request the thread is spawned, otherwise the request is queued.

B. Does the attribute antworkingdir for AntBuilder have to correspond to the agent.properties configuration? If so that prevents agents from differing from each other. That is, each agent should be able to have an independent configuration. antworkingdir requires knowledge of the build agent that the master shouldn't know and that might vary from agent to agent. If the CCConfig API is changed, the agent could resolve env variables at remote build time (instead of using the env var values of the master).

Configuration Reference

CruiseControl configuration files are written in XML. This document describes the XML elements and attributes for a valid configuration file.

The use of plugins 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 <cruisecontrol> element, with one or more child <project> elements.

<cruisecontrol>

<property/> <dashboard/> <include.projects/> <system> <configuration> <threads/> </configuration> </system> <plugin/> <project> <property/> <plugin/> <cvslabelincrementer> <emptylabelincrementer> <formattedlabelincrementer> <labelincrementer/> <p4changelistlabelincrementer> <propertyfilelabelincrementer> <svnlabelincrementer> <listeners> <cmsynergysessionmonitor/> <currentbuildstatusftplistener/> <currentbuildstatuslistener/> <currentbuildstatuspagelistener/> <lockfilelistener/> </listeners> <bootstrappers> <accurevbootstrapper/> <alienbrainbootstrapper/> <antbootstrapper/> <clearcasebootstrapper/> <clearcaseviewstrapper/> <cmsynergybootstrapper/> <cmsynergybaselinebootstrapper/> <cvsbootstrapper/> <darcsbootstrapper/> <execbootstrapper/> <gitbootstrapper/> <harvestbootstrapper/> <lockfilebootstrapper/> <mercurialbootstrapper/> <p4bootstrapper/> <plasticscmbootstrapper/> <snapshotcmbootstrapper/> <starteambootstrapper/> <surroundbootstrapper/> <svnbootstrapper/> <tfsbootstrapper/> <vssbootstrapper/> </bootstrappers> <modificationset> <accurev> <alienbrain/> <alwaysbuild/> <buildstatus/> <clearcase/> <cmsynergy/> <compound> <targets/> <triggers/> </compound> <cvs/> <darcs/> <filesystem/>

<forceonly/> <git/> <harvest/> <httpfile/> <mavensnapshotdependency/> <maven2snapshotdependency/> <mercurial/> <mks/> <p4/> <plasticscm/> <pvcs/> <snapshotcm/> <starteam/> <store/> <surround/> <svn/> <tfs/> <timebuild> <ucm> <veto/> <vss/> <vssjournal/> </modificationset> <schedule> <ant/> <maven/> <maven2/> <pause/> <nant/> <phing/> <rake/> <exec/> <pipedexec/> <composite/> <xcode/> </schedule> <log> <merge/>

<gzip/> <delete/> <deleteartifacts/>

</log> <publishers> <antpublisher/> <artifactspublisher/> <clearcasebaselinepublisher/> <cmsynergybaselinepublisher/> <cmsynergytaskpublisher/> <compoundpublisher/> <email/> <execute/> <ftppublisher/> <htmlemail/> <http> <jabber/> <onfailure/> <onsuccess/> <origo/> <rss/> <sametimeannouncement/> <scp/> <sfeedocman/> <sfeefrs/> <sfeetracker/>

<socket/> <twitter> <weblog> <x10/> <xsltlogpublisher/> <yahoopublisher/> </publishers> </project></cruisecontrol>

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

Child Elements

Element Cardinality Description

<system> 0 .. 1

Currently just a placeholder for the <configuration> element, which in its turn is just a placeholder for the <threads> element.We expect that in the future, more system-level features can be configured under this element.

<project> 1 .. * Defines a basic unit of work.<plugin> 0 .. * Registers a classname with an alias.<property> 0 .. * Defines a name/value pair used in configuration.<include.projects> 0 .. * Add projects defined in other configuration files.<dashboard> 0 .. 1 Configure dashboard related settings.top

<threads>

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

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

Attributes

Attribute Required Description

count Yes Maximum number of threads to be in use simultaneously to build projects

top

<property>

<cruisecontrol> <property>

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

1. By supplying both the name and value attributes.2. By setting the file attribute with the filename of the property file to

load. This property file must follow the format defined by the class java.util.Properties, with the same rules about how non-ISO8859-1 characters must be escaped.

3. By setting the environment attribute with a prefix to use. Properties will be defined for every environment variable by prefixing the supplied name and a period to the name of the variable.

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

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

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

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

Attributes

Attribute Required Descriptionname

Exactly one of name, environment, or file.

The name of the property to set.

environment

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

file The filename of the property file to load.

value Yes, if name was set.

The value of the property. This may contain any previously defined properties.

toupper NoUsed in conjunction with environment. If set to true, all environment variable names will be converted to upper case.

Examples

1. Set a couple of global properties using name/value pairs: 2. <cruisecontrol>3. <property name="cruisedir" value="/home/cruise"/>4. <property name="logdir" value="${cruisedir}/logs"/>5. ...6. <cruisecontrol>

7. Set a collection of global properties from the properties file

"config.properties":

8. <cruisecontrol>9. <property file="config.properties"/>10. ...11. <cruisecontrol>

12. Load the system's environment into a collection of global properties.

Uppercase all environment variable names: 13. <cruisecontrol>14. <property environment="env" toupper="true"/>15. <property name="logdir" value="${env.CCDIR}/logs"/>16. ...17. <cruisecontrol>

18. Define a global property called "buildmanager". Override it's value

only within the scope of the project called "project2". 19. <cruisecontrol>20.21. <property name="buildmanager" value="buildmgr@here.com"/>22.23. <project name="project1">24. <!-- ${buildmanager} resolves to "buildmgr@here.com" -->25. </project>26.27. <project name="project2">28. <property name="buildmanager" value="someoneelse@here.com"/>29. <!-- ${buildmanager} resolves to "someoneelse@here.com" -->30. </project>31.32. <cruisecontrol>

33. As demonstrated here, properties and plugin pre-configuration can be

an extremely powerful combination. 34. <cruisecontrol>35.36. <!-- Load environment variables -->37. <property environment="env" toupper="true"/>38.39. <!-- Commonly used directories -->40. <property name="reportdir" value="${env.CCDIR}/report"/>41. <property name="projectdir" value="${env.CCDIR}/checkout/$

{project.name}"/>42. <property name="testdir" value="${projectdir}/build/junit-reports"/>43. <property name="logdir" value="${env.CCDIR}/logs/${project.name}"/>44.45. <!-- Defaults for email -->46. <property name="buildmaster.email" value="buildmaster@example.com"/>47. <property name="buildmaster.name" value="Buildmaster"/>48.49. <!-- Preconfigure our plugins -->50. <plugin name="log"51. dir="${logdir}"/>52.53. <plugin name="currentbuildstatuslistener"54. file="${logdir}/buildstatus.html"/>55.56. <plugin name="cvs"57. localworkingcopy="${projectdir}"/>58.59. <plugin name="ant"60. antscript="${env.ANT_HOME}/bin/ant"61. antWorkingDir="${projectdir}"62. target="cruise"/>63.64. <plugin name="htmlemail"

65. buildresultsurl="http://servername/cruisecontrol/buildresults/${project.name}"

66. mailhost="smtp.example.com"67. returnaddress="${buildmaster.email}"68. returnname="${buildmaster.name}"69. subjectprefix="[BUILD ${project.name}]"70. xsldir="${reportdir}/jsp/webcontent/xsl"71. css="${reportdir}/jsp/webcontent/css/cruisecontrol.css"/>72.73. <project name="project1"/>74. <listeners>75. <currentbuildstatuslistener/>76. </listeners>77. <log>78. <merge dir="${testdir}">79. </log>80. <modificationset>81. <cvs/>82. </modificationset>83. <schedule>84. <ant/>85. </schedule>86. <publishers>87. <htmlemail>88. <always address="${buildmaster.email}">89. <failure address="proj1dev@example.com">90. <ignore address="buildmaster">91. </htmlemail>92. </publishers>93. </project>94.95. <project name="project2"/>96. <listeners>97. <currentbuildstatuslistener/>98. </listeners>99. <log>100. <merge dir="${testdir}">101. </log>102. <modificationset>103. <cvs/>104. </modificationset>105. <schedule>106. <ant/>107. </schedule>108. <publishers>109. <htmlemail>110. <always address="${buildmaster.email}">111. <failure address="proj2dev@example.com">112. </htmlemail>113. </publishers>114. </project>115.116. </cruisecontrol>

top

<include.projects>

<cruisecontrol> <include.projects>

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

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

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

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

Attributes

Attribute Required Description

file Yes Relative path from current configuration file to the configuration file to process.

top

<dashboard>

<cruisecontrol> <dashboard>

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

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

Attributes

Attribute Required Description

url No Home page address of your dashboard. The default value is http://localhost:8080/dashboard.

postinterval No The interval [in seconds] that build loop post builds information to the dashboard. The default value is 5 seconds.

top

<project>

<cruisecontrol> <project>

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

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

Attributes

Attribute Required Descriptionname Yes Unique identifier for this project

buildafterfailedNo (defaults to true)

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

forceBuildNewProjectNo (defaults to true)

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.

requireModificationNo (defaults to true)

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

forceOnlyNo (defaults to false)

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 <schedule> until the build is successful.

Child Elements

Element Cardinality Description<listeners> 0 .. 1 Container element for Listener plugin instances.<bootstrappers> 0 .. 1 Container element for Bootstrapper plugin instances.<modificationset> 1 Container element for SourceControl plugin instances.

<schedule> 1 Specifies the SourceControl poll interval, and is a parent element for Builder plugin instances.

<log> 0 .. 1 Specifies where project log files are stored.<publishers> 0 .. 1 Container element for Publisher plugin instances.<plugin> 0 .. * Registers a classname with an alias.top

<listeners>

<cruisecontrol> <project> <listeners>

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

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

Child Elements

Element Cardinality Description

<currentbuildstatusftplistener> 0 .. * Writes a build status snippet to the filesystem and to an FTP server

<currentbuildstatuslistener> 0 .. * Writes a build status snippet to the filesystem

<currentbuildstatuspagelistener> 0 .. *Writes build status to the filesystem using by replacing values in a template

<cmsynergysessionmonitor> 0 .. * Monitors and starts CM Synergy

Element Cardinality Descriptionsessions as needed

<lockfilelistener> 0 .. * Responsible for deleting the lock file when a project goes IDLE

top

<cmsynergysessionmonitor>

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

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

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

1. If the session file does not exist, it will be created.2. If an entry for the session name does not exist in the session file, a new

CM Synergy session will be started and an entry recorded in the file.3. If an entry for the session name does exist in the file, it will check that

the CM Synergy session ID associated with the session name is still running. If it is, no further action is taken. If it is not, a new CM Synergy session is started, and the new ID recorded in the file.

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

System Environment Variable ValueCCM_ENGLOG ${path to build Synergy users ccm_eng.log}CCM_UILOG ${path to build Synergy users ccm_ui.log}

Attributes

Attribute Required Description

ccmexe NoThe 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).

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

Child Elements

Element Cardinality Description<session> 1 .. * Defines a CM Synergy session you wish to monitor. The session

information may be provided in one of two ways.

1. You may provide each individual attribute directly in the config file.

Element Cardinality Description

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

Attribute Required Description

name Yes

The name of the CM Synergy session. This value will be used in the "sessionname" attributes of the other CM Synergy plugins.

attributefile NoThe properties file which will be read to set the remainder of the session's attributes.

database YesThe CM Synergy database with which this session will communicate (e.g. /ccmdb/mydb).

user Yes The CM Synergy user account under which the session will run.

password Yes The password for the specified user.

role Yes The role under which the CM Synergy session will run (e.g. build_mgr).

host No

If you wish the CM Synergy session to run on a host other than the current machine, you may set the host name here.

remoteclient NoIf CM Synergy is running on a UNIX environment and the database is not locally accessible, set this to true

Examples

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

2. <listeners>3. <cmsynergysessionmonitor>4. <session name="session1"5. database="/ccmdb/product1"6. user="buildmgr"7. role="build_mgr"8. password="P@ssW0rd!"/>9. <session name="session2"10. attributefile="session2.properties"/>11. <cmsynergysessionmonitor/>12. <listeners/>

Session 2 would then use a properties file as follows:

#CM Synergy session properties for "session2"database=/ccmdb/product2user=buildmgrrole=build_mgrpassword=P@ssW0rd!

top

<compoundpublisher>

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

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

All child elements must meet the following criteria:

1. They must be registered as publishers. If you are adding a publisher which ships with CruiseControl, this will be done for you automatically. If you are adding a custom publisher, you must remember to register it with CruiseControl using a <plugin> element within your config file.

2. They must validate successfully regardless of whether or not the build was successful.

Child Elements

Element Cardinality DescriptionAny defined publisher

1 .. * You may use any defined publisher as a child element.

Examples

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

2. <compoundpublisher>3. <x10 houseCode="A" deviceCode="3"/>4. <antpublisher antscript="/opt/apache-ant-1.6.1/bin/ant"5. target="cleanupafterfailure">6. </antpublisher>7. </compoundpublisher>

top

<currentbuildstatuslistener>

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

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

Attributes

Attribute Required Descriptionfile Yes The filename to write, including pathtop

<currentbuildstatuspagelistener>

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

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

{Project} - Project Name. {State.Name} - Name of current project state. {State.Description} - Description of current project state. {State.Date} - Date/time the current state happened {State.Duration} - How long since this state was in effect. (Only useful in

{History} line.) {History} - Historical states. Must be first on line. This line will be

processed and output once for each state the project has previously been in. The {History} tag will be deleted from the line.

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

Attributes

Attribute Required Descriptionfile Yes The filename to write, including pathsourceFile No The file with the template to use for subtitutiontop

<currentbuildstatusftplistener>

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

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

Attributes

Attribute Required Descriptionfilename Yes The filename to write, including pathdestdir Yes The remote directory in which the file will be sent to.top

<lockfilelistener>

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

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

Attributes

Attribute Required Description

lockfile Yes The name (and path) of the file to serve as the lock between multiple projects.

projectname Yes Lockfile only deleted when contents match the value set for project name.

top

<bootstrappers>

<cruisecontrol> <project> <bootstrappers>

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

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

Child Elements

Element Cardinality Description

<accurevbootstrapper> 0 .. * Updates the resources of an Accurev workspace

<alienbrainbootstrapper> 0 .. * Bootstraps resources from AlienBrain

<antbootstrapper> 0 .. * Executes an Ant script which implements a custom bootstrapper

<clearcasebootstrapper> 0 .. * Bootstraps resources from ClearCase

<clearcaseviewstrapper> 0 .. * Bootstraps View and VOB resources from ClearCase

<cmsynergybootstrapper> 0 .. * Bootstraps resources from CM Synergy

<cmsynergybaselinebootstrapper> 0 .. * Creates a Synergy baseline prior to build

<cvsbootstrapper> 0 .. * Bootstraps resources from CVS<darcsbootstrapper> 0 .. * Bootstraps resources from Darcs<execbootstrapper> 0 .. * Execute a command for bootstrapping<gitbootstrapper> 0 .. * Bootstraps resources from git

<harvestbootstrapper> 0 .. * Bootstraps resources from AllFusion Harvest

<lockfilebootstrapper> 0 .. * Creates the lock file if it doesn't already exist

<mercurialbootstrapper> 0 .. * Bootstraps resources from Mercurial<p4bootstrapper> 0 .. * Bootstraps resources from Perforce<plasticscmbootstrapper> 0 .. * Bootstraps resources from Plastic SCM<snapshotcmbootstrapper> 0 .. * Bootstraps resources from SnapshotCM<starteambootstrapper> 0 .. * Bootstraps resources from Star Team<surroundbootstrapper> 0 .. * Bootstraps resources from Surround SCM<svnbootstrapper> 0 .. * Bootstraps resources from Subversion

<tfsbootstrapper> 0 .. * Bootstraps resources from Microsoft Visual Studio Team Foundation Server

<vssbootstrapper> 0 .. * Bootstraps resources from Visual Source Safe

top

<accurevbootstrapper>

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

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

Attributes

Attribute Required Description

keepNo (defaults to "false")

If true, the plugin runs "accurev keep -m" before trying to update the workspace, to keep all modified elements.

synctimeNo (defaults to "false")

If true, the plugin runs "accurev synctime" before trying to update the workspace, to synchronize the local clock with the Accurev server's.

verbose No (defaults to "false")

Enables detailed logging.

workspace No (defaults to the current dir)

The local path containing the working copy of the desired workspace.

Examples

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

2. <bootstrappers>3. <accurevbootstrapper workspace="D:\accurev\workspace_user\MyProject"4. synctime="true"5. keep="true"6. verbose="true"/>7. <bootstrappers>

top

<alienbrainbootstrapper>

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

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

Attributes

Attribute Required Description

server NoThe name of the machine hosting the AlienBrain repository. If specified, it will override the value in the NXN_AB_SERVER environment variable.

database NoThe name of the project in the AlienBrain repository. If specified, it will override the value in the NXN_AB_DATABASE environment variable.

user No The AlienBrain user account name to use when querying

Attribute Required Descriptionfor modifications. If specified, it will override the value in the NXN_AB_USERNAME environment variable.

password No

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.

path Yes

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.

branch No The branch of the project from which to retrieve the path.

forcefileupdateNo (defaults to false)

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.

overwritewritableNo (defaults to 'skip')

Must be either 'skip' or 'replace'. 'ask' is not an option as no one is around to answer the question. skip:

do not touch the filereplace:

replace the file with the version on the server

localpath No If localpath is specified the item is copied to the specified local path.

top

<antbootstrapper>

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

Executes an Ant script which implements a custom bootstrapper.

Attributes

The antbootstrapper uses the same attributes as the <ant> builder.

Child Elements

The antbootstrapper supports the same set of child elements as the <ant> builder.

Examples

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

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

<bootstrappers>For additional examples, please see the <ant> builder.

top

<clearcasebootstrapper>

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

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

Attributes

Attribute Required Descriptionfile Yes The filename to writeviewPath No local path to the filetop

<clearcaseviewstrapper>

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

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

Attributes

Attribute Required Description

viewpath Yes

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.

voblist No A comma separated list of VOBs to mount, i.e. "\VOB1,\VOB2" (Windows) or "/vobs/VOB1,/vobs/VOB2" (Linux/Unix).

Examples

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

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

J2EE_Binaries"/><bootstrappers>

top

<cmsynergybootstrapper>

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

Used to reconfigure a CM Synergy project or project hierarchy

Attributes

Attribute Required Description

ccmexe NoThe 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).

sessionfile No

The session file used by the <cmsynergysessionmonitor> to persist your CM Synergy session information. If this attribute is not set, it defaults to the file ".ccmsessionmap" in your home directory.

sessionname No

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.

project Yes The project spec (two part name) of the project you wish to reconfigure.

recurse No If set to true, all subprojects will also be reconfigured. Defaults to true

Examples

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

2. <bootstrappers>3. <cmsynergybootstrapper project="j2ee~1.0_int"4. sessionname="j2ee_session"5. recurse="false"/>

<bootstrappers>top

<cmsynergybaselinebootstrapper>

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

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

Attributes

Attribute Required Description

ccmexe NoThe 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).

sessionfile No

The session file used by the <cmsynergysessionmonitor> to persist your CM Synergy session information. If this attribute is not set, it defaults to the file ".ccmsessionmap" in your home directory.

sessionname No

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.

baselinename NoAn optional name for the baseline. If not provided, CM Synergy will assign a default name based upon the current date.

Attribute Required Description

project Yes The project spec (two part name) of the project you wish to reconfigure.

description No An optional description of the baselinebuild No Value to specify for the build attribute of the baselinepurpose No Value to specify for the purpose of the baseline

state NoValue to specify for the state of the baseline. Valid values are: "published_baseline","test_baseline" or "released". Default state is "published_baseline"

Examples

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

2. <bootstrappers>3. <cmsynergybootstrapper project="test_project~dev410"4. sessionname="cc_session"5. build="QA432"6. purpose="System Testing"7. state="released"8. baselinename="test_baseline"/>

<bootstrappers>top

<cvsbootstrapper>

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

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

Attributes

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

Attribute Required Description

localWorkingCopy No

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.

cvsroot NoThe CVSROOT. Not required if the current working directory is in the cvs project or if the localWorkingCopy attribute is set.

file No

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.

overwriteChanges No If set to true the update command will include the -C option which will overwrite local changes.

resetStickyTags No If set to true the update command will include the -A option which will reset any sticky tags, dates, or -k

Attribute Required Descriptionoptions.

compression No

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.

top

<darcsbootstrapper>

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

Handles updating from a darcs repository before the build begins.

Attributes

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

Attribute Required Description

darcsBinary no (default "darcs")

Name or location of the darcs binary

workingdir At least one of workingdir or repository location

Relative or absolute path to the workingdir. Directory must exist.

repositorylocation Specifies the location of the Darcs repository to pull into.

remoteRepositoryLocation no

Specifies the location of the remote Darcs repository to pull from. Usually, the local repository already knows about this.

top

<execbootstrapper>

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

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

top

<gitbootstrapper>

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

Handles updating from a git repository before the build begins.

Attributes

Attribute Required Description

localWorkingCopy Yesthe relative or absolute path to the local working copy of the git repository on which to execute the update command.

top

<harvestbootstrapper>

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

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

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

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

Attributes

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

Attribute Required Descriptionusername Yes Usename to use in connecting to the Harvest Broker.password Yes Password to use in connecting to the Harvest Broker.broker Yes The name of the Harvest Broker to connect to.

project YesThe name of the project containing the file you wish to bootstrap. Can be different from the cruisecontrol project name.

state Yes The name of the state containing the file you wish to bootstrap.

viewpath Yes The Harvest view path of the file you wish to bootstrap.

clientpath Yes The Harvest client path to use when checking out the bootstrap file.

process Yes The name of the Harvest checkout process to use.file Yes The name of the file to be bootstrapped.

item No The item filter to use. One of: baseline, modified, both. Default is both.

version No The version filter to use. One of: latest_in_view, all_in_view, all, latest. Default is latest_in_view.

status No The status option to use. One of: all, no_tag, reserved, merged, removed, any. Default is all.

branch No The branch option to use. One of: trunk, branch, trunk_and_branch, unmerged. Default is trunk.

top

<lockfilebootstrapper>

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

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

Attributes

Attribute Required Description

lockfile Yes The name (and path) of the file to serve as the lock between multiple projects.

projectname Yes The project name is written to the lockfile so that the LockFileListener knows which to delete.

top

<mercurialbootstrapper>

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

Handles updating from a Mercurial repository before the build begins.

Attributes

Attribute Required Description

localWorkingCopy Yesthe relative or absolute path to the local working copy of the Mercurial repository on which to execute the update command.

top

<p4bootstrapper>

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

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

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

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

Attributes

Attribute Required Descriptionview Yes Valid Perforce path (a.k.a. 'view')port No Perforce Server connection to use (host:port)user No Perforce User name to usepasswd No Perforce password to useclient No Perforce Client name to usetop

<plasticscmbootstrapper>

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

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

Attributes

Attribute Required Descriptionwkspath Yes Valid Plastic SCM workspace path.

branch NoThe branch from which to get the source. If none has been specified, it updates the workspace according to its configuration.

repository NoThe repository from which to get the source. If none has been specified, it updates the workspace according to its configuration.

pathtoupdate No A path under the workspace path which will be updated. If none is specied, it updates all the workspace.

forced No (defaults to "false")

Do the update with the "--forced" option

Examples

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

2. <bootstrappers>3. <plasticscmbootstrapper wkspath="c:\work\cruise\plasticwks"4. branch="br:/main"5. forced="yes" />

<bootstrappers>top

<snapshotcmbootstrapper>

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

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

Attributes

Attribute Required Descriptionfile Yes Name of the file or directory to fetch from the SnapshotCM

Attribute Required Descriptionrepository. Updates from SnapshotCM repository will be recursive and forced (over-writing any local changes).

top

<starteambootstrapper>

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

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

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

Attributes

Attribute Required Descriptionfiles Yes Space separated list of files to retrievefolder Yes The repository folderlocalfolder No Path to the folder on the local file systempassword Yes  port Yes Port StarTeam server is usingproject Yes StarTeam projectserver Yes Hostname for StarTeam serverusername Yes  view Yes StarTeam viewtop

<surroundbootstrapper>

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

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

Attributes

Attribute Required Description

branch No Surround SCM branch name. The default is pulled from the local working directory.

repository No Surround SCM repository path. The default is pulled from the local working directory.

label No Enter a label to search for when getting files.

includeremovedfiles NoInclude removed files when getting files by label or timestamp. Default is true. Ignored if a label is not specified. Options are 1 or 0 (default).

overwrite No Enter how to handle a local writable file. Options are 1 to overwrite or 0 (default) to skip.

recursive No Recursively get files and sub-repositories. Options are 1 or 0 (default).

Attribute Required Description

forcefetch No Force file retrieval from server regardless of the local copy status. Options are 1 or 0 (default).

makewritable No Make local file editable or writable. Default is read-only. Options are 1 or 0 (default).

serverconnect No

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.

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

top

<svnbootstrapper>

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

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

Attributes

Attribute Required Description

localWorkingCopy One of these

the relative or absolute path to the local working copy of the Subversion repository on which to execute the update command.

file file to update from the Subversion repository.username No used for authentication.password No used for authentication.

configDir NoInstructs Subversion to read configuration information from the specified directory instead of the default location (.subversion in the user's home directory).

top

<tfsbootstrapper>

<cruisecontrol> <project>

<bootstrappers> <tfsbootstrapper>

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

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

Gets are performed by executing a command similar to the following

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

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

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

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

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

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

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

Attributes

Attribute Required Description

itemSpec Yes

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 http://msdn2.microsoft.com/en-us/library/56f7w6be(VS.80).aspx#sectionToggle3

username no

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.

The username should be passed in the form DOMAIN\username.  From unix systems the name can be passed in the username@DOMAIN format if preferred as that removes confusion over escaping of the \ character which should not be required.

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.

password no The password to use with the username when authenticating with the server.

Attribute Required Description

tfPathNo (defaults to "tf")

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 C:\Program Files\Microsoft Visual Studio 8\Common7\IDE\TF.exe

recursiveno (defaults to false)

Flag to indicate if a recursive get should be performed.

forceno (defaults to false)

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.

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

top

<vssbootstrapper>

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

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

Attributes

Attribute Required Description

vsspath Yes

Fully qualified VSS path to the target file. If the leading dollar-sign ['$'] is omitted, one will be prepended automatically.Example: /Project/subproject/filename.ext

localdirectory Yes Fully qualified path for the destination directory.Example: c:\directory\subdirectory\

login No VSS login information in the form username,password

ssdir NoPath to the directory containing ss.exe. By default, ss.exe is assumed to be in the path.Note: should not contain whitespace.

serverpath No Path to the directory containing srcsafe.ini.top

<modificationset>

<cruisecontrol> <project> <modificationset>

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

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

Attributes

Attribute Required Description

requiremodificationNo (defaults to true)

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). NOTE - This attribute will be going away. Use the requireModification attribute that is on the project tag instead.

quietperiodNo (defaults to 60)

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.

ignoreFiles No

Specify a comma separated list of glob-patterns identify files to be ignored in modificationsets. Each pattern is matched against the complete path. Example: *.txt,*/build/build.xmlThis is useful if you want to update and commit files during your CC build.

Child Elements

Element Cardinality Description<accurev> 0 .. * Checks for changes in an AccuRev stream.<alienbrain> 0 .. * Checks for changes in an AlienBrain repository.

<alwaysbuild> 0 .. * Always returns a single modification so the build will be run.

<buildstatus> 0 .. * Checks for a successful build in another project.<clearcase> 0 .. * Checks for changes in a ClearCase repository.<cmsynergy> 0 .. * Checks for changes in a CM Synergy repository.

<compound> 0 .. *Checks for changes from a list of trigger source controls, and if modification are detected, returns changes from a list of target source controls.

<cvs> 0 .. * Checks for changes in a CVS repository.<darcs> 0 .. * Checks for changes in a Darcs repository.<filesystem> 0 .. * Checks for changes in a file system.

<forceonly> 0 .. * Never returns any changes. Deprecated: use forceonly attribute on <project> instead.

<git> 0 .. * Checks for changes in a git repository.<git> 0 .. * Checks for changes in a git repository.<harvest> 0 .. * Checks for changes in an All Fusion Harvest repository.<httpfile> 0 .. * Checks for changes in a remote file via http.<mercurial> 0 .. * Checks for changes in a Mercurial repository.<mks> 0 .. * Checks for changes in a MKS repository.<p4> 0 .. * Checks for changes in a Perforce repository.<plasticscm> 0 .. * Checks for changes in a Plastic SCM branch.

Element Cardinality Description<pvcs> 0 .. * Checks for changes in a PVCS repository.<snapshotcm> 0 .. * Checks for changes in a SnapshotCM repository.<starteam> 0 .. * Checks for changes in a Star Team repository.

<store> 0 .. * Checks for changes in a Cincom Smalltalk VisualWorks Store repository.

<surround> 0 .. * Checks for changes in a Surround SCM repository.<svn> 0 .. * Checks for changes in a Subversion repository.

<tfs> 0 .. * Checks for changes in a Microsoft Visual Studio Team Foundation Server repository.

<timebuild> 0 .. * Triggers a build after a particular time threshold.

<veto> 0 .. * Checks for changes in another project and will veto a build if changes are found.

<vss> 0 .. * Checks for changes in a Visual SourceSafe repository.

<vssjournal> 0 .. * Checks for changes in a Visual SourceSafe, Journal File Implementation.

top

<accurev>

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

Checks for modifications in an AccuRev stream.

Attributes

Attribute Required Description

stream Yes The name of the AccuRev stream where the plugin looks for Modification(s).

verbose No (defaults to "false")

Set to "true" to enable a more verbose logging style.

property No Will set this property if a modification has occurred. For use in conditionally controlling the build later.

top

<alienbrain>

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

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

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

ab find PathToProject -regex "SCIT > lastbuildtime" 

Attributes

Attribute Required Description

server NoThe name of the machine hosting the AlienBrain repository. If specified, it will override the value in the NXN_AB_SERVER environment variable.

database No The name of the project in the AlienBrain repository. If

Attribute Required Descriptionspecified, it will override the value in the NXN_AB_DATABASE environment variable.

user NoThe AlienBrain user account name to use when querying for modifications. If specified, it will override the value in the NXN_AB_USERNAME environment variable.

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

path Yes The path to the item that will be queried for modifications Typically a path like 'alienbrain://Project/SubProject'

branch No The branch of the project to check for modifications.

property No Will set this property if a modification has occurred. For use in conditionally controlling the build later.

top

<alwaysbuild>

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

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

Attributes

Attribute Required Description

username No (defaults to "User")

The username to use for the single reported (fake) Modification.

property No Set this property if a modification has occurred. For use in conditionally controlling the build later.

top

<buildstatus>

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

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

Attributes

Attribute Required Description

logdir Yes Path to CruiseControl log directory for the project to monitor.

property No Will set this property if a modification has occurred. For use in conditionally controlling the build later.

vetoIfFailing No Will abort the build attempt if the last build of the monitored project is failing. Defaults to false.

Properties Passed to the Builders

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

Property Name Descriptionmost.recent.logdir The location being checked for new log files

most.recent.logfile The name of the newest logfile included in the modification set

most.recent.logtime The timestamp of the newest build included in the modification set, using the format yyyyMMddHHmmss

most.recent.loglabel The label of the newest build included in the modification settop

<clearcase>

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

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

Attributes

Attribute Required Descriptionbranch Yes The ClearCase branch

recursiveNo (defaults to true)

Whether to check sub-folders in the viewpath.

allNo (defaults to false)

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.

This option is mutually exclusive with the recursive property.

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.

viewpath Yes Local working copy to use when making queries

property No Will set this property if a modification has occurred. For use in conditionally controlling the build later.

Properties Passed to the Builders

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

Property Name Description

clearcaselastbuild Timestamp representing the last built time, using the format dd-MMMM-yyyy.HH:mm:ss

clearcasenow Timestamp representing the time the current build started, using the format dd-MMMM-yyyy.HH:mm:ss

top

<cmsynergy>

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

Triggers a build if tasks have been added to any folder within a CM Synergy project's reconfigure properties since the last build. If used to check for modifications to a System Testing or Insulated Development project, this will also check for any completed tasks included in the latest baseline for the projects release value since the last build.

Attributes

Attribute Required Description

ccmexe NoThe 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).

sessionfile No

The session file used by the <cmsynergysessionmonitor> to persist your CM Synergy session information. If this attribute is not set, it defaults to the file ".ccmsessionmap" in your home directory.

sessionname No

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.

project Yes The project spec (two part name) of the CM Synergy project in which you wish to search for changes.

instance No

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

ccmdateformat No

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.

updatefolders No

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. This feature will only work with CM Synergy version 6.3 and above. If you are using an older version, you must set this option to false. In this case, you'll want to use the <cmsynergybootstrapper> as a workaround. Please see example 2 below as well as the Wiki site for more information.

reconfigure No

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.

recurse NoUsed in conjunction with the reconfigure option. If set to true (which is the default) all subprojects will also be reconfigured.

usebindtime No If set to true, the time a task came into the reconfigure

Attribute Required Descriptionfolder 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. This feature will only work with CM Synergy version 6.3SP1 and above. If you are using an older version, you must set this option to false (default).

ignoreworkarea No

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

changesynergyurl No

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.

ccmdb NoUsed in conjunction with changesynergyurl. This should be set to the location of the database on the CM Synergy server. (e.g. "/ccmdb/mydb")

language NoIf you have a non U.S. English installation of CM Synergy, you may specify the ISO language code here. (e.g. fr, de, etc.)

country NoIf you have a non U.S. English installation of CM Synergy, you may specify the ISO country code here. (e.g. FR, DE, etc.)

property No

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.

Properties Passed to the Builders

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

Property Name Description

cc.ccm.session The CM Synergy session ID used to check for modifications.

cc.ccm.dateformat The date format used to convert CM Synergy dates into Java dates.

cc.ccm.project The two part name of the project (as provided in the project attribute).

cc.ccm.workareaThe file system location of the CM Synergy work area for the project (unless the ignoreworkarea attribute was set).

cc.ccm.haschanged (or the value specified by the property attribute)

Set to true if any CM Synergy objects have changed since the last build.

Examples

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

2. <modificationset>3. <cmsynergy project="j2ee~1.0_int"

4. sessionname="j2ee_session"5. reconfigure="true"/>6. <modificationset/>

7. For users of CM Synergy older than version 6.3 only. Use the

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

8. <bootstrappers>9. <cmsynergybootstrapper project="j2ee~1.0_int"10. sessionname="j2ee_session"11. recurse="false"/>12. <bootstrappers>13. <modificationset>14. <cmsynergy project="j2ee~1.0_int"15. updatefolders="false"16. sessionname="j2ee_session"17. reconfigure="true"/>18. <modificationset/>

top

<compound>

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

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

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

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

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

Attributes

Attribute Required Description

includeTriggerChangesNo (defaults to false)

Add the trigger modifications to the list of returned modifications? By default, the list of returned modifications only includes the source controls from the <targets> element. By setting this attribute to true, the list of modifications will include both <triggers> and <targets> modifications.

property NoSet this property if a modification has occurred. For use in conditionally controlling the build later.

Child Elements

Element Cardinality Description

<triggers> 1

A container for one or more source control elements that trigger a full check of the targets. Any child element of <modificationset> can be used as a child element of <triggers>.

<targets> 1

A container for one or more source control elements that collectively represent the modificationset of the <compound> element. Any child element of <modificationset> can be used as a child element of <targets>.

Example

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

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

<cvs>

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

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

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

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

The following changes are made to generate the actual command:

log is used when the localworkingcopy attribute is set, rlog otherwise. lastbuildtime is replaced with the date of the last build, using the date

format yyyy-MM-dd HH:mm:ss 'GMT'. checktime is replaced with the date at which the check takes place. The -d option is only used when the cvsroot attribute is specified; CVSROOT

is replaced by the value of that attribute. The -r option is only used when the tag attribute is specified; TAG is

replaced by the value of that attribute. Otherwise, the -b option is used. The -N option is only used when the tag attribute is not specified or if it

is set to HEAD. module is replaced with the specified module name. If a local working copy

is used then the module name is left off.

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

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

Attributes

Attribute Required Description

localworkingcopy

Either localworkingcopy or both cvsroot and module.

Relative or absolute path to the local working copy. Directory must exist and should have files from a previous checkout.

cvsrootSpecifies the location of the CVS repository. This should be of the form:pserver:username@cvs.example.com:/cvsroot/reponame

module

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 rlog command in the cvs log reference for further details.

tagNo (defaults to HEAD)

Specify the cvs tag. The value of this attribute is passed directly to cvs log using the -r 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 -r option in the cvs log reference for further details.

property NoSet this property if a modification has occurred. For use in conditionally controlling the build later.

propertyondelete No Set this property if a file has been deleted. For use in conditionally controlling the build later.

reallyQuiet No

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.

recurseLocalWorkingCopy No

Sets the behavior when a local working coppy is set which is not under control of CVS itself (that is, does not have a CVS subdirectory). If set to true all subdirectories are searched recursively. All subdirectories which are under control of CVS are searched for modifications in the usual manner. Defaults to false.

compression No

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.

skipEmailsFetching No (defaults to false)

If set to true, fetching of CVSROOT/users is skipped.

top

<darcs>

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

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

Attributes

Attribute Required Description

workingdirEither workingdir or repository location.

Relative or absolute path to the workingdir. Directory must exist.

repositorylocation Specifies the location of the Darcs repository.

property NoSet this property if a modification has occurred. For use in conditionally controlling the build later.

propertyondelete NoSet this property if a file has been deleted. For use in conditionally controlling the build later.

top

<filesystem>

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

Returns all files beneath the specified path than have been modified since the last build time. Any modified files are reported as modifications of type "changed" by user "User". Can also have folder be just a single file. Only looks at timestamp, not for actual changes to the file. If includedirectories is set it detects changes to directory timestamps, and will show modification if any files were deleted

Attributes

Attribute Required Description

folder Yes Root folder of the directories to scan, or path to file to check for modifications.

includedirectories No Include modified directories. Defaults to false.

property NoSet this property if a modification has occurred. For use in conditionally controlling the build later.

username No (defaults to "User")

The username to use for the reported Modifications.

top

<forceonly>

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

Deprecated. Use forceonly attribute on <project> instead.

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

Attributes

Attribute Required Description

property No Set this property if a modification has occurred. For use in conditionally controlling the build later.

top

<git>

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

Checks for changes within a git repository.

Attributes

Attribute Required

Description

LocalWorkingCopy

Yes Relative or absolute path to the local working copy of the git repository of which to find the log history.

property No Set this property if a modification has occurred. For use in conditionally controlling the build later.

propertyondelete

No Set this property if a file has been deleted. For use in conditionally controlling the build later.

Properties Passed to the Builders

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

Property Name

Description

gitcommitid The commit id of the latest commit

top

<harvest>

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

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

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

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

See the AllFusion Harvest product page for more information.

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

Attributes

Attribute Required

Description

username Yes The username to connect as.password Yes The password to connect with.broker Yes The name of the Harvest broker to connect to.state Yes The state in which you want to search for changes.

prevstate No The state in which you want to search for demotion changes. Only used if mode is set to package.

viewpath No The Harvest view path within which to limit the search.

project YesThe name of the project in AllFusion Harvest that you want to watch. Note that this can be different than the CruiseControl project name.

item No The item filter to use. One of: baseline, modified, both. Default is both.

version No The version filter to use. One of: latest_in_view, all_in_view, all, latest. Default is latest_in_view.

status No The status option to use. One of: all, no_tag, reserved, merged, removed, any. Default is all.

branch No The branch option to use. One of: trunk, branch, trunk_and_branch, unmerged. Default is trunk.

mode No

The mode to use for searching. One of: version, package. version monitors for new versions being checked in. package monitors for the promotion and demotion of packages. Default is version.

property No Set this property if a modification has occurred. For use in conditionally controlling the build later.

propertyondelete

No Set this property if a file has been deleted. For use in conditionally controlling the build later.

top

<httpfile>

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

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

Attributes

Attribute

Required Description

url Yes The HTTP URL of a file to check the modification date ofusername

No (defaults to "User")

The username to use for the reported Modification.

property

No Set this property if a modification has occurred. For use in conditionally controlling the build later.

top

<mavensnapshotdependency>

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

Triggers a build if a Maven snapshot detects a change.

Attributes

Attribute Required

Description

projectFile

Yes Maven POM file.

user Yes The username to use when reporting modifications.localRepository

No Local Maven JAR repository. Defaults to {user.home}/.maven/repository.

propertiesFile

No Sets the .properties file which contains overriding tags for POM. Default is build.properties.

property No Set this property if a modification has occurred. For use in conditionally controlling the build later.

top

<maven2snapshotdependency>

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

Triggers a build if a Maven2 snapshot detects a change.

Attributes

Attribute Required Descriptionpomfile Yes maven2 POM file.user Yes The username to use when reporting modifications.

localRepository

No (Not available until after maven v2.0.4+)

Local Maven2 JAR repository. Defaults to {user.home}/.m2/repository.

property NoSet this property if a modification has occurred. For use in conditionally controlling the build later.

top

<mks>

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

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

1. The sandbox must always exists. The MKS sourcecontrol are unable to create the sandbox for you. In principle, this is not a real problem as long as the underlying MKS command si are able to handle such a task, but in this initial version I don't create a sandbox during runtime. If you not always create your sandbox, see si createsandbox for more information.

2. You have already logged in into the MKS Server. This should be done in your bootstrap section by the ANT task siconnect. The underlying java class is situated in the mksant.jar which is available through the MKS Customer Community. Since this (and the corresponding sidisconnect) anttasks are only small wrapper for the command line call of si, this could be done in later versions by the MKS sourcecontroller itself. You should call the sidisconnect task after your build, e.g. during your publishing phase.

Attributes

Attribute Required

Description

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

localworkingdir

Yes Local directory for the sandbox.

project Yes The name of the MKS project file (mostly project.pj).

property No Set this property if a modification has occurred. For use in conditionally controlling the build later.

top

<mercurial>

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

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

Attributes

Attribute Required

Description

localWorkingCopy

Yes Local directory for the sandbox.

hgcommand No The hg command used to check changes. Either 'incoming' or 'log'. Default is 'incoming'

Properties Passed to the Builders

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

Property Name

Description

hgrevision The latest revision number

top

<p4>

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

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

Attributes

Attribute Required

Description

correctForServerTime No

Should CruiseControl correct for time differences between the Perforce server and the CruiseControl server? Defaults to true.

port Yes Perforce Server connection to use (host:port)client Yes Perforce Client name to useuser Yes Perforce User name to usepasswd No Perforce password to useview Yes Valid Perforce view (i.e. a depot path)

property No Set this property if a modification has occurred. For use in conditionally controlling the build later.

usep4email No Should the Email address for the users be retrieved from Perforce if possible. Defaults to true.

top

<plasticscm>

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

Checks for changes in a Plastic SCM repository.

Attributes

Attribute

Required

Description

wkspath Yes Valid Plastic SCM workspace path.

branch Yes The branch in which changes will be looked for.

repository

No The repository in which changes will be looked for.

Examples

1. Used to check for changes in the branch br:/main. 2. <modificationset>3. <plasticscm wkpath="c:\work\cruise\plasticwks"4. branch="br:/main" />5. <modificationset/>

top

<pvcs>

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

Checks for changes in a PVCS repository.

Attributes

Attribute Required Descriptionarchivefilesuffix

no Standard suffix for archive set when the repository is created. Default value is "-arc".

loginid noUsed to supply a user and password. Example: loginid="sampleuser:samplepassword" or loginid="sampleuser"

pvcsproject Yes Project name.pvcssubproject Yes Subproject name.pvcsbin No Path to directory with pcli.

pvcsversionlabel No

The version label for the PVCS builder to check against. Example: pvcsVersionLabel="SampleVersionLabel"

pvcspromotiongroup No

The promotion group for the PVCS builder to check against. Example: pvcspromotiongroup="SampleGroup"

outdateformatNo (defaults to "MMM dd yyyy HH:mm:ss")

The format to use to parse the LastModified entry as produced by your pvcs system

indateformatNo (defaults to "MM/dd/yyyy hh:mm:ss aa")

The format used to format the lastbuild date for pvcs commands.

property NoSet this property if a modification has occurred. For use in conditionally controlling the build later.

top

<snapshotcm>

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

Checks for changes in a SnapshotCM repository.

Attributes

Attribute Required

Description

sourcepaths Yes A semi-colon-separated list of source paths to check for modifications. All paths will be checked recursively.

property No Property to be set if a modification has occurred. For use in conditionally controlling the build later.

propertyondelete

No Property to be set if a file has been deleted. For use in conditionally controlling the build later.

top

<starteam>

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

Checks for changes in a Star Team repository.

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

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

Attributes

Attribute Required Descriptionfolder Yes The repository folderpassword Yes Password for the StarTeam userstarteamurl Yesusername Yes StarTeam user namepreloadFileInformation

No (defaults to true)

When set to true can make the modification check much faster.

property No Property to be set if a modification has occurred. For use in conditionally controlling the build later.

propertyondelete

No Property to be set if a file has been deleted. For use in conditionally controlling the build later.

top

<store>

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

Checks for changes within a Cincom Smalltalk VisualWorks Store repository.

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

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

Attributes

Attribute Required

Description

workingDirectory Yes Relative or absolute path to the directory in which to run the Store script.

script Yes

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.

profile Yes The name of the Store connection profile for the repository to check.

packages Yes A comma-separated list of package names. These packages and their pre-requisites will be checked for modifications.

versionRegex NoA Regex11-style regular expression. Only package versions that match the regular expression will be considered. By default, all package versions are considered.

minimumBlessingL No A Store blessing level string. Package versions with a

Attribute Required

Description

evel lower blessing level will not be considered. Default: Development.

parcelBuilderFile

No

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.

property No Set this property if a modification has occurred. For use in conditionally controlling the build later.

top

<surround>

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

Attributes

Attribute Required

Description

branch No Surround SCM branch name. The default is pulled from the local working directory.

repository

No Surround SCM repository path. The default is pulled from the local working directory.

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

searchregexp

No If set to 1, the file parameter will be interpreted as a regular expression. Options are 1 or 0 (default).

recursive No Recursively check files and sub-repositories. Options are 1 or 0 (default).

serverconnect No

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.

serverlogin No

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.

property No Set this property if a modification has occurred. For use in conditionally controlling the build later.

top

<svn>

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

Checks for changes within a Subversion repository.

Attributes

Attribute Required

Description

LocalWorkingCopy

One of these

Relative or absolute path to the local working copy of the Subversion repository of which to find the log history.

Attribute Required

Description

RepositoryLocation

The url to the Subversion repository on which to find the log history.

username No used for authentication.password No used for authentication.

configDir NoInstructs Subversion to read configuration information from the specified directory instead of the default location (.subversion in the user's home directory).

property No Set this property if a modification has occurred. For use in conditionally controlling the build later.

propertyondelete

No Set this property if a file has been deleted. For use in conditionally controlling the build later.

checkExternals

No Whether any subversion externals this project uses should also be checked for modifications.

useLocalRevision false

Optionally allows the user to get the modifications made between the last build time and the localworkingcopy's revision number.

Properties Passed to the Builders

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

Property Name

Description

svnrevision The repository revision number

top

<tfs>

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

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

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

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

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

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

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

Attributes

Attribute Required Descriptionprofile

One of these

Name of the profile to set. Supported by the Teamprise client.

server URL to access the Team Foundation Server including port, for example http://tfserver:8080

projectPath

yesPath in the TFS repository that is recursively checked for modifications.  Any changes under that path will trigger a build.

tfPath

No (defaults to "tf")

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 C:\Program Files\Microsoft Visual Studio 8\Common7\IDE\TF.exe

inputEncoding

No (defaults to UTF-8)

Required if file names or comments contains non-Latin symbols

username no

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.

The username should be passed in the form DOMAIN\username.  From unix systems the name can be passed in the username@DOMAIN format if preferred as that removes confusion over escaping of the \ character which should not be required.

password no The password to use with the username when authenticating with the server.

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

Properties Passed to the Builders

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

Property Name

Description

tfschangeset

The maximum changeset number in the modifications detected

top

<timebuild>

<cruisecontrol>

<project> <modificationset> <timebuild>

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

Attributes

Attribute

Required Description

username

No (defaults to "User")

The username to use for the single reported (fake) Modification.

time Yes The threshold time to cross that starts triggering a build, specified as hhmm format.

property

No Set this property if a modification has occurred. For use in conditionally controlling the build later.

top

<ucm>

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

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

Attributes

Attribute

Required Description

stream YesThe ClearCase UCM stream (actually, the branch, so make sure to enter the branch type if it is named differently than your UCM stream)

rebases No (defaults to false)

Whether rebases of the integration stream are reported as changes.

pvobNo (unless rebases is true)

The name of the pvob to use for queries. Required if rebases = true. Required if multiVob is true and the pvob for the project is not loaded or mounted.

contributors

No (defaults to true)

Whether to check for and log contributor activities

viewpath Yes Local working copy to use when making queries

property No Set this property if a modification has occurred. For use in conditionally controlling the build later.

multiVob No Set whether the view contains multiple vobs. Defaults to false.

Properties Passed to the Builders

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

Property Name

Description

ucmlastbuil Timestamp representing the last built time, using the format dd-MMMM-

Property Name

Description

d yyyy.HH:mm:ss

ucmnow Timestamp representing the time the current build started, using the format dd-MMMM-yyyy.HH:mm:ss

top

<veto>

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

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

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

Child Elements

Element Cardinality

Description

<triggers> 1

A container for one or more source control elements that trigger a full check of the targets. Any child element of <modificationset> can be used as a child element of <triggers>.

<buildstatus>

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

Example

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

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

<vss>

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

Checks for changes in a Visual SourceSafe repository.

Attributes

Attribute Required Description

dateformatNo (defaults to default is MM/dd/yy)

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 dd/MM/yy.

timeformatNo (default is hh:mma)

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 HH:mm:ss.

vsspath Yes The VSS project to get history from.Example: /Project/subproject

login Yes The VSS login to use, in the form username,password

ssdir NoPath to the directory containing ss.exe. By default, ss.exe is assumed to be in the path.Note: should not contain whitespace.

serverpath No Path to the directory containing srcsafe.ini.

property No Set this property if a modification has occurred. For use in conditionally controlling the build later.

propertyondelete

No Set this property if a file has been deleted. For use in conditionally controlling the build later.

top

<vssjournal>

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

Checks for changes in a Visual SourceSafe repository.

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

Attributes

Attribute Required

Description

journalfile Yes Full path to journal file. Example: c:/vssdata/journal/journal.txt

ssdir Yes The VSS project to get history from

property No Set this property if a modification has occurred. For use in conditionally controlling the build later.

propertyondelete

No Set this property if a file has been deleted. For use in conditionally controlling the build later.

top

<schedule>

<cruisecontrol> <project> <schedule>

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

Note: Only one builder is used for a given interval where modifications are found. Builds using the time attribute take precedence over builds using the multiple attribute. If no matching time builds are found the multiple builds are evaluated by the value of their multiple from high to low. If there are multiple Builders with the same multiple only one will build but which one is undefined.

Attributes

Attribute Required Description

interval No

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.

showProgress

No (defaults to true)

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.

Child Elements

Element Cardinality

Description

<ant> 0 .. * Builds the project using Ant.<composite>

0 .. * Executes a list of builds.

<maven> 0 .. * Builds the project using Maven.

<maven2> 0 .. * Builds the project using Maven2.

<pause> 0 .. * Pauses the build.<nant> 0 .. * Builds the project using NAnt.<phing> 0 .. * Builds the project using Phing.<rake> 0 .. * Builds the project using Rake.

<exec> 0 .. * Builds the project using the ExecBuilder.

<pipedexec>

0 .. * Builds the project using the PipedExecBuilder.

<xcode> 0 .. * Builds the project using Apple's Xcode IDE.

Common Builder Attributes

Attribute Required Description

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

time No Time in the form HHmm. Can't be set if multiple is set.day No Valid values are (case-insensitive) the English names for the

days of the week (Sunday, Monday, Tuesday, etc). Does not

Attribute Required Descriptionsupport multiple days except for the default of every day.

showProgress

No (defaults to true)

If true, the builder will provide short progress messages, visible in the JSP reporting application. If parent builders exist (eg: composite), and any parent's showProgress=false, then no progress messages will be shown, regardless of this builder's showProgress setting.

liveOutput

No (defaults to true)

If true, the builder will write all output to a file that can be read by the Dashboard reporting application while the builder is executing.

Properties Passed to Builders

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

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

Property Name Descriptionprojectname The name of the CruiseControl project.label The build label determined by the labelincrementer

cvstimestampTimestamp that indicates when the build started, using the format yyyy-MM-dd HH:mm:ss 'GMT' so it can be used as a CVS argument

cctimestamp Timestamp that indicates when the build started, using the format yyyyMMddHHmmss

cclastgoodbuildtimestamp

Timestamp that indicates when the last successful build was run, using the format yyyyMMddHHmmss. Only available if the project has previously built successfullly.

cclastbuildtimestamp

Timestamp that indicates when the last build was run, using the format yyyyMMddHHmmss. Only available if the project has built prevviously.

lastbuildsuccessful

indicates if the last build was successful; either "true" or "false"

buildforced indicates if the build was forced; either "true" or "false"

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

<buildstatus> sets specific properties. <clearcase> sets specific properties. If specified, the property or propertyondelete attribute value will be set.

This feature is supported by <clearcase>, <cvs>, <filesystem>, <mavensnapshotdependency>, <maven2snapshotdependency>, <mks>, <snapshotcm>, <starteam>, <vss> and <vssjournal>.

top

<ant>

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

Specifies an Ant build to be run at a given time or build number. For instance, we can run a clean build every 5 builds, or run more comprehensive (and time

intensive) system tests every 10 builds. We can also schedule an official build to run every night at midnight, if we so desire.

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

1. Using the antscript, or anthome, attribute (preferred) helps to ensure that builds are run completely independent of the CruiseControl distribution, and that extra jars required in the ant lib-directory need not be duplicated within CruiseControl.

2. Using the ant binaries distributed with CruiseControl. Settings for the virtual machine can be specified using the nested <jvmarg> element. This also requires that java be on the executable path.

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

See below for examples of the <ant> element.

Attributes

See also the common attributes for builders.

Attribute Required Description

buildfile No (defaults to build.xml)

Path to Ant build file.

target No Ant target(s) to run. Default is "", or the default target for the build file.

tempfile No Name of temp file. Defaults to log.xml

antscript

No, but recommended. Cannot be specified if anthome attribute is also specified

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

anthomeNo. Cannot be specified if antscript attribute is also specified.

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

antWorkingDir No Will invoke ant in the specified directory.

saveLogDir NoIf supplied a copy of the ant log will be saved in the specified directory. Example: saveLogDir="/usr/local/dev/projects/cc/logs"

timeout NoAnt build will be halted if it continues longer than the specified timeout. Value in seconds.

uselogger No '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 Ant manual). 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

Attribute Required Descriptionrecommended for production situations.

RE: liveOutput: If liveOutput=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. The liveOutput setting has no effect if uselogger=false. AntBootstrapper and AntPublisher do not provide access to liveOutput, and operate as if liveOutput=false. 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 liveOutput=false (and please report the problem).

loggerclassname

No (defaults to org.apache.tools.ant.XmlLogger)

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.

usedebug No

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.

usequiet No

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.

RE: showProgress: useQuiet="true" will prevent any progress messages from being displayed. 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).

keepgoing No

If true will invoke ant with -keep-going, which can be useful for performing build steps after an optional step fails. Defaults to 'false'.

propertyfile No

Load all properties from file with -D properties (like child <property> elements) taking precedence. Useful when the propertyfile content can change for every build.

progressLoggerLib

No Overrides the default -lib search path used to add support for showProgress features in the ant builder. This search path ensures

Attribute Required Descriptioncustomized 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.

Child Elements

Element Cardinality

Description

<jvmarg>

0 .. *

Pass specified argument to the jvm used to invoke ant. Ignored if using anthome or antscript. The element has a single required attribute: "arg".Example: <jvmarg arg="-Xmx120m"/>

<property>

0 .. *

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"Example: <property name="foo" value="bar"/>

<lib> 0 .. *Used to define additional library directories for the ant build. The element has one required attribute: "searchPath".Example: <lib searchPath="/home/me/myantextensions"/>

<listener>

0 .. *

Used to define additional listeners for the ant build. The element has one required attribute: "classname".Example: <listener classname="org.apache.tools.ant.listener.Log4jListener"/>

Examples

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

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

<schedule>

Or equivalently, using the anthome attribute

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

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

9. <schedule>10. <ant antscript="/home/cc/workspace/build.sh"11. antworkingdir="/home/cc/workspace"12. target="smoketest"13. uselogger="true"/>

<schedule>

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

#!/bin/shPROJECT_HOME=`dirname "$0"`ANT_HOME=${PROJECT_HOME}/tools/antchmod 0755 ${ANT_HOME}/bin/antANT_CMD=${ANT_HOME}/bin/antexec "$ANT_CMD" "$@"

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

An example of a Windows batch file to invoke ant:

@echo offsetlocalset PROJECT_HOME=%~dp0call %PROJECT_HOME%..\devtools\env.batcall ant.bat %*endlocal

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

top

<maven>

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

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

The goal attribute has the following usage examples:

"clean" will run 'clean' goal on the project "clean java:compile" will run 'clean' goal then 'java:compile' goal on the

project, within the same Maven session run "clean my-cvs-update|java:compile" will run 'clean' goal then 'my-cvs-

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

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

Attributes

See also the common attributes for builders.

Attribute

Required

Description

mavenscript

Yes Absolute filename of maven startup script (maven.bat or maven.sh).

projectfile

Yes Path to Maven's "project.xml" file

goal Yes Maven goal, "set of goals" or "set of set of goals" to run. (see above Note2)

timeout No Build will be halted if it continues longer than the specified timeout. Value in seconds.

<maven2>

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

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

The goal attribute has the following usage examples:

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

Goals "clean compile" will run 'clean' goal then 'compile' goal on the project,

within the same Maven2 session run

Sessions "clean scm:update|deploy" will run 'clean' goal then 'scm:update' goal on

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

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

Attributes

See also the common attributes for builders.

Attribute Required

Description

mvnscriptOne of these

Path to maven startup script (.../bin/mvn.bat or mvn.sh).

mvnhomePath to Maven2's home directory (M2_HOME). Maven script will be found by appending "/bin/mvn" (or "/bin/mvn.bat") to this directory.

pomfile Yes Path to Maven2's "pom.xml" file

goal Yes Maven2 goal, "set of goals" or "set of set of goals" to run. (see Goals note above)

sitegoal No Maven2 site goal, "set of site goals" or "set of set of site

Attribute Required

Description

goals" to run after those configured in above mentioned goal attribute (even when these goals failed). For example <maven2 ... goal="clean|install" sitegoal="site|dashboard:dashboard|site:deploy"/>. This way it is possible to supply a site with test failure info.

settingsfile

No Alternate path for the user settings file.

activateprofiles

No Comma-delimited list of profiles to activate.

flags NoCommand line flags to be passed to maven. For example: '-U -Dmaven.test.skip=true'. The flags will be passed to each session invocation (see Sessions note above).

timeout No Build will be halted if it continues longer than the specified timeout. Value in seconds.

Child Elements

Element Cardinality

Description

<property> 0 .. *

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 Sessions note above).Example: <property name="foo" value="bar"/>

top top

<composite>

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

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

Attributes

See also the common attributes for builders.

Attribute Required Description

timeout No Composite Build will be halted if it continues longer than the specified timeout. Value in seconds.

showProgress

No (defaults to true)

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.

liveOutput

No (defaults to true)

Currently, the liveOutput setting has no effect on composite builders.

Child Elements

Element Cardinality

Description

<ant> 0 .. * Builds the project using Ant.<maven> 0 .. * Builds the project using Maven.

<maven2> 0 .. * Builds the project using Maven2.

<nant> 0 .. * Builds the project using NAnt.<phing> 0 .. * Builds the project using Phing.<rake> 0 .. * Builds the project using Rake.

<exec> 0 .. * Builds the project using the ExecBuilder.

<pipedexec>

0 .. * Builds the project using the PipedExecBuilder.

<xcode> 0 .. * Builds the project using Apple's Xcode IDE.

top top

<pause>

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

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

Attributes

Attribute

Required

Description

day No Day when the pause should take place (Sunday, Monday, etc). Does not support multiple days except for the default of every day.

starttime

Yes Start of the pause in HHmm format

endtimeYes End of the pause in HHmm formattop

<nant>

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

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

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

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

See below for examples of the <nant> element.

Attributes

See also the common attributes for builders.

Attribute Required Description

buildfile No (defaults to default.build)

Path to NAnt build file.

target No NAnt target(s) to run. Default is "", or the default target for the build file.

tempfile No Name of temp file. Defaults to log.xmltargetFramework

No, but recommended

Specifies the framework to target. Typical values are "net-1.1" and "mono-1.0".

nantWorkingDir

No Will invoke NAnt in the specified directory.

timeout No NAnt build will be halted if it continues longer than the specified timeout. Value in seconds.

uselogger No

'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 NAnt documentation). 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.

loggerclassname

No (defaults to NAnt.Core.XmlLogger)

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.

usedebug No

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

usequiet No

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

Child Elements

Element Cardinality

Description

<property>

0 .. *

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"Example: <property name="foo" value="bar"/>

Examples

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

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

<schedule>7. Invoke NAnt, specifying the working directory as /home/cc/workspace, the

build file as default.build, the nant target as smoketest, and the targetframework as .NET version 1.1.

8. <schedule>9. <nant targetframework="net-1.1"10. nantworkingdir="/home/cc/workspace"11. target="smoketest"12. uselogger="true"/>

<schedule>top

<phing>

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

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

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

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

See below for examples of the <phing> element.

Attributes

See also the common attributes for builders.

Attribute Required Description

buildfile No (defaults to build.xml)

Path to Phing build file.

target No Phing target(s) to run. Default is "", or the default target for the build file.

tempfile No Name of temp file. Defaults to log.xml

phingscript

No. Cannot be specified if phinghome attribute is also specified

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.

phinghome No. Cannot be specified if phingscript attribute is also

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

Attribute Required Descriptionspecified.

phingWorkingDir

No Will invoke phing in the specified directory.

saveLogDir NoIf supplied a copy of the phing log will be saved in the specified directory. Example: saveLogDir="/usr/local/dev/projects/cc/logs"

timeout No Phing build will be halted if it continues longer than the specified timeout. Value in seconds.

uselogger No

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

loggerclassname

No (defaults to phing.listener.XmlLogger)

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.

usedebug No

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.

usequiet No

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.

Child Elements

Element Cardinality

Description

<property>

0 .. *

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"Example: <property name="foo" value="bar"/>

Examples

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

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

<schedule>

Or equivalently, using the phinghome attribute

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

top

<rake>

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

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

When a build runs, Rake is invoked in a separate Java process.

Attributes

See also the common attributes for builders.

Attribute

Required Description

rubyNo (defaults to ruby)

Name of / Path to the ruby interpreter. Typical values are "ruby", "ruby19" or "jruby"

rakeNo (defaults to rake)

Name of / Path to the rake binary. Typical values are "rake", "rake19" or "jrake"

buildfile

No (defaults to Rakefile)

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

target No Rake target(s) to run. Default is "", or the default target for the rake file.

workingDir No

Will invoke rake in the specified directory. The directory can be relative (to the cruisecontrol current working directory) or absolute.

timeout No Rake build will be halted if it continues longer than the specified timeout. Value in seconds.

top

<exec>

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

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

See below for examples of the <exec> element.

Attributes

See also the common attributes for builders.

Attribute

Required

Description

command Yes The command or script to be executed.

args No Set of arguments (as a single string) to be passed to the command or script.

workingdir

No The directory in which the script or command is to be executed. Defaults to the Java temporary directory.

errorstr

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

timeout No Build will be halted if the script or command continues longer than the specified timeout. Value in seconds.

Examples

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

2. <schedule>3. <exec workingdir="/workspace/${projectname}"4. command="/usr/local/bin/Perl"5. args="backup.pl"/>

</schedule>6. Invoke execbuilder, specifying the working directory as D:\Workspace\

MyProject, the script file as build.bat, its arguments as smoketest, and the error message to be search for as build failed.

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

</schedule>12. Invoke execbuilder to call a function of the shell, in this case copy. 13. <schedule>14. <exec command="cmd.exe"15. workingdir="D:\Workspace\MyProject"16. args="copy foo.txt bar.txt"

</schedule>top

<pipedexec>

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

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

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

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

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

See below for examples of the <pipedexec> element.

Attributes

See also the common attributes for builders.

Attribute

Required

Description

workingdir No

The directory in which all the scripts or commands are to be executed. Each individual script or command may override this value. Defaults to the Java temporary directory.

timeout No

Build will be halted if the scripts or commands running under the pipedexec continue longer than the specified timeout. Each individual script or command may also set its own limitation. Value in seconds.

Child Elements

Element

Cardinality

Description

<exec> 0 .. * Runs a specified command or script under the piped exec builder, and optionally pipe it with another command(s) or script(s).

The <exec> element is based on the ExecBuilder, so it has the same attributes and capabilities (i.e. setting its own workingdir,

timeout and/or error string). In addition, <exec> as piped exec builder children have the following attributes: Attribu

teRequired

Description

id YesThe unique identifier of the command or script script (any string). The value is referenced by pipefrom and waitfor attributes.

pipefrom

No

The ID of script to connect to - the STDIO of this command or script is fed up by STDOUT of <exec> with the given ID. Several <exec> may be piped from one ID.

waitforNo The execution of this command or script will be hold

Element

Cardinality

Description

Attribute

Required

Description

until <exec> with the given ID finishes. It may be used to prevent memory exhausting/swapping, or to wait for data generated by another script and not passed through STDOUT-STDIN pipe.

Examples

Suppose that all the scripts read data either from input file (option -i), or from STDIN if no file is given. Also suppose that they write output into file (option -o) or into STDOUT if no file is given.

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

2. <schedule>3. <pipedexec workingdir="/workspace/${projectname}">4. <exec id="1"5. command="/usr/local/bin/Perl"6. args="first.pl -i data.txt" />7. <exec id="2"8. pipefrom="1"9. command="/usr/local/bin/Perl"10. args="second.pl -o result.txt" />11. </pipedexec>

</schedule>12. Invoke piped exec builder, specifying another working directory for

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

13. <schedule>14. <pipedexec workingdir="/workspace/${projectname}">15. timeout="60"16. <exec id="1"17. command="/usr/local/bin/Perl"18. args="first.pl -i data.txt" />19. timeout="10" />20. errorstr="error occurred" />21. <exec id="2"22. pipefrom="1"23. command="/usr/local/bin/Perl"24. args="second.pl -o results.txt" />25. <exec id="3"26. pipefrom="1"27. command="/usr/local/bin/Perl"28. args="third.pl -o result.txt"29. workingdir="/distribution/${projectname}" />30. </pipedexec>

</schedule>31. Invoke more complicated piped exec builder, where 5th script required

data generated by 2nd and 4th scripts, and 6th script requires data generated by 2th and 5th script. Therefore, scripts must wait for each other.

32. <schedule>33. <pipedexec workingdir="/workspace/${projectname}">34. <exec id="1"35. command="/usr/local/bin/Perl"36. args="first.pl -i data.txt" />37. <exec id="2"38. pipefrom="1"

39. command="/usr/local/bin/Perl"40. args="second.pl" />41. <exec id="3"42. pipefrom="2"43. command="/usr/local/bin/Perl"44. args="third.pl" />45. <exec id="4"46. pipefrom="3"47. command="/usr/local/bin/Perl"48. args="fourth.pl -o 4out.txt" />49. <!-- must not start until 4out.txt is ready. Without 'waitfor' it

would be started50. before 4 is finished! -->51. <exec id="5"52. pipefrom="2"53. waitfor="4"54. command="/usr/local/bin/Perl"55. args="fiveth.pl -e 4out.txt -o 5out.txt" />56. <!-- The same here -->57. <exec id="6"58. pipefrom="2"59. waitfor="5"60. command="/usr/local/bin/Perl"61. args="sixth.pl -e 5out.txt" />62. <exec id="7"63. pipefrom="6"64. command="/usr/local/bin/Perl"65. args="seventh.pl -o results.txt" />66. </pipedexec>

</schedule>top

<xcode>

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

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

Attributes

See also the common attributes for builders.

Attribute

Required

Description

directory

Yes Path the directory where xcodebuild will execute

timeoutNo Build will be halted if the command continues longer than the specified timeout. Value in seconds.

Child Elements

Element

Cardinality

Description

<arg> 0 .. *

Pass specified argument to xcodebuild. The element has the required attribute: value. Any of the properties passed to builders can be substituted into the value. Example: <arg value="-project ${projectname}"/>.

top

<log>

<cruisecontrol> <project> <log>

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

Attributes

Attribute Required

Description

dir No The cruisecontrol log directory. Default is "logs/[projectname]".

encoding No Encoding for CruiseControl's XML log file.

trimWhitespace No

if true, trim whitespace from start and end of log lines. Primarily intended only to force historic "trim" behavior. Defaults to false.

Child Elements

Element Cardinality

Description

<merge> 0 .. * Merges log file together.

<gzip> 0 .. 1 GZips old log files

<delete> 0 .. 1 Deletes old log files.

<deleteartifacts>

0 .. 1 Deletes old artifact directories.

top

<merge>

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

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

Attributes

Attribute Required Descriptionfile

One of file or dir.

path to file to merge into build log

dir all files matching the specified pattern will be merged into the build log.

removeproperties

No (defaults to true)

when merging a JUnit xml file should the properties section be removed.

pattern NoSpecifies the pattern which matches the filenames to merge. This pattern should be a valid Jakarta-ORO Glob pattern. Defaults to "*.xml".

top

<gzip>

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

After the build-file is written, this manipulator gzips all old log files that may exist.

Attributes

Attribute

Required

Description

every true Sets the amount of Units after which the logfiles are backuped.

unit true The Unit for backups. Valid Units are DAY, WEEK, MONTH or YEAR

top

<delete>

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

After the build-file is written, this manipulator deletes all old log files that may exist.

Attributes

Attribute

Required

Description

every true Sets the amount of Units after which the logfiles are deleted.

unit true The Unit for deletions. Valid Units are DAY, WEEK, MONTH or YEAR

ignoreSuffix

true Ignores default xml-suffix when deleting files, so other logfiles could be deleted

top

<deleteartifacts>

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

After the build-file is written, this manipulator deletes all old artifact directories that may exist.

Attributes

Attribute

Required

Description

every true Sets the amount of Units after which the artifact directories are deleted.

unit true The Unit for deletions. Valid Units are DAY, WEEK, MONTH or YEAR

top

<publishers>

<cruisecontrol> <project> <publishers>

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

Child Elements

Element Cardinality

Description

<antpublisher> 0 .. * Executes an Ant script which implements a custom publisher.

<artifactspublisher> 0 .. * Copies build products to a directory<clearcasebaselinepublisher>

0 .. * Creates a ClearCase UCM baseline.

<cmsynergybaselinepublisher>

0 .. * Creates an intermediate baseline in a CM Synergy database.

<cmsynergytaskpublisher>

0 .. * Copies all new CM Synergy tasks into a shared folder.

<compoundpublisher> 0 .. * Executes all publishers specified as child elements.<email> 0 .. * Sends an email with a URL to the build results JSP<execute> 0 .. * Execute a command as part of the publishing phase

<ftppublisher> 0 .. * Copies the log file and build artifacts to an FTP server

<htmlemail> 0 .. * Sends an email with the build results embedded as HTML

<http> 0 .. * Connects to an HTTP URL and sends the build results as parameters

<jabber> 0 .. * Sends an instant message with a link to the build results via a Jabber server using XMPP

<onfailure> 0 .. 1 Executes all publishers specified as child elements if and only if the current build failed.

<onsuccess> 0 .. 1 Executes all publishers specified as child elements if and only if the current build was successful.

<origo> 0 .. * Creates/closes an issue in an Origo project.<sametimeannouncement>

0 .. * Sends Sametime announcements with the result of the build

<scp> 0 .. * Copies a file using SCP

<sfeedocman> 0 .. * Uploads a document to a SourceForge Enterprise Edition project's Document Manager.

<sfeefrs> 0 .. * Uploads a file to a SourceForge Enterprise Edition project's file release system (FRS).

<sfeetracker> 0 .. * Creates a Tracker artifact in a SourceForge Enterprise Edition project.

<socket> 0 .. * Writes "Success" or "Failure" to a socket<x10> 0 .. * Controls an x10 electronic device<xsltlogpublisher> 0 .. * Performs a transformation of the log file

Element Cardinality

Description

<yahoopublisher> 0 .. * Sends an instant message with a link to the build results via a Yahoo IM message

top

<antpublisher>

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

Executes an Ant script which implements a custom publisher.

Attributes

The antpublisher uses the same attributes as the <ant> builder.

Child Elements

The antpublisher supports the same set of child elements as the <ant> builder.

Properties Passed to the Publisher

The <antpublisher> passes all of the same properties that are passed by <ant> and

the other builders. Those properties are augmented by <antpublisher> to include the following additional properties:

Property Name Descriptionthisbuildsuccessful

Set to true if the current build was successful, false otherwise. See also the <onsuccess> and <onfailure>.

projectname The name of the CruiseControl project.

lastbuild The timestamp of the last attempted build, using the format yyyyMMddHHmmss.

lastsuccessfulbuild

The timestamp of the last successful build, using the format yyyyMMddHHmmss.

builddate The date of the last build, formatted using the default format.interval The time interval between builds.logdir The directory containing the log file from the last build.logfile The name of the log file from the last build.

Examples

1. Invoke the ant.bat script distributed with ant, specifying the working directory as D:\workspace\MyProject and the ant build file as MyProject-nightlybuild.xml and the ant target as publish. Pass in the property "custom" with a value of "true".

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

</publishers>

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

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

For additional examples, please see the <ant> builder. top

<artifactspublisher>

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

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

Attributes

Attribute Required Descriptionfile one of file

or dirwill copy specified file

dir will copy all files from this directory

dest Yesparent directory of actual destination directory; actual destination directory name will be the build timestamp.

subdirectory No subdirectory under the unique (timestamp) directory to contain artifacts

publishOnFailure

No (defaults to true)

Deprecated. Use <onsuccess> and <onfailure> instead.set this attribute to false to stop the publisher from running when the build fails.

moveInsteadOfCopy

No (defaults to false)

The publisher will move files/directrories instead of copying them.

top

<clearcasebaselinepublisher>

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

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

Attributes

Attribute Required

Description

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

full NoBoolean value indicating whether a "Fully Labelled" or "Incremental" baseline should be created. Default is false, i.e. "Incremental".

baselineprefix

No

A prefix which should be applied together with the CruiseControl ${label} property, for example specifying "EXAMPLE_" with a CruiseControl generated label of "1_INT" would create a baseline called "EXAMPLE_1_INT".

component NoThe component to restrict the baseline creation to. By default the baseline is applied to all of the stream's changed components.

Examples

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

2. <publishers>3. <clearcasebaselinepublisher viewtag = "j2ee_int"4. baselineprefix = "J2EE_"5. component = "J2EE_SRC"/>6. </publishers>

top

<cmsynergybaselinepublisher>

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

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

Attributes

Attribute Required

Description

ccmexe NoThe 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).

sessionfile No

The session file used by the <cmsynergysessionmonitor> to persist your CM Synergy session information. If this attribute is not set, it defaults to the file ".ccmsessionmap" in your home directory.

sessionname

No

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.

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

purpose No The purpose of the baseline. If not specified, this will default

Attribute Required

Description

to "Integration Testing".description

No An optional description of the baseline.

baselinename

No

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

build No A value for the build attribute introduced for baselines since Synergy 6.4.

state No

A value specifying the state the the baseline should be created with. The state attribute is new since Synergy 6.4 and will only be used if 6.4 is detected. Acceptable values for the attribute are "published_baseline, "test_baseline",and "released". The default value is "published_baseline".

Examples

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

2. <publishers>3. <cmsynergybaselinepublisher sessionname = "j2ee_session"4. project = "j2ee~1.0_int"5. baselinename = "BUILD_@{cctimestamp}"/>6. </publishers>

top

<cmsynergytaskpublisher>

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

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

Attributes

Attribute Required Description

ccmexe NoThe 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).

sessionfile

No

The session file used by the <cmsynergysessionmonitor> to persist your CM Synergy session information. If this attribute is not set, it defaults to the file ".ccmsessionmap" in your home directory.

sessionname

No

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.

foldernumber

Either foldernumber or foldername and

The number of the target folder.

foldernam A substring of the name of the target folder (i.e.

Attribute Required Description

e

project

"Integration tested tasks"). If this attribute is set, you must also set the project attribute.

project The two part name of the project which contains the named folder.

Examples

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

2. <publishers>3. <cmsynergytaskpublisher sessionname = "j2ee_session"4. foldernumber = "203"/>5. </publishers>

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

7. <publishers>8. <cmsynergytaskpublisher sessionname = "j2ee_session"9. project = "j2ee~1.0_int"10. foldername = "Integration tested tasks"/>11. </publishers>

top

<execute>

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

Execute a command as part of the publishing phase.

Attributes

Attribute

Required

Description

commandYes The command to execute

top

<scp>

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

SCP a file as part of the publishing process.

Attributes

Attribute Required DescriptionexecutableName

No Specify the name of the executable to invoke. Default is "scp".

sourceuser Yes if sourcehost is specified

Log in to the sourcemachine as this user.

Attribute Required Description

sourcehost Yes if sourceuser is specified

SCP from this machine.

sourcedir No (defaults to '.') The directory to copy from.

targetuser Yes if targethost is specified

Log in to the target machine as this user.

targethost Yes if targetuser is specified

SCP to this machine.

targetdir No (defaults to '.') The directory to copy to.

targetseparator

No (defaults to File.separator on the source machine)

The file separator on the target machine.

sourceseparator

No (defaults to File.separator on the source machine)

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.

ssh No (defaults to 'ssh')

The ssh application.

options No Additional options to pass to SCP.

file No (defaults to the current logfile)

The filename to copy.

top

<sfeedocman>

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

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

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

Attributes

Attribute

Required

Description

serverurl

Yes URL for the SFEE instance.

username Yes Valid username for the specified SFEE instance.password Yes Password for the specified username.document Yes The path to the document to publish.folder Yes The Document Manager folder in which to publish.projectName

Yes The name of the SFEE project where the Document Manager folder specified exists.

Child Elements

Element Cardinality

Description

<description> 1 The description for the Document. This child element is required and is an XPath Aware Child. Look there for

Element Cardinality

Description

attribute details.

<status> 1The status for the Document. This child element is required and is an XPath Aware Child. Look there for attribute details.

<documentname> 0..1

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 XPath Aware Child. Look there for attribute details.

<versioncomment> 0..1

The version comment for the Document. This child element is optional and is a XPath Aware Child. Look there for attribute details.

Examples

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

<sfeefrs>

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

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

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

Attributes

Attribute

Required Description

file Yes Path to a file on the local filesystem that should be uploaded.

serverurl

Yes URL for the SFEE instance.

username Yes Valid username for the specified SFEE instance.

password Yes Password for the specified username.

Attribute

Required Description

releaseid

Yes The SFEE id for the FRS release, e.g. rel2509.

uploadname

No (defaults to the same name as the local file)

The name to be used for the file in the FRS.

Examples

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

<sfeetracker>

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

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

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

Attributes

Attribute

Required

Description

trackerName

Yes The name of the Tracker within the specified SFEE project.

projectName

Yes The name of the SFEE project where the tracker specified exists.

serverurl

Yes URL for the SFEE instance.

username Yes Valid username for the specified SFEE instance.

password Yes Password for the specified username.

Child Elements

Element Cardinality

Description

<title> 1The title for the tracker artifact. This child element is required and is an XPath Aware Child. Look there for attribute details.

<description> 1

The description for the tracker artifact. This child element is required and is an XPath Aware Child. Look there for attribute details.

<status> 1The status for the tracker artifact. This child element is required and is an XPath Aware Child. Look there for attribute details.

<field> 0..*Sets a field that exists in the tracker artifact. This child element is optional and is a Named XPath Aware Child. Look there for attribute details.

Examples

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

<email>

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

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

Attributes

Attribute Required Description

buildresultsurl No

URL to the build results JSP. This defaults to the hostname, domain name and web port (if specified) of the server, followed by /dashboard.

defaultsuffix No

Default e-mail suffix to append to user names to build valid e-mail addresses. This defaults to an empty string if not specified.

failasimportant

No Flag emails about failed builds as important? Default is 'true'.

mailhost No

Mail server address to use for sending build notification emails. If not set, CruiseControl will attempt to connect directly to the SMTP servers defined in the DNS MX records for each recipient's domain.

mailport No Mail server port

username

if password is specified

Username for smtp server

Attribute Required Description

password

if username is specified

Password for smtp server

reportsuccess

No (defaults to always

Valid values: always:

publishes (i.e., e-mails) results on every successful build.

fixes:publishes results only on the first successful build and the first successful build after a failed build.

never:only publishes on failed builds

returnaddress

Yes E-mail address that will appear in the sent email's From field

returnname No A name to match to the return address

skipusersNo (defaults to false)

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.

spamwhilebroken

No (defaults to true)

Whether or not e-mail reports on failed builds will continue for subsequent failed builds.

subjectprefix

No Prefix for subject line of email. Useful for easily filtering email.

usessl No "true" to connect to the smtp server using SSL. Do not forget to set the corresponding mailport.

Child Elements

Element Cardinality

Description

<always> 0 .. *

Mail address to be emailed notification after all builds.

<always> has the following attributes: Attribu

teRequired

Description

addressYes e-mail address

<failure> 0 .. *

Mail address to be emailed notification after failed builds.

<failure> has the following attributes:

Attribute Required

Description

address Yes e-mail addressreportWhenFixed

No either true or false; defaults to false

<ignore> 0 .. *

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. <ignore> has the following attributes: Attribu

teRequired

Description

user Yes user name from modification to be ignored

<success> 0 .. *

Mail address to be emailed notification after successful

builds. <success> has the following attributes: Attribu

teRequired

Description

addressYes e-mail address

Element Cardinality

Description

<alert> 0 .. *

Mail address to be emailed notification if any of the build's modified files match the supplied regular

expression. <alert> has the following attributes: Attribut

eRequired

Description

fileRegExpr

Yes A regular expression indicating which modified files you are interested in

address Yes e-mail address

<map> 0 .. *

Maps a source control user id to an email address. <map> has the following attributes: Attribu

teRequired

Description

alias Yes alias (username) as it appears on modifications

addressYes e-mail address

<propertiesmapper> 0 .. *

map source control user names to either valid email names or

complete email addresses. <propertiesmapper> has the following attributes: Attribu

teRequired

Description

file Yes

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.

<harvestmapper> 0 .. *

Map source control user names to their respective email address using the Harvest user id and email address stored

in the Harvest repository. <harvestmapper> has the following attributes: Attribu

teRequired

Description

broker Yes The name of the Harvest Broker to connect to.

username

Yes Usename to use in connecting to the Harvest Broker.

password

Yes Password to use in connecting to the Harvest Broker.

<mavenmapper> 0 .. *

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 <id> element of the

<developer> entry. <mavenmapper> has the following attributes: Attribu

teRequired

Description

projectfile

Yes Full path to Maven's project.xml (Maven 1) or pom.xml (Maven 2) file.

<ldapmapper> 0 .. * map source control user names to either valid email names or

complete email addresses. <ldapmapper> has the following attributes: Attribute Required Description

url Yes URL used to connect to an LDAP server, e.g. ldap://ca.com:389

rootdn Yes search DN, scope is sub-tree-levelbinddn no DN to bind to the LDAPbindpassword

if binddn is

password to bind to the LDAP

Element Cardinality

Description

Attribute Required Descriptionspecified

searchtmpl

No

Search filter. Default: (cn=?). The ? character in the template is replaced by the user id to be mapped into an email address

searchattr

No

Default: mail. The LDAP attribute that is searched to retrieve the email address of the user id used in the search.

ctxfactory No

Default: com.sun.jndi.ldap.LdapCtxFactory. LDAP Context Factory to be used.

top

<htmlemail>

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

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

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

Attributes

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

Attribute Required Descriptionbuildresultsurl

No Email will include link to the build results JSP if this URL is provided.

charset No If not set the content type will be set to 'text/html'. If set the content type will be 'text/html;charset="value"'.

css

versions up to 2.3: unless xslfile specifiedversions 2.3 and greater: no

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.

logdir

No (Yes for versions < 2.2)

Path to the log directory as set in the log element of the configuration xml file. Follows default of log's dir-attribute since version 2.2

xsldir versions up to 2.3:

Directory where standard CruiseControl xsl files are located. Starting with version 2.3, the HTMLEmailPublisher will try to

Attribute Required Descriptionunless xslfile specifiedversions 2.3 and greater: no

determine the correct value itself when it's not specified and xslfile isn't used.

xslfile No If specified, xsldir, xslfilelist, and css are ignored. Must handle the entire document.

xslfilelist No

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.

Child Elements

Element Cardinality

Description

<parameter>

0 .. *

Parameters passed to the XSL files before transforming them to HTML. Check the Reporting application's documentation for

parameters used in the standard XSL files. <parameter/> has the following attributes: Attribu

teRequired

Description

name Yes the name of the XSLT parameter

value Yes the parameter's valuetop

<http>

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

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

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

Attributes

Attribute Required

Description

url Yes The URL to connect to. Must be of the HTTP protocol.

requestMethod

Yes HTTP request method. POST, GET etc.

Child Elements

Element Cardinality

Description

<paramet 0..* Sets an HTTP attribute-value parameter. If the request method is

Element Cardinality

Description

er>

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 Named XPath Aware Child. Look there for attribute details.

top

<jabber>

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

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

Attributes

Attribute Required

Description

host Yes The host of the Jabber server.

port No Port of the Jabber server. Defaults to 5222. Note: SSL typically runs on port 5223.

username YesUsername of the account used to send the instant message. For individuals, this is typically of the form 'foo' as opposed to 'foo@bar.com'

password Yes Password of the sender account

recipient Yes Username of the recipient of the instant message. Recipient username is typically fully qualified: foo@bar.com

chatroom No Whether the recipient is a group/chat (true) versus an individual (false). Defaults to false.

ssl No Whether the XMPP connection on host:port is using SSL.buildresultsurl

Yes Email will include link to the build results.

service No Service to use.top

<onfailure>

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

Provides the means to execute another publisher (or set of publishers) if and only if the current build has failed. This is accomplished by simply adding any desired publishers as child elements.

All child elements must meet the following criteria:

1. They must be registered as publishers. If you are adding a publisher which ships with CruiseControl, this will be done for you automatically. If you are adding a custom publisher, you must remember to register it with CruiseControl using a <plugin> element within your config file.

2. They must validate successfully regardless of whether or not the build was successful.

Child Elements

Element Cardinality

Description

Any defined publisher

1 .. * You may use any defined publisher as a child element.

Examples

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

2. <onfailure>3. <x10 houseCode="A" deviceCode="3"/>4. <antpublisher antscript="/opt/apache-ant-1.6.1/bin/ant"5. target="cleanupafterfailure">6. </antpublisher>7. </onfailure>

top

<onsuccess>

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

Provides the means to execute another publisher (or set of publishers) if and only if the current build was successful. This is accomplished by simply adding any desired publishers as child elements.

All child elements must meet the following criteria:

1. They must be registered as publishers. If you are adding a publisher which ships with CruiseControl, this will be done for you automatically. If you are adding a custom publisher, you must remember to register it with CruiseControl using a <plugin> element within your config file.

2. They must validate successfully regardless of whether or not the build was successful.

Child Elements

Element Cardinality

Description

Any defined publisher

1 .. * You may use any defined publisher as a child element.

Examples

1. After a successful build, use the x10 publisher to light up a lamp, and run the artifacts publisher to save the build artifacts.

2. <onsuccess>3. <x10 houseCode="A" deviceCode="7"/>4. <artifactspublisher dir="checkout/project1/dist"5. dest="artifacts/project1">6. </artifactspublisher>7. </onsuccess>

top

<origo>

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

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

Attributes

Attribute Required Description

apiurlNo (defaults to http://api.origo.ethz.ch/api/xmlrpc)

URL to Origo API

buildresultsurl

No (defaults to http://localhost:8180/)

URL to the build results JSP

issueprivate

No (defaults to true) Should the issue be private

issuesubject

No (defaults to Cruisecontrol failed)

Subject for newly created issue

issuetag No (defaults to cruisecontrol::failed)

Tag for newly created issue, must be unique in the project

projectname

Yes Name of the origo project

userkey Yes Origo user key to report/update the issue

Examples

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

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

top

<rss>

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

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

Attributes

Attribute Required

Description

buildresultsurl yes

RSS item will include a link to the build results page. Build results URL should look like 'http://MACHINENAME/cruisecontrol/buildresults/PROJECTNAME'.

channellinNo The primary URL associated with the RSS feed.

Attribute Required

Description

kurl

file Yes

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.

maxlength No The maximum number of items to maintain in the RSS file. Defaults to 10.

top

<sametimeannouncement>

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

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

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

Attributes

Attribute Required Descriptionbuildresultsurl No URL to include with the build results.host Yes Synonym for mailHost.username Yes User name to login to the Sametime community.

password NoPassword used to login to the Sametime community. If not specified, an anonymous login (using username) will be attempted.

community No Sametime community to login to. Default is null — appropriate for single community servers.

resolveusers No (defaults to true)

Whether addresses should be resolved as users.

resolvegroups No (defaults to true)

Whether addresses should be resolved as groups.

usegroupcontentNo (defaults to true)

Whether to send announcements to the content (members) of a group instead of the group directly.

handleresolveconflicts

No (defaults to recipient)

How to handle address resolution conflicts. Valid values: error:

abort the announcementwarn:

log a warning, ignoring the conflicting addresses

ignore:ignore the conflicting addresses

recipient:treat all conflicting addresses as recipients of the announcement

handleresolvefails No (defaults to error)

How to handle address resolution failures. Valid values: error:

abort the announcement

Attribute Required Descriptionwarn:

log a warning and proceedignore:

ignore the failure

handlequerygroupcontentfails

No (defaults to error)

How to handle group content query failures. Valid values: error:

abort the announcementwarn:

log a warning and proceedignore:

ignore the failuretop

<socket>

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

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

Attributes

Attribute Required Description

socketServer Yes Hostname (i.e., first argument for constructing a Java socket)

port Yes Port number for the listening socketsendProjectName

No (defaults to true)

Whether the project name should be appended to the result string.

sendFixed No (defaults to false)

Whether the publisher should send "Fixed" instead of "Success" after "Failure".

top

<twitter>

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

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

Attributes

Attribute

Required

Description

username

Yes Username for the Twitter account.

password

Yes Password for the Twitter account.

top

<weblog>

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

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

Examples

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

Attributes

Attribute Required Description

api No The API to use for posting to the blog. Accepted values include blogger and metaWeblog. Defaults to metaWeblog.

blogurl Yes The URL where your blog receives XML-RPC requests.

Attribute Required Description

blogid Yes The "identifier" for your blog. See your blog's documentation for the correct value.

username Yes The username for authentication.password Yes The password for authentication.logdir Yes The CruiseControl log directory.

xslfile

Yes, unless xsldir is used.

The XSL stylesheet used for transforming the build results into the message being posted to the blog.

xsldir

Yes, unless xslfile is used.

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.

cssYes, if xsldir is used.

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.

buildresultsurl No

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.

category No

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.

reportsuccess No

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

subjectprefix

No The prefix to use for blog entries' title.

top

<x10>

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

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

Quick Start

1. Buy the home automation kit found at http://www.x10.com/automation/x10_ck11a_1.htm.

2. Plug the computer interface to your serial port (for example, COM1 or /dev/ttyS0), and your powerline

3. Set the lamp module's house and device code such as A3 and plug it into your powerline.

4. Plug in an electronic device to the lamp module like a lava lamp or flashing red light found at http://www.bwild.com/redsiren.html.

5. Install the Java Communications API on your CruiseControl machine. On Windows, copy win32com.dll from the CruiseControl lib directory to your JAVA_HOME/bin directory. On Linux, first obtain the Linux zip file from http://www.sun.com/download/products.xml?id=43208d3d. At the time of this

writing, the name of the file was comm3.0_u1_linux.zip. Extract commapi/jar/comm.jar and commapi/docs/javax.comm.properties into the CruiseControl lib directory, overwriting the existing comm.jar file.Then extract commapi/lib/libLinuxSerialParallel.so and point LD_LIBRARY_PATH to it, like so:

export LD_LIBRARY_PATH=$HOME/commapi/lib${LD_LIBRARY_PATH+:$LD_LIBRARY_PATH}6. Add the x10 publisher to CruiseControl's config.xml. For example, on

Windows:

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

On Linux:

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

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

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

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

NOTE: If you receive the following error:

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

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

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

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

Attributes

Attribute Required Description

houseCode Yes The house code for the device to control, A through P case insensitive

deviceCode Yes The device code for the device to control, 1 -> 16

port No (defaults to COM2)

Serial port to which the computer interface controller is connected, e.g. COM1

Attribute Required DescriptiononWhenBroken

No (defaults to true)

Set to false if the device should turn on when the build is successful and off when failed

interfaceModel

No (defaults to CM11A)

Model number for the computer interface controller being used, either CM11A or CM17A (case insensitive).

Examples

<!--Turn on X10 device(s) A3 using a CM11A computer interface on COM2 whenever the build breaks.--><x10 houseCode="A" deviceCode="3"/><!--Turn on X10 device(s) P12 using a CM11A computer interface on COM2 whenever the build breaks.--><x10 houseCode="P" deviceCode="12"/><!--Turn on X10 device(s) A3 using a CM11A computer interface on COM1 whenever the build breaks.--><x10 houseCode="A" deviceCode="3" port="COM1"/><!--Turn on X10 device(s) A3 using a CM11A computer interface on COM1 whenever the build is successful.--><x10 houseCode="A" deviceCode="3" port="COM1" onWhenBroken="false"/><!--Same as the previous, only explicitly indicating which X10 computer interface is being used.--><x10 houseCode="A" deviceCode="3" port="COM1" onWhenBroken="false" interfaceModel="CM11A"/><!--Turn on X10 device(s) A3 using a CM17A computer interface on COM1 whenever the build is successful.--><x10 houseCode="A" deviceCode="3" port="COM1" onWhenBroken="false" interfaceModel="CM17A"/>top

<xsltlogpublisher>

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

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

Attributes

Attribute Required Descriptiondirectory Yes Directory for output fileoutfilename

No Name for the output file. Default uses the build label, 'label.log'

publishonfail

No (defaults to true)

Deprecated. Use <onsuccess> and <onfailure> instead.Generate file if the build failed?

xsltfile Yes XSL file to used for the transform.top

<yahoopublisher>

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

Sends an instant message with a link to the build results via a Yahoo IM message. To use this plugin you'll need to build the plugin.

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

Attributes

Attribute Required

Description

username YesUsername of the account used to send the instant message. For individuals, this is typically of the form 'foo' as opposed to 'foo@yahoo.com'

password Yes Password of the sender account

recipient YesUsername of the recipient of the instant message. Recipient username is typically of the form 'foo' as opposed to 'foo@yahoo.com'

buildresultsurl

Yes Email will include link to the build results.

proxyHost No HTTP proxy to use.proxyPort No HTTP proxy port to use.top

<plugin>

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

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

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

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

Attributes

Attribute

Required

Description

name Yes The alias used to refer to the plugin elsewhere in the configuration file.

classname

Yes The class that implements the plugin.

top

<labelincrementer>

<cruisecontrol> <project> <labelincrementer>

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

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

Attributes

Attribute Required Description

defaultLabelNo (default to "build.1")

set label to use if there is no saved label.

preBuildIncrementer

No (defaults to false)

if true the build number will be incremented prior to the build attempt and thus each build attempt will have a unique build number.

separatorNo (defaults to period '.')

specifies the separator to use between label and build count.

top

<cvslabelincrementer>

<cruisecontrol> <project> <cvslabelincrementer>

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

top

<emptylabelincrementer>

<cruisecontrol> <project> <emptylabelincrementer>

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

top

<formattedlabelincrementer>

<cruisecontrol> <project> <formattedlabelincrementer>

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

Attributes

Attribute Required

Description

defaultLabel No Set label to use if there is no saved label. Default is CC_1_INT.

preBuildIncrementer No

If true the build number will be incremented prior to the build attempt and thus each build attempt will have a unique build number. Default is false.

Attribute Required

Description

prefix No Indications if a prefix is required (three part label) or not (two part label). Default is true.

separator No Specifies the separator to use between portions of the label. Default is underscore '_'

top

<p4changelistlabelincrementer>

<cruisecontrol> <project> <p4changelistlabelincrementer>

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

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

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

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

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

Attributes

Attribute

Required Description

changelist

No set the changelist number to sync to. Not specifying this value will sync to the most recently committed changelist.

port Yes Perforce Server connection to use (host:port)client Yes Perforce Client name to useuser Yes Perforce User name to usepasswd No Perforce password to useview Yes Valid Perforce view (i.e. a depot path)

separator

No (defaults to period '.')

specifies the separator to use between label and build count.

noSync No enable to turn off synchronizing the depot to the label

Attribute

Required Description

(defaults to false)

(changelist) number.

cleanNo (defaults to false)

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.

deleteNo (defaults to false)

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.

top

<propertyfilelabelincrementer>

<cruisecontrol> <project> <propertyfilelabelincrementer>

Returns a value for the label from a property file.

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

Attributes

Attribute Required

Description

defaultlabel No value to return if property file doesn't exist. if not specified and file doesn't exist an exception is thrown.

preBuildIncrementer No

If true the property will be re-read from the property file prior to the build attempt and thus each build attempt will have the latest value of the property

propertyfile Yes the property file to read.propertyname Yes the name of the property to read for the value of the label.top

<svnlabelincrementer>

<cruisecontrol> <project> <svnlabelincrementer>

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

Attributes

Attribute Required DescriptionworkingcopypNo (defaults Path to the SVN working copy

Attribute Required Descriptionath to .)

labelprefix No (defaults to svn)

Prefix for the label

separator No (defaults to .)

The separator to use between label and build count

top

<ftppublisher>

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

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

Attributes

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

Attribute Required Description

destDir Yes The remote directory (relative to targetDir) to publish the files.

srcDir YesTo publish the XML log file, this must be the same as the dir attribute of the <log> element. To publish the artifacts, this must be the same as the <artifactspublisher> directory.

deleteArtifacts

No (defaults to false)

If true, then all files successfully sent to the FTP server will be deleted locally.

top

Common FTP Attributes

The following attributes are common to the <ftppublisher>.

Attribute Required DescriptiontargetHost Yes Host name of the FTP server.

targetUser No (defaults to anonymous)

The user used for logging into the FTP site.

targetPasswd

No (default to eat@joes.com)

The password used during FTP log in for the targetUser.

targetPort No (defaults to 21) Port number of the FTP server.

targetDir No (defaults to '.')Base directory in the FTP server to put the files.

targetSeparator

No (defaults to '/'.Directory separator character used by the FTP server.

top

XPath Aware Child Attributes

The following attributes are common to the xpath aware children found in

<sfeetracker> and <sfeedocman>.

Attribute Required Description

valueOne of value or xpathExpression must be specified.

A fixed value that will not change at runtime.

xpathExpression

One of value or xpathExpression must be specified.

An xpath expression to evaluate against the CruiseControl log file, or the xml file as specified by xmlFile attribute. The result of the expression will be used as the value.

xmlFileNo (defaults to the CruiseControl build log).

Path to a file on the local filesystem against which the xpathExpression will be evaluated.

top

Named XPath Aware Child Attributes

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

Attribute

Required

Description

name Yes The name of a field in the tracker artifact.

top

Building Plugins That Need External Libraries

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

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

FAQ

Why don't my jUnit results show up on the web page?

Perhaps the JUnit results are not being captured correctly. Ensure that your <junit> ant task contains the proper formatting directive to instruct JUnit to output the results in XML format: <formatter type="xml"/>. If you are directing JUnit to send output to a subdirectory, make sure to tell CC about it - use the <merge> element in the <log> section of your config.xml.

What does "Too much repository activity" mean?

This means there is currently code being committed to the repository, and CC is afraid of doing a build that may potentially contain partial check-ins. CC will not kick off a build until it is sure that a developer is done committing code. CC uses the "quietperiod" setting to determine the amount of time it should wait after the last commit before doing a build. If you get this message in your CC log and not many builds are run, you may want to lower your "quietperiod" setting to a smaller time value.

The amount of time that CruiseControl waits is based on the (quietperiod - (now - checkin time)). If we are only 5 seconds away from the end of the quiet period, we'll just wait that long rather than waiting for the full

quiet period. Some issues may arise if the clocks are not synchronized between the CruiseControl machine and the CVS machine -- you might get large/odd sleep times if the CVS machine is ahead of the CruiseControl machine.

Why does my jsp page show the build and dates, but the right half of the page is blank no matter what I click on?

Your xml log file encoding is incorrect. CC puts the JVM system encoding at the top of every xml log file that it generates, and the xsl transformer on your system is not happy transforming that specific encoding. Use the "encoding" parameter of the "log" entry in the config.xml to override the xml encoding name. Try "UTF-8" or "ISO-8859-1".

===========================

Some of the verify and assert methods are: ‹ verifyElementPresent ‹ verifyElementNotPresent ‹ verifyText ‹ verifyAttribute ‹ verifyChecked ‹ verifyAlert ‹ verifyTitle