Performing unattended daily builds with WebSphere Studio and Ant -- Part 3

The third of three articles on build automation in WebSphere Studio, this article shows you how to set up unattended builds when using WebSphere Studio V5 with ClearCase as the repository. A sample WebSphere Studio project is included along with Ant scripts and wrapper code to run the build from the command line. The article explains how to download and install a WebSphere Studio plug-in that extends the headless Ant capabilities to support importing a project to a workspace. The article also includes a downloadable build.xml file and related files that are needed for the automated build process. After reading this article, you will be able to set up an automated, centralized, unattended build process for a development shop that uses WebSphere Studio as the primary tool for project development.

David Leigh (dleigh@us.ibm.com), Solution Test Architect, IBM

David Leigh is an Advisory Software Engineer in the IBM Software Group's System House organization, located in Research Triangle Park, North Carolina. His areas of expertise include process choreography, application and server security, high availability, monitoring, IBM AIX, and Linux. You can reach David at dleigh@us.ibm.com.



Mark Wainwright (markwain@us.ibm.com), Solution Test Architect, IBM

Mark Wainwright is a Senior Software Engineer also in the IBM Software Group's System House organization. He designs large-scale software solutions both to demonstrate IBM middleware integration, and to identify integration problems for IBM development teams to solve. He has a wife and two children, with whom he takes having fun very seriously. You can reach Mark at markwain@us.ibm.com.



01 April 2004

Introduction

Part 1 of this series explains the motivation and objectives of build automation, and describes the overall approach. Part 2 describes how you can implement this approach using Application Developer V4 with CVS as the code repository. This article, Part 3, shows how to set up automated builds using IBM ® WebSphere® Studio Application Developer V5 (hereafter called Application Developer), with IBM Rational® ClearCase as the software configuration management (SCM) system. While this article applies to ClearCase, the procedures and scripts described below can be used with CVS and other SCMs with relatively minor changes.

Here is a brief overview of the approach described in this article series:

  1. Developers work on projects in an Application Developer workspace, where they create code, make changes, and unit test. When satisfied with their code, developers copy their projects into the SCM.
  2. Builders add the names of any newly created projects to the list of projects to be included in the build.
  3. The automation process periodically runs and performs the following tasks within a single, batch-mode (headless) Application Developer Ant session:
    1. Extracts all projects to be included in the build from the SCM to a local directory
    2. Creates a new Application Developer workspace
    3. Imports each project into the new workspace
    4. Builds each project in turn
    5. Writes any build-time errors to a log output file
    6. Exports the executables to an appropriate location. This can be an FTP site or a mounted file system

Application Developer V5 includes the Ant tasks needed to do sub-steps 1-6 above, with the exception of steps 3 and 6. To import projects into a workspace and export them via FTP, you must extend Application Developer using the plug-ins provided with this article. The ImportProject plug-in provides a new Ant task, ImportProject, and it enables an Ant session to import projects in a workspace just as selecting File => Import => Existing Project Into Workspace does in the user interface. The CommonsNet plug-in contains the Apache Jakarta project Commons/Net internet protocol suite Java™ library, packaged as a WebSphere Studio plug-in archive. The CommonsNet plug-in makes it possible to FTP files from within an Ant session. The remaining Ant tasks in the build process use the antextras package, which is included in Application Developer V5, and described in detail in the article series Using Ant with WebSphere Studio Application Developer.


Setting up the build machine

Setting up the machine used to run automated builds (the build machine) involves the following steps:

  1. Install Application Developer.
  2. Install the IBM Rational ClearCase client.
  3. Install the ImportProject plug-in.
  4. Install the NetComponents plug-in and JAR file (only if using FTP).
  5. Set up the build script files.
  6. Create a ClearCase view containing the projects to be built.

These steps are described in detail below.

Installing Application Developer

The build machine must have Application Developer installed on it. If the application to be built relies on the Programming Model Extensions in WebSphere Studio Application Developer Integration Edition, then the build machine should instead have Integration Edition installed. Rational ClearCase LT client is packaged with Application Developer, and can be installed when Application Developer is installed. You must configure Rational ClearCase client to point to the ClearCase server, which you can do during ClearCase client installation. This approach works on a build machine running either Windows® or Linux; this article assumes that the build machine is running Windows.

Installing the ImportProject plug-in

To install the plug-in that enables the ImportProject Ant task, download the ImportProject.zip file and unzip it in the <WSAD_HOME>/wstools directory, where WSAD_HOME is the root directory where Application Developer is installed.

Installing the NetComponents Plug-in and JAR

To copy the results of the build to the appropriate destination via FTP, you must install the NetComponents Java library, which is a documented library dependency to the Ant ftp task. The version of Ant that comes with Application Developer V5 is Ant V1.5.3, which requires the NetCompnents.jar library. The latest version of Ant, V1.6.0, on the other hand, requires the commons-net.jar library. To install the NetComponents library:

  1. Download NetComponentsPlugin-1.3.8.zip and unzip the archive in the <WSAD_HOME>/wstools directory. This will create the directory for the library file (<WSAD_HOME>/wstools/eclipse/plugins/com.oroinc.net_1.3.8), and the necessary plug-in.xml. Because of licensing restrictions, you need to download the actual library JAR file separately.
  2. Download NetComponents-1.3.8.zip from http://www.savarese.org/oro/. Copy NetComponents.jar from this archive into <WSAD_HOME>/wstools/eclipse/plugins/com.oroinc.net_1.3.8.

Setting up the build script files

The next step is to extract the build script files from buildscripts.zip into a directory (such as C:\Automation) on the build machine. There are five files in this archive:

FilenameDescription
build.batThe main executable that sets up the build environment and invokes Application Developer in headless mode.
build.xmlThe main Ant build file. Edit this file and add the names of each project that should be built.
fullbuild.batA wrapper script for build.bat that is useful for running automated builds as a scheduled task.
ProjectBuild.xmlAn Ant build file containing the targets used to build Application Developer projects.
setupBuild.batA configuration file containing variables used to set up the build environment.

You must set several variables in the setupBuild.bat file to match your environment:

Set the WSAD_HOME variable to the root directory where Application Developer is installed:

rem WSAD 5.0 installation directory - use back slashes
SET WSAD_HOME=C:\PROGRA~1\IBM\WSAD

Set the CLEARCASE_HOME directory to the bin directory of the Rational ClearCase installation:

rem ClearCase base directory (usually \PROGRA~1\Rational\CLEARC~1\bin)
rem use back slashes
SET CLEARCASE_HOME=C:\PROGRA~1\Rational\CLEARC~1\bin

Set the AUTOMATION_HOME variable to the directory where the buildscripts.zip archive was extracted:

rem Root directory of the automation scripts and workspaces 
rem (usually C:\Automation) 
rem use back slashes
SET AUTOMATION_HOME=C:\Automation

Set the FTP_SERVER and FTP_PORT variables to the hostname and port of the FTP server to which the results of the build will be copied:

rem FTP server
SET FTP_SERVER=myftpserver
rem FTP port (default port is 21)
SET FTP_PORT=21

The FTP_USER and FTP_PASSWORD variables are used to authenticate to the FTP server:

rem FTP user ID
SET FTP_USER=build
rem FTP password
rem If you "rem" out the following line, you will be prompted to enter
rem the password.
rem This means that you will not be able to run truly unattended build.
SET FTP_PASSWORD=buildpass

The FTP_REMOTEDIR variable is the location on the FTP server where the build results will be copied:

rem Directory on FTP server to upload the newly built files
rem use forward slashes
SET FTP_REMOTEDIR=/dailybuilds/%CLEARCASE_VOB%

Creating a ClearCase view

