Merge pull request #176 from IBM/develop

Release zAppBuild 2.3.0

.gitattributes

@@ -16,3 +16,4 @@
 *.asm zos-working-tree-encoding=ibm-1047 git-encoding=utf-8
 *.jcl zos-working-tree-encoding=ibm-1047 git-encoding=utf-8
 *.mac zos-working-tree-encoding=ibm-1047 git-encoding=utf-8
+*.json zos-working-tree-encoding=utf-8 git-encoding=utf-8

BUILD.md

@@ -14,7 +14,7 @@ $DBB_HOME/bin/groovyz build.groovy --workspace /u/build/repos --application app1
 ```
 Since we are still missing a build target or calculated build option, the build will run successfully but not actually build any programs.  
 
-## Common Invocation Examples
+## Common Pipeline Invocation Examples
 
 **Build one program**
 ```
@@ -32,6 +32,10 @@ $DBB_HOME/bin/groovyz build.groovy --workspace /u/build/repos --application app1
 ```
 $DBB_HOME/bin/groovyz build.groovy --workspace /u/build/repos --application app1 --outDir /u/build/out --hlq BUILD.APP1 --impactBuild
 ```
+**Build only the changes which will be merged back to the main build branch. No calculation of impacted files.**
+```
+$DBB_HOME/bin/groovyz build.groovy --workspace /u/build/repos --application app1 --outDir /u/build/out --hlq BUILD.APP1 --mergeBuild
+```
 **Only scan source files in the application to collect dependency data without actually creating load modules**
 ```
 $DBB_HOME/bin/groovyz build.groovy --workspace /u/build/repos --application app1 --outDir /u/build/out --hlq BUILD.APP1 --fullBuild --scanOnly
@@ -40,19 +44,45 @@ $DBB_HOME/bin/groovyz build.groovy --workspace /u/build/repos --application app1
 ```
 $DBB_HOME/bin/groovyz build.groovy --workspace /u/build/repos --application app1 --outDir /u/build/out --hlq BUILD.APP1 --fullBuild --scanAll
 ```
+**Build programs with the 'Test' Options for debugging**
+```
+$DBB_HOME/bin/groovyz build.groovy --workspace /u/build/repos --application app1 --outDir /u/build/out --hlq BUILD.APP1 --debug --impactBuild
+```
 **Use Code Coverage Headless Collector in zUnit Tests and specify parameters through command-line options (which override properties defined in ZunitConfig.properties)**
 ```
 $DBB_HOME/bin/groovyz build.groovy --workspace /u/build/repos --application app1 --outDir /u/build/out --hlq BUILD.APP1 --fullBuild --cc --cch localhost --ccp 8009 --cco "e=CCPDF"
 ```
- **Build one program using a [user build dependency file](samples/userBuildDependencyFile) predefining dependency information to skip DBB scans and dependency resolution.**
+## Common User Build Invocation Examples
+**Build one program**
+
+Build a single program in a user build context. Does not require a repository client connection to the DBB WebApp.
+```
+$DBB_HOME/bin/groovyz build.groovy --workspace /u/build/repos --application app1 --outDir /u/build/out --hlq BUILD.APP1 --userBuild app1/cobol/epsmpmt.cbl
+```
+**Build one program using a [user build dependency file](samples/userBuildDependencyFile) predefining dependency information to skip DBB scans and dependency resolution.**
+
+Build a single program in a user build context and provide the dependency information from the IDE to skip scanning the files on USS. Useful when building on IBM ZD&T or Wazi Sandbox environments. 
 ```
 $DBB_HOME/bin/groovyz build.groovy --workspace /u/build/repos --application app1 --outDir /u/build/out --hlq BUILD.APP1 --userBuild --dependencyFile userBuildDependencyFile.json app1/cobol/epsmpmt.cbl
 ```
- **Build only the changes which will be merged back to the main build branch. No calculation of impacted files.**
+**Build one program with Debug Options**
+
+Build a single program in a user build context including the configured TEST compile time options.
+```
+$DBB_HOME/bin/groovyz build.groovy --workspace /u/build/repos --application app1 --debug --outDir /u/build/out --hlq BUILD.APP1 --userBuild app1/cobol/epsmpmt.cbl
 ```
-$DBB_HOME/bin/groovyz build.groovy --workspace /u/build/repos --application app1 --outDir /u/build/out --hlq BUILD.APP1 --mergeBuild
+**Build (Process) the zUnit Config file and start a debug session**
+
+Process the zUnit bzucfg file in a user build context and initialize a debug session of the application under test. Requires the program under test to be compiled with Debug Options.
+```
+$DBB_HOME/bin/groovyz build.groovy --workspace /u/build/repos --application app1 --debugzUnitTestcase --outDir /u/build/out --hlq BUILD.APP1 --userBuild app1/testcfg/epsmpmt.bzucfg
 ```
+**Build (Process) the zUnit Config file and collect code coverage data**
 
+Process the zUnit bzucfg file in a user build context and direct the code coverage report to the user. Requires the program under test to be compiled with Debug Options.
+```
+$DBB_HOME/bin/groovyz build.groovy --workspace /u/build/repos --application app1 --ccczUnit --outDir /u/build/out --hlq BUILD.APP1 --userBuild app1/testcfg/epsmpmt.bzucfg
+```
 ## Command Line Options Summary
 ```
 $DBB_HOME/bin/groovyz <zAppBuildLocation>/build.groovy [options] buildfile
