From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mx0a-0031df01.pphosted.com (mx0a-0031df01.pphosted.com [205.220.168.131]) by mx.groups.io with SMTP id smtpd.web11.5938.1670474836783839486 for ; Wed, 07 Dec 2022 20:47:16 -0800 Authentication-Results: mx.groups.io; dkim=fail reason="body hash did not verify" header.i=@quicinc.com header.s=qcppdkim1 header.b=IK5eBl0O; spf=permerror, err=parse error for token &{10 18 %{ir}.%{v}.%{d}.spf.has.pphosted.com}: invalid domain name (domain: quicinc.com, ip: 205.220.168.131, mailfrom: quic_rcran@quicinc.com) Received: from pps.filterd (m0279863.ppops.net [127.0.0.1]) by mx0a-0031df01.pphosted.com (8.17.1.19/8.17.1.19) with ESMTP id 2B84Tuxl013546; Thu, 8 Dec 2022 04:47:10 GMT DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=quicinc.com; h=message-id : date : mime-version : subject : to : cc : references : from : in-reply-to : content-type : content-transfer-encoding; s=qcppdkim1; bh=DlsuLgTsyrhKYzMBCSEsCG0rTx2BIkiv/PQ9Id+h9KU=; b=IK5eBl0OjwSc4LGfjJ5RtYYIO4Mm/nE16kpQQqfb6Md1JwMNepFpLMTUJagakzgsCchc tdB5wLTQLm8kZnjV+rG5N7q76uuAEKraCtcEtwmwRTrXRK5+NcqP40zX8dCPhLQdUiHS THN8/Rkl87FP3Hx8AFjmNR7hS8SMO2nvy+fWRjAs9yxoT4k27t93xDARgdxeu7IqQ9ND l7wqDAr9tHjHTkTef75S7Y2kgo8jOb6ETztOBbA+TdtuZ1u7+U1/Lk4VB3ZJ3WMj/Ies U2di2dkZ+xyZZAapd1xhSIiuKAFt3SVQefRMNVi7JjokwCK86XqkZpqbehzJs/u10LxF 3g== Received: from nasanppmta05.qualcomm.com (i-global254.qualcomm.com [199.106.103.254]) by mx0a-0031df01.pphosted.com (PPS) with ESMTPS id 3mavtf22ee-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=NOT); Thu, 08 Dec 2022 04:47:09 +0000 Received: from nasanex01b.na.qualcomm.com (nasanex01b.na.qualcomm.com [10.46.141.250]) by NASANPPMTA05.qualcomm.com (8.17.1.5/8.17.1.5) with ESMTPS id 2B84l94i005555 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=NOT); Thu, 8 Dec 2022 04:47:09 GMT Received: from [10.110.10.233] (10.80.80.8) by nasanex01b.na.qualcomm.com (10.46.141.250) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.2.986.36; Wed, 7 Dec 2022 20:47:08 -0800 Message-ID: Date: Wed, 7 Dec 2022 21:47:07 -0700 MIME-Version: 1.0 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:102.0) Gecko/20100101 Thunderbird/102.5.1 Subject: Re: [edk2-devel] [edk2-wiki][PATCH v3 1/4] Add initial How to Build with Stuart Document To: , CC: Sean Brogan , Michael D Kinney , Liming Gao References: <20221207162403.337-1-mikuback@linux.microsoft.com> <20221207162403.337-2-mikuback@linux.microsoft.com> From: "Rebecca Cran" In-Reply-To: <20221207162403.337-2-mikuback@linux.microsoft.com> X-Originating-IP: [10.80.80.8] X-ClientProxiedBy: nasanex01a.na.qualcomm.com (10.52.223.231) To nasanex01b.na.qualcomm.com (10.46.141.250) X-QCInternal: smtphost X-Proofpoint-Virus-Version: vendor=nai engine=6200 definitions=5800 signatures=585085 X-Proofpoint-GUID: uYBbzduYFHgTbVkwyyVMjGZ1Y3Ek7cCL X-Proofpoint-ORIG-GUID: uYBbzduYFHgTbVkwyyVMjGZ1Y3Ek7cCL X-Proofpoint-Virus-Version: vendor=baseguard engine=ICAP:2.0.205,Aquarius:18.0.923,Hydra:6.0.545,FMLib:17.11.122.1 definitions=2022-12-08_02,2022-12-07_01,2022-06-22_01 X-Proofpoint-Spam-Details: rule=outbound_notspam policy=outbound score=0 impostorscore=0 lowpriorityscore=0 suspectscore=0 mlxscore=0 mlxlogscore=999 malwarescore=0 clxscore=1015 adultscore=0 spamscore=0 phishscore=0 bulkscore=0 priorityscore=1501 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.12.0-2210170000 definitions=main-2212080040 X-MIME-Autoconverted: from 8bit to quoted-printable by mx0a-0031df01.pphosted.com id 2B84Tuxl013546 Content-Language: en-US Content-Type: text/plain; charset="UTF-8"; format=flowed Content-Transfer-Encoding: quoted-printable What tool do you use to write the pages? It seems to be a mixture of markdown and HTML: for example I'm surprised=20 to see things like "C Compiler" - I'd expect something=20 like "**C Compiler**" instead. --=20 Rebecca Cran On 12/7/22 09:24, Michael Kubacki wrote: > From: Michael Kubacki >=20 > Adds a new document that comprehensively describes how to manually > set up a build environment using Stuart. >=20 > Covers the following topics: >=20 > 1. Pre-requisites - Git, Python, compilers, SDKs, etc. > 2. Initial steps - Cloning the repo, set up Python virtual env, etc. > 3. Stuart command explanation and corresponding examples > 4. Common developer scenarios with examples showing what to do > 5. Common questions section with answers >=20 > Stuart presents a relatively consistent interface to build most > content in edk2 so this document is meant as a long-term starting > point for new contributors to understand the basics of using Stuart > for various areas they are working in within edk2. >=20 > Cc: Sean Brogan > Cc: Michael D Kinney > Cc: Liming Gao > Signed-off-by: Michael Kubacki > --- > How-to-Build-With-Stuart.md | 758 ++++++++++++++++++++ > 1 file changed, 758 insertions(+) >=20 > diff --git a/How-to-Build-With-Stuart.md b/How-to-Build-With-Stuart.md > new file mode 100644 > index 000000000000..1f107f5bf7c2 > --- /dev/null > +++ b/How-to-Build-With-Stuart.md > @@ -0,0 +1,758 @@ > +# How to Build in edk2 with Stuart > + > +EDK II packages are easy to build with set of tools called "stuart". > + > +>=F0=9F=92=A1 If you are familiar with the `build` command and would l= ike to learn about `build` vs `stuart`, > +> [click here](Build-Instructions.md#build-option-comparison). > + > +Steps are split into two categories: [(1) one-time](#one-time-steps) a= nd [(2) regular use](#regular-use-steps). > + > +## One-Time Steps > + > +If you've already completed these steps you don't need to run them aga= in. > + > +
> + Pre-requisites (Git, Python, Compiler) > +
> + > +
    > +
  • > + Git - Source Control Management (SCM) Tool > + > + Git is the source control management tool used by this project. > + > + You need git to pull the edk2 source code onto your sys= tem, make changes in the code, and submit > + your changes back to the GitHub repository. > + > + Git Down= load Page > +
    • > +
  • > + Python > + > + Python is a programming language that many of the edk2 build tools a= re written in. > + > + You will need Python to run the edk2 build tools including stu= art, which is written in Python. > + > + It is recommended you install a Python version that is equal to the = version used in the > + UsePythonVersion@0 step in this file > + .azurepipelines/templ= ates/pr-gate-steps.yml. > + > + That version is constantly tested against the code in the repository. > + > + Pyth= on Download Page > +
    • > +
  • > + C Compiler > + > + A C compiler is needed to compile the firmware code. > + > + Several options are available. This is an area where direct guidance= cannot be provided. > + > + You will need to choose a compiler supported on your host operating = system and the particular firmware packages > + you are building. > + > + However, it is common to use: > +
      > +
    • GCC on = Linux
      • > +
      > + Ubuntu GCC Installation Instructions > + apt-get update && apt-get install -y build-essential git n= asm wget m4 bison flex uuid-dev python unzip acpica-tools gcc-multilib > +
      > +
    • Visual Studio on Windows
      • > +
      > + Visual Studio Installation Instructions (Windows) > +
      > +
      > + Visual Studio 2022 Installation Instructions > +
      > +

      > + Click to download Visual Studio 2022 Build Tools > +

      > +
        > +
      1. > + Open an Administrator Command Prompt by r= ight-clicking on Command Prompt > + and select Run as Administrator > +
        2. > +
      2. > + Change to the directory where you downloaded the vs_= BuildTools.exe file > + (e.g. C:\Downloads) > +
        3. > +
      3. > + Enter the following command: > +
        > + > + start /w vs_BuildTools.exe --quiet --wait --norestart --= nocache --installPath C:\BuildTools ^ > + --add Microsoft.VisualStudio.Component.VC.CoreBuildTools= --add Microsoft.VisualStudio.Component.VC.Tools.x86.x64 ^ > + --add Microsoft.VisualStudio.Component.Windows11SDK.2200= 0 --add Microsoft.VisualStudio.Component.VC.Tools.ARM ^ > + --add Microsoft.VisualStudio.Component.VC.Tools.ARM64 > + > +
        4. > +
      > +
      > +
      > +
      > + Visual Studio 2019 Installation Instructions > +
      > +

      > + Click to download Visual Studio 2019 Build Tools > +

      > +
        > +
      1. > + Open an Administrator Command Prompt by rig= ht-clicking on Command Prompt > + and select Run as Administrator > +
        2. > +
      2. > + Change to the directory where you downloaded the vs_Bu= ildTools.exe file > + (e.g. C:\Downloads) > +
        3. > +
      3. > + Enter the following command: > +
        > + > + start /w vs_BuildTools.exe --quiet --wait --norestart --no= cache --installPath C:\BuildTools ^ > + --add Microsoft.VisualStudio.Component.VC.CoreBuildTools -= -add Microsoft.VisualStudio.Component.VC.Tools.x86.x64 ^ > + --add Microsoft.VisualStudio.Component.Windows10SDK.19041 = --add Microsoft.VisualStudio.Component.VC.Tools.ARM ^ > + --add Microsoft.VisualStudio.Component.VC.Tools.ARM64 > + > +
        4. > +
      > +
      > +
      > +
      > + Visual Studio 2017 Installation Instructions > +
      > +

      > + Click to download Visual Studio 2017 Build Tools > +

      > +
        > +
      1. > + Open an Administrator Command Prompt by right= -clicking on Command Prompt and > + select Run as Administrator > +
        2. > +
      2. > + Change to the directory where you downloaded the vs_Buil= dTools.exe file > + (e.g. C:\Downloads) > +
        3. > +
      3. > + Enter the following command: > +
        > + > + start /w vs_BuildTools.exe --quiet --wait --norestart --no= cache --installPath C:\BuildTools ^ > + --add Microsoft.VisualStudio.Component.VC.CoreBuildTools -= -add Microsoft.VisualStudio.Component.VC.Tools.x86.x64 ^ > + --add Microsoft.VisualStudio.Component.Windows10SDK.17763 = --add Microsoft.VisualStudio.Component.VC.Tools.ARM ^ > + --add Microsoft.VisualStudio.Component.VC.Tools.ARM64 > + > +
        4. > +
      > +
      > +
      > +

      > +

        > +
      • > + Note: You can find the latest version of Visual Studio suppo= rted by edk2 on the > + CI Status section of the > + repo readme file. > +
        • > +
      • > + Note: If you still run into build problems finding tools in = the SDK, try installing the Windows SDK manually > + using the following instructions. > +
        • > +
      > +

      > +
      > + Optional: Install the Windows SDK manually > +
      > +

      > + Download the Windows Software Development Kit (SDK) from > + Windows Dev Center - Windows SDK > +

      > +

      > + Follow the default options until you reach the "Select= the features you want to install" page. > +

      > + Select the following options: > +
        > +
      • Windows SDK Signing Tools for Desktop Apps
        • > +
      • Windows SDK for UWP Managed Apps
        • > +
      • Windows SDK for UWP C++ Apps
        • > +
      • Windows SDK for Desktop C++ x86 Apps
        • > +
      • Windows SDK for Desktop C++ amd64 Apps
        • > +
      • Windows SDK for Desktop C++ arm Apps
        • > +
      > +

      > + Click Download and complete the installation = process. > +

      > +
      > +
      > +
    > +
    • > +
  • > + Mono (Linux) > +

    Mono= needs to be installed on Linux.

    > + apt-get install mono-complete > +
    • > +
