• Git - Source Control Management (SCM) Tool

  Git is the source control management tool used by this project.

  You needgit to pull the edk2 source code onto your system, make changes in the code, and submityour changes back to the GitHub repository.

  Git Download Page

• Python

  Python is a programming language that many of the edk2 build tools are written in.

  You will need Python to run the edk2 build tools includingstuart, which is written in Python.

  It is recommended you install a Python version that is equal to the version used in theUsePythonVersion@0 step in this file.azurepipelines/templates/pr-gate-steps.yml.

  That version is constantly tested against the code in the repository.

  Python Download Page

• C Compiler

  A C compiler is needed to compile the firmware code.

  Several options are available. This is an area where direct guidance cannot be provided.

  You will need to choose a compiler supported on your host operating system and the particular firmware packagesyou are building.

  However, it is common to use:

  • GCC on Linux
  Ubuntu GCC Installation Instructions
  apt-get update && apt-get install -y build-essential git nasm wget m4 bison flex uuid-dev python unzip acpica-tools gcc-multilib
  • Visual Studio on Windows
  Visual Studio Installation Instructions (Windows)

  
  

  Visual Studio 2022 Installation Instructions

  ---

  Click to downloadVisual Studio 2022 Build Tools

  1. Open anAdministrator Command Prompt by right-clicking onCommand Prompt and selectRun as Administrator
  2. Change to the directory where you downloaded thevs_BuildTools.exe file (e.g.C:\Downloads)
  3. Enter the following command:
     start /w vs_BuildTools.exe --quiet --wait --norestart --nocache --installPath C:\BuildTools ^ --add Microsoft.VisualStudio.Component.VC.CoreBuildTools --add Microsoft.VisualStudio.Component.VC.Tools.x86.x64 ^ --add Microsoft.VisualStudio.Component.Windows11SDK.22000 --add Microsoft.VisualStudio.Component.VC.Tools.ARM ^ --add Microsoft.VisualStudio.Component.VC.Tools.ARM64

  ---

  Visual Studio 2019 Installation Instructions

  ---

  Click to downloadVisual Studio 2019 Build Tools

  1. Open anAdministrator Command Prompt by right-clicking onCommand Prompt and selectRun as Administrator
  2. Change to the directory where you downloaded thevs_BuildTools.exe file (e.g.C:\Downloads)
  3. Enter the following command:
     start /w vs_BuildTools.exe --quiet --wait --norestart --nocache --installPath C:\BuildTools ^ --add Microsoft.VisualStudio.Component.VC.CoreBuildTools --add Microsoft.VisualStudio.Component.VC.Tools.x86.x64 ^ --add Microsoft.VisualStudio.Component.Windows10SDK.19041 --add Microsoft.VisualStudio.Component.VC.Tools.ARM ^ --add Microsoft.VisualStudio.Component.VC.Tools.ARM64

  ---

  Visual Studio 2017 Installation Instructions

  ---

  Click to downloadVisual Studio 2017 Build Tools

  1. Open anAdministrator Command Prompt by right-clicking onCommand Prompt and selectRun as Administrator
  2. Change to the directory where you downloaded thevs_BuildTools.exe file (e.g.C:\Downloads)
  3. Enter the following command:
     start /w vs_BuildTools.exe --quiet --wait --norestart --nocache --installPath C:\BuildTools ^ --add Microsoft.VisualStudio.Component.VC.CoreBuildTools --add Microsoft.VisualStudio.Component.VC.Tools.x86.x64 ^ --add Microsoft.VisualStudio.Component.Windows10SDK.17763 --add Microsoft.VisualStudio.Component.VC.Tools.ARM ^ --add Microsoft.VisualStudio.Component.VC.Tools.ARM64

  ---

  • Note: You can find the latest version of Visual Studio supported by edk2 on theCI Status section of the repo readme file.
  • Note: If you still run into build problems finding tools in the SDK, try installing the Windows SDK manually using the following instructions.

  Optional: Install the Windows SDK manually

  ---

  Download the Windows Software Development Kit (SDK) fromWindows Dev Center - Windows SDK

  Follow the default options until you reach the "Select the features you want to install" page.

  Select the following options:

  • Windows SDK Signing Tools for Desktop Apps
  • Windows SDK for UWP Managed Apps
  • Windows SDK for UWP C++ Apps
  • Windows SDK for Desktop C++ x86 Apps
  • Windows SDK for Desktop C++ amd64 Apps
  • Windows SDK for Desktop C++ arm Apps

  ClickDownload and complete the installation process.

  ---

• Mono (Linux)

  Mono needs to be installed on Linux.

  apt-get install mono-complete

The important parameter here is the-p parameter which specifies thatMdeModulePkg should be built.

The example below uses:

• TheTOOL_CHAIN_TAG parameter to specify the build should useVS2019 (Visual Studio 2019).
• The-a parameter is used to specify that theIA32 andX64 architectures should be built.

stuart_ci_build -c .pytool/CISettings.py -p MdeModulePkg -a IA32,X64 TOOL_CHAIN_TAG=VS2019

