EDK II Build Specification
DRAFT FOR REVIEW
03/01/2024 01:40:53
Acknowledgements
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:
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.
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.
Copyright (c) 2008-2017, Intel Corporation. All rights reserved.
Revision History
| Revision | Revision History | Date |
|---|---|---|
| 1.0 | Initial release. | February 2008 |
| 1.1 | Update based on errata | August 2008 |
| 1.2 | Updates based on enhancement requests | June 2009 |
| 1.21 | Updates based on errata and enhancement requests | January 2010 |
| Definitions in DSC file [defines] section are now global to both DSC and FDF files | ||
| Added language filters: RFC_LANGUAGES and ISO_LANGUAGES | ||
| Rule processing for file type lists is alphabetical, i.e., files are added in alphabetical order | ||
| Added warning for VFR file naming convention - cannot use a name that is also used for a C file | ||
| Use of the IDENTIFIER statement in tools_def.txt is optional | ||
| Whitespace characters are permitted in the meta-data files, so tools must handle them (use of token based processing is recommended) | ||
| Tools must support any number of FV_EXT_ENTRY_TYPE statements in an FDF file | ||
| The build tools must auto compute the ExtHeaderOffset in the FV Header. | ||
| The build tools must auto compute the ExtHeaderSize in the FV Ext Header based on the size of the FV Ext Header and all the FV Ext Header Entries. | ||
| The build tools must auto compute the ExtEntrySize field in the FV Ext Header Entry structure based on the size of the file specified by the FILE statement or the number of bytes in the byte array of the DATA statement. If the size is greater than 16-bits, the build should break. | ||
| Specified parsing priority rules for definitions and values | ||
| Added report generator syntax as part of the build | ||
| Add support for "Auto" alignment for PE32 and TE images | ||
| Add support for specifying block information for capsules | ||
| FeatureFlagExpression processing should allow C-style expression syntax and follow C rules for processing | ||
| 1.22 | Grammatical and formatting changes. Added Module types appendix. | May 2010 |
| 1.22 w/ | Updated to match the implementation at the time of the UDK2010 SR1 release: | December 2011 |
| Errata A | Updated to support UEFI version 2.3.1 and updated spec release dates in Introduction | |
| Clarify UEFI's PI Distribution Package Specification | ||
| Spelling and punctuation fixes | ||
Updated document title, removed ADD_BUILD_RULE from target.txt, Added VPD information, Fixed VOID* string format, Break build if EDK II modules uses ISO 639-2 language codes, updated macro usage in tools_def.txt |
||
| Allow user visible language name to contain space characters | ||
| Updated language code from RFC 3066 to RFC 4646 as well as adding additional content that matches implementation | ||
Update to specify VOID* data must be translated to either a Hex Byte Array, a C Format GUID or a valid C format string |
||
| Update AutoGen section regarding UEFI and PI specification versions _gUefiDriverRevisions, _gDxeRevision or _gPeimRevision | ||
| Add rules and file formats for the VPD tools | ||
| Added description of EDK_GLOBAL macro utilization - defined in DSC, used in EDK II DSC, EDK II FDF and EDK INF files only | ||
| Added description of the SOURCE_OVERRIDE_PATH for EDK INF files only | ||
| Added ECP_SOURCE system environment variable | ||
| Remove SET statements from DSC processing | ||
| Use just the PcdName in conditional directive statements. $(PcdName) and PCD(PcdName) are not permitted in conditional directive statements defined in the DSC and FDF files | ||
| Document what the valid numbers are for the debug switch for build.exe, updated EBNF for -D command-line option | ||
| Specify normal build report items, including the number of warning messages that might come from the EDK II build tools (not the third party tools, just the EDK II build system tools), correct module report for dependency expressions, correct PCD reports, removed notification report section, added Fixed Address Prediction and EOT sections to the reports | ||
| Prohibit listing multiple library class instances or PCD entries within a single section in EDK II Meta-data files | ||
| Updated to remove path restriction on macro values, clarified how architectures are selected for the build, clarified macro precedence tables | ||
| Updated MACRO EBNF inside of tools_def.txt definitions | ||
| Make sure that generated values in the AutoGen stage have either a u or a ull appended to the value to ensure that they are unsigned (PCD values are always unsigned integers) | ||
| Update description of the TOOL_CHAIN_TAG so that if it is not specified, the build will break | December 2011 | |
| Remove CREATE_FILE from specification, 10.5.1, as this was never supported | ||
| Updated Create FFS files from Leaf sections description in Rules section | ||
| Specify how sections are merged during parsing of the EDK II meta-data files | ||
Specify how the maximum size of a VOID* PCD is calculated if it is not specified |
||
| Allow any non-zero number to evaluate to True | ||
| Change "should" to say recommended | ||
| Require MdePkg/MdePkg.dec in the [Packages] section of all INF files listed in the DSC file | ||
| updated comments and operand notes in table | ||
| REMOVED "ALL" from the Report Type list, as ALL is not a valid option value | ||
| Clarify that macros are only expanded when parsing EDK II INF and DEC files, and that Macro values are expanded or evaluated when parsing of EDK II DSC and FDF files | ||
| Updated 5.2.3 and E.4.2 to allow lower case characters in a MACRO name in tools_def.txt. | ||
| Updated TOOL_CHAIN_TAG in Appendix C to match definition in chapter 5 | ||
| Removed number of warnings message at the completion of the build - not for SR1 - 13,0 | ||
| Added Support for C++ in auto-generated code | ||
| 1.22 w/ | Updates: | June 2012 |
| Errata B | Section 1.1, page 1: Added description regarding build system tools and appropriate error conditions for 'forward compatibility' | |
| Section 1.4, page 5: Updated Specification Versions to include released Errata | ||
Section 5, added note about build_rule.txt updates |
||
Section 5.2.3: Added DOS <EOL> character sequence definition |
||
Section 5.3: Added DOS <EOL> character sequence definition |
||
Removed Section 5.4, build_rule.txt. This file is for tool usage and not for normal editing purposes. |
||
| Section 8.5, Removed reference to binary "LIB" - library distribution is not currently supported | ||
Section 10, table 19, updated to support EFI_SECTION_FREEFORM_SUBTYPE_GUID |
||
| Removed section 12.5 for EDK Library INF modifications | ||
| Removed Appendix_D_Build_rule.txt | ||
| Appendix I Updated - clarify that Unicode file is a UCS-2 encoded file, and that the Language Code for EDK II modules must be RFC4646 language codes; EDK components support UCS-2 encoded files containing ISO639 language codes | ||
| 1.22 w/ | Updates: | August 2013 |
| Errata C | Section 1.3, Updated Errata for UEFI Specs. | |
| Sections 4.3.4, 4.4, 4.5.3, 8.1, 8.4, 9.7, 10.1, Appendix E.2, Removed 8.4.2, Appendix L.1 and L.2, removing Top level and Architectural level Makefiles - build system has been modified to have Python call the module Makefiles if they exist; also updating figures to remove the 'Platform' Makefile | ||
| Section 8.5.1.2.4 - removed fds target in the makefile, as the build command will call the GenFds if the fds target is given on the command-line | ||
| Section 4.1, 5, 5.3, D.4, Allow DSC, FDF and the Conf directory to be located outside of the WORKSPACE directory(--conf=CONF_DIRECTORY) | ||
| Section 5.2.3, Table 9, Added ADDDEBUGFLAG predefined attribute | ||
| Section 6.4.4,2 remove line following GenFv --help, as this is not the correct usage | ||
| Section 7.1.5, State that flags are processed from left to right, with the right most flag overriding a flag that is to the left | ||
| Added new section 8.5 added wording for generating "As Built" INF files as part of the AutoGen process | ||
| Added new section 8.4 describing the PEI and DXE Dynamic PCD database generation | ||
| 8.3.5.5.2 Added statement regarding when to generate a #define statement for Fixed At Build PCDs in libraries | ||
| Build system reports the total number of warning messages emitted by the EDK II tools (not the third party tools invoked by the EDK II build system). Added support for lower case characters in the UEFI Compliant Unicode Token entry. | ||
| Cleaned up EBNF for HII Tokens to remove ambiguity. Added support for Patchable In Module PCD for overriding a Formset Class GUID in a binary HII driver. | ||
| Added additional rules for PCD Database generation | ||
| 1.22 w/ | Updates: | January 2014 |
| Errata D | Added text describing new DSC flag to generate a special version of the PCD database that contains both the PCD token name and the token number. New section, 8.2.4.10 provides text describing this option. | |
| Updated section 10.5 to describe how PCDs are used in expressions in the [FD] offset fields. | ||
| Updated section 10.2 to describe the last statement taking precedence when duplicate statements appear for some entries in the FDF file. | ||
| Updated Chapter 13 to reflect current implementation | ||
| 1.24 | Updates: | December 2014 |
| Changed specification version to 1.24 | ||
| Updated UEFI specification and EDK II meta data specifications in section 1.3; added the EDK II UNI Unicode File Specification and EDK II Expression Syntax Specification | ||
| Removed Appendix G, EFI Compliant Unicode File Grammar and Appendix I, HII UEFI Compliant Unicode File Grammar - refer to the EDK II UNI Unicode File Specification instead | ||
| "Clarify that the "As Built" INF [Depex] section contains the full dependency expression including the linked in library classes' Depex section in comments. | ||
| "Updated options in Appendix D to match implementation (removed several flags); added reserved flag, --tool- profile to build.exe. | ||
| Added clarification of PCD rules for INF files in 8.4.1 | ||
| Removed example text from tool_def.txt and target.txt appendices and Meta-Data File Spec chapter, adding hyper link to SVN location for the template files used to create these two files | ||
| 1.24 w/ | Updates: | March 2015 |
| Errata A | Update link to the EDK II Specifications, fixed the name of the Multi-String .UNI File Format Specification | |
| Updated 10.4 to describe how tools add an FvNameString in the FV image extension header | ||
| Adding a VPD PCD Sub-section to the FLASH Report - defined in new section, 13.6.3 | ||
| 1.25 | Updates: | June 2015 |
| Updated to support UEFI 2.5 and PI 1.4 specifications | ||
| Add BUILDRULEORDER attribute to tools_def.txt in chapter 5.2.3 | ||
Updated 7.1.5 to include the MODULE_TYPE modifier in [BuildOptions] sections specified in the DSC file. |
||
Clarify 8.4.2.10 wording that VOID* PCDs size reservation, when not present in the DSC file, is determined as the largest of the sizes for content in the DSC, DEC and INF files. |
||
| Update 8.7.12 [Binaries] section in an As Built INF to allow flexibility when determining file types and to allow module relative subdirectories in the filename. | ||
| Updated 8.2.4.12 to include the flag that generates the Dynamic and DynamicEx HII PCD Variable check binary in the FV section | ||
| 1.24 w/ | Updates: | August 2015 |
| Errata A | Updated 10.4 to describe how tools add an FvNameString in the FV image extension header | |
| Update 8.7.5 - 8.7.9 to allow the build system to update usage information based on feature flag evaluation during the build | ||
| 1.26 | Updates : | January 2016 |
| Specification revision to 1.26 | ||
| Removed data structure definitions (duplicates from PE/ COFF, PI Specifications and TE headers) in Chapter 3 and included references to the industry specifications to remove potential typographical errors and inconsistencies. | ||
| Removed Setup and Getting Started sections from Quick Start chapter 6 - this information is available on the TianoCore.org web-site. | ||
| 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, optional system environment variables used by the build system in this environment. | ||
| Provide clarification on VPD data generation and report for VPD data content | ||
| Clarify precedence of the DPX_SOURCE and [Depex] section. | ||
Specify the alignment required for VOID* PCDs based on the string, Unicode string or byte-code array values. |
||
| Remove Unicode file storage requirement; refer to the Multi-String UNI File Format Specification instead. | ||
| Clarify BUILDRULEORDER | ||
| Add support for INF statement in an FD region. | ||
| 1.27 | Convert to Gitbook | May 2017 |
| #471 Build spec: only copy the "TianoCore" Userextension section into "As Built" INF | ||
| #472 [Build Spec] Extend macro usage in the !include statements for DSC/FDF files | ||
| #483 Build Spec: add description for merge Pre-build and Post-build into build process | ||
| #490 Build Spec: specify the alignment requirements for VOID* PCDs stored in a PCD section | ||
| #479 Build spec: add description for nmake long command line handling | ||
| #485 Build spec: add support for mixed Pcd access method | ||
| #476 Build spec: add support for HII image package | ||
| #465 DEC spec: document private definitions | ||
| #504 Update build report to support -Y HASH option | ||
| #508 Build Spec: Add sections to PCD report for PCDs only used in conditions PCDs that are not used anywhere | ||
| #480 Build spec: add description for Override PCD value on the command line | ||
| #523 Build spec: add EBNF for the --pcd syntax in the Section D.4 | ||
| #517 Build spec: chapter 5.2.2 Guided Tools add description for Pkcs7Sign tool and BrotliCompress tool | ||
| #481 Build Spec: add clarification for not used Pcd that build tool will not do additional checks on its value | ||
| #518 Build Spec: Update Precedence of PCD Values | ||
| #669 Build Spec: Add multi-arg support to PREBUILD/POSTBUILD | ||
| #717 Build Spec: Build report to display every module's build time | ||
| #689 Build spec: add description for build with binary cache | ||
| 1.28 | Add clarification for the binary cache files | Mar 2018 |
| #775 Build spec: Add description about auto detect thread number | ||
| Add Flexible PCD value format into spec | ||
| Update PCD value and SKU, DefaultStore info in build report | ||
| Clarify structure PCD field value assignment precedence | ||
| Update description for build handles PCDs for SKU support | ||
Add statement about module scoped <Pcd*> section override scope |
||
| Add !error statement section | ||
| #1110 Extend exclamation statement's keyword to case-insensitive | ||
| #598 update supported operators in 8.2.4.6 Expressions | ||
| 1.29 | #1453 Update Build spec to remove EDK related contents | Mar 2019 |
| 1.30 | #1952 Update Build spec to support HOST_APPLICATION MODULE_TYPE | July 2019 |
| 1.31 | #991 generate ProcessLibraryConstructorList() declaration in AutoGen.h for SEC modules | February 2024 |