4.3 Pre-Build Stage Overview
This section provides an overview of the first three meta-data files that are
used to control different aspects of the build. There are three files of
interest, build_rule.txt
, tools_def.txt
and target.txt
. The next chapter
defines the format of the tools_def.txt
and target.txt
files. The
build_rule.txt
file is not documented here, as it is internal to the EDK II
build system. See the build_rule.txt
file for additional information.
4.3.1 target.txt
The $(WORKSPACE)/Conf/target.txt
file is created the first time edksetup
script is run. The default version of this file is the
$(EDK_TOOLS_PATH)/Conf/target.template
file.
The target.txt
file is used as a filter, allowing a developer to build items
of interest without having to build everything. The variables set in this file
include the target platform, the target architecture, the tool chain and
pointers to the tool chain configuration and build rule files. If no options
are provided on the build command-line, values from this file are used to
determine what to build, what tool chain will be used and where to obtain the
rules for processing the files.
4.3.2 tools_def.txt
The $(WORKSPACE)/Conf/tools_def.txt
file is created the first time the
edksetup
script is run. The default version of this file is the
$(EDK_TOOLS_PATH)/Conf/tools_def.template
.
The tools_def.txt
describes sets of user configurable paths, commands and
default flags for external tools (as well as optional tools provided with the
build system). Since advanced developers may have multiple versions of tool
chains installed, this file allows setting up paths and flags for different
tool chains. Each tool chain is identified by a unique name.
4.3.2.1 "Best Known Safe" flags
The tools_def.txt
file flags for the supported (tested) compiler tool chains
that contain "Best Known Safe" flags for generating libraries, drivers and
applications. These flags are set for speed optimization. The build system does
provide for modifying flags for individual modules and platforms, so flags may
be modified for better debug ability.
4.3.3 build_rule.txt
The $(WORKSPACE)/Conf/build_rule.txt
file is created the first time the
edksetup
script is run. The default version of this file is the
$(EDK_TOOLS_PATH)/Conf/build_rule.template
.
The build_rule.txt
file is used by the tools to define how different file
types are processed. This includes how different files and module types are
compiled, as well as how the build tools manipulate the binary image files.
Normally, users should not make changes to this file.
4.3.4 Parse EDK II Meta-Data - AutoGen stage
Once the build system knows the basic information needed for the build, the build system parses the additional EDK II meta-data files. The meta-data in the EDK II code base is stored in text-based, INI-style, documents. Refer to the EDK II INF Specification, EDK II DSC Specification, EDK II DEC Specification, and EDK II Flash Description File Specification to see the format of these files.
The DSC file is the first of the EDK II meta-data files that gets parsed. This file provides a list of the other EDK II meta-data files that need to be parsed. The DSC file may be parsed twice in order to resolve PCD values that are used are used in conditional directive statements.
The contents of current working directory (at the time the build command is
executed) may alter what gets built. If the working directory contains one INF
file, only the module gets built. This is useful when debugging a driver, as
only the one module will be rebuilt. If more than one INF file exists, you will
need to use an command-line option to select which INF file you want to build.
(The INF filename must be listed in the ACTIVE_PLATFORM
DSC file's
[Components]
section.)
Note: More than one INF file may exist in a module directory, however the
BASENAME and FILE_GUID
for these INF files must be different if both modules
will be included in a single FV for platform.
Note: The build system has also been modified to support building multiple versions of a single INF using the format defined in the DSC specification. This permits having multiple versions of a module linked against different libraries.
The second file to be parsed will be the FDF file if one is specified in the DSC file or on the command-line. While the FDF file specified what content gets assembled into the final firmware device image, PCD values from this file may be required for building specific modules specified in the DSC file.
Note: INF files that are listed in the DSC file must include the package, MdePkg/MdePkg.dec in order to build properly (even if the module does not contain C files).
The parse stage creates individual module and library AutoGen.c
, AutoGen.h
and Makefiles. Since EDK II supports Microsoft, Intel and GCC complier tool
chains, the Microsoft Build Tool, NMAKE/Makefile
is for Windows developer
Workstations using Microsoft or Intel tool chains on a Microsoft Windows
operating system development workstation. For UNIX based development
workstations, the GCC build tool, MAKE/GNUmakefile
is used.
All third party tools and flags for those tools get expanded in the generated Makefiles. The following is an example of makefile statements that support this mode.
...
PP = C:\Program Files\Microsoft Visual Studio .NET 2003\Vc7\bin\cl.exe
CC = C:\Program Files\Microsoft Visual Studio .NET 2003\Vc7\bin\cl.exe
APP = C:\Program Files\Microsoft Visual Studio .NET 2003\Vc7\bin\cl.exe
VFRPP = C:\Program Files\Microsoft Visual Studio .NET 2003\Vc7\bin\cl.exe
DLINK = C:\Program Files\Microsoft Visual Studio .NET 2003\Vc7\bin\link.exe
PCH = C:\Program Files\Microsoft Visual Studio .NET 2003\Vc7\bin\cl.exe
ASM = C:\Program Files\Microsoft Visual Studio .NET 2003\Vc7\bin\ml.exe
TIANO = TianoCompress.exe
SLINK = C:\Program Files\Microsoft Visual Studio .NET 2003\Vc7\bin\lib.exe
ASMLINK = C:\WINDDK\3790.1830\bin\bin16\link.exe ASL = C:\ASL\iasl.exe
...
DEFAULT_PP_FLAGS = /nologo /E /TC /FI$(DEST_DIR_DEBUG)/AutoGen.h
DEFAULT_CC_FLAGS = /nologo /W4 /WX /Gy /c /D UNICODE /O1ib2 /GL / FI$(DEST_DIR_DEBUG)/AutoGen.h /EHs-c- /GF /Gs8192 /Zi /Gm
DEFAULT_APP_FLAGS = /nologo /E /TC
DEFAULT_VFRPP_FLAGS = /nologo /E /TC /DVFRCOMPILE /FIAutoGen.h
DEFAULT_DLINK_FLAGS = /NOLOGO /NODEFAULTLIB /IGNORE:4086 /OPT:REF /OPT:ICF=10 /MAP /ALIGN:32 /MACHINE:I386 /LTCG /DLL /ENTRY:$(ENTRYPOINT) /SUBSYSTEM:CONSOLE /SAFESEH:NO /BASE:0 /DRIVER /DEBUG /PDB:$(DEST_DIR_DEBUG)/$(BASE_NAME).pdb
DEFAULT_PCH_FLAGS = /nologo /W4 /WX /Gy /c /D UNICODE /O1ib2 /GL /FI$(DEST_DIR_DEBUG)/AutoGen.h /EHs-c- /GF /Gs8192 /Fp$(DEST_DIR_OUTPUT)/AutoGen.h.gch /Yc /TC /Zi /Gm
DEFAULT_ASM_FLAGS = /nologo /W3 /WX /c /coff /Cx /Zd /W0 /Zi
DEFAULT_TIANO_FLAGS =
DEFAULT_SLINK_FLAGS = /nologo /LTCG
DEFAULT_ASMLINK_FLAGS = /link /nologo /tiny
DEFAULT_ASL_FLAGS =
...
$(OUTPUT_DIR)\Ia32\WriteGdtr.obj : $(COMMON_DEPS)
$(OUTPUT_DIR)\Ia32\WriteGdtr.obj :
$(WORKSPACE)\MdePkg\Include\Library\DebugLib.h
$(OUTPUT_DIR)\Ia32\WriteGdtr.obj : $(WORKSPACE)\MdePkg\Include\Library\BaseLib.h
$(OUTPUT_DIR)\Ia32\WriteGdtr.obj :
$(WORKSPACE)\MdePkg\Include\Library\TimerLib.h
$(OUTPUT_DIR)\Ia32\WriteGdtr.obj :
$(WORKSPACE)\MdePkg\Include\Library\BaseMemoryLib.h
$(OUTPUT_DIR)\Ia32\WriteGdtr.obj : $(WORKSPACE)\MdePkg\Include\Library\PcdLib.h
$(OUTPUT_DIR)\Ia32\WriteGdtr.obj :
$(WORKSPACE)\MdePkg\Library\BaseLib\Ia32\WriteGdtr.c
$(OUTPUT_DIR)\Ia32\WriteGdtr.obj :
$(WORKSPACE)\MdePkg\Library\BaseLib\BaseLibInternals.h
"$(CC)" /Fo$(OUTPUT_DIR)\Ia32\WriteGdtr.obj $(CC_FLAGS) $(INC) $(WORKSPACE)\MdePkg\Library\BaseLib\Ia32\WriteGdtr.c
$(OUTPUT_DIR)\Ia32\WriteDr3.obj : $(COMMON_DEPS)
$(OUTPUT_DIR)\Ia32\WriteDr3.obj :
$(WORKSPACE)\MdePkg\Library\BaseLib\Ia32\WriteDr3.c
"$(CC)" /Fo$(OUTPUT_DIR)\Ia32\WriteDr3.obj $(CC_FLAGS) $(INC)
$(WORKSPACE)\MdePkg\Library\BaseLib\Ia32\WriteDr3.c
...
One makefile is generated for each module under a combination of
$(TARGET)_$(TOOL_CHAIN_TAG)
and $(ARCH)
, package name, module directory,
directory name and the BASE_NAME
of the module's INF file.
Parse DSC file
Obtain platform FixedAtBuild and FeatureFlag PCD values and Macro values that are used in the Conditional Directives - if the value of a Macro, FixedAtBuild PCD or FeatureFlag PCD used in the conditional directives cannot be determined, the build will break with an appropriate error message. The use of FixedAtBuild or FeatureFlag PCD names which are defined by SET statements in the FDF file cannot be used in conditional directive statements in the DSC file.
Second pass over the DSC files will crush out any conditional directives where the feature flag expression used in the conditional directive is False.
Obtain platform PCD values which will go into the individual module AutoGen.h files where needed.
If
VPD_TOOL_GUID
was specified in the DSC file's[Defines]
section, the build processes is suspended while the tool specified by the GUID is called after the build process generates a text file containing the VPD PCDs. If the tool returns successfully (an exit code of 0), the build system parses the name of the 'map' file that contains an ordered list of VPD PCDs.There are some PCD values that get set on the command line, in the FDF file, listed in binary INF files or listed in source INF files, so generating the C files is delayed until all PCD values have been finalized.
Obtain the FDF filename and obtain the Flash related PCDs from the FDF file. FeatureFlag and FixedAtBuild PCD names which are defined in the DSC file can be used in conditional directives within the FDF file.
For each component listed in the DSC file, parse the Module's INF file
Create a directed graph list of the EDK II Library Instances that will be used for the EDK II modules.
Create the PEI, DXE or SMM DEPEX file
Create the Library Instance's AutoGen.c files containing PCD, Guid, Protocol, Ppi and EntryPoint definitions and data structures. PCD values come from command line, FDF file, DSC's INF scoped section, DSC's global PCD sections, default values in the INF file's PCD section, or the DEC file's default values.
Create the module's library instance Makefiles
- Individual modules may require different compilation options, over-riding any global definitions.
Create the AutoGen.c files containing PCD, Guid, Protocol, Ppi and EntryPoint definitions and data structures.
Create any Strings header file required for VFR processing.
- The VFR file name cannot be same as a C file name in a module directory. If so, the same output files will be generated and overwritten. (A.vfr --> A.c --> A.obj, A.c --> A.obj)
Create the module Makefiles
Individual modules may require different compilation options, over-riding any global definitions. If an INF file is not listed in the DSC file and is listed in the FDF file, the parsing tools must check if the INF in the FDF file contains
PatchableInModule
orDynamicEX
entries. If the INF lists other PCD access methods (FeatureFlag, FixedAtBuild or Dynamic), and the INF contains files listed in a[Sources]
section and does not contain a[Binaries]
section, then the build tools must break the build with an appropriate error message.The tools are also responsible for creating binary files containing all
DynamicEx
PCDs that are listed in the DSC, FDF and Binary INF files (listed in the FDF file). These binaries are automatically placed into the (PEIM and DXE) PCD driver FFS files.If the build option, --ignore-sources is present on the build command-line, none of the source files listed in a [Sources] section will be processed, even if the module is listed in the DSC file and no files (AutoGen.h, AutoGen.c or Makefile) will be generated; the INF must be treated as a Binary only INF file.