> +
> +
> + > +1. Clone the edk2 repo > + - Open a command-prompt in the directory where you would like to ke= ep the edk2 repo > + - Clone the repo > + - Example: `git clone edk2` > + > +2. Change into the edk2 directory > + - `cd edk` > + > +3. Create a Python virtual environment > + - Note that the steps differ between Linux and Windows. > + -
> + Linux Instructions > + python -m venv .venv > +
> + source .venv/bin/activate > +
> + -
> + Windows Instructions > + py -m venv .venv > +
> + .venv\Scripts\activate.bat > +
> + > +4. Tell Git to ignore the Python virtual environment > + > + The problem: Git will try to track your Python virtual environment= as new code changes if it is not told to > + ignore it. > + > + - Open the file `.git/info/exclude` > + - `cd .git` > + - `cd info` > + - Open the `exclude` file in a text editor > + - Add the following line to the end of the file: > + - `*venv*/**` > + - Close the file > + - Note: Git will no longer try to track your Python virtual enviro= nments in this repository. > + > +That's it! > + > +Your terminal may now indicate that a virtual environment is active by= showing `(.venv)` before the > +current line. > + > +## Regular Use Steps > + > +These are steps you should run on a regular basis. > + > +The steps are split into three categories: (1) once per session, (2) w= hen dependencies are updated, and (3) before > +each build. > + > +### Once Per Session Steps > + > +These assume your command prompt is in the edk2 repository directory. > + > +1. Activate the Python virtual environment > + - Linux > + - `source .venv/bin/activate` > + - Windows > + - `.venv\Scripts\activate.bat` > + > +2. Update Python PIP modules > + - `pip install -r pip-requirements.txt --upgrade` > + > +3. Get updated code dependencies > + - `stuart_setup -c .pytool/CISettings.py` > + > +That's it! > + > +### When Dependencies are Updated Steps > + > +The edk2 repo has a number of dependencies on external content. For ex= ample, it depends on git submodules, Python pip > +modules, tools in the form of application binaries, etc. If the corres= ponding version information for these is updated > +in the repo, you will need to pull the update. > + > +The recommended steps to update dependencies are in this section. > + > +#### Git Submodules > + > +`git submodule update --init --recursive` > + > +#### Python PIP Modules > + > +`pip install -r pip-requirements.txt --upgrade` > + > +#### Rebuild BaseTools > + > +See the [BaseTools build example](#example-i-want-to-build-basetools). > + > +### Before Each Build Steps > + > +Now every time you would like to build the code, you only need to run = the following commands until you end this > +session and return. > + > +1. Update other dependencies (like binaries) > + - `stuart_update -c .pytool/CISettings.py` > + > +2. Run CI build (--help will give you options) > + - `stuart_ci_build -c .pytool/CISettings.py TOOL_CHAIN_TAG=3D` > + > + - Common options: > + - `-p `: To build only certain packages use a = comma-separated list > + - `-a `: To run only certain architectures = use a comma-separated list > + - `-t `: To run only tests related to certain= targets use a comma-separated list > + > +That's it to do a basic build. > + > +The remainder of this page contains more details about the `stuart_ci_= build` and `stuart_build` commands. > + > +--- > + > +## Examples > + > +
> + Example: I want to build MdeModulePkg to test a change I ma= de there. > +
> +

