You are on page 1of 118

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

Build loop Install 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, cruisecontrollauncher.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/cruisecontrollauncher.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-fitsall" 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 4. 5. 7. 8.

o Plugin configuration o Plugin validation Execution Registration 6. o Preconfiguration Plugin XML Documentation 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 in the config file. In this case, implement an add or create method nested element is itself a plugin nested elements within your plugin's declaration CruiseControl will expect your plugin class to for each nested element, depending whether your 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 preconfigured child element might accumulate them. If you want to preconfigure an already registered plugin (whether default plugin, or plugin registered at the root of the config), you may leave out the classname attribute of the plugin element. An example: to define some default values for the htmlemail publisher, you can specify something like this in your config file: <plugin name="htmlemail" mailhost="smtp.example.com" returnaddress="buildmaster@example.com" subjectprefix="[CC]" xsldir="C:\java\cruisecontrol-2.2.1\report\jsp\webcontent\xsl" css="C:\java\cruisecontrol2.2.1\report\jsp\webcontent\css\cruisecontrol.css"> <always address="project-dev@domain.com"/> <plugin/> Combined with ant style properties this can greatly reduce the size of your config files. In the extreme case you can create a template project where all that needs to be supplied is the project name:

<cruisecontrol> <plugin name="project"> <bootstrappers> <cvsbootstrapper localworkingcopy="projects/${project.name}"/> </bootstrappers> ... </plugin> <project name="foo" /> <project name="bar" /> ... </cruisecontrol> More information and examples can be found on the wiki. Plugin XML Documentation The config reference is automatically generated from comments and tags contained in the plugins code. Here's a simple self-commented example: /** * This will make it into the plugin description. * <p>You can also have HTML code </p> * @cc-plugin * @see other javadoc tags are not taken into account. */ public class MyPlugin { /** The default value is automatically identified whenever possible */ private String myField = "defaultValue"; /** * A comment that will describe the entry in the parameter table for the plugin. * @required "the comment that will make it into the required column" * @defaultValue "forceDefaultValue" */ public void setMyField(String myField) { this.myField = myField; } /** * A comment that will describe the entry in the Child table for the plugin. * @cardinality 0..* */ public void addObject(Object object) { ... } } Build Results JSP Installation Guide Note that this is a brief guide to installation from the source code. For basic CruiseControl installation, go to the Getting Started page. Getting The Source If you have Subversion installed, you can get the entire CruiseControl source by running: svn checkout https://cruisecontrol.svn.sourceforge.net/svnroot/cruisecontrol/trunk/cruisecontro l

Once you have obtained the source, you should have a reporting/jsp directory that contains the following: src - The source for the JSP custom tags test - JUnit Tests for the JSP custom tags docs - This manual dist - Output directory for the cruisecontrol.war distributable images - Images used by the buildresults.jsp lib - 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. ccname Name for this CruiseControl instance The binaryrelease sets this to the -ccname value given as a commandline argument cruisecontrol.jmxport port 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.jmxhost host where the CruiseControl JMX agent's HTTP adaptor is listening If not specified CruiseControl will trying to guess the host name running the reporting application cruisecontrol.rmiport port 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 cacheRoot Full 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 logDir The binaryrelease does not specify this parameter logDir This 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 currentBuildStatusFile This 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.welcomeFiles The 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.jmxhost The 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.jmxport The 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 rootDir The absolute path to the directory where additional build artifacts are stored. If this is not specified the logDir context parameter will be used The 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.threshold PMD 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.url The URL of the ViewCVS website used by cvstagdiff.xsl, checkstyledetails.xsl and pmd-details.xsl This is not specified by default cvstagdiff.success.show Controls whether the ViewCVS differences report should be shown when the build was successful. The default is to only show the modifications report for broken builds true checkstyle.hide.warnings Controls 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 class net.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 Building the code A. 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: export ANT_HOME=~/devtools/apache-ant-1.6.5 export ANT_ARGS="-lib ~/devtools/cruisecontrol/main/lib/junit3.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)

C. D.

dist/ extensions)

(New directory created by builing distributed (*Build Agent) (DistributedMasterBuilder class, used by (*Lookup Service - aka: Registrar) (*General utilites, including Agent

agent/... builder/... master build loop). core/... lookup/... util/... Utility) 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.

E.

(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. (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. 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. 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.DistributedMasterBui lder"/>

F.

G.

H.

I.

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 Description A semicolon-delimited list (key1=value1;key2=value2) used to find a entries No matching agent on which to perform this build. Build artifacts directory on remote Agent. All content of this directory is returned to agentlogdir No the Master, and deleted after the build completes. Build artifacts directory on Master into masterlogdir No which Agent artifacts will be moved. Typically included in log merge Another artifacts directory on the remote Agent. All content of this directory is agentoutputdir No returned to the Master, and deleted after the build completes. Another artifacts directory on Master into masteroutputdir No which Agent artifacts will be moved. Typically included in log merge 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 No false, no progress messages will be shown by showProgress (defaults the distributed builder or nested builder to true) 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 <builder> Cardinality 1 Description The nested <builder> to be executed on the remote Build Agent. See <composite> to execute multiple Builders. 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 merge Example: <remoteResult agentDir="target/site" masterDir="target/site"/> Attribute Required

<remoteResult> 0 .. *

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-controlagent/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. 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 userdefined.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">

6.

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

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

9.

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

J.

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. 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. Test that Jini is running and your agent(s) is/are registered using the JiniLookUpUtility. In contrib/distributed/dist/util run ant testjini. 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 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.) 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

K.

L.

M.

N.

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. Advanced configuration O. 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 userdefined.properties and agent.properties are copied into the ccagent.zip you'll need to unzip and make your changes locally on the agent.

P.

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

2.

3.

Q.

R. S. T. U. V. W. X. Y. Z. AA. BB. CC.

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: log4j.rootCategory=INFO,A1,FILE,Mail ... # Mail is set to be a SMTPAppender log4j.appender.Mail=org.apache.log4j.net.SMTPAppender log4j.appender.Mail.BufferSize=100 log4j.appender.Mail.From=ccbuild@yourdomain.com log4j.appender.Mail.SMTPHost=yoursmtp.mailhost.com log4j.appender.Mail.Subject=CC has had an error!!! log4j.appender.Mail.To=youremail@yourdomain.com log4j.appender.Mail.layout=org.apache.log4j.PatternLayout log4j.appender.Mail.layout.ConversionPattern=%d{dd.MM.yyyy HH:mm:ss} %-5p [%x] [%c{3}] %m%n CruiseControl manages its own thread count for simultaneous builds. While this makes sense when the build master is the only machine

DD.

EE. FF. GG. HH.

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: <system> <configuration> <threads count="5" /> </configuration> </system> where 5 would be replaced with your expected number of build agents.

II.

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

JJ.

KK.

LL.

MM.

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: <distributed entries="sound=hardwaremixable"> ... </distributed>

NN. OO.

Deploy and launch all your agents, without modifying entries in userdefined.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-xmllibs" patternset in CCDist build.xml). Todo for this implementation

A. A default cruise.build.dir could be used on the agent, removing the

B.

C. D.

E. F.

G.

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. 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. More secure default Jini policy files. 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. 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...) 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 "nonbusy") 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 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 <system> <project> <plugin> <property> <include.projects> <dashboard> 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. Cardinality 0 .. 1 1 0 0 0 0 .. .. .. .. .. * * * * 1 Description 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. Defines a basic unit of work. Registers a classname with an alias. Defines a name/value pair used in configuration. Add projects defined in other configuration files. Configure dashboard related settings.

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 count 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 name Required Description The name of the property to set. 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". The filename of the property file to load. Yes Description Maximum number of threads to be in use simultaneously to build projects

Exactly one of name, environment environment, or file. file

Attribute value toupper

Required Description Yes, if name was The value of the property. This may contain any set. previously defined properties. Used in conjunction with environment. If set to true, No all environment variable names will be converted to upper case.

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

7. Set a collection of global properties from the properties file "config.properties": 8. <cruisecontrol> 9. <property file="config.properties"/> 10. ... 11. <cruisecontrol>

12.

Load the system's environment into a collection of global properties. Uppercase all environment variable names: 13. <cruisecontrol> 14. <property environment="env" toupper="true"/> 15. <property name="logdir" value="${env.CCDIR}/logs"/> 16. ... 17. <cruisecontrol>

18.

Define a global property called "buildmanager". Override it's value only within the scope of the project called "project2". 19. <cruisecontrol> 20. 21. <property name="buildmanager" value="buildmgr@here.com"/> 22. 23. <project name="project1"> 24. <!-- ${buildmanager} resolves to "buildmgr@here.com" --> 25. </project> 26. 27. <project name="project2"> 28. <property name="buildmanager" value="someoneelse@here.com"/> 29. <!-- ${buildmanager} resolves to "someoneelse@here.com" --> 30. </project> 31. 32. <cruisecontrol>

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


extremely powerful combination. 34. <cruisecontrol> 35. 36. <!-- Load environment variables --> 37. <property environment="env" toupper="true"/> 38. 39. <!-- Commonly used directories --> 40. <property name="reportdir" value="${env.CCDIR}/report"/>

41.

<property name="projectdir" value="${env.CCDIR}/checkout/$ {project.name}"/> 42. <property name="testdir" value="${projectdir}/build/junit-reports"/> 43. <property name="logdir" value="${env.CCDIR}/logs/${project.name}"/> 44. 45. <!-- Defaults for email --> 46. <property name="buildmaster.email" value="buildmaster@example.com"/> 47. <property name="buildmaster.name" value="Buildmaster"/> 48. 49. <!-- Preconfigure our plugins --> 50. <plugin name="log" 51. dir="${logdir}"/> 52. 53. <plugin name="currentbuildstatuslistener" 54. file="${logdir}/buildstatus.html"/> 55. 56. <plugin name="cvs" 57. localworkingcopy="${projectdir}"/> 58. 59. <plugin name="ant" 60. antscript="${env.ANT_HOME}/bin/ant" 61. antWorkingDir="${projectdir}" 62. target="cruise"/> 63. 64. <plugin name="htmlemail" 65. buildresultsurl="http://servername/cruisecontrol/buildresults/ ${project.name}" 66. mailhost="smtp.example.com" 67. returnaddress="${buildmaster.email}" 68. returnname="${buildmaster.name}" 69. subjectprefix="[BUILD ${project.name}]" 70. xsldir="${reportdir}/jsp/webcontent/xsl" 71. css="${reportdir}/jsp/webcontent/css/cruisecontrol.css"/> 72. 73. <project name="project1"/> 74. <listeners> 75. <currentbuildstatuslistener/> 76. </listeners> 77. <log> 78. <merge dir="${testdir}"> 79. </log> 80. <modificationset> 81. <cvs/> 82. </modificationset> 83. <schedule> 84. <ant/> 85. </schedule> 86. <publishers> 87. <htmlemail> 88. <always address="${buildmaster.email}"> 89. <failure address="proj1dev@example.com"> 90. <ignore address="buildmaster"> 91. </htmlemail> 92. </publishers> 93. </project> 94. 95. <project name="project2"/> 96. <listeners> 97. <currentbuildstatuslistener/> 98. </listeners> 99. <log> 100. <merge dir="${testdir}"> 101. </log> 102. <modificationset>

