1 # OvmfPkg - Platform CI
3 This ReadMe.md describes the Azure DevOps based Platform CI for OvmfPkg and how
4 to use the same Pytools based build infrastructure locally.
6 ## Supported Configuration Details
8 This solution for building and running OvmfPkg has only been validated with Windows 10
9 with VS2019 and Ubuntu 18.04 with GCC5 toolchain. Four different firmware builds are
10 supported and are described below.
12 | Configuration name | Architectures | DSC File |Additional Flags |
13 | :---- | :----- | :---- | :---- |
14 | IA32 | IA32 | OvmfPkgIa32.dsc | None |
15 | X64 | X64 | OvmfPkgIa64.dsc | None |
16 | IA32 X64 | PEI-IA32 DXE-X64 | OvmfPkgIa32X64.dsc | None |
17 | IA32 X64 Full | PEI-IA32 DXE-X64 | OvmfPkgIa32X64.dsc | SECURE_BOOT_ENABLE=1 SMM_REQUIRE=1 TPM1_ENABLE=1 TPM2_ENABLE=1 NETWORK_TLS_ENABLE=1 NETWORK_IP6_ENABLE=1 NETWORK_HTTP_BOOT_ENABLE=1 |
19 ## EDK2 Developer environment
21 - [Python 3.8.x - Download & Install](https://www.python.org/downloads/)
22 - [GIT - Download & Install](https://git-scm.com/download/)
23 - [QEMU - Download, Install, and add to your path](https://www.qemu.org/download/)
24 - [Edk2 Source](https://github.com/tianocore/edk2)
25 - Additional packages found necessary for Ubuntu 18.04
26 - apt-get install gcc g++ make uuid-dev
28 Note: edksetup, Submodule initialization and manual installation of NASM, iASL, or
29 the required cross-compiler toolchains are **not** required, this is handled by the
32 ## Building with Pytools for OvmfPkg
34 1. [Optional] Create a Python Virtual Environment - generally once per workspace
37 python -m venv <name of virtual environment>
40 2. [Optional] Activate Virtual Environment - each time new shell opened
44 source <name of virtual environment>/bin/activate
50 <name of virtual environment>/Scripts/activate.bat
53 3. Install Pytools - generally once per virtual env or whenever pip-requirements.txt changes
56 pip install --upgrade -r pip-requirements.txt
59 4. Initialize & Update Submodules - only when submodules updated
62 stuart_setup -c OvmfPkg/PlatformCI/PlatformBuild.py TOOL_CHAIN_TAG=<TOOL_CHAIN_TAG> -a <TARGET_ARCH>
65 5. Initialize & Update Dependencies - only as needed when ext_deps change
68 stuart_update -c OvmfPkg/PlatformCI/PlatformBuild.py TOOL_CHAIN_TAG=<TOOL_CHAIN_TAG> -a <TARGET_ARCH>
71 6. Compile the basetools if necessary - only when basetools C source files change
74 python BaseTools/Edk2ToolsBuild.py -t <ToolChainTag>
81 stuart_build -c OvmfPkg/PlatformCI/PlatformBuild.py -a IA32 TOOL_CHAIN_TAG=<TOOL_CHAIN_TAG>
87 stuart_build -c OvmfPkg/PlatformCI/PlatformBuild.py -a X64 TOOL_CHAIN_TAG=<TOOL_CHAIN_TAG>
93 stuart_build -c OvmfPkg/PlatformCI/PlatformBuild.py -a IA32,X64 TOOL_CHAIN_TAG=<TOOL_CHAIN_TAG>
96 - use `stuart_build -c OvmfPkg/PlatformCI/PlatformBuild.py -h` option to see additional
97 options like `--clean`
100 - You can add `--FlashRom` to the end of your build command and the emulator will run after the
102 - or use the `--FlashOnly` feature to just run the emulator.
105 stuart_build -c OvmfPkg/PlatformCI/PlatformBuild.py TOOL_CHAIN_TAG=<TOOL_CHAIN_TAG> -a <TARGET_ARCH> --FlashOnly
110 1. Configuring *ACTIVE_PLATFORM* and *TARGET_ARCH* in Conf/target.txt is **not** required. This
111 environment is set by PlatformBuild.py based upon the `[-a <TARGET_ARCH>]` parameter.
112 2. QEMU must be on your path. On Windows this is a manual process and not part of the QEMU installer.
114 **NOTE:** Logging the execution output will be in the normal stuart log as well as to your console.
116 ### Custom Build Options
118 **MAKE_STARTUP_NSH=TRUE** will output a *startup.nsh* file to the location mapped as fs0. This is
119 used in CI in combination with the `--FlashOnly` feature to run QEMU to the UEFI shell and then execute
120 the contents of *startup.nsh*.
122 **QEMU_HEADLESS=TRUE** Since CI servers run headless QEMU must be told to run with no display otherwise
123 an error occurs. Locally you don't need to set this.
125 ### Passing Build Defines
127 To pass build defines through _stuart_build_, prepend `BLD_*_`to the define name and pass it on the
128 command-line. _stuart_build_ currently requires values to be assigned, so add an`=1` suffix for bare defines.
129 For example, to enable the TPM2 support, instead of the traditional "-D E1000_ENABLE", the stuart_build
130 command-line would be:
132 `stuart_build -c OvmfPkg/PlatformCI/PlatformBuild.py BLD_*_E1000_ENABLE=1`
136 - [Installing and using Pytools](https://github.com/tianocore/edk2-pytool-extensions/blob/master/docs/using.md#installing)
137 - More on [python virtual environments](https://docs.python.org/3/library/venv.html)