> + The important parameter here is the -p parameter whic= h specifies that MdeModulePkg > + should be built. > +

> +

> + The example below uses: > +

    > +
  • > + The TOOL_CHAIN_TAG parameter to specify the build= should use VS2019 > + (Visual Studio 2019). > +
    • > +
  • > + The -a parameter is used to specify that the IA32 and X64 architectures > + should be built. > +
    • > +
> +

> + > + stuart_ci_build -c .pytool/CISettings.py -p MdeModulePkg -a IA3= 2,X64 TOOL_CHAIN_TAG=3DVS2019 > +
> +
> + > +
> + Example: I want to build OvmfPkg to test a change I made th= ere. > +
> +

> + OvmfPkg is considered a "platform firmware" for the > + QEMU open-sour= ce emulator. > +

> +
    > +
  • > + Therefore, it provides a platform build file (see What is PlatformBuild.py?) > + > +
    • > +
  • > + Because we are building a platform build file, the build command= will be stuart_build instead of > + stuart_ci_build to compile the code > +
    • > +
> + > + stuart_build -c PlatformBuild.py -p OvmfPkg -a IA32,X64 TOOL_CH= AIN_TAG=3DVS2019 > + > +

> + If you want to run CI checks such as CI plugins, you can use stuart_ci_build with the CI build file. > +