@@ -112,6 +142,7 @@ web application credentials
 
 IDz/ZOD User Build options
  -u,--userBuild               Flag indicating running a user build
+ -dz,--debugzUnitTestcase     Flag indicating to start a debug session for zUnit Test configurations as part of user build  
  -e,--errPrefix <arg>         Unique id used for IDz error message datasets
  -df,--dependencyFile <arg>   Absolute or relative path (from workspace) to user build JSON file containing dependency information.
 

build-conf/Assembler.properties

@@ -47,3 +47,15 @@ dbb.DependencyScanner.languageHint=ASM :: **/*.asm, **/*.mac
 #
 # additional libraries for linkEdit SYSLIB concatenation, comma-separated, see definitions in application-conf
 # assembler_linkEditSyslibConcatenation=
+
+# assembler_dependenciesDatasetMapping - an optional dbb property mapping to map dependencies to different target datasets
+#  this property is used when dependencies are copied to the different build libraries, e.q dclgens going into to a dedicated library
+#  note, that a dependency file needs to match a single rule, target dataset definitions need to exist
+#
+#  sample:
+#   assembler_dependenciesDatasetMapping = assembler_macroPDS :: **/macro/*.mac
+#   assembler_dependenciesDatasetMapping = assembler_cpyPDS :: **/copy/*.asmcpy
+#
+#  default copies all dependencies into the dependency dataset definition which was previously passed to the utilities/BuildUitilities.copySourceFiles method
+#   assembler_dependenciesDatasetMapping = assembler_macroPDS :: **/* 
+assembler_dependenciesDatasetMapping = assembler_macroPDS :: **/*

build-conf/Cobol.properties

@@ -70,7 +70,6 @@ dbb.DependencyScanner.languageHint=COB :: **/*.cbl, **/*.cpy
 # The following filter excludes CICS and LE Library references.
 dbb.LinkEditScanner.excludeFilter = ${SDFHLOAD}.*, ${SCEELKED}.*
 
-
 #
 # additional libraries for compile SYSLIB concatenation, comma-separated, see definitions in application-conf
 # cobol_compileSyslibConcatenation=
@@ -79,7 +78,23 @@ dbb.LinkEditScanner.excludeFilter = ${SDFHLOAD}.*, ${SCEELKED}.*
 # additional libraries for linkEdit SYSLIB concatenation, comma-separated, see definitions in application-conf
 # cobol_linkEditSyslibConcatenation=
 
+# cobol_dependenciesAlternativeLibraryNameMapping - an *optional* map to define target dataset definition for alternate include libraries
+#  this property is used to 
+#   * copy files the to mapped dataset definition (PLEASE NOTE! This setting takes precendence over cobol_dependenciesDatasetMapping)
+#   * defining additional allocations in the compile step
+#
+#  note that the SYSLIB is defaulted to the dataset definition 'cobol_cpyPDS' and is not required to be set here
+#  sample: cobol_dependenciesAlternativeLibraryNameMapping = [MYFILE: 'cobol_myfilePDS', DCLGEN : 'cobol_dclgenPDS']
+cobol_dependenciesAlternativeLibraryNameMapping=
 
-
-
-
+# cobol_dependenciesDatasetMapping - an optional dbb property mapping to map dependencies to different target datasets
+#  this property is used when dependencies are copied to the different build libraries, e.q dclgens going into to a dedicated library
+#  note, that a dependency file needs to match a single rule
+#
+#  sample:
+#   cobol_dependenciesDatasetMapping = cobol_cpyPDS :: **/copybook/*.cpy
+#   cobol_dependenciesDatasetMapping = cobol_dclgenPDS :: **/dclgens/*.cpy
+#
+#  default copies all dependencies into the dependency dataset definition which was previously passed to the utilities/BuildUitilities.copySourceFiles method
+#   cobol_dependenciesDatasetMapping = cobol_cpyPDS :: **/* 
+cobol_dependenciesDatasetMapping = cobol_cpyPDS :: **/*

build-conf/PLI.properties

@@ -26,6 +26,13 @@ pli_BMS_PDS=${team}.BMS.COPY
 # PL/I load data sets
 pli_loadPDS=${hlq}.LOAD
 
+# PL/I test case source data sets
+pli_testcase_srcPDS=${hlq}.TEST.PLI
+
+#
+# PL/I test case load data sets
+pli_testcase_loadPDS=${hlq}.TEST.LOAD
+
 #
 # List the data sets that need to be created and their creation options
 pli_srcDatasets=${pli_srcPDS},${pli_incPDS},${pli_objPDS},${pli_dbrmPDS}
@@ -37,6 +44,14 @@ pli_loadOptions=cyl space(1,1) dsorg(PO) recfm(U) blksize(32760) dsntype(library
 pli_tempOptions=cyl space(5,5) unit(vio) blksize(80) lrecl(80) recfm(f,b) new
 pli_listOptions=cyl space(5,5) unit(vio) blksize(0) lrecl(137) recfm(v,b) new
 
+# List the data sets for tests that need to be created and their creation options
+pli_test_srcDatasets=${pli_testcase_srcPDS}
+pli_test_srcOptions=cyl space(1,1) lrecl(80) dsorg(PO) recfm(F,B) dsntype(library)
+
+pli_test_loadDatasets=${pli_testcase_loadPDS}
+pli_test_loadOptions=cyl space(1,1) dsorg(PO) recfm(U) blksize(32760) dsntype(library)
+
+
 # Allocation of SYSMLSD Dataset used for extracting Compile Messages to Remote Error List
 pli_compileErrorFeedbackXmlOptions=tracks space(200,40) dsorg(PS) blksize(27998) lrecl(16383) recfm(v,b) new keep
 
@@ -50,4 +65,24 @@ dbb.DependencyScanner.languageHint=PLI :: **/*.pli, **/*.inc, **/*.cpy
 
 #
 # additional libraries for linkEdit SYSLIB concatenation, comma-separated, see definitions in application-conf
