* [edk2-DscSpecification PATCH] Use macros in !include file paths
@ 2017-04-12 19:13 Michael Kinney
2017-04-12 19:13 ` Michael Kinney
0 siblings, 1 reply; 3+ messages in thread
From: Michael Kinney @ 2017-04-12 19:13 UTC (permalink / raw)
To: edk2-devel; +Cc: Liming Gao, Yonghong Zhu, Kevin W Shaw
https://bugzilla.tianocore.org/show_bug.cgi?id=351
GitHub branch for review:
https://github.com/mdkinney/edk2-DscSpecification/tree/Bugzilla_351_MacrosInIncludes
GitHub branch compare against latest DRAFT for review:
https://github.com/tianocore-docs/edk2-DscSpecification/compare/master...mdkinney:Bugzilla_351_MacrosInIncludes?w=1
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>
Michael Kinney (1):
Use macros in !include file paths
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(-)
--
2.6.3.windows.1
^ permalink raw reply [flat|nested] 3+ messages in thread
* [edk2-DscSpecification PATCH] Use macros in !include file paths
2017-04-12 19:13 [edk2-DscSpecification PATCH] Use macros in !include file paths Michael Kinney
@ 2017-04-12 19:13 ` Michael Kinney
2017-04-13 2:21 ` Zhu, Yonghong
0 siblings, 1 reply; 3+ messages in thread
From: Michael Kinney @ 2017-04-12 19:13 UTC (permalink / raw)
To: edk2-devel; +Cc: Liming Gao, Yonghong Zhu, Kevin W Shaw
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
^ permalink raw reply related [flat|nested] 3+ messages in thread
* Re: [edk2-DscSpecification PATCH] Use macros in !include file paths
2017-04-12 19:13 ` Michael Kinney
@ 2017-04-13 2:21 ` Zhu, Yonghong
0 siblings, 0 replies; 3+ messages in thread
From: Zhu, Yonghong @ 2017-04-13 2:21 UTC (permalink / raw)
To: Kinney, Michael D, edk2-devel@lists.01.org
Cc: Gao, Liming, Shaw, Kevin W, Zhu, Yonghong
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
^ permalink raw reply related [flat|nested] 3+ messages in thread
end of thread, other threads:[~2017-04-13 2:22 UTC | newest]
Thread overview: 3+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2017-04-12 19:13 [edk2-DscSpecification PATCH] Use macros in !include file paths Michael Kinney
2017-04-12 19:13 ` Michael Kinney
2017-04-13 2:21 ` Zhu, Yonghong
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox