Skip to main content

Build

The Build component of a continuous integration/continuous delivery (CI/CD) pipeline converts the source code into executable binaries. It supports multiple platforms and languages. In mainframe environments, it includes understanding dependencies, compile, link-edit, and unit test. The build can include the inspection of code quality to perform automated validation against a set of coding rules. In some cases, code quality inspection could also be a component of its own in the pipeline.

While many of the steps in the DevOps flow for mainframe applications can be performed using the same tooling used by other development teams, the build step in particular needs to remain on z/OS®. Therefore, this step is primarily handled by IBM® Dependency Based Build (DBB). DBB has intelligent build capabilities where it can not only compile and link z/OS programs to produce executable binaries, but it can also perform different types of builds to support the various steps in an application development workflow. This includes the ability to perform an "impact build", where DBB will only build programs that have changed since the last successful build and the files impacted by those changes, saving time and resources during the development process.

DBB is a set of APIs based on open-source Groovy and adapted to z/OS. This enables you to incorporate your z/OS application builds into the same automated CI/CD pipeline used by other teams. While it is possible to use DBB as a basis to write your own build scripts, we recommend starting with DBB's built-in zBuilder framework as a template for your build, and then customizing it as necessary for your enterprise and applications.

zBuilder facilitates the adoption of DBB APIs for your enterprise and applications via its configuration-based approach, and is available with DBB 3.0.0 and above. Build configurations are defined in YAML files under the control of your build engineering team, and specify build steps and settings for DBB to follow when performing z/OS application builds.

The zAppBuild framework is also available as a Groovy-based alternative to zBuilder. zAppBuild is an open-source DBB build framework.

DBB features​

  • Perform builds on z/OS and persist build results
  • Persist metadata about the builds, which can then be used in subsequent automated CI/CD pipeline steps, as well as informing future DBB builds
  • Can be run from the command line interface, making it easy to integrate into an automated CI/CD pipeline
  • Fully documented on the IBM Docs for DBB

zBuilder features​

  • Included with DBB version 3.0.0 and above
  • Configuration-based framework to simplify the adoption of DBB APIs through YAML configuration files, making builds more maintainable and easier to understand than script-based approaches
  • High-level enterprise-wide settings that can be set for all z/OS application builds
  • Application-level settings for any necessary overrides in individual application builds
  • Out-of-the-box language support for COBOL, PL/I, Assembler, link cards, and more
  • Build lifecycles to support various points across the z/OS application development lifecycle, including:
    • Single file build: Build a single source file in the application
      • This can be done in in a "User Build" context in the IDE for developer testing and debugging.
    • List of files: Build a list of files provided by a text file or build list
    • Full build: Build all buildable files of an application
    • Impact build: Build only the files impacted by source files that have changed since the last successful build or user-provided baselines
    • Pipeline build: Build impacted files with a subsequent task to package the build outputs, and optionally publish them to an artifact repository
    • Metadata (scan) only: Skip the actual building and only scan source files and existing load modules for dependency data
    • Additional build lifecycles listed in zBuilder's Lifecycle samples documentation
  • Support for custom build steps and extensions through configuration
  • Fully documented in the dedicated zBuilder section of the IBM Docs for DBB

Understanding zBuilder concepts, architecture, and customization​

zBuilder is an integrated configuration-based build framework included with IBM Dependency Based Build (DBB) version 3.0.0 and above. It provides a declarative approach to building z/OS applications through YAML configuration files, making it accessible to teams without extensive Groovy scripting knowledge. zBuilder is designed to simplify the adoption of DBB APIs for enterprise and application builds.

Build configurations can span across all applications (enterprise-level) or individual applications (application-level). Enterprise-wide configurations are managed by build engineering teams and define settings such as compiler programs, system libraries, data set allocation attributes, and language-specific build parameters. Application-level configurations are typically managed within the application repository itself to provide customizations specific to that application.

The zBuilder framework is invoked either by a developer using the "User Build" capability in their integrated development environment (IDE), or by an automated CI/CD pipeline. It supports different build lifecycles including impact, full, and single-file builds.

zBuilder uses YAML configuration files to define the build process, which are processed by DBB-provided Java tasks that invoke the DBB toolkit APIs. The build process creates logs and an artifact manifest (BuildReport.json) that can subsequently be used in CI/CD pipeline automation.

zBuilder architecture​

The zBuilder framework uses a configuration-driven architecture with two main configuration levels: enterprise-level configuration and application-level configuration. The following sections provide an overview of the architecture for these two levels, with links to the full zBuilder documentation for further details.

Enterprise-level configuration​

Enterprise-level build configuration resides in a central directory on the z/OS UNIX file system and contains YAML files that define enterprise-wide build settings. This configuration is typically owned and controlled by the central build engineering team.

