public inbox for devel@edk2.groups.io
 help / color / mirror / Atom feed
* [Patch] Document: Update DSC spec to add Packages section
@ 2019-11-25  5:50 Bob Feng
  2019-11-27  8:21 ` [edk2-devel] " Liming Gao
  0 siblings, 1 reply; 2+ messages in thread
From: Bob Feng @ 2019-11-25  5:50 UTC (permalink / raw)
  To: devel; +Cc: Liming Gao

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_format.md#d1-edk-ii-build-system-output-file-format)
-- 
2.20.1.windows.1


^ permalink raw reply related	[flat|nested] 2+ messages in thread
end of thread, other threads:[~2019-11-27  8:21 UTC | newest]

Thread overview: 2+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2019-11-25  5:50 [Patch] Document: Update DSC spec to add Packages section Bob Feng
2019-11-27  8:21 ` [edk2-devel] " Liming Gao

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox