A guide to the Rational build utility

Perform automated headless builds of your application in Rational Application Developer

The build utility feature is a scriptable tool that you can use to automate builds of projects that you create with IBM® Rational® Application Developer. It is a subset of Rational Application Developer and available by default within the product. This article serves as an introductory guide to the tool, complete with a tutorial to help you get started.


Mattia Parigiani (parigian@mx1.ibm.com), Rational Build Utility Team Lead and Engineer, IBM

author photoMattia Parigiani is the team lead for the Rational build utility feature and main developer, based in Guadalajara, Mexico. He started on this role with IBM back in December 2009 initially as the headless Ant component owner.

06 September 2011

Also available in Russian

Headless Ant builds in Rational Application Developer

Headless Ant builds provides a scriptable way of automating production builds of Eclipse based workspaces. These types of builds are performed from a command line, and are faster and more resource efficient.

The headless build feature in Rational Application Developer is based on Apache Ant. Supported by the Eclipse platform, it enables you to perform headless builds (compiling and packaging) of applications that you create in Rational Application Developer. Different versions of Apache Ant are supported in the following versions of Rational Application Developer:

  • Apache Ant 1.7.1 for Rational Application Developer 8.0.x
  • Apache Ant 1.7.0 for Rational Application Developer 7.5.x
  • Apache Ant 1.6.5 for Rational Application Developer 7.0.0.x

The application developer tool provides a series of Ant tasks that you can use in headless mode through the build utility. They are similar to common operations performed by developers in an Eclipse workbench.

Headless build results are consistent with Rational Application Developer (Eclipse) build systems. By using the build utility, you can ensure that jobs you would normally run in the Rational Application Developer graphical interface are also run, such as indexing jobs or ensuring that various validators are configured with the projects.

The Rational build utility

The Rational build utility feature (the build utility) can be run exclusively from the command line. The Build Utility is the Rational Application Developer's headless build feature made into a stand-alone tool. You can install it through IBM Installation Manager on both Windows and Linux. See the documentation in the product information center for how to get and install the Rational Build Utility. A separate offering is also available for the IBM System z® platform; see Rational Build Utility z/OS offering documentation.

The code base for the build utility and the Rational Application Developer headless Ant builds are the same. Each Ant task contributed by the build utility can be directly mapped to a specific action or function in the application development workbench.

Running headless builds

To run a headless build of a Rational Application Developer workspace, you must have the following items available:

  • The workspace
  • An Ant build script that defines the build, such as build.xml
  • Either Rational Application Developer or the build utility installed on your build machine

You typically run headless builds from either a UNIX terminal or a Windows command prompt. The input is a single Eclipse workspace that contains projects and applications. The output depends on the type of work performed by the Ant build script, but it usually includes a compilation of the Eclipse workspace projects and the export files and packages of your applications.

A headless build is based on a single workspace and a new directory can usually be created to serve as the 'headless workspace'. It is also fundamental to have a workspace environment variable set up to point to the workspace directory before the headless build can run without errors.

Builds typically follow three distinct steps:

  1. Import projects
  2. Build projects
  3. Export application artifacts (EAR, WAR, JAR, SCA and OSGi archives for example)

Note that importing projects from the application development tool can either happen from a source control management system or directly from the local file system. The general scenario is to create projects in the application development tool, check them in to a source control system, and then use the build utility to import from the source control system for the headless build to proceed. For the introductory purposes of this article, we only cover how to import projects from a local file system.

The build script

You typically create the XML build script on your own. The script contains a combination of standard Apache Ant tasks as well as Ant tasks provided by Rational Application Developer. You can create the script in Rational Application Developer or your preferred editor.

The build utility includes the following Ant tasks for importing projects into a workspace, compiling projects, exporting build results as Java archives like WARs and EARs and many more:

  • projectImport - imports a project from the local file system
  • projectBuild - builds (compiles) a single project
  • workspaceBuild - performs a full build of the workspace
  • exportEAR - exports the project as an EAR file

For a detailed list of the Ant tasks as of version 8.0 see the product documentation. For more information about how to run the build utility see its documentation.

Integrate with Websphere Application Server, source control management systems, and more

As previously mentioned, a headless build can potentially import projects from any source control system. At the time of this writing, CVS is currently supported even though it is possible to extend this functionality in general to any other source control system. A possible workaround is to use the projectImporttask to import Eclipse projects from the local file system that you have checked out from a source control system.

