This project builds the Project Mu shared crypto binaries. It consists of scripts, pipelines, and submodules to perform a binary release of EDK II [CryptoPkg](https://github.com/microsoft/mu_basecore/tree/HEAD/CryptoPkg) drivers to power the BaseCryptOnProtocol/Ppi infrastructure.
These releases will be tagged and tracked in this repo, but published to the Mu Nuget feed.
This repository is part of Project Mu. Please see Project Mu for details https://microsoft.github.io/mu
If you simply want to use shared crypto in your project, view the [shared crypto driver instructions](CryptoBinPkg/Driver/readme.md).
The remaining instructions are for those working directly in this repository to build new shared crypto releases.
Here is a brief description of the scripts in this repository and how they are used.
This script is not to be used directly, but is a configuration module to be consumed by the other scripts in this repo (or used directly as a Stuart settings module). If any submodules or scopes need to be changed, this is the place to do it.
Note that any changes to names might require additional changes in other scripts that look for those names when copying files around.
This script will run an EDK2 build of a single flavor and a single target of CryptBin. Example: TINY_SHA,DEBUG
or
STANDARD,RELEASE
. This is because a single EDK2 build run requires a single and flavor target and so each run
must be set up independently. This script is called multiple times by the MultiFlavorBuild.py
script.
Should have good support for -h
and print a useful help menu.
This script organizes the build for an entire release by coordinating multiple calls to SingleFlavorBuild.py
.
Multiple targets, flavors, and architectures can be passed into this script to be built in sequence. This is the
main entry point for the build from the pipeline and is the ideal entry point for any local builds.
Calling this script without any parameters default to all available targets, architectures, and flavors.
Should have good support for -h
and print a useful help menu.
This script will take in a directory of build artifacts and reorganize them into the Nuget package layout.
Should have good support for -h
and print a useful help menu.
Building locally for test consists of two primary pieces:
- Run the
MultiFlavorBuild.py
script to build the drivers, depexes, and other release collateral. - Run the
AssembleNugetPackage.py
script to organize the release collateral into the format for - the release package. Just point at the
Build
directory as the input directory.
- Run the
The steps are:
- Make sure that you've updated your pip requirements
- Run the
MultiFlavorBuild.py
script with--setup
- Run the
MultiFlavorBuild.py
script with--update
- Run the
MultiFlavorBuild.py
script with whatever flavors and architectures you would like in your binary package. This is the primary build and may take a while - Run the
MultiFlavorBuild.py
script with--bundle
to create the Nuget package layout in theBundle
directory
- TODO: How to support the security patch repos? (This isn't essential if there are no security
- patches for CryptoPkg, but it's a necessary piece to figure out for the process.)
Most releases will be performed on a new EDK2 integration cycle (to re-enable the CryptoBin dependencies for the Basecore release branch). As such, most integrations will need all of the following steps.
If you're already on an existing release branch and you've just updated CryptoPkg and want to release a new CryptoBin, you can skip to the Regular Release Steps.
While performing the Basecore integration:
- Disable the
edk2-basecrypto-driver-bin
extdep until a new release can be generated for this integration- In the file
CryptoPkg/Driver/Bin/BaseCryptoDriver_ext_dep.json
: - Set the
scope
to "global-disabled" - Set the
version
back to "0.0.0" (for safety so that we don't accidentally mis-version it when re-enabling)
- In the file
Then, in this repo:
- Take a look at the
.gitmodules
file and cross reference all required submodules- Make sure that all submodules have a matching
release/*
branch and that they have all been tagged as*_CIBuild
- Example: if we're trying to make a new package on the
release/202202
branch, we must first check Basecore and Silicon Arm Tiano to make sure that they have2202_CIBuild
tags, proving that they're valid to perform a new release
- Make sure that all submodules have a matching
- Create the new release branch in this repo
- Update the
version_major_minor
parameter in the.azuredevops/pipelines/ReleaseBuild.yml
file - Update
pip-requirements.txt
file to match Basecore for this release - Update pipeline tools to match Basecore for the new release (right now, this is just
the
python_version
variable)
In this repo:
- Update to the correct release branches for each submodule in
.gitmodules
- Pull the correct commit for each submodule
- Determine whether any configuration or PCDs need to change. This configuration is outside the scope of this document. Please refer to the greater documentation around CryptoBin and BCOP
- Generate the new packaging files. These files are created by a script that lives in Mu Crypto Release
- Script lives at
CryptoBinPkg/Driver/Packaging/generate_cryptodriver.py
- Running this with no arguments should be an acceptable default. Refer to the script help for information on the possible arguments
- This script needs to be executed from within a valid Python venv configured for Mu
- Script lives at
- Compare the changes and stage them for PR into Mu Crypto Release
- Total changes should affect dozens of files in CryptoBinPkg, most of which live in
CryptoBinPkg/Driver/Bin
directory - For most releases, these changes should only be timestamps. If they are anything other than timestamps, make sure you understand why and make sure they are intended
- IMPORTANT NOTE If any new functions are introduced or any existing crypto family is updated
to include new functions (or the prototypes change), you must update the
EDKII_CRYPTO_VERSION
inCryptoBinPkg/Driver/Packaging/Crypto.template.h
- Total changes should affect dozens of files in CryptoBinPkg, most of which live in
- Submit your PR to Mu Crypto Release
Once the server is updated for the new release, run the release pipeline on the new branch. The release pipeline is located in the public Project Mu DevOps organization. To release a new version:
- Go to the release pipeline
Run pipeline
and select your branch- The following parameters are currently available:
- If you're confident in this build, you can go ahead and click the "Publish Nuget Package" checkbox
- It's possible to swap the VM image and build toolchain to Linux/GCC5
- The Major and Minor version is set by default in the pipeline (updated on each release), but can be overridden
- The Patch version must be set on each release. This must be manually checked for uniqueness. See here for the currently published versions
- The Version Label is optional. For example, a Version Label might be
-beta
for versionX.Y.Z-beta
. If you don't want a version label at all, set this toNone
and the pipeline will ignore it entirely
Once successfully released, tag the commit with the version (e.g. 2022.02.1
) and push tag to the server.
This project has adopted the Microsoft Open Source Code of Conduct https://opensource.microsoft.com/codeofconduct/
For more information see the Code of Conduct FAQ https://opensource.microsoft.com/codeofconduct/faq/ or contact opencode@microsoft.com. with any additional questions or comments.
Contributions are always welcome and encouraged! Please open any issues in the Project Mu GitHub tracker and read https://microsoft.github.io/mu/How/contributing/