Re: [edk2-devel] [Patch] Document: Update DSC spec to add Packages section

["Liming Gao" <liming.gao@intel.com>]

I have two comments. 

1. Remove FeatureFlagExpress. This is not required. 
2. Please use real example, such as UefiCpuPkg. Don't use IA32FamilyCpuPkg as the example. 

Thanks
Liming
>-----Original Message-----
>From: devel@edk2.groups.io [mailto:devel@edk2.groups.io] On Behalf Of
>Bob Feng
>Sent: Monday, November 25, 2019 1:50 PM
>To: devel@edk2.groups.io
>Cc: Gao, Liming <liming.gao@intel.com>
>Subject: [edk2-devel] [Patch] Document: Update DSC spec to add Packages
>section
>
>BZ: https://bugzilla.tianocore.org/show_bug.cgi?id=2383
>
>Update DSC spec to add Packages section.
>
>The purpose of this section is to involve the packages,
>which are not included by any component, into the platform.
>In this way, more FeatureFlagPcd or FixedAtBuildPcd
>can be used in platform DSC file or FDF file,
>even if those PCDs are not used in any component.
>
>Signed-off-by: Bob Feng <bob.c.feng@intel.com>
>Cc: Liming Gao <liming.gao@intel.com>
>---
> .../213_[packages]_section_processing.md      | 70 ++++++++++++++
> .../313_[packages]_section.md                 | 93 +++++++++++++++++++
> README.md                                     |  1 +
> SUMMARY.md                                    |  2 +
> 4 files changed, 166 insertions(+)
> create mode 100644
>2_dsc_overview/213_[packages]_section_processing.md
> create mode 100644 3_edk_ii_dsc_file_format/313_[packages]_section.md
>
>diff --git a/2_dsc_overview/213_[packages]_section_processing.md
>b/2_dsc_overview/213_[packages]_section_processing.md
>new file mode 100644
>index 0000000..7a73031
>--- /dev/null
>+++ b/2_dsc_overview/213_[packages]_section_processing.md
>@@ -0,0 +1,70 @@
>+<!--- @file
>+  2.13 [Packages] Section Processing
>+
>+  Copyright (c) 2019, 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.
>+
>+-->
>+
>+## 2.13 [Packages] Section Processing
>+
>+The `[Packages]` section lists the EDK II declaration files. The purpose of this
>+section is to involve the packages, which are not included by any component,
>into
>+the platform. In this way, more FeatureFlagPcd or FixedAtBuildPcd can be
>used in
>+platform DSC file or FDF file, even if those PCDs are not used in any
>component.
>+
>+Packages listed in architectural sections must not be listed in common
>+`[Packages]` sections. The architectural section modifier is used as a
>+restriction to mask items from architectures that are not applicable. The
>+locations of the packages listed in this section will be used for build tool to
>+get the PCD declaration. The packages must be listed
>+in the order that resolves any include dependencies.
>+
>+This section uses one of the following section definitions:
>+
>+```ini
>+[Packages]
>+[Packages.common]
>+[Packages.IA32]
>+[Packages.X64]
>+[Packages.EBC]
>+```
>+
>+The path must include the DEC file name and the name of the directory that
>+contains the DEC file.
>+
>+```
>+MdeModulePkg/MdeModulePkg.dec  # MdeModulePkg
>+MdePkg/MdePkg.dec              # MdePkg
>+```
>+
>+The following is an example of a packages section:
>+
>+```ini
>+[Packages]
>+  MdeModulePkg/MdeModulePkg.dec
>+  MdePkg/MdePkg.dec
>+```
>diff --git a/3_edk_ii_dsc_file_format/313_[packages]_section.md
>b/3_edk_ii_dsc_file_format/313_[packages]_section.md
>new file mode 100644
>index 0000000..0594048
>--- /dev/null
>+++ b/3_edk_ii_dsc_file_format/313_[packages]_section.md
>@@ -0,0 +1,93 @@
>+<!--- @file
>+  3.13 [Packages] Section
>+
>+  Copyright (c) 2019, 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.
>+
>+-->
>+
>+## 3.13 [Packages] Section
>+
>+These are optional sections. The purpose of this section is to involve the
>packages,
>+which are not included by any component, into the platform. In this way,
>more
>+FeatureFlagPcd or FixedAtBuildPcd can be used in platform DSC file or FDF
>file,
>+even if those PCDs are not used in any component.
>+
>+#### Summary
>+
>+Defines the `[Packages]` section tag that is used in EDK II platform DSC files.
>+Each entry in this section contains a directory name, forward slash character
>+and the name of the DEC file contained in the directory name.
>+
>+Each package filename must be listed only once per section. Package
>filenames
>+listed in architectural sections are not permitted to be listed in the common
>+architectural section.
>+
>+The `"common"` architecture modifier in a section tag must not be combined
>with
>+other architecture type; doing so will result in a build break.
>+
>+Packages listed under the `"common"` architecture section must not be
>listed in
>+sections that have other architecture modifiers.
>+
>+#### Prototype
>+
>+```c
>+<Packages>           ::= "[Packages" [<com_attrs>] "]" <EOL> <Statements>*
>+<com_attrs>          ::= {".common"} {<attrs>}
>+<attrs>              ::= <Archs> ["," <TS> "Packages" <Archs>]
>+<Archs>              ::= "." <arch>
>+<Statements>         ::= {<MacroDefinition>} {<PkgStatements>}
>+<PkgStatements>      ::= <TS> <Filename> [<Field2>] <EOL>
>+<Field2>             ::= <FS> <FeatureFlagExpress>
>+<FeatureFlagExpress> ::= <Boolean>
>+```
>+
>+#### Parameters
>+
>+**_Filename_**
>+
>+Paths listed in the `[Packages]` section contain a directory name, forward
>+slash character and the name of the DEC file contained in the directory name.
>+Use of "..", "." and "../" in the directory path is not permitted. Use of an
>+absolute path is prohibited.
>+
>+**_FeatureFlagExpress_**
>+
>+When present, the feature flag expression determines whether the entry
>line is
>+valid. If the feature flag expression evaluates to FALSE, this entry will be
>+ignored by the EDK II build tools.
>+
>+#### Example
>+
>+```ini
>+[Packages]
>+  MdePkg/MdePkg.dec
>+  MdeModulePkg/MdeModulePkg.dec
>+
>+[Packages.IA32]
>+  DEFINE CPUS = IA32FamilyCpuPkg
>+  $(CPUS)/DualCore/DualCore.dec
>+```
>diff --git a/README.md b/README.md
>index 42febaf..4ec9105 100644
>--- a/README.md
>+++ b/README.md
>@@ -194,5 +194,6 @@ Copyright (c) 2006-2017, Intel Corporation. All rights
>reserved.
> |            | Add structure PCD field value assignment syntax
>|                |
> |            | Add !error statement section
>|                |
> |            |[#1110](https://bugzilla.tianocore.org/show_bug.cgi?id=1110)
>Extend exclamation statement's keyword to case-insensitive
>|                |
> | 1.29     | [#1453](https://bugzilla.tianocore.org/show_bug.cgi?id=1453)
>Update DSC spec to remove EDK related contents
>| Mar 2019      |
> | 1.30     | [#1952](https://bugzilla.tianocore.org/show_bug.cgi?id=1952)  add
>HOST_APPLIACTION ModuleTpye
>| July 2019      |
>+|            |[#2383](https://bugzilla.tianocore.org/show_bug.cgi?id=2383) Add
>[Packages] section into DSC file
>|                |
>diff --git a/SUMMARY.md b/SUMMARY.md
>index e00a040..bd206e1 100644
>--- a/SUMMARY.md
>+++ b/SUMMARY.md
>@@ -48,10 +48,11 @@
>   * [2.8 PCD Sections](2_dsc_overview/28_pcd_sections.md#28-pcd-sections)
>   * [2.9 PCD Database](2_dsc_overview/29_pcd_database.md#29-pcd-
>database)
>   * [2.10 [Components] Section
>Processing](2_dsc_overview/210_[components]_section_processing.md#210
>-components-section-processing)
>   * [2.11 [UserExtensions]
>Section](2_dsc_overview/211_[userextensions]_section.md#211-
>userextensions-section)
>   * [2.12 [DefaultStores]
>Section](2_dsc_overview/212_[defaultstores]_section_processing.md#212-
>defaultstores-section-processing)
>+  * [2.13 [Packages]
>Section](2_dsc_overview/213_[packages]_section_processing.md#213-
>packages-section-processing)
> * [3 EDK II DSC File Format](3_edk_ii_dsc_file_format/README.md#3-edk-ii-
>dsc-file-format)
>   * [3.1 Building multiple
>architectures](3_edk_ii_dsc_file_format/31_building_multiple_architectures.
>md#31-building-multiple-architectures)
>   * [3.2 General Rules](3_edk_ii_dsc_file_format/32_general_rules.md#32-
>general-rules)
>   * [3.3 Platform DSC
>Definition](3_edk_ii_dsc_file_format/33_platform_dsc_definition.md#33-
>platform-dsc-definition)
>   * [3.4 Header
>Section](3_edk_ii_dsc_file_format/34_header_section.md#34-header-
>section)
>@@ -61,10 +62,11 @@
>   * [3.8 [LibraryClasses]
>Sections](3_edk_ii_dsc_file_format/38_[libraryclasses]_sections.md#38-
>libraryclasses-sections)
>   * [3.9 PCD Sections](3_edk_ii_dsc_file_format/39_pcd_sections.md#39-
>pcd-sections)
>   * [3.10 [Components]
>Sections](3_edk_ii_dsc_file_format/310_[components]_sections.md#310-
>components-sections)
>   * [3.11 [UserExtensions]
>Sections](3_edk_ii_dsc_file_format/311_[userextensions]_sections.md#311-
>userextensions-sections)
>   * [3.12 [DefaultStores]
>Sections](3_edk_ii_dsc_file_format/312_[defaultstores]_section.md#312-
>defaultstores-section)
>+  * [3.13 [Packages]
>Sections](3_edk_ii_dsc_file_format/313_[packages]_section.md#313-
>packages-section)
> * [Appendix A Variables](appendix_a_variables.md#appendix-a-variables)
> * [Appendix B Sample EDK II DSC
>File](appendix_b_sample_edk_ii_dsc_file.md#appendix-b-sample-edk-ii-dsc-
>file)
> * [Appendix C Module Types](appendix_c_module_types.md#appendix-c-
>module-types)
> * [Appendix D Vpd Data
>Files](appendix_d_vpd_data_files/README.md#appendix-d-vpd-data-files)
>   * [D.1 EDK II Build System Output File
>Format](appendix_d_vpd_data_files/d1_edk_ii_build_system_output_file_f
>ormat.md#d1-edk-ii-build-system-output-file-format)
>--
>2.20.1.windows.1
>
>
>