The last step in setting up the build machine is to create a suitable ClearCase view to the Versioned Object Base (VOB) containing the projects to be built. Name this view <CC_VOB>_view, where CC_VOB is the name of the ClearCase VOB. It should be located in the AUTOMATION_HOME directory. For example, if the name of the VOB is projectVOB and the AUTOMATION_HOME directory is C:\Automation, then name the view projectVOB_view, and put it in C:\Automation\projectVOB_view.


Running a build

Before running a build, edit build.xml and add an Ant task to the buildAll target for each project to be built. The format of these tasks is shown in the example below -- the three projects to be built are named projectEAR, projectEJB, and projectWEB.

<target name="buildAll" depends="init">
    <ant antfile="ProjectBuild.xml"><property name="project.name" value="projectEAR"/></ant>
    <ant antfile="ProjectBuild.xml"><property name="project.name" value="projectEJB"/></ant>
    <ant antfile="ProjectBuild.xml"><property name="project.name" value="projectWEB"/></ant>
</target>

Important: Keep this list up-to-date as projects are added to the VOB. If there is no task for a project, it will not be included in the build.

To run a build from the command line, open a command prompt, navigate to the AUTOMATION_HOME\buildscripts directory and run build.bat, specifying the ClearCase VOB you want to build and the Ant targets you want to invoke:

C:\buildscripts> build <CLEARCASE_VOB> [ <Ant target> ] ...

For example, the following statement will build all of the projects listed in build.xml:

C:\buildscripts> build cc_build_view buildAll

If you don't specify any Ant targets, you will be presented with a list describing all of the available targets:

Click to see code listing

Available targets:
    
      init        - displays the currently set variables and displays this help message
      extractCode - extracts the contents of clearcase.vob into the workspace.dir 
                    (${workspace.dir}) directory.
      buildAll    - builds each of the projects.  This target will run build.xml (using the default target) 
                    in each of the project directories.  In turn, these ant scripts should do whatever 
                    compiling is necessary as well as package any needed artifacts (EAR, WAR, RAR, JAR
                    files etc...) to the ftp.localdir (${output.dir}) directory.
      ftpAll      - FTPs the packaged files to the ftp.server (${ftp.server}) FTP site.
      
    To run a full build:
    
      C:\Automation\buildscripts> build init extractCode buildAll ftpAll

To set up a Windows machine to automatically run a scheduled build without manual intervention, you must add a scheduled task that cleans up any previous builds and invokes a new build with the correct parameters. From the Windows Start menu, select Programs => Accessories => System Tools => Scheduled Tasks. Then select File => New and enter a sensible name such as Automated daily build. Double-click the new task and complete the fields as shown below:

Run:;C:\Automation\buildscripts\fullbuild.bat <CLEARCASE_VOB>
Start in:;C:\Automation\buildscripts

The values above assume that AUTOMATION_HOME = C:\Automation. The fullbuild.bat executable is a simple wrapper around build.bat. It removes old build data from the AUTOMATION_HOME\dailybuilds directory and calls build.bat, specifying the init, extractCode, buildAll, and ftpAll targets. From the Schedule tab, set the task to run when you want and click OK. The build should now run automatically as scheduled. Log data will be written to AUTOMATION_HOME\dailybuilds\CLEARCASE_VOB\TODAYS_DATE, as specified in the setupBuild.bat file.


Conclusion

This simple approach to build automation has proved successful on a number of development projects. The build process imports and builds Application Developer workspace projects just as developers do, and the resulting build artifacts are accurate, reliable, and repeatable.


Acknowledgements

The authors would like to thank Jim Thorpe, the author of the ImportProject Ant task, for his help in making automated builds a possibility.


Downloads

DescriptionNameSize
Code samplebuildscripts.zip  ( HTTP | FTP )6 KB
Code sampleImportProject.zip  ( HTTP | FTP )23 KB
Code sampleNetComponentsPlugin-1.3.8.zip  ( HTTP | FTP )1 KB

Resources

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere
ArticleID=13663
ArticleTitle=Performing unattended daily builds with WebSphere Studio and Ant -- Part 3
publish-date=04012004