Using the Builders Page

You use the builders page to define what is built when this build specification is used. A single builder can be used to create one object or several objects of the same kind from source.

The Layout of the Builders Page

The Builders page consists of two main areas. On the left side, there is a tree view showing all of the builders and their various components. You can use the buttons next to the tree view to add, duplicate, and remove components from the view. On the right side, there is an area used for editing the various attributes of the component that is selected on the left.

The components of a builder are inputs, resource dependencies, prerequisite builders, and command sets. You would typically define them in that order.

Builder Properties

Builders themselves have properties that can be edited. When you select a builder you will see three sections providing those properties.

Use the Builder Details section to provide the name of the builder. This name is the builder's identifier and it is required. The builder name can contain any characters except spaces and commas and can be up to 50 characters long. It is used when referring to that builder as a dependency. You can also enter a description for the builder. The description is optional.

The Output Objects section describes the objects that are created by this builder. The build runtime will check these objects for existence and staleness and select the appropriate command set section to execute. If the builder creates object from source you can use the predefined variable &N to name the output object. If the builder is used for setup, it may not actually create or change any objects and this section can be left blank.

Builder Variables can be used to provide values for variables in command sets and in output objects. You can define whatever substitution variables you want in this section. These variables can then be referenced from the command sets used by this builder. If you use more than one command set in this builder you could define variables here that will be used across command sets.

Working with Input Lists

An input list provides values to the command sets referenced by this builder. Command sets used by the builder may have variables specified in their definitions. You use the input list to provide values for these variables.

Each input list has a name which can be used in the command set variable table. The input specifies a list of resources by defining what to include in the list and possibly what to exclude from that. For example, you could specify that an input be a list of all members of QRPGLESRC except for member ABC.

Some inputs are meant to be processed one at a time by the builder, for example, a list of source members provided to a compile command set. Other inputs are meant to be processed as a group, for example, those module objects that are meant to be combined into a service program. You specify the kind of input when you provide its properties. It is unlikely that you would have both kinds of input in the same builder, however the build editor does not disallow this.

Repeating Tasks for each Element of an Input List

If the input list is to be processed one at a time then the command sets in this builder are run for each element of this list. The list element provides the values for the predefined variables &N, &X, &L, and &F. The command sets are run in the order you specify them in the builder.

Substituting a whole Input List for a Variable

If the input list is to be processed as a group then the builder combines all the elements of the list into a single value, separating each of the elements by a blank and formatting them according to the selected format in the command set variable table. You can use this list to provide parameters to commands that take lists as values. A good example of this would be modules that are to be combined into a service program.

Specifying Resource Dependencies

Dependencies that this builder might have on resources are described very similarly to input lists, except that they do not have names. For example, you might have an include library that is supplied by a vendor. You can specify that include library as a resource dependency. If that library is changed, then the build will cause this builder to be run.

To work with resource dependencies, select the "Resource Dependencies" component of the specified builder in the tree view on the left side of the page, and use the forms on the right side of the page to add or edit them. The exact form of the dependency depends on the whether it is a member or an object.

Setting Up Prerequisite Builders

The Prerequisite Builder section is used to specify the dependencies of one builder upon another. The build uses this information to determine the order in which to run the builders. For example, you can specify that builder B depends on builder A by referring to builder A from the definition of builder B. Since A is required by B, the build will check to see if A needs to be built prior to building B. If so, then the build will build A first, then, since B depends on the newly built A, B will be built.

Prerequisite builders usually do not need to be used. Builders are guaranteed to be run in the order they are specified in the list of builders. Prerequisite builders can be used to fine-tune that order.

Working with Command Set References

Command set references are used by builders to define the processing that is done when that builder is run. Command set references are defined using the identifier assigned to the command set. To add a command set reference to a builder, select the Command Sets section of the builder in the tree on the left side of the page and use the buttons on the form to add a new command set or duplicate the currently selected command set for modification.

Your command sets should be quite small and accomplish one thing. For example, a command set might only have a single compile command and a CHGOBJOWN command. Likewise, your builders should be limited to building one kind of IBM® object. For example, you might define a builder to compile all RPG source members of a particular source file into programs.

You can reference more than one command set in a builder. The build processes these command set in the order in which they are defined in the builder. If a command set is conditional the output object is tested to see if it exists and, if so, if it is out-of-date. These checks are then used to select the appropriate processing section of the command set.

Command sets can have substitution variables defined inside them. You provide values for these variables by defining the values at the project level on the Overview page, at the builder level in the builder properties, or locally using the command set variables table. The variables table for a command set will be shown when you select the command in the tree view on the left side of the Builders page. In the variables table you can match a variable to a literal string or to an input list. Input lists are given a format when used in a variable table. That format describes how their values are substituted into a command. Currently the only format that is supported is a qualified name format that allows input lists to be used to provide values to commands that take these fully qualified object names as parameters.

Please refer to Jazz™.net for more information.


Feedback