> + > + stuart_ci_build -c .pytool/CISettings.py -p OvmfPkg -a IA32,X64= TOOL_CHAIN_TAG=3DVS2019 > +
> +
> + > +
> + Example: I want to build OvmfPkg and automatically run with= my firmware after build. > +
> +

> + OvmfPkg is considered a "platform firmware" for the > + QEMU open-sour= ce emulator. > +

> + > + > + > +

> + To see what parameters are supported by this platform build file (= at the time this page was written), we can pass > + the --help argument to the stuart_build = command: > +

> + > + 
> +    =E2=9D=AF stuart_build -c PlatformBuild.py --help
> +    usage: stuart_build [-h] [--SKIPBUILD] [--SKIPPREBUILD] [--SKIPPOS=
TBUILD] [--FLASHONLY] [--FLASHROM]
> +                        [--UPDATECONF] [--CLEAN] [--CLEANONLY] [--OUTP=
UTCONFIG OUTPUTCONFIG] [-a BUILD_ARCH]
> +                        [--build-config BUILD_CONFIG] [--verbose]
> +
> +    options:
> +      -h, --help            show this help message and exit
> +      --SKIPBUILD, --skipbuild, --SkipBuild
> +                            Skip the build process
> +      --SKIPPREBUILD, --skipprebuild, --SkipPrebuild
> +                            Skip prebuild process
> +      --SKIPPOSTBUILD, --skippostbuild, --SkipPostBuild
> +                            Skip postbuild process
> +      --FLASHONLY, --flashonly, --FlashOnly
> +                            Flash rom after build.
> +      --FLASHROM, --flashrom, --FlashRom
> +                            Flash rom. Rom must be built previously.
> +      --UPDATECONF, --updateconf, --UpdateConf
> +                            Update Conf. Builders Conf files will be r=
eplaced with latest template files
> +      --CLEAN, --clean, --CLEAN
> +                            Clean. Remove all old build artifacts and =
intermediate files
> +      --CLEANONLY, --cleanonly, --CleanOnly
> +                            Clean Only. Do clean operation and don't b=
uild just exit.
> +      --OUTPUTCONFIG OUTPUTCONFIG, --outputconfig OUTPUTCONFIG, --Outp=
utConfig OUTPUTCONFIG
> +                            Provide shell variables in a file
> +      -a BUILD_ARCH, --arch BUILD_ARCH
> +                            Optional - CSV of architecture to build. I=
A32 will use IA32 for Pei & Dxe. X64 will use
> +                            X64 for both PEI and DXE. IA32,X64 will us=
e IA32 for PEI and X64 for DXE. default is
> +                            IA32,X64
> +      --build-config BUILD_CONFIG
> +                            Provide shell variables in a file
> +      --verbose, --VERBOSE, -v
> +                            verbose
> +
> +    positional arguments:
> +      =3D              - Set an env variable for the pre/p=
ost build process
> +      BLD_*_=3D        - Set a build flag for all build ty=
pes
> +                                  (key=3Dvalue will get passed to buil=
d process)
> +      BLD__=3D - Set a build flag for build type o=
f 
> +                                  (key=3Dvalue will get passed to buil=
d process for given build type)
> +
> +