This example shows how to run only the host-based unit tests inMdeModulePkg.

• Normally, all package supported targets are tested including unit tests.
• Unit tests are run for theNOOPT target.

stuart_ci_build -c .pytool/CISettings.py -p MdeModulePkg -a IA32,X64 TOOL_CHAIN_TAG=VS2019 -t NOOPT

The important parameter here is the-t parameter which specifies that only theNOOPT target should be built.

OvmfPkg is considered a "platform firmware" for theQEMU open-source emulator.

• Therefore, it provides a platform build file (seeWhat is PlatformBuild.py?)
  • Located atOvmfPkg/PlatformCI/PlatformBuild.py
• Because we are building a platform build file, the build command will bestuart_build instead ofstuart_ci_buildto compile the code

As a one-time step (and when binary dependencies are updated):

stuart_update -c PlatformBuild.py

Then to build:

stuart_build -c PlatformBuild.py -a IA32,X64 TOOL_CHAIN_TAG=VS2019

If you want to run CI checks such as CI plugins, you can usestuart_ci_build with the CI build file.

stuart_ci_build -c .pytool/CISettings.py -p OvmfPkg -a IA32,X64 TOOL_CHAIN_TAG=VS2019

OvmfPkg is considered a "platform firmware" for theQEMU open-source emulator.

• Therefore, it provides a platform build file (seeWhat is PlatformBuild.py?)
  • Located atOvmfPkg/PlatformCI/PlatformBuild.py
• Because we are building a platform build file, the build command will bestuart_build instead ofstuart_ci_build

To see what parameters are supported by this platform build file (at the time this page was written), we can passthe--help argument to thestuart_build command:

    ❯ stuart_build -c PlatformBuild.py --help    usage: stuart_build [-h] [--SKIPBUILD] [--SKIPPREBUILD] [--SKIPPOSTBUILD] [--FLASHONLY] [--FLASHROM]                        [--UPDATECONF] [--CLEAN] [--CLEANONLY] [--OUTPUTCONFIG OUTPUTCONFIG] [-a BUILD_ARCH]                        [--build-config BUILD_CONFIG] [--verbose]    options:      -h, --help            show this help message and exit      --SKIPBUILD, --skipbuild, --SkipBuild                            Skip the build process      --SKIPPREBUILD, --skipprebuild, --SkipPrebuild                            Skip prebuild process      --SKIPPOSTBUILD, --skippostbuild, --SkipPostBuild                            Skip postbuild process      --FLASHONLY, --flashonly, --FlashOnly                            Flash rom after build.      --FLASHROM, --flashrom, --FlashRom                            Flash rom. Rom must be built previously.      --UPDATECONF, --updateconf, --UpdateConf                            Update Conf. Builders Conf files will be replaced with latest template files      --CLEAN, --clean, --CLEAN                            Clean. Remove all old build artifacts and intermediate files      --CLEANONLY, --cleanonly, --CleanOnly                            Clean Only. Do clean operation and don't build just exit.      --OUTPUTCONFIG OUTPUTCONFIG, --outputconfig OUTPUTCONFIG, --OutputConfig OUTPUTCONFIG                            Provide shell variables in a file      -a BUILD_ARCH, --arch BUILD_ARCH                            Optional - CSV of architecture to build. IA32 will use IA32 for Pei & Dxe. X64 will use                            X64 for both PEI and DXE. IA32,X64 will use IA32 for PEI and X64 for DXE. default is                            IA32,X64      --build-config BUILD_CONFIG                            Provide shell variables in a file      --verbose, --VERBOSE, -v                            verbose    positional arguments:      <key>=<value>              - Set an env variable for the pre/post build process      BLD_*_<key>=<value>        - Set a build flag for all build types                                  (key=value will get passed to build process)      BLD_<TARGET>_<key>=<value> - Set a build flag for build type of <target>                                  (key=value will get passed to build process for given build type)

The--flashonly and--flashrom commands are especially useful with OvmfPkg. They automatically load QEMU with thenewly built firmware.

The example below uses:

• TheTOOL_CHAIN_TAG parameter to specify that the build should useGCC5 to build with GCC.
• The-a parameter is used to specify theIA32 andX64 architectures should be built.
• The--flashrom parameter is used to load the firmware in QEMU and boot QEMU after the firmware build is completed.

stuart_build -c PlatformBuild.py -a IA32,X64 TOOL_CHAIN_TAG=GCC5 --flashrom

BaseTools has its own build script that leveragesedk2-pytools tobuild the BaseTools applications.

The fileBaseTools/Edk2ToolsBuild.pycan be called as a standalone Python script. You just need to pass the tool chain tag you would like to build with.

Example:python3 BaseTools/Edk2ToolsBuild.py -t GCC5

TheNO-TARGET build target specifies that the actual firmware source code should not be built for anyparticular target and, instead, the other parts of the CI process will be active such as the non-compiler checks(plugins).

In the following example, the CI plugins will be run against all packages supported by theCISettings.py file.

stuart_ci_build -c .pytool/CISettings.py -t NO-TARGET

