Re: [edk2-DscSpecification PATCH] Use macros in !include file paths

["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: Thursday, April 13, 2017 3:14 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-DscSpecification PATCH] Use macros in !include file paths

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

The EBNF already allows !include statements to use
$(MACRO) values in the file path.  This change updates the description and examples for !include statements to allow the use of macros and specific environment variables in !include file paths.

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>
---
 2_dsc_overview/22_build_description_file_format.md    | 19 +++++++++----------
 .../33_platform_dsc_definition.md                     | 19 ++++++++++++-------
 README.md                                             |  3 ++-
 3 files changed, 23 insertions(+), 18 deletions(-)

diff --git a/2_dsc_overview/22_build_description_file_format.md b/2_dsc_overview/22_build_description_file_format.md
index ebe4cca..d32c9b0 100644
--- a/2_dsc_overview/22_build_description_file_format.md
+++ b/2_dsc_overview/22_build_description_file_format.md
@@ -230,9 +230,15 @@ definition, contain complete sections, or combination of both.
 The argument of this statement is a filename. The file is relative to the  directory that contains this DSC file, and if not found the tool must attempt  to find the file relative to the paths listed in the system environment -variables, `$(WORKSPACE)`, `$(EFI_SOURCE)`, `$(EDK_SOURCE)`, `$(ECP_SOURCE)` in -the file name is permitted. If the file is still not found, the parsing tools -must terminate with an error.
+variables `$(WORKSPACE)`, `$(EFI_SOURCE)`, `$(EDK_SOURCE)`, and 
+`$(ECP_SOURCE)`. If the file is still not found, the parsing tools must 
+terminate with an error.
+
+Macros, defined in this file, are permitted in the path or file name of 
+the !include statement, as these files are included prior to processing 
+the file for macros. The system environment variables `$(WORKSPACE)`, 
+`$(EDK_SOURCE)`, `$(EFI_SOURCE)`, and `$(ECP_SOURCE)` may also be used; 
+only these system environment variables are permitted to start the path of the included file.
 
 Files specified by `!include` statements may not contain `!include` statements.
 
@@ -241,13 +247,6 @@ the included file is read in by tools in the exact position of the file, and is  functionally equivalent of copying the contents of the included file and  inserting (paste) the content into the DSC file.
 
-Macros, defined in this file, are not permitted in the path or file name of the -!include statement, as these files are included prior to processing the file -for macros. If the path starts with a "$" character, then one of the system -environment variables, `$(WORKSPACE)`, `$(EDK_SOURCE)`, `$(EFI_SOURCE)`, or -`$(ECP_SOURCE)` is being used; only these system environment variables are -permitted to start the path of the included file.
-
 The following examples show the valid usage of the `!include` statement.
 
 ```ini
diff --git a/3_edk_ii_dsc_file_format/33_platform_dsc_definition.md b/3_edk_ii_dsc_file_format/33_platform_dsc_definition.md
index 8119ee4..1ed3f7e 100644
--- a/3_edk_ii_dsc_file_format/33_platform_dsc_definition.md
+++ b/3_edk_ii_dsc_file_format/33_platform_dsc_definition.md
@@ -655,18 +655,21 @@ section that the `!include` statement resides, or it may contain completely new  sections. If the included file starts with a section header, then the section  being processed in the Platform DSC file is considered to have been terminated.
 
+If the `<Filename>` contains "$" characters, then macros defined in the 
+DSC file and the system environment variables, `$(WORKSPACE)`, 
+`$(EDK_SOURCE)`, `$(EFI_SOURCE)`, and `$(ECP_SOURCE)` are substituted into `<Filename>`.
+
+The tools look for `<Filename>` relative to the directory the DSC file resides.
+If the file is not found, and a directory separator is in `<Filename>`, 
+the tools attempt to find the file in a WORKSPACE (or a directory 
+listed in the
+PACKAGES_PATH) relative path. If the file cannot be found, the build 
+system must exit with an appropriate error message.
+
 The `!include` file cannot contain additional `!include` statements.
 
 Statements in the include file are permitted to override previous definitions  as well as to define new entries.
 
-If the filename is a filename, the tools will look for the file in the same -directory as the DSC file. If the filename starts with a "$", then the system -environment variable will be used to locate the file. If neither of these -methods find the file, and a directory separator is in the filename, the tools -will attempt to find the file in an EDK II Package . If the file cannot be -found, the build system must exit with an appropriate error message.
-
 #### Prototype
 
 `<IncludeStatement> ::= <TS> "!include" <MTS> <Filename> <EOL>` @@ -676,6 +679,8 @@ found, the build system must exit with an appropriate error message.
 ```
 !include MyPlatformPkg/feature_pcds.mak  !include MyFeatures.mak
+!include $(WORKSPACE)/PackageDir/Features.dsc
+!include $(MACRO1)/AnotherDir/$(MACRO2)/Features.dsc
 ```
 
 **********
diff --git a/README.md b/README.md
index 7a87ccf..64bf2b7 100644
--- a/README.md
+++ b/README.md
@@ -176,4 +176,5 @@ Copyright (c) 2006-2017, Intel Corporation. All rights reserved.
 |            | Update the DSC_SPECIFICATION version to 0x0001001A                                                                                                                                                                                                                                           |                |
 |            | Revised WORKSPACE wording for updated build system that can handle packages located outside of the WORKSPACE directory tree (refer to the TianoCore.org/ EDKII website for additional instructions on setting up a development environment).                                                 |                |
 |            | Added new system environment variables used by the build system.                                                                                                                                                                                                                             |                |
-| 1.27       | Convert to GitBooks                                                                                                                                                                                                                                                                          | March 2017     |
+| 1.27       | Convert to GitBooks                                                                                                                                                                                                                                                                          | April 2017     |
+|            | [#351](https://bugzilla.tianocore.org/show_bug.cgi?id=351) [DSC Spec] Extend macro usage in the !include statement                                                                                                                                                                           |                |
--
2.6.3.windows.1