[edk2-FdfSpecification PATCH 0/2] Allow macros in !include file paths

[edk2-FdfSpecification PATCH 0/2] Allow macros in !include file paths

[Michael Kinney]

* Use macros in !include file paths
  https://bugzilla.tianocore.org/show_bug.cgi?id=350
* Remove illegal white space in FDF file examples

GitHub branch for review:

  https://github.com/mdkinney/edk2-FdfSpecification/tree/Bugzilla_350_MacrosInIncludes
  
GitHub branch compare against latest DRAFT for review:

  https://github.com/tianocore-docs/edk2-FdfSpecification/compare/master...mdkinney:Bugzilla_350_MacrosInIncludes


Michael Kinney (2):
  Use macros in !include file paths
  Remove illegal white space in FDF file examples

 .../22_flash_description_file_format.md            | 21 +++++++++--------
 2_fdf_design_discussion/25_[fv]_sections.md        | 12 +++++-----
 3_edk_ii_fdf_file_format/32_fdf_definition.md      | 26 +++++++++++++---------
 appendix_a_nt32pkg_flash_description_file.md       | 14 ++++++------
 4 files changed, 39 insertions(+), 34 deletions(-)

-- 
2.6.3.windows.1

[edk2-FdfSpecification PATCH 1/2] Use macros in !include file paths

[Michael Kinney]

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

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>
---
 .../22_flash_description_file_format.md            | 21 +++++++++--------
 3_edk_ii_fdf_file_format/32_fdf_definition.md      | 26 +++++++++++++---------
 2 files changed, 26 insertions(+), 21 deletions(-)

diff --git a/2_fdf_design_discussion/22_flash_description_file_format.md b/2_fdf_design_discussion/22_flash_description_file_format.md
index 9c993f4..67c777e 100644
--- a/2_fdf_design_discussion/22_flash_description_file_format.md
+++ b/2_fdf_design_discussion/22_flash_description_file_format.md
@@ -216,19 +216,18 @@ 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 paths listed in the system environment variables,
-`$(WORKSPACE)`, `$(PACKAGES_PATH)`, `$(EFI_SOURCE)`, `$(EDK_SOURCE)`,
-`$(ECP_SOURCE)` in the file name is permitted. If the file is not found after
-testing for the possible combinations, the parsing tools must terminate with
-an error.
+`$(WORKSPACE)`, `$(PACKAGES_PATH)`, `$(EFI_SOURCE)`, `$(EDK_SOURCE)`, and
+`$(ECP_SOURCE)`.  If the file is not found after testing for the possible
+combinations, the parsing tools must terminate with an error.
 
-Files specified by `!include` statements may not contain `!include` statements.
-
-Macros, defined in this FDF file or in the DSC file, are not permitted in the
+Macros, defined in this FDF file or in the DSC 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. 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.
+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.
 
 Statements in !include files must not break the integrity of the FDF file, the
 included file is read in by tools in the exact position of the file, and is
diff --git a/3_edk_ii_fdf_file_format/32_fdf_definition.md b/3_edk_ii_fdf_file_format/32_fdf_definition.md
index 62e54af..e4e9869 100644
--- a/3_edk_ii_fdf_file_format/32_fdf_definition.md
+++ b/3_edk_ii_fdf_file_format/32_fdf_definition.md
@@ -636,16 +636,20 @@ completely new sections of the same section type. If the included file contains
 new sections, then the section being processed in the Platform FDF file is
 considered to have been terminated.
 
-If the filename is a filename, the tools will look for the file in the same
-directory as the FDF file. If the file is not found, and the directory
-containing this FDF file is not the same directory as the directory containing
-the DSC, the tools must attempt to locate the file in the directory tree that
-contains the DSC file. If the filename starts with a "$", then the system
-environment variable will be used to locate the file. If none of these methods
-find the file, and a directory separator is in the filename, the tools will
-attempt to find the file in a WORKSPACE (or directory listed in the
-PACKAGES_PATH) relative path. If the file cannot be found, the build system
-must exit with an appropriate error message.
+If the `<Filename>` contains "$" characters, then macros defined in the DSC
+file, FDF 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 FDF file resides.
+If the file is not found, and the directory containing this FDF file is not the
+same directory as the directory containing the DSC file, the tools must attempt
+to locate the file relaitive to the directory that contains the DSC file.
+
+If none of these methods find the file, 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.
 
@@ -658,4 +662,6 @@ The `!include` file cannot contain additional `!include` statements.
 ```
 !include myPlatform/NvRamDefs.txt
 !include myFeatures.mak
+!include $(WORKSPACE)/PackageDir/Features.dsc
+!include $(MACRO1)/AnotherDir/$(MACRO2)/Features.dsc
 ```
-- 
2.6.3.windows.1