You can integrate the build utility with IBM® WebSphere® Application Server. By default, the build utility packages the stub runtimes for different WebSphere Application Server versions, depending on the product version. The current version of the build utility is 8.0.3 and it provides the stubs for versions 6.0, 6.1, 7.0 and 8.0. The build utility and Rational Application Developer headless Ant builds can target the WebSphere Application Server stubs that come with it. The builds use a specific application server stub or runtime for compilation. Moreover, the build uses whatever runtime the projects created by the user in Rational Application Developer are pointing to, whether it is a stub runtime, a real application server runtime, or even a WebSphere test environment in the case of Rational Application Developer.

A third case that you can pursue is to include external libraries in a headless builds. For example, use ant-contrib.jar. This library provides you with a set of useful Ant tasks and XML control structures that you can use in the build script. For more information about this library, see the ant-contrib documentation.

New features in the build utility

You can install this version of the build utility through IBM Installation Manager on both the Linux and Windows platforms. The IBM System z offering still remains a compressed file format.

As of Rational Application Developer v8 (Headless Ant and the build utility), the Ant build tool includes numerous extra features and Ant tasks. The premier feature is support for building user projects that are targeted for a Websphere Application Server v8 runtime.

A series of new Ant tasks have also been included in the various v8.0.x fix pack releases. Some of the tasks were added to support importing, exporting, and compiling new artifact types in Rational Application Developer v8.0:

  • scaArchiveExport. This task allows SCA projects to be exported.
  • OSGi Enterprise tooling Ant tasks. A series of Ant tasks created to import, export and convert OSGi Enterprise artifacts.
  • prepareForDeploy. Just like in the workbench, this task will generate and compile the deployment code necessary for your application to run on a WebSphere Application Server.
  • xmlCatalog. The task allows modification of the XML Catalog used by the product for a given workspace. The same operation may be performed within RAD via the workspace preferences. For more information, see the documentation.
  • disableIndexer. This task allows disabling workspace indexers which usually make sense mainly in a graphical (UI) environment. Using this task should improve the performance of headless builds.
  • Server Control Ant tasks. A series of tasks that allow handling workspace server runtimes: creating a server, starting/stopping a server, publishing to a server.

A scenario for using the build utility

In this section, we will work through a sample scenario for using the build utility. It shows how you can use the utility to perform a headless build of an application that was created in Rational Application Developer. The SimpleCalculator application consists of a series of projects from Rational Application Developer that implement a simple mathematical calculator. There is an EAR project made up of an EJB module, an application client module and a web module.

The Ant script used to perform the headless build of the sample workspace will be examined (see the demoBuild.xml file), together with the output expected from its run by using the build utility (the expected output is also provided in the output.log file). The most significant part of this scenario is the example of how single Rational Application Developer Ant tasks in the build script can directly be mapped to functions inside the workbench. To see the sample and the files contained in it, get the DemoBuild.zip archive found at the end of this article.

Assuming that Windows is used to run the headless build of the sample, the following actions must be performed:

  1. Extract the sample files to a temporary location (use C:\DemoBuild)
  2. Open a command prompt and type: cd RBU_HOME\bin (where RBU_HOME is the directory where the build utility is installed)
  3. Set the workspace: set workspace= C:\DemoBuild
  4. Run the headless build: runAnt.bat –f C:\DemoBuild\demoBuild.xml)

Then we must review the build script to understand what actions the headless build performs. See the demoBuild.xml file in the sample. Each of the following sections focuses on a particular Ant task from Rational Application Developer and used to perform one, or more, specific workbench operations:

  • Initialize the workspace
  • Import the projects into the workspace
  • Build the projects
  • Prepare the application server deployment code
  • Export different types of artifacts
  • Create a workspace server
  • Start the server and add projects to it
  • Remove projects from the server
  • Stop and delete the the server

Initialize the workspace

The following createWSRuntime Ant task is the first one run by the sample script:

<createWSRuntime targetId="was.v7.runtime"
typeId="com.ibm.ws.ast.st.runtime.v70" />

The task creates a workspace runtime environment of a type specified by the mandatory typeId attribute. The path attribute is also a mandatory one. You must specify the location on the file system where the installation directory for the runtime environment is located. Finally, the targetId attribute represents the ID that is assigned to the new runtime and can later be used when creating a new workspace server with the createWSServer Ant task. The targetId attribute is optional. If a value is not provided, a default value will be set. The following related output is from the task:

[createWSRuntime] Creating a new server runtime.
[createWSRuntime] ... subtask: Saving WebSphere Application Server v7.0
[createWSRuntime] Done creating a new server runtime.

