Setting up the user build

The following steps describe how to manually configure the prerequisites for User Build. In the tutorial Improve your development productivity with Ansible we also show examples for automating many of these steps with Ansible playbooks.

1. Starting from IBM® Wazi 1.1.0, the user build functionality is part of the IBM Z® Open Editor VS Code extension. Install the IBM Z Open Editor VS Code extension.

2. For Z Open Editor to find and upload local copybooks used for the build, configured property groups are required to define the locations. At the moment, these property groups need to be defined in addition to the copybooks rules you define for dbb-zappbuild. To test whether a copybook can be resolved, open a COBOL program in the editor and move your mouse cursor over the copybook name in a COPY statement. If a copybook preview appears, it means that copybook is resolved successfully.

   For more information, see Setting preferences for code editing, Setting property groups, and Configuring your applications with ZAPP files.

3. Install Zowe™ CLI. To install Zowe CLI, see the Installing Zowe CLI section in topic Setting up integrations.

4. (Optional) If you plan to use RSE API to connect to UNIX System Services, install IBM RSE API Plug-in for Zowe CLI. If you plan to use z/OSMF to connect to UNIX System Services, you can skip this step. To install RSE CLI plug-in, see the Installing IBM RSE API Plug-in for Zowe CLI section in topic Setting up integrations.

5. Ensure that you have created Zowe CLI profiles by using a Zowe CLI command or the Zowe Explorer's graphical user interface as described in Interacting with z/OS. If you are using z/OSMF, you also need to create an SSH profile. Zowe SSH profiles support SSH key or password as the authentication method. If you are using RSE API, SSH profile is not required because SSH commands are executed via the RSE REST API.

6. Once you have created more than one profile, you need to specify in the user settings which profile to use for user build. The profile that is currently active will be displayed in the VS Code status bar at the bottom right of the windows.

zAppBuild is the generic build solution for building z/OS® applications that uses Apache Groovy build scripts and DBB APIs. You can refer to zAppBuild as part of your DevOps transformation. The user build tutorial also uses the zAppBuild build solution to run the build.

If your UNIX System Services system does not yet have the ~/dbb-zappbuild folder, you can clone it from the zAppBuild's GitHub repository and find instructions on setting up the appropriate properties files. Copy the dbb-zappbuild folder to your UNIX System Services system.

Important: Make sure dbb-zappbuild/build-conf/datasets.properties is configured to the specific settings of your z/OS system, such as the location of your compliers, before running user build. Refer to documentation above for details.

Important: For the best experience when defining custom encodings for running user builds by using Z Open Editor, install Git on your local computer and make sure it's available on your path.

In order to specify the encoding with which files get uploaded to UNIX System Services during user build, update the .gitattributes file located at the root of the repository. Entries in .gitattributes follow the format below:

pattern attr1 attr2 ...

• pattern describes the files to which the attributes attr1 and attr2 should be assigned. pattern follows fnmatch(3) glob style patterns.

• The attribute for configuring encoding on UNIX System Services is: zos-working-tree-encoding and working-tree-encoding

The following example specifies an encoding of IBM-1047 for all files in the repository with the .cpy file extension:

*.cpy zos-working-tree-encoding=ibm-1047

Learn more about gitattributes.

As the name user settings indicate, these are settings specific to the individual developer running the user build. They specify absolute path name for locations to use on UNIX System Services and high level qualifiers for MVS data sets to use. It is possible to share these settings with multiple users, such as when using a functional user id. You can place the settings described below in VS Code workspace settings so that every developer will use the same values. However, if two developers run user builds at the same time they will use the same file locations and can overwrite each others files leading to incorrect outcomes.

1. Access the User settings. User Settings are unique to each developer.

   • On Windows or Linux®, click File > Preferences > Settings.

   • On macOS, click Code > Preferences > Settings.

   For more information about VS Code User Settings, see VS Code documentation.

2. On the left side, navigate to the Extensions view, and click on IBM Z Open Editor. Alternatively, open the Settings page, use the search bar at the top on the page to search for IBM Z Open Editor, and scroll until you find Userbuild: User Settings.

3. Add the following User settings with your own information:

   Item	Description	Example
   dbbWorkspace	Required. The UNIX System Services location where all files get uploaded to. This folder might contain several application folders you are working on.	/u/user/projects
   dbbHlq	Required. TSO high level qualifier(s) for your project.	USER.SAMPLE
   dbbLogDir	Required. Directory on z/OS where user build logs will be stored.	/u/user/projects/zopeneditor-sample/logs
   dbbDefaultZappProfile	Optional. Name of the ZAPP profile to be used when running a User Build. If not defined User Build will use the 1st defined ZAPP dbb profile.	dbb-profile-2
   localLogDir	Optional. Local directory where User Build logs will be downloaded. Path can be absolute or relative to the workspace of the build file. If not defined, User Build will download logs into a directory in your local workspace called logs	/Users/deb/dbb-logs

   An example, for such an user setting entry:

   "zopeneditor.userbuild.userSettings": {
     "dbbHlq": "USER1.BUILD",
     "dbbLogDir": "/u/user1/projects/logs",
     "dbbWorkspace": "/u/user1/projects"
   },