[edk2-FdfSpecification PATCH 2/2] Remove illegal white space in FDF file examples

[Michael Kinney]

Remove space between '$' and '(' for macro usage
Remove space before/after directory separator '/'

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_fdf_design_discussion/25_[fv]_sections.md  | 12 ++++++------
 appendix_a_nt32pkg_flash_description_file.md | 14 +++++++-------
 2 files changed, 13 insertions(+), 13 deletions(-)

diff --git a/2_fdf_design_discussion/25_[fv]_sections.md b/2_fdf_design_discussion/25_[fv]_sections.md
index d35f268..928455c 100644
--- a/2_fdf_design_discussion/25_[fv]_sections.md
+++ b/2_fdf_design_discussion/25_[fv]_sections.md
@@ -278,7 +278,7 @@ FFS file specification syntax is one of the following:
 OR
 
 ```c
-FILE Type $ (NAMED_GUID) [Options] {
+FILE Type $(NAMED_GUID) [Options] {
   SECTION SECTION_TYPE = FileName
   SECTION SECTION_TYPE = FileName
 }
@@ -371,7 +371,7 @@ The following is an example for using additional sections:
 #Encapsulation - Compress
 FILE FOO = 12345678-0000-AAAA-FFFF-0123ABCD12BD {
   SECTION COMPRESS {
-    SECTION PE32 = $ (WORKSPACE) / EdkModulePkg / Core / Dxe / DxeMain.inf
+    SECTION PE32 = $(WORKSPACE)/EdkModulePkg/Core/Dxe/DxeMain.inf
     SECTION VERSION = "1.2.3"
   }
 }
@@ -379,13 +379,13 @@ FILE FOO = 12345678-0000-AAAA-FFFF-0123ABCD12BD {
 # Encapsulation - GUIDED
 FILE FV_IMAGE = 87654321-FFFF-BBBB-2222-9874561230AB {
   SECTION GUIDED gEfiTianoCompressionScheme {
-    SECTION PE32 = $ (WORKSPACE) / EdkModulePkg / Core / Dxe / DxeMain.inf
+    SECTION PE32 = $(WORKSPACE)/EdkModulePkg/Core/Dxe/DxeMain.inf
   }
 }
 
 # LEAF Section
 FILE DXE_CORE = B5596C75-37A2-4b69-B40B-72ABD6DD8708 {
-  SECTION VERSION $ (BUILD_DIR)/$(ARCH)/D6A2CB7F-6A18-4E2F-B43B-9920A733700A-DxeMain.ver
+  SECTION VERSION $(BUILD_DIR)/$(ARCH)/D6A2CB7F-6A18-4E2F-B43B-9920A733700A-DxeMain.ver
 }
 ```
 
@@ -418,12 +418,12 @@ specify a string, that will be used to create an EFI section.
 The `GUIDED` encapsulation section uses one of the following formats.
 
 ```c
-SECTION GUIDED $ (GUID_CNAME) [auth] {
+SECTION GUIDED $(GUID_CNAME) [auth] {
   SECTION EFI_SECTION_TYPE = FILENAME
   SECTION EFI_SECTION_TYPE = "string"
 }
 
-SECTION GUIDED $ (GUID_CNAME) [auth] FILENAME
+SECTION GUIDED $(GUID_CNAME) [auth] FILENAME
 ```
 
 The required argument is the `GUIDED` name followed by an optional "auth"
diff --git a/appendix_a_nt32pkg_flash_description_file.md b/appendix_a_nt32pkg_flash_description_file.md
index 8d7a0ce..89be76c 100644
--- a/appendix_a_nt32pkg_flash_description_file.md
+++ b/appendix_a_nt32pkg_flash_description_file.md
@@ -369,7 +369,7 @@ FILE FREEFORM = PCD(gEfiIntelFrameworkModulePkgTokenSpaceGuid.PcdLogoFile) {
   }
 
 [Rule.Common.PEIM]