103. <cvs/> 104. </modificationset> 105. <schedule> 106. <ant/> 107. </schedule> 108. <publishers> 109. <htmlemail> 110. <always address="${buildmaster.email}"> 111. <failure address="proj2dev@example.com"> 112. </htmlemail> 113. </publishers> 114. </project> 115. 116. </cruisecontrol> top <include.projects> <cruisecontrol> <include.projects> The <include.projects> tag is used to consolidate several configuration files into a single configuration. One advantage over using XML includes are that the target files are valid configuration files in their own right and not just XML fragments. Also, including projects using the tag is less fragile as an error in one file will not keep the rest of the projects for building. Configuration files included this way are processed with the properties and plugins defined in the main configuration file, which easily allows per instance configuration. Properties and plugins defined in the processed files are not made available outside the scope of that file. Project names must still remain unique. The first project with a given name will be loaded and any subsequent projects attempting to use the same name will be skipped. Changes to any of the included file with be detected and cause the configuration to be reload, just as if they had been made to the parent file. Attributes Attribute Required file 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 Yes Description Relative path from current configuration file to the configuration file to process.

Attribute url

Required No

postinterval No top <project> <cruisecontrol> <project>

Description Home page address of your dashboard. The default value is http://localhost:8080/dashboard. The interval [in seconds] that build loop post builds information to the dashboard. The default value is 5 seconds.

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 name Required Yes No (defaults to true) Description Unique identifier for this project 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). 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. 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). 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.

buildafterfailed

No forceBuildNewProject (defaults to true) No requireModification (defaults to true) No (defaults to false)

forceOnly

Child Elements Element <listeners> <bootstrappers> <modificationset> <schedule> <log> <publishers> <plugin> top <listeners> Cardinality Description 0 .. 1 Container element for Listener plugin instances. 0 .. 1 Container element for Bootstrapper plugin instances. 1 Container element for SourceControl plugin instances. Specifies the SourceControl poll interval, and is a 1 parent element for Builder plugin instances. 0 .. 1 Specifies where project log files are stored. 0 .. 1 Container element for Publisher plugin instances. 0 .. * Registers a classname with an alias.

<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 Writes a build status snippet to the filesystem and to an FTP server Writes a build status snippet to the filesystem Writes build status to the filesystem using by replacing values in a template Monitors and starts CM Synergy sessions as needed Responsible for deleting the lock file when a project goes IDLE

<currentbuildstatusftplistener> 0 .. * <currentbuildstatuslistener> 0 .. *

<currentbuildstatuspagelistener> 0 .. * <cmsynergysessionmonitor> <lockfilelistener> top <cmsynergysessionmonitor> <cruisecontrol> <project> <listeners> <cmsynergysessionmonitor> 0 .. * 0 .. *

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 Value CCM_ENGLOG ${path to build Synergy users ccm_eng.log} CCM_UILOG ${path to build Synergy users ccm_ui.log}

Attributes Attribute Required ccmexe No Description The name of the CM Synergy command line client. If not provided, the plugin will search the system path for an executable called "ccm" (or "ccm.exe" for Windows). The session file used to persist the CM Synergy session information. If not provided, it defaults to a file called ".ccmsessionmap" located in your home directory.

sessionfile No

Child Elements Element Cardinality Description 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. 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 name <session> 1 .. * attributefile No database user password role host Yes Yes Yes Yes No Required Yes Description The name of the CM Synergy session. This value will be used in the "sessionname" attributes of the other CM Synergy plugins. The properties file which will be read to set the remainder of the session's attributes. The CM Synergy database with which this session will communicate (e.g. /ccmdb/mydb). The CM Synergy user account under which the session will run. The password for the specified user. The role under which the CM Synergy session will run (e.g. build_mgr). 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 No

If 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/product2 user=buildmgr role=build_mgr password=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 Any defined publisher 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> Cardinality 1 .. * Description You may use any defined publisher as a child element.

<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 Description file Yes The filename to write, including path top <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 Description file Yes The filename to write, including path sourceFile No The file with the template to use for subtitution top <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 Description filename Yes The filename to write, including path destdir 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 lockfile Yes Description The name (and path) of the file to serve as the lock between multiple projects. Lockfile only deleted when contents match the value set for project name.

projectname Yes 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 <accurevbootstrapper> <alienbrainbootstrapper> <antbootstrapper> <clearcasebootstrapper> <clearcaseviewstrapper> <cmsynergybootstrapper> Cardinality 0 .. * 0 .. * 0 .. * 0 .. * 0 .. * 0 .. * Description Updates the resources of an Accurev workspace Bootstraps resources from AlienBrain Executes an Ant script which implements a custom bootstrapper Bootstraps resources from ClearCase Bootstraps View and VOB resources from ClearCase Bootstraps resources from CM Synergy Creates a Synergy baseline prior to build Bootstraps resources from CVS Bootstraps resources from Darcs Execute a command for bootstrapping Bootstraps resources from git Bootstraps resources from AllFusion

<cmsynergybaselinebootstrapper> 0 .. * <cvsbootstrapper> <darcsbootstrapper> <execbootstrapper> <gitbootstrapper> <harvestbootstrapper> 0 0 0 0 0 .. .. .. .. .. * * * * *

Element <lockfilebootstrapper> <mercurialbootstrapper> <p4bootstrapper> <plasticscmbootstrapper> <snapshotcmbootstrapper> <starteambootstrapper> <surroundbootstrapper> <svnbootstrapper> <tfsbootstrapper> <vssbootstrapper> top <accurevbootstrapper> <cruisecontrol> <project> <bootstrappers> <accurevbootstrapper>

Cardinality 0 .. * 0 0 0 0 0 0 0 .. .. .. .. .. .. .. * * * * * * *

0 .. * 0 .. *

Description Harvest Creates the lock file if it doesn't already exist Bootstraps resources from Mercurial Bootstraps resources from Perforce Bootstraps resources from Plastic SCM Bootstraps resources from SnapshotCM Bootstraps resources from Star Team Bootstraps resources from Surround SCM Bootstraps resources from Subversion Bootstraps resources from Microsoft Visual Studio Team Foundation Server Bootstraps resources from Visual Source Safe

Automatically updates an accurev workspace. The selected workspace must already exist on the local filesystem. Attributes Attribute keep synctime verbose Required No (defaults to "false") No (defaults to "false") Description If true, the plugin runs "accurev keep -m" before trying to update the workspace, to keep all modified elements. If true, the plugin runs "accurev synctime" before trying to update the workspace, to synchronize the local clock with the Accurev server's.

No (defaults to Enables detailed logging. "false") No (defaults to The local path containing the working copy of the workspace the current dir) desired workspace. Examples

1. Updates the workspace locally stored on D:\accurev\workspace_user\MyProject,


2. 3. 4. 5. 6. 7. top <alienbrainbootstrapper> <cruisecontrol> <project> <bootstrappers> after synchronizing the local clock with the autokeeping all the modified files. <bootstrappers> <accurevbootstrapper workspace="D:\accurev\workspace_user\MyProject" synctime="true" keep="true" verbose="true"/> <bootstrappers>

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

Attributes Description The name of the machine hosting the AlienBrain server No repository. If specified, it will override the value in the NXN_AB_SERVER environment variable. The name of the project in the AlienBrain repository. database No If specified, it will override the value in the NXN_AB_DATABASE environment variable. The AlienBrain user account name to use when querying user No for modifications. If specified, it will override the value in the NXN_AB_USERNAME environment variable. The password of the AlienBrain user account to use when querying for modifications. If specified, it will password No override the value in the NXN_AB_PASSWORD environment variable. The path to the item that will be retrieved from AlienBrain. Typically a path like 'alienbrain://Project/SubProject/build.xml' If the path path Yes is a file, that file will be retrieved. If the path is a directory, the directory will be retrieved recursively. The branch of the project from which to retrieve the branch No path. If set to true, the local file is always updated with No the file on the server. This is not the same as forcefileupdate (defaults overwritewritable="replace". It means that the file to false) will be retrieved even if it has not been modified in the repository. Must be either 'skip' or 'replace'. 'ask' is not an option as no one is around to answer the question. No skip: overwritewritable (defaults do not touch the file to 'skip') replace: replace the file with the version on the server If localpath is specified the item is copied to the localpath No 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 Attribute Required

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 MyProjectnightlybuild.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 Description file Yes The filename to write viewPath No local path to the file top <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 viewpath Yes Description 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. A comma separated list of VOBs to mount, i.e. "\VOB1,\VOB2" (Windows) or "/vobs/VOB1,/vobs/VOB2" (Linux/Unix).

voblist Examples

No

top

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>

<cmsynergybootstrapper> <cruisecontrol> <project> <bootstrappers> <cmsynergybootstrapper> Used to reconfigure a CM Synergy project or project hierarchy Attributes Attribute Required ccmexe No Description The name of the CM Synergy command line client. If not provided, the plugin will search the system path for an executable called "ccm" (or "ccm.exe" for Windows). 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. 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. The project spec (two part name) of the project you wish to reconfigure. If set to true, all subprojects will also be reconfigured. Defaults to true

sessionfile No

sessionname No project recurse Examples Yes No

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 ccmexe Required No Description The name of the CM Synergy command line client. If not provided, the plugin will search the system path for an executable called "ccm" (or "ccm.exe" for Windows). 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. 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. An optional name for the baseline. If not provided, CM Synergy will assign a default name based upon the current date. The project spec (two part name) of the project you wish to reconfigure. An optional description of the baseline Value to specify for the build attribute of the baseline Value to specify for the purpose of the baseline Value to specify for the state of the baseline. Valid values are: "published_baseline","test_baseline" or "released". Default state is "published_baseline"