> + The --flashonly and --flashrom commands = are especially useful with OvmfPkg. They > + automatically load QEMU with the newly built firmware. > +

> +

> + The example below uses: > +

    > +
  • > + The TOOL_CHAIN_TAG parameter to specify that the = build should use GCC5 > + to build with GCC. > +
    • > +
  • > + The -a parameter is used to specify the IA3= 2 and X64 architectures should be > + built. > +
    • > +
  • > + The --flashrom parameter is used to load the firm= ware in QEMU and boot QEMU after the firmware build > + is completed. > +
    • > +
> +

> + > + stuart_build -c PlatformBuild.py -p OvmfPkg -a IA32,X64 TOOL_CH= AIN_TAG=3DGCC5 --flashrom > +
> +
> + > +
> + Example: I want to= build BaseTools. > +
> + BaseTools has its own build scri= pt that leverages > + edk2-pytools to build the Bas= eTools applications. > +
> +
> +
> + Linux (Ubuntu) Pre-Steps > + sudo apt update > +
> + sudo apt install build-essential uuid-dev > +
> +

> + The file BaseTools/Edk2ToolsBuild.p= y > + can be called as a standalone Python script. You just need to pass= the tool chain tag you would like to build with. > +

> +

> + Example: > + python BaseTools/Edk2ToolsBuild.py -t GCC5 > +

