documentcc
TRANSCRIPT
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="[email protected]" 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="[email protected]"/> <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. [email protected]. log4j.appender.Mail.SMTPHost=yoursmtp.mailhost.comL. log4j.appender.Mail.Subject=CC has had an error!!!M. [email protected]. 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="[email protected]"/>22.23. <project name="project1">24. <!-- ${buildmanager} resolves to "[email protected]" -->25. </project>26.27. <project name="project2">28. <property name="buildmanager" value="[email protected]"/>29. <!-- ${buildmanager} resolves to "[email protected]" -->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="[email protected]"/>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="[email protected]">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="[email protected]">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:[email protected]:/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 '[email protected]'
password Yes Password of the sender account
recipient Yes Username of the recipient of the instant message. Recipient username is typically fully qualified: [email protected]
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 '[email protected]'
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 '[email protected]'
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 [email protected])
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