Re: [Patch] DSC 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] DSC 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>
>---
> 2_dsc_overview/23_[defines]_section_processing.md | 22
>++++++++++++++--------
> 3_edk_ii_dsc_file_format/35_[defines]_section.md  | 12 ++++++++++--
> README.md                                         |  1 +
> 3 files changed, 25 insertions(+), 10 deletions(-)
>
>diff --git a/2_dsc_overview/23_[defines]_section_processing.md
>b/2_dsc_overview/23_[defines]_section_processing.md
>index 96d02a0..95c2893 100644
>--- a/2_dsc_overview/23_[defines]_section_processing.md
>+++ b/2_dsc_overview/23_[defines]_section_processing.md
>@@ -53,18 +53,22 @@ The format for entries in this section is:
>
> `Name = Value`
>
> If the `PREBUILD` and/or `POSTBUILD` entries are specified, value must be a
> tool that can be executed.  If the value contains space characters, then the
>-value must be a quoted string. The `build` tool suspends processing of the
>DSC
>-file if the `PREBUILD` entry is present, calls the script, and either terminates
>-or continues processing the DSC file depending on the exit code from the
>script.
>-If the `POSTBUILD` entry is present, prior to the successful `build` exit, the
>-script is called. If the script fails (non-zero exit code from the script)
>-`build` terminates immediately using the exit code returned from the script,
>-otherwise, `build` terminates normally. The author of the script is responsible
>-for ensuring that the script terminates with a non-zero exit code when it fails.
>+value must be a quoted string. The `PREBUILD` and `POSTBUILD` enty
>support
>+multiple arguments, and tool will convert the arguments that are
>WORKSPACE or
>+PACKAGES_PATH relative paths to absolute paths. Quotes may be used for
>arguments
>+that have spaces or special characters. The `build` tool suspends processing
>of
>+the DSC file if the `PREBUILD` entry is present, calls the script, and either
>+terminates or continues processing the DSC file depending on the exit code
>from
>+the script. If the `POSTBUILD` entry is present, prior to the successful `build`
>+exit, the script is called. If the script fails (non-zero exit code from the
>+script) `build` terminates immediately using the exit code returned from the
>+script, otherwise, `build` terminates normally. The author of the script is
>+responsible for ensuring that the script terminates with a non-zero exit code
>+when it fails.
>
> All defined elements of the DSC file's `[Defines]` section are valid when
> parsing the FDF file. The these elements must be treated as Macros when
>using
> them in other sections of the DSC and FDF file, as in $(PLATFORM_NAME).
>
>@@ -114,10 +118,12 @@ item is required.
> | `RFC_LANGUAGES`               | Optional    | RFC4646 Language code list       | A
>semi-colon ";" separated list of RFC4646 Language codes (EDK II Modules)
>used during the generation of only a set, rather than all, UNICODE languages
>during the StrGather AutoGen phase. The list must be encapsulated in double
>quotes.
>|
> | `ISO_LANGUAGES`               | Optional    | ISO-639-2 Language code list     | A
>non-separated list of three character ISO 639-2 Language codes (EDK
>Components) used during the generation of only a set, rather than all,
>UNICODE languages during the StrGather AutoGen phase. The list must be
>encapsulated in double quotes.
>|
> | `VPD_TOOL_GUID`               | Optional    | Registry Format GUID             | When
>this element is present, the build process will be interrupted during the
>AutoGen stage in order to call an external program, named by GUID that must
>also be defined in the Conf/tools_def.txt file using a tool code name of
>VPDTOOL. Refer to the EDK II Build specification for additional information.
>|
> | `PCD_INFO_GENERATION`         | Optional    | TRUE or FALSE                    | If
>present, and set to TRUE, this flag will generate PCD information in the Pcd
>Database.
>|
> | `PCD_VAR_CHECK_GENERATION`    | Optional    | TRUE or FALSE                    |
>If present and set to TRUE, this flag will generate the variable validation table
>binary file in the build output FV floder. If not present ro set to FALSE, then
>the binary file will not be generated.
>|
>+| `PREBUILD`                    | Optional    | String of script with arguments  | If
>present, build tool will call the script of this statement to execute.
>|
>+| `POSTBUILD`                   | Optional    | String of script with arguments  | If
>present, build tool will call the script of this statement to execute.
>|
>
> [^1]: WORKSPACE refers to the combination of the directories specified in the
> WORKSPACE system environment variable and the PACKAGES_PATH system
>environment
> variable.
>
>diff --git a/3_edk_ii_dsc_file_format/35_[defines]_section.md
>b/3_edk_ii_dsc_file_format/35_[defines]_section.md
>index fa6ee60..8950b80 100644
>--- a/3_edk_ii_dsc_file_format/35_[defines]_section.md
>+++ b/3_edk_ii_dsc_file_format/35_[defines]_section.md
>@@ -123,12 +123,12 @@ The `!include` statement may be used in a
>`[Defines]` section.
>                    [<TS> "ISO_LANGUAGES" <Eq> <Iso6392List> <EOL>] [<TS>
>                    "TIME_STAMP_FILE" <Eq> <Filename> <EOL>]
>                    [<TS> "VPD_TOOL_GUID" <Eq> <RegistryFormatGUID>
>                    <EOL>]
>                    [<TS> "PCD_VAR_CHECK_GENERATION" <Eq> <TF> <EOL>]
>-                   [<TS> "PREBUILD" <Eq> {<AsciiString>} {<QuotedString>} <EOL>]
>-                   [<TS> "POSTBUILD" <Eq> {<AsciiString>} {<QuotedString>} <EOL>]
>+                   [<TS> "PREBUILD" <Eq> <Script> <EOL>]
>+                   [<TS> "POSTBUILD" <Eq> <Script> <EOL>]
>                    [<TS> <AddressStmts>]
>                    <IncludeStatement>*
>                    <MacroDefinition>*
> <SpecValue>    ::= {<HexVersion>} {(0-9)+ "." (0-9)+}
> <SkuUiName>    ::= <Word> [<FS> <Word>]*
>@@ -146,10 +146,12 @@ The `!include` statement may be used in a
>`[Defines]` section.
> <Ext639>       ::= <Iso639-2Code>
> <Rfc4646Code>  ::= RFC4646 Format Language code
>                    <Iso639-2
> Code>          ::= ISO 639-2 Format Language code
> <TF>           ::= {"TRUE"} {"FALSE"}
>+<Script>       ::= [<Interpreter>] <Filename> [<Options>]
>+<Options>      ::= {<AsciiString>} {<QuotedString>}
> ```
>
> #### Parameters
>
> **_SpecVal_**
>@@ -204,10 +206,16 @@ SHRINK).
> **_FLASH_DEFINITION Filename_**
>
> The FDF filename must be either relative to the directory that contains this
> DSC file, or it can be absolute, as well as relative to the WORKSPACE .
>
>+**_Interpreter_**
>+
>+An interpreter is a computer program that directly executes, i.e. Python,
>+instructions written in a programming or scripting language, without
>previously
>+compiling them into a machine language program.
>+
> #### Example
>
> ```ini
> [Defines]
>   PLATFORM_NAME           = NT32
>diff --git a/README.md b/README.md
>index 94386af..270857e 100644
>--- a/README.md
>+++ b/README.md
>@@ -182,5 +182,6 @@ Copyright (c) 2006-2017, Intel Corporation. All rights
>reserved.
> |            | [#353](https://bugzilla.tianocore.org/show_bug.cgi?id=353) Build
>spec: Allow nested includes in DSC and FDF files
>|                |
> |            | [#521](https://bugzilla.tianocore.org/show_bug.cgi?id=521) DSC
>spec: add clarification for mixed PCD usage in the DSC spec
>|                |
> |            | [#519](https://bugzilla.tianocore.org/show_bug.cgi?id=519) DSC
>Spec: update Precedence of PCD Values
>|                |
> |            | [#584](https://bugzilla.tianocore.org/show_bug.cgi?id=584) DSC
>Spec: Update the DSC_SPECIFICATION version to 0x0001001B or 1.27
>|                |
> |            | [#645](https://bugzilla.tianocore.org/show_bug.cgi?id=645) DSC
>Spec: Remove Restriction on Using NULL in [LibraryClasses] Section
>|                |
>+|            | [#669](https://bugzilla.tianocore.org/show_bug.cgi?id=669) DSC
>Spec: Add multi-arg support to PREBUILD/POSTBUILD
>|                |
>--
>2.6.1.windows.1