]>
Commit | Line | Data |
---|---|---|
4eb2baba SB |
1 | # Edk2 Continuous Integration\r |
2 | \r | |
3 | ## Basic Status\r | |
4 | \r | |
5 | | Package | Windows VS2019 (IA32/X64)| Ubuntu GCC (IA32/X64/ARM/AARCH64) | Known Issues |\r | |
6 | | :---- | :----- | :---- | :--- |\r | |
7 | | ArmPkg |\r | |
8 | | ArmPlatformPkg |\r | |
9 | | ArmVirtPkg |\r | |
10 | | CryptoPkg | :heavy_check_mark: | :heavy_check_mark: | Spell checking in audit mode\r | |
11 | | DynamicTablesPkg |\r | |
12 | | EmbeddedPkg |\r | |
13 | | EmulatorPkg |\r | |
14 | | FatPkg | :heavy_check_mark: | :heavy_check_mark: |\r | |
15 | | FmpDevicePkg | :heavy_check_mark: | :heavy_check_mark: |\r | |
16 | | IntelFsp2Pkg |\r | |
17 | | IntelFsp2WrapperPkg |\r | |
18 | | MdeModulePkg | :heavy_check_mark: | :heavy_check_mark: | DxeIpl dependency on ArmPkg, Depends on StandaloneMmPkg, Spell checking in audit mode\r | |
19 | | MdePkg | :heavy_check_mark: | :heavy_check_mark: | Spell checking in audit mode\r | |
20 | | NetworkPkg | :heavy_check_mark: | :heavy_check_mark: | Spell checking in audit mode\r | |
21 | | OvmfPkg |\r | |
22 | | PcAtChipsetPkg | :heavy_check_mark: | :heavy_check_mark: |\r | |
23 | | SecurityPkg | :heavy_check_mark: | :heavy_check_mark: | Spell checking in audit mode\r | |
24 | | ShellPkg | :heavy_check_mark: | :heavy_check_mark: | Spell checking in audit mode, 3 modules are not being built by DSC\r | |
25 | | SignedCapsulePkg |\r | |
26 | | SourceLevelDebugPkg |\r | |
27 | | StandaloneMmPkg |\r | |
28 | | UefiCpuPkg | :heavy_check_mark: | :heavy_check_mark: | Spell checking in audit mode, 2 binary modules not being built by DSC\r | |
29 | | UefiPayloadPkg |\r | |
30 | \r | |
31 | For more detailed status look at the test results of the latest CI run on the\r | |
32 | repo readme.\r | |
33 | \r | |
34 | ## Background\r | |
35 | \r | |
36 | This Continuous integration and testing infrastructure leverages the TianoCore EDKII Tools PIP modules:\r | |
37 | [library](https://pypi.org/project/edk2-pytool-library/) and\r | |
38 | [extensions](https://pypi.org/project/edk2-pytool-extensions/) (with repos\r | |
39 | located [here](https://github.com/tianocore/edk2-pytool-library) and\r | |
40 | [here](https://github.com/tianocore/edk2-pytool-extensions)).\r | |
41 | \r | |
42 | The primary execution flows can be found in the\r | |
43 | `.azurepipelines/Windows-VS2019.yml` and `.azurepipelines/Ubuntu-GCC5.yml`\r | |
44 | files. These YAML files are consumed by the Azure Dev Ops Build Pipeline and\r | |
45 | dictate what server resources should be used, how they should be configured, and\r | |
46 | what processes should be run on them. An overview of this schema can be found\r | |
47 | [here](https://docs.microsoft.com/en-us/azure/devops/pipelines/yaml-schema?view=azure-devops&tabs=schema).\r | |
48 | \r | |
49 | Inspection of these files reveals the EDKII Tools commands that make up the\r | |
50 | primary processes for the CI build: 'stuart_setup', 'stuart_update', and\r | |
51 | 'stuart_ci_build'. These commands come from the EDKII Tools PIP modules and are\r | |
52 | configured as described below. More documentation on the tools can be\r | |
53 | found [here](https://github.com/tianocore/edk2-pytool-extensions/blob/master/docs/using.md)\r | |
54 | and [here](https://github.com/tianocore/edk2-pytool-extensions/blob/master/docs/features/feature_invocables.md).\r | |
55 | \r | |
56 | ## Configuration\r | |
57 | \r | |
58 | Configuration of the CI process consists of (in order of precedence):\r | |
59 | \r | |
60 | * command-line arguments passed in via the Pipeline YAML\r | |
61 | * a per-package configuration file (e.g. `<package-name>.ci.yaml`) that is\r | |
62 | detected by the CI system in EDKII Tools.\r | |
63 | * a global configuration Python module (e.g. `CISetting.py`) passed in via the\r | |
64 | command-line\r | |
65 | \r | |
66 | The global configuration file is described in\r | |
67 | [this readme](https://github.com/tianocore/edk2-pytool-extensions/blob/master/docs/usability/using_settings_manager.md)\r | |
68 | from the EDKII Tools documentation. This configuration is written as a Python\r | |
69 | module so that decisions can be made dynamically based on command line\r | |
70 | parameters and codebase state.\r | |
71 | \r | |
72 | The per-package configuration file can override most settings in the global\r | |
73 | configuration file, but is not dynamic. This file can be used to skip or\r | |
74 | customize tests that may be incompatible with a specific package. Each test generally requires\r | |
75 | per package configuration which comes from this file.\r | |
76 | \r | |
77 | ## Running CI locally\r | |
78 | \r | |
79 | The EDKII Tools environment (and by extension the ci) is designed to support\r | |
80 | easily and consistantly running locally and in a cloud ci environment. To do\r | |
81 | that a few steps should be followed. Details of EDKII Tools can be found in the\r | |
82 | [docs folder here](https://github.com/tianocore/edk2-pytool-extensions/tree/master/docs)\r | |
83 | \r | |
84 | ### Prerequisets\r | |
85 | \r | |
86 | 1. A supported toolchain (others might work but this is what is tested and validated)\r | |
87 | * Windows 10:\r | |
88 | * VS 2017 or VS 2019\r | |
89 | * Windows SDK (for rc)\r | |
90 | * Windows WDK (for capsules)\r | |
91 | * Ubuntu 16.04\r | |
92 | * GCC5\r | |
93 | * Easy to add more but this is the current state\r | |
94 | 2. Python 3.7.x or newer on path\r | |
95 | 3. git on path\r | |
96 | 4. Recommended to setup and activate a python virtual environment\r | |
97 | 5. Install the requirements `pip install --upgrade pip-requirements.txt`\r | |
98 | \r | |
99 | ### Running CI\r | |
100 | \r | |
101 | 1. clone your edk2 repo\r | |
102 | 2. Activate your python virtual environment in cmd window\r | |
103 | 3. Get code dependencies (done only when submodules change)\r | |
104 | * `stuart_setup -c .pytool/CISettings.py TOOL_CHAIN_TAG=<your tag here>`\r | |
105 | 4. Update other dependencies (done more often)\r | |
106 | * `stuart_update -c .pytool/CISettings.py TOOL_CHAIN_TAG=<your tag here>`\r | |
107 | 5. Run CI build (--help will give you options)\r | |
108 | * `stuart_ci_build -c .pytool/CISettings.py TOOL_CHAIN_TAG=<your tag here>`\r | |
109 | * -p <pkg1,pkg2,pkg3> : To build only certain packages use a CSV list\r | |
110 | * -a <arch1,arch2,arch3>: To run only certain architectures use a CSV list\r | |
111 | * -t <target1,target2>: To run only tests related to certain targets use a\r | |
112 | CSV list\r | |
113 | * By default all tests are opted in. Then given a package.ci.yaml file those\r | |
114 | tests can be configured for a package. Finally setting the check to the\r | |
115 | value `skip` will skip that plugin. Examples:\r | |
116 | * `CompilerPlugin=skip` skip the build test\r | |
117 | * `GuidCheck=skip` skip the Guid check\r | |
118 | * `SpellCheck=skip` skip the spell checker\r | |
119 | * etc\r | |
120 | 6. Detailed reports and logs per package are captured in the `Build` directory\r | |
121 | \r | |
122 | ## Current PyTool Test Capabilities\r | |
123 | \r | |
124 | All CI tests are instances of EDKII Tools plugins. Documentation on the plugin\r | |
125 | system can be found [here](https://github.com/tianocore/edk2-pytool-extensions/blob/master/docs/usability/using_plugin_manager.md)\r | |
126 | and [here](https://github.com/tianocore/edk2-pytool-extensions/blob/master/docs/features/feature_plugin_manager.md).\r | |
127 | Upon invocation, each plugin will be passed the path to the current package\r | |
128 | under test and a dictionary containing its targeted configuration, as assembled\r | |
129 | from the command line, per-package configuration, and global configuration.\r | |
130 | \r | |
131 | Note: CI plugins are considered unique from build plugins and helper plugins,\r | |
132 | even though some CI plugins may execute steps of a build.\r | |
133 | \r | |
134 | In the example, these plugins live alongside the code under test (in the\r | |
135 | `.pytool/Plugin` directory), but may be moved to the 'edk2-test' repo if that\r | |
136 | location makes more sense for the community.\r | |
137 | \r | |
138 | ### Module Inclusion Test - DscCompleteCheck\r | |
139 | \r | |
140 | This test scans all available modules (via INF files) and compares them to the\r | |
141 | package-level DSC file for the package each module is contained within. The test\r | |
142 | considers it an error if any module does not appear in the `Components` section\r | |
143 | of at least one package-level DSC (indicating that it would not be built if the\r | |
144 | package were built).\r | |
145 | \r | |
146 | ### Code Compilation Test - CompilerPlugin\r | |
147 | \r | |
148 | Once the Module Inclusion Test has verified that all modules would be built if\r | |
149 | all package-level DSCs were built, the Code Compilation Test simply runs through\r | |
150 | and builds every package-level DSC on every toolchain and for every architecture\r | |
151 | that is supported. Any module that fails to build is considered an error.\r | |
152 | \r | |
153 | ### GUID Uniqueness Test - GuidCheck\r | |
154 | \r | |
155 | This test works on the collection of all packages rather than an individual\r | |
156 | package. It looks at all FILE_GUIDs and GUIDs declared in DEC files and ensures\r | |
157 | that they are unique for the codebase. This prevents, for example, accidental\r | |
158 | duplication of GUIDs when using an existing INF as a template for a new module.\r | |
159 | \r | |
160 | ### Cross-Package Dependency Test - DependencyCheck\r | |
161 | \r | |
162 | This test compares the list of all packages used in INFs files for a given\r | |
163 | package against a list of "allowed dependencies" in plugin configuration for\r | |
164 | that package. Any module that depends on a disallowed package will cause a test\r | |
165 | failure.\r | |
166 | \r | |
167 | ### Library Declaration Test - LibraryClassCheck\r | |
168 | \r | |
169 | This test scans at all library header files found in the `Library` folders in\r | |
170 | all of the package's declared include directories and ensures that all files\r | |
171 | have a matching LibraryClass declaration in the DEC file for the package. Any\r | |
172 | missing declarations will cause a failure.\r | |
173 | \r | |
174 | ### Invalid Character Test - CharEncodingCheck\r | |
175 | \r | |
176 | This test scans all files in a package to make sure that there are no invalid\r | |
177 | Unicode characters that may cause build errors in some character\r | |
178 | sets/localizations.\r | |
179 | \r | |
180 | ### Spell Checking - cspell\r | |
181 | \r | |
182 | This test runs a spell checker on all files within the package. This is done\r | |
183 | using the NodeJs cspell tool. For details check `.pytool/Plugin/SpellCheck`.\r | |
184 | For this plugin to run during ci you must install nodejs and cspell and have\r | |
185 | both available to the command line when running your CI.\r | |
186 | \r | |
187 | Install\r | |
188 | \r | |
189 | * Install nodejs from https://nodejs.org/en/\r | |
190 | * Install cspell\r | |
191 | 1. Open cmd prompt with access to node and npm\r | |
192 | 2. Run `npm install -g cspell`\r | |
193 | \r | |
194 | More cspell info: https://github.com/streetsidesoftware/cspell\r | |
195 | \r | |
196 | ## PyTool Scopes\r | |
197 | \r | |
198 | Scopes are how the PyTool ext_dep, path_env, and plugins are activated. Meaning\r | |
199 | that if an invocable process has a scope active then those ext_dep and path_env\r | |
200 | will be active. To allow easy integration of PyTools capabilities there are a\r | |
201 | few standard scopes.\r | |
202 | \r | |
203 | | Scope | Invocable | Description |\r | |
204 | | :---- | :----- | :---- |\r | |
205 | | global | edk2_invocable++ - should be base_abstract_invocable | Running an invocables |\r | |
206 | | global-win | edk2_invocable++ | Running on Microsoft Windows |\r | |
207 | | global-nix | edk2_invocable++ | Running on Linux based OS |\r | |
208 | | edk2-build | | This indicates that an invocable is building EDK2 based UEFI code |\r | |
209 | | cibuild | set in .pytool/CISettings.py | Suggested target for edk2 continuous integration builds. Tools used for CiBuilds can use this scope. Example: asl compiler |\r | |
210 | \r | |
211 | ## Future investments\r | |
212 | \r | |
213 | * PatchCheck tests as plugins\r | |
214 | * MacOS/xcode support\r | |
215 | * Clang/LLVM support\r | |
216 | * Visual Studio AARCH64 and ARM support\r | |
217 | * BaseTools C tools CI/PR and binary release process\r | |
218 | * BaseTools Python tools CI/PR process\r | |
219 | * Host based unit testing\r | |
220 | * Extensible private/closed source platform reporting\r | |
221 | * Platform builds, validation\r | |
222 | * UEFI SCTs\r | |
223 | * Other automation\r |