Re: [edk2-BuildSpecification PATCH] Declare Pre/Post build scripts in [Defines] section

["Zhu, Yonghong" <yonghong.zhu@intel.com>]

Reviewed-by: Yonghong Zhu <yonghong.zhu@intel.com>

Best Regards,
Zhu Yonghong


-----Original Message-----
From: Kinney, Michael D 
Sent: Tuesday, April 18, 2017 9:06 AM
To: edk2-devel@lists.01.org
Cc: Gao, Liming <liming.gao@intel.com>; Zhu, Yonghong <yonghong.zhu@intel.com>; Shaw, Kevin W <kevin.w.shaw@intel.com>
Subject: [edk2-BuildSpecification PATCH] Declare Pre/Post build scripts in [Defines] section

https://bugzilla.tianocore.org/show_bug.cgi?id=483

Add support for PREBUILD and POSTBUILD defines in the [Defines] section of an DSC to declare scripts that are executed before and after normal DSC/FDF file processing.

Cc: Liming Gao <liming.gao@intel.com>
Cc: Yonghong Zhu <yonghong.zhu@intel.com>
Cc: Kevin W Shaw <kevin.w.shaw@intel.com>
Contributed-under: TianoCore Contribution Agreement 1.1
Signed-off-by: Michael Kinney <michael.d.kinney@intel.com>
---
 .../106_post_build_processing.md                   | 61 ++++++++++++++++++++++
 .../82_auto-generation_process.md                  | 33 ++++++++++++
 README.md                                          |  1 +
 SUMMARY.md                                         |  1 +
 4 files changed, 96 insertions(+)
 create mode 100644 10_post-build_imagegen_stage_-_flash/106_post_build_processing.md

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
new file mode 100644
index 0000000..6b48a4f
--- /dev/null
+++ b/10_post-build_imagegen_stage_-_flash/106_post_build_processing.md
@@ -0,0 +1,61 @@
+<!--- @file
+  10.6 Post Build Processing
+
+  Copyright (c) 2008-2017, Intel Corporation. All rights reserved.<BR>
+
+  Redistribution and use in source (original document form) and 'compiled'
+  forms (converted to PDF, epub, HTML and other formats) with or 
+ without  modification, are permitted provided that the following conditions are met:
+
+  1) Redistributions of source code (original document form) must retain the
+     above copyright notice, this list of conditions and the following
+     disclaimer as the first lines of this file unmodified.
+
+  2) Redistributions in compiled form (transformed to other DTDs, converted to
+     PDF, epub, HTML and other formats) must reproduce the above copyright
+     notice, this list of conditions and the following disclaimer in the
+     documentation and/or other materials provided with the distribution.
+
+  THIS DOCUMENTATION IS PROVIDED BY TIANOCORE PROJECT "AS IS" AND ANY 
+ EXPRESS OR  IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 
+ IMPLIED WARRANTIES OF  MERCHANTABILITY AND FITNESS FOR A PARTICULAR 
+ PURPOSE ARE DISCLAIMED. IN NO  EVENT SHALL TIANOCORE PROJECT  BE 
+ LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,  SPECIAL, EXEMPLARY, OR 
+ CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,  PROCUREMENT OF 
+ SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;  OR 
+ BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,  
+ WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE 
+ OR
+  OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, 
+ EVEN IF  ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+-->
+
+
+## 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.
+
+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`.
+
+If the script terminates successfully (exit value of 0), then the 
+**build** command terminates normally.
+
+**********
+**Note:** This entry may be wrapped in a conditional directive. Unlike 
+the `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.
+**********
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 deb1c47..4175552 100644
--- a/8_pre-build_autogen_stage/82_auto-generation_process.md
+++ b/8_pre-build_autogen_stage/82_auto-generation_process.md
@@ -958,6 +958,39 @@ If the `[Defines]` section has the `PCD_VAR_CHECK_GENERATION` entry set to  TRUE, then a binary file will be created in the FV directory for Dynamic and  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 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`.
+
+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.
+
+**********
+**Note:** This entry may be wrapped in a conditional directive that 
+uses the 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.
+**********
+
 ### 8.2.5 Post processing
 
 Once all files are parsed, the build tools will do following work for each EDK diff --git a/README.md b/README.md index 71c4511..3f9ef99 100644
--- a/README.md
+++ b/README.md
@@ -203,3 +203,4 @@ Copyright (c) 2008-2017, Intel Corporation. All rights reserved.
 | 1.27       | Convert to Gitbook                                                                                                                                                                                                                                                                                                                                                  | April 2017    |
 |            | [#471](https://bugzilla.tianocore.org/show_bug.cgi?id=471) Build spec: only copy the "TianoCore" Userextension section into "As Built" INF                                                                                                                                                                                                                          |               |
 |            | [#472](https://bugzilla.tianocore.org/show_bug.cgi?id=472) [Build Spec] Extend macro usage in the !include statements for DSC/FDF files                                                                                                                                                                                                                             |               |
+|            | [#483](https://bugzilla.tianocore.org/show_bug.cgi?id=483) Build Spec: add description for merge Pre-build and Post-build into build process                                                                                                                                                                                                                        |               |
diff --git a/SUMMARY.md b/SUMMARY.md
index fb76372..e374319 100644
--- a/SUMMARY.md
+++ b/SUMMARY.md
@@ -90,6 +90,7 @@
   * [10.3 Build Intermediate Images](10_post-build_imagegen_stage_-_flash/103_build_intermediate_images.md#103-build-intermediate-images)
   * [10.4 Create the FV Image File(s)](10_post-build_imagegen_stage_-_flash/104_create_the_fv_image_files.md#104-create-the-fv-image-files)
   * [10.5 Create the FD image file(s)](10_post-build_imagegen_stage_-_flash/105_create_the_fd_image_files.md#105-create-the-fd-image-files)
+  * [10.6 Post Build 
+ Processing](10_post-build_imagegen_stage_-_flash/106_post_build_proces
+ sing.md#106_post_build_processing)
 * [11 Post-Build ImageGen Stage - Other](11_post-build_imagegen_stage_-_other/README.md#11-post-build-imagegen-stage---other)
   * [11.1 EFI PCI Option ROM Images](11_post-build_imagegen_stage_-_other/111_efi_pci_option_rom_images.md#111-efi-pci-option-rom-images)
   * [11.2 UEFI Applications](11_post-build_imagegen_stage_-_other/112_uefi_applications.md#112-uefi-applications)
--
2.6.3.windows.1