-  FILE PEIM = $ (NAMED_GUID){
+  FILE PEIM = $(NAMED_GUID){
     PEI_DEPEX PEI_DEPEX                 Optional $(INF_OUTPUT)/$(MODULE_NAME).depex
     PE32      PE32 Align=4K             $(INF_OUTPUT)/$(MODULE_NAME).efi
     UI        STRING = "$(MODULE_NAME)" Optional
@@ -377,7 +377,7 @@ FILE FREEFORM = PCD(gEfiIntelFrameworkModulePkgTokenSpaceGuid.PcdLogoFile) {
   }
 
 [Rule.Common.DXE_CORE]
-  FILE DXE_CORE = $ (NAMED_GUID) {
+  FILE DXE_CORE = $(NAMED_GUID) {
     COMPRESS PI_STD {
       PE32    PE32                      $(INF_OUTPUT)/$(MODULE_NAME).efi
       UI      STRING = "$(MODULE_NAME)" Optional
@@ -386,7 +386,7 @@ FILE FREEFORM = PCD(gEfiIntelFrameworkModulePkgTokenSpaceGuid.PcdLogoFile) {
   }
 
 [Rule.Common.UEFI_DRIVER]
-  FILE DRIVER = $ (NAMED_GUID) {
+  FILE DRIVER = $(NAMED_GUID) {
     DXE_DEPEX DXE_DEPEX Optional $(INF_OUTPUT)/$(MODULE_NAME).depex
     COMPRESS PI_STD {
       GUIDED {
@@ -398,7 +398,7 @@ FILE FREEFORM = PCD(gEfiIntelFrameworkModulePkgTokenSpaceGuid.PcdLogoFile) {
   }
 
 [Rule.Common.UEFI_DRIVER.TIANOCOMPRESSED]
-  FILE DRIVER = $ (NAMED_GUID) {
+  FILE DRIVER = $(NAMED_GUID) {
     DXE_DEPEX DXE_DEPEX Optional $(INF_OUTPUT)/$(MODULE_NAME).depex
     GUIDED A31280AD-481E-41B6-95E8-127F4C984779 PROCESSING_REQUIRED = TRUE {
       PE32    PE32                      $(INF_OUTPUT)/$(MODULE_NAME).efi
@@ -408,7 +408,7 @@ FILE FREEFORM = PCD(gEfiIntelFrameworkModulePkgTokenSpaceGuid.PcdLogoFile) {
   }
 
 [Rule.Common.DXE_DRIVER]
-  FILE DRIVER = $ (NAMED_GUID) {
+  FILE DRIVER = $(NAMED_GUID) {
     DXE_DEPEX   DXE_DEPEX Optional        $(INF_OUTPUT)/$(MODULE_NAME).depex
     COMPRESS PI_STD {
       GUIDED {
@@ -420,7 +420,7 @@ FILE FREEFORM = PCD(gEfiIntelFrameworkModulePkgTokenSpaceGuid.PcdLogoFile) {
   }
 
 [Rule.Common.DXE_RUNTIME_DRIVER]
-  FILE DRIVER = $ (NAMED_GUID) {
+  FILE DRIVER = $(NAMED_GUID) {
     DXE_DEPEX   DXE_DEPEX Optional        $(INF_OUTPUT)/$(MODULE_NAME).depex
     COMPRESS PI_STD {
       GUIDED {
@@ -432,7 +432,7 @@ FILE FREEFORM = PCD(gEfiIntelFrameworkModulePkgTokenSpaceGuid.PcdLogoFile) {
   }
 
 [Rule.Common.UEFI_APPLICATION]
-  FILE APPLICATION = $ (NAMED_GUID) {
+  FILE APPLICATION = $(NAMED_GUID) {
     COMPRESS PI_STD {
       GUIDED {
         PE32    PE32                      $(INF_OUTPUT)/$(MODULE_NAME).efi
-- 
2.6.3.windows.1

Re: [edk2-FdfSpecification PATCH 0/2] Allow macros in !include file paths

[Zhu, Yonghong]

The patches are good to me.

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

Best Regards,
Zhu Yonghong


-----Original Message-----
From: edk2-devel [mailto:edk2-devel-bounces@lists.01.org] On Behalf Of Michael Kinney
Sent: Saturday, April 08, 2017 10:45 AM
To: edk2-devel@lists.01.org
Subject: [edk2] [edk2-FdfSpecification PATCH 0/2] Allow macros in !include file paths

* Use macros in !include file paths
  https://bugzilla.tianocore.org/show_bug.cgi?id=350
* Remove illegal white space in FDF file examples

GitHub branch for review:

  https://github.com/mdkinney/edk2-FdfSpecification/tree/Bugzilla_350_MacrosInIncludes
  
GitHub branch compare against latest DRAFT for review:

  https://github.com/tianocore-docs/edk2-FdfSpecification/compare/master...mdkinney:Bugzilla_350_MacrosInIncludes


Michael Kinney (2):
  Use macros in !include file paths
  Remove illegal white space in FDF file examples

 .../22_flash_description_file_format.md            | 21 +++++++++--------
 2_fdf_design_discussion/25_[fv]_sections.md        | 12 +++++-----
 3_edk_ii_fdf_file_format/32_fdf_definition.md      | 26 +++++++++++++---------
 appendix_a_nt32pkg_flash_description_file.md       | 14 ++++++------
 4 files changed, 39 insertions(+), 34 deletions(-)

-- 
2.6.3.windows.1

_______________________________________________
edk2-devel mailing list
edk2-devel@lists.01.org
https://lists.01.org/mailman/listinfo/edk2-devel