sessionfile No

sessionname No

baselinename No project Yes

description No build No purpose No state No

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

localWorkingCopy No

cvsroot

No

file

No

overwriteChanges No resetStickyTags No

compression

No

Description 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. The CVSROOT. Not required if the current working directory is in the cvs project or if the localWorkingCopy attribute is set. 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. If set to true the update command will include the -C option which will overwrite local changes. If set to true the update command will include the -A option which will reset any sticky tags, dates, or -k options. 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 darcsBinary workingdir Required no (default "darcs") Description Name or location of the darcs binary

Relative or absolute path to the At least one of workingdir. Directory must exist. workingdir or repository location Specifies the location of the Darcs repositorylocation repository to pull into. Specifies the location of the remote Darcs repository to pull from. remoteRepositoryLocation no 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 the relative or absolute path to the local working copy of the git repository on which to execute the update command.

localWorkingCopy Yes 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 username password broker project state Required Description Yes Usename to use in connecting to the Harvest Broker. Yes Password to use in connecting to the Harvest Broker. Yes The name of the Harvest Broker to connect to. The name of the project containing the file you wish to Yes bootstrap. Can be different from the cruisecontrol project name. The name of the state containing the file you wish to Yes bootstrap.

Attribute Required Description viewpath Yes The Harvest view path of the file you wish to bootstrap. The Harvest client path to use when checking out the bootstrap clientpath Yes file. process Yes The name of the Harvest checkout process to use. file Yes The name of the file to be bootstrapped. The item filter to use. One of: baseline, modified, both. item No Default is both. The version filter to use. One of: latest_in_view, all_in_view, version No all, latest. Default is latest_in_view. The status option to use. One of: all, no_tag, reserved, status No merged, removed, any. Default is all. The branch option to use. One of: trunk, branch, branch No 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 lockfile Yes Description The name (and path) of the file to serve as the lock between multiple projects. The project name is written to the lockfile so that the LockFileListener knows which to delete.

projectname Yes top

<mercurialbootstrapper> <cruisecontrol> <project> <bootstrappers> <mercurialbootstrapper> Handles updating from a Mercurial repository before the build begins. Attributes Attribute Required Description the relative or absolute path to the local working copy of the Mercurial repository on which to execute the update command.

localWorkingCopy Yes top <p4bootstrapper> <cruisecontrol>

<project> <bootstrappers> <p4bootstrapper> Syncs leave makes after a single path from Perforce before the build begins. Useful if you want to all SCM up to CruiseControl. Allowing the bootstrapper to update the project for a simpler build.xml but allows a window where a file can be committed 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 Description view Yes Valid Perforce path (a.k.a. 'view') port No Perforce Server connection to use (host:port) user No Perforce User name to use passwd No Perforce password to use client No Perforce Client name to use top <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 wkspath branch repository Required Yes No No Description Valid Plastic SCM workspace path. The branch from which to get the source. If none has been specified, it updates the workspace according to its configuration. The repository from which to get the source. If none has been specified, it updates the workspace according to its configuration. A path under the workspace path which will be updated. If none is specied, it updates all the workspace. Do the update with the "--forced" option

pathtoupdate No forced Examples No (defaults to "false")

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 file 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 files folder localfolder password port project server username view top Required Description Yes Space separated list of files to retrieve Yes The repository folder No Path to the folder on the local file system Yes Yes Port StarTeam server is using Yes StarTeam project Yes Hostname for StarTeam server Yes Yes StarTeam view Yes Description Name of the file or directory to fetch from the SnapshotCM repository. Updates from SnapshotCM repository will be recursive and forced (over-writing any local changes).

<surroundbootstrapper> <cruisecontrol> <project> <bootstrappers> <surroundbootstrapper> Fetches a single repository (and optionally it's sub-repositories) from Surround SCM before starting the build. Attributes

Attribute branch repository label

Required No No No

includeremovedfiles No overwrite recursive forcefetch makewritable serverconnect No No No No No

serverlogin top <svnbootstrapper>

No

Description Surround SCM branch name. The default is pulled from the local working directory. Surround SCM repository path. The default is pulled from the local working directory. Enter a label to search for when getting files. Include 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). Enter how to handle a local writable file. Options are 1 to overwrite or 0 (default) to skip. Recursively get files and sub-repositories. Options are 1 or 0 (default). Force file retrieval from server regardless of the local copy status. Options are 1 or 0 (default). Make local file editable or writable. Default is readonly. Options are 1 or 0 (default). 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. 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.

<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 the relative or absolute path to the local working copy of the Subversion repository on which to execute the update command. file to update from the Subversion repository. used for authentication. used for authentication. Instructs Subversion to read configuration information from the specified directory instead of the default location (.subversion in the user's home directory).

localWorkingCopy One of these file username No password No configDir top <tfsbootstrapper> No

<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 crossplatform 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 itemSpec Yes username no Description 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/enus/library/56f7w6be(VS.80).aspx#sectionToggle3 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.

Attribute Required

Description 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. The password to use with the username when authenticating with password no the server. Specify the full path to the tf command being used. If not No supplied then the plug-in will try to locate a command called tfPath (defaults "tf" in the cruise control system path. By default, the to "tf") Microsoft client is installed into C:\Program Files\Microsoft Visual Studio 8\Common7\IDE\TF.exe no recursive (defaults Flag to indicate if a recursive get should be performed. 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 no TFS workspace. It will also not overwrite locally writable force (defaults files. Setting the force option will make TFS always download to false) 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. An optional string that may be passed as part of the command options no 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 vsspath Required Yes Description 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 Fully qualified path for the destination directory. Example: c:\directory\subdirectory\ VSS login information in the form username,password Path to the directory containing ss.exe. By default, ss.exe is assumed to be in the path. Note: should not contain whitespace. Path to the directory containing srcsafe.ini.

localdirectory Yes login ssdir serverpath No No No

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 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. 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. 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.xml This is useful if you want to update and commit files during your CC build.

No requiremodification (defaults to true)

quietperiod

No (defaults to 60)

ignoreFiles

No

Child Elements Element Cardinality Description <accurev> 0 .. * Checks for changes in an AccuRev stream. <alienbrain> 0 .. * Checks for changes in an AlienBrain repository. Always returns a single modification so the build will be <alwaysbuild> 0 .. * 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. Checks for changes from a list of trigger source <compound> 0 .. * controls, and if modification are detected, returns changes from a list of target source controls. <cvs> 0 .. * Checks for changes in a CVS repository.

Element Cardinality Description <darcs> 0 .. * Checks for changes in a Darcs repository. <filesystem> 0 .. * Checks for changes in a file system. Never returns any changes. Deprecated: use forceonly <forceonly> 0 .. * 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. <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. Checks for changes in a Cincom Smalltalk VisualWorks <store> 0 .. * Store repository. <surround> 0 .. * Checks for changes in a Surround SCM repository. <svn> 0 .. * Checks for changes in a Subversion repository. Checks for changes in a Microsoft Visual Studio Team <tfs> 0 .. * Foundation Server repository. <timebuild> 0 .. * Triggers a build after a particular time threshold. Checks for changes in another project and will veto a <veto> 0 .. * build if changes are found. <vss> 0 .. * Checks for changes in a Visual SourceSafe repository. Checks for changes in a Visual SourceSafe, Journal File <vssjournal> 0 .. * Implementation. top <accurev> <cruisecontrol> <project> <modificationset> <accurev> Checks for modifications in an AccuRev stream. Attributes Attribute stream verbose Yes Required Description The name of the AccuRev stream where the plugin looks for Modification(s).

No (defaults to Set to "true" to enable a more verbose logging style. "false") Will set this property if a modification has occurred. property No 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 server No Description The name of the machine hosting the AlienBrain repository. If specified, it will override the value in the NXN_AB_SERVER environment variable. The name of the project in the AlienBrain repository. If specified, it will override the value in the NXN_AB_DATABASE environment variable. The AlienBrain user account name to use when querying for modifications. If specified, it will override the value in the NXN_AB_USERNAME environment variable. 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. The path to the item that will be queried for modifications Typically a path like 'alienbrain://Project/SubProject' The branch of the project to check for modifications. Will set this property if a modification has occurred. For use in conditionally controlling the build later.

database No user No

password No path branch top <alwaysbuild> Yes No

property No

<cruisecontrol> <project> <modificationset> <alwaysbuild> Used to always trigger a build by returning a single modification. Attributes Required Description No (defaults to The username to use for the single reported (fake) username "User") Modification. Set this property if a modification has occurred. For use property No 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

Attribute logdir property

Required Yes No

vetoIfFailing No

Description Path to CruiseControl log directory for the project to monitor. Will set this property if a modification has occurred. For use in conditionally controlling the build later. 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 most.recent.logdir Description The location being checked for new log files The name of the newest logfile included in the modification most.recent.logfile set The timestamp of the newest build included in the modification most.recent.logtime set, using the format yyyyMMddHHmmss most.recent.loglabel The label of the newest build included in the modification set top <clearcase> <cruisecontrol> <project> <modificationset> <clearcase> Triggers a build if there is a change within a ClearCase repository. Attributes Attribute Required branch Yes No recursive (defaults to true) Description The ClearCase branch Whether to check sub-folders in the viewpath. 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. Local working copy to use when making queries Will set this property if a modification has occurred. For use in conditionally controlling the build later.

all

No (defaults to false)

viewpath Yes property No

Properties Passed to the Builders

In addition to the standard CruiseControl properties passed to builders, <clearcase> sets the following properties: Description Timestamp representing the last built time, using the format ddclearcaselastbuild MMMM-yyyy.HH:mm:ss Timestamp representing the time the current build started, using clearcasenow 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 ccmexe Required No Description The name of the CM Synergy command line client. If not provided, the plugin will search the system path for an executable called "ccm" (or "ccm.exe" for Windows). 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. 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. The project spec (two part name) of the CM Synergy project in which you wish to search for changes. 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. 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. 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 Property Name

sessionfile

No

sessionname project

No Yes

instance

No

ccmdateformat updatefolders

No No

Attribute

Required

reconfigure

No

recurse

No

usebindtime

No

ignoreworkarea

No

changesynergyurl No

ccmdb language country

No No No

property

No

Description Wiki site for more information. 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. Used in conjunction with the reconfigure option. If set to true (which is the default) all subprojects will also be reconfigured. If set to true, the time a task came into the reconfigure folder is used to determine modified tasks instead of the tasks completion date. This is a more precise query to find modifications since the last build when the reconfiguration rules are based on other criteria e.g. the status of a Change Synergy change request. 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). 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. 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. Used in conjunction with changesynergyurl. This should be set to the location of the database on the CM Synergy server. (e.g. "/ccmdb/mydb") If you have a non U.S. English installation of CM Synergy, you may specify the ISO language code here. (e.g. fr, de, etc.) If you have a non U.S. English installation of CM Synergy, you may specify the ISO country code here. (e.g. FR, DE, etc.) 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 cc.ccm.session cc.ccm.dateformat cc.ccm.project cc.ccm.workarea cc.ccm.haschanged (or the value specified by the property Description The CM Synergy session ID used to check for modifications. The date format used to convert CM Synergy dates into Java dates. The two part name of the project (as provided in the project attribute). The file system location of the CM Synergy work area for the project (unless the ignoreworkarea attribute was set). Set to true if any CM Synergy objects have changed since the last build.

Property Name attribute) Examples

Description

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 includeTriggerChanges No Description Add the trigger modifications to the list of

Attribute

Required (defaults to false)

property

No

Description 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. Set this property if a modification has occurred. For use in conditionally controlling the build later.

Child Elements Element Cardinality Description 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>. 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>.

<triggers> 1

<targets> 1

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 Relative or absolute path to the local working localworkingcopy copy. Directory must exist and should have files from a previous checkout. Either Specifies the location of the CVS repository. Th cvsroot localworkingcopy should be of the form or both cvsroot :pserver:username@cvs.example.com:/cvsroot/repon and module. The name of the CVS module that should be used. This is passed as the last parameter to the cvs module rlog command. Refer to the rlog command in the c log reference for further details. Specify the cvs tag. The value of this attribute passed directly to cvs log using the -r option. Numeric revision numbers, tags, branch tags, or No (defaults to tag ranges of revisions are valid (when a non branch HEAD) tag is used, a single modification per file will listed). Refer to the -r option in the cvs log reference for further details. Set this property if a modification has occurred property No For use in conditionally controlling the build later. Set this property if a file has been deleted. Fo propertyondelete No use in conditionally controlling the build later Sets whether to use "-Q", instead of the default q" for the cvs log command. Setting this attribu reallyQuiet No to true can help to reduce CruiseControl log fil size, especially when using branches. Defaults t false. Sets the behavior when a local working coppy is which is not under control of CVS itself (that i does not have a CVS subdirectory). If set to tru recurseLocalWorkingCopy No all subdirectories are searched recursively. All subdirectories which are under control of CVS ar 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 parame is NOT included. Valid levels are 1 (high speed,

Attribute

skipEmailsFetching top <darcs> <cruisecontrol> <project> <modificationset> <darcs>

Description low compression) to 9 (low speed, high compression), or 0 to disable compression. No (defaults to If set to true, fetching of CVSROOT/users is false) skipped.

