From 068327cf16e7c95827a1cd5857c6a5f35befdf0f Mon Sep 17 00:00:00 2001 From: Dennis Behm Date: Tue, 15 Aug 2023 16:22:03 +0200 Subject: [PATCH 01/11] Refactor how to locate the application-conf directory Signed-off-by: Dennis Behm --- build-conf/build.properties | 55 ++++++++++++++++++++++++++------- build.groovy | 54 ++++++++++++++++++-------------- utilities/BuildUtilities.groovy | 19 ++++++++++++ 3 files changed, 92 insertions(+), 36 deletions(-) diff --git a/build-conf/build.properties b/build-conf/build.properties index 055e3df3..61e4bcb9 100644 --- a/build-conf/build.properties +++ b/build-conf/build.properties @@ -12,6 +12,9 @@ # # Comma separated list of additional build property files to load # Supports both relative path (to zAppBuild/build-conf/) and absolute path +# +# These properties files expect to contain centrally managed defaults +# buildPropFiles=datasets.properties,dependencyReport.properties,Assembler.properties,BMS.properties,\ MFS.properties,PSBgen.properties,DBDgen.properties,ACBgen.properties,Cobol.properties,\ LinkEdit.properties,PLI.properties,REXX.properties,ZunitConfig.properties,Transfer.properties,\ @@ -20,20 +23,45 @@ CRB.properties # # Comma separated list of default application configuration property files to load # Supports both relative path (to zAppBuild/build-conf/) and absolute path +# +# These properties files expect to contain centrally managed defaults of +# zAppBuild features such as the reporting features +# and also may reference properties files containing configuration +# of the language script configurations such as return codes, deploy types +# +# default: +# applicationDefaultPropFiles=defaultzAppBuildConf.properties +# +# extended sample to set default language script configurations: +# applicationDefaultPropFiles=defaultzAppBuildConf.properties,\ +# application-conf/Cobol.properties applicationDefaultPropFiles=defaultzAppBuildConf.properties # -# file extension that indicates the build file is really a build list or build list filter -buildListFileExt=txt - +# applicationConfDir +# +# required build property that specifies the directory of the +# application specific build configurations for zAppBuild, also known +# as application-conf folder # -# Alternate root directory for application-conf locations. Allows for the deployment of -# the application-conf directories to an alternate location rather in the application repository. -# The expectation is that the root directory will have subfolders for all of the applications built -# by zAppBuild in which the actual application-conf directory is located: +# a sample of the application-conf can be found in +# samples/application-conf +# +# zAppBuild expects a file called application.properties in this directory. +# +# The property also allows for the deployment of +# the application-conf directories to an alternate location rather +# in the application repository. +# +# Default: +# Location within the application repository and resolving the configuration +# based on workspace + application and application-conf +# +# applicationConfDir=${workspace}/${application}/application-conf +# # # Example: Static location on USS -# applicationConfRootDir=/u/build/config/applications +# applicationConfDir=/u/build/config/applications/${application}/application-conf # |- /u/build/config/applications # | |- App1 # | | |- application-conf @@ -41,8 +69,8 @@ buildListFileExt=txt # | |- App2 # | | |- application-conf # -# Example: Application cofig files stored in zAppBuild -# applicationConfRootDir=${zAppBuildDir}/applications +# Example: Application config files stored in zAppBuild +# applicationConfDir=${zAppBuildDir}/applications/${application}/application-conf # |- /u/build/zAppBuild/applications # | |- App1 # | | |- application-conf @@ -50,8 +78,11 @@ buildListFileExt=txt # | |- App2 # | | |- application-conf # -# Defaults to ${workspace} -applicationConfRootDir= +applicationConfDir=${workspace}/${application}/application-conf + +# +# file extension that indicates the build file is really a build list or build list filter +buildListFileExt=txt # # Determine if a subfolder with a timestamp should be created in the buildOutDir location. diff --git a/build.groovy b/build.groovy index ffae506b..ee85b5e9 100644 --- a/build.groovy +++ b/build.groovy @@ -313,7 +313,7 @@ options: /* * populateBuildProperties - loads all build property files, creates properties for command line - * arguments and sets calculated propertied for he build process + * arguments and sets calculated propertied for the build process */ def populateBuildProperties(def opts) { @@ -333,52 +333,59 @@ def populateBuildProperties(def opts) { // load build.properties def buildConf = "${zAppBuildDir}/build-conf" - props.load(new File("${buildConf}/build.properties")) + buildUtils.loadBuildProperties("${buildConf}/build.properties") // load additional build property files + if (opts.v) println "** Loading build-conf settings" if (props.buildPropFiles) { String[] buildPropFiles = props.buildPropFiles.split(',') buildPropFiles.each { propFile -> if (!propFile.startsWith('/')) propFile = "${buildConf}/${propFile}" - if (opts.v) println "** Loading property file ${propFile}" - props.load(new File(propFile)) + buildUtils.loadBuildProperties(propFile) } } // load additional build property files + if (opts.v) println "** Loading default application settings" if (props.applicationDefaultPropFiles) { String[] applicationDefaultPropFiles = props.applicationDefaultPropFiles.split(',') applicationDefaultPropFiles.each { propFile -> if (!propFile.startsWith('/')) propFile = "${buildConf}/${propFile}" - if (opts.v) println "** Loading property file ${propFile}" - props.load(new File(propFile)) + buildUtils.loadBuildProperties(propFile) } } // load application.properties - String appConfRootDir = props.applicationConfRootDir ?: props.workspace - if (!appConfRootDir.endsWith('/')) - appConfRootDir = "${appConfRootDir}/" - - String appConf = "${appConfRootDir}${props.application}/application-conf" - if (opts.v) println "** appConf = ${appConf}" - props.load(new File("${appConf}/application.properties")) - - // load additional application property files - if (props.applicationPropFiles) { - String[] applicationPropFiles = props.applicationPropFiles.split(',') - applicationPropFiles.each { propFile -> - if (!propFile.startsWith('/')) - propFile = "${appConf}/${propFile}" + String appConf = props.applicationConfDir + if (appConf.endsWith('/')) + appConf = appConf.substring(0, appConf.length() - 1) + + if (opts.v) println "** Loading application specific settings" + if (opts.v) println "** applicationConfDir = ${appConf}" + + applicationProperties = "${appConf}/application.properties" + applicationPropertiesFile = new File(applicationProperties) + + if (applicationPropertiesFile.exits()) { + buildUtils.loadBuildProperties(applicationProperties) + + // load additional application property files + if (props.applicationPropFiles) { + String[] applicationPropFiles = props.applicationPropFiles.split(',') + applicationPropFiles.each { propFile -> + if (!propFile.startsWith('/')) + propFile = "${appConf}/${propFile}" - if (opts.v) println "** Loading property file ${propFile}" - props.load(new File(propFile)) + buildUtils.loadBuildProperties(propFile) + } } + } else { + if (opts.v) println "*! Properties file ${applicationProperties} was not found. Build continues." } // load property files from argument list @@ -389,8 +396,7 @@ def populateBuildProperties(def opts) { if (!propFile.startsWith('/')) propFile = "${props.workspace}/${propFile}" - if (opts.v) println "** Loading property file ${propFile}" - props.load(new File(propFile)) + buildUtils.loadBuildProperties(propFile) } } diff --git a/utilities/BuildUtilities.groovy b/utilities/BuildUtilities.groovy index 5963157b..6fb42e7e 100644 --- a/utilities/BuildUtilities.groovy +++ b/utilities/BuildUtilities.groovy @@ -849,6 +849,24 @@ def printLogicalFileAttributes(LogicalFile logicalFile) { } +/** + * method to load build properties into the DBB Build properties. + * + * takes the path to the property file, validates if the property file exist + * + */ + +def loadBuildProperties(String propertyFile) { + File propFile = new File("$propertyFile") + if (propFile.exists()) { + if (opts.v) println "** Loading property file ${propertyFile}" + props.load(propFile) + } else { + println "*!* The specified $propertyFile does not exist. Build exits." + System.exit(1) + } +} + /** * Validates if a buildFile is a zUnit generated test case program * @@ -861,3 +879,4 @@ def isGeneratedzUnitTestCaseProgram(String buildFile) { } return false } + From 096f631410aed06a8adec31b4ac8bfe6d49a4a81 Mon Sep 17 00:00:00 2001 From: Dennis Behm Date: Tue, 15 Aug 2023 16:31:39 +0200 Subject: [PATCH 02/11] Reorganize the print msgs Signed-off-by: Dennis Behm --- build.groovy | 10 ++++++++-- utilities/BuildUtilities.groovy | 1 - 2 files changed, 8 insertions(+), 3 deletions(-) diff --git a/build.groovy b/build.groovy index ee85b5e9..e883c76d 100644 --- a/build.groovy +++ b/build.groovy @@ -333,6 +333,7 @@ def populateBuildProperties(def opts) { // load build.properties def buildConf = "${zAppBuildDir}/build-conf" + if (opts.v) println "** Loading property file ${buildConf}/build.properties" buildUtils.loadBuildProperties("${buildConf}/build.properties") // load additional build property files @@ -342,7 +343,8 @@ def populateBuildProperties(def opts) { buildPropFiles.each { propFile -> if (!propFile.startsWith('/')) propFile = "${buildConf}/${propFile}" - + + if (opts.v) println "** Loading property file ${propFile}" buildUtils.loadBuildProperties(propFile) } } @@ -355,6 +357,7 @@ def populateBuildProperties(def opts) { if (!propFile.startsWith('/')) propFile = "${buildConf}/${propFile}" + if (opts.v) println "** Loading property file ${propFile}" buildUtils.loadBuildProperties(propFile) } } @@ -372,6 +375,7 @@ def populateBuildProperties(def opts) { applicationPropertiesFile = new File(applicationProperties) if (applicationPropertiesFile.exits()) { + if (opts.v) println "** Loading property file ${applicationProperties}" buildUtils.loadBuildProperties(applicationProperties) // load additional application property files @@ -380,7 +384,8 @@ def populateBuildProperties(def opts) { applicationPropFiles.each { propFile -> if (!propFile.startsWith('/')) propFile = "${appConf}/${propFile}" - + + if (opts.v) println "** Loading property file ${propFile}" buildUtils.loadBuildProperties(propFile) } } @@ -396,6 +401,7 @@ def populateBuildProperties(def opts) { if (!propFile.startsWith('/')) propFile = "${props.workspace}/${propFile}" + if (opts.v) println "** Loading property file ${propFile}" buildUtils.loadBuildProperties(propFile) } } diff --git a/utilities/BuildUtilities.groovy b/utilities/BuildUtilities.groovy index 6fb42e7e..fb153d2e 100644 --- a/utilities/BuildUtilities.groovy +++ b/utilities/BuildUtilities.groovy @@ -859,7 +859,6 @@ def printLogicalFileAttributes(LogicalFile logicalFile) { def loadBuildProperties(String propertyFile) { File propFile = new File("$propertyFile") if (propFile.exists()) { - if (opts.v) println "** Loading property file ${propertyFile}" props.load(propFile) } else { println "*!* The specified $propertyFile does not exist. Build exits." From 96aa4e2e18d93ae737f7dce270878e2009df1d30 Mon Sep 17 00:00:00 2001 From: Dennis Behm Date: Tue, 15 Aug 2023 16:33:35 +0200 Subject: [PATCH 03/11] Fix syntax error Signed-off-by: Dennis Behm --- build.groovy | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/build.groovy b/build.groovy index e883c76d..7bc4cceb 100644 --- a/build.groovy +++ b/build.groovy @@ -374,7 +374,7 @@ def populateBuildProperties(def opts) { applicationProperties = "${appConf}/application.properties" applicationPropertiesFile = new File(applicationProperties) - if (applicationPropertiesFile.exits()) { + if (applicationPropertiesFile.exists()) { if (opts.v) println "** Loading property file ${applicationProperties}" buildUtils.loadBuildProperties(applicationProperties) From 2ea6ae6ecc790c81002931eea58431cc3d17d0f7 Mon Sep 17 00:00:00 2001 From: Dennis Behm Date: Thu, 17 Aug 2023 17:40:45 +0200 Subject: [PATCH 04/11] documentation updates to describe the recipe Signed-off-by: Dennis Behm --- build-conf/build.properties | 23 ++++++++++++++++------ docs/HOWTOS.md | 38 ++++++++++++++++++++++++++++++++++++- 2 files changed, 54 insertions(+), 7 deletions(-) diff --git a/build-conf/build.properties b/build-conf/build.properties index 61e4bcb9..8c338360 100644 --- a/build-conf/build.properties +++ b/build-conf/build.properties @@ -6,7 +6,7 @@ ####################################################################### -# Global build properties used by zappbuild +# Global build properties used by zAppBuild # # @@ -14,6 +14,7 @@ # Supports both relative path (to zAppBuild/build-conf/) and absolute path # # These properties files expect to contain centrally managed defaults +# such as system datasets, language script specific settings # buildPropFiles=datasets.properties,dependencyReport.properties,Assembler.properties,BMS.properties,\ MFS.properties,PSBgen.properties,DBDgen.properties,ACBgen.properties,Cobol.properties,\ @@ -24,17 +25,27 @@ CRB.properties # Comma separated list of default application configuration property files to load # Supports both relative path (to zAppBuild/build-conf/) and absolute path # -# These properties files expect to contain centrally managed defaults of -# zAppBuild features such as the reporting features +# These properties files expect to contain centrally managed defaults # and also may reference properties files containing configuration -# of the language script configurations such as return codes, deploy types -# +# of the language script configurations such as return codes, deploy types +# +# See also application-conf/application.properties#applicationPropFiles +# # default: # applicationDefaultPropFiles=defaultzAppBuildConf.properties # # extended sample to set default language script configurations: +# # applicationDefaultPropFiles=defaultzAppBuildConf.properties,\ -# application-conf/Cobol.properties +# default-application-conf/searchPaths.properties,\ +# default-application-conf/scriptMappings.properties,\ +# default-application-conf/Cobol.properties,\ +# default-application-conf/BMS.properties,\ +# default-application-conf/PLI.properties,\ +# default-application-conf/Transfer.properties,\ +# default-application-conf/LinkEdit.properties,\ +# default-application-conf/ZunitConfig.properties +# applicationDefaultPropFiles=defaultzAppBuildConf.properties # diff --git a/docs/HOWTOS.md b/docs/HOWTOS.md index 88c6346b..ea917a44 100644 --- a/docs/HOWTOS.md +++ b/docs/HOWTOS.md @@ -4,6 +4,7 @@ This page collects information to configure and use specific features of zAppBui - [How-to and Frequently Asked Questions](#how-to-and-frequently-asked-questions) - [Signing load modules and program objects](#signing-load-modules-and-program-objects) + - [Reduce necessary **application-conf** configurations within the application repository](#reduce-necessary-application-conf-configurations-within-the-application-repository) ## Signing load modules and program objects @@ -81,4 +82,39 @@ In the output of amblist, locate the user data section and find the data that th DATE USER DATA CSECT: EPSCMORT 06/19/2023 MortgageApplication/a21b6ab0 -``` \ No newline at end of file +``` + +## Reduce necessary **application-conf** configurations within the application repository + +**The 3 properties for loading configuration files to configure the build framework** + +zAppBuild provides 3 properties `buildPropFiles`, `applicationDefaultPropFiles` and the `applicationPropFiles` that each reference a list of properties files, which contain important configuration parameters to configure the build process. The referenced property files are loaded the below order of precedence: + +* `buildPropFiles` managed in [build-conf/build.properties](../build-conf/build.properties) references properties files in [build-conf](../build-conf/) for core zAppBuild settings for the language scripts such as system datasets, naming conventions of build datasets, dataset characteristics and various core properties of the build framework as well, like the reporting facility. +* The property `applicationDefaultPropFiles` is managed in [build-conf/build.properties](../build-conf/build.properties) as well and allows the user to define default application (and also language script specific related) properties, that are centrally managed. +* `applicationPropFiles` is providing application specific settings. This property is managed is within the applications' `application-conf/application.properties` file of the applications [application-conf](../samples/application-conf/) repository. These settings define compiler and link options, deploy types. A sample is provided in [application-conf](../samples/application-conf/). `application-conf/application.properties` also defines the search path configurations for the DBB dependency and impact analysis. The default location for zAppBuild to locate the `application-conf` directory including the `application.properties` file is defined via the `applicationConfDir` setting that is managed in [build-conf/build.properties](../build-conf/build.properties). The default mandates the a `application-conf` directory to be present in the applications' git repository. + +Historically, a lot of application-level build properties are configured and provided via the `applicationPropFiles` within the `application-conf` directory. However, users have reported that zAppBuild is exposing far too many properties to the application team. + +This how-to outlines the changes to manage default application settings more centrally. + +**Centrally defining application related properties** + +Return codes, deploy types or even search path configurations for the DBB dependency and impact analysis can rather be centrally configured especially when application teams follow the similar repository layout and application architecture. This avoids having multiple copies of files with the same definitions spread across multiple locations. + +Loading common properties files or properties via the `applicationDefaultPropFiles` setting, helps to achieve this easily. For instance, the below configuration of `applicationDefaultPropFiles` is loading properties that define the search path configurations, script mappings, and various language settings. + +```properties +applicationDefaultPropFiles=defaultzAppBuildConf.properties,\ +default-application-conf/searchPaths.properties,\ +default-application-conf/scriptMappings.properties,\ +default-application-conf/Cobol.properties,\ +default-application-conf/BMS.properties,\ +default-application-conf/PLI.properties,\ +default-application-conf/Transfer.properties,\ +default-application-conf/LinkEdit.properties,\ +default-application-conf/ZunitConfig.properties +``` +This allows to reduce the necessary definitions within the `application-conf` directory within the application repository, which now only contains the `application.properties` and `file.properties` files to define the application specific settings and exceptions, such as [file properties](../docs/FilePropertyManagement.md#dbb-file-properties) for a particular build file. + +If the application does not need to specify any application specifics, zAppBuild executes the build even without finding an `application-conf/application.properties` at the `applicationConfDir` location. \ No newline at end of file From 2adcca056ab9a11e8a053f88e90a1a670016d0c5 Mon Sep 17 00:00:00 2001 From: Dennis Behm Date: Thu, 17 Aug 2023 17:56:51 +0200 Subject: [PATCH 05/11] properties instead of settings Signed-off-by: Dennis Behm --- build.groovy | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/build.groovy b/build.groovy index 7bc4cceb..03ae50e8 100644 --- a/build.groovy +++ b/build.groovy @@ -337,7 +337,7 @@ def populateBuildProperties(def opts) { buildUtils.loadBuildProperties("${buildConf}/build.properties") // load additional build property files - if (opts.v) println "** Loading build-conf settings" + if (opts.v) println "** Loading zAppBuild build properties" if (props.buildPropFiles) { String[] buildPropFiles = props.buildPropFiles.split(',') buildPropFiles.each { propFile -> @@ -350,7 +350,7 @@ def populateBuildProperties(def opts) { } // load additional build property files - if (opts.v) println "** Loading default application settings" + if (opts.v) println "** Loading default application properties" if (props.applicationDefaultPropFiles) { String[] applicationDefaultPropFiles = props.applicationDefaultPropFiles.split(',') applicationDefaultPropFiles.each { propFile -> @@ -368,7 +368,7 @@ def populateBuildProperties(def opts) { if (appConf.endsWith('/')) appConf = appConf.substring(0, appConf.length() - 1) - if (opts.v) println "** Loading application specific settings" + if (opts.v) println "** Loading application specific properties" if (opts.v) println "** applicationConfDir = ${appConf}" applicationProperties = "${appConf}/application.properties" From b5fec5a41bdcd55220e26809980c68f31b52c544 Mon Sep 17 00:00:00 2001 From: Dennis Behm Date: Thu, 17 Aug 2023 18:09:56 +0200 Subject: [PATCH 06/11] improved documentation Signed-off-by: Dennis Behm --- docs/HOWTOS.md | 20 +++++++++++++++----- 1 file changed, 15 insertions(+), 5 deletions(-) diff --git a/docs/HOWTOS.md b/docs/HOWTOS.md index ea917a44..04552617 100644 --- a/docs/HOWTOS.md +++ b/docs/HOWTOS.md @@ -88,13 +88,13 @@ CSECT: EPSCMORT **The 3 properties for loading configuration files to configure the build framework** -zAppBuild provides 3 properties `buildPropFiles`, `applicationDefaultPropFiles` and the `applicationPropFiles` that each reference a list of properties files, which contain important configuration parameters to configure the build process. The referenced property files are loaded the below order of precedence: +zAppBuild provides 3 properties `buildPropFiles`, `applicationDefaultPropFiles` and the `applicationPropFiles` that each reference a list of properties files, which contain important configuration parameters to configure the build process. The referenced properties files are loaded in the below order of precedence: -* `buildPropFiles` managed in [build-conf/build.properties](../build-conf/build.properties) references properties files in [build-conf](../build-conf/) for core zAppBuild settings for the language scripts such as system datasets, naming conventions of build datasets, dataset characteristics and various core properties of the build framework as well, like the reporting facility. +* `buildPropFiles` managed in [build-conf/build.properties](../build-conf/build.properties) references properties files in the [build-conf](../build-conf/) directory for core zAppBuild settings for the language scripts such as system datasets, naming conventions of build datasets, dataset characteristics and various core properties of the build framework as well, like the reporting features. * The property `applicationDefaultPropFiles` is managed in [build-conf/build.properties](../build-conf/build.properties) as well and allows the user to define default application (and also language script specific related) properties, that are centrally managed. -* `applicationPropFiles` is providing application specific settings. This property is managed is within the applications' `application-conf/application.properties` file of the applications [application-conf](../samples/application-conf/) repository. These settings define compiler and link options, deploy types. A sample is provided in [application-conf](../samples/application-conf/). `application-conf/application.properties` also defines the search path configurations for the DBB dependency and impact analysis. The default location for zAppBuild to locate the `application-conf` directory including the `application.properties` file is defined via the `applicationConfDir` setting that is managed in [build-conf/build.properties](../build-conf/build.properties). The default mandates the a `application-conf` directory to be present in the applications' git repository. +* `applicationPropFiles` is providing application specific settings. This property is managed is within the applications' `application-conf/application.properties` file of the applications' [application-conf](../samples/application-conf/) repository. These settings define compiler and link options, deploy types. A sample is provided in [application-conf](../samples/application-conf/). `application-conf/application.properties` also defines the search path configurations for the DBB dependency and impact analysis as well as the script mappings. The default location for zAppBuild to locate the `application.properties` file within the `application-conf` directory is defined via the `applicationConfDir` setting that is managed in [build-conf/build.properties](../build-conf/build.properties). The default mandates a `application-conf` directory to be present in the applications' git repository. -Historically, a lot of application-level build properties are configured and provided via the `applicationPropFiles` within the `application-conf` directory. However, users have reported that zAppBuild is exposing far too many properties to the application team. +Historically, a lot of application-level properties are configured and provided via the `applicationPropFiles` within the `application-conf` directory. However, users have reported that zAppBuild is exposing far too many properties to the application team. This how-to outlines the changes to manage default application settings more centrally. @@ -105,6 +105,9 @@ Return codes, deploy types or even search path configurations for the DBB depend Loading common properties files or properties via the `applicationDefaultPropFiles` setting, helps to achieve this easily. For instance, the below configuration of `applicationDefaultPropFiles` is loading properties that define the search path configurations, script mappings, and various language settings. ```properties +.. +# Extended list of applicationDefaultPropFiles to include +# default application settings for language scripts applicationDefaultPropFiles=defaultzAppBuildConf.properties,\ default-application-conf/searchPaths.properties,\ default-application-conf/scriptMappings.properties,\ @@ -114,7 +117,14 @@ default-application-conf/PLI.properties,\ default-application-conf/Transfer.properties,\ default-application-conf/LinkEdit.properties,\ default-application-conf/ZunitConfig.properties +.. ``` -This allows to reduce the necessary definitions within the `application-conf` directory within the application repository, which now only contains the `application.properties` and `file.properties` files to define the application specific settings and exceptions, such as [file properties](../docs/FilePropertyManagement.md#dbb-file-properties) for a particular build file. +This allows to reduce the necessary definitions within the `application-conf` directory within the application repository, which now only contains the `application.properties` and `file.properties` files to define the application specific settings and exceptions, such as [file properties](../docs/FilePropertyManagement.md#dbb-file-properties) for a particular build file: + +```properties +# Reduced list of applicationPropFiles +applicationPropFiles=file.properties +``` +You can go that far to merge the properties defined in `file.properties` into the `application.properties` file. If the application does not need to specify any application specifics, zAppBuild executes the build even without finding an `application-conf/application.properties` at the `applicationConfDir` location. \ No newline at end of file From 2328e4e0d1ba2db8245bbf5c094537894c3aa2d7 Mon Sep 17 00:00:00 2001 From: Dennis Behm Date: Fri, 18 Aug 2023 08:31:32 +0200 Subject: [PATCH 07/11] Minor doc updates Signed-off-by: Dennis Behm --- docs/HOWTOS.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/HOWTOS.md b/docs/HOWTOS.md index 04552617..f525ae73 100644 --- a/docs/HOWTOS.md +++ b/docs/HOWTOS.md @@ -92,17 +92,17 @@ zAppBuild provides 3 properties `buildPropFiles`, `applicationDefaultPropFiles` * `buildPropFiles` managed in [build-conf/build.properties](../build-conf/build.properties) references properties files in the [build-conf](../build-conf/) directory for core zAppBuild settings for the language scripts such as system datasets, naming conventions of build datasets, dataset characteristics and various core properties of the build framework as well, like the reporting features. * The property `applicationDefaultPropFiles` is managed in [build-conf/build.properties](../build-conf/build.properties) as well and allows the user to define default application (and also language script specific related) properties, that are centrally managed. -* `applicationPropFiles` is providing application specific settings. This property is managed is within the applications' `application-conf/application.properties` file of the applications' [application-conf](../samples/application-conf/) repository. These settings define compiler and link options, deploy types. A sample is provided in [application-conf](../samples/application-conf/). `application-conf/application.properties` also defines the search path configurations for the DBB dependency and impact analysis as well as the script mappings. The default location for zAppBuild to locate the `application.properties` file within the `application-conf` directory is defined via the `applicationConfDir` setting that is managed in [build-conf/build.properties](../build-conf/build.properties). The default mandates a `application-conf` directory to be present in the applications' git repository. +* `applicationPropFiles` is referencing properties files providing application specific settings. This property is managed in the applications' `application-conf/application.properties` file which is by default located in the applications' [application-conf](../samples/application-conf/) folder. These settings define compiler and link options, deploy types, script mappings and search path configurations for the DBB dependency and impact analysis. A sample is provided in [application-conf](../samples/application-conf/). The default location for zAppBuild to locate the `application.properties` file within the `application-conf` directory is defined via the `applicationConfDir` setting that is managed in [build-conf/build.properties](../build-conf/build.properties). The default mandates am `application-conf` folder including the `application.properties` file to be present in the applications' git repository. -Historically, a lot of application-level properties are configured and provided via the `applicationPropFiles` within the `application-conf` directory. However, users have reported that zAppBuild is exposing far too many properties to the application team. +Historically, a lot of application-level properties are configured and provided via the `applicationPropFiles` within the `application-conf` directory. However, users have reported that zAppBuild is exposing far too many properties to the application team, which also makes it hard to control the update process for new or modified properties. This how-to outlines the changes to manage default application settings more centrally. **Centrally defining application related properties** -Return codes, deploy types or even search path configurations for the DBB dependency and impact analysis can rather be centrally configured especially when application teams follow the similar repository layout and application architecture. This avoids having multiple copies of files with the same definitions spread across multiple locations. +Return codes, deploy types, script mappings or search path configurations for the DBB dependency and impact analysis can be centrally configured especially when application teams follow the similar repository layout and have similar application architectures. It is desireable to avoid having multiple copies of files with the same definitions spread across multiple locations. -Loading common properties files or properties via the `applicationDefaultPropFiles` setting, helps to achieve this easily. For instance, the below configuration of `applicationDefaultPropFiles` is loading properties that define the search path configurations, script mappings, and various language settings. +Loading common properties files via the `applicationDefaultPropFiles` setting, helps to achieve this easily. For instance, the below configuration of `applicationDefaultPropFiles` is loading properties that define the search path configurations, script mappings, and various language settings that can be applied to all applications using this zAppBuild configuration. ```properties .. From d31cc5e111330b012caf1cbcf43feb9fad9ad0e8 Mon Sep 17 00:00:00 2001 From: Dennis Behm Date: Fri, 18 Aug 2023 08:49:12 +0200 Subject: [PATCH 08/11] Minor doc updates Signed-off-by: Dennis Behm --- docs/HOWTOS.md | 4 +++- samples/application-conf/README.md | 6 +++--- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/HOWTOS.md b/docs/HOWTOS.md index f525ae73..1e325cd2 100644 --- a/docs/HOWTOS.md +++ b/docs/HOWTOS.md @@ -127,4 +127,6 @@ applicationPropFiles=file.properties ``` You can go that far to merge the properties defined in `file.properties` into the `application.properties` file. -If the application does not need to specify any application specifics, zAppBuild executes the build even without finding an `application-conf/application.properties` at the `applicationConfDir` location. \ No newline at end of file +If the application does not need to specify any application specifics, zAppBuild executes the build even without finding an `application-conf/application.properties` at the `applicationConfDir` location. + +Please note, that moving property files to the central build framework implementation, is excluding the defined properties in these files from the zAppBuild capability to perform impactBuilds on a property change - see `impactBuildOnBuildPropertyChanges` setting at [default](../build-conf/defaultzAppBuildConf.properties). \ No newline at end of file diff --git a/samples/application-conf/README.md b/samples/application-conf/README.md index c4ff9576..80dd76d8 100644 --- a/samples/application-conf/README.md +++ b/samples/application-conf/README.md @@ -1,12 +1,12 @@ # Application Configuration This folder contains application specific configuration properties used by the zAppBuild Groovy build and utility scripts. It is intended to be copied as a high level folder in the application repository or main application repository if the application source files are distributed across multiple repositories. Once copied to the application repository, users should review the default property files and modify any values as needed. -At the beginning of the build, the `application-conf/application.properties` file will automatically be loaded into the [DBB BuildProperties class](https://www.ibm.com/support/knowledgecenter/SS6T76_1.0.4/scriptorg.html#build-properties-class). Use the `applicationPropFiles` property (see table below) to load additional application property files. +At the beginning of the build, the `application-conf/application.properties` file will automatically be loaded based on the definition of `applicationConfDir` [property](../../build-conf/build.properties) into the [DBB BuildProperties class](https://www.ibm.com/docs/en/dbb/2.0?topic=apis-build-properties#build-properties-class). Use the `applicationPropFiles` property (see table below) to load additional application property files. -Properties can be overwritten on a per file basis through DBB Build Properties file properties. The tables below indicate which properties keys can be overwritten. It is recommended to manage these overwrites in file.properties. +Properties can be overwritten on a per file basis through DBB Build Properties file properties. The tables below indicate which properties keys can be overwritten. It is recommended to manage these overwrites in `file.properties`. ## Property File Descriptions -Since all properties will be loaded into a single static instance of BuildProperties, the organization and naming convention of the *property files* are somewhat arbitrary and targeted more for self documentation and understanding. +Since all properties will be loaded into a single static instance of BuildProperties, the organization and naming convention of the *property files* are somewhat arbitrary and targeted more for self documentation and understanding. Properties related to a language script are prefixed with the name of the language script (i.e `cobol_compileParms`). ### application.properties This property file is loaded automatically at the beginning of the build and contains application specific properties used mainly by `build.groovy` but can also be a place to declare properties used by multiple language scripts. Additional property files are loaded based on the content of the `applicationPropFiles` property. From ef04ac9960364022d549b050bf2aa3a6bacb57cb Mon Sep 17 00:00:00 2001 From: Dennis Behm Date: Thu, 31 Aug 2023 12:08:20 +0200 Subject: [PATCH 09/11] Updated readmes to include reviewer feedback Signed-off-by: Dennis Behm --- docs/HOWTOS.md | 10 ++++++---- samples/application-conf/README.md | 2 +- 2 files changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/HOWTOS.md b/docs/HOWTOS.md index 1e325cd2..dc2475bf 100644 --- a/docs/HOWTOS.md +++ b/docs/HOWTOS.md @@ -92,9 +92,11 @@ zAppBuild provides 3 properties `buildPropFiles`, `applicationDefaultPropFiles` * `buildPropFiles` managed in [build-conf/build.properties](../build-conf/build.properties) references properties files in the [build-conf](../build-conf/) directory for core zAppBuild settings for the language scripts such as system datasets, naming conventions of build datasets, dataset characteristics and various core properties of the build framework as well, like the reporting features. * The property `applicationDefaultPropFiles` is managed in [build-conf/build.properties](../build-conf/build.properties) as well and allows the user to define default application (and also language script specific related) properties, that are centrally managed. -* `applicationPropFiles` is referencing properties files providing application specific settings. This property is managed in the applications' `application-conf/application.properties` file which is by default located in the applications' [application-conf](../samples/application-conf/) folder. These settings define compiler and link options, deploy types, script mappings and search path configurations for the DBB dependency and impact analysis. A sample is provided in [application-conf](../samples/application-conf/). The default location for zAppBuild to locate the `application.properties` file within the `application-conf` directory is defined via the `applicationConfDir` setting that is managed in [build-conf/build.properties](../build-conf/build.properties). The default mandates am `application-conf` folder including the `application.properties` file to be present in the applications' git repository. +* `applicationPropFiles` is referencing properties files providing application-level settings. This property is managed in the applications' `application-conf/application.properties` file which is by default located in the applications' [application-conf](../samples/application-conf/) folder. These settings define compiler and link options, deploy types, script mappings and search path configurations for the DBB dependency and impact analysis. A sample is provided in [application-conf](../samples/application-conf/). The default location for zAppBuild to locate the `application.properties` file within the `application-conf` directory is defined via the `applicationConfDir` setting that is managed in [build-conf/build.properties](../build-conf/build.properties). The default mandates am `application-conf` folder including the `application.properties` file to be present in the applications' git repository. -Historically, a lot of application-level properties are configured and provided via the `applicationPropFiles` within the `application-conf` directory. However, users have reported that zAppBuild is exposing far too many properties to the application team, which also makes it hard to control the update process for new or modified properties. +The `buildPropFiles` and `applicationDefaultPropFiles` settings define enterprise-level, centrally controlled properties, that are used by all applications using the build framework. They are shared across all applications. + +Historically, a lot of application-level properties are configured and provided via the `applicationPropFiles` within the `application-conf` directory. However, users have reported that zAppBuild is exposing far too many properties to the application team, which also makes it hard to control the update process for new or modified properties. For example, most customers prefer to manage compiler and binder options in the centrally controlled properties settings. This how-to outlines the changes to manage default application settings more centrally. @@ -102,7 +104,7 @@ This how-to outlines the changes to manage default application settings more cen Return codes, deploy types, script mappings or search path configurations for the DBB dependency and impact analysis can be centrally configured especially when application teams follow the similar repository layout and have similar application architectures. It is desireable to avoid having multiple copies of files with the same definitions spread across multiple locations. -Loading common properties files via the `applicationDefaultPropFiles` setting, helps to achieve this easily. For instance, the below configuration of `applicationDefaultPropFiles` is loading properties that define the search path configurations, script mappings, and various language settings that can be applied to all applications using this zAppBuild configuration. +Loading common properties files via the `applicationDefaultPropFiles` setting, helps to achieve this easily. For instance, the below configuration of `applicationDefaultPropFiles` is loading properties that define the search path configurations, script mappings, and various language settings (such as compiler or linker options) that can be applied to all applications using zAppBuild. ```properties .. @@ -119,7 +121,7 @@ default-application-conf/LinkEdit.properties,\ default-application-conf/ZunitConfig.properties .. ``` -This allows to reduce the necessary definitions within the `application-conf` directory within the application repository, which now only contains the `application.properties` and `file.properties` files to define the application specific settings and exceptions, such as [file properties](../docs/FilePropertyManagement.md#dbb-file-properties) for a particular build file: +This allows to reduce the necessary definitions within the `application-conf` directory within the application repository, which now only contains the `application.properties` and `file.properties` files to define the application specific settings and exceptions, such as [file properties](../docs/FilePropertyManagement.md#dbb-file-properties) for particular build files: ```properties # Reduced list of applicationPropFiles diff --git a/samples/application-conf/README.md b/samples/application-conf/README.md index 80dd76d8..5791535e 100644 --- a/samples/application-conf/README.md +++ b/samples/application-conf/README.md @@ -1,7 +1,7 @@ # Application Configuration This folder contains application specific configuration properties used by the zAppBuild Groovy build and utility scripts. It is intended to be copied as a high level folder in the application repository or main application repository if the application source files are distributed across multiple repositories. Once copied to the application repository, users should review the default property files and modify any values as needed. -At the beginning of the build, the `application-conf/application.properties` file will automatically be loaded based on the definition of `applicationConfDir` [property](../../build-conf/build.properties) into the [DBB BuildProperties class](https://www.ibm.com/docs/en/dbb/2.0?topic=apis-build-properties#build-properties-class). Use the `applicationPropFiles` property (see table below) to load additional application property files. +At the beginning of the build, the `application-conf/application.properties` file will automatically be searched and loaded if it exists into the into the [DBB BuildProperties class](https://www.ibm.com/docs/en/dbb/2.0?topic=apis-build-properties#build-properties-class). The `application.properties` file is by default searched in the application-conf folder of the application, but this can be modified through the `applicationConfDir` property in [build-conf/build.properties](../../build-conf/build.properties). Use the `applicationPropFiles` property (see table below) to load additional application property files. Properties can be overwritten on a per file basis through DBB Build Properties file properties. The tables below indicate which properties keys can be overwritten. It is recommended to manage these overwrites in `file.properties`. From 8c4321f1dc7faecf5be2fb5f15774f7e45a94682 Mon Sep 17 00:00:00 2001 From: Mathieu Dalbin Date: Fri, 1 Sep 2023 08:43:46 +0200 Subject: [PATCH 10/11] Copyedit of readmes (#5) Signed-off-by: M-DLB --- docs/HOWTOS.md | 26 +++++++++++++------------- samples/application-conf/README.md | 2 +- 2 files changed, 14 insertions(+), 14 deletions(-) diff --git a/docs/HOWTOS.md b/docs/HOWTOS.md index dc2475bf..6bec65fc 100644 --- a/docs/HOWTOS.md +++ b/docs/HOWTOS.md @@ -88,23 +88,23 @@ CSECT: EPSCMORT **The 3 properties for loading configuration files to configure the build framework** -zAppBuild provides 3 properties `buildPropFiles`, `applicationDefaultPropFiles` and the `applicationPropFiles` that each reference a list of properties files, which contain important configuration parameters to configure the build process. The referenced properties files are loaded in the below order of precedence: +zAppBuild proposes 3 properties called `buildPropFiles`, `applicationDefaultPropFiles` and `applicationPropFiles`, each referencing a list of properties files that contain important parameters to configure the build process. The referenced properties files are loaded in the below order of precedence: -* `buildPropFiles` managed in [build-conf/build.properties](../build-conf/build.properties) references properties files in the [build-conf](../build-conf/) directory for core zAppBuild settings for the language scripts such as system datasets, naming conventions of build datasets, dataset characteristics and various core properties of the build framework as well, like the reporting features. -* The property `applicationDefaultPropFiles` is managed in [build-conf/build.properties](../build-conf/build.properties) as well and allows the user to define default application (and also language script specific related) properties, that are centrally managed. -* `applicationPropFiles` is referencing properties files providing application-level settings. This property is managed in the applications' `application-conf/application.properties` file which is by default located in the applications' [application-conf](../samples/application-conf/) folder. These settings define compiler and link options, deploy types, script mappings and search path configurations for the DBB dependency and impact analysis. A sample is provided in [application-conf](../samples/application-conf/). The default location for zAppBuild to locate the `application.properties` file within the `application-conf` directory is defined via the `applicationConfDir` setting that is managed in [build-conf/build.properties](../build-conf/build.properties). The default mandates am `application-conf` folder including the `application.properties` file to be present in the applications' git repository. +1. `buildPropFiles`, managed in [build-conf/build.properties](../build-conf/build.properties), references properties files in the [build-conf](../build-conf/) directory for core zAppBuild settings for the language scripts such as system datasets, naming conventions of build datasets, dataset characteristics and various core properties of the build framework, like the reporting features. +2. `applicationDefaultPropFiles`, managed in [build-conf/build.properties](../build-conf/build.properties) as well, allows the user to define default application-related (and "language script"-related) properties, that are centrally managed and shared across applications. +3. `applicationPropFiles` is referencing properties files providing application-level settings. This property is managed in the applications' `application-conf/application.properties` file which is by default located in the applications' [application-conf](../samples/application-conf/) folder. These settings define compiler and link options, deploy types, script mappings and search path configurations for the DBB dependency and impact analysis. A sample is provided in [application-conf](../samples/application-conf/). The location where zAppBuild searches for the `application.properties` file is defined via the `applicationConfDir` setting that is managed in [build-conf/build.properties](../build-conf/build.properties). The default location mandates an `application-conf` folder including the `application.properties` file to be present in the applications' git repository. -The `buildPropFiles` and `applicationDefaultPropFiles` settings define enterprise-level, centrally controlled properties, that are used by all applications using the build framework. They are shared across all applications. +The `buildPropFiles` and `applicationDefaultPropFiles` settings define enterprise-level, centrally-controlled properties, that are used by all applications using the build framework. They are shared across all applications. -Historically, a lot of application-level properties are configured and provided via the `applicationPropFiles` within the `application-conf` directory. However, users have reported that zAppBuild is exposing far too many properties to the application team, which also makes it hard to control the update process for new or modified properties. For example, most customers prefer to manage compiler and binder options in the centrally controlled properties settings. +Historically, a lot of application-level properties are configured and provided via the `applicationPropFiles` within the `application-conf` directory. However, users have reported that zAppBuild is exposing far too many properties to the application team, which also makes it hard to control the update process for new or modified properties. For example, most customers prefer to manage compiler and binder options in the centrally-controlled settings. -This how-to outlines the changes to manage default application settings more centrally. +This how-to outlines the changes to centrally manage default application settings. -**Centrally defining application related properties** +**Centrally defining application-related properties** Return codes, deploy types, script mappings or search path configurations for the DBB dependency and impact analysis can be centrally configured especially when application teams follow the similar repository layout and have similar application architectures. It is desireable to avoid having multiple copies of files with the same definitions spread across multiple locations. -Loading common properties files via the `applicationDefaultPropFiles` setting, helps to achieve this easily. For instance, the below configuration of `applicationDefaultPropFiles` is loading properties that define the search path configurations, script mappings, and various language settings (such as compiler or linker options) that can be applied to all applications using zAppBuild. +Loading common properties files via the `applicationDefaultPropFiles` setting helps to achieve this easily. For instance, the below configuration of `applicationDefaultPropFiles` is loading properties that define the search path configurations, script mappings, and various language settings (such as compiler or linker options) that can be applied to all applications using zAppBuild. ```properties .. @@ -121,14 +121,14 @@ default-application-conf/LinkEdit.properties,\ default-application-conf/ZunitConfig.properties .. ``` -This allows to reduce the necessary definitions within the `application-conf` directory within the application repository, which now only contains the `application.properties` and `file.properties` files to define the application specific settings and exceptions, such as [file properties](../docs/FilePropertyManagement.md#dbb-file-properties) for particular build files: +This allows to reduce the necessary definitions within the `application-conf` directory of the application repository. This `application-conf` directory now only contains the `application.properties` and `file.properties` files to define the application-specific settings and exceptions, such as [file properties](../docs/FilePropertyManagement.md#dbb-file-properties) for particular build files: ```properties # Reduced list of applicationPropFiles applicationPropFiles=file.properties ``` -You can go that far to merge the properties defined in `file.properties` into the `application.properties` file. +Potentially, you could go farther and merge the properties defined in `file.properties` into the `application.properties` file. -If the application does not need to specify any application specifics, zAppBuild executes the build even without finding an `application-conf/application.properties` at the `applicationConfDir` location. +If an application doesn't need to specify any application-specific settings, there is no need to create an `application.properties` file and zAppBuild will execute the build, even without finding the `application.properties` file expected at the `applicationConfDir` location. -Please note, that moving property files to the central build framework implementation, is excluding the defined properties in these files from the zAppBuild capability to perform impactBuilds on a property change - see `impactBuildOnBuildPropertyChanges` setting at [default](../build-conf/defaultzAppBuildConf.properties). \ No newline at end of file +Please note that moving property files to the central build framework implementation disables the capability to perform impactBuilds on a property change for these properties - see `impactBuildOnBuildPropertyChanges` setting at [default](../build-conf/defaultzAppBuildConf.properties). diff --git a/samples/application-conf/README.md b/samples/application-conf/README.md index 5791535e..6bea3757 100644 --- a/samples/application-conf/README.md +++ b/samples/application-conf/README.md @@ -1,7 +1,7 @@ # Application Configuration This folder contains application specific configuration properties used by the zAppBuild Groovy build and utility scripts. It is intended to be copied as a high level folder in the application repository or main application repository if the application source files are distributed across multiple repositories. Once copied to the application repository, users should review the default property files and modify any values as needed. -At the beginning of the build, the `application-conf/application.properties` file will automatically be searched and loaded if it exists into the into the [DBB BuildProperties class](https://www.ibm.com/docs/en/dbb/2.0?topic=apis-build-properties#build-properties-class). The `application.properties` file is by default searched in the application-conf folder of the application, but this can be modified through the `applicationConfDir` property in [build-conf/build.properties](../../build-conf/build.properties). Use the `applicationPropFiles` property (see table below) to load additional application property files. +At the beginning of the build, the `application.properties` file will automatically be searched and loaded if it exists into the [DBB BuildProperties class](https://www.ibm.com/docs/en/dbb/2.0?topic=apis-build-properties#build-properties-class). The `application.properties` file is by default searched in the `application-conf` folder of the application, but this can be configured through the `applicationConfDir` property in [build-conf/build.properties](../../build-conf/build.properties). Use the `applicationPropFiles` property (see table below) to load additional application property files. Properties can be overwritten on a per file basis through DBB Build Properties file properties. The tables below indicate which properties keys can be overwritten. It is recommended to manage these overwrites in `file.properties`. From cb5fd44ba23884ee2031697e22499e4c45673bef Mon Sep 17 00:00:00 2001 From: Dennis Behm Date: Fri, 1 Sep 2023 08:54:00 +0200 Subject: [PATCH 11/11] Minor docu update Signed-off-by: Dennis Behm --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index d788a125..2d0c3b51 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@ zAppBuild is a generic build solution for building z/OS applications using Apach For instructions on how to contribute enhancements and bug fixes to zAppBuild, please read the [Contributions Guidelines](CONTRIBUTIONS.md). ## How zAppBuild works -The zAppBuild repository is intended to be cloned to a single location on Unix Systems Services (USS) and used to build all of your z/OS applications. This is done by simply copying the supplied `application-conf` folder (located in the [samples folder](samples)) to the application source repository you want to build and then verify/update the contained default configuration property values to ensure they meet the build requirements of your application. See the included [MortgageApplication](samples/MortgageApplication) sample for an example of an application that has been modified to be built by zAppBuild. +The zAppBuild repository is intended to be cloned to a single location on Unix Systems Services (USS) and used to build all of your z/OS applications. Global configuration properties are configured in the properties files in the [build-conf](build-conf/) directory. Specifying application-level properties is done by simply copying the supplied `application-conf` folder (located in the [samples folder](samples)) to the application source repository you want to build and then verify/update the contained default configuration property values to ensure they meet the build requirements of your application. See the included [MortgageApplication](samples/MortgageApplication) sample for an example of an application that has been modified to be built by zAppBuild. **IMPORTANT** : The [datasets.properties](build-conf/datasets.properties) must be configured for your build machine before executing a build! See [build-conf/README.md](build-conf/README.md) for more information.