GitHubContribute in GitHub: Edit online

include:

Use the include keyword to import and merge configuration from other YAML files. Two types of include are available:

  • include:file
  • include:application

Example:

Source: dbb-build.yaml

---
include:
  - file: ‘Cobol.yaml’
  - file: ‘Assembler.yaml’
  - application: MortgageApplication
    file: ‘applications/MortgageApplication.yaml’

Source: dbb-app.yaml

---
include:
  - file: ‘applications/MortgageApplication.yaml’

include: file

Use include:file to include other configuration files. When used in the build configuration, it defines another build configuration file to be merged into the current one. When used in the application configuration, it defines another application configuration to be merged into the current one.

You can split a large dbb-build.yaml/dbb-app.yaml file into multiple files to increase readability and simplify configuration. Included build configuration files are merged with the dbb-build.yaml/dbb-app.yaml file into an internal configuration model at runtime.

Syntax

include:
  - file: string # absolute or relative path of the build/application configuration YAML file.

Rules

  • Both absolute and relative paths are supported.
    • Relative paths are assumed to be relative to the $DBB_BUILD directory in the following cases:
      • Including a build configuration from another build configuration file.
      • Including an application configuration from another application configuration that was included from the build configuration file.
    • Relative paths are assumed to be relative to the working directory in the following case:
      • Including an application configuration from another application configuration when no application configuration was included in the build configuration file.
  • UNIX glob ** and * path wild cards are supported.
    • All the files that match the pattern are merged in order of discovery. The order is indeterminate, so configurations included in this manner should not override eachother's elements.
  • When used in a build configuration, only valid build configuration files are included. They must contain one top-level include, lifecycles, tasks, or variables element.
  • When used in an application configuration only valid application configuration are included. They must contain a top level application element.
  • Downstream file include statements are resolved before merging into the parent configuration file.
  • Build lifecycles, tasks, variables, and task variable overrides are merged at the end of the parent configuration file in the order of the include statements.
    • For Build Configurations:
    • Lifecycle definitions overwrite earlier definitions in their entirety.
    • Task/Language/Stage definitions overwrite earlier definitions in their entirety.
    • Global variable definitions are merged together; individual variable names overwrite earlier definitions.
    • For Application Configurations:
    • The top-level application configuration name element is not merged and remains unaffected.
    • Task variable override definitions are merged together; individual variable names overwrite earlier definitions.
  • Included build configurations are not allowed to include application configurations.
  • Included configuration paths may not make use of reference replacement.

include:application

Use the application configuration file to override task variables on an application or application file basis. The dbb-app.yaml application configuration YAML files are usually located in the root directory of the application being built. However, you might want to prevent developers from accessing application configuration. In this case, use include: application statements in the dbb-build.yaml file to restrict application configuration to the z/OS build and DevOps teams.

Syntax

include:
  - application: string # the directory name of the application.
    file: string # absolute or relative path of the build configuration YAML file.

Rules

  • The value of the application element must match the application directory's name that the included configuration applies to. This allows the build engineer to define multiple application includes for different applications.
  • Only one application configuration file can exist for the applications that are loaded at runtime. Other application include statements are ignored.
  • When an application configuration is included, the user is prevented from using the --config <dbb-app.yaml> command line option. This option is used to add application overrides at runtime.
  • If no include:application statement exists for the application being built, then the zBuilder searches for a dbb-app.yaml file in the directory of the application that is being built.
  • If no application configuration is found, then a warning is issued, and the build continues with the base build configuration.
  • Included configuration paths may not make use of reference replacement.