Back to Blog List

EGL headless build integrated with RTC

Like

This tutorial offers you a scenario of how to run EGL headless build automatically using the RTC Jazz build system. In this scenario, the EGL developers use RBD to develop EGL projects, and they use RTC as the source control system for such EGL projects. We will explore how the developers kick off a build in the Jazz build server, where they can automatically check out, compile, generate and deploy the EGL project.

This scenario can be particularly used for the continuous integration of EGL projects which is one of the key factors of Agile programming.

Prerequisite

Before we start this tutorial, you must have some basic understanding of Rational Business Developer(RBD) and Rational Team Concert(RTC). Please refer to the reference for more information.

Scenario

Figure 1: Scenario Structure

In this scenario, a RTC server is set up to provide the source repository. EGL developers (could be a large number of developers) create and develop the EGL program and deliver to RTC server again and again. Usually, the RTC build client administrator will kick off a build request at a certain time for a particular time period ( e.g. daily or hourly ). The Jazz build engine will respond to the build request and do the build.

A quick overview of the steps of the scenario is as follows:

Set up the environment, start the RTC build server and Jazz build engine.
In the RTC build client, create the build definition and build engine.
EGL developers develop EGL projects and build scripts and deliver to RTC code repository repeatedly.
In RTC build client, request a build repeatedly at a certain time.

Attached are all the data needed for running this scenario:RBDHealessBuildTestProjects.zip

In the scenario, we provide a sample workspace which contains all kinds of EGL projects including RUI project with Services, Web project, Cobol project etc. We will build all these projects and deploy the RUI project automatically.

Setup the Environment

There are 4 kinds of roles in this scenario:

RTC Server: Usually an organization with a single server
- Install the RTC server.
Jazz Build Engine: This is where the build happens. When it receives the build request from the client, the build engine will fetch the source code from RTC server and invoke RBD to do the headless build.
- Install the Jazz build engine
- Install RBD
- Install ant-contrib to RBD: ant-contrib is an extension of ant tasks library which provide functionalities such as loop and conditional statement. Download the ant-contrib lib at http://ant-contrib.sourceforge.net/. To install it, just unzip it somewhere.

RTC Build Client: This is the place to define and kick off a build.
- Install the RTC client
EGL Developer: There may be a large number of developers inside an organization who contribute EGL codes to the RTC server.
- Install RBD to develop EGL program
- Install the RTC client to deliver EGL code to RTC repository

After setting up the environment, we should start the RTC server and Jazz build engine to process any requests from clients.

Configure the RTC build client

In this section, we will set up the RTC build client. We will complete the following tasks:

Connect to the RTC server
Define a build engine to run the build definition
Define a build definition to identify your build script
Create the build script to run

Notice that, this section is all about RTC configuration, we can get a more detailed instruction from RTC documents.

Connect to the RTC server

We should connect to the RTC server which serves as the source code repository. You must get an invitation email from the RTC server admin before you connect to the server. Follow this link to do the connection: http://pic.dhe.ibm.com/infocenter/rtc/v2r0m0/index.jsp?topic=/com.ibm.team.concert.tutorial.doc/topics/tut_rtc_getcon
We will create a repository workspace “EGL Build Sample Workspace” to store all the EGL projects in this scenario.

Define a build engine

The build engine identifies the build system that performs builds. The build engine identifier (engine ID) is typically the same as the build machine name, so that it is easier to determine which build machine is associated with which engine ID. Follow this link to create a build engine:

http://pic.dhe.ibm.com/infocenter/rtc/v2r0m0/index.jsp?topic=/com.ibm.team.build.doc/topics/tcreatebuildengine.html

Figure 2: The build engines and build definitions after setting up

Define a build definition

Build definitions are based on various build templates, such as Ant, command line, or Maven. We will use Ant script in this scenario. Follow this link to crate a new build definition. http://pic.dhe.ibm.com/infocenter/rtc/v2r0m0/index.jsp?topic=/com.ibm.team.build.doc/topics/tcreatebuilddefinition.html

Note that we can specify properties in the properties tab. These properties can be used in the build definition and the build script. We need to specify several common properties here. The paths are paths in the Jazz Build Engine machine. Figure 3 is the properties setting we use in this scenario.

Figure 3: Build Definition properties setting

In the Jazz Source Control tab, we specify the repository workspace where the EGL projects are stored, which is “EGL Build Sample Workspace” in this scenario.

Load directory is a directory that resides in the Jazz Build Engine machine in which the EGL projects will be retrieved and built. Figure 4 is the Jazz Source Control settings we use in this scenario.

Figure 4: Build Definition Jazz Source Control setting

In the Ant tab, we must identify the build script in the build file.

