Specifying IBM i dependency build settings

You can modify the settings for the operating system after you create a build definition by using the Build Definition editor.

Before you begin

Dependency builds require a Rational® Build Agent build engine.


  1. In the Team Artifacts view, expand the project folder.
  2. Expand the Builds node, right-click your build definition, and click Open Build Definition.
  3. In the Build Definition editor, click the Overview tab.
    1. Optional: In the General Information section, briefly describe your build definition in the Description field.
    2. Select the Ignore warnings when computing overall status check box.
    3. In the Supporting Build Engines section, click Create to create a build engine, click Add to add one, or click Remove to remove one.
    4. Optional: In the Pruning Policy section, select the Prune build results check box, and then set the number of successful and failed builds to save.
  4. Optional: Open the Schedule tab to set up automatic builds.
    1. Select the Enabled check box; then, add or remove automatic builds as needed.
    2. In the Build time section, click either Continuous interval in minutes, and indicate the interval, or click At, and specify a time for the automatic build to run.
    3. In the Build days section, specify the days of the week on which to run the build.
  5. Open the Properties tab to add, edit, or remove any build definition properties.
  6. Click the Jazz Source Control tab and select a build workspace or create one.
    Note: Specify a dedicated build workspace for your build definition. For more information, see Dedicated build workspaces. Set the visibility of the build repository workspace so that the Jazz® user that you configured for your Rational Build Agent can access the workspace in read-only mode.
    1. In the Load Options section, specify file extraction details, such as a load directory and a resource prefix.
      Note: It is advised to avoid using blanks or $ in the path or the prefix as these characters (or their national language equivalents) can cause inconsistent results.

      You can reference properties by using this format: ${propertyName}.

      Restriction: Unlike other IBM® i builds, IBM i dependency builds cannot load Rational Developer for Power Systems Software binary (.oar) files from Engineering Workflow Management source control to the IBM i file system.
    2. Choose one or more load options.

      Two options apply to QSYS:

      • Load workspace to the resource with the resource prefix at the beginning of the build. Select this option to specify whether artifacts that are stored in an enterprise file system (QSYS) are loaded to the resource with the designated resource prefix at the beginning of a build. If you do not select this option, artifacts are loaded during the build as necessary. Reference this option with this property: team.enterprise.build.ant.fetchAll.
      • Select the Log Loading check box to create a log file and attach it to the build results on the Logs tab. The log file shows all of the commands that run to perform the required loading.

      These options apply to the integrated file system (IFS):

      • Select the Delete directory before loading check box to delete the metadata for the load directory.
        Tip: Metadata stores information about the files that you load from Engineering Workflow Management. When a build fails because of corrupted metadata, select the Delete directory before loading check box to clean up the metadata and resolve the issue. However, when metadata is not corrupted and you select this option, your build might take longer to complete. Select this option only if you want to clean up the load directory and its associated metadata.
      • Load workspace to the load directory at the beginning of the build. Select this option to specify whether artifacts stored in the integrated file system (IFS) are loaded to the directory at the beginning of a build. Reference this option with this property:team.enterprise.build.ant.fetchWorkspaceBeforeBuild.
        Important: If you do not select this option, no file is loaded to the IBM i integrated file system.
      • Create folders for components. Reference this option with this property: team.enterprise.scm.createFoldersForComponents.
      • If you are loading only some of the components, select which components to load in the Components to exclude field. Reference this option with this property: team.enterprise.scm.loadComponents.
      • In the Load rules field, select which load rules you want to use to describe how to load the build workspace. Reference this option with this property: team.enterprise.scm.componentLoadRules.
    3. In the Accept Options section, select one or more options.
  7. Click the IBM i Dependency Build tab, and then click the General tab.
    1. In the Build File and Targets section, click Generate build file from language definitions to automatically generate a build file from the available language definitions. The order determines the order in which items are built.
      • If you are not sure of the order that you want to set the language definitions, you can open any of the language definitions in the list by double-clicking the name of the language definition.
      • If you click Generate a build file from these language definitions, the language definition you specify must have a translator that is associated with it, or a build file cannot be generated. If you do not have language definitions in this project area that are associated with translators, browse to another project area.
      The generated build file, generatedBuild.xml, is attached to the build results on the Downloads tab.
    2. Optional: Instead of generating a build file, you can specify a custom build file and build targets by clicking Use an existing build file.
    3. Optional: Select the Trust build outputs check box.
      • When you select this check box, the build runs as though you did not delete or modify the outputs that were created in previous builds. This option improves performance when you rebuild because you skip unnecessary checks for missing or changed outputs.
      • When you select this check box, even if you delete outputs, such as program objects, on the build server, Ant does not initialize, and nothing is built unless you made associated changes in the repository, such as changes in the source code.
    4. Optional: If you want to publish build map links to the External Links tab in the build results view, select the Publish build map links check box.
    5. Optional: In the Frequency of updates to the number of buildable files preprocessed in the build report contribution summary field, define the number of files to preprocess before updates are made in the Build Result editor.
    6. In the Search Path field, you can browse to a search path for the build to use as the library list for the build. If you specify a search path in this field and in the translator, the search path in the translator overrides this search path. If you do not select a search path in either the build definition or the translator, the IBM i project object and source libraries are used.
      The build checks for a search path in the following order, and it reads the first one that it finds:
      1. Translator
      2. Build definition
      3. IBM i project source and object libraries.
    7. In the Fail on Errors section, specify whether to cancel the build when an error of a certain severity level occurs.
    8. Optional: In the Commands section, specify an IBM i command to run before the build script runs, after it runs, or both.
    9. In the Ant with Enterprise Extensions Configuration section, specify any configuration details, including the following details:
      • Ant home
      • Ant arguments. The default is -verbose.
        Tip: To make debugging easier, replace -verbose, which is the default, with -debug. If you do not need detailed debugging information in the build log files, in the Ant arguments field, delete the -verbose argument, or replace it with -quiet.
      • Working directory
      • Java™ home
      • Java VM arguments. The default is -Xquickstart.
      • Properties file
  8. To enable dependency builds, click the Dependency Options tab, and then click either Build workspace or, to limit builds to a subset of the buildable items, select Build subset.
    If there are files to be included in each build for this build definition, select Mandatory subset. Click Browse to locate the subset containing the files that are required to be included in this build. The files in the mandatory subset are always built, even if they are not changed.
    1. Optional: To build only changed items, select the Build changed items only check box.
    2. Optional: In the Select components to be excluded from build field, click Select to add components that you do not want to process in the build.
      By selecting this option, you can improve build performance by reducing the number of files that are processed during a dependency build.
    3. Expand the Impact calculations (advanced) section to limit which calculations are included during build preprocessing. The build processing feature normally runs various queries to find files that are affected by the changed files. All of the queries are selected by default, but you can clear the impact calculation check boxes to disable the queries.
  9. Optional: Click the Request Options tab to set the options that are to be available on the Request Build dialog. The options you select are enabled in the request, and the options that are not selected are hidden. The following options are new on the Request Build dialog.
    • Mandatory subset, if the build is a workspace build and Build changed items only is not selected
    • The Advanced options section contains some properties from the build definition that were not previously on the Request Build dialog.
    • Personal Build Options are only shown on the Request Build dialog if Personal Build is selected.
    • The options for editing the build file and build targets are only displayed if you are not generating a build file.
    • The Pre-build script option is only displayed if the build definition has a pre-build script.
    • The Post-build script option and the Always run post-build script option are only displayed on the Request Build dialog if the build definition has a post-build script. When the Post-build script option is not selected, the Always run post-build script option is hidden.
    • If the Pre-build script or Post-build script options are not selected, the corresponding property is hidden so that the script is not processed.
    • If the requestor lacks permission under the Enterprise Build permissions and does not have JazzAdmin capabilities, the Advanced options are hidden on the Request Build dialog .
    The Build workspace, Build subset, and Personal build options can not be hidden on the Request Build dialog. The Repository workspace, Load directory, and Resource prefix options can not be hidden for personal builds.
  10. Click Save.

What to do next

Request a dependency build by using the build you created.