> +
> +
> + > +
> + Example: I just want to check if my changes will pass all t= he non-compiler checks in CI. > +
> +

> + The NO-TARGET build target specifies that the actual = firmware source code should not be built for any > + particular target and, instead, the other parts of the CI process = will be active such as the non-compiler checks > + (plugins). > +

> +

> + In the following example, the CI plugins will be run against all p= ackages supported by the > + CISettings.py file. > +

> + stuart_ci_build -c .pytool/CISettings.py -t NO-TARGET > +

> + The CI checks could be run against a single package (or a selectio= n of packages) by passing the package names to > + with the -p parameter. > +

> + stuart_ci_build -c .pytool/CISettings.py -p MdePkg,UefiCpuPkg -= t NO-TARGET > +
> +
> + > +
> + > + Example: I want to fix all the spelling errors in my package. How = do I just run the spell check plugin? > + > +
> +

> + Plugins are automatically discovered in the workspace by stuart. > +

> +

> + The easiest way to have stuart only one run plugin if many others = are present (as is the case in edk2) is to simply > + delete the other plugin directories so they are not discovered. Yo= u can then test with the remaining plugins and > + then use git to restore the deleted plugin directories back when d= one testing. > +

> +

> + For example, to only test with the SpellCheck plugin,= delete every other plugin folder from > + .pytool/Plugin in your > + workspace. > +

> +

> + Run the command to only perform CI checks: > +
> + stuart_ci_build -c .pytool/CISettings.py -t NO-TARGET > +

> +