You can get a list of available runtimes that are created by the createWSRuntime task from the listRuntimeTypes Ant task. For more information, see the related documentation.

You can create a server runtime in the workbench through the Rational Application Developer preferences window. Select Windows > Preferences > Server > Runtime Environments and use the wizard to add a new runtime environment.

Figure 1. Create a new server runtime
Create new server runtime from the preferences window

Import the projects into the workspace

The following calls of the projectImport Ant task are responsible for importing the different projects from the sample workspace into the build utility workspace:

<projectImport projectName="SimpleCalculatorEJB21"
projectlocation="${basedir}/SimpleCalculatorEJB21" />
<projectImport projectName="SimpleCalculatorEJB21Client"
projectlocation="${basedir}/SimpleCalculatorEJB21Client" />
<projectImport projectName="SimpleCalculatorEJB21Web"
<projectImport projectName="SimpleCalculatorEJB21EAR"

If you were to do this same task in the graphical interface, you would select File > Import > General > Existing Project.

Figure 2. Import projects into the workspace
Window for importing projects in a workspace

Each task call receives the two attribute parameters projectName and projectLocation. Only the first parameter is required. It specifies the name of the project to be imported. If a location is not specified, the default location<workspace>/<projectName>is used. If a location is specified, the project is imported from that location.

The following output represents the first invocation of the projectImport task in this sample:

[projectImport] projectName=SimpleCalculatorEJB21
[projectImport] importing projectLocation=SimpleCalculatorEJB21
[projectImport] (Begin)
[projectImport] project.create
[projectImport] project.open
[projectImport] ... subtask: Opening 'SimpleCalculatorEJB21'. Opening 
[projectImport] ... subtask: Opening 'SimpleCalculatorEJB21'. Refreshing
[projectImport] (Done)

Moreover, the import task ensures that extra operations, such as those that would normally run in the workbench after the import of a project are also run in headless mode.

Build the projects

Let's now take a look at the build operations. Here a single task is used, which performs the full workspace build.

<workspaceBuild buildtype="full"/>

The previous call compiles the whole sample workspace to produce the following output:

[workspaceBuild] WorkspaceBuild (Begin)
[workspaceBuild] (Begin)
[workspaceBuild] ... subtask: Invoking 'Java Builder' on '/SimpleCalculatorEJB21Client'.
[workspaceBuild] ... subtask: Preparing to build SimpleCalculatorEJB21Client
[workspaceBuild] ... subtask: Cleaning output folder for SimpleCalculatorEJB21Client 
[workspaceBuild] ... subtask: Copying resources to the output folder 
[workspaceBuild] ... subtask: Cleaning output folder for SimpleCalculatorEJB21Client 
[workspaceBuild] ... subtask: Copying resources to the output folder 
[workspaceBuild] ... subtask: Analyzing sources 
[workspaceBuild] ... subtask: Compiling 
[workspaceBuild] ... subtask: 
Compiling SimpleCalculatorEJB21Client/ejbModule/org/omg/stub/java/lang 
[workspaceBuild] ... subtask: Compiling SimpleCalculatorEJB21Client/ejbModule/ejbs 
[workspaceBuild] ... subtask: Compiling

This call is only part of the generated headless output. You can see all of the headless build output of the sample in the provided output.log file.

The workspaceBuild Ant task has the same effect as selecting Project > Build All from inside the workbench.

Figure 3. Performing a full workspace build from within the workbench
Build the full workspace from the workbench

Building the whole workspace ensures the other required post build operations are also performed. These operations might include running workspace validators or indexers, as well as executing external tool builders that are configured within the projects. Some validation is run during the headless build of the simple calculator workspace, which is displayed in the following output:

[workspaceBuild] ... subtask: Invoking 'Faceted Project Validation Builder' on 
[workspaceBuild] ... subtask: Invoking 'Validation' on '/SimpleCalculatorEJB21Client'.

Prepare application server deployment code

The prepForDeploy task generates the application server deployment code of the project that is specified by the projectNameattribute. In the simple calculator sample, the task is invoked in correspondence to the EAR project. This action is generally required for EJB v2.x artifacts and for Web services deployment code. More modern artifacts will not require prepForDeploy to be invoked as the Websphere application server will generate their deployment code automatically. The same result can be obtained in the workbench by right clicking on the SimpleCalculatorEJB21EAR project and selecting the Java EE > Prepare for Deployment option.

Figure 4. Preparing for deployment in the workbench
Prepare for deploy invoked on EAR project

Export Different types of artifacts

