Historically, preparing the edk2 source for building has been quite an involved affair. So much so that I've written several articles to document all the steps required just to get your system prepared to build an edk2 driver/application. E.g.:
- Quick-Start Guide to UDK2014
- “Hello World” Quick-Start with UDK2015
- “Hello World” Quick-Start with edk2-stable201908
Specifically, one would have to unzip files into a particular directory structure, edit a text file and choose a toolchain tag, initialize submodules, download NASM and the ACPI compiler and place them where BaseTools can find them, and build BaseTools itself when its sources have changed.
Enter the "Stuart" tool. Stuart is a relatively new set of Python commands that TianoCore uses to prepare an edk2 workspace for building. It is not a compiler, and it is not a replacement for BaseTools. "build" is still the program that reads the INF, DEC, DSC, and FDF files and produces EFI images. Stuart's job is everything that has to be done before build can be invoked: setup the Python environment, the git submodules, the binary dependencies, the toolchain tag, the architecture list, and any platform-specific steps that run before or after the compile.
"Stuart" is not an acronym. The maintainers describe Stuart as a mouse that lives in the machine and looks after an edk2 workspace. Stuart commands are the requests you make of him. In the source tree, the form of that request is one of three commands: stuart_setup, stuart_update, or stuart_build.
Key highlights:
- A front end, not a new build system. Stuart arranges the workspace and then calls build, AutoGen, the compiler, and the firmware-volume tools as usual.
- The platform description is in a Python file, passed with -c. PlatformBuild.py is a common name for that file.
- Two different flows. stuart_build builds one platform, and stuart_ci_build runs the package checks used by continuous integration (CI), including the compile stage, on multiple platforms.
- Originated in Project Mu, then became the TianoCore packages edk2-pytool-library and edk2-pytool-extensions. edk2 has driven its own CI with these commands since 2019.
- Version-sensitive. On edk2/master in November 2026, pip-requirements.txt pins edk2-pytool-extensions~=0.31.1 and edk2-pytool-library~=0.23.16. Use those versions, not whatever is newest in the package index.
The impetus for Stuart
These days, a production BIOS image is an ongoing collaboration among partners, some of whom publish source and some of whom publish only a binary. The workspace is several git repositories, plus binary artifacts, plus a CI system, all continuously changing as new versions of each component are released. Hard-coded shell scripts, then, are inefficient in capturing the complex and dynamic nature of the workspace. With Stuart, each repository contributes a description of what it needs. The tool collects those descriptions and initializes the build environment, abstracting the ever-changing low-level details from the developer.
Where Stuart came from
Stuart started life inside Project Mu, as the Python packages mu_pip_environment and mu_pip_build. The command you would call was mu_build. That repository was archived on 16 November 2023; the archive notice refers to tianocore/edk2-pytool-extensions as the destination where active work moved. The earlier mu_build command corresponds to today's stuart_build.
edk2 adopted the tools for its own continuous integration even earlier. On 11 November 2019 the tree gained .pytool/CISettings.py, under TianoCore bug 2315, and the README committed with it already told a developer to run stuart_setup, stuart_update, and stuart_ci_build. The copyright header on CISettings.py is Microsoft's, showing the Project Mu lineage.
TianoCore's own build instructions now list three ways to build; in the order they recommend:
- A container from tianocore/containers, which is what the server-side jobs use and what a local build can use when the goal is build environment standardization
- Stuart, for a local build without a container
- build itself, which both of the other two ultimately call
The container does not bypass Stuart; the container runs Stuart. Stuart does not bypass BaseTools. The three stages inside build—AutoGen, compile and link, then the generation of sections, files, and firmware volumes, remains unchanged.
Two packages, several commands
Stuart requires Python 3.10 or newer. It consists of two distributions:
edk2-pytool-library (imported as edk2toollib) is the reusable component: it contains parsers and helpers for edk2 metadata, paths, and GUIDs, meant to be called from other tools.
edk2-pytool-extensions (imported as edk2toolext) is Stuart: the command-line tools, the self-describing environment, and the plugin host. The extensions package declares the library as a dependency. Its console scripts, as declared in the package metadata, are:
|
Command |
Role |
|
stuart_setup |
Synchronize the git submodules the settings manager says this workspace needs |
|
stuart_update |
Fetch external dependencies for the scopes that are active |
|
stuart_build |
Build one platform |
|
stuart_ci_setup |
Clone the repositories a CI settings manager lists, for a multi-repository workspace |
|
stuart_ci_build |
Run CI plugins across packages |
|
stuart_pr_eval |
Decide which packages a set of changes affects, so a pull-request job can skip the rest |
|
stuart_parse |
Parse the workspace into a SQLite database |
|
stuart_report |
Run reports against that database |
The settings file
Every Stuart command that does real work takes the -c parameter and a path to a Python module. That module defines a class which subclasses one settings manager per command: a setup manager, an update manager, and a build manager. The Python module answers questions like: Which packages exist? Which architectures? Which DSC? Which scopes are active? Where is the workspace root?
Scopes are how a dependency stays out of a build that does not need it. A settings manager reports an ordered list, for example a platform scope, a silicon scope, and a family scope. Descriptors that match any active scope are included, higher scopes override lower ones, and every workspace inherits a global scope at the bottom.
Let's look at edk2's own OVMF's settings file as an example:
CommonPlatform in OvmfPkg/PlatformCI/PlatformBuild.py sets the package to OvmfPkg, the architectures to IA32 and X64, the targets to DEBUG, RELEASE, and NOOPT, and the scopes to ovmf and edk2-build. GetDscName maps the architecture string IA32,X64 to OvmfPkgIa32X64.dsc and any other architecture string to OvmfPkgX64.dsc.
The three commands, and when to re-run them
stuart_setup synchronizes git submodules to what the settings manager requires. Run it once per machine per platform, and again when submodule pointers move.
stuart_update fetches and verifies external dependencies for the active scopes. Run it when those descriptors change, and whenever a build tells you the environment is stale. Pass the same architecture list and TOOL_CHAIN_TAG you will compile with.
stuart_build is the compile stage. It has three phases: pre-build plugins, the call to build, and post-build plugins. Pre-build is where a platform writes Conf/target.txt, sets PACKAGES_PATH, and otherwise does what edksetup.bat plus a hand-edited target file used to do. Post-build is where OVMF can launch QEMU. The environment can be pointed at a different build executable with EDK_BUILD_CMD, and extra arguments can be handed to it with EDK_BUILD_PARAMS. That is the supported way to wrap build, rather than editing Stuart.
For the core CI settings module, the work is split the same way, with one extra command. Once per session, from a clean shell: activate the virtual environment, pip install -r pip-requirements.txt --upgrade, then stuart_setup -c .pytool/CISettings.py. When Python dependencies or submodules move, repeat those. When BaseTools sources move, rebuild them with python BaseTools/Edk2ToolsBuild.py -t <tag> before expecting a firmware build to succeed. Then stuart_update, then either stuart_ci_build or a platform stuart_build.
Stuart will not choose a toolchain, write a DSC, or debug an AutoGen failure. When build reports an error, the failure is still an edk2 failure, and the place to look is still the build log, the DSC, and tools_def, not Stuart's settings manager.
Building OVMF
To test out Stuart, let's build the OVMF image. OVMF is the BIOS image that edk2 builds for QEMU, and the tree already contains a settings file. As mentioned in the previous section, OVMF keeps its platform module at OvmfPkg/PlatformCI/PlatformBuild.py. From the root of a current edk2 checkout, on Windows, with Visual Studio 2026 installed and a Python virtual environment active (py -m venv .venv & .venv\Scripts\activate.bat), I ran:
pip install --upgrade -r pip-requirements.txt
python BaseTools/Edk2ToolsBuild.py -t VS2026
stuart_setup -c OvmfPkg/PlatformCI/PlatformBuild.py -a IA32,X64 TOOL_CHAIN_TAG=VS2026
stuart_update -c OvmfPkg/PlatformCI/PlatformBuild.py -a IA32,X64 TOOL_CHAIN_TAG=VS2026
stuart_build -c OvmfPkg/PlatformCI/PlatformBuild.py -a IA32,X64 TOOL_CHAIN_TAG=VS2026
stuart_build -c OvmfPkg/PlatformCI/PlatformBuild.py -a IA32,X64 TOOL_CHAIN_TAG=VS2026 --flashrom-a IA32,X64 is the combination that selects OvmfPkgIa32X64.dsc: IA32 for PEI, X64 for DXE. -a X64 builds both PEI and DXE as X64, and in this settings file that is OvmfPkgX64.dsc. TARGET=RELEASE selects the release target; the default target is DEBUG.
--flashrom on that same stuart_build command line is an OVMF post-build step. It takes the image just produced and starts QEMU against it. (qemu-system-x86_64.exe has to be in PATH)
--flashonly skips the compile and runs QEMU against an image already built.
Finally, the build completed and QEMU launched:
A note on stuart_ci_build
stuart_ci_build runs the CI plugins across the packages the CI settings file lists. One of the plugins is CompilerPlugin, which builds each package DSC, so a CI run does compile code. A local CI run is the same code edk2's Azure Pipelines jobs run.
The checks currently wired in edk2's .pytool/Readme.md are:
- CompilerPlugin — build every package-level DSC for the selected toolchains and architectures.
- HostUnitTestCompilerPlugin — build the host-based unit-test DSC and, on Windows, run those tests.
- DscCompleteCheck and HostUnitTestDscCompleteCheck — every INF the package owns is actually listed in the package DSC, so a module cannot silently drop out of the build.
- GuidCheck — FILE_GUIDs and DEC GUIDs are unique across the repository.
- DependencyCheck — a package does not depend on a package outside its allowed set.
- LibraryClassCheck — each library header has a matching LibraryClass in the DEC.
- CharEncodingCheck — no source file contains a character that will break a build under a different code page.
- SpellCheck — cspell over the package.
- LicenseCheck — newly added files carry the BSD-2-Clause-Patent license.
- EccCheck — the BaseTools ECC coding-standard tool.
- UncrustifyCheck — formatting against the EDK II coding standard.
-p restricts the package list. -a restricts the architectures. -t restricts the target. Two values of -t are worth remembering. NOOPT is the target the host unit tests build under, so a unit-test-only run is -t NOOPT. NO-TARGET tells the CI run not to compile firmware at all and to execute the other plugins only.
Reporting
There is also a reporting feature that is easy to miss because it is not part of the compile. stuart_parse walks the workspace into a SQLite database, and stuart_report runs queries against it. This is a good tool to use when asking questions like where is this GUID defined or which modules consume this library class, rather than does this tree build.
Conclusion
Stuart is a relatively new, but essential, tool in the edk2 ecosystem. It is best understood as an orchestration layer around edk2. The traditional build tools still compile the modules and construct the firmware image; Stuart makes sure the correct source, tools, binaries, variables, plugins, and validation steps are in place before and after that happens. Check it out!
Stuart's behavior is documented in the edk2-pytool-extensions manual. Specific links:
|
Topic |
Page |
|
Install |
|
|
stuart_setup, stuart_update, stuart_build |
|
|
stuart_ci_setup, stuart_ci_build |
|
|
What the settings class must implement |
|
|
Scopes, paths, and why setup does not touch a dirty submodule |
|
|
_extdep.json, NuGet, git, web, Azure feeds |
|
|
OMNICACHE_PATH, EDK_BUILD_CMD, EDK_BUILD_PARAMS |
|
|
Writing a platform settings file |


Post a Comment
Be sure to select an account profile (e.g. Google, OpenID, etc.) before typing your comment!