Build descriptor part

A build descriptor part controls the generation process. The part contains several kinds of information:

Master build descriptors

Your system administrator may require that you use a master build descriptor to specify information that cannot be overridden and that is in effect for every generation that occurs in your installation of EGL. By a mechanism described in Master build descriptor, the system administrator identifies that part by name, along with the EGL build file that contains the part.

If the information in the master build descriptor is not sufficient for a particular generation process or if no master build descriptor is identified, you can specify a build descriptor at generation time, along with the EGL build file that contains the generation-specific part. The generation-specific build descriptor (like the master build descriptor) must be at the top level of an EGL build file.

You can create a chain of build descriptors from the generation-specific build descriptor, so that the first in the chain is processed before the second, and the second before the third. When you define a given build descriptor, you begin a chain (or continue one) by assigning a value to the build descriptor option nextBuildDescriptor. Your system administrator can use the same technique to create a chain from the master build descriptor. The implication of chaining information is described later.

Any build part referenced by a build descriptor must be visible to the referencing build descriptor, in accordance with the rules described in References to parts. The build part can be a linkage options part or a resource associations part, for example, or the next build descriptor.

Precedence of options

For a given build descriptor option (or Java run-time property), the value that is initially processed at generation time stays in effect, and the overall order of precedence is as follows:

The master build descriptor
The generation-specific build descriptor, followed by the chain that extends from it
The chain that extends from the master build descriptor

The benefit of this scheme is convenience:

The system administrator can specify unchanging values by setting up a master build descriptor.
You can use a generation-specific build descriptor to assign values that are specific to a generation.
A project manager can specify a set of defaults by customizing one or more build descriptors. In most situations of this kind, the generation-specific build descriptor points to the first build descriptor in a chain that was developed by the project manager.
Default options can be useful when your organization develops a set of programs that must be generated or prepared similarly.
The system administrator can create a set of general defaults by establishing a chain that extends from the master build descriptor, although use of this feature is unusual.

If a given build descriptor is used more than once, only the first access of that build descriptor has an effect. Also, only the first specification of a particular option has an effect.

Example

Let's assume that the master build descriptor contains these (unrealistic) option-and-value pairs:

  OptionX                02
  OptionY                05

In this example, the generation-specific build descriptor (called myGen) contains these option-and-value pairs.

  OptionA                20
  OptionB                30
  OptionC                40
  OptionX                50

As identified in myGen, the next build descriptor is myNext01, which contains these:

  OptionA                120
  OptionD                150

As identified in myNext01, the next build descriptor is myNext02, which contains these:

  OptionB                220
  OptionD                260
  OptionE                270

As identified in the master build descriptor, the next build descriptor is myNext99, which contains this:

  OptionZ                99

EGL accepts option values in the following order:

Values for options in the master build descriptor:
```
  OptionX              02
  OptionY              05
```
Those options override all others.
Values in the generation-specific build descriptor myGen:
```
  OptionA             20
  OptionB             30
  OptionC             40
```
The value for optionX in myGen was ignored.
Values for other options in myNext01and myNext02:
```
  OptionD             150
  OptionE             270
```
The value for optionA in myNext01 was ignored, as was the value for optionD in myNext02.
Values for other options in myNext99:
```
  OptionZ              99
```