In the following example, there are three different export tasks that are being invoked: earExport, ejbExport and warExport. All three use a similar syntax, but the difference is the name of certain key attributes of the task. The generic "projectName" and "exportFile" attributes (earProjectName and earExportFile in the case of the earExport task for example) are the only two required attributes. They specify respectively the name of the project to export and which file the exported artifacts should be saved to.

<earExport EARProjectName="SimpleCalculatorEJB21EAR" 
EARExportFile="${basedir}/simpleCalculatorEJB21EAR.ear" overwrite="true" /> 
<ejbExport ejbprojectname="SimpleCalculatorEJB21" 
ejbexportfile="${basedir}/simpleCalculatorEJB21.jar" overwrite="true" /> 
<warExport warprojectname="SimpleCalculatorEJB21Web" 
warexportfile="${basedir}/simpleCalculatorEJB21Web.war" overwrite="true" />

Note that we use the overwrite attribute. Since the value is set to "true" the operation ensures that any previously created EAR, JAR or WAR files are overwritten. The following output is a sample of the earExport tasks:

[earExport] Exporting project: SimpleCalculatorEJB21EAR (Begin)
[earExport] (Begin) 
[earExport] ... subtask: Exporting archive 'simpleCalculatorEJB21EAR.ear'. Refreshing 
[earExport] (Done) 
[earExport] EARExport completed to C:\ArticleSample2/simpleCalculatorEJB21EAR.ear

You can perform this same task in the workbench by right-clicking on the project and selecting the corresponding export action. For example, Export > EAR file:

Figure 5. Exporting an EAR file in the workbench
Export ear file in the product

Create a workspace Server

The following sample task creates a WebSphere Application Server v7 workspace based on the runtime which was created earlier on in the headless build by the createWSRuntime task and specified by the required attribute runtimeId of the workspace server creation task.

<createWSServer targetId="was7server" typeId="com.ibm.ws.ast.st.v7.server.base" 
runtimeId ="was.base.v7" />

The other required attribute is targetId, which is later used by the other contributed server control Ant tasks in order to use the server; start it up, add and remove projects to it, perform a publishing operation.

Finally, the typeIdattribute is an optional one. If it is not specified, the value defaults to the server name itself. You can get a list of all workspace servers that can be created by using the listServerTypes Ant task (see the related documentation).

When createWSServer is run it generates the following output:

[createWSServer] Creating a new server instance. 
[createWSServer] ... subtask: Saving WebSphere Application Server v7.0 @ localhost 
[createWSServer] Initializing the server... (Begin) 
[createWSServer] CWPKI0308I: Adding signer alias "CN=, OU=Root Certi" to 
[createWSServer] keystore "null" with the following SHA digest:
[createWSServer] 59:6B:52:1D:8E:94:38:65:25:BF:D4:2B:F9:B8:4F:CC:06:77:0D:C5 
[createWSServer] Initializing the server... (Done) 
[createWSServer] Done creating a new server instance.

Creating a server in the workbench can be done from the Servers view. Click anywhere in the blank part of the view and select New > Server.

Figure 6. Creating a new server in the workbench
Creating a new server in the workbench

The wizard for creating a server is simple. Select the appropriate runtime that is required for the server. Just like in the Ant task (attribute runtimeId), you must provide the specific runtime in order to create the server instance.

Figure 7. Create a new server in the workbench
Wizard for creating a workspace server

Start the server and add projects to it

You can start the server from the Servers view in the workbench. Right-click on the server entry itself and select Start.

Figure 8. Start a server from the workbench
Start the server from the Server view

To start the server in headless mode, use the serverId that was previously assigned to the newly create workspace server by the createWSServer Ant task.

<startWSServer serverId="was7server" />

The headless build runs for a while before it displays the following message:

[startWSServer] Synchronously starting the server instance 'WebSphere Application 
Server v7.0 @ localhost'.

When the server has started, the headless build produces the following message:

[startWSServer] Done starting the server.

In the workbench, the Console view opens with information about the server startup status. The same status is not displayed after the headless build.

You can add applications from the local workspace into a workspace application server in the "Add and Remove" window. Access this window from the Servers view by right-clicking on a specific server and choosing Add and Remove:

Figure 9. The Add and Remove window
window to add/remove projects to workspace server

In a headless environment, you can do this same task by using the addToWSServer Ant task:

<addToWSServer serverId="was7server"> 
<resource name="SimpleCalculatorEJB21EAR" type="ear"/> 

Notice the inner resource element. In this task, you can add several resources to the workspace server at one time, without having to run the addToWSServer task multiple times.

When you add the SimpleCalculatorEJB21EAR project to the server and click Finish in the Add and Remove window, the project is added to the server and automatically published. This latter operation is run in headless mode by the publishToWSServer Ant task:

<publishToWSServer serverId="was7server" type="incremental" />

The following output is for these two operations in the headless build tool:

[addToWSServer] Adding the following resources to the server: 
[addToWSServer] ... subtask: Adding and/or removing resources. 
[addToWSServer] ... subtask: Saving WebSphere Application Server v7.0 @ localhost 
[addToWSServer] Done adding the application(s) to the server. 
[publishToWSServer] The server 'WebSphere Application Server v7.0 @ localhost' is not 
started. Attempting to start it in 'run' mode. 
[publishToWSServer] Synchronously starting the server instance 'WebSphere Application 
Server v7.0 @ localhost'. 
[publishToWSServer] Done starting the server. 
[publishToWSServer] Synchronously publishing to the server instance 'WebSphere 
Application Server v7.0 @ localhost' (type: incremental) 
[publishToWSServer] (Begin) 
[publishToWSServer] ... subtask: Preparing launch delegate... 
[publishToWSServer] ... subtask: Performing pre-launch check... 
[publishToWSServer] ... subtask: Building prerequisite project list
[publishToWSServer] ... subtask: Performing final launch validation... 
[publishToWSServer] ... subtask: Initializing source locator... 
[publishToWSServer] (Done) 
[publishToWSServer] The publishing action may have failed due to the following reason: 
Source locator does not exist: com.ibm.debug.wsa.WSASourceLookupDirector 
[publishToWSServer] Done publishing to the server instance 'WebSphere Application 
Server v7.0 @ localhost'.

Remove projects from the server

You can remove an application from the workspace server with the removeFromWSServer Ant task. Do this in the Add and Remove window for the server. Alternatively, the user can expand the server entry in the Servers view to see the resources that were added to it. Remove the resource by right-clicking on it and selecting Remove.

Figure 10. Remove projects from a server in the workbench
removing a project from the server in the product

The call to the corresponding Ant task and its output is:

<removeFromWSServer serverId="was7server"> 
    <resource name="SimpleCalculatorEJB21EAR" type="ear"/> 

[removeFromWSServer] Removing the following resources from the server: 
[removeFromWSServer] ... subtask: Adding and/or removing resources. 
[removeFromWSServer] ... subtask: Saving WebSphere Application Server v7.0 @ localhost 
[removeFromWSServer] Done removing the application(s) from the server.

Just like in the addToWSServer task, multiple resources may be removed at one time from the workspace server by using multiple resource entries inside a single removeFromWSServer task invocation.

Stop and delete the server

The following output is produced when the stopWSServer and deleteWSServer are called:

[stopWSServer] Synchronously stopping the server instance 'WebSphere Application 
Server v7.0 @ localhost'. 
[stopWSServer] Done stopping the server. 

[deleteWSServer] Deleting the server instance 'WebSphere Application Server v7.0 
@ localhost'. 
[deleteWSServer] Done deleting the server instance 'WebSphere Application Server 
v7.0 @ localhost'.

Then the following Ant tasks stop and delete the server:

<stopWSServer serverId="was7server" /> 
<deleteWSServer serverId="was7server" />

To perform this same task in the workbench, select the server in the Servers view and click Stop.

Figure 11. Stop a server in the workbench
stop a running server from the Server view

You can delete the server by right-clicking on the server in the Servers view and selecting Delete.

Figure 12. Delete a server in the workbench
delete a workspace server in the product

Error Handling

Most Ant tasks in Rational Application Developer provide the failOnError attribute. Use this attribute to decide what to do in cases where errors occur during a headless build. The value of the attribute can either be "false" or "true" with the default value being "true" in most cases and when the attribute is not specified. The effect of having the failOnError attribute set to "true" is that the headless build will exit immediately as soon as an error is found. On the contrary, if the attribute is set to "false" the build will continue running through the script beyond the point where an error was found and ignore the errors.

The build utility also provides some other error detection Ant tasks for build operations. These are the workspaceGetErrors and the projectGetErrors tasks. They are respectively subsets of the workspaceBuild and projectBuild Ant tasks but they do not perform build operations. Both tasks are used to detect the errors independently of how they were generated and display them to the user. For more information on these two tasks, see the related documentation.


Archive file for articleDemoBuild.zip708KB



Get products and technologies



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 Rational software on developerWorks

Zone=Rational, DevOps
ArticleTitle=A guide to the Rational build utility