Required

Triggers a build if there is a change within a Darcs repository. Attributes Description Relative or absolute path to the workingdir Either workingdir or workingdir. Directory must exist. repository location. Specifies the location of the Darcs repositorylocation repository. Set this property if a modification has property No occurred. For use in conditionally controlling the build later. Set this property if a file has been propertyondelete No 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 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 at timestamp, not for actual changes to the file. If includedirectories is detects changes to directory timestamps, and will show modification if any were deleted Attributes Attribute folder Yes Required Description Root folder of the directories to scan, or path to file to check for modifications. Include modified directories. Defaults to false. Set this property if a modification has occurred. For use in conditionally controlling the build later. The username to use for the reported Modifications. the looks set it files Attribute Required

includedirectories No property username top <forceonly> No No (defaults to "User")

<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 property No top <git> <cruisecontrol> <project> <modificationset> <git> Checks for changes within a git repository. Attributes Attribute Requir ed Description Relative or absolute path to the local working copy of the git repository of which to find the log history. Set this property if a modification has occurred. For use in conditionally controlling the build later. Set this property if a file has been deleted. For use in conditionally controlling the build later. Description Set this property if a modification has occurred. For use in conditionally controlling the build later.

LocalWorkingC Yes opy property No

propertyondel No ete

Properties Passed to the Builders In addition to the standard CruiseControl properties passed to builders, <git> sets the following properties: Property Name gitcommitid top <harvest> <cruisecontrol> <project> <modificationset> <harvest> Description The commit id of the latest commit

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 username password broker state prevstate viewpath project item version status branch mode property Requir ed Yes Yes Yes Yes No No Yes No No No No No No Description The username to connect as. The password to connect with. The name of the Harvest broker to connect to. The state in which you want to search for changes. The state in which you want to search for demotion changes. Only used if mode is set to package. The Harvest view path within which to limit the search. The name of the project in AllFusion Harvest that you want to watch. Note that this can be different than the CruiseControl project name. The item filter to use. One of: baseline, modified, both. Default is both. The version filter to use. One of: latest_in_view, all_in_view, all, latest. Default is latest_in_view. The status option to use. One of: all, no_tag, reserved, merged, removed, any. Default is all. The branch option to use. One of: trunk, branch, trunk_and_branch, unmerged. Default is trunk. 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. Set this property if a modification has occurred. For use in conditionally controlling the build later. Set this property if a file has been deleted. For use in conditionally controlling the build later.

propertyond No elete 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 Attribu Required te url Yes usernam No (defaults e to "User") propert No y top Description The HTTP URL of a file to check the modification date of The username to use for the reported Modification. Set this property if a modification has occurred. For use in conditionally controlling the build later.

<mavensnapshotdependency> <cruisecontrol> <project> <modificationset> <mavensnapshotdependency> Triggers a build if a Maven snapshot detects a change. Attributes Attribute projectFil e user localRepos itory properties File property top <maven2snapshotdependency> <cruisecontrol> <project> <modificationset> <maven2snapshotdependency> Triggers a build if a Maven2 snapshot detects a change. Attributes Attribute Required pomfile Yes user Yes No (Not available localRepos until after maven itory v2.0.4+) property top <mks> No Description maven2 POM file. The username to use when reporting modifications. Local Maven2 JAR repository. Defaults to {user.home}/.m2/repository. Set this property if a modification has occurred. For use in conditionally controlling the build later. Requir ed Yes Yes No No No Maven POM file. The username to use when reporting modifications. Local Maven JAR repository. Defaults to {user.home}/.maven/repository. Sets the .properties file which contains overriding tags for POM. Default is build.properties. Set this property if a modification has occurred. For use in conditionally controlling the build later. Description

<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 doNothing Requir ed No Description If this attribute is set to true, no mks command is executed. This is for testing purposes, if a potentially slow MKS server connection should avoid Local directory for the sandbox. The name of the MKS project file (mostly project.pj). Set this property if a modification has occurred. For use in conditionally controlling the build later.

localworkin Yes gdir project Yes property top <mercurial> No

<cruisecontrol> <project> <modificationset> <mercurial> Triggers a build if there is a change within an Mercurial repository. Attributes Attribute Requir ed Description Local directory for the sandbox. The hg command used to check changes. Either 'incoming' or 'log'. Default is 'incoming'

localWorkingC Yes opy hgcommand No

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

Property Name hgrevision top <p4>

Description The latest revision number

<cruisecontrol> <project> <modificationset> <p4> Triggers a build if there is a change within an Perforce repository. Attributes Attribute Requir ed Description Should CruiseControl correct for time differences between the Perforce server and the CruiseControl server? Defaults to true. Perforce Server connection to use (host:port) Perforce Client name to use Perforce User name to use Perforce password to use Valid Perforce view (i.e. a depot path) Set this property if a modification has occurred. For use in conditionally controlling the build later. Should the Email address for the users be retrieved from Perforce if possible. Defaults to true.

correctForServe No rTime port client user passwd view property usep4email top <plasticscm> <cruisecontrol> <project> <modificationset> <plasticscm> Yes Yes Yes No Yes No No

Checks for changes in a Plastic SCM repository. Attributes Attribu Requir Description te ed wkspath Yes Valid Plastic SCM workspace path. The branch in which changes will branch Yes be looked for. reposit The repository in which changes No ory 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 archivefilesuf no fix loginid no Required Description Standard suffix for archive set when the repository is created. Default value is "-arc". Used to supply a user and password. Example: loginid="sampleuser:samplepassword" or loginid="sampleuser" Project name. Subproject name. Path to directory with pcli. The version label for the PVCS builder to check against. Example: pvcsVersionLabel="SampleVersionLabel" The promotion group for the PVCS builder to check against. Example: pvcspromotiongroup="SampleGroup" The format to use to parse the LastModified entry as produced by your pvcs system The format used to format the lastbuild date for pvcs commands. Set this property if a modification has occurred. For use in conditionally controlling the build later.

pvcsproject Yes pvcssubproject Yes pvcsbin No pvcsversionlab No el pvcspromotiong No roup No (defaults to outdateformat "MMM dd yyyy HH:mm:ss") No (defaults to indateformat "MM/dd/yyyy hh:mm:ss aa") property top <snapshotcm> <cruisecontrol> <project> <modificationset> <snapshotcm> No

Checks for changes in a SnapshotCM repository. Attributes Attribute Requir ed Description A semi-colon-separated list of source paths to check for modifications. All paths will be checked recursively. Property to be set if a modification has occurred. For use in conditionally controlling the build later. Property to be set if a file has been deleted. For use in conditionally controlling the build later.

sourcepaths Yes property No

propertyond No elete

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 folder password starteamurl username preloadFileInfo rmation property Required Yes Yes Yes Yes No (defaults to true) No Description The repository folder Password for the StarTeam user StarTeam user name When set to true can make the modification check much faster. Property to be set if a modification has occurred. For use in conditionally controlling the build later. Property to be set if a file has been deleted. For use in conditionally controlling the build later.

propertyondelet No e 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 Requir ed Description Relative or absolute path to the directory in which to run the Store script. 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

workingDirectory Yes script Yes

Attribute

Requir ed

Description image must be configured so that the only output on standard output is that produced by the CruiseControl package itself. The name of the Store connection profile for the repository to check. A comma-separated list of package names. These packages and their pre-requisites will be checked for modifications. A Regex11-style regular expression. Only package versions that match the regular expression will be considered. By default, all package versions are considered. A Store blessing level string. Package versions with a lower blessing level will not be considered. Default: Development. 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. Set this property if a modification has occurred. For use in conditionally controlling the build later.

