Publishing

In the previous chapter I created two publishersone to send an e-mail on build success or failure, and the other to store the build results in an archive directory. However, CruiseControl has a number of other publishers that can automate aspects of your build and release process. This section discusses how to implement the following publisher scenarios:

• Deploying your application to a web or application server

• FTPing the results of your build to a remote server

• Specifying which publishers should work on build success or failure

• Triggering a system build from the outputs of a component build

• Receiving build notifications via RSS

There are other ways of implementing CruiseControl build publishers, but the preceding are the most common scenarios.

Automated Deployment

Figure 6.1 in Chapter 6 illustrated a CruiseControl environment containing a build server and an application or web server. An application or web server is typically required for development or integration testing, as discussed in the previous section for link testing. If this is the case, you need some way of publishing an application to this environment. A number of publishers could achieve this, depending on your exact requirements and how the application needs to be deployed. This section takes a closer look at the Ant publisher and FTP publisher.

Because Ant has been used as the basis for all the build definition activities, it makes sense to extend our use of it to deployment activities where possible. I will look in more detail at how to specify Ant targets for deployment in Chapter 11, "Release Packaging and Deployment." For now I will assume that the Ant build.xml contains a target called deploy, which deploys an application. To execute this target, an Ant publisher could be implemented as follows:

<publishers>     <antpublisher      antscript="${dir.javatools}\ant\bin\ant.bat"      antWorkingDir="${dir.ratlbankweb}"      buildfile="${dir.ratlbankweb}/build.xml"      target="deploy">         <property name="server" value="web-server"/>     </antpublisher> ... </publishers>

In this example you can see that the use of the Ant publisher is very similar to that of the Ant builder. In fact, it uses all the same attributes. The only difference is that a different targetdeployis being called. You will also notice the definition of a custom property called server that is passed to the Ant build.xml file. In this way you can reuse the deploy task to deploy to different servers. Here's an example of the deploy target in an Ant build.xml file:

<target name="deploy">     <deploy-task  hostname="${server}" .../> </target>

In this example, deploy-task is the specific deploy task that you want to execute, such as an Apache Tomcat or IBM WebSphere Application Server deployment task.

One of the most common deployment scenarios is making the results of the build available to an external development or test team, who could in fact be distributed anywhere in the world. They could then install the build for themselves as they see fit. This type of deployment can be achieved using the CruiseControl <ftppublisher>:

<plugin name="ftppublisher" classname="net.sourceforge.cruisecontrol.publishers. FTPPublisher"/> ... <publishers>     <ftppublisher srcDir="artifacts/RatlBankModel"      destDir="RatlBankModel" targetHost="ftp-server"      targetUser="ftpuser" targetPasswd="password"/> </publishers>

Unlike the majority of CruiseControl plug-ins, the <ftppublisher> plug-in is not registered by default, so this is what the first part of this example does. The second part is obviously the invocation of the <ftppublisher> itself. In this case it publishes (or FTPs) the contents of the artifacts directory, as specified by the srcDir attribute. This could be distribution .jar or .war files or whatever the final output of the build is. This means that the <artifactpublisher> must run before the <ftppublisher>. The remaining attributes specify the parameters to the FTP server at the remote site. In this case a directory is created under RatlBankModel based on the build's timestamp that contains the build outputs.

The Secure Approach

If there are concerns about the security of sending files via FTP, or if FTP is simply not allowed between locations, you should be able to use the <scp> plug-in instead. This plug-in securely copies and encrypts files between locations using the SSH protocol.

Many other useful publishers are available in CruiseControl. I encourage you to examine the CruiseControl documentation to find out more about them. Even if you don't find one that meets your exact requirements, the extensible plug-in nature of CruiseControl should make it easy to implement your own.

Publishing Criteria

You can wrap any publisher or set of publishers with <onsuccess> or <onfailure> elements. This allows you to initiate certain actions only if a build is successful or otherwise. For example, suppose that you wanted to deploy your build results only if the build was successful. You could change the <publishers> definition to the following:

<publishers>     <onsuccess>         <artifactspublisher          dir="C:\Views\RatlBankModel_bld\RatlBankModel\dist"          dest="artifacts/RatlBankModel"/>         <ftppublisher srcDir="artifacts/RatlBankModel"          destDir="RatlBankModel" targetHost="ftp-server"          targetUser="ftpuser" targetPasswd="password"/>     </onsuccess>     <onfailure>         ...     </onfailure> </publishers>

This example executes <artifactspublisher> and <ftppublisher> only when the build is successful. Typically, you would keep the <htmlemail> publishers outside the <onsuccess> or <onfailure> elements because this plug-in reconciles success or failure from the build log file. Another area where you could use this capability is with baselines. For example, you could use the <onsuccess> element to apply a baseline only if the build is successful. Alternatively, you could create a baseline before the build and then use the <onsuccess> element to promote the baseline (to BUILT) or the <onfailure> element to demote the baseline (to REJECTED).

Continuous Staging

If you have a number of subsystems or components that are built independently, you might want to trigger a system build of the cumulative outputs of these components automatically to generate your system build. This approach is typically called continuous staging (see [BerczukCS]) because an intermediate staging directory is used to store the build outputs from each component. One way to achieve this with CruiseControl is to use the <antpublisher> plug-in to publish the outputs of a component build to a monitored location:

