Re: [Patch] Build Spec: Add multi-arg support to PREBUILD/POSTBUILD

["Gao, Liming" <liming.gao@intel.com>]

Reviewed-by: Liming Gao <liming.gao@intel.com>

>-----Original Message-----
>From: Zhu, Yonghong
>Sent: Wednesday, August 30, 2017 5:01 PM
>To: edk2-devel@lists.01.org
>Cc: Gao, Liming <liming.gao@intel.com>; Kinney, Michael D
><michael.d.kinney@intel.com>; Shaw, Kevin W <kevin.w.shaw@intel.com>
>Subject: [Patch] Build Spec: Add multi-arg support to PREBUILD/POSTBUILD
>
>fixes: https://bugzilla.tianocore.org/show_bug.cgi?id=669
>Cc: Liming Gao <liming.gao@intel.com>
>Cc: Michael Kinney <michael.d.kinney@intel.com>
>Cc: Kevin W Shaw <kevin.w.shaw@intel.com>
>Contributed-under: TianoCore Contribution Agreement 1.1
>Signed-off-by: Yonghong Zhu <yonghong.zhu@intel.com>
>---
> .../106_post_build_processing.md                   | 22 +++++++++++-----------
> .../82_auto-generation_process.md                  | 14 +++++++-------
> README.md                                          |  1 +
> 3 files changed, 19 insertions(+), 18 deletions(-)
>
>diff --git a/10_post-build_imagegen_stage_-
>_flash/106_post_build_processing.md b/10_post-build_imagegen_stage_-
>_flash/106_post_build_processing.md
>index 6b48a4f..7046ca3 100644
>--- a/10_post-build_imagegen_stage_-_flash/106_post_build_processing.md
>+++ b/10_post-build_imagegen_stage_-
>_flash/106_post_build_processing.md
>@@ -32,22 +32,21 @@
>
> ## 10.6 Post Build Processing
>
> If the `[Defines]` section of the DSC file contains a `POSTBUILD = entry`
> statement, prior to exiting, the script specified in the `POSTBUILD` statement
>-is executed. If the script file is not found, the **build** command exits with
>-an appropriate error message. If the script fails, it must terminate with a
>-non-zero exit code and the **build** command terminates with the exit
>value
>-from the post-build script. The script is required to generate error messages
>-that provide the reason for the termination.
>+is executed. The entry of `POSTBUILD` support multiple arguments. And Tool
>+will convert arguments that are `WORKSPACE` or `PACKAGES_PATH` relative
>paths
>+to absolute paths. If the script file is not found, the **build** command
>+exits with an appropriate error message. If the script fails, it must terminate
>+with a non-zero exit code and the **build** command terminates with the
>exit
>+value from the post-build script. The script is required to generate error
>+messages that provide the reason for the termination.
>
> All of the command line options passed into the **build** command are also
>-passed  into the script along with the command line options for `TARGET`,
>-`ARCH`, and `TOOL_CHAIN_TAG`. The values for `TARGET`, `ARCH`, and
>-`TOOL_CHAIN_TAG` are from the command line options passed into the
>**build**
>-command. If these values are not passed into the **build** command, then
>they
>-are retrieved from `target.txt`.
>+passed into the script along with the options for `TARGET`, `ARCH`,
>+`TOOL_CHAIN_TAG`, `ACTIVE_PLATFORM`, `Conf Directory`, and `build
>target`.
>
> If the script terminates successfully (exit value of 0), then the **build**
> command terminates normally.
>
> **********
>@@ -55,7 +54,8 @@ command terminates normally.
> `PREBUILD` entry, there are no restrictions on the MACRO values used in a
> conditional directive.
> **********
> **Note:** Quotes are needed when the script's additional options are
>present.
> Quotes are also required if the path to the post-build command contains
>space
>-or special characters.
>+or special characters. Quotes may be used for arguments that have spaces or
>+special characters.
> **********
>diff --git a/8_pre-build_autogen_stage/82_auto-generation_process.md
>b/8_pre-build_autogen_stage/82_auto-generation_process.md
>index 7bca366..671a7d5 100644
>--- a/8_pre-build_autogen_stage/82_auto-generation_process.md
>+++ b/8_pre-build_autogen_stage/82_auto-generation_process.md
>@@ -983,22 +983,21 @@ DynamicEx PCD HII Variable checking.
> #### 8.2.4.13 Pre Build Processing
>
> The DSC file is parsed after the tool meta-data files. If the `[Defines]`
> section of the DSC file contains a `PREBUILD = entry` statement, processing
> of the DSC file is suspended and the script specified in the `PREBUILD`
>-statement is executed. If the script file is not found, the **build** command
>+statement is executed. The entry of `PREBUILD` support multiple arguments.
>And
>+Tool will convert arguments that are `WORKSPACE` or `PACKAGES_PATH`
>relative
>+paths to absolute paths. If the script file is not found, the **build**
>command
> exits with an appropriate error message. If the script fails, it must terminate
> with a non-zero exit code and the **build** command terminates with the
>exit
> value from the pre-build script. The script is required to generate error
> messages that provide the reason for the termination.
>
> All of the command line options passed into the **build** command are also
>-passed  into the script along with the command line options for `TARGET`,
>-`ARCH`, and `TOOL_CHAIN_TAG`. The values for `TARGET`, `ARCH`, and
>-`TOOL_CHAIN_TAG` are from the command line options passed into the
>**build**
>-command. If these values are not passed into the **build** command, then
>they
>-are retrieved from `target.txt`.
>+passed into the script along with the options for `TARGET`, `ARCH`,
>+`TOOL_CHAIN_TAG`, `ACTIVE_PLATFORM`, `Conf Directory`, and `build
>target`.
>
> If the script terminates successfully (exit value of 0), parsing of the DSC
> file continues, and build tools may retrieve environment variables that have
> been updated by the script.
>
>@@ -1008,11 +1007,12 @@ value of the `TOOL_CHAIN_TAG` determined
>earlier. Using a MACRO value other
> than `$(TOOL_CHAIN_TAG)` is prohibited, as the DSC file has not been
>processed
> at the time the ENTRY was found.
> **********
> **Note:** Quotes are needed when the script's additional options are
>present.
> Quotes are also required if the path to the pre-build command contains space
>-or special characters.
>+or special characters. Quotes may be used for arguments that have spaces or
>+special characters.
> **********
>
> #### 8.2.4.14 NMAKE Command line limitation handling
>
> `NMAKE` is limited to command-line length of 4096 characters.  Due to the
>large
>diff --git a/README.md b/README.md
>index 1ef0c00..52abb6a 100644
>--- a/README.md
>+++ b/README.md
>@@ -214,5 +214,6 @@ Copyright (c) 2008-2017, Intel Corporation. All rights
>reserved.
> |            | [#480](https://bugzilla.tianocore.org/show_bug.cgi?id=480) Build
>spec: add description for Override PCD value on the command line
>|               |
> |            | [#523](https://bugzilla.tianocore.org/show_bug.cgi?id=523) Build
>spec: add EBNF for the --pcd syntax in the Section D.4
>|               |
> |            | [#517](https://bugzilla.tianocore.org/show_bug.cgi?id=517) Build
>spec: chapter 5.2.2 Guided Tools add description for Pkcs7Sign tool and
>BrotliCompress tool
>|               |
> |            | [#481](https://bugzilla.tianocore.org/show_bug.cgi?id=481) Build
>Spec: add clarification for not used Pcd that build tool will not do additional
>checks on its value
>|               |
> |            | [#518](https://bugzilla.tianocore.org/show_bug.cgi?id=518) Build
>Spec: Update Precedence of PCD Values
>|               |
>+|            | [#669](https://bugzilla.tianocore.org/show_bug.cgi?id=669) Build
>Spec: Add multi-arg support to PREBUILD/POSTBUILD
>|               |
>--
>2.6.1.windows.1