mirror of https://github.com/acidanthera/audk.git
.pytool: Add CISettings.py and Readme.md
https://bugzilla.tianocore.org/show_bug.cgi?id=2315 Add main python script for EDK II Continuous Integration (CI) builds along with a Readme.md that provides a summary of the packages, platforms, and checks performs during a CI build. Cc: Sean Brogan <sean.brogan@microsoft.com> Cc: Bret Barkelew <Bret.Barkelew@microsoft.com> Cc: Liming Gao <liming.gao@intel.com> Signed-off-by: Michael D Kinney <michael.d.kinney@intel.com> Reviewed-by: Liming Gao <liming.gao@intel.com>
This commit is contained in:
Sean Brogan
Michael D Kinney
parent
3137900fc9
commit
4eb2baba93
|
|
@ -0,0 +1,173 @@
|
||||||
|
# @file
|
||||||
|
#
|
||||||
|
# Copyright (c) Microsoft Corporation.
|
||||||
|
# SPDX-License-Identifier: BSD-2-Clause-Patent
|
||||||
|
##
|
||||||
|
import os
|
||||||
|
import logging
|
||||||
|
from edk2toolext.environment import shell_environment
|
||||||
|
from edk2toolext.invocables.edk2_ci_build import CiBuildSettingsManager
|
||||||
|
from edk2toolext.invocables.edk2_setup import SetupSettingsManager, RequiredSubmodule
|
||||||
|
from edk2toolext.invocables.edk2_update import UpdateSettingsManager
|
||||||
|
from edk2toolext.invocables.edk2_pr_eval import PrEvalSettingsManager
|
||||||
|
from edk2toollib.utility_functions import GetHostInfo
|
||||||
|
|
||||||
|
|
||||||
|
class Settings(CiBuildSettingsManager, UpdateSettingsManager, SetupSettingsManager, PrEvalSettingsManager):
|
||||||
|
|
||||||
|
def __init__(self):
|
||||||
|
self.ActualPackages = []
|
||||||
|
self.ActualTargets = []
|
||||||
|
self.ActualArchitectures = []
|
||||||
|
self.ActualToolChainTag = ""
|
||||||
|
|
||||||
|
# ####################################################################################### #
|
||||||
|
# Extra CmdLine configuration #
|
||||||
|
# ####################################################################################### #
|
||||||
|
|
||||||
|
def AddCommandLineOptions(self, parserObj):
|
||||||
|
pass
|
||||||
|
|
||||||
|
def RetrieveCommandLineOptions(self, args):
|
||||||
|
pass
|
||||||
|
|
||||||
|
# ####################################################################################### #
|
||||||
|
# Default Support for this Ci Build #
|
||||||
|
# ####################################################################################### #
|
||||||
|
|
||||||
|
def GetPackagesSupported(self):
|
||||||
|
''' return iterable of edk2 packages supported by this build.
|
||||||
|
These should be edk2 workspace relative paths '''
|
||||||
|
|
||||||
|
return ("MdePkg",
|
||||||
|
"MdeModulePkg",
|
||||||
|
"NetworkPkg",
|
||||||
|
"PcAtChipsetPkg",
|
||||||
|
"SecurityPkg",
|
||||||
|
"UefiCpuPkg",
|
||||||
|
"FmpDevicePkg",
|
||||||
|
"ShellPkg",
|
||||||
|
"FatPkg",
|
||||||
|
"CryptoPkg"
|
||||||
|
)
|
||||||
|
|
||||||
|
def GetArchitecturesSupported(self):
|
||||||
|
''' return iterable of edk2 architectures supported by this build '''
|
||||||
|
return ("IA32",
|
||||||
|
"X64",
|
||||||
|
"ARM",
|
||||||
|
"AARCH64")
|
||||||
|
|
||||||
|
def GetTargetsSupported(self):
|
||||||
|
''' return iterable of edk2 target tags supported by this build '''
|
||||||
|
return ("DEBUG", "RELEASE", "NO-TARGET", "NOOPT")
|
||||||
|
|
||||||
|
# ####################################################################################### #
|
||||||
|
# Verify and Save requested Ci Build Config #
|
||||||
|
# ####################################################################################### #
|
||||||
|
|
||||||
|
def SetPackages(self, list_of_requested_packages):
|
||||||
|
''' Confirm the requested package list is valid and configure SettingsManager
|
||||||
|
to build the requested packages.
|
||||||
|
|
||||||
|
Raise UnsupportedException if a requested_package is not supported
|
||||||
|
'''
|
||||||
|
unsupported = set(list_of_requested_packages) - \
|
||||||
|
set(self.GetPackagesSupported())
|
||||||
|
if(len(unsupported) > 0):
|
||||||
|
logging.critical(
|
||||||
|
"Unsupported Package Requested: " + " ".join(unsupported))
|
||||||
|
raise Exception("Unsupported Package Requested: " +
|
||||||
|
" ".join(unsupported))
|
||||||
|
self.ActualPackages = list_of_requested_packages
|
||||||
|
|
||||||
|
def SetArchitectures(self, list_of_requested_architectures):
|
||||||
|
''' Confirm the requests architecture list is valid and configure SettingsManager
|
||||||
|
to run only the requested architectures.
|
||||||
|
|
||||||
|
Raise Exception if a list_of_requested_architectures is not supported
|
||||||
|
'''
|
||||||
|
unsupported = set(list_of_requested_architectures) - \
|
||||||
|
set(self.GetArchitecturesSupported())
|
||||||
|
if(len(unsupported) > 0):
|
||||||
|
logging.critical(
|
||||||
|
"Unsupported Architecture Requested: " + " ".join(unsupported))
|
||||||
|
raise Exception(
|
||||||
|
"Unsupported Architecture Requested: " + " ".join(unsupported))
|
||||||
|
self.ActualArchitectures = list_of_requested_architectures
|
||||||
|
|
||||||
|
def SetTargets(self, list_of_requested_target):
|
||||||
|
''' Confirm the request target list is valid and configure SettingsManager
|
||||||
|
to run only the requested targets.
|
||||||
|
|
||||||
|
Raise UnsupportedException if a requested_target is not supported
|
||||||
|
'''
|
||||||
|
unsupported = set(list_of_requested_target) - \
|
||||||
|
set(self.GetTargetsSupported())
|
||||||
|
if(len(unsupported) > 0):
|
||||||
|
logging.critical(
|
||||||
|
"Unsupported Targets Requested: " + " ".join(unsupported))
|
||||||
|
raise Exception("Unsupported Targets Requested: " +
|
||||||
|
" ".join(unsupported))
|
||||||
|
self.ActualTargets = list_of_requested_target
|
||||||
|
|
||||||
|
# ####################################################################################### #
|
||||||
|
# Actual Configuration for Ci Build #
|
||||||
|
# ####################################################################################### #
|
||||||
|
|
||||||
|
def GetActiveScopes(self):
|
||||||
|
''' return tuple containing scopes that should be active for this process '''
|
||||||
|
scopes = ("cibuild","edk2-build")
|
||||||
|
|
||||||
|
self.ActualToolChainTag = shell_environment.GetBuildVars().GetValue("TOOL_CHAIN_TAG", "")
|
||||||
|
|
||||||
|
if GetHostInfo().os.upper() == "LINUX" and self.ActualToolChainTag.upper().startswith("GCC"):
|
||||||
|
if "AARCH64" in self.ActualArchitectures:
|
||||||
|
scopes += ("gcc_aarch64_linux",)
|
||||||
|
if "ARM" in self.ActualArchitectures:
|
||||||
|
scopes += ("gcc_arm_linux",)
|
||||||
|
|
||||||
|
return scopes
|
||||||
|
|
||||||
|
def GetRequiredSubmodules(self):
|
||||||
|
''' return iterable containing RequiredSubmodule objects.
|
||||||
|
If no RequiredSubmodules return an empty iterable
|
||||||
|
'''
|
||||||
|
rs=[]
|
||||||
|
rs.append(RequiredSubmodule(
|
||||||
|
"ArmPkg/Library/ArmSoftFloatLib/berkeley-softfloat-3", False))
|
||||||
|
rs.append(RequiredSubmodule(
|
||||||
|
"CryptoPkg/Library/OpensslLib/openssl", False))
|
||||||
|
return rs
|
||||||
|
|
||||||
|
def GetName(self):
|
||||||
|
return "Edk2"
|
||||||
|
|
||||||
|
def GetDependencies(self):
|
||||||
|
return []
|
||||||
|
|
||||||
|
def GetPackagesPath(self):
|
||||||
|
return ()
|
||||||
|
|
||||||
|
def GetWorkspaceRoot(self):
|
||||||
|
''' get WorkspacePath '''
|
||||||
|
return os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
|
||||||
|
|
||||||
|
def FilterPackagesToTest(self, changedFilesList: list, potentialPackagesList: list) -> list:
|
||||||
|
''' Filter potential packages to test based on changed files. '''
|
||||||
|
build_these_packages=[]
|
||||||
|
possible_packages=potentialPackagesList.copy()
|
||||||
|
for f in changedFilesList:
|
||||||
|
nodes=f.split("/") # split each part of path for comparison later
|
||||||
|
|
||||||
|
# python file change in .pytool folder causes building all
|
||||||
|
if f.endswith(".py") and ".pytool" in nodes:
|
||||||
|
build_these_packages = possible_packages
|
||||||
|
break
|
||||||
|
|
||||||
|
# BaseTools files that might change the build
|
||||||
|
if "BaseTools" in nodes:
|
||||||
|
if os.path.splitext(f) not in [".txt", ".md"]:
|
||||||
|
build_these_packages = possible_packages
|
||||||
|
break
|
||||||
|
return build_these_packages
|
||||||
|
|
@ -0,0 +1,223 @@
|
||||||
|
# Edk2 Continuous Integration
|
||||||
|
|
||||||
|
## Basic Status
|
||||||
|
|
||||||
|
| Package | Windows VS2019 (IA32/X64)| Ubuntu GCC (IA32/X64/ARM/AARCH64) | Known Issues |
|
||||||
|
| :---- | :----- | :---- | :--- |
|
||||||
|
| ArmPkg |
|
||||||
|
| ArmPlatformPkg |
|
||||||
|
| ArmVirtPkg |
|
||||||
|
| CryptoPkg | :heavy_check_mark: | :heavy_check_mark: | Spell checking in audit mode
|
||||||
|
| DynamicTablesPkg |
|
||||||
|
| EmbeddedPkg |
|
||||||
|
| EmulatorPkg |
|
||||||
|
| FatPkg | :heavy_check_mark: | :heavy_check_mark: |
|
||||||
|
| FmpDevicePkg | :heavy_check_mark: | :heavy_check_mark: |
|
||||||
|
| IntelFsp2Pkg |
|
||||||
|
| IntelFsp2WrapperPkg |
|
||||||
|
| MdeModulePkg | :heavy_check_mark: | :heavy_check_mark: | DxeIpl dependency on ArmPkg, Depends on StandaloneMmPkg, Spell checking in audit mode
|
||||||
|
| MdePkg | :heavy_check_mark: | :heavy_check_mark: | Spell checking in audit mode
|
||||||
|
| NetworkPkg | :heavy_check_mark: | :heavy_check_mark: | Spell checking in audit mode
|
||||||
|
| OvmfPkg |
|
||||||
|
| PcAtChipsetPkg | :heavy_check_mark: | :heavy_check_mark: |
|
||||||
|
| SecurityPkg | :heavy_check_mark: | :heavy_check_mark: | Spell checking in audit mode
|
||||||
|
| ShellPkg | :heavy_check_mark: | :heavy_check_mark: | Spell checking in audit mode, 3 modules are not being built by DSC
|
||||||
|
| SignedCapsulePkg |
|
||||||
|
| SourceLevelDebugPkg |
|
||||||
|
| StandaloneMmPkg |
|
||||||
|
| UefiCpuPkg | :heavy_check_mark: | :heavy_check_mark: | Spell checking in audit mode, 2 binary modules not being built by DSC
|
||||||
|
| UefiPayloadPkg |
|
||||||
|
|
||||||
|
For more detailed status look at the test results of the latest CI run on the
|
||||||
|
repo readme.
|
||||||
|
|
||||||
|
## Background
|
||||||
|
|
||||||
|
This Continuous integration and testing infrastructure leverages the TianoCore EDKII Tools PIP modules:
|
||||||
|
[library](https://pypi.org/project/edk2-pytool-library/) and
|
||||||
|
[extensions](https://pypi.org/project/edk2-pytool-extensions/) (with repos
|
||||||
|
located [here](https://github.com/tianocore/edk2-pytool-library) and
|
||||||
|
[here](https://github.com/tianocore/edk2-pytool-extensions)).
|
||||||
|
|
||||||
|
The primary execution flows can be found in the
|
||||||
|
`.azurepipelines/Windows-VS2019.yml` and `.azurepipelines/Ubuntu-GCC5.yml`
|
||||||
|
files. These YAML files are consumed by the Azure Dev Ops Build Pipeline and
|
||||||
|
dictate what server resources should be used, how they should be configured, and
|
||||||
|
what processes should be run on them. An overview of this schema can be found
|
||||||
|
[here](https://docs.microsoft.com/en-us/azure/devops/pipelines/yaml-schema?view=azure-devops&tabs=schema).
|
||||||
|
|
||||||
|
Inspection of these files reveals the EDKII Tools commands that make up the
|
||||||
|
primary processes for the CI build: 'stuart_setup', 'stuart_update', and
|
||||||
|
'stuart_ci_build'. These commands come from the EDKII Tools PIP modules and are
|
||||||
|
configured as described below. More documentation on the tools can be
|
||||||
|
found [here](https://github.com/tianocore/edk2-pytool-extensions/blob/master/docs/using.md)
|
||||||
|
and [here](https://github.com/tianocore/edk2-pytool-extensions/blob/master/docs/features/feature_invocables.md).
|
||||||
|
|
||||||
|
## Configuration
|
||||||
|
|
||||||
|
Configuration of the CI process consists of (in order of precedence):
|
||||||
|
|
||||||
|
* command-line arguments passed in via the Pipeline YAML
|
||||||
|
* a per-package configuration file (e.g. `<package-name>.ci.yaml`) that is
|
||||||
|
detected by the CI system in EDKII Tools.
|
||||||
|
* a global configuration Python module (e.g. `CISetting.py`) passed in via the
|
||||||
|
command-line
|
||||||
|
|
||||||
|
The global configuration file is described in
|
||||||
|
[this readme](https://github.com/tianocore/edk2-pytool-extensions/blob/master/docs/usability/using_settings_manager.md)
|
||||||
|
from the EDKII Tools documentation. This configuration is written as a Python
|
||||||
|
module so that decisions can be made dynamically based on command line
|
||||||
|
parameters and codebase state.
|
||||||
|
|
||||||
|
The per-package configuration file can override most settings in the global
|
||||||
|
configuration file, but is not dynamic. This file can be used to skip or
|
||||||
|
customize tests that may be incompatible with a specific package. Each test generally requires
|
||||||
|
per package configuration which comes from this file.
|
||||||
|
|
||||||
|
## Running CI locally
|
||||||
|
|
||||||
|
The EDKII Tools environment (and by extension the ci) is designed to support
|
||||||
|
easily and consistantly running locally and in a cloud ci environment. To do
|
||||||
|
that a few steps should be followed. Details of EDKII Tools can be found in the
|
||||||
|
[docs folder here](https://github.com/tianocore/edk2-pytool-extensions/tree/master/docs)
|
||||||
|
|
||||||
|
### Prerequisets
|
||||||
|
|
||||||
|
1. A supported toolchain (others might work but this is what is tested and validated)
|
||||||
|
* Windows 10:
|
||||||
|
* VS 2017 or VS 2019
|
||||||
|
* Windows SDK (for rc)
|
||||||
|
* Windows WDK (for capsules)
|
||||||
|
* Ubuntu 16.04
|
||||||
|
* GCC5
|
||||||
|
* Easy to add more but this is the current state
|
||||||
|
2. Python 3.7.x or newer on path
|
||||||
|
3. git on path
|
||||||
|
4. Recommended to setup and activate a python virtual environment
|
||||||
|
5. Install the requirements `pip install --upgrade pip-requirements.txt`
|
||||||
|
|
||||||
|
### Running CI
|
||||||
|
|
||||||
|
1. clone your edk2 repo
|
||||||
|
2. Activate your python virtual environment in cmd window
|
||||||
|
3. Get code dependencies (done only when submodules change)
|
||||||
|
* `stuart_setup -c .pytool/CISettings.py TOOL_CHAIN_TAG=<your tag here>`
|
||||||
|
4. Update other dependencies (done more often)
|
||||||
|
* `stuart_update -c .pytool/CISettings.py TOOL_CHAIN_TAG=<your tag here>`
|
||||||
|
5. Run CI build (--help will give you options)
|
||||||
|
* `stuart_ci_build -c .pytool/CISettings.py TOOL_CHAIN_TAG=<your tag here>`
|
||||||
|
* -p <pkg1,pkg2,pkg3> : To build only certain packages use a CSV list
|
||||||
|
* -a <arch1,arch2,arch3>: To run only certain architectures use a CSV list
|
||||||
|
* -t <target1,target2>: To run only tests related to certain targets use a
|
||||||
|
CSV list
|
||||||
|
* By default all tests are opted in. Then given a package.ci.yaml file those
|
||||||
|
tests can be configured for a package. Finally setting the check to the
|
||||||
|
value `skip` will skip that plugin. Examples:
|
||||||
|
* `CompilerPlugin=skip` skip the build test
|
||||||
|
* `GuidCheck=skip` skip the Guid check
|
||||||
|
* `SpellCheck=skip` skip the spell checker
|
||||||
|
* etc
|
||||||
|
6. Detailed reports and logs per package are captured in the `Build` directory
|
||||||
|
|
||||||
|
## Current PyTool Test Capabilities
|
||||||
|
|
||||||
|
All CI tests are instances of EDKII Tools plugins. Documentation on the plugin
|
||||||
|
system can be found [here](https://github.com/tianocore/edk2-pytool-extensions/blob/master/docs/usability/using_plugin_manager.md)
|
||||||
|
and [here](https://github.com/tianocore/edk2-pytool-extensions/blob/master/docs/features/feature_plugin_manager.md).
|
||||||
|
Upon invocation, each plugin will be passed the path to the current package
|
||||||
|
under test and a dictionary containing its targeted configuration, as assembled
|
||||||
|
from the command line, per-package configuration, and global configuration.
|
||||||
|
|
||||||
|
Note: CI plugins are considered unique from build plugins and helper plugins,
|
||||||
|
even though some CI plugins may execute steps of a build.
|
||||||
|
|
||||||
|
In the example, these plugins live alongside the code under test (in the
|
||||||
|
`.pytool/Plugin` directory), but may be moved to the 'edk2-test' repo if that
|
||||||
|
location makes more sense for the community.
|
||||||
|
|
||||||
|
### Module Inclusion Test - DscCompleteCheck
|
||||||
|
|
||||||
|
This test scans all available modules (via INF files) and compares them to the
|
||||||
|
package-level DSC file for the package each module is contained within. The test
|
||||||
|
considers it an error if any module does not appear in the `Components` section
|
||||||
|
of at least one package-level DSC (indicating that it would not be built if the
|
||||||
|
package were built).
|
||||||
|
|
||||||
|
### Code Compilation Test - CompilerPlugin
|
||||||
|
|
||||||
|
Once the Module Inclusion Test has verified that all modules would be built if
|
||||||
|
all package-level DSCs were built, the Code Compilation Test simply runs through
|
||||||
|
and builds every package-level DSC on every toolchain and for every architecture
|
||||||
|
that is supported. Any module that fails to build is considered an error.
|
||||||
|
|
||||||
|
### GUID Uniqueness Test - GuidCheck
|
||||||
|
|
||||||
|
This test works on the collection of all packages rather than an individual
|
||||||
|
package. It looks at all FILE_GUIDs and GUIDs declared in DEC files and ensures
|
||||||
|
that they are unique for the codebase. This prevents, for example, accidental
|
||||||
|
duplication of GUIDs when using an existing INF as a template for a new module.
|
||||||
|
|
||||||
|
### Cross-Package Dependency Test - DependencyCheck
|
||||||
|
|
||||||
|
This test compares the list of all packages used in INFs files for a given
|
||||||
|
package against a list of "allowed dependencies" in plugin configuration for
|
||||||
|
that package. Any module that depends on a disallowed package will cause a test
|
||||||
|
failure.
|
||||||
|
|
||||||
|
### Library Declaration Test - LibraryClassCheck
|
||||||
|
|
||||||
|
This test scans at all library header files found in the `Library` folders in
|
||||||
|
all of the package's declared include directories and ensures that all files
|
||||||
|
have a matching LibraryClass declaration in the DEC file for the package. Any
|
||||||
|
missing declarations will cause a failure.
|
||||||
|
|
||||||
|
### Invalid Character Test - CharEncodingCheck
|
||||||
|
|
||||||
|
This test scans all files in a package to make sure that there are no invalid
|
||||||
|
Unicode characters that may cause build errors in some character
|
||||||
|
sets/localizations.
|
||||||
|
|
||||||
|
### Spell Checking - cspell
|
||||||
|
|
||||||
|
This test runs a spell checker on all files within the package. This is done
|
||||||
|
using the NodeJs cspell tool. For details check `.pytool/Plugin/SpellCheck`.
|
||||||
|
For this plugin to run during ci you must install nodejs and cspell and have
|
||||||
|
both available to the command line when running your CI.
|
||||||
|
|
||||||
|
Install
|
||||||
|
|
||||||
|
* Install nodejs from https://nodejs.org/en/
|
||||||
|
* Install cspell
|
||||||
|
1. Open cmd prompt with access to node and npm
|
||||||
|
2. Run `npm install -g cspell`
|
||||||
|
|
||||||
|
More cspell info: https://github.com/streetsidesoftware/cspell
|
||||||
|
|
||||||
|
## PyTool Scopes
|
||||||
|
|
||||||
|
Scopes are how the PyTool ext_dep, path_env, and plugins are activated. Meaning
|
||||||
|
that if an invocable process has a scope active then those ext_dep and path_env
|
||||||
|
will be active. To allow easy integration of PyTools capabilities there are a
|
||||||
|
few standard scopes.
|
||||||
|
|
||||||
|
| Scope | Invocable | Description |
|
||||||
|
| :---- | :----- | :---- |
|
||||||
|
| global | edk2_invocable++ - should be base_abstract_invocable | Running an invocables |
|
||||||
|
| global-win | edk2_invocable++ | Running on Microsoft Windows |
|
||||||
|
| global-nix | edk2_invocable++ | Running on Linux based OS |
|
||||||
|
| edk2-build | | This indicates that an invocable is building EDK2 based UEFI code |
|
||||||
|
| cibuild | set in .pytool/CISettings.py | Suggested target for edk2 continuous integration builds. Tools used for CiBuilds can use this scope. Example: asl compiler |
|
||||||
|
|
||||||
|
## Future investments
|
||||||
|
|
||||||
|
* PatchCheck tests as plugins
|
||||||
|
* MacOS/xcode support
|
||||||
|
* Clang/LLVM support
|
||||||
|
* Visual Studio AARCH64 and ARM support
|
||||||
|
* BaseTools C tools CI/PR and binary release process
|
||||||
|
* BaseTools Python tools CI/PR process
|
||||||
|
* Host based unit testing
|
||||||
|
* Extensible private/closed source platform reporting
|
||||||
|
* Platform builds, validation
|
||||||
|
* UEFI SCTs
|
||||||
|
* Other automation
|
||||||
Loading…
Reference in New Issue