4. (Optional) Specify which Zowe CLI profiles should be used for User Build. If these are not defined, then the build process will search for default profiles set by Zowe, looking first for an RSE default profile, and if one is not found, it will then search for a default z/OSMF profile. It will also search for default SSH profile.

   In User Settings, navigate to Extensions, and click on IBM Z Open Editor. Scroll down to the Zowe section and add the following profiles with your own information:

   Item	Value
   defaultCliProfile	The name of a valid RSE API or z/OSMF Zowe CLI profile created for the current user.
   defaultSshCliProfile	The name of a valid SSH profile created for the current user. Required for z/OSMF only.

   Note: To view the above settings in the JSON text format click the Open Settings (JSON) button located in the upper right corner of the page.

   View VS Code documentation for more details.

   An example, for such an user setting entry:

   "zopeneditor.zowe": {
     "defaultCliProfile": "sandbox1.zosmf",
     "defaultSshCliProfile": "sandbox1.ssh"
   },

   Double-check that your setting took effect in the editor by reviewing the VS Code status bar listing the currently active profile.

5. (Optional) Enabling and disabling timestamps

   User build log adds a timestamp to each output statement when the "zopeneditor.logger" setting is set to DEBUG. To disable timestamps, change this setting to any other less detailed log level option.

The workspace settings configure build settings shared by all developers. They are specific to the project files being built. These settings are defined in a ZAPP file. The ZAPP file editor has code templates that you can use to quickly get started writing these files. (See Configuring your applications with ZAPP files for details.)

1. Use the code template "ZAPP User Build Profile" to add a new profile to your ZAPP file.

   Notes:

   • Variable substitution with the user settings defined in the previous section is supported. They will be substituted between the brackets ${} as shown in the example below.

   • The --dependencyFile build script argument is only supported for PL/I and COBOL based user builds.

     profiles:
       - name: dbb-userbuild
         type: dbb
         settings:
           application: SAM
           command: "$DBB_HOME/bin/groovyz -DBB_PERSONAL_DAEMON"
           buildScriptPath: "${zopeneditor.userbuild.userSettings.dbbWorkspace}/dbb-zappbuild/build.groovy"
           buildScriptArgs:
             - "--userBuild"
             - "--workspace ${zopeneditor.userbuild.userSettings.dbbWorkspace}"
             - "--application ${application}"
             - "--hlq ${zopeneditor.userbuild.userSettings.dbbHlq}"
             - "--outDir ${zopeneditor.userbuild.userSettings.dbbLogDir}"
             - "--dependencyFile ${dependencyFile}"
           additionalDependencies:
             - application-conf
             - "zapp*"
           logFilePatterns:
             - "${buildFile.basename}.log"
             - "BuildReport.*"
   

   Update the following fields with your own information:

   • application: Starting in Z Open Editor 3.0.0 this variable defines the top-level folder name where User Build will upload the source code. This folder will be created inside the UNIX System Services folder defined under dbbWorkspace User setting. This could be the name of the git repository of the build file and can be referenced in the buildScriptArgs via the ${application} variable.

   • command: Points to the binary executable file that initiates the user build. For example, /bin/groovyz.

   • buildScriptPath: The UNIX System Services location of your dbb-zappbuild/build.groovy file or another build script file.

   • buildScriptArgs:

     • --userBuild - Indicates to DBB that this is a user build

     • --workspace - This setting is the parent workspace used by DBB and will be resolved by the value in the User Settings dbbWorkspace (see below)

     • --application - Application directory path on UNIX System Services relative to workspace buildScriptArgs parameter. The application directory needs to have application-conf folder at the top level. If you opened your local workspace in VS Code such that your program source code with application-conf is nested, then define the application path to reflect that. See example below for more explanation.

     • --hlq - This setting is the TSO high-level qualifier(s) which is used by DBB for data set creation/updating and will be resolved by the value in the User Setting dbbHlq (see below).

     • --outDir - The UNIX System Services location for the log files and a subfolder to the workspace location.

     • --dependencyFile - Optional parameter that can improve the performance of running the build as Z Open Editor will compute all the dependencies of the program via its language server so that Dependency-Based Build does not have to do it. If you omit the parameter, the DBB will do this work potentially slowing down build times. The parameter points to the path to a dependency file on z/OS UNIX System Services that was generated and uploaded by Z Open Editor. The file will contain the list of copybooks and the type of application. If the default parameter ${dependencyFile} is used, user build will automatically generate and place this file in the dbbLogs folder location specified. Otherwise, you can specify the path to a file that already exists on z/OS. In addition, the dependency file will be tagged by default as UTF-8. If a custom encoding is required (e.g. IBM-1047), specify the dependency file encoding in the .gitattributes file by setting the zos-working-tree-encoding value as IBM-1047 or your preferred value.

       *.userbuilddependencies zos-working-tree-encoding=ibm-1047 git-encoding=utf-8

     You can add additional arguments if needed. Refer to Command Line Options Summary for a complete list of optional arguments.

   • additionalDependencies - Other folders or files that are needed for the build, such as the application-conf folder containing the DBB properties files. The path needs to be relative to the build file workspace and reside inside of it. Starting with Z Open Editor 3.0.0 the paths can contain GLOB wildcards.

   • logFilePatterns - With Z Open Editor 3.0.0, you can specify locations relative to ${zopeneditor.userbuild.userSettings.dbbLogDir} for the files to be downloaded. Glob wildcards are supported. If this setting is not defined, all the log files under dbbLogDir get downloaded. User build will also search for matching logs in nested directories under dbbLogDir. To limit the searching to top level only, define your pattern like "${zopeneditor.userbuild.userSettings.dbbLogDir}/my_pattern".

   Defining --application path examples:
   When building zAppBuild application, ensure application-conf folder is at the top level. Sometimes, your git repository will contain a single application with application-conf at the root. In that case, your ZAPP application variable and buildScriptArgs can be the same. Look at the zopeneditor-sample SAM ZAPP configuration above. Other times, your application will be nested inside your git repository. In the example below, MortApp program code is in the folder samples/MortgageApplication (relative to VS Code workspace). The code should be uploaded to the folder ${application}/samples/MortgageApplication so the value of the --application parameter needs to be --application ${application}/samples/MortgageApplication.

     profiles:
   - name: MortgageApplicationBuild
     type: dbb
     settings:
       application: MortApp
       command: "$DBB_HOME/bin/groovyz -DBB_PERSONAL_DAEMON"
       buildScriptPath: "${zopeneditor.userbuild.userSettings.dbbWorkspace}/dbb-zappbuild/build.groovy"
       buildScriptArgs:
         - "--userBuild"
         - "--workspace ${zopeneditor.userbuild.userSettings.dbbWorkspace}"
         - "--application ${application}/samples/MortgageApplication"
         - "--hlq ${zopeneditor.userbuild.userSettings.dbbHlq}"
         - "--outDir ${zopeneditor.userbuild.userSettings.dbbLogDir}"
         - "--dependencyFile ${dependencyFile}"
       additionalDependencies:
         - "samples/MortgageApplication/application-conf"
       logFilePatterns:
         - "${buildFile.basename}.log"
         - "BuildReport.*"

