Worker Build Configuration XML Files

While the OWD file described above holds fundamental information about the worker’s source code, and information required to build and run the worker, the optional build configuration file describes the various ways it should be currently built.

Thus the build configuration file narrows down the perhaps large number of ways the worker might be built (for different combinations of parameter values or targeting different platforms), to what will actually get built. When it is not present, the worker is built using the default values of parameter properties, and the platforms being targeted is limited by the fundamental limitations on platforms expressed in the top-level attributes of the OWD.

For portable workers with no parameters, the build file is not recommended or needed.

The use cases for this file include:

  • Specifying useful combinations of compile-time parameters for unit testing

  • Specifying known currently required combinations of compile-time parameters for applications

  • Limiting platforms to build for, for temporary convenience rather than an expression of “what platforms are viable”, which is already specified in the OWD.

The name of this optional file is <worker>-build.xml, and the top level element is build. The top-level attributes controlling/limiting the build targets and platforms in the OWD are also valid here. Limitations in the OWD override those in this file since the OWD platform constraints are considered fundamental, while those in this file are considered for convenience to further limit what platforms or targets get built.

These platform/target constraint attributes that are defined for the OWD and are also valid in the build file are: OnlyPlatforms, ExcludePlatforms, OnlyTargets, ExcludeTargets. There are no other top-level attributes for this file.

Build Configurations

We use the term build configuration to be a set of parameter property values to use when building the worker. Each build configuration has an ID. When the build configuration file does not exist, there is a single build configuration, with an ID of zero, with default values of all parameters (from OCS or OWD).

The target-* directories mentioned above are used to separate the files that result from building for different targets (e.g. rocky9 vs. xilinx24_1_aarch32, or [Xilinx] zynq vs [Xilinx] zynq_ultra). A different target-* subdirectory is in fact created for each build configuration. If the ID is zero, the name of the directory is target-<platform>. If it is not zero, then the directory name is target-<id>-<platform>.

There are two valid child elements in the top level build XML element, which together determine the set of build configurations for the worker:

  • parameter to specify parameter values for all configurations

  • configuration to specify a build configuration.

If there are none of either element, a configuration with ID zero is generated using the default values of all parameter properties. The same thing happens when there is no file at all.

If there are parameter elements, but no configuration elements, then configurations are generated for all combinations of values mentioned in all the parameter elements, using default values for unmentioned parameter properties. Since parameter elements can provide multiple values (see below), this means that configurations are automatically generated for the cross-product of all parameter values. E.g. if property A is specified with values 1 and 2, and property B is specified with values 10, 11, and 12, and property C is unmentioned but having a default value of 77, then these build configurations will be generated:

ID

A

B

C

0

1

10

77

1

1

11

77

2

1

12

77

3

2

10

77

4

2

11

77

5

2

12

77

The file in this example would be:

<build>
  <parameter name='a' values='1,2'/>
  <parameter name='b' values='10,11,12'/>
</build>

When a configuration element is specified with an id attribute, all parameter properties unmentioned in the configuration element take on default values. Using the above example we might have:

<build>
  <configuration id='0'>
    <parameter name='a' value='2'/>
    <parameter name='b' value='12'/>
  </configuration>
</build>

Which would result in A being 2, B being 12 and C being 77.

When a configuration element is specified without an id attribute, configurations are generated that have the all the combinations mentioned in top-level parameter elements as in the above example, but with the values for parameter properties mentioned inside the configuration element taking those specific values. For example:

<build>
  <parameter name='a' values='1,2'/>
  <parameter name='b' values='10,11,12'/>
  <configuration>
    <parameter name='c' value='78'/>
  </configuration>
</build>

This would create 6 build configurations (like the table above), but with property C having the value 78 rather than its default of 77.

Parameter Elements in the <worker>-build.xml File

This element specifies one or more values for a parameter property. The name attribute specifies which property, and must match the name of the parameter property in the OWD or OCS (case insensitive). The values for the parameter can be specified using one of these attributes:

  • The value attribute can specify the single value.

  • The values attribute can specify a comma-separated list of values.

  • The valueFile attribute can specify a value in a file.

  • The valuesFile attribute can specify multiple values in a file.

When the parameter element is at the top level of the <worker>-build file, it is specifying values common to all configurations that do not have id attributes. If the same parameter element is mentioned as a child element of a configuration element, it overrides any top level value(s) for that parameter in that configuration. An example <worker>-build file is:

<build>
  <parameter name='debug' value='true'/>
  <configuration id='1'>
    <parameter name='mode' value='lownoise'/>
    <parameter name='taps' valueFile='taps.txt'/>
  </configuration>
</build>

Since there is an id attribute present for the configurations, it would use the default value of the debug parameter, not the value specified in the parameter element (which in this case would be ignored).

Configuration Elements in the <worker>-build.xml File

The configuration element has an optional numeric id attribute which will appear as the build configuration suffix in the name of the target directory for that configuration. If the id attribute is zero, no suffix is added. The configuration element also has parameter subelements indicating the specific parameter values for that configuration.

When there is no id attribute, the globally defined values for parameters are used to generate build configurations.