Creating an IBM i Build Specification - Rational Build Agent build definition

Create and configure an IBM® i Build Specification - Rational® Build Agent build definition. Note that this build template is deprecated in Rational Team Concert version 4.0 and higher.

Before you begin

You must have a Developer for IBM Enterprise Platforms client access license (CAL) and you must be connected to a project area and logged in as a user with Save Build Definition permission. The IBM i Jazz® Source Control pre-build participant is used to load workspace artifacts to the library file system, which requires a dedicated build workspace. For more information see, Dedicated build workspaces.

About this task

To create an IBM i Build Specification build definition, follow these steps:


  1. In the Team Artifacts view, expand your project area.
  2. Right-click Builds, then click New Build Definition.
  3. In the New Build Definition wizard, on the New Build Definition page, use the Browse button to select a team area. You can create a build definition or copy an existing one and modify it. Choose the option to create a build definition. Click Next.
  4. On the General Information page, enter an ID for the build definition or leave the default. Optionally, you can provide a description of the build definition you are creating. In the Available build templates pane, select IBM i Build Specification - Rational Build Agent (Deprecated) and click Next.
  5. On the Pre-Build page, make sure IBM i Jazz Source Control is selected and click Next.
  6. On the Additional Configuration page, ensure that all options are selected and click Finish.
  7. On the Overview tab of the build definition editor you can specify build engines and pruning policies:
    1. In the Supporting Build Engines section click Edit to add an existing build engine to the Supporting Build Engines list or click Create to create a new build engine.
      Note: IBM i Build Specification builds require a Rational Build Agent build engine.
    2. In the Pruning Policy section you can define whether you want build results to be deleted when there are more than a certain number of successful/failed build results.
  8. To schedule builds, complete the following steps:
    1. Click the Schedule tab.
    2. To enable build scheduling, under Schedule, select Enable.
    3. In the Build Time pane, specify either continuous build intervals in minutes, or a specific build time.
    4. In the Build Days pane, select the days of the week you want that the build to run.
  9. The Properties tab allows you to specify Ant properties. You can add, edit, and remove Ant properties using the corresponding buttons. You will not typically need to specify Ant properties.
  10. In the Build Definition editor, click the Jazz Source Control - IBM i tab.
  11. Click Select to find the dedicated build workspace you created or click Create to create a new dedicated build workspace.
  12. In the Load Options section, specify what to load. Select Load changes since snapshot to specify a Snapshot you can use to compare to the dedicated build workspace. Any changes in the dedicated build workspace since the snapshot was created will be loaded to the library file system. Use this option to build only a subset of the changes since a particular point in time. Click Select, then select the Repository Workspace or Stream that contains the snapshot you want to use, click Next, then select the snapshot, and click Finish. The other option Load all workspace contents will load all the contents of the dedicated build workspace to the library file system each time a build runs. This option is not recommended for large projects.
  13. The i Project to Library Mappings and Build Order section, lists all the i Projects with the Build Specification build style that are in the build workspace in the table. The Build column lets you choose whether you want this i Project to be built. The next column lists the name of the i Project. The Load Library column is used to specify where the contents of this i Project should be loaded to. The contents of the i Project that are loaded to this library depends on the setting defined in the Load Options section. The fourth column, Object Library, specifies the library where objects are built for this i Project. The load library and object libraries will be created if they do not exist. To modify the settings for an i Project, select the i Project in the table and click Edit. In the dialog that appears, specify the load library, object library, and whether to build the i Project or not. Click OK. Repeat this for each i Project as a load and object library are required to be set. The Move Up and Move Down buttons allow you to control the order in which the projects should be built. The projects will be built in the order specified unless a project has a dependency on another project, in which case the dependent projects are run first. Note: i Projects will be built, even if not checked to be built, if i Projects that are selected to be built have project dependencies on them. Project dependencies are defined in the Build Specification for the project. All projects, even those not selected to be built, are loaded to their libraries to fulfill possible build dependencies.
  14. The Referenced Libraries section provides a way of specifying libraries that are required to be in the search path when each i Project is being built. The variable &SP is used in build specifications to denote the search path. The search path for a project is a combination of the libraries you provide in the Referenced Libraries section and the load library and object library for the i Project, provided in the previous step. When the build is running, the libraries in the search path are added to the top of the library list in the order specified. Click Add to add Libraries and the Move Up/Move Down buttons to control the order they should be in the search path. Example: When building an i Project (Project A) the search path is set to be the Load Library of Project A, Object Library of Project A, and then the Referenced Libraries list. If Project A had a dependency on another i Project (Project B) then the load and object library of that project would be part of the search path after the load and object library of Project A and before the Referenced Libraries: Load Library A, Object Library A, Load Library B, Object Library B, Referenced Libraries. This chain of libraries being added will continue for any dependent projects that Project B has.
  15. In the Build Definition editor, click the Build Options tab.
  16. In the Build Script Information section choose between Generate build scripts based on the build specifications in each i Project or Specify your Ant script to execute. Choosing to generate build scripts based on build specifications in each i Project requires specifying a Load directory, an IFS directory in which to load these files. You can leave the default location or change it to a different directory. Choosing to use your own Ant script is an Advanced option for those that know Ant. When choosing this option you must specify a Build File, which is the path to your Ant script to run. Optionally you can specify which targets in the build file to run through in the Build targets field.
  17. The Fail on Error from Events Files section lets you customize whether you want the build to stop when it encounters a severity of a certain level. Note: This function requires the commands specified in your build specifications or Ant script to specify to generate an events file. Use the check box Stop the build when a compile error of a certain level is found in the generated events files to turn on or turn off this functionality. If enabled, you must specify the Severity level at which you want the build to stop. By default this is enabled with a severity level of 40.
  18. In the Commands section you can specify a Pre-build command or Post-build command. In the Pre-build command and Post-build command fields, type any CL commands necessary to set up or clean the build environment.
    For example, you can call a program to set up file overrides. The Pre-build command is executed after the files are loaded to the libraries and before the i Projects are built. The Post-build command is executed after building the i Projects.