profile packages versionRegex

Yes Yes No

minimumBlessingL No evel parcelBuilderFil No e property top <surround> <cruisecontrol> <project> <modificationset> <surround> Attributes Attribute branch Requir ed No No

Description Surround SCM branch name. The default is pulled from the local working directory. Surround SCM repository path. The default is pulled from the local working directory. Enter a file or repository name or a searchable pattern. Can be / or empty, which means the repository specified by the repository option or the default repository. If set to 1, the file parameter will be interpreted as a regular expression. Options are 1 or 0 (default). Recursively check files and sub-repositories. Options are 1 or 0 (default). 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. 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. Set this property if a modification has occurred. For use in conditionally controlling the build later.

repositor No y file No

searchreg No exp recursive No servercon No nect serverlog No in property top <svn> No

<cruisecontrol> <project> <modificationset>

<svn> Checks for changes within a Subversion repository. Attributes Attribute LocalWorkingC opy RepositoryLoc ation username password configDir property Require d One of these No No No No Description Relative or absolute path to the local working copy of the Subversion repository of which to find the log history. The url to the Subversion repository on which to find the log history. used for authentication. used for authentication. Instructs Subversion to read configuration information from the specified directory instead of the default location (.subversion in the user's home directory). Set this property if a modification has occurred. For use in conditionally controlling the build later. Set this property if a file has been deleted. For use in conditionally controlling the build later. Whether any subversion externals this project uses should also be checked for modifications. Optionally allows the user to get the modifications made between the last build time and the localworkingcopy's revision number.

propertyondel No ete checkExternal No s useLocalRevis false ion

Properties Passed to the Builders In addition to the standard CruiseControl properties passed to builders, <svn> sets the following properties: Property Name svnrevision 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: Description The repository revision number

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 Description profile Name of the profile to set. Supported by the Teamprise client. One of URL to access the Team Foundation Server including port, for these server example http://tfserver:8080 Path in the TFS repository that is recursively checked for projectPat yes modifications. Any changes under that path will trigger a h build. Specify the full path to the tf command being used. If not No supplied then the plug-in will try to locate a command called (default tfPath "tf" in the cruise control system path. By default, the s to Microsoft client is installed into C:\Program Files\Microsoft "tf") Visual Studio 8\Common7\IDE\TF.exe No inputEncod (default Required if file names or comments contains non-Latin symbols ing s to UTF-8) 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 username no 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. The password to use with the username when authenticating with the server. An optional string that may be passed as part of the command line. The contents of the options tag are passed as an argument to the tf history command.

password options

no no

Properties Passed to the Builders In addition to the standard CruiseControl properties passed to builders, <svn> sets the following properties: Property Description Name tfschangese The maximum changeset number in the t 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 Attribu Required te usernam No (defaults e to "User") time Yes Description The username to use for the single reported (fake) Modification. The threshold time to cross that starts triggering a build, specified as hhmm format. Set this property if a modification has occurred. For use in conditionally controlling the build later.

propert No y top <ucm> <cruisecontrol> <project> <modificationset> <ucm>

Triggers a build if there is a change within a ClearCase UCM repository. Attributes Attribut e stream rebases pvob contribu tors viewpath property multiVob Required Yes Description

The ClearCase UCM stream (actually, the branch, so make sure to enter the branch type if it is named differently than your UCM stream) No (defaults Whether rebases of the integration stream are reported as to false) changes. No (unless The name of the pvob to use for queries. Required if rebases rebases is = true. Required if multiVob is true and the pvob for the true) project is not loaded or mounted. No (defaults Whether to check for and log contributor activities to true) Yes Local working copy to use when making queries Set this property if a modification has occurred. For use in No conditionally controlling the build later. Set whether the view contains multiple vobs. Defaults to No false.

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

Property Description Name ucmlastbuil Timestamp representing the last built time, using the format dd-MMMMd yyyy.HH:mm:ss Timestamp representing the time the current build started, using the ucmnow 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 Cardinal ity Description 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>. 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>.

<triggers 1 > <buildsta 1 tus> 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 Required Description No (defaults to The date format to use for querying VSS and processing dateformat default is reports. If your computer is set to a different region, MM/dd/yy) you may wish to use a format such as dd/MM/yy. The time format to use for querying VSS and processing No (default is timeformat reports. If your VSS is configured differently you may hh:mma) need a different format such as HH:mm:ss. The VSS project to get history from. vsspath Yes Example: /Project/subproject login Yes The VSS login to use, in the form username,password Path to the directory containing ss.exe. By default, ssdir No ss.exe is assumed to be in the path. Note: should not contain whitespace. serverpath No Path to the directory containing srcsafe.ini. Set this property if a modification has occurred. For property No use in conditionally controlling the build later. propertyond Set this property if a file has been deleted. For use No elete 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 Requir ed Description Full path to journal file. Example: c:/vssdata/journal/journal.txt The VSS project to get history from Set this property if a modification has occurred. For use in conditionally controlling the build later. Set this property if a file has been deleted. For use in conditionally controlling the build later. Attribute

journalfile Yes ssdir property Yes No

propertyond No elete 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 Description Interval period in seconds. Default value is 300 (five minutes). Maximum value is 31536000 (one year), but for the builders that interval No 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. If true or omitted, the scheduled builder will provide progress No messages if the builder supports this feature and the builder's showProgr (default own showProgress setting is not false. If false, no progress ess s to messages will be shown - regardless of the scheduled builder's true) showProgress setting. Child Elements Element Cardinal Description ity 0 .. * Builds the project using Ant. Executes a list of builds. Builds the project Builds the project Maven2. Pauses the build. Builds the project Builds the project Builds the project Builds the project ExecBuilder. Builds the project PipedExecBuilder. Builds the project Apple's Xcode IDE. using Maven. using Attribute Required

<ant> <composit 0 .. * e> <maven> 0 .. * <maven2> 0 .. * <pause> <nant> <phing> <rake> <exec> 0 0 0 0 .. .. .. .. * * * *

0 .. *

using using using using

NAnt. Phing. Rake. the

<pipedexe 0 .. * c> <xcode> 0 .. *

using the using

Common Builder Attributes Attribute Required multiple time day No No No Description Build index used to run different builders. For example, if this is set to 3, the builder will be run every 3 builds. Default value is 1. Can't be set if time is set. Time in the form HHmm. Can't be set if multiple is set. Valid values are (case-insensitive) the English names for the days of the week (Sunday, Monday, Tuesday, etc). Does not support multiple days except for the default of every day.

Description If true, the builder will provide short progress messages, No visible in the JSP reporting application. If parent builders showProgr (defaults exist (eg: composite), and any parent's showProgress=false, ess to true) then no progress messages will be shown, regardless of this builder's showProgress setting. No If true, the builder will write all output to a file that can liveOutpu (defaults be read by the Dashboard reporting application while the t to true) 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 projectname label Description The name of the CruiseControl project. The build label determined by the labelincrementer Timestamp that indicates when the build started, using the cvstimestamp format yyyy-MM-dd HH:mm:ss 'GMT' so it can be used as a CVS argument Timestamp that indicates when the build started, using the cctimestamp format yyyyMMddHHmmss Timestamp that indicates when the last successful build was run, cclastgoodbuildti using the format yyyyMMddHHmmss. Only available if the project mestamp has previously built successfullly. Timestamp that indicates when the last build was run, using the cclastbuildtimest format yyyyMMddHHmmss. Only available if the project has built amp prevviously. lastbuildsuccessf indicates if the last build was successful; either "true" or ul "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>.

Attribute Required

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

2.

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 buildfile target Required No (defaults to build.xml) No Description Path to Ant build file.

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 Absolute filename of script (shell script or bat file) used to start Ant. You can use this No, but recommended. to make CruiseControl use your own Ant Cannot be specified if antscript installation. If this is not specified, the anthome attribute is AntBuilder uses the Ant distribution that also specified ships with CruiseControl. See below for examples. Directory in which Ant is installed. No. Cannot be specified CruiseControl will attempt to use the anthome if antscript attribute standard Ant execution scripts (i.e. ant.bat is also specified. or ant). See below for examples. antWorkingDir No Will invoke ant in the specified directory. If supplied a copy of the ant log will be saveLogDir No saved in the specified directory. Example: saveLogDir="/usr/local/dev/projects/cc/logs" Ant build will be halted if it continues timeout No 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 recommended for production situations.

Attribute

Required

Description

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). If you want to use another logger (or listener, when uselogger="false") than Ant's No (defaults to loggerclassna XmlLogger, you can specify the classname of org.apache.tools.ant.Xml me the logger here. The logger needs to output Logger) compatible XML, and the class needs to be available on the classpath at buildtime. 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 usedebug No 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. 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 usequiet No 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). If true will invoke ant with -keep-going, which can be useful for performing build steps after an optional step fails. Defaults to 'false'. Load all properties from file with -D properties (like child <property> elements) taking precedence. Useful when the propertyfile content can change for every build. Overrides the default -lib search path used to add support for showProgress features in the ant builder. This search path ensures customized ant Loggers/Listeners are

keepgoing

No

propertyfile No progressLogge No rLib

Attribute

Required

Description 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 Cardinal ity Description 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"/> 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"/> Used to define additional library directories for the ant build. The element has one required attribute: "searchPath". Example: <lib searchPath="/home/me/myantextensions"/> 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"/>

<jvmarg 0 .. * > <proper 0 .. * ty> <lib> 0 .. *

<listen 0 .. * er>

Examples

1. Invoke the ant.bat script distributed with ant using the antscript
2. 3. 4. 5. 6. 7. attribute, specifying the working directory as D:\workspace\MyProject and the ant build file as MyProject-nightlybuild.xml using the default target. <schedule> <ant antscript="C:\Java\apache-ant-1.6.1\bin\ant.bat" antworkingdir="D:\workspace\MyProject" buildfile="MyProject-nightlybuild.xml" uselogger="true" usedebug="false"/> <schedule> Or equivalently, using the anthome attribute <schedule> <ant anthome="C:\Java\apache-ant-1.6.1" antworkingdir="D:\workspace\MyProject" buildfile="MyProject-nightlybuild.xml" uselogger="true" usedebug="false"/> <schedule>

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/sh PROJECT_HOME=`dirname "$0"` ANT_HOME=${PROJECT_HOME}/tools/ant chmod 0755 ${ANT_HOME}/bin/ant ANT_CMD=${ANT_HOME}/bin/ant exec "$ANT_CMD" "$@" Note the double quotes around $@: this ensures that all arguments will be quoted, which is necessary for arguments containing spaces. An example of a Windows batch file to invoke ant: @echo off setlocal set PROJECT_HOME=%~dp0 call %PROJECT_HOME%..\devtools\env.bat call ant.bat %* endlocal The %* as a param to ant.bat is important it means that all the arguments to build.bat are passed along to ant.bat. If this is skipped then CruiseControl wouldn't work properly. 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-cvsupdate' 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.

