Ant: The Definitive Guide, 2nd Edition

Scheduling Automatic Builds

It's time to add some automation to the build process. When you're working alone, you probably won't need to automate nightly builds, but as part of a team, it's a good idea. Larger projects typically have nightly builds posted to a web site, and using various automation tools and tasks like ftp, that's no problem. I'll take a look at various options here.

Unix

You can schedule recurring builds with Unix utilies like crontab, which you use to configure the cron daemon. For example, say you have a shell script that runs your nightly build, dobuild.sh, something like this:

export ANT_HOME=/usr/local/ant
export JAVA_HOME=/usr/local/jdk1.4
export PATH=${PATH}:${ANT_HOME}/bin
cd /home/work
ant -f nightlybuild.xml

You can schedule that build to happen at various times with crontab by starting its editing mode:

-bash-2.05b$ crontab -e

Edit the crontab file to include this line:

run at 00:01 every day 30 0 * * * $HOME/work/dobuild.sh

That makes your build run every night at 12:01 A.M. Easy enough.

Windows

The Windows at command schedules commands to run in Windows at specific times. For example, say you had a batch file, dobuild.bat, which runs your nightly build:

set ANT_HOME=C:\ant\apache-ant-1.6.1
set JAVA_HOME=C:\jdk1.4 
set PATH=%PATH%;%ANT_HOME%\bin
cd C:\work
call %ANT_HOME%\bin\ant.bat -f nightlybuild.xml

You can schedule that build for every night with the Windows at command:

C:\ant>at 00:01 /every:M,T,W,Th,F "C:\work\dobuild.bat"
Added a new job with job ID = 1

To list scheduled at jobs, enter at:

C:\ant>at
Status ID   Day                     Time          Command Line
-------------------------------------------------------------------------------
        1   Each M T W Th F         12:01 AM      C:\work\dobuild.bat

Tip

Want to get the results of your nightly build emailed to you? Use the Ant mail logger, covered earlier in this chapter.

The crontab and at commands are basic ways to get your builds to run automatically, but they're still basic. There are more advanced and powerful tools available.

Anthill

In my opinion, Anthill is the easist of the automatic build tools to use as well as the easiest to install. It's a software build management server that can handle most of your build needs, from individual up to the corporate. The web site is http://www.urbancode.com/default.jsp, and this is how Anthill describes itself:

Anthill ensures a controlled build process and promotes the sharing of knowledge within an organization. Anthill performs a checkout from the source repository of the latest version of a project before every build and tags the repository with a unique build number after every build. It supports many repository adapters including: Concurrent Version System (CVS), Visual Source Safe, Perforce, Clearcase, PVCS, StarTeam, MKSIntegrity and FileSystem. Anthill automatically updates a project intranet site with artifacts from the latest build.

Anthill comes in two versions: Anthill Pro (fairly expensive) and Anthill OS (free). To install Anthill, download the binary distribution you want and expand it. Copy anthill.war from the expanded dist directory to a Web server's application deployment directory, such as the webapps directory of a Tomcat server installation.

Anthill is designed to be used with a Web server that can execute Java code, like Tomcat, and you can get Tomcat free from http://jakarta.apache.org/tomcat/. (Anthill was developed and has only been tested using the Tomcat server, though it's supposed to work with any servlet container.)

Anthill gives you a servlet-based console, hosted by Tomcat or similar server, that lets you configure your automatic build process. Anthill is designed to check source code out of a code repository automatically and build that code.

For example, you can test your Anthill installation by logging into the Anthill CVS server to retrieve the code for a project named anthill-test, using the password "anthill-example":

%cvs -d :pserver:[e-mail]:/usr/local/anthill-test login
Logging in to :pserver:[e-mail]:2401:/usr/local/anthill-test
CVS password: ***************

In the same command-prompt session, start Tomcat and navigate to http://localhost:8080/anthill to open the Anthill console, as shown in Figure 4-1. This is the console that lets you schedule and configure your builds. Successfully built projects are marked with a green box in the right column of the console.

Figure 4-1. The Anthill build management server

Having logged into the Anthill CVS server, click the Build hyperlink in the top line of the table shown in Figure 4-1, which will build the CVS_Anthill example. This opens the Build Project page shown in Figure 4-2. Click the Force Build checkbox, enter a build version such as 1.1, and click the Build button.

Figure 4-2. Forcing a build