The CI checks could be run against a single package (or a selection of packages) by passing the package names towith the-p parameter.

stuart_ci_build -c .pytool/CISettings.py -p MdePkg,UefiCpuPkg -t NO-TARGET

Plugins are automatically discovered in the workspace by stuart.

Stuart supports command-line arguments to disable all discovered plugins and only run those explicitly requested.The following command disables all plugins and then enables onlySpellCheck:

stuart_ci_build -c .pytool/CISettings.py --disable-all SpellCheck=run

Alternative Method

You can also simply delete the other plugin directories so they are not discovered. You can then test with theremaining plugins and then use git to restore the deleted plugin directories back when done testing.

For example, to only test with theSpellCheck plugin, delete every other plugin folder from.pytool/Plugin in your workspace.

Run the command to only perform CI checks:

stuart_ci_build -c .pytool/CISettings.py -t NO-TARGET

When done, restore the other plugin directories:git restore .pytool/Plugin/**

Continuous Integration

Continuous integration is used in edk2 to test new contributions before they are merged to the edk2 main branch.Stuart is used within the edk2 CI process to pull build dependencies and build the code.

You can use stuart to perform the same CI checks locally that are done on the server (see the examples section).

Also seeEDK II Continuous Integration.

A collection of build related tools for edk2.

Examples:

• AutoGen
• Build
• GenSec
• GenFV
• GenFW
• GenRds

Each tool has a user manual located inBaseTools/UserManuals.

A more complete list of BaseTools is located in theEDK II Tools List.

A collection of Python code for working with edk2.

• edk2-pytool-library - Pythonlibrary code that seeks to provide an easy way to organize and share edk2 related functionality to facilitatereuse across environments, tools, and scripts.
• edk2-pytool-extensions - APython project that consists of command line and other tools and extensions for building and maintaining an edk2based UEFI firmware code tree.

CISettings.py is a common name given to a configuration file used with Stuart for CI. It is oftenstored in a folder named.pytools in the root of a repository. So you'll likely encounter commandslike the following be used with the file:

• stuart_ci_setup -c .pytool/CISettings.py TOOL_CHAIN_TAG=PUT_TAG_VALUE_HERE
• stuart_update -c .pytool/CISettings.py TOOL_CHAIN_TAG=PUT_TAG_VALUE_HERE
• stuart_ci_build -c .pytool/CISettings.py TOOL_CHAIN_TAG=PUT_TAG_VALUE_HERE

PlatformBuild.py is a common name given to a configuration file used with Stuart for platform build.It is often stored in the root directory of the package it builds.

For example:

• stuart_setup -c SomePkg/PlatformBuild.py TOOL_CHAIN_TAG=PUT_TAG_VALUE_HERE
• stuart_update -c SomePkg/PlatformBuild.py TOOL_CHAIN_TAG=PUT_TAG_VALUE_HERE
• stuart_build -c SomePkg/PlatformBuild.py TOOL_CHAIN_TAG=PUT_TAG_VALUE_HERE

Like Stuart CI has "CI plugins", the build process has "build plugins". These can hook into the build in"pre-build" or "post-build".

Note: Build plugins will also run during CI if a CompilerPlugin is present that builds the code.

• stuart_ci_build - Runs CI plugins. By default, often runs CI on several packages at once. Thisincludes all of the checks needed to consider the code ready for integration to the mainline.
• stuart_build - Does not run CI plugins. Builds one platform. Platforms often exposeplatform-specific parameters as defined in theirPlatformBuild.py file.

The Stuart CI process is composed of "CI plugins" that get discovered in the code tree at CI time and hook intothe CI process. Some examples of CI plugins are a host-based unit test compile and execution, spell checking thecode, performing markdown lint on the code, etc. Firmware (C code) compilation is performed during CI by a compilerCI plugin.

Each plugin reports back a pass/fail status. If any plugin fails, CI fails. However, plugins usually provide somelevel of customization in a "CI package configuration file". If this file is present, it is in the root of thepackage with the naming conventionPkgName.ci.yaml. For example,MdePkg.ci.yaml is the CI package configurationfile forMdePkg. Sometimes, CI plugins will allow the plugin to be set to run in "audit mode" so the plugin will runand report results but not fail CI if errors are found. As an example, some packages in edk2 currently use this file torun the spell checker CI plugin in audit mode.

The two main places to look for CI settings are:

• The CISettings.py file - Usually has repo-wide CI settings
• The CI package configuration file - Has package-specific CI settings for a given package

You can pass the-v argument to Stuart commands to get more detailed output.

Also, look in your/Build directory.

Each Stuart command produces a separate file. Open the file corresponding to the command you're using that has thefailure.

• stuart_ci_setup -CISETUP.txt
• stuart_setup -SETUPLOG.txt
• stuart_update -UPDATE_LOG.txt
• stuart_ci_build -CI_BUILDLOG.txt
• stuart_build -BUILDLOG_PACKAGENAME.txt

The different types of plugins supported by Stuart and details about each type are available in theedk2-pytool-extensions Plugin Managerpage.

Start in theedk2-pytool-extensions User Documentation.