Setting up and configuring zBuilder

The zBuilder introduced in DBB 3.0 is an integrated configuration-based build framework for building z/OS applications. Build configuration is defined in YAML files. The underlying implementation is comprised of Java tasks that invoke the existing DBB APIs. For more information on the zBuilder see Building z/OS applications with the zBuilder.

Copy configuration directory to an alternate location

DBB ships with a default zBuilder configuration directory located at /usr/lpp/IBM/dbb/build. This directory should be relocated to an alternate location like /etc/dbb/build so as to not be ovewritten when new updates of DBB are applied.

For the example below /etc/dbb must exist before the cp command is executed:

#> cp -r /usr/lpp/IBM/dbb/build /etc/dbb

Verify that build directory exists in the new location and contains dbb-build.yaml.

#> ls -la /etc/dbb/build
total 64
drwxr-xr-x   3 USER1   OMVS        8192 Sep 22 08:04 .
drwxr-xr-x   3 USER1   OMVS        8192 Sep 22 08:04 ..
-rw-r--r--   1 USER1   OMVS         168 Sep 22 08:04 .gitattributes
-rw-r--r--   1 USER1   OMVS        3794 Sep 22 08:04 dbb-build.yaml
drwxr-xr-x   2 USER1   OMVS           0 Sep 22 08:04 groovy

Copy zBuilder sample language configuration files to configuration directory

Customers using the zBuilder need to provide a language configuration file for each type of source file to be built i.e Cobol.yaml, PLI.yaml, Assembler.yaml, etc. DBB provides a number of sample Language configuration files. These configuration files can be used as is or be used as a basis for providing custom configuration. To copy the sample language configuration files to the new build configuration, enter the following command:

#> cp /usr/lpp/IBM/dbb/samples/languages/*.yaml /etc/dbb/build

Verify that additonal language configuration files were copied to new location including Languages.yaml.
NOTE: Not all sample language configuration files displayed.

#> ls -la /etc/dbb/build
total 208
drwxr-xr-x   3 USER1   OMVS        8192 Sep 22 08:04 .
drwxr-xr-x   3 USER1   OMVS        8192 Sep 22 08:04 ..
-rw-r--r--   1 USER1   OMVS         168 Sep 22 08:04 .gitattributes
-rw-r--r--   1 USER1   OMVS        9489 Sep 22 08:12 Assembler.yaml
-rw-r--r--   1 USER1   OMVS        7382 Sep 22 08:12 Cobol.yaml
-rw-r--r--   1 USER1   OMVS        3762 Sep 22 08:12 Languages.yaml
-rw-r--r--   1 USER1   OMVS        2553 Sep 22 08:12 LinkEdit.yaml
-rw-r--r--   1 USER1   OMVS        7818 Sep 22 08:12 PLI.yaml
-rw-r--r--   1 USER1   OMVS        3794 Sep 22 08:04 dbb-build.yaml
drwxr-xr-x   2 USER1   OMVS           0 Sep 22 08:04 groovy

Configure `Languages.yaml` for your development system

In addition to the sample language configuration files, a Languages.yaml file is also provided in the language sample directory and should have been copied during the previous step. The Languages.yaml file is referenced by dbb-build.yaml and is used to define zBuilder variables for Partition Data Sets (PDS) used by the sample language configuration files. This file must be configured for your build machine!

Example of variables needed to be set to build the MortgageApplication sample:

##############################################################################     
# Partition Data Sets (PDS) used by included language tasks
# Please provide a fully qualified DSN for each build variable below as needed
##############################################################################
variables:

  ############################################################
  # Start: Datasets required for MortgageApplication sample
  ############################################################
  
  # z/OS macro library. Example: SYS1.MACLIB
  #- name: MACLIB
  #  value: 
    
  # LE (Language Environment) load library. Example: CEE.SCEELKED
  #- name: SCEELKED
  #  value: 

  # High Level Assembler (HLASM) load library. Example: ASM.SASMMOD1
  #- name: SASMMOD1
  #  value: 

  # Cobol Compiler Data Sets. Example: COBOL.V6R1M0.SIGYCOMP
  #- name: SIGYCOMP
  #  value: 

  # CICS Macro Library. Example: CICSTS.V6R1M0.CICS.SDFHMAC
  #- name: SDFHMAC
  #  value: 

  # CICS COBOL Library. Example: CICSTS.V6R1M0.CICS.SDFHCOB
  #- name: SDFHCOB
  #  value: 
  
  # CICS Load Library. Example: CICSTS.V6R1M0.CICS.SDFHLOAD
  #- name: SDFHLOAD
  #  value: 
  
  # DB2 Load Library. Example: DB2.V12R1M0.SDSNLOAD
  #- name: SDSNLOAD
  #  value: 

  # Optional IDz Load Library. Needed for Error Feedback option. Example: FEL.V16R0M0.SFELLOAD
  #- name: SFELLOAD
  #  value: 
  
  ############################################################
  # End: Datasets required for MortgageApplication sample
  ############################################################

To set a variable uncomment the name: and value: properties of the variable and provide the value:

  # z/OS macro library. Example: SYS1.MACLIB
  - name: MACLIB
    value: SYS1.MACLIB

See Language samples for more information on configuring the Languages.yaml file.

NOTE all YAML configuration files are encoded in UTF-8. Only editors that support UTF-8 or ASCII should be used to edit them. Examples:

Configuring Extra Datasets for Samples

Depending on which out-of-box language scripts you decide to use, you may need to add their corresponding datasets to Languages.yaml from the following:

Assembler

  # IMS Macro Library. Example: DFS.V11R1M0.SDFSMAC
  - name: SDFSMAC
    value:

  # ADFz Common Components library. Example: IPV.V1R9M0.SIPVMODA
  - name: PDTCCMOD
    value:

  # IMS RESLIB. Example: DFS.V11R1M0.SDFSRESL
  - name: SDFSRESL
    value:

PLI

  # IMS RESLIB. Example: DFS.V11R1M0.SDFSRESL
  - name: SDFSRESL
    value:

Set `DBB_BUILD` environment variable to configuration directory

The DBB_BUILD environment variable is used by the zBuilder to locate the dbb-build.yaml file which is the first configuration file loaded during the zBuilder build process. This should usually be done as part of a start up shell script.

# zBuilder configuration directory
export DBB_BUILD=/etc/dbb/build

See DBB environment variables for more information on setting up DBB environment variables.

Convert the configuration directory to a Git repository (optional)

Storing zBuilder configuration files in Git has several benefits

Version control - Users can easliy revert to earlier configurations.
Configuration as code - Configuration uses the same workflow as code i.e. review, test in a pull request.
Edit anywhere - Using an internal or external Git provider allows access editing configuration files on workstations or even web editors.

NOTE: This step requires that a z/OS Git client such as IBM Open Enterprise Foundation for z/OS Git already be installed and configured on your system.

Initialize the zBuilder configuration directory as a local git repository

Make sure you are in the zBuilder configuration directory

#> cd $DBB_BUILD
#> git init -b main
Initialized empty Git repository in /etc/dbb/build/.git/

Add zBuilder configuration files to the local Git repository

#> git add .

Commit your changes to Git

#> git commit -m "First commit"

Verify Git status

#>git status
On branch main
nothing to commit, working tree clean

Import the local Git repository to an internal or cloud Git provider

This task generally requires additonal information such as provider type, location and access credentials to perform. Contact your system administator to provide instruction on performing this step.