<property name="dir.staging" value="C:\staging\libs"/> <project name="component1"> ...     <publishers>         <onsuccess>             <antpublisher              antscript="${dir.javatools}\ant\bin\ant.bat"              antWorkingDir="${dir.component1}"              buildfile="${dir.component1}/build.xml"              target="stage">                 <property name="dir.staging"                   value="${dir.staging}"/>         </onsuccess>     </publishers> </project> <project name="component2"> ...     <publishers>         <onsuccess>             <antpublisher              antscript="${dir.javatools}\ant\bin\ant.bat"              antWorkingDir="${dir.component2}"              buildfile="${dir.component2}/build.xml"              target="stage">                 <property name="dir.staging"                   value="${dir.staging}"/>         </onsuccess>     </publishers> </project>

In this example, the staging directory is defined in the property dir.staging as the file system location C:\staging\libs. To publish to this staging area, each component executes the Ant target called stage after a successful build. This target could simply copy the component's built objects, such as .jar files, to the staging directory:

<target name="stage">     <copy todir="${dir.staging}">         <fileset dir="${dir.dist}">             <include name="**/*.jar"/>         </fileset>     </copy> </target>

To monitor the staging directory and then trigger a system build automatically, you could use the CruiseControl <filesystem> plug-in. This is a <modificationset> plug-in that works in a way similar to the <clearcase> plug-in used in this and the preceding chapter. However, rather than monitoring a ClearCase branch for changes, it monitors a file system location:

<property name="dir.staging" value="C:\staging\libs"/> <project name="system-build">     ...     <modificationset>          <filesystem dir="${dir.staging}"/>     </modificationset>     <schedule>         <ant          antscript="${dir.javatools}\ant\bin\ant.bat"          antWorkingDir="${dir.system}"          buildfile="${dir.system}\build.xml"          target="integration"/>     </schedule>     ... </project>

In this example a system-build CruiseControl project is created. It has its own project directory structure and build scripts. It additionally and automatically builds against all the libraries from the different components as and when they are staged. This is a very agile approach to conducting a system build. Another way to implement continuous staging is to check in (or stage) a project's build outputs to a ClearCase repository and then configure the dependent CruiseControl project to monitor this staging area. I will discuss staging in detail in Chapter 10, "The Art of Releasing."

CruiseControl RSS Feed

RSS is a family of XML formats for syndicating information across the Internet. Rather confusingly, the abbreviation can refer to several standards or versions of RSS:

• Rich Site Summary (RSS 0.91)

• RDF Site Summary (RSS 0.9 and 1.0)

• Really Simple Syndication (RSS 2.0)

RSS is used to syndicate a wide variety of information, such as news feeds, weblogs, and product patches and updates. Basically, RSS allows you to subscribe to a Web site (that has an RSS feed) and then be automatically informed of updates. Usually these updates consist of one or two lines of basic text and a link back to the Web site for more details. The point with RSS is that you subscribe or choose what you want to be informed of, and nothing more.

As of CruiseControl 2.3, you can use RSS feeds to help with the communication and notification of build results across your projects. If you go to the CruiseControl Build Results web and then open the results for an individual build (as shown in Figure 7.5 earlier), you see an RSS button. If you click it, you see the content of the RSS feed, which would be similar to the following:

[View full width]
<?xml version="1.0" encoding="UTF-8" ?> <rss version="2.0"> <channel> <title>CruiseControl Results - RatlBankModel_int</title> <link>http://localhost:8080/cruisecontrol/buildresults/RatlBankModel_int </link> <description>Summary of the 10 most recent builds for this project. </description> <language>en-us</language> <item>     <title>Thu Jan 22 09:36:02 BST 2006, passed</title>     <description>Build passed</description>     <pubDate>Thu, 22 Jan 2006 09:36:02 +0100</pubDate>     <link>http://localhost:8080/cruisecontrol/buildresults /RatlBankModel_int?log=log20050922093602L4_INT</link> </item> <item>     <title>Sun Jan 18 14:49:52 BST 2006, passed</title>     <description>Build passed</description>     <pubDate>Sun, 18 Jan 2006 14:49:52 +0100</pubDate>     <link>http://localhost:8080/cruisecontrol/buildresults /RatlBankModel_int?log=log20050918144952L3_INT</link> </item> ... </channel> </rss>

As you can see, this output basically lists the results of each build (whether it passed or failed) and a link to the equivalent page in the Build Results web. To use this capability, you need to use an RSS aggregator tool, such as RSSReader (available from www.rssreader.com/). With any of these tools you can subscribe to an individual CruiseControl project by using a URL similar to the following:

http://localhost:8080/cruisecontrol/rss/RatlBankModel_int

This is also the URL behind the RSS button. Once you are subscribed to this feed, your aggregator tool checks the feed for changes on a regular basis and informs you if changes have occurred. RSSReader, for example, displays a pop-up window on your taskbar, as shown in Figure 7.9.

Figure 7.9. RSS build results pop-up

You can click this feed to find out more about the build and then eventually go directly to the Build Results web.

The advantage of RSS over e-mail is that you can choose what you want to be informed about. For example, if you only want to be informed of the status of two CruiseControl projects, you simply subscribe to just those two feeds. With CruiseControl e-mail notification, however, you need to decide the rules of who is to be informed and then add them to the config.xml file. There are also lots of ways that RSS can be integrated with existing systems. For example, you could integrate it into your existing project portal. In use, RSS is probably the better feature for getting an idea of the general build status of a collection of projects. E-mail notification is probably better at sending information directly to the developers and integrators when specific builds are broken.