Attribut Requir Description e ed mavenscr Absolute filename of maven startup script (maven.bat or Yes ipt maven.sh). projectf Yes Path to Maven's "project.xml" file ile Maven goal, "set of goals" or "set of set of goals" to goal Yes run. (see above Note2) Build will be halted if it continues longer than the timeout No 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: Goals "clean compile" will run 'clean' goal then 'compile' goal on the project, within the same Maven2 session run "clean" will run 'clean' goal on the project

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 mvnscript mvnhome pomfile goal Require d Description

Path to maven startup script (.../bin/mvn.bat or mvn.sh). One of Path to Maven2's home directory (M2_HOME). Maven script will be these found by appending "/bin/mvn" (or "/bin/mvn.bat") to this directory. Yes Path to Maven2's "pom.xml" file Yes Maven2 goal, "set of goals" or "set of set of goals" to run.

Attribute

Require d

Description (see Goals note above) Maven2 site goal, "set of site goals" or "set of set of site 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. Alternate path for the user settings file. Comma-delimited list of profiles to activate. Command line flags to be passed to maven. For example: '-U -Dmaven.test.skip=true'. The flags will be passed to each session invocation (see Sessions note above). Build will be halted if it continues longer than the specified timeout. Value in seconds.

sitegoal

No

settingsfi No le activatepr No ofiles flags timeout No No

Child Elements Element Cardinal ity Description 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"/>

<proper 0 .. * ty> 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. Description Composite Build will be halted if it continues longer than the timeout No specified timeout. Value in seconds. If true or omitted, the composite builder will provide progress messages, as will any child builders that support this feature No (assuming the child builder's own showProgress setting is true). showProgr (default If false, no progress messages will be shown by the composite ess s to builder or child builders - regardless of child builder true) showProgress settings. If any parent showProgress is false, then no progress will be shown, regardless of the composite or child builder settings. liveOutpu No Currently, the liveOutput setting has no effect on composite t (default builders. s to Attribute Required

Attribute Required true) Child Elements Cardinal Description ity <ant> 0 .. * Builds the project using <maven> 0 .. * Builds the project using Builds the project using <maven2> 0 .. * Maven2. <nant> 0 .. * Builds the project using <phing> 0 .. * Builds the project using <rake> 0 .. * Builds the project using Builds the project using <exec> 0 .. * ExecBuilder. <pipedexe Builds the project using 0 .. * c> PipedExecBuilder. Builds the project using <xcode> 0 .. * Apple's Xcode IDE. top top Element <pause> <cruisecontrol> <project> <schedule> <pause>

Description

Ant. Maven.

NAnt. Phing. Rake. the the

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 Attribu Requir te ed day No Description Day when the pause should take place (Sunday, Monday, etc). Does not support multiple days except for the default of every day. Start of the pause in HHmm format End of the pause in HHmm format

startti Yes me endtime Yes top <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 buildfile target tempfile targetFrame work nantWorking Dir timeout Required No (defaults to default.build) No No No, but recommended No No Description Path to NAnt build file. NAnt target(s) to run. Default is "", or the default target for the build file. Name of temp file. Defaults to log.xml Specifies the framework to target. Typical values are "net-1.1" and "mono-1.0". Will invoke NAnt in the specified directory.

NAnt build will be halted if it continues longer than the specified timeout. Value in seconds. '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 uselogger No 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. If you want to use another logger than NAnt's No (defaults to XmlLogger, you can specify the classname of the loggerclass NAnt.Core.XmlLogge logger here. The logger needs to output compatible name r) XML, and the class needs to be available on the classpath at buildtime. If true will invoke NAnt with -debug, which can be useful for debugging your NAnt build. Defaults to usedebug No 'false', cannot be set to 'true' if usequiet is also set to 'true'. Is only effective when used in combination with uselogger="true"! 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 usequiet No 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

Cardinal ity

Description 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"/>

<proper 0 .. * ty>

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 buildfile target tempfile Required No (defaults to build.xml) No No Description Path to Phing build file. Phing target(s) to run. Default is "", or the default target for the build file. Name of temp file. Defaults to log.xml

Required No. Cannot be specified if phingscript phinghome attribute is also specified No. Cannot be specified if phinghome phingscript attribute is also specified. phingWorking No Dir saveLogDir No

Attribute

Description 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. 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. Will invoke phing in the specified directory.

If supplied a copy of the phing log will be saved in the specified directory. Example: saveLogDir="/usr/local/dev/projects/cc/logs" Phing build will be halted if it continues longer timeout No than the specified timeout. Value in seconds. '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 uselogger No 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. If you want to use another logger (or listener, when uselogger="false") than Phing's XmlLogger, No (defaults to loggerclassn you can specify the classname of the logger here. phing.listener.XmlLo ame The logger needs to output compatible XML, and gger) the class needs to be available on the classpath at buildtime. 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 usedebug No 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. 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 usequiet No '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 Cardinal Description ity <proper 0 .. * Used to define properties for the phing build. The element has two ty> required attributes: "name" and "value". These will be passed on the phing command-line as "-Dname=value" Element

Element

Cardinal ity

Description Example: <property name="foo" value="bar"/>

Examples

1. Invoke the phing.bat script distributed with phing using the phingscript
2. 3. 4. 5. 6. 7. attribute, specifying the working directory as D:\workspace\MyProject and the phing build file as MyProject-nightlybuild.xml using the default target. <schedule> <phing phingscript="C:\PHP\applications\phing-2.3.0\bin\phing.bat" phingworkingdir="D:\workspace\MyProject" buildfile="MyProject-nightlybuild.xml" uselogger="true" usedebug="false"/> <schedule> Or equivalently, using the phinghome attribute <schedule> <phing phinghome="C:\PHP\applications\phing-2.3.0\bin\" phingworkingdir="D:\workspace\MyProject" buildfile="MyProject-nightlybuild.xml" uselogger="true" usedebug="false"/> <schedule>

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. Attribut Required e No ruby (defaults to ruby) No rake (defaults to rake) No buildfil (defaults e to Rakefile) target No Description Name of / Path to the ruby interpreter. Typical values are "ruby", "ruby19" or "jruby" Name of / Path to the rake binary. Typical values are "rake", "rake19" or "jrake" 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 Rake target(s) to run. Default is "", or the default target for the rake file.

Attribut Required e workingD No ir timeout No top <exec> <cruisecontrol> <project> <schedule> <exec>

Description Will invoke rake in the specified directory. The directory can be relative (to the cruisecontrol current working directory) or absolute. Rake build will be halted if it continues longer than the specified timeout. Value in seconds.

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. Attribu Requir Description te ed command Yes The command or script to be executed. Set of arguments (as a single string) to be passed to the command args No or script. working The directory in which the script or command is to be executed. No dir Defaults to the Java temporary directory. errorst String which is to be searched for in the output of the command or No r script. If it is found then the build will return an error. Build will be halted if the script or command continues longer than timeout No 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. Attribu Requir te ed working No dir timeout No Description 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. 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 Elemen Cardinal t ity <exec> 0 .. * Description Runs a specified command or script under the piped exec builder, and optionally pipe it with another command(s) or script(s).

Elemen Cardinal t ity

Description 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 Requir Description te ed The unique identifier of the command or script id Yes script (any string). The value is referenced by pipefrom and waitfor attributes. The ID of script to connect to - the STDIO of this pipefro command or script is fed up by STDOUT of <exec> with No m the given ID. Several <exec> may be piped from one ID. waitfor No

The execution of this command or script will be hold 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. 29. 30.

args="third.pl -o result.txt" workingdir="/distribution/${projectname}" /> </pipedexec> </schedule>

31.

top

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

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

Attribu Requir Description te ed directo Yes Path the directory where xcodebuild will execute ry Build will be halted if the command continues longer than the timeout No specified timeout. Value in seconds. Child Elements Elemen Cardinal t ity <arg> 0 .. * 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 dir encoding Requir ed No No Description The cruisecontrol log directory. Default is "logs/ [projectname]". Encoding for CruiseControl's XML log file. if true, trim whitespace from start and end of log lines. Primarily intended only to force historic "trim" behavior. Defaults to false. Description 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}"/>.

trimWhites No pace Child Elements Element <merge> <gzip> <delete>

Cardinal ity 0 .. * 0 .. 1 0 .. 1

Description Merges log file together. GZips old log files Deletes old log files. Deletes old artifact directories.

<deletearti 0 .. 1 facts> 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 file Description path to file to merge into build log One of file all files matching the specified pattern will be merged or dir. dir into the build log. No removeproper when merging a JUnit xml file should the properties section (defaults ties be removed. to true) Specifies the pattern which matches the filenames to merge. pattern No 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 Attribu Requir te ed every unit top <delete> <cruisecontrol> <project> <log> <delete> After the build-file is written, this manipulator deletes all old log files that may exist. Attributes Attribut Requir e ed every unit true true Description Sets the amount of Units after which the logfiles are deleted. The Unit for deletions. Valid Units are DAY, WEEK, MONTH or YEAR Ignores default xml-suffix when deleting files, so other logfiles could be deleted true true Sets the logfiles The Unit MONTH or Description amount of Units after which the are backuped. for backups. Valid Units are DAY, WEEK, YEAR Required

ignoreSu true ffix

top <deleteartifacts> <cruisecontrol> <project> <log> <deleteartifacts> After the build-file is written, this manipulator deletes all old artifact directories that may exist. Attributes Attribu Requir te ed every unit 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 <antpublisher> Cardinal ity 0 .. * .. * .. * .. * .. * .. * .. * .. * Description Executes an Ant script which implements a custom publisher. Copies build products to a directory Creates a ClearCase UCM baseline. Creates an intermediate baseline in a CM Synergy database. Copies all new CM Synergy tasks into a shared folder. Executes all publishers specified as child elements. Sends an email with a URL to the build results JSP Execute a command as part of the publishing phase Copies the log file and build artifacts to an FTP server Sends an email with the build results embedded as HTML Connects to an HTTP URL and sends the build results as parameters Sends an instant message with a link to the build results via a Jabber server using XMPP Executes all publishers specified as child elements if and only if the current build failed. Executes all publishers specified as child elements if and only if the current build was successful. true true Description Sets the amount of Units after which the artifact directories are deleted. The Unit for deletions. Valid Units are DAY, WEEK, MONTH or YEAR

