EmulatorPkg/PlatformCI/ReadMe.md

   1 # EmulatorPkg - Platform CI
   2
   3 This ReadMe.md describes the Azure DevOps based Platform CI for EmulatorPkg 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 EmulatorPkg 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               | EmulatorPkg.dsc  | None            |
  15 | X64                     | X64                | EmulatorPkg.dsc  | None            |
  16 | IA32 Full               | IA32               | EmulatorPkg.dsc  | SECURE_BOOT_ENABLE=TRUE |
  17 | X64 Full                | X64                | EmulatorPkg.dsc  | SECURE_BOOT_ENABLE=TRUE |
  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 - [Edk2 Source](https://github.com/tianocore/edk2)
  24 - For building Basetools and other host applications
  25
  26   ``` bash
  27   sudo apt-get update
  28   sudo apt-get install gcc g++ make uuid-dev
  29   ```
  30
  31 - For building ARCH IA32 on X64 Ubuntu 18.04 LTS these steps where needed.
  32
  33   ``` bash
  34   sudo dpkg --add-architecture i386
  35   sudo apt-get update
  36   sudo apt-get install libc6-dev:i386 libx11-dev:i386 libxext-dev:i386 lib32gcc-7-dev
  37   ```
  38
  39 Note: edksetup, Submodule initialization and manual installation of NASM, iASL, or
  40 the required cross-compiler toolchains are **not** required, this is handled by the
  41 Pytools build system.
  42
  43 ## Building with Pytools for EmulatorPkg
  44
  45 If you are unfamiliar with Pytools, it is recommended to first read through
  46 the generic set of edk2 [Build Instructions](https://github.com/tianocore/tianocore.github.io/wiki/Build-Instructions).
  47
  48 1. [Optional] Create a Python Virtual Environment - generally once per workspace
  49
  50     ``` bash
  51     python -m venv <name of virtual environment>
  52     ```
  53
  54 2. [Optional] Activate Virtual Environment - each time new shell opened
  55     - Linux
  56
  57       ```bash
  58       source <name of virtual environment>/bin/activate
  59       ```
  60
  61     - Windows
  62
  63       ``` bash
  64       <name of virtual environment>/Scripts/activate.bat
  65       ```
  66
  67 3. Install Pytools - generally once per virtual env or whenever pip-requirements.txt changes
  68
  69     ``` bash
  70     pip install --upgrade -r pip-requirements.txt
  71     ```
  72
  73 4. Initialize & Update Submodules - only when submodules updated
  74
  75     ``` bash
  76     stuart_setup -c EmulatorPkg/PlatformCI/PlatformBuild.py TOOL_CHAIN_TAG=<TOOL_CHAIN_TAG> -a <TARGET_ARCH>
  77     ```
  78
  79 5. Initialize & Update Dependencies - only as needed when ext_deps change
  80
  81     ``` bash
  82     stuart_update -c EmulatorPkg/PlatformCI/PlatformBuild.py TOOL_CHAIN_TAG=<TOOL_CHAIN_TAG> -a <TARGET_ARCH>
  83     ```
  84
  85 6. Compile the basetools if necessary - only when basetools C source files change
  86
  87     ``` bash
  88     python BaseTools/Edk2ToolsBuild.py -t <ToolChainTag>
  89     ```
  90
  91 7. Compile Firmware
  92
  93     ``` bash
  94     stuart_build -c EmulatorPkg/PlatformCI/PlatformBuild.py TOOL_CHAIN_TAG=<TOOL_CHAIN_TAG> -a <TARGET_ARCH>
  95     ```
  96
  97     - use `stuart_build -c EmulatorPkg/PlatformCI/PlatformBuild.py -h` option to see additional
  98     options like `--clean`
  99
 100 8. Running Emulator
 101     - You can add `--FlashRom` to the end of your build command and the emulator will run after the
 102     build is complete.
 103     - or use the `--FlashOnly` feature to just run the emulator.
 104
 105       ``` bash
 106       stuart_build -c EmulatorPkg/PlatformCI/PlatformBuild.py TOOL_CHAIN_TAG=<TOOL_CHAIN_TAG> -a <TARGET_ARCH> --FlashOnly
 107       ```
 108
 109 ### Notes
 110
 111 1. Configuring *ACTIVE_PLATFORM* and *TARGET_ARCH* in Conf/target.txt is **not** required. This
 112    environment is set by PlatformBuild.py based upon the `[-a <TARGET_ARCH>]` parameter.
 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
 119 used in CI in combination with the `--FlashOnly` feature to run the Emulator to the UEFI shell and then execute
 120 the contents of *startup.nsh*.
 121
 122 ### Passing Build Defines
 123
 124 To pass build defines through _stuart_build_, prepend `BLD_*_`to the define name and pass it on the
 125 command-line. _stuart_build_ currently requires values to be assigned, so add an`=1` suffix for bare defines.
 126 For example, to enable the IP6 Network Stack, the stuart_build command-line would be:
 127
 128 `stuart_build -c EmulatorPkg/PlatformCI/PlatformBuild.py BLD_*_NETWORK_IP6_ENABLE=1`
 129
 130 ## References
 131
 132 - [Installing and using Pytools](https://github.com/tianocore/edk2-pytool-extensions/blob/master/docs/using.md#installing)
 133 - More on [python virtual environments](https://docs.python.org/3/library/venv.html)