Readme.md

   1 # EDK II Project
   2
   3 A modern, feature-rich, cross-platform firmware development environment
   4 for the UEFI and PI specifications from www.uefi.org.
   5
   6 # Build Status
   7
   8 <table>
   9   <tr>
  10     <th>Host Type</th>
  11     <th>Toolchain</th>
  12     <th>Branch</th>
  13     <th>Build Status</th>
  14     <th>Test Status</th>
  15     <th>Code Coverage</th>
  16   </tr>
  17   <tr>
  18     <td>Windows</td>
  19     <td>VS2019</td>
  20     <td>master</td>
  21     <td>
  22       <a  href="https://dev.azure.com/tianocore/edk2-ci/_build/latest?definitionId=32&branchName=master">
  23       <img src="https://dev.azure.com/tianocore/edk2-ci/_apis/build/status/Windows%20VS2019%20CI?branchName=master"/></a>
  24     </td>
  25     <td>
  26       <a  href="https://dev.azure.com/tianocore/edk2-ci/_build/latest?definitionId=32&branchName=master">
  27       <img src="https://img.shields.io/azure-devops/tests/tianocore/edk2-ci/32.svg"/></a>
  28     </td>
  29     <td>
  30       <a  href="https://dev.azure.com/tianocore/edk2-ci/_build/latest?definitionId=32&branchName=master">
  31       <img src="https://img.shields.io/badge/coverage-coming_soon-blue"/></a>
  32     </td>
  33   </tr>
  34   <tr>
  35     <td>Ubuntu</td>
  36     <td>GCC</td>
  37     <td>master</td>
  38     <td>
  39       <a  href="https://dev.azure.com/tianocore/edk2-ci/_build/latest?definitionId=31&branchName=master">
  40       <img src="https://dev.azure.com/tianocore/edk2-ci/_apis/build/status/Ubuntu%20GCC5%20CI?branchName=master"/></a>
  41     </td>
  42     <td>
  43       <a  href="https://dev.azure.com/tianocore/edk2-ci/_build/latest?definitionId=31&branchName=master">
  44       <img src="https://img.shields.io/azure-devops/tests/tianocore/edk2-ci/31.svg"/></a>
  45     </td>
  46     <td>
  47       <a  href="https://dev.azure.com/tianocore/edk2-ci/_build/latest?definitionId=31&branchName=master">
  48       <img src="https://img.shields.io/badge/coverage-coming_soon-blue"/></a>
  49     </td>
  50   </tr>
  51 </table>
  52
  53 [More CI Build information](.pytool/Readme.md)
  54
  55 # License Details
  56
  57 The majority of the content in the EDK II open source project uses a
  58 [BSD-2-Clause Plus Patent License](License.txt).  The EDK II open source project
  59 contains the following components that are covered by additional licenses:
  60 * [BaseTools/Source/C/BrotliCompress](BaseTools/Source/C/BrotliCompress/LICENSE)
  61 * [MdeModulePkg/Library/BrotliCustomDecompressLib](MdeModulePkg/Library/BrotliCustomDecompressLib/LICENSE)
  62 * [BaseTools/Source/C/LzmaCompress](BaseTools/Source/C/LzmaCompress/LZMA-SDK-README.txt)
  63 * [MdeModulePkg/Library/LzmaCustomDecompressLib](MdeModulePkg/Library/LzmaCustomDecompressLib/LZMA-SDK-README.txt)
  64 * [IntelFrameworkModulePkg/Library/LzmaCustomDecompressLib/Sdk](IntelFrameworkModulePkg/Library/LzmaCustomDecompressLib/LZMA-SDK-README.txt)
  65 * [BaseTools/Source/C/VfrCompile/Pccts](BaseTools/Source/C/VfrCompile/Pccts/RIGHTS)
  66 * [MdeModulePkg/Universal/RegularExpressionDxe/Oniguruma](MdeModulePkg/Universal/RegularExpressionDxe/Oniguruma/README)
  67 * [OvmfPkg](OvmfPkg/License.txt)
  68 * [CryptoPkg/Library/OpensslLib/openssl](https://github.com/openssl/openssl/blob/50eaac9f3337667259de725451f201e784599687/LICENSE)
  69 * [ArmPkg/Library/ArmSoftFloatLib/berkeley-softfloat-3](https://github.com/ucb-bar/berkeley-softfloat-3/blob/b64af41c3276f97f0e181920400ee056b9c88037/COPYING.txt)
  70
  71 The EDK II Project is composed of packages.  The maintainers for each package
  72 are listed in [Maintainers.txt](Maintainers.txt).
  73
  74 # Resources
  75 * [TianoCore](http://www.tianocore.org)
  76 * [EDK II](https://github.com/tianocore/tianocore.github.io/wiki/EDK-II)
  77 * [Getting Started with EDK II](https://github.com/tianocore/tianocore.github.io/wiki/Getting-Started-with-EDK-II)
  78 * [Mailing Lists](https://github.com/tianocore/tianocore.github.io/wiki/Mailing-Lists)
  79 * [TianoCore Bugzilla](https://bugzilla.tianocore.org)
  80 * [How To Contribute](https://github.com/tianocore/tianocore.github.io/wiki/How-To-Contribute)
  81 * [Release Planning](https://github.com/tianocore/tianocore.github.io/wiki/EDK-II-Release-Planning)
  82
  83 # Code Contributions
  84 To make a contribution to a TianoCore project, follow these steps.
  85 1. Create a change description in the format specified below to
  86    use in the source control commit log.
  87 2. Your commit message must include your `Signed-off-by` signature
  88 3. Submit your code to the TianoCore project using the process
  89    that the project documents on its web page.  If the process is
  90    not documented, then submit the code on development email list
  91    for the project.
  92 4. It is preferred that contributions are submitted using the same
  93    copyright license as the base project. When that is not possible,
  94    then contributions using the following licenses can be accepted:
  95    * BSD (2-clause): http://opensource.org/licenses/BSD-2-Clause
  96    * BSD (3-clause): http://opensource.org/licenses/BSD-3-Clause
  97    * MIT: http://opensource.org/licenses/MIT
  98    * Python-2.0: http://opensource.org/licenses/Python-2.0
  99    * Zlib: http://opensource.org/licenses/Zlib
 100
 101    For documentation:
 102    * FreeBSD Documentation License
 103      https://www.freebsd.org/copyright/freebsd-doc-license.html
 104
 105    Contributions of code put into the public domain can also be
 106    accepted.
 107
 108    Contributions using other licenses might be accepted, but further
 109    review will be required.
 110
 111 # Developer Certificate of Origin
 112
 113 Your change description should use the standard format for a
 114 commit message, and must include your `Signed-off-by` signature.
 115
 116 In order to keep track of who did what, all patches contributed must
 117 include a statement that to the best of the contributor's knowledge
 118 they have the right to contribute it under the specified license.
 119
 120 The test for this is as specified in the [Developer's Certificate of
 121 Origin (DCO) 1.1](https://developercertificate.org/). The contributor
 122 certifies compliance by adding a line saying
 123
 124   Signed-off-by: Developer Name <developer@example.org>
 125
 126 where `Developer Name` is the contributor's real name, and the email
 127 address is one the developer is reachable through at the time of
 128 contributing.
 129
 130 ```
 131 Developer's Certificate of Origin 1.1
 132
 133 By making a contribution to this project, I certify that:
 134
 135 (a) The contribution was created in whole or in part by me and I
 136     have the right to submit it under the open source license
 137     indicated in the file; or
 138
 139 (b) The contribution is based upon previous work that, to the best
 140     of my knowledge, is covered under an appropriate open source
 141     license and I have the right under that license to submit that
 142     work with modifications, whether created in whole or in part
 143     by me, under the same open source license (unless I am
 144     permitted to submit under a different license), as indicated
 145     in the file; or
 146
 147 (c) The contribution was provided directly to me by some other
 148     person who certified (a), (b) or (c) and I have not modified
 149     it.
 150
 151 (d) I understand and agree that this project and the contribution
 152     are public and that a record of the contribution (including all
 153     personal information I submit with it, including my sign-off) is
 154     maintained indefinitely and may be redistributed consistent with
 155     this project or the open source license(s) involved.
 156 ```
 157
 158 # Sample Change Description / Commit Message
 159
 160 ```
 161 From: Contributor Name <contributor@example.com>
 162 Subject: [Repository/Branch PATCH] Pkg-Module: Brief-single-line-summary
 163
 164 Full-commit-message
 165
 166 Signed-off-by: Contributor Name <contributor@example.com>
 167 ```
 168
 169 ## Notes for sample patch email
 170
 171 * The first line of commit message is taken from the email's subject
 172   line following `[Repository/Branch PATCH]`. The remaining portion of the
 173   commit message is the email's content.
 174 * `git format-patch` is one way to create this format
 175
 176 ## Definitions for sample patch email
 177
 178 * `Repository` is the identifier of the repository the patch applies.
 179   This identifier should only be provided for repositories other than
 180   `edk2`. For example `edk2-BuildSpecification` or `staging`.
 181 * `Branch` is the identifier of the branch the patch applies. This
 182   identifier should only be provided for branches other than `edk2/master`.
 183   For example `edk2/UDK2015`, `edk2-BuildSpecification/release/1.27`, or
 184   `staging/edk2-test`.
 185 * `Module` is a short identifier for the affected code or documentation. For
 186   example `MdePkg`, `MdeModulePkg/UsbBusDxe`, `Introduction`, or
 187   `EDK II INF File Format`.
 188 * `Brief-single-line-summary` is a short summary of the change.
 189 * The entire first line should be less than ~70 characters.
 190 * `Full-commit-message` a verbose multiple line comment describing
 191   the change.  Each line should be less than ~70 characters.
 192 * `Signed-off-by` is the contributor's signature identifying them
 193   by their real/legal name and their email address.
 194
 195 # Submodules
 196
 197 Submodule in EDK II is allowed but submodule chain should be avoided
 198 as possible as we can. Currently EDK II contains the following submodules
 199
 200 - CryptoPkg/Library/OpensslLib/openssl
 201 - ArmPkg/Library/ArmSoftFloatLib/berkeley-softfloat-3
 202
 203 ArmSoftFloatLib is actually required by OpensslLib. It's inevitable
 204 in openssl-1.1.1 (since stable201905) for floating point parameter
 205 conversion, but should be dropped once there's no such need in future
 206 release of openssl.
 207
 208 To get a full, buildable EDK II repository, use following steps of git
 209 command
 210
 211 ```
 212 $ git clone https://github.com/tianocore/edk2.git
 213 $ cd edk2
 214 $ git submodule update --init
 215 $ cd ..
 216 ```
 217
 218 If there's update for submodules, use following git commands to get the
 219 latest submodules code.
 220
 221 ```
 222 $ cd edk2
 223 $ git pull
 224 $ git submodule update
 225 ```
 226
 227 Note: When cloning submodule repos, '--recursive' option is not
 228 recommended. EDK II itself will not use any code/feature from
 229 submodules in above submodules. So using '--recursive' adds a
 230 dependency on being able to reach servers we do not actually want
 231 any code from, as well as needlessly downloading code we will not
 232 use.