Building z/OS C++ programs with VS Code
Introduction
This document outlines a modern approach for developing and building C++ applications on IBM z/OS using Visual Studio Code. By leveraging IBM Z Open Editor and Dependency Based Build (DBB), development teams can improve productivity through familiar tooling and automated builds.
This solution enables organizations to adopt agile practices, reduce onboarding time, and streamline the integration of mainframe C++ development into broader DevOps workflows.
Overview
This guide offers a practical solution for building C++ applications on IBM z/OS using **Visual Studio Code**, **IBM Z Open Editor**, and **IBM Dependency Based Build (DBB)**. This approach enables teams to begin mainframe C++ development using modern tooling and workflows that includes:
1. VS Code Configuration
1. DBB Build Framework Configuration
1. Build Process Tips
1. General Considerations
Prerequisites and additional references:
Before you begin, ensure the following:
- Configure Z Open Editor's User Build feature:
- Enable a VS Code connection to z/OS environment using Zowe
- Additional references:
- RSE API:
VS Code Setup
The first step is to configure the IBM Z Open Editor VS Code extension.
From the Z Open Editor's VS Code settings page, enable "Always Show Commands".
When enabled, this feature displays the DBB "IBM User Build" and "IBM User Build with full upload" choices when you right click on a C++ source file.
Next, configure the application's "Z Open Editor" zapp.yaml file to include any C++ header files needed for a build.
The `zapp.yaml` file is a configuration file used by Z Open Editor to define application-specific settings, such as dependencies and build configurations. Below is an example `zapp.yaml` file configured for DBB v3 zBuilder that defines the path of a C++ application's header path under the "additionalDependencies" section.
yaml
profiles:
- name: zBuilder-userbuild
type: dbb
settings:
command: "$DBB_HOME/bin/dbb build"
lifecycle: user
lifecycleArgs:
- "--hlq ${zopeneditor.userbuild.userSettings.dbbHlq}"
additionalDependencies:
- "dbb-app.yaml"
- "**/header/*.h"
logFilePatterns:
- "${buildFile.basename}-*.log"
- "BuildReport.*"
On the first build or when any `additionalDependencies` file(s) are changed, select "full upload" to initialize or refresh the current users' z/OS Unix System Services build workspace folder. In the above example, _all_ C++ header files with an extension of `.h` are copied to the workspace. Replace `**/headers/*.h` with the header path of the application.
Dependency Based Build Setup
DBB's two build frameworks, zBuilder and dbb-zappbuild, support building and linking C++ programs from VS Code.
zBuilder
The DBB zBuilder is an integrated configuration-based build framework for building z/OS applications with DBB. Build configuration is defined in YAML files under the control of the build engineering team. The underlying implementation comprises DBB provided Java tasks that use the existing DBB toolkit APIs.
As of DBB V3.0.2, zBuilder includes a sample CPP.yaml Language script to compile and link C++ programs. Review and customize the sample to meet your needs. Also ensure the task variable dependencySearchPath references the application's header path.
dbb-zappbuild
dbb-zappbuild is a generic build solution for building z/OS applications using Apache Groovy build scripts and IBM Dependency Based Build (DBB) APIs.
As of Ver 3.11.0 dbb-zappbuild includes a sample CPP.groovy build script. Follow the standard configuration to include this groovy script in your build.
Build a C++ program with VS Code
For the first build of a C++ program, select the "IBM User Build with __full upload__" command as shown in the "VS Code Setup" section above. Otherwise, select the "IBM User Build" choice.
Z Open Editor will copy all related files to the z/OS Unix System Services workspace and invoke the DBB build command.
Below is an example of a user build log. It shows the file upload phase that includes header files and the zBuilder results. A "clean" status means the build was successful.
Limitations/Considerations
While this workaround offers a reliable solution, the initial build of a large C++ application may take longer. This is because all header files must be copied to the Unix System Services (USS) environment during the first build.
However, once the product fully supports this feature, only the dependent header files required for each specific C++ program will be copied, significantly reducing build time.
Conclusion
Using Visual Studio Code with the IBM Z Open Editor and Dependency Based Build provides a practical and flexible solution for developing and building C++ applications on z/OS today. Although the current process requires copying all header files during the initial build, this approach enables teams to do C++ development with IBM Developer for z/OS Enterprise Edition (IDzEE). By following the outlined setup steps and leveraging either zBuilder or dbb-zappbuild, developers can efficiently integrate modern tooling with traditional mainframe environments and streamline their C++ build workflows.