--- /dev/null
+# ArmVirtPkg - Platform CI\r
+\r
+This Readme.md describes the Azure DevOps based Platform CI for ArmVirtPkg and how\r
+to use the same Pytools based build infrastructure locally.\r
+\r
+## Supported Configuration Details\r
+\r
+This solution for building and running ArmVirtPkg has only been validated with Ubuntu\r
+18.04 and the GCC5 toolchain. Two different firmware builds are supported and are\r
+described below.\r
+\r
+| Configuration name | Architecture | DSC File |Additional Flags |\r
+| :---------- | :----- | :----- | :---- |\r
+| AARCH64 | AARCH64 | ArmVirtQemu.dsc | None |\r
+| ARM | ARM | ArmVirtQemu.dsc | None |\r
+\r
+## EDK2 Developer environment\r
+\r
+- [Python 3.8.x - Download & Install](https://www.python.org/downloads/)\r
+- [GIT - Download & Install](https://git-scm.com/download/)\r
+- [QEMU - Download, Install, and add to your path](https://www.qemu.org/download/)\r
+- [Edk2 Source](https://github.com/tianocore/edk2)\r
+- Additional packages found necessary for Ubuntu 18.04\r
+ - apt-get install gcc g++ make uuid-dev\r
+\r
+Note: edksetup, Submodule initialization and manual installation of NASM, iASL, or\r
+the required cross-compiler toolchains are **not** required, this is handled by the\r
+Pytools build system.\r
+\r
+## Building with Pytools for ArmVirtPkg\r
+\r
+1. [Optional] Create a Python Virtual Environment - generally once per workspace\r
+\r
+ ``` bash\r
+ python -m venv <name of virtual environment>\r
+ ```\r
+\r
+2. [Optional] Activate Virtual Environment - each time new shell opened\r
+ - Windows\r
+\r
+ ``` bash\r
+ <name of virtual environment>/Scripts/activate.bat\r
+ ```\r
+\r
+ - Linux\r
+\r
+ ```bash\r
+ source <name of virtual environment>/bin/activate\r
+ ```\r
+\r
+3. Install Pytools - generally once per virtual env or whenever pip-requirements.txt changes\r
+\r
+ ``` bash\r
+ pip install --upgrade -r pip-requirements.txt\r
+ ```\r
+\r
+4. Initialize & Update Submodules - only when submodules updated\r
+\r
+ ``` bash\r
+ stuart_setup -c ArmVirtPkg/PlatformCI/PlatformBuild.py TOOL_CHAIN_TAG=<TOOL_CHAIN_TAG> -a <TARGET_ARCH>\r
+ ```\r
+\r
+5. Initialize & Update Dependencies - only as needed when ext_deps change\r
+\r
+ ``` bash\r
+ stuart_update -c ArmVirtPkg/PlatformCI/PlatformBuild.py TOOL_CHAIN_TAG=<TOOL_CHAIN_TAG> -a <TARGET_ARCH>\r
+ ```\r
+\r
+6. Compile the basetools if necessary - only when basetools C source files change\r
+\r
+ ``` bash\r
+ python BaseTools/Edk2ToolsBuild.py -t <ToolChainTag>\r
+ ```\r
+\r
+7. Compile Firmware\r
+\r
+ ``` bash\r
+ stuart_build -c ArmVirtPkg/PlatformCI/PlatformBuild.py TOOL_CHAIN_TAG=<TOOL_CHAIN_TAG> -a <TARGET_ARCH>\r
+ ```\r
+\r
+ - use `stuart_build -c ArmVirtPkg/PlatformCI/PlatformBuild.py -h` option to see additional\r
+ options like `--clean`\r
+\r
+8. Running Emulator\r
+ - You can add `--FlashRom` to the end of your build command and the emulator will run after the\r
+ build is complete.\r
+ - or use the `--FlashOnly` feature to just run the emulator.\r
+\r
+ ``` bash\r
+ stuart_build -c ArmVirtPkg/PlatformCI/PlatformBuild.py TOOL_CHAIN_TAG=<TOOL_CHAIN_TAG> -a <TARGET_ARCH> --FlashOnly\r
+ ```\r
+\r
+### Notes\r
+\r
+1. Including the expected build architecture and toolchain to the _stuart_update_ command is critical.\r
+ This is because there are extra scopes and tools that will be resolved during the update step that\r
+ need to match your build step.\r
+2. Configuring *ACTIVE_PLATFORM* and *TARGET_ARCH* in Conf/target.txt is **not** required. This\r
+ environment is set by PlatformBuild.py based upon the `[-a <TARGET_ARCH>]` parameter.\r
+3. QEMU must be on your path. On Windows this is a manual process and not part of the QEMU installer.\r
+\r
+**NOTE:** Logging the execution output will be in the normal stuart log as well as to your console.\r
+\r
+### Custom Build Options\r
+\r
+**MAKE_STARTUP_NSH=TRUE** will output a *startup.nsh* file to the location mapped as fs0. This is\r
+used in CI in combination with the `--FlashOnly` feature to run QEMU to the UEFI shell and then execute\r
+the contents of *startup.nsh*.\r
+\r
+**QEMU_HEADLESS=TRUE** Since CI servers run headless QEMU must be told to run with no display otherwise\r
+an error occurs. Locally you don't need to set this.\r
+\r
+### Passing Build Defines\r
+\r
+To pass build defines through _stuart_build_, prepend `BLD_*_`to the define name and pass it on the\r
+command-line. _stuart_build_ currently requires values to be assigned, so add an`=1` suffix for bare defines.\r
+For example, to enable the TPM2 support, instead of the traditional "-D TPM2_ENABLE=TRUE", the stuart_build\r
+command-line would be:\r
+\r
+`stuart_build -c ArmVirtPkg/PlatformCI/PlatformBuild.py BLD_*_TPM2_ENABLE=TRUE`\r
+\r
+## References\r
+\r
+- [Installing and using Pytools](https://github.com/tianocore/edk2-pytool-extensions/blob/master/docs/using.md#installing)\r
+- More on [python virtual environments](https://docs.python.org/3/library/venv.html)\r
projects / mirror_edk2.git / blobdiff