<artifactspublisher> 0 <clearcasebaselinepub 0 lisher> <cmsynergybaselinepub 0 lisher> <cmsynergytaskpublish 0 er> <compoundpublisher> 0 <email> 0 <execute> 0 <ftppublisher> <htmlemail> <http> <jabber> <onfailure> <onsuccess>

0 .. * 0 .. * 0 .. * 0 .. * 0 .. 1 0 .. 1

Cardinal Description ity <origo> 0 .. * Creates/closes an issue in an Origo project. <sametimeannouncement Sends Sametime announcements with the result of the 0 .. * > build <scp> 0 .. * Copies a file using SCP Uploads a document to a SourceForge Enterprise <sfeedocman> 0 .. * Edition project's Document Manager. Uploads a file to a SourceForge Enterprise Edition <sfeefrs> 0 .. * project's file release system (FRS). Creates a Tracker artifact in a SourceForge <sfeetracker> 0 .. * 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 Sends an instant message with a link to the build <yahoopublisher> 0 .. * results via a Yahoo IM message top Element <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 Description thisbuildsucc Set to true if the current build was successful, false otherwise. See essful also the <onsuccess> and <onfailure>. projectname The name of the CruiseControl project. The timestamp of the last attempted build, using the format lastbuild yyyyMMddHHmmss. lastsuccessfu The timestamp of the last successful build, using the format lbuild 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 MyProjectnightlybuild.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 MyProjectnightlybuild.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 file dir Required Description will copy specified file one of file or dir will copy all files from this directory parent directory of actual destination directory; dest Yes actual destination directory name will be the build timestamp. subdirectory under the unique (timestamp) directory to subdirectory No contain artifacts Deprecated. Use <onsuccess> and <onfailure> instead. publishOnFailu No (defaults set this attribute to false to stop the publisher from re to true) running when the build fails. moveInsteadOfC No (defaults The publisher will move files/directrories instead of opy to false) 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 viewtag full Requir ed Yes No Description The view tag of the UCM view that you wish to create the baseline in. The baseline is created in the stream that the view is attached to. Boolean value indicating whether a "Fully Labelled" or "Incremental" baseline should be created. Default is false, i.e. "Incremental". 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". The component to restrict the baseline creation to. By default the baseline is applied to all of the stream's changed components.

baselinep No refix component No

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 ccmexe Requir Description ed No The name of the CM Synergy command line client. If not provided,

Attribute

Requir ed

Description the plugin will search the system path for an executable called "ccm" (or "ccm.exe" for Windows). 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. 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. The project spec (two part name) of the project you wish to form the top level project of the baseline. Note that all subprojects will also be included. The purpose of the baseline. If not specified, this will default to "Integration Testing". An optional description of the baseline. 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}". A value for the build attribute introduced for baselines since Synergy 6.4. 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".

sessionfi No le sessionna No me project purpose Yes No

descripti No on baselinen No ame build No

state

No

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 ccmexe No Required Description The name of the CM Synergy command line client. If not provided, the plugin will search the system path for an

Attribute

Required

sessionfi No le sessionna No me foldernum ber

Description executable called "ccm" (or "ccm.exe" for Windows). 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. 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.

The number of the target folder. Either A substring of the name of the target folder (i.e. foldernam foldernumber or "Integration tested tasks"). If this attribute is set, e foldername and you must also set the project attribute. project The two part name of the project which contains the named project 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 Attribu Requir te ed command Yes top <scp> <cruisecontrol> <project> Description The command to execute

<publishers> <scp> SCP a file as part of the publishing process. Attributes Attribute Required executableN No ame Yes if sourcehost is sourceuser specified Yes if sourceuser is sourcehost specified sourcedir No (defaults to '.') Yes if targethost is targetuser specified Yes if targetuser is targethost specified targetdir No (defaults to '.') No (defaults to targetsepar File.separator on ator the source machine) Description Specify the name of the executable to invoke. Default is "scp". Log in to the sourcemachine as this user. SCP from this machine. The directory to copy from. Log in to the target machine as this user. SCP to this machine. The directory to copy to. The file separator on the target machine.

The file separator on the source machine. Useful No (defaults to sourcesepar when using an alternate shell environment, e.g. File.separator on ator Cygwin, that expects a separator that differs from the source machine) the native OS. No (defaults to ssh The ssh application. 'ssh') options No Additional options to pass to SCP. No (defaults to the file The filename to copy. current logfile) 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 Attribut e serverur l username password document Requir ed Yes Yes Yes Yes Description URL for the SFEE instance. Valid username for the specified SFEE instance. Password for the specified username. The path to the document to publish.

Attribut Requir Description e ed folder Yes The Document Manager folder in which to publish. projectN The name of the SFEE project where the Document Manager Yes ame folder specified exists. Child Elements Element Cardinal ity Description The description for the Document. This child element is required and is an XPath Aware Child. Look there for attribute details. The status for the Document. This child element is required and is an XPath Aware Child. Look there for attribute details. 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. The version comment for the Document. This child element is optional and is a XPath Aware Child. Look there for attribute details.

<description> 1 <status> 1

<documentname 0..1 >

<versioncomme 0..1 nt> 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

Attribut e file Yes

Required

Description Path to a file on the local filesystem that should be uploaded. URL for the SFEE instance. Valid username for the specified SFEE instance. Password for the specified username. The SFEE id for the FRS release, e.g. rel2509. The name to be used for the file in the FRS.

serverur Yes l username Yes password releasei d uploadna me Examples Yes Yes No (defaults to the same name as the local file)

<!-- 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 Attribut e trackerN ame projectN ame serverur l Requir ed Yes Yes Yes Description The name of the Tracker within the specified SFEE project. The name of the SFEE project where the tracker specified exists. URL for the SFEE instance.

Attribut Requir e ed username Yes password Yes Child Elements Element <title> Cardinal ity 1

Description Valid username for the specified SFEE instance. Password for the specified username.

Description The title for the tracker artifact. This child element is required and is an XPath Aware Child. Look there for attribute details. The description for the tracker artifact. This child element is required and is an XPath Aware Child. Look there for attribute details. The status for the tracker artifact. This child element is required and is an XPath Aware Child. Look there for attribute details. 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.

<descript 1 ion> <status> <field> 1 0..*

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 URL to the build results JSP. This defaults to the hostname, domain name and web port (if specified) of the server, followed by /dashboard. Default e-mail suffix to append to user names to build valid e-mail addresses. This defaults to an empty string if not specified. Flag emails about failed builds as important? Default is 'true'. Mail server address to use for sending build notification

buildresults No url defaultsuffi No x failasimport No ant mailhost No

Attribute

Required

mailport