> + When done, restore the other plugin directories: > +
> + git restore .pytool/Plugin/** > +

> +
> +
> + > +## Common Questions > + > +
> + What is CI? > +
> +

> + Continuous Integration > +

> +

> + Continuous integration is used in edk2 to test new contributions b= efore they are merged to the edk2 main branch. > + Stuart is used within the edk2 CI process to pull build dependenci= es and build the code. > +

> +

> + You can use stuart to perform the same CI checks locally that are = done on the server (see the examples section). > +

> +

> + Also see EDK II Continuou= s Integration. > +

> +
> +
> + > +
> + What are BaseTools? > +
> +

A collection of build related tools for edk2.

> +

> + Examples: > + > +

    > +
  • AutoGen
    • > +
  • Build
    • > +
  • GenSec
    • > +
  • GenFV
    • > +
  • GenFW
    • > +
  • GenRds
    • > +
> +

> +

> + Each tool has a user manual located in Ba= seTools/UserManuals. > +

> +

> + A more complete list of BaseTools is located in the EDK II Tools List. > +

> +
> +
> + > +
> + What are edk2-pytools? > +
> +

A collection of Python code for working with edk2.

> +
    > +
  • > + edk2-pytool-library - Python > + library code that seeks to provide an easy way to organize and s= hare edk2 related functionality to facilitate > + reuse across environments, tools, and scripts. > +
    • > +
  • > + edk2-pytool-extensions - A > + Python project that consists of command line and other tools and= extensions for building and maintaining an edk2 > + based UEFI firmware code tree. > +
    • > +
> +
> +
> + > +
> + What is CISettings.py? > +
> +

> + CISettings.py is a common name given to a configurati= on file used with Stuart for CI. It is often > + stored in a folder named .pytools in the root of a re= pository. So you'll likely encounter commands > + like the following be used with the file: > +

> + > +
    > +
  • > + > + stuart_ci_setup -c .pytool/CISettings.py TOOL_CHAIN_TAG=3DPUT_TA= G_VALUE_HERE > + > +
    • > +
  • > + > + stuart_update -c .pytool/CISettings.py TOOL_CHAIN_TAG=3DPUT_TAG_= VALUE_HERE > + > +
    • > +
  • > + > + stuart_ci_build -c .pytool/CISettings.py TOOL_CHAIN_TAG=3DPUT_TA= G_VALUE_HERE > + > +
    • > +
> +
> +
> + > +
> + What is PlatformBuild.py? > +
> +

> + PlatformBuild.py is a common name given to a configur= ation file used with Stuart for platform build. > + It is often stored in the root directory of the package it builds. > +

> +

> + For example: > +

> +
    > +
  • > + > + stuart_setup -c SomePkg/PlatformBuild.py TOOL_CHAIN_TAG=3DPUT_TA= G_VALUE_HERE > + > +
    • > +
  • > + > + stuart_update -c SomePkg/PlatformBuild.py TOOL_CHAIN_TAG=3DPUT_T= AG_VALUE_HERE > + > +
    • > +
  • > + > + stuart_build -c SomePkg/PlatformBuild.py TOOL_CHAIN_TAG=3DPUT_TA= G_VALUE_HERE > + > +
    • > +
> +

> + Like Stuart CI has "CI plugins", the build process has "build plug= ins". These can hook into the build in > + "pre-build" or "post-build". > +

> +
> + Note: Build plugins will also run during CI if a CompilerPlugin is= present that builds the code. > +
> +
> +
> + > +
> + > + What is the difference between stuart_ci_build and stuart_build? > + > +
> +
    > +
  • > + stuart_ci_build - Runs CI plugins. By default, ofte= n runs CI on several packages at once. This > + includes all of the checks needed to consider the code ready for= integration to the mainline. > +
    • > +
  • > + stuart_build - Does not run CI plugins. Builds one = platform. Platforms often expose > + platform-specific parameters as defined in their PlatformB= uild.py file. > +
    • > +
> +
> +
> + > +
> + What does stuart_= ci_build do exactly? > +
> +

> + The Stuart CI process is composed of "CI plugins" that get discove= red in the code tree at CI time and hook into > + the CI process. Some examples of CI plugins are a host-based unit = test compile and execution, spell checking the > + code, performing markdown lint on the code, etc. Firmware (C code)= compilation is performed during CI by a compiler > + CI plugin. > +

> +

> + Each plugin reports back a pass/fail status. If any plugin fails, = CI fails. However, plugins usually provide some > + level of customization in a "CI package configuration file". If th= is file is present, it is in the root of the > + package with the naming convention PkgName.ci.yaml. F= or example, > + MdePkg.ci.yaml is > + the CI package configuration file for MdePkg. Sometim= es, CI plugins will allow the plugin to be set to > + run in "audit mode" so the plugin will run and report results but = not fail CI if errors are found. As an example, > + some packages in edk2 currently use this file to run the spell che= cker CI plugin in audit mode. > +

> +

> + The two main places to look for CI settings are: > +

    > +
  • The CISettings.py file - Usually has repo-wide CI settings > +
  • The CI package configuration file - Has package-specific CI = settings for a given package
    • > +
> +

> +
> +
> + > +
> + > + How do I get more detailed information if an error happens? > + > +
> +

> + You can pass the -v argument to Stuart commands to ge= t more detailed output. > +

> +

> + Also, look in your /Build directory. > +

> +

> + Each Stuart command produces a separate file. Open the file corres= ponding to the command you're using that has the > + failure. > +

> +
    > +
  • stuart_ci_setup - CISETUP.txt
    • > +
  • stuart_setup - SETUPLOG.txt
    • > +
  • stuart_update - UPDATE_LOG.txt
    • > +
  • stuart_ci_build - CI_BUILDLOG.txt > +
  • stuart_build - BUILDLOG_PACKAGENAME.txt
    • > +
> +
> +
> + > +
> + What are "plugins"? > +
> +

> + The different types of plugins supported by Stuart and details abo= ut each type are available in the > + edk2-pyt= ool-extensions Plugin Manager > + page. > +

> +
> +
> + > +
> + How do I = get lower-level technical details? > +
> +

> + Start in the > + edk2-pytool-extensions Use= r Documentation. > +

> +
> +