-# pli_linkEditSyslibConcatenation=
+# pli_linkEditSyslibConcatenation=
+
+# pli_dependenciesAlternativeLibraryNameMapping - an *optional* map to define target dataset definition for alternate include libraries
+#  this property is used to 
+#   * copy files the to mapped dataset definition (this setting takes precendence over pli_dependenciesDatasetMapping)
+#   * defining additional allocations in the compile step
+#  note that the SYSLIB is defaulted to the dataset definition 'pli_cpyPDS' and is not required to be set here
+#  sample: pli_dependenciesAlternativeLibraryNameMapping = [MYFILE: 'pli_myfilePDS', DCLGEN : 'pli_dclgenPDS']
+pli_dependenciesAlternativeLibraryNameMapping=
+
+# pli_dependenciesDatasetMapping - an optional dbb property mapping to map dependencies to different target datasets
+#  this property is used when dependencies are copied to the different build libraries, e.q dclgens going into to a dedicated library
+#  note, that a dependency file needs to match a single rule
+#
+#  sample:
+#   pli_dependenciesDatasetMapping = pli_incPDS :: **/includes/*.cpy
+#   pli_dependenciesDatasetMapping = pli_dclgenPDS :: **/dclgens/*.cpy
+#
+#  default copies all dependencies into the dependency dataset definition which was previously passed to the utilities/BuildUitilities.copySourceFiles method
+#   pli_dependenciesDatasetMapping = pli_incPDS :: **/* 
+pli_dependenciesDatasetMapping = pli_incPDS :: **/*