Key configuration files​

  • dbb-build.yaml: Main entry point to the enterprise-level configuration that defines:

    • Build lifecycles (impact, full, single-file builds, and so on), which each perform a configured set of build tasks
    • Build tasks that are each responsible for a specific unit of work during the build process, and can be referenced in multiple lifecycles
    • Build variables to store values that are referenced by lifecycles and tasks
    • An include element to reference to other YAML files (such as Languages.yaml, described later in this section)

  • Language-specific YAML files (for example, Cobol.yaml, PLI.yaml, and so on): Define language tasks to configure the sources, variables, datasets, and steps needed to build source files for each specific language

  • Languages.yaml: Provides declarations for language task configurations and variables which can be used to build the MortgageApplication sample application that comes with DBB. This file can also be used as a template and customized to work for other enterprise applications.

    • Includes references to the language-specific YAML files (such as Cobol.yaml, PLI.yaml, and so on), and organizes the individual language tasks into a single "stage" (that is, a named collection of tasks) called Languages.
      • Once Languages.yaml is included in dbb-build.yaml, the Languages stage can be referenced there and reused in multiple lifecycle configurations.
    • Initializes variables for datasets used by the language task configurations
tip

It is recommended to version control the directory containing these enterprise-level configuration files via a dedicated Git repository.

Application-level configuration​

Application-level configuration typically resides within each application repository as a dbb-app.yaml file and is owned by the application team. It provides application-specific settings that override or extend enterprise-level configuration.

Typical application settings:

  • Application-specific build parameters
  • Application-specific directory structures
  • File-to-language mappings
  • Custom dependency rules

Note: While application-level configuration is usually owned by the application team, some enterprises require that all build configurations including application configuration remain under the control to the central build engineering team. zBuilder can be configured to manage this approach via an include: application statement in the central dbb-build.yaml build configuration file. This approach is further detailed in zBuilder's include schema documentation.

zBuilder customization capabilities​

To further facilitate zBuilder setup, DBB provides the schema file that validates the YAML configuration files. This can help ensure that all required fields are present and correctly formatted when customizing these configuration files in an IDE. Tutorials on how to set up your IDE to use the schema file are available in the zBuilder documentation on Configuring schema validation in your IDE.

zBuilder's YAML-based configuration approach allows build engineering teams to define and maintain build logic declaratively, making the build process more transparent and easier to maintain compared to script-based approaches. However, zBuilder is also designed to be comprehensive, and additionally supports the following customization capabilities to cover a wider range of build use cases:

  • Conditional logic: Conditions can be implemented in zBuilder's YAML files to:
    • control when a zBuilder task, stage or language step is run.
    • determine if an MVS DD Statement should be allocated.
    • dynamically create a variable value at runtime.
  • Extensibility: For scenarios where additional configuration options are needed to meet specific requirements, zBuilder provides the ability to extend its functionality through custom tasks, lifecycles, and source code scanners.
    • The DBB community repository's zBuilder section also contains several examples of custom tasks and extensions that may either be used as-is, or as examples for creating your own custom tasks.

Next steps with DBB and zBuilder​

Once DBB and zBuilder have been set up and configured to be able to run initial builds of your application from the CLI, you can check out the Implementing pipeline actions page for guidance on how to integrate these tools into your CI/CD pipelines using samples and templates from the DBB community repository.

zAppBuild​

As an alternative to zBuilder, zAppBuild is a Groovy-based generic mainframe application build framework that customers can extend to meet their DevOps needs with DBB. It is available via the IBM-maintained open source zAppBuild repository under the Apache 2.0 license, and is a sample to get you started with building Git-based source code on z/OS UNIX System Services (z/OS UNIX) with DBB. It is made up of property files to configure the build behavior, and Groovy scripts that invoke the DBB toolkit APIs.

Being zBuilder's precursor, zAppBuild shares many of the zBuilder's core concepts and capabilities. A more detailed overview of zAppBuild and its architecture can be found in the zAppBuild repository's documentation on Getting started.

Migrating from zAppBuild to zBuilder​

If you currently use zAppBuild and would like to move to DBB's built-in zBuilder configuration-based framework, DBB 3.0.4 and above includes a utility to migrate from Groovy-based build scripts (such as zAppBuild) to zBuilder YAML files. This utility works by listening in to a Groovy build process and detecting the code scope where DBB APIs are called. Then, it creates a zBuilder language task that contains the steps to build the program.

For more information about the migration process and how to use the migration utility, refer to DBB's documentation page on Migrating Groovy language scripts to zBuilder YAML files.

A tutorial for Migrating a Groovy build script is also available in the DBB documentation.

Resources​

On this page