Anthill will download the code for this project from the Anthill CVS server and build it. The Anthill console page will reappear; click Refresh to verify that the project has been built. A green box should appear at right in the CVS Anthill-Example line in the console table, as shown in Figure 4-3, if the build was successful.

Figure 4-3. Running a new build

If you click the CVS_Anthill-Example hyperlink in the console now, you'll get access to the results of the build, as shown in Figure 4-4.

Figure 4-4. Build artifacts

The tests hyperlink links to the results of JUnit tests, and the buildLogs hyperlink links to the build log. Here's what the build log looks like:

all:

compile:
    [mkdir] Created dir: D:\anthill\work\Anthill-Example\build\temp
    [mkdir] Created dir: D:\anthill\work\Anthill-Example\build\temp\classes
    [javac] Compiling 1 source file to D:\anthill\work\Anthill-Example\build\temp\classes
     [copy] Copying 1 file to D:\anthill\work\Anthill-Example\build\temp\classes

jars:
      [jar] Building jar: D:\anthill\publishDir\CVS_Anthill-Example\Anthill-Example-1.1.jar

compile:

compile-tests:
    [mkdir] Created dir: D:\anthill\work\Anthill-Example\build\temp\tests\classes
    [javac] Compiling 1 source file to D:\anthill\work\Anthill-Example\build\temp\
tests\classes
      [jar] Building jar: D:\anthill\publishDir\CVS_Anthill-Example\
Anthill-Example-tests-1.1.jar

run-tests:
    [mkdir] Created dir: D:\anthill\work\Anthill-Example\build\temp\tests\data
    [mkdir] Created dir: D:\anthill\publishDir\CVS_Anthill-Example\tests
    [junit] Running example.WidgetTestCase
    [junit] Tests run: 2, Failures: 0, Errors: 0, Time elapsed: 0.651 sec
    [junit] Testsuite: example.WidgetTestCase
    [junit] Tests run: 2, Failures: 0, Errors: 0, Time elapsed: 0.651 sec

[junitreport] Using Xalan version: Xalan Java 2.2.D11
[junitreport] Transform time: 1051ms

doc:

javadoc:
    [mkdir] Created dir: D:\anthill\publishDir\CVS_Anthill-Example\api
  [javadoc] Generating Javadoc
  [javadoc] Javadoc execution
  [javadoc] Loading source files for package example...
  [javadoc] Constructing Javadoc information...
  [javadoc] Standard Doclet version 1.4.0

  [javadoc] Building tree for all the packages and classes...
  [javadoc] Building index for all the packages and classes...
  [javadoc] D:\anthill\work\Anthill-Example\source\java\example\Widget.java:12: 
warning - @author tag has no arguments.
  [javadoc] Building index for all classes...
  [javadoc] Generating D:\anthill\publishDir\CVS_Anthill-Example\api\stylesheet.css...
  [javadoc] 1 warning
        .
        .
        .
clean:
   [delete] Deleting directory D:\anthill\work\Anthill-Example\build\temp

BUILD SUCCESSFUL
Total time: 15 seconds

You schedule builds from the console page, http://localhost:8080/anthill/, if you're using Tomcat. Click Create New Schedule in the Schedule box, configure the new schedule as shown in Figure 4-5, and click Update to update the scheduler.

Figure 4-5. Setting up a schedule

All in all, Anthill is a great automated build tooleasy to set up, easy to use.

Cruise Control and Gump

Cruise Control and Gump are two other Ant automated build tools for use with Ant. You can get Cruise Control at http://cruisecontrol.sourceforge.net/. It's an extensive build management tool, but it takes some effort to install. To configure a build, you work with a modification set. Cruise Control supports an Ant task named modificationset that contains nested tasks you can use to configure your build.

After setting up the build as you want it, you start the Cruise Control runner using .sh and .bat scripts, depending on your operating system, and Cruise Control takes it from there.

An alternative automated build tool is Gump. You can get Gump from the Jakarta CVS repository, using the password anoncvs:

%cvs -d :pserver:[e-mail]:home/cvspublic login
Logging in to pserver:[e-mail]:home/cvspublic
CVS password: *******

%cvs -d :pserver:[e-mail]:home/cvspublic checkuot jakarta-alexandria

You can read all about Gump and how it works at http://gump.apache.org/. Using Gump, project definitions are converted from XML to scripts native to the platform on which you are running. These scripts execute CVS or SVN update commands for every module which contains a project being built, and then builds each of those projects.