This article describes how the EDK2 build reporting system works. I think it's a little known topic; most people just run a build and see some status output at the end. However, the reporting can be customized in powerful ways, mainly as described in §13 of the EDK2 Build Specification. Let's dive in.
First, we need to define terminology. EDK2 distinguishes between a build log and build report:
- Build Log (-j LOGFILE, --log=LOGFILE): this is exactly what you see on the console during the build, mainly the compiler and linker output. There is a brief build summary at the end.
- Build Report (-y REPORTFILE, --report-file=REPORTFILE): the build report contains higher-level data regarding the content of what you've built, not the status of compiling/linking.
The build log is straightforward, so this article will focus on the build report. By default, unless the quiet or silent options are used (--quiet/--silent), the build system will automatically generate the following output at the end of the build:
- Each region, offset and size defined in the FD
- The location of the GUID cross reference file
- The size of the data in each FV region
- The date and time the build completed
For example, if I get the latest EDK2 source (edk2-stable202408 at time of writing), and build the default target, EmulatorPkg, I get reporting on the console that looks like:
Fd File Name:FV_RECOVERY (<path>\edk2\Build\EmulatorX64\DEBUG_VS2015x86\FV\FV_RECOVERY.fd)Generate Region at Offset 0x0
Region Size = 0x580000
#####
Generate Region at Offset 0x580000
Region Size = 0xC000
Region Size = 0x2000
Region Size = 0x2000
Region Size = 0x10000
Build end time: 16:56:24, Oct.01 2024
Build total time: 00:02:05
Extending the Default Build Reporting
This default build reporting can be extended in two ways, with the -y switch and -Y switch:
- -y REPORTFILE, --report-file=REPORTFILE — Asks for creation of a specific build report file with the default set of build report flags: PCD, LIBRARY, FLASH, DEPEX, HASH, BUILD_FLAGS and FIXED_ADDRESS
- -Y REPORTTYPE, --report-type=REPORTTYPE — Used to customize the set of default build report flags (above). This can be used to create a smaller build report focusing on just one or more of the default flags, and/or add the special EXECUTION_ORDER flag.
The build report flags are fairly self-explanatory: PCD, LIBRARY, FLASH, DEPEX, HASH, BUILD_FLAGS and FIXED_ADDRESS. Each flag adds to the build report data regarding PCDs, libraries, flash map outline, dependency expressions, etc., respectively. §13 of the EDK2 Build Specification does a good job providing more information, so please look there for help, or even better, generate some reports of your own and take a look at them.
Problems with EXECUTION_ORDER
A special note on the EXECUTION_ORDER build report flag that isn't part of the default build report. First, it fails to build on the edk2-stable202408 tag:
<path>\edk2\BaseTools\Source\Python\Eot\EotGlobalData.py:14: SyntaxWarning: invalid escape sequence '\S'gSHELL_INF = 'Application\Shell'
<path>\edk2\BaseTools\Source\Python\Eot\c.py:57: SyntaxWarning: invalid escape sequence '\w'
p = re.compile('[_\w\s]*\([\w\s]*\*+\s*[_\w]+\s*\)\s*\(.*\)', re.DOTALL)
(Python 3.12.6 on win32
Traceback (most recent call last):
File <path>\edk2\BaseTools\Source\Python\build\BuildReport.py", line 1690, in _InvokeEotTool
from Eot.EotMain import Eot
File "<path>\edk2\BaseTools\Source\Python\Eot\EotMain.py", line 23, in <module>
from Eot import c
File "<path>\edk2\BaseTools\Source\Python\Eot\c.py", line 17, in <module>
from . import CodeFragmentCollector
File "<path>\edk2\BaseTools\Source\Python\Eot\CodeFragmentCollector.py", line 19, in <module>
import antlr4 as antlr
ModuleNotFoundError: No module named 'antlr4'
import antlr4 as antlr
ModuleNotFoundError: No module named 'antlr4'
So, it appears maybe there is a dependency on antlr? I didn't find that documented, and I did rebuild all the EDK2 tools, so it looks like this is a bug, either in code or in documentation.
Also, the EDK2 Build Specification says you can use the -Y EXECUTION_ORDER switch by itself and the build system will generate an HTML report in the working directory. That doesn't work at all.
Conclusion
Corner-case issues with the EXECUTION_ORDER flag aside, the EDK2 system of build logs and build reports is helpful. I encourage you to experiment with it, and refer to §13 of the specification for more information!
Post a Comment
Be sure to select an account profile (e.g. Google, OpenID, etc.) before typing your comment!