Substitution variables

Starting in Z Open Editor 3.0.0 User Build added several dynamically evaluated variables. These variables allow referencing the file that is being built from all other properties, such as buildScriptArgs, logFilePatterns, or additionalDependencies. For a workspace file zopeneditor-sample/COBOL/SAM1.cbl (e.g. stored in /home/users/user1/dev/cobol/zopeneditor-sample/COBOL/SAM1.cbl). These examples assume you opened zopeneditor-sample as the workspace:

Variable	Description	Example
${buildFile}	Build file name and extension	SAM1.cbl
${buildFile.basename}	Build file name without extension	SAM1
${buildFile.extension}	Build file extension	.cbl
${buildFile.workspaceDir}	Build file directory relative to the workspace. In our example workspace file would be COBOL/SAM1.cbl, so directory would be just COBOL	COBOL
${application}	Will substitute the value of the application setting defined in ZAPP file anywhere in type dbb profile

Note: additionalDependencies and logFilePatterns support GLOB wildcards now. You can define patterns to get files with certain extensions, names, or files in certain directories. This, combined with substitution variables, gives users more flexibility. For example, if we build a file zopeneditor-sample/COBOL/SAM1.cbl stored in /home/users/user1/dev/cobol/zopeneditor-sample/COBOL/SAM1.cbl:

The following log file pattern will only download files named SAM1.log, SAM1.html, and SAM1.json

      logFilePatterns:
      - "${buildFile.basename}.+(log|html|json)" 

In this next example, only files in myfiles directory starting with SAM1 and ending with .dat will be uploaded.

      additionalDependencies:
      - "myfiles/${buildFile.basename}*.dat"

Learn more about how IBM User Build does pattern matching here: https://github.com/isaacs/minimatch

You can use VS Code multi-root workspaces in a limited way for user build.

The limitation is that the ZAPP file, the application-conf directory and the program to be built need to be in the same workspace as the multi-workspace setup. Include files, such as copybooks, can be in other workspaces and Z Open Editor will find them if a valid property group is defined.

If there are multiple ZAPP files in different workspaces, then the ZAPP file in the workspace where the program will be built is used to find the user build profile to use. For property groups, Z Open Editor will combine and use all the property groups defined in all the workspace's ZAPP files to locate the include files.

We have provided a sample multi-root workspace on GitHub that shows a valid setup. See the README document here.

For more information about running a user build, see Building COBOL, PL/I, and HLASM programs with user build.