Steps to setup your environment, compile, and run QemuQ35Pkg and QemuSbsaPkg.
This is a Project Mu platform and thus the default environment requirements can be found here at the Project Mu Prerequisites page.
In addition if you want to run your locally compiled firmware you need
This build uses edk2-pytools for functionality. Documentation can be found here. On most Linux distros this requires an extra step for mono and nuget support. https://github.com/tianocore/edk2-pytool-extensions/blob/master/docs/usability/using_extdep.md#a-note-on-nuget-on-linux
Building with Pytools¶
[Optional] Create a Python Virtual Environment - generally once per workspace
python -m venv <name of virtual environment>
[Optional] Activate Virtual Environment - each time new shell opened
source <name of virtual environment>/bin/activate
<name of virtual environment>/Scripts/activate.bat
Install Pytools - generally once per virtual env or whenever pip-requirements.txt changes
pip install --upgrade -r pip-requirements.txt
Initialize & Update Submodules - only when submodules updated
stuart_setup -c Platforms/<Package>/PlatformBuild.py TOOL_CHAIN_TAG=<TOOL_CHAIN_TAG>
TOOL_CHAIN_TAGbeing the toolchain you want to build with, currently
GCC5are supported values. Q35 can be built with
VS2022toolchains. SBSA can be built with
Initialize & Update Dependencies - only as needed when ext_deps change
stuart_update -c Platforms/<Package>/PlatformBuild.py TOOL_CHAIN_TAG=<TOOL_CHAIN_TAG>
stuart_build -c Platforms/<Package>/PlatformBuild.py TOOL_CHAIN_TAG=<TOOL_CHAIN_TAG>
stuart_build -c Platforms/<Package>/PlatformBuild.py -hoption to see additional options like
- You can add
--FlashRomto the end of your build command and the emulator will run after the build is complete.
- or use the
--FlashOnlyfeature to just run the emulator.
stuart_build -c Platforms/<Package>/PlatformBuild.py TOOL_CHAIN_TAG=<TOOL_CHAIN_TAG> --FlashOnly
- You can add
- All the commands specified here can use a shortcut, which is to invoke the Build file directly. For example:
py Platforms/<Package>/PlatformBuild.py TOOL_CHAIN_TAG=<TOOL_CHAIN_TAG> --FlashOnly
- Setup and update can be done by passing it in
py Platforms/<Package>/PlatformBuild.py TOOL_CHAIN_TAG=<TOOL_CHAIN_TAG> --setup
py Platforms/<Package>/PlatformBuild.py TOOL_CHAIN_TAG=<TOOL_CHAIN_TAG> --update
- Under the hood, it just does the invocation of Stuart for you.
- QEMU must be on your path. On Windows this is a manual process and not part of the QEMU installer.
- QEMU output will be in Build directory.
NOTE: Logging the execution output will be in the normal stuart log as well as to your console (if you have the correct logging level set, by default it doesn't output to console).
Custom Build Options¶
SHUTDOWN_AFTER_RUN=TRUE will output a startup.nsh file to the location mapped as fs0 with
reset -s as
the final line. This is used in CI in combination with the
--FlashOnly feature to run QEMU to the UEFI shell
and then execute the contents of startup.nsh.
QEMU_HEADLESS=TRUE Since CI servers run headless QEMU must be told to run with no display otherwise an error occurs. Locally you don't need to set this.
GDB_SERVER=\<TCP Port> Enables the GDB port in the QEMU instance at the provided TCP port.
SERIAL_PORT=\<Serial Port> Enables the specified serial port to be used as console.
Passing Build Defines¶
To pass build defines through stuart_build, prepend
BLD_*_ to the define name and pass it on the
command-line. stuart_build currently requires values to be assigned, so add a
=1 suffix for bare defines.
For example, to enable the E1000 network support, instead of the traditional "-D E1000_ENABLE", the stuart_build
command-line would be:
stuart_build -c Platforms/<Package>/PlatformBuild.py BLD_*_E1000_ENABLE=1