No if password username Username for smtp server is specified if username password Password for smtp server is specified Valid values: always: publishes (i.e., e-mails) results on every successful No build. reportsucces (defaults fixes: s to always publishes results only on the first successful build and the first successful build after a failed build. never: only publishes on failed builds returnaddres E-mail address that will appear in the sent email's From Yes s field returnname No A name to match to the return address Controls if the users who made changes in this build get No email. Useful to set to "true" while configuring or skipusers (defaults debugging your system. Users specified by the failure or to false) always nested elements will still receive email. No spamwhilebro Whether or not e-mail reports on failed builds will (defaults ken continue for subsequent failed builds. to true) subjectprefi Prefix for subject line of email. Useful for easily No x filtering email. "true" to connect to the smtp server using SSL. Do not usessl No forget to set the corresponding mailport. Child Elements Element Cardinal ity Description Mail address to be emailed notification after all builds. <always> has the following attributes: Attribu Requir Descriptio te ed n address Yes

Description 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. Mail server port

<always>

0 .. *

e-mail address

<failure>

0 .. *

Mail address to be emailed notification after failed builds. <failure> has the following attributes: Requir Attribute Description ed address Yes e-mail address reportWhenFi No xed

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:

Element

Cardinal ity Attribu Requir te ed user Yes

Description Description

user name from modification to be ignored

<success>

0 .. *

Mail address to be emailed notification after successful builds. <success> has the following attributes: Attribu Requir Descriptio te ed n address Yes

e-mail address

<alert>

0 .. *

<map>

0 .. *

<propertiesma 0 .. * pper>

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 Requir Description e ed fileRegE A regular expression indicating which Yes xpr modified files you are interested in address Yes e-mail address Maps a source control user id to an email address. <map> has the following attributes: Attribu Requir Description te ed alias (username) as it appears alias Yes on modifications address Yes e-mail address map source control user names to either valid email names or complete email addresses. <propertiesmapper> has the following attributes: Attribu Requir Description te ed 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.

<harvestmappe 0 .. * r>

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 Requir Description te ed The name of the Harvest Broker to broker Yes connect to. usernam Usename to use in connecting to the Yes e Harvest Broker. passwor Yes d

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 Requir Description te ed Full path to Maven's project.xml (Maven 1) project Yes file or pom.xml (Maven 2) file.

Element

Cardinal ity

Description map source control user names to either valid email names or complete email addresses. <ldapmapper> has the following attributes: Attribute Required Description URL used to connect to an LDAP server, url Yes e.g. ldap://ca.com:389 rootdn Yes search DN, scope is sub-tree-level binddn no DN to bind to the LDAP if binddn bindpassw is password to bind to the LDAP ord specifie d Search filter. Default: (cn=?). The ? searchtmp character in the template is replaced by No l the user id to be mapped into an email address Default: mail. The LDAP attribute that searchatt is searched to retrieve the email No r address of the user id used in the search. ctxfactor No y

<ldapmapper>

0 .. *

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 buildresul No tsurl charset css Description Email will include link to the build results JSP if this URL is provided. If not set the content type will be set to 'text/html'. If No set the content type will be 'text/html;charset="value"'. versions Path to cruisecontrol.css. Used only if xsldir set and not up to 2.3: xslfile. Starting with version 2.3, the HTMLEmailPublisher unless will try to determine the correct value itself when it's not xslfile specified and xslfile isn't used. specified versions

Attribute

logdir

xsldir

Required 2.3 and greater: no No (Yes for versions < 2.2) versions up to 2.3: unless xslfile specified versions 2.3 and greater: no No

Description

Path to the log directory as set in the log element of the configuration xml file. Follows default of log's dirattribute since version 2.2

Directory where standard CruiseControl xsl files are located. Starting with version 2.3, the HTMLEmailPublisher will try to determine the correct value itself when it's not specified and xslfile isn't used.

xslfile

xslfilelis No t

If specified, xsldir, xslfilelist, and css are ignored. Must handle the entire document. 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 hardcoded list of xsl files.

Child Elements Element Cardinal ity Description 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 Requir Description te ed the name of the XSLT name Yes parameter value Yes the parameter's value

<paramet 0 .. * er>

top <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 url Requir ed Yes Description The URL to connect to. Must be of the HTTP protocol. HTTP request method. POST, GET etc.

requestMet Yes

Attribute hod

Requir ed

Description

Child Elements Element Cardinal ity Description Sets an HTTP attribute-value parameter. If the request method is GET, the attribute-value pairs are added to the URL string. Otherwise they are included in the message body. This child element is optional and is a Named XPath Aware Child. Look there for attribute details.

<paramet 0..* er> top <jabber> <cruisecontrol> <project> <publishers> <jabber>

Sends an instant message with a link to the build results via a Jabber server using XMPP. Attributes Requir Description ed host Yes The host of the Jabber server. Port of the Jabber server. Defaults to 5222. Note: SSL typically port No runs on port 5223. Username of the account used to send the instant message. For username Yes individuals, this is typically of the form 'foo' as opposed to 'foo@bar.com' password Yes Password of the sender account Username of the recipient of the instant message. Recipient recipient Yes username is typically fully qualified: foo@bar.com Whether the recipient is a group/chat (true) versus an individual chatroom No (false). Defaults to false. ssl No Whether the XMPP connection on host:port is using SSL. buildresul Yes Email will include link to the build results. tsurl service No Service to use. top Attribute <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 Any defined publisher 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: Cardinal ity 1 .. * Description You may use any defined publisher as a child element.

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 Any defined publisher 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"/> Cardinal ity 1 .. * Description You may use any defined publisher as a child element.

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 Required No (defaults to apiurl http://api.origo.ethz.ch/api/xmlr pc) buildresul No (defaults to tsurl http://localhost:8180/) issuepriva No (defaults to true) te issuesubje No (defaults to Cruisecontrol ct failed) No (defaults to issuetag cruisecontrol::failed) projectnam Yes e userkey 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 Yes Attribute Description URL to Origo API URL to the build results JSP Should the issue be private Subject for newly created issue Tag for newly created issue, must be unique in the project Name of the origo project Origo user key to report/update the issue

Attribute

Requir ed

Description RSS item will include a link to the build results page. Build results URL should look like 'http://MACHINENAME/cruisecontrol/buildresults/PROJECTNAME'. The primary URL associated with the RSS feed. 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. The maximum number of items to maintain in the RSS file. Defaults to 10.

buildresul yes tsurl channellin No kurl file Yes

maxlength No 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 buildresultsurl host username password community resolveusers Required No Yes Yes No No No to No to Description URL to include with the build results. Synonym for mailHost. User name to login to the Sametime community. Password used to login to the Sametime community. If not specified, an anonymous login (using username) will be attempted. Sametime community to login to. Default is null appropriate for single community servers.

(defaults Whether addresses should be resolved as users. true) (defaults resolvegroups Whether addresses should be resolved as groups. true) Whether to send announcements to the content No (defaults usegroupcontent (members) of a group instead of the group to true) directly. How to handle address resolution conflicts. Valid values: error: abort the announcement warn: No (defaults handleresolveconflic log a warning, ignoring the conflicting to ts addresses recipient) ignore: ignore the conflicting addresses recipient: treat all conflicting addresses as recipients of the announcement

Description How to handle address resolution failures. Valid values: error: No (defaults abort the announcement handleresolvefails to error) warn: log a warning and proceed ignore: ignore the failure How to handle group content query failures. Valid values: error: handlequerygroupcont No (defaults abort the announcement entfails to error) warn: log a warning and proceed ignore: ignore the failure top <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 socketServer Yes port Yes sendProjectN No (defaults ame to true) No (defaults sendFixed to false) 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 Attribu Requir te ed usernam Yes e passwor Yes d top Description Username for the Twitter account. Password for the Twitter account. Required Description Hostname (i.e., first argument for constructing a Java socket) Port number for the listening socket Whether the project name should be appended to the result string. Whether the publisher should send "Fixed" instead of "Success" after "Failure".

Attribute

Required

<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

Attribute Required blogurl blogid username password logdir Yes Yes

Yes Yes Yes Yes, unless The XSL stylesheet used for transforming the build results into xslfile xsldir is the message being posted to the blog. used. The directory containing the XSL stylesheets used for Yes, transforming the build results into the message being posted to unless xsldir the blog. You can use the CruiseControl distribution's XSL xslfile directory, "${CC_HOME}/reporting/jsp/xsl", or use your custom is used. stylesheets. The path to cruisecontrol.css to be used for styling the Yes, if generated HTML. You can use the CruiseControl distribution's css xsldir is 'cruisecontrol.css' file from "${CC_HOME}/reporting/jsp/css" or used. use a custom stylesheet. The base URL for the CruiseControl reporting web application. Usually of the form buildresul No "http://buildserver/cruisecontrol/<projectname>". If this URL tsurl is provided, the resulting blog entry will include a link to the build results. The category to which the blog entries should be added. For the Blogger API, only one category name is allowed. For the category No MetaWeblog API, a comma-separated list of category names is also possible. The rule for reporting successful builds. Accepted values are reportsucc No "always", "never", and "fixes" (only post the results for the ess first successful build after a failed one). subjectpre No The prefix to use for blog entries' title. fix 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

Description blogger and metaWeblog. Defaults to metaWeblog. The URL where your blog receives XML-RPC requests. The "identifier" for your blog. See your blog's documentation for the correct value. The username for authentication. The password for authentication. The CruiseControl log directory.

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 houseCode Yes Description The house code for the device to control, A through P

Attribute

Required

deviceCode Yes No (defaults port to COM2) onWhenBrok No (defaults en to true) interfaceM No (defaults odel to CM11A) Examples

Description case insensitive The device code for the device to control, 1 -> 16 Serial port to which the computer interface controller is connected, e.g. COM1 Set to false if the device should turn on when the build is successful and off when failed Model number for the computer interface controller being used, either CM11A or CM17A (case insensitive).

<!--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 directory Yes outfilena No me publishon No (defaults fail to true) xsltfile Yes top <yahoopublisher> <cruisecontrol> Description Directory for output file Name for the output file. Default uses the build label, 'label.log' Deprecated. Use <onsuccess> and <onfailure> instead. Generate file if the build failed? XSL file to used for the transform.

<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 username password Requir ed Yes Yes Description Username of the account used to send the instant message. For individuals, this is typically of the form 'foo' as opposed to 'foo@yahoo.com' Password of the sender account Username of the recipient of the instant message. Recipient username is typically of the form 'foo' as opposed to 'foo@yahoo.com' Email will include link to the build results. HTTP proxy to use. HTTP proxy port to use.

recipient Yes buildresul Yes tsurl proxyHost No proxyPort No 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 Attribu Requir te ed name Yes Description The alias used to refer to the plugin elsewhere in the configuration file. The class that implements the plugin.

classna Yes me 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 defaultLabel Required No (default to "build.1") Description set label to use if there is no saved label.

if true the build number will be incremented prior to preBuildIncrem No (defaults the build attempt and thus each build attempt will have enter to false) a unique build number. No (defaults specifies the separator to use between label and build separator to period 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 defaultLabel Requir ed No Description Set label to use if there is no saved label. Default is CC_1_INT.

Attribute

Requir ed

Description 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. Indications if a prefix is required (three part label) or not (two part label). Default is true. Specifies the separator to use between portions of the label. Default is underscore '_'

preBuildIncrem No enter prefix separator top No No

<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 Attribu Required te changel No ist port Yes client Yes user Yes passwd No view Yes separat No or (defaults Description set the changelist number to sync to. Not specifying this value will sync to the most recently committed changelist. Perforce Server connection to use (host:port) Perforce Client name to use Perforce User name to use Perforce password to use Valid Perforce view (i.e. a depot path) specifies the separator to use between label and build count.

Attribu te

Required

Description

to period '.') No noSync (defaults to false) clean No (defaults to false)

enable to turn off synchronizing the depot to the label (changelist) number. 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. 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.

No delete (defaults to 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 defaultlabel Requir ed No Description value to return if property file doesn't exist. if not specified and file doesn't exist an exception is thrown. 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 the property file to read. the name of the property to read for the value of the label.

preBuildIncrem No enter propertyfile propertyname top Yes Yes

<svnlabelincrementer> <cruisecontrol> <project> <svnlabelincrementer> Returns a value for the label based on the SVN revision number. Attributes

Attribute workingcopyp No ath to No labelprefix to No separator to top <ftppublisher>

Required (defaults .) (defaults svn) (defaults .)

Description Path to the SVN working copy Prefix for the label The separator to use between label and build count

<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 destDir srcDir Required Yes Yes Description The remote directory (relative to targetDir) to publish the files. To 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.

No deleteArti If true, then all files successfully sent to the FTP server (defaults facts will be deleted locally. to false) top Common FTP Attributes The following attributes are common to the <ftppublisher>. Attribute Required targetHost Yes No (defaults to targetUser anonymous) targetPass No (default to wd eat@joes.com) targetPort No (defaults to 21) Description Host name of the FTP server. The user used for logging into the FTP site. The password used during FTP log in for the targetUser. Port number of the FTP server. Base directory in the FTP server to targetDir No (defaults to '.') put the files. targetSepa Directory separator character used by No (defaults to '/'. rator the FTP server. top XPath Aware Child Attributes The following attributes are common to the xpath aware children found in <sfeetracker> and <sfeedocman>.

Required Description One of value or value xpathExpression must A fixed value that will not change at runtime. be specified. An xpath expression to evaluate against the One of value or xpathExpres CruiseControl log file, or the xml file as xpathExpression must sion specified by xmlFile attribute. The result of the be specified. expression will be used as the value. No (defaults to the Path to a file on the local filesystem against xmlFile CruiseControl build which the xpathExpression will be evaluated. log). 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. Attribu Requir te ed name 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 Yes Description The name of a field in the tracker artifact.

Attribute

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