OvmfPkg/PlatformCI/ReadMe.md

   1 # OvmfPkg - Platform CI
   2
   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.
   5
   6 ## Supported Configuration Details
   7
   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.
  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 TPM1_ENABLE=1 TPM2_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
  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
  30 Pytools build system.
  31
  32 ## Building with Pytools for OvmfPkg
  33
  34 If you are unfamiliar with Pytools, it is recommended to first read through
  35 the generic set of edk2 [Build Instructions](https://github.com/tianocore/tianocore.github.io/wiki/Build-Instructions).
  36
  37 1. [Optional] Create a Python Virtual Environment - generally once per workspace
  38
  39     ``` bash
  40     python -m venv <name of virtual environment>
  41     ```
  42
  43 2. [Optional] Activate Virtual Environment - each time new shell opened
  44     - Linux
  45
  46       ```bash
  47       source <name of virtual environment>/bin/activate
  48       ```
  49
  50     - Windows
  51
  52       ``` bash
  53       <name of virtual environment>/Scripts/activate.bat
  54       ```
  55
  56 3. Install Pytools - generally once per virtual env or whenever pip-requirements.txt changes
  57
  58     ``` bash
  59     pip install --upgrade -r pip-requirements.txt
  60     ```
  61
  62 4. Initialize & Update Submodules - only when submodules updated
  63
  64     ``` bash
  65     stuart_setup -c OvmfPkg/PlatformCI/PlatformBuild.py TOOL_CHAIN_TAG=<TOOL_CHAIN_TAG> -a <TARGET_ARCH>
  66     ```
  67
  68 5. Initialize & Update Dependencies - only as needed when ext_deps change
  69
  70     ``` bash
  71     stuart_update -c OvmfPkg/PlatformCI/PlatformBuild.py TOOL_CHAIN_TAG=<TOOL_CHAIN_TAG> -a <TARGET_ARCH>
  72     ```
  73
  74 6. Compile the basetools if necessary - only when basetools C source files change
  75
  76     ``` bash
  77     python BaseTools/Edk2ToolsBuild.py -t <ToolChainTag>
  78     ```
  79
  80 7. Compile Firmware
  81     - To build IA32
  82
  83     ``` bash
  84     stuart_build -c OvmfPkg/PlatformCI/PlatformBuild.py -a IA32 TOOL_CHAIN_TAG=<TOOL_CHAIN_TAG>
  85     ```
  86
  87     - To build X64
  88
  89     ``` bash
  90     stuart_build -c OvmfPkg/PlatformCI/PlatformBuild.py -a X64 TOOL_CHAIN_TAG=<TOOL_CHAIN_TAG>
  91     ```
  92
  93     - To build IA32 X64
  94
  95     ``` bash
  96     stuart_build -c OvmfPkg/PlatformCI/PlatformBuild.py -a IA32,X64 TOOL_CHAIN_TAG=<TOOL_CHAIN_TAG>
  97     ```
  98
  99     - use `stuart_build -c OvmfPkg/PlatformCI/PlatformBuild.py -h` option to see additional
 100     options like `--clean`
 101
 102 8. Running Emulator
 103     - You can add `--FlashRom` to the end of your build command and the emulator will run after the
 104     build is complete.
 105     - or use the `--FlashOnly` feature to just run the emulator.
 106
 107       ``` bash
 108       stuart_build -c OvmfPkg/PlatformCI/PlatformBuild.py TOOL_CHAIN_TAG=<TOOL_CHAIN_TAG> -a <TARGET_ARCH> --FlashOnly
 109       ```
 110
 111 ### Notes
 112
 113 1. Configuring *ACTIVE_PLATFORM* and *TARGET_ARCH* in Conf/target.txt is **not** required. This
 114    environment is set by PlatformBuild.py based upon the `[-a <TARGET_ARCH>]` parameter.
 115 2. QEMU must be on your path.  On Windows this is a manual process and not part of the QEMU installer.
 116
 117 **NOTE:** Logging the execution output will be in the normal stuart log as well as to your console.
 118
 119 ### Custom Build Options
 120
 121 **MAKE_STARTUP_NSH=TRUE** will output a *startup.nsh* file to the location mapped as fs0. This is
 122 used in CI in combination with the `--FlashOnly` feature to run QEMU to the UEFI shell and then execute
 123 the contents of *startup.nsh*.
 124
 125 **QEMU_HEADLESS=TRUE** Since CI servers run headless QEMU must be told to run with no display otherwise
 126 an error occurs. Locally you don't need to set this.
 127
 128 ### Passing Build Defines
 129
 130 To pass build defines through _stuart_build_, prepend `BLD_*_`to the define name and pass it on the
 131 command-line. _stuart_build_ currently requires values to be assigned, so add an`=1` suffix for bare defines.
 132 For example, to enable the TPM2 support, instead of the traditional "-D E1000_ENABLE", the stuart_build
 133 command-line would be:
 134
 135 `stuart_build -c OvmfPkg/PlatformCI/PlatformBuild.py BLD_*_E1000_ENABLE=1`
 136
 137 ## References
 138
 139 - [Installing and using Pytools](https://github.com/tianocore/edk2-pytool-extensions/blob/master/docs/using.md#installing)
 140 - More on [python virtual environments](https://docs.python.org/3/library/venv.html)