ArmVirtPkg/PlatformCI/ReadMe.md

   1 # ArmVirtPkg - Platform CI
   2
   3 This Readme.md describes the Azure DevOps based Platform CI for ArmVirtPkg 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 ArmVirtPkg has only been validated with Ubuntu
   9 18.04 and the GCC5 toolchain. Two different firmware builds are supported and are
  10 described below.
  11
  12 | Configuration name      | Architecture       | DSC File         |Additional Flags |
  13 | :----------             | :-----             | :-----           | :----           |
  14 | AARCH64                 | AARCH64            | ArmVirtQemu.dsc  | None            |
  15 | ARM                     | ARM                | ArmVirtQemu.dsc  | None            |
  16
  17 ## EDK2 Developer environment
  18
  19 - [Python 3.8.x - Download & Install](https://www.python.org/downloads/)
  20 - [GIT - Download & Install](https://git-scm.com/download/)
  21 - [QEMU - Download, Install, and add to your path](https://www.qemu.org/download/)
  22 - [Edk2 Source](https://github.com/tianocore/edk2)
  23 - Additional packages found necessary for Ubuntu 18.04
  24   - apt-get install gcc g++ make uuid-dev
  25
  26 Note: edksetup, Submodule initialization and manual installation of NASM, iASL, or
  27 the required cross-compiler toolchains are **not** required, this is handled by the
  28 Pytools build system.
  29
  30 ## Building with Pytools for ArmVirtPkg
  31
  32 1. [Optional] Create a Python Virtual Environment - generally once per workspace
  33
  34     ``` bash
  35     python -m venv <name of virtual environment>
  36     ```
  37
  38 2. [Optional] Activate Virtual Environment - each time new shell opened
  39     - Windows
  40
  41       ``` bash
  42       <name of virtual environment>/Scripts/activate.bat
  43       ```
  44
  45     - Linux
  46
  47       ```bash
  48       source <name of virtual environment>/bin/activate
  49       ```
  50
  51 3. Install Pytools - generally once per virtual env or whenever pip-requirements.txt changes
  52
  53     ``` bash
  54     pip install --upgrade -r pip-requirements.txt
  55     ```
  56
  57 4. Initialize & Update Submodules - only when submodules updated
  58
  59     ``` bash
  60     stuart_setup -c ArmVirtPkg/PlatformCI/PlatformBuild.py TOOL_CHAIN_TAG=<TOOL_CHAIN_TAG> -a <TARGET_ARCH>
  61     ```
  62
  63 5. Initialize & Update Dependencies - only as needed when ext_deps change
  64
  65     ``` bash
  66     stuart_update -c ArmVirtPkg/PlatformCI/PlatformBuild.py TOOL_CHAIN_TAG=<TOOL_CHAIN_TAG> -a <TARGET_ARCH>
  67     ```
  68
  69 6. Compile the basetools if necessary - only when basetools C source files change
  70
  71     ``` bash
  72     python BaseTools/Edk2ToolsBuild.py -t <ToolChainTag>
  73     ```
  74
  75 7. Compile Firmware
  76
  77     ``` bash
  78     stuart_build -c ArmVirtPkg/PlatformCI/PlatformBuild.py TOOL_CHAIN_TAG=<TOOL_CHAIN_TAG> -a <TARGET_ARCH>
  79     ```
  80
  81     - use `stuart_build -c ArmVirtPkg/PlatformCI/PlatformBuild.py -h` option to see additional
  82     options like `--clean`
  83
  84 8. Running Emulator
  85     - You can add `--FlashRom` to the end of your build command and the emulator will run after the
  86     build is complete.
  87     - or use the `--FlashOnly` feature to just run the emulator.
  88
  89       ``` bash
  90       stuart_build -c ArmVirtPkg/PlatformCI/PlatformBuild.py TOOL_CHAIN_TAG=<TOOL_CHAIN_TAG> -a <TARGET_ARCH> --FlashOnly
  91       ```
  92
  93 ### Notes
  94
  95 1. Including the expected build architecture and toolchain to the _stuart_update_ command is critical.
  96    This is because there are extra scopes and tools that will be resolved during the update step that
  97    need to match your build step.
  98 2. Configuring *ACTIVE_PLATFORM* and *TARGET_ARCH* in Conf/target.txt is **not** required. This
  99    environment is set by PlatformBuild.py based upon the `[-a <TARGET_ARCH>]` parameter.
 100 3. QEMU must be on your path.  On Windows this is a manual process and not part of the QEMU installer.
 101
 102 **NOTE:** Logging the execution output will be in the normal stuart log as well as to your console.
 103
 104 ### Custom Build Options
 105
 106 **MAKE_STARTUP_NSH=TRUE** will output a *startup.nsh* file to the location mapped as fs0. This is
 107 used in CI in combination with the `--FlashOnly` feature to run QEMU to the UEFI shell and then execute
 108 the contents of *startup.nsh*.
 109
 110 **QEMU_HEADLESS=TRUE** Since CI servers run headless QEMU must be told to run with no display otherwise
 111 an error occurs. Locally you don't need to set this.
 112
 113 ### Passing Build Defines
 114
 115 To pass build defines through _stuart_build_, prepend `BLD_*_`to the define name and pass it on the
 116 command-line. _stuart_build_ currently requires values to be assigned, so add an`=1` suffix for bare defines.
 117 For example, to enable the TPM2 support, instead of the traditional "-D TPM2_ENABLE=TRUE", the stuart_build
 118 command-line would be:
 119
 120 `stuart_build -c ArmVirtPkg/PlatformCI/PlatformBuild.py BLD_*_TPM2_ENABLE=TRUE`
 121
 122 ## References
 123
 124 - [Installing and using Pytools](https://github.com/tianocore/edk2-pytool-extensions/blob/master/docs/using.md#installing)
 125 - More on [python virtual environments](https://docs.python.org/3/library/venv.html)