ReadMe.md
1# OvmfPkg - Platform CI
2
3This ReadMe.md describes the Azure DevOps based Platform CI for OvmfPkg and how
4to use the same Pytools based build infrastructure locally.
5
6## Supported Configuration Details
7
8This solution for building and running OvmfPkg has only been validated with Windows 10
9with VS2019 and Ubuntu 18.04 with GCC5 toolchain. Four different firmware builds are
10supported and are described below.
11
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 TPM_ENABLE=1 TPM_CONFIG_ENABLE=1 NETWORK_TLS_ENABLE=1 NETWORK_IP6_ENABLE=1 NETWORK_HTTP_BOOT_ENABLE=1 |
18
19## EDK2 Developer environment
20
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
27
28Note: edksetup, Submodule initialization and manual installation of NASM, iASL, or
29the required cross-compiler toolchains are **not** required, this is handled by the
30Pytools build system.
31
32## Building with Pytools for OvmfPkg
33
341. [Optional] Create a Python Virtual Environment - generally once per workspace
35
36 ``` bash
37 python -m venv <name of virtual environment>
38 ```
39
402. [Optional] Activate Virtual Environment - each time new shell opened
41 - Linux
42
43 ```bash
44 source <name of virtual environment>/bin/activate
45 ```
46
47 - Windows
48
49 ``` bash
50 <name of virtual environment>/Scripts/activate.bat
51 ```
52
533. Install Pytools - generally once per virtual env or whenever pip-requirements.txt changes
54
55 ``` bash
56 pip install --upgrade -r pip-requirements.txt
57 ```
58
594. Initialize & Update Submodules - only when submodules updated
60
61 ``` bash
62 stuart_setup -c OvmfPkg/PlatformCI/PlatformBuild.py TOOL_CHAIN_TAG=<TOOL_CHAIN_TAG> -a <TARGET_ARCH>
63 ```
64
655. Initialize & Update Dependencies - only as needed when ext_deps change
66
67 ``` bash
68 stuart_update -c OvmfPkg/PlatformCI/PlatformBuild.py TOOL_CHAIN_TAG=<TOOL_CHAIN_TAG> -a <TARGET_ARCH>
69 ```
70
716. Compile the basetools if necessary - only when basetools C source files change
72
73 ``` bash
74 python BaseTools/Edk2ToolsBuild.py -t <ToolChainTag>
75 ```
76
777. Compile Firmware
78 - To build IA32
79
80 ``` bash
81 stuart_build -c OvmfPkg/PlatformCI/PlatformBuild.py -a IA32 TOOL_CHAIN_TAG=<TOOL_CHAIN_TAG>
82 ```
83
84 - To build X64
85
86 ``` bash
87 stuart_build -c OvmfPkg/PlatformCI/PlatformBuild.py -a X64 TOOL_CHAIN_TAG=<TOOL_CHAIN_TAG>
88 ```
89
90 - To build IA32 X64
91
92 ``` bash
93 stuart_build -c OvmfPkg/PlatformCI/PlatformBuild.py -a IA32,X64 TOOL_CHAIN_TAG=<TOOL_CHAIN_TAG>
94 ```
95
96 - use `stuart_build -c OvmfPkg/PlatformCI/PlatformBuild.py -h` option to see additional
97 options like `--clean`
98
998. Running Emulator
100 - You can add `--FlashRom` to the end of your build command and the emulator will run after the
101 build is complete.
102 - or use the `--FlashOnly` feature to just run the emulator.
103
104 ``` bash
105 stuart_build -c OvmfPkg/PlatformCI/PlatformBuild.py TOOL_CHAIN_TAG=<TOOL_CHAIN_TAG> -a <TARGET_ARCH> --FlashOnly
106 ```
107
108### Notes
109
1101. 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.
1122. QEMU must be on your path. On Windows this is a manual process and not part of the QEMU installer.
113
114**NOTE:** Logging the execution output will be in the normal stuart log as well as to your console.
115
116### Custom Build Options
117
118**MAKE_STARTUP_NSH=TRUE** will output a *startup.nsh* file to the location mapped as fs0. This is
119used in CI in combination with the `--FlashOnly` feature to run QEMU to the UEFI shell and then execute
120the contents of *startup.nsh*.
121
122**QEMU_HEADLESS=TRUE** Since CI servers run headless QEMU must be told to run with no display otherwise
123an error occurs. Locally you don't need to set this.
124
125### Passing Build Defines
126
127To pass build defines through _stuart_build_, prepend `BLD_*_`to the define name and pass it on the
128command-line. _stuart_build_ currently requires values to be assigned, so add an`=1` suffix for bare defines.
129For example, to enable the TPM2 support, instead of the traditional "-D E1000_ENABLE", the stuart_build
130command-line would be:
131
132`stuart_build -c OvmfPkg/PlatformCI/PlatformBuild.py BLD_*_E1000_ENABLE=1`
133
134## References
135
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)
138