Reporting¶
Top take your EDK2 workspace from freshly cloned, to parsed and ready to be reported on, you only need to execute three commands. If you've properly installed edk2-pytool-extensions, then these commands will be available to execute as seen below:
stuart_setup (or stuart_ci_setup) -c path/to/SettingsFile.py
stuart_update -c path/to/SettingsFile.py
stuart_parse -c path/to/SettingsFile.py
From there, you will use stuart_report (or sql queries against the database) to run reports / queries against the database.
Stuart Parse¶
Command Line Interface¶
Similar to all other invocables, the user can use the -h
flag review a detailed description of the CLI interface,
however for convenience, here are the options available:
Optional Arguments:
--append, --Append, --APPEND Run only environment aware parsers and append them to the database.
-p, --pkg, --pkg-dir Packages to parse (CI builder only)
-a, --arch Architectures to use when parsing (CI builder only)
-t, --target Targets (DEBUG, etc.) to use when parsing (CI builder only)
Example usage¶
:: parse the workspace for mu_tiano_platform's QemuQ35Pkg in debug mode
stuart_parse -c Platforms/QemuQ35Pkg/PlatformBuild.py TARGET=DEBUG
:: parse the workspace for mu_tiano_platform's QemuQ35Pkg in release mode, appending the results to the existing database
stuart_parse -c Platforms/QemuQ35Pkg/PlatformBuild.py --append TARGET=RELEASE
:: parse the workspace for all packages supported in mu_basecore
stuart_parse -c .pytool/CISettings.py
:: parse the workspace for all packages supported in mu_basecore, filtering the packages
stuart_parse -c .pytool/CISettings.py -p MdePkg -p MdeModulePkg
:: parse the workspace for all packages supported in mu_basecore, only using DEBUG
stuart_parse -c .pytool/CISettings.py -t DEBUG
Stuart Report¶
Command line arguments¶
usage: A tool to generate reports on a edk2 workspace. [-h] [--verbose] [-db DATABASE] {coverage,component-libs,usage} ...
positional arguments:
{coverage,component-libs,usage}
options:
-h, --help show this help message and exit
--verbose, --VERBOSE, -v
verbose
-db DATABASE, --database DATABASE, --DATABASE DATABASE
The database to use when generating reports. Can be a comma separated list of db's to merge. Globbing is supported.
Review the command line arguments with stuart_report -h
. As you can tell, the
command line interface for the tool itself is simple, only truly needing a path
to the database to use. Out of convenience, the default path for the database
is Reports/DATABASE.db, as that is where the database is generated when running
stuart_parse
. If the database is moved or renamed, you will need to manually
link it with the -db, --database
.
Each available report (positional argument) has it's own subset of command line
arguments so before running a report, it is important to review it's interface
also stuart_report <Report> -h
to see the customizations / necessary
arguments for the report.
Coverage Report¶
stuart_report coverage
converts coverage xml results into a similar coverage
xml that re-organizes the data to be based off the library INF rather than the
executed binary used for testing. It provides a more accurate representation of
the current code coverage as most UEFI developers will care about code coverage
of a specific library. Additionally, some files are used in multiple INFs,
which this report will more accurately depict.
Due to the complex nature involved in building a UEFI package, code coverage results can also contain code coverage results for INFs outside of the package the developer cares about. This tool allows for the filtering of results to specific packages.
usage: A tool to generate reports on a edk2 workspace. coverage [-h] [-o OUTPUT] [-s {inf}] [-p PACKAGE_LIST] [-ws WORKSPACE] [--library] xml
Reorganizes an xml coverage report by INF rather than executable.
positional arguments:
xml The path to the XML file parse.
options:
-h, --help show this help message and exit
-o OUTPUT, --output OUTPUT, --Output OUTPUT, --OUTPUT OUTPUT
The path to the output XML file.
-s {inf}, --scope {inf}, --Scope {inf}, --SCOPE {inf}
The scope to associate coverage data
-p PACKAGE_LIST, --package PACKAGE_LIST, --Package PACKAGE_LIST, --PACKAGE PACKAGE_LIST
The package to include in the report. Can be specified multiple times.
-ws WORKSPACE, --workspace WORKSPACE, --Workspace WORKSPACE, --WORKSPACE WORKSPACE
The Workspace root associated with the xml argument.
--library To only show results for library INFs
Usage Report¶
stuart_report usage
generates a standalone html document (requires internat)
that contains pie charts showing the different library and component INFs that
are used to build the specific package parsed, and which submodules (or BASE)
they come from. It also contains a table of all INFs used, and a table of all
environment variables used when building the package.
usage: A tool to generate reports on a edk2 workspace. usage [-h] [-e ENV_ID] [-o OUTPUT]
Generates a report of INF usage for a specific build.
options:
-h, --help show this help message and exit
-e ENV_ID, -env ENV_ID
The environment id to generate the report for. Defaults to the latest environment.
-o OUTPUT, -output OUTPUT
The output file to write the report to. Defaults to 'usage_report.html'.
Component Library Report¶
stuart_report component-libs
prints to the terminal (or writes to a file) the
actual list of library instances (and their associated library classes) used to
create the component. This is based off the package dsc that was parsed. The
report will print a flat version, providing each library compiled into the
component, or a recursive list of dependencies for each library.
usage: A tool to generate reports on a edk2 workspace. component-libs [-h] [-o FILE] [-d DEPTH] [-f] [-s] [-e ENV_ID] component
Dumps the library instances used by component.
positional arguments:
component The component to query.
options:
-h, --help show this help message and exit
-o FILE, --out FILE The file, to write the report to. Defaults to stdout.
-d DEPTH, --depth DEPTH
The depth to recurse when printing libraries used.
-f, --flatten Flatten the list of libraries used in the component.
-s, --sort Sort the libraries listed in alphabetical order.
-e ENV_ID, --env ENV_ID
The environment id to generate the report for.