Figure 5: Build Definition Ant setting

Create the build script

The build script is identified in the build definition and will be run in the Jazz build engine. In our scenario, the build script is defined in the RBDBuildScripts project callAnt.xml. Note that, the project is also shared in the RTC repository, so the build script can be updated and the latest will be run automatically by the Jazz build.

There are 2 ant script files in RBDBuildScripts. callAnt.xml is the entry ant script file. It connects RTC with RBD. buildAll.xml will leverage RAD and RBD ant tasks to do the build.

Let’s examine the entry ant script file callAnt.xml. This ant task invokes the com.ibm.etools.j2ee.ant.RunAnt application to run an Ant file - buildAll.xml in the IDE.

Figure 6: callAnt.xml

buildAll.xml is more complicated. It uses the ant tasks defined by Eclipse, RAD, RBD and ant-contrib lib together to finish the automatically headless build of the EGL project. The link for the ant tasks library can be found:

Apache Ant User Manual

Ant in Eclipse

Working With Ant In RA D

ant-contrib ant tasks

RBD also provides more ant tasks: egl.buildDescriptorGet, egl.buildDescriptorSet, egl.cmd, egl.deploy, egl.export, egl.generate, egl.optBuildOrder

Please refer to RBD document for the full list of EGL ant tasks and their properties.

The buildAll.xml is composed by 4 components:

Property setting.
Init section. In this section, we will do some workspace initialization such as creating server runtime, setup workspace preference, etc.

We can use listServerTypes to get all supported server types in current workspace..
To get all supported preference, we can open the RBD workspace and try File > Export > General > Preference. This will allow us to export the Eclipse preferences from your workspace on an Eclipse.EPF archive. We can inspect this file to find out the preferences' names, their IDs and values for the workspace and then use those in the WorkspacePreferencesSet Ant task.

Import projects section. Loop through all directories in the workspace folder and use the projectImport task to import projects into the workspace.
Default target section. Call the workspaceBuild task to do an overall build. Then loop through all the projects and run the build files if there is a ant script file build.xml inside of the build folder. workspaceBuild will run just like the user run Build All in the workspace. The project specific ant script can be designed to run something that won’t be done by default workspace build such as export EGLAR file etc.

Note that, this buildAll.xml is just a sample file. User can define their own build script file according to their needs.

Deliver the EGL projects

EGL developers will develop the EGL projects and deliver to the RTC repository workspace. The build scripts can also be delivered there.

In this scenario, we should import the projects in the zip file into a RBD developer workspace with RTC client installed. Then you can share the projects to the RTC repository workspace “EGL Build Sample Workspace”. User can repeatedly update and test the EGL projects and deliver to the repository.

Note that, there are build scripts in the build folder in some of the projects. The name here must be consistent with the buildAll.xml section 4. In this scenario, these build.xml files are designed to run actions that won’t be done by the workspace build. In EGL, Java and JS generation will be done by workspaceBuild while COBOL generation won’t be run by default configuration. So build.xml should contain generation for COBOL project but should not contain generation for Java or RUI projects.

Create build script

We have created an overall build script buildAll.xml in last section. In the build script, we will run build scripts inside of the imported projects build folder. To create a build script for a specific project, the location and name of the build script must be consistent to what’s in buildAll.xml. So we will create build.xml in build folder if it is necessary.

In this scenario, we created some build scripts inside of the test projects:

ACobolProject: Invoke egl.generate to generate COBOL for EGL source. The COBOL generation is not invoked by the workspace build by default, so we need an additional build script.

ARUIProject: Invoke egl.deploy to deploy the RUI project to a web project.

AJavaProject: Invoke egl.export to export the project into an EGLAR file.

Test the build script locally

The developer can test the build script in the local workspace before it’s delivered to the repository workspace. To test the build script, follow the steps below:

Right click at the project, select “Properties”, a dialog of properties configuration will pop up.
Select “Builder”, click the “New...” button to create a new builder. A dialog with title “Choose configuration type” will pop up.
Select “Ant Builder” then click “OK”. A dialog with title “Edit Configuration” will pop up.
Fill in Name field, select the Build file and optionally fill in other fields according to your environment and click “OK”. It will go back to “Properties” dialog. The new builder has been added to the builder list.
Run Project->Clean... or Project -> Build All, the build script will be run.

After testing, we should remove the builder configuration because some of the behaviors of build script do not need to run for each build such as deploy or export EGLAR. In order not to affect other developers, the builder should be removed before delivering to the server.

Request a build

We can schedule a build and run it automatically or request a build manually. In this scenario, in the Team Artifact view, we can right click the “EGL Sample Build” build definition, select “Request Build...” to run the build.

The build result can be viewed in the “Builds” view.