From nobody Mon Apr 29 13:21:08 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of groups.io designates 66.175.222.108 as permitted sender) client-ip=66.175.222.108; envelope-from=bounce+27952+97094+1787277+3901457@groups.io; helo=mail02.groups.io; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of groups.io designates 66.175.222.108 as permitted sender) smtp.mailfrom=bounce+27952+97094+1787277+3901457@groups.io; dmarc=fail(p=none dis=none) header.from=linux.microsoft.com ARC-Seal: i=1; a=rsa-sha256; t=1670430267; cv=none; d=zohomail.com; s=zohoarc; b=M+q5SPjlzV7kFBbGRXQ84VgFDGns353jvbDRpz5aj/2FmGyLmk1H7tZEsZwol0ORLcGMt66FfePM4WbS36tyjFbK/I5M2BMHbaETHg9UDSHeiCGh3FQ11Lfh1fnFbs/biCUwID4IamWuIxYmIVIJDtfeyZl07xDiQN33R4SpCnM= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1670430267; h=Content-Type:Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Id:List-Help:List-Unsubscribe:MIME-Version:Message-ID:Reply-To:References:Sender:Subject:To; bh=KsQAU13z9rR0QHKEfvs6tMf6Z8lYsFlJpAmUwMFxXSo=; b=LLbiwadDYY9/FI+UvJy3+obb1tuzeUoiNd1S8xejXUSsAmOL9VN/lTIyipPoyKjD1L0oGIJSwTCMfyr1AhZ/MxjFV2ico5t2wPSxicy7X7pC8bdCcOaOaMZqw1NSCwhlQXiUR5lP/JwVB2Bo1jHGp0KaOgprJIW7YiCAlljY508= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of groups.io designates 66.175.222.108 as permitted sender) smtp.mailfrom=bounce+27952+97094+1787277+3901457@groups.io; dmarc=fail header.from= (p=none dis=none) Received: from mail02.groups.io (mail02.groups.io [66.175.222.108]) by mx.zohomail.com with SMTPS id 167043026718884.37701888495167; Wed, 7 Dec 2022 08:24:27 -0800 (PST) Return-Path: X-Received: by 127.0.0.2 with SMTP id z1abYY1788612xxagI6wE5oO; Wed, 07 Dec 2022 08:24:26 -0800 X-Received: from linux.microsoft.com (linux.microsoft.com [13.77.154.182]) by mx.groups.io with SMTP id smtpd.web10.20067.1670430266245668301 for ; Wed, 07 Dec 2022 08:24:26 -0800 X-Received: from localhost.localdomain (unknown [47.201.8.94]) by linux.microsoft.com (Postfix) with ESMTPSA id 4EBA620B83E7; Wed, 7 Dec 2022 08:24:25 -0800 (PST) DKIM-Filter: OpenDKIM Filter v2.11.0 linux.microsoft.com 4EBA620B83E7 From: "Michael Kubacki" To: devel@edk2.groups.io Cc: Sean Brogan , Michael D Kinney , Liming Gao Subject: [edk2-devel] [edk2-wiki][PATCH v3 1/4] Add initial How to Build with Stuart Document Date: Wed, 7 Dec 2022 11:24:00 -0500 Message-Id: <20221207162403.337-2-mikuback@linux.microsoft.com> In-Reply-To: <20221207162403.337-1-mikuback@linux.microsoft.com> References: <20221207162403.337-1-mikuback@linux.microsoft.com> MIME-Version: 1.0 Precedence: Bulk List-Unsubscribe: List-Subscribe: List-Help: Sender: devel@edk2.groups.io List-Id: Mailing-List: list devel@edk2.groups.io; contact devel+owner@edk2.groups.io Reply-To: devel@edk2.groups.io,mikuback@linux.microsoft.com X-Gm-Message-State: 2s39kZaqLhYRCAEE7oZiqYm4x1787277AA= Content-Transfer-Encoding: quoted-printable DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=groups.io; q=dns/txt; s=20140610; t=1670430266; bh=WNk2IP7rfbB9hb+2i/5bz6cH4U0xQZSUPeo70rwufec=; h=Cc:Content-Type:Date:From:Reply-To:Subject:To; b=n9HwQrxPrFXhkmN/gQZAElQ22iXcx3M+AEK4quFyQlw8zjXu41o0+tLxGzD5w50aIrc L/Q9SnTtmhebFKXSwRjNHrXiQr1jW/8IsP5L85hNiDgssFZDHd/KZfX9cVd/d05HZ20P3 dFeKBy6RvuAACt9cgQcN3hVb8k+rPikk28s= X-ZohoMail-DKIM: pass (identity @groups.io) X-ZM-MESSAGEID: 1670430268081100006 Content-Type: text/plain; charset="utf-8" From: Michael Kubacki Adds a new document that comprehensively describes how to manually set up a build environment using Stuart. Covers the following topics: 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 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. 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(+) 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 like = 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) and [= (2) regular use](#regular-use-steps). + +## One-Time Steps + +If you've already completed these steps you don't need to run them again. + +
+ 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 system,= make changes in the code, and submit + your changes back to the GitHub repository. + + Git Download= Page +
    • +
  • + Python + + Python is a programming language that many of the edk2 build tools are w= ritten in. + + You will need Python to run the edk2 build tools including stuart<= /code>, which is written in Python. + + It is recommended you install a Python version that is equal to the vers= ion used in the + UsePythonVersion@0 step in this file + .azurepipelines/templates/p= r-gate-steps.yml. + + That version is constantly tested against the code in the repository. + + Python D= ownload Page +
    • +
  • + C Compiler + + A C compiler is needed to compile the firmware code. + + Several options are available. This is an area where direct guidance can= not be provided. + + You will need to choose a compiler supported on your host operating syst= em and the particular firmware packages + you are building. + + However, it is common to use: +
      +
    • GCC on Linu= x
      • +
      + Ubuntu GCC Installation Instructions + apt-get update && apt-get install -y build-essential git nasm = 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 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 --noca= che --installPath C:\BuildTools ^ + --add Microsoft.VisualStudio.Component.VC.CoreBuildTools --a= dd Microsoft.VisualStudio.Component.VC.Tools.x86.x64 ^ + --add Microsoft.VisualStudio.Component.Windows11SDK.22000 --= 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 right-c= licking on Command Prompt + and select Run as Administrator +
        2. +
      2. + Change to the directory where you downloaded the vs_BuildT= ools.exe file + (e.g. C:\Downloads) +
        3. +
      3. + Enter the following command: +
        + + start /w vs_BuildTools.exe --quiet --wait --norestart --nocach= e --installPath C:\BuildTools ^ + --add Microsoft.VisualStudio.Component.VC.CoreBuildTools --add= Microsoft.VisualStudio.Component.VC.Tools.x86.x64 ^ + --add Microsoft.VisualStudio.Component.Windows10SDK.19041 --ad= d 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-cli= cking on Command Prompt and + select Run as Administrator +
        2. +
      2. + Change to the directory where you downloaded the vs_BuildToo= ls.exe file + (e.g. C:\Downloads) +
        3. +
      3. + Enter the following command: +
        + + start /w vs_BuildTools.exe --quiet --wait --norestart --nocach= e --installPath C:\BuildTools ^ + --add Microsoft.VisualStudio.Component.VC.CoreBuildTools --add= Microsoft.VisualStudio.Component.VC.Tools.x86.x64 ^ + --add Microsoft.VisualStudio.Component.Windows10SDK.17763 --ad= d Microsoft.VisualStudio.Component.VC.Tools.ARM ^ + --add Microsoft.VisualStudio.Component.VC.Tools.ARM64 + +
        4. +
      +
      +
      +

      +

        +
      • + Note: You can find the latest version of Visual Studio supported= 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 proc= ess. +

      +
      +
      +
    +
    • +
  • + 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 keep t= he 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 environmen= ts in this repository. + +That's it! + +Your terminal may now indicate that a virtual environment is active by sho= wing `(.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) when = 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 exampl= e, it depends on git submodules, Python pip +modules, tools in the form of application binaries, etc. If the correspond= ing 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 comm= a-separated list + - `-a `: To run only certain architectures use = a comma-separated list + - `-t `: To run only tests related to certain tar= gets 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_buil= d` and `stuart_build` commands. + +--- + +## Examples + +
+ Example: I want to build MdeModulePkg to test a change I made t= here. +
+

+ The important parameter here is the -p parameter which sp= ecifies that MdeModulePkg + should be built. +

+

+ The example below uses: +

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

+ + stuart_ci_build -c .pytool/CISettings.py -p MdeModulePkg -a IA32,X6= 4 TOOL_CHAIN_TAG=3DVS2019 +
+
+ +
+ Example: I want to build OvmfPkg to test a change I made there.= +
+

+ OvmfPkg is considered a "platform firmware" for the + QEMU open-source e= mulator. +

+ + + stuart_build -c PlatformBuild.py -p OvmfPkg -a IA32,X64 TOOL_CHAIN_= TAG=3DVS2019 + +

+ If you want to run CI checks such as CI plugins, you can use stu= art_ci_build with the CI build file. +

+ + stuart_ci_build -c .pytool/CISettings.py -p OvmfPkg -a IA32,X64 TOO= L_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-source e= mulator. +

+ + + +

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

+ + 
+    =E2=9D=AF stuart_build -c PlatformBuild.py --help
+    usage: stuart_build [-h] [--SKIPBUILD] [--SKIPPREBUILD] [--SKIPPOSTBUI=
LD] [--FLASHONLY] [--FLASHROM]
+                        [--UPDATECONF] [--CLEAN] [--CLEANONLY] [--OUTPUTCO=
NFIG 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 repla=
ced with latest template files
+      --CLEAN, --clean, --CLEAN
+                            Clean. Remove all old build artifacts and inte=
rmediate files
+      --CLEANONLY, --cleanonly, --CleanOnly
+                            Clean Only. Do clean operation and don't build=
 just exit.
+      --OUTPUTCONFIG OUTPUTCONFIG, --outputconfig OUTPUTCONFIG, --OutputCo=
nfig OUTPUTCONFIG
+                            Provide shell variables in a file
+      -a BUILD_ARCH, --arch BUILD_ARCH
+                            Optional - CSV of architecture to build. IA32 =
will use IA32 for Pei & Dxe. X64 will use
+                            X64 for both PEI and DXE. IA32,X64 will use IA=
32 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/post =
build process
+      BLD_*_=3D        - Set a build flag for all build types
+                                  (key=3Dvalue will get passed to build pr=
ocess)
+      BLD__=3D - Set a build flag for build type of 
+                                  (key=3Dvalue will get passed to build pr=
ocess 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 buil= d should use GCC5 + to build with GCC. +
    • +
  • + The -a parameter is used to specify the IA32 and X64 architectures should be + built. +
    • +
  • + The --flashrom parameter is used to load the firmware= in QEMU and boot QEMU after the firmware build + is completed. +
    • +
+

+ + stuart_build -c PlatformBuild.py -p OvmfPkg -a IA32,X64 TOOL_CHAIN_= TAG=3DGCC5 --flashrom +
+
+ +
+ Example: I want to bui= ld BaseTools. +
+ BaseTools has its own build script t= hat leverages + edk2-pytools to build the BaseToo= ls applications. +
+
+
+ Linux (Ubuntu) Pre-Steps + sudo apt update +
+ sudo apt install build-essential uuid-dev +
+

+ The file BaseTools/Edk2ToolsBuild.py + 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 the n= on-compiler checks in CI. +
+

+ The NO-TARGET build target specifies that the actual firm= ware 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 packa= ges 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 selection 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. You ca= n then test with the remaining plugins and + then use git to restore the deleted plugin directories back when done = testing. +

+

+ For example, to only test with the SpellCheck plugin, del= ete 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 befor= e they are merged to the edk2 main branch. + Stuart is used within the edk2 CI process to pull build dependencies a= nd 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 Continuous Inte= gration. +

+
+
+ +
+ 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 BaseTool= s/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 share= 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 ext= ensions for building and maintaining an edk2 + based UEFI firmware code tree. +
    • +
+
+
+ +
+ What is CISettings.py? +
+

+ CISettings.py is a common name given to a configuration f= ile used with Stuart for CI. It is often + stored in a folder named .pytools in the root of a reposi= tory. 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_TAG_VA= LUE_HERE + +
    • +
  • + + stuart_update -c .pytool/CISettings.py TOOL_CHAIN_TAG=3DPUT_TAG_VALU= E_HERE + +
    • +
  • + + stuart_ci_build -c .pytool/CISettings.py TOOL_CHAIN_TAG=3DPUT_TAG_VA= LUE_HERE + +
    • +
+
+
+ +
+ What is PlatformBuild.py? +
+

+ PlatformBuild.py is a common name given to a configuratio= n 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_TAG_VA= LUE_HERE + +
    • +
  • + + stuart_update -c SomePkg/PlatformBuild.py TOOL_CHAIN_TAG=3DPUT_TAG_V= ALUE_HERE + +
    • +
  • + + stuart_build -c SomePkg/PlatformBuild.py TOOL_CHAIN_TAG=3DPUT_TAG_VA= LUE_HERE + +
    • +
+

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

+
+ Note: Build plugins will also run during CI if a CompilerPlugin is pre= sent that builds the code. +
+
+
+ +
+ + What is the difference between stuart_ci_build and = stuart_build? + +
+
    +
  • + stuart_ci_build - Runs CI plugins. By default, often ru= ns CI on several packages at once. This + includes all of the checks needed to consider the code ready for int= egration to the mainline. +
    • +
  • + stuart_build - Does not run CI plugins. Builds one plat= form. Platforms often expose + platform-specific parameters as defined in their PlatformBuild= .py file. +
    • +
+
+
+ +
+ What does stuart_ci_b= uild do exactly? +
+

+ The Stuart CI process is composed of "CI plugins" that get discovered = 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) com= pilation is performed during CI by a compiler + CI plugin. +

+

+ Each plugin reports back a pass/fail status. If any plugin fails, CI f= ails. However, plugins usually provide some + level of customization in a "CI package configuration file". If this f= ile is present, it is in the root of the + package with the naming convention PkgName.ci.yaml. For e= xample, + MdePkg.ci.yaml is + the CI package configuration file for MdePkg. Sometimes, = 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 checker= 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 sett= ings 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 get mo= re detailed output. +

+

+ Also, look in your /Build directory. +

+

+ Each Stuart command produces a separate file. Open the file correspond= ing 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<= /li> +
+
+
+ +
+ What are "plugins"? +
+

+ The different types of plugins supported by Stuart and details about e= ach type are available in the + edk2-pytool-ex= tensions Plugin Manager + page. +

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

+ Start in the + edk2-pytool-extensions User Docu= mentation. +

+
+
--=20 2.28.0.windows.1 -=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D- Groups.io Links: You receive all messages sent to this group. View/Reply Online (#97094): https://edk2.groups.io/g/devel/message/97094 Mute This Topic: https://groups.io/mt/95518590/1787277 Group Owner: devel+owner@edk2.groups.io Unsubscribe: https://edk2.groups.io/g/devel/unsub [importer@patchew.org] -=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D- From nobody Mon Apr 29 13:21:08 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of groups.io designates 66.175.222.108 as permitted sender) client-ip=66.175.222.108; envelope-from=bounce+27952+97095+1787277+3901457@groups.io; helo=mail02.groups.io; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of groups.io designates 66.175.222.108 as permitted sender) smtp.mailfrom=bounce+27952+97095+1787277+3901457@groups.io; dmarc=fail(p=none dis=none) header.from=linux.microsoft.com ARC-Seal: i=1; a=rsa-sha256; t=1670430269; cv=none; d=zohomail.com; s=zohoarc; b=Gw/1YEXgFVzYOuMcobIIouDifkp/i7Rqgu0wr3wviXYPg+XdoZbW0a14C425H02LQa5gwfgK1XqWnGYm5KXhsGVf821miunaq6KSIQWs6kf3lZe02/XB4fssv12mVTW4qmMvOjZr3DlkAP6sn3REjKBwfY/5Zu9sDPvItxXhqOU= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1670430269; h=Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Id:List-Help:List-Unsubscribe:MIME-Version:Message-ID:Reply-To:References:Sender:Subject:To; bh=RQf/ODO5JHNHh/qBnI+4/UdRPCGfm7eQcXWTjjVb4AE=; b=mMzT15zsnIxXNqARXtGgEM1Ted5xxo3kLKEnlDqq0TJWVsvb36uMsXF00FSEIXu3kW7TtsSj+xs9il1+XHJl25Hm+Q8QlYUrm4nqZjXq4wFAcdD3sTQGTkCLjzI8hpd+me5Tn9+kVHxvm5mZPT7len18J6FAoMgpwbahCyXAzG8= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of groups.io designates 66.175.222.108 as permitted sender) smtp.mailfrom=bounce+27952+97095+1787277+3901457@groups.io; dmarc=fail header.from= (p=none dis=none) Received: from mail02.groups.io (mail02.groups.io [66.175.222.108]) by mx.zohomail.com with SMTPS id 1670430269672517.9283799263272; Wed, 7 Dec 2022 08:24:29 -0800 (PST) Return-Path: X-Received: by 127.0.0.2 with SMTP id GQ4ZYY1788612x22tPP8PKSw; Wed, 07 Dec 2022 08:24:29 -0800 X-Received: from linux.microsoft.com (linux.microsoft.com [13.77.154.182]) by mx.groups.io with SMTP id smtpd.web10.20068.1670430268736573081 for ; Wed, 07 Dec 2022 08:24:28 -0800 X-Received: from localhost.localdomain (unknown [47.201.8.94]) by linux.microsoft.com (Postfix) with ESMTPSA id 997DC20B83E2; Wed, 7 Dec 2022 08:24:27 -0800 (PST) DKIM-Filter: OpenDKIM Filter v2.11.0 linux.microsoft.com 997DC20B83E2 From: "Michael Kubacki" To: devel@edk2.groups.io Cc: Sean Brogan , Michael D Kinney , Liming Gao , Michael Kubacki Subject: [edk2-devel] [edk2-wiki][PATCH v3 2/4] Add initial container usage instructions Date: Wed, 7 Dec 2022 11:24:01 -0500 Message-Id: <20221207162403.337-3-mikuback@linux.microsoft.com> In-Reply-To: <20221207162403.337-1-mikuback@linux.microsoft.com> References: <20221207162403.337-1-mikuback@linux.microsoft.com> MIME-Version: 1.0 Precedence: Bulk List-Unsubscribe: List-Subscribe: List-Help: Sender: devel@edk2.groups.io List-Id: Mailing-List: list devel@edk2.groups.io; contact devel+owner@edk2.groups.io Reply-To: devel@edk2.groups.io,mikuback@linux.microsoft.com X-Gm-Message-State: wVBi9fAc4h19n831kh0DduPKx1787277AA= Content-Transfer-Encoding: quoted-printable DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=groups.io; q=dns/txt; s=20140610; t=1670430269; bh=zFLR4OMX9HIA41Lncij1Twk7o9np9UMA1xfzA8aAVtM=; h=Cc:Date:From:Reply-To:Subject:To; b=UhEJlx120L32hQnCJlKZFvoMCJ0YYlA7n9i0WXAipXg+w2RTyyPrDZTLM4yATnVCTLW Pg87toOLAxzaRpdWWj+ABIYSdj1r8FjADnLw4MBglE/0+mIZWPvtna1hQ72Zt9YIM/xpk h6wPSZwDF2gE+0AMlcenQ2rcdmop3sDrjXk= X-ZohoMail-DKIM: pass (identity @groups.io) X-ZM-MESSAGEID: 1670430270055100009 Content-Type: text/plain; charset="utf-8" From: Chris Fernald Covers: - Container background - Docker background and installation - Local development with containers - How to manually configure a container - Integration with VS Code - Containers in pipelines Cc: Sean Brogan Cc: Michael D Kinney Cc: Liming Gao Cc: Michael Kubacki Signed-off-by: Chris Fernald --- How-to-Develop-With-Containers.md | 120 ++++++++++++++++++++ 1 file changed, 120 insertions(+) diff --git a/How-to-Develop-With-Containers.md b/How-to-Develop-With-Contai= ners.md new file mode 100644 index 000000000000..aa9ff802f158 --- /dev/null +++ b/How-to-Develop-With-Containers.md @@ -0,0 +1,120 @@ +# How to Develop With Containers + +Because various EDKII project can have specific build tools and environmen= t requirements +it can be beneficial to use a container build environment for local develo= pment. +TianoCore maintains container images for various Operating Systems and too= l chains in the +[TianoCore Containers repository](https://github.com/tianocore/containers)= . These +images contain the build tools and environment configurations to ensure a = consistent +and reproducible build between local development, CI, and pipeline platfor= m builds. + +If you are new to the concept of containers, more information can be found +[on the Docker website](https://www.docker.com/resources/what-container/). + +## Setting up Docker + +> NOTE: +> Some Docker software is not free and some uses of Docker may require a p= ersonal or +> Business subscription. Users should verify their use is licensed for the= ir organization +> if necessary. + +The existing TianoCore container images are created for use with Docker. O= n Linux, +docker can be installed through the distributions package management appli= cation. +For specific builds and for other operating systems, see the [Docker insta= ll page](https://docs.docker.com/engine/install/). + +### Windows Docker Setup + +It is strongly recommended to use the WSL 2 based engine when running Dock= er on +Windows. This can be configured in the General settings in Docker Desktop.= Generally, +this provides better performance and overall design over the legacy. Detai= ls on +this framework can be found in the [Docker documentation](https://docs.doc= ker.com/desktop/windows/wsl/). + +## Local Development + +To use the build container images to develop locally, there are several co= nfigurations +depending the developers preferences. This section details some tools and = tips that +make using containers for local development easier. This section is not co= mprehensive +however and it is encouraged users experiment and consider contributing ba= ck any +new useful configurations or tools to this documentation. + +> NOTE: +> If the code base is cloned in Windows, it is not advised to directly open +> this repository in a Linux dev container as the file system share betwee= n Windows +> and WSL 2 causes a very significant performance reduction. Instead, clon= e the +> repo in the WSL file system and map into the container or directly clone= into +> the container. + +### Manually configuring the container + +Some developers may wish to manually maintain their containers. This is us= eful +for using editors that do not have native support for containers or the sp= ecific +type of containers used. + +First, select the image most appropriate from the [TianoCore containers li= st](https://github.com/tianocore/containers#current-status) +or a custom image for a specific platform or project. This image can be pu= lled down +from the docker command line. + +```bash +docker pull ghcr.io/tianocore/containers/: +``` + +After pulling the image, the image can be started. It is useful to map in = the workspace +from the host OS as this allows easy access to the code and build files fr= om the +host as well as the container. + +```bash +docker run -i -v : --workdir=3D= --name=3D ghcr.io/tianocore/containers/:= +``` + +After the container is existed, it can be resume by using the start comman= d. + +```bash +docker start -i +``` + +When running in the container, the build instructions should be used as th= ey normally +would using the stuart commands. + +### Visual Studio Code + +The Visual Studio Code [Dev Container extension](https://code.visualstudio= .com/docs/devcontainers/containers) +provides an easy and consistent way to use containers for local developmen= t. At +the time of writing, this extension only supports Linux based containers. = This +extension provides a number of useful additions to the specified docker im= age on +creation. + +- Configures git credential manager to pipe in git credentials. +- Makes extensions available on code inside the container. +- Abstracts management of the container for seamless use in the editor. + +For a shared docker image configuration, this can be configured by creatin= g a +.devcontainer file in the repository. Some useful configurations are detai= ls below. + +| Configuration | Purpose | +| :------------ | :------ | +| "privileged": true | This may be needed for access to KVM for QEMU a= cceleration. | +| "forwardPorts": [####] | Can be used to forward debug or serial ports to= the host OS. | + +It may also be desireable to run initialization commands using the "postCr= eateCommand" +option. Specifically running `git config --global --add safe.directory ${c= ontainerWorkspaceFolder}` +may be required if mapping the repository into the container is expected. + +And example of a devcontainer used for a QEMU platform repo is included be= low. + +```json +{ + "image": "ghcr.io/tianocore/containers/fedora-35-dev:latest", + "postCreateCommand": "git config --global --add safe.directory ${contain= erWorkspaceFolder} && pip install --upgrade -r pip-requirements.txt", + "forwardPorts": [5000], + "privileged": true +} +``` + +## Pipeline Builds + +Both Azure pipelines and github workflows have native support for containe= rs. Information +on this can be found in the [Azure Pipeline Documentation](https://learn.m= icrosoft.com/en-us/azure/devops/pipelines/process/container-phases?view=3Da= zure-devops) +and the [Github Workflow Documentation](https://docs.github.com/en/actions= /using-workflows/workflow-syntax-for-github-actions). + +One important detail to note is that Azure pipelines will create a new use= r in the +docker image during the pipeline. This user is used for all tasks and oper= ations +and so certain local user install locations may not be by default on the p= ath. --=20 2.28.0.windows.1 -=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D- Groups.io Links: You receive all messages sent to this group. View/Reply Online (#97095): https://edk2.groups.io/g/devel/message/97095 Mute This Topic: https://groups.io/mt/95518591/1787277 Group Owner: devel+owner@edk2.groups.io Unsubscribe: https://edk2.groups.io/g/devel/unsub [importer@patchew.org] -=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D- From nobody Mon Apr 29 13:21:08 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of groups.io designates 66.175.222.108 as permitted sender) client-ip=66.175.222.108; envelope-from=bounce+27952+97096+1787277+3901457@groups.io; helo=mail02.groups.io; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of groups.io designates 66.175.222.108 as permitted sender) smtp.mailfrom=bounce+27952+97096+1787277+3901457@groups.io; dmarc=fail(p=none dis=none) header.from=linux.microsoft.com ARC-Seal: i=1; a=rsa-sha256; t=1670430273; cv=none; d=zohomail.com; s=zohoarc; b=i9dBwSYBJauCBkQkYJmzuojyTbQgK6cMIX9yNYQAvhqa3Psir9iwc5WKVoDFh2/O2jo12Gudhs+IDBjsVXXz5vtg/xZYVipeAsUgA6TOpkVP+yiyWFwZHpb1o9AtK0VHxzOfHJAxePWQUUaUYJ9P7tKp/DXQBvA6pydE6d/zlN8= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1670430273; h=Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Id:List-Help:List-Unsubscribe:MIME-Version:Message-ID:Reply-To:References:Sender:Subject:To; bh=T/vs73UrXCFVp0elU61dkJ8S+KF+HYGAgXPr+FRW42s=; b=LrnhMnwW+UyFdbqWG6wHfabPRGtV5TAHZXI4qRXZV6Sy76v0svSVk0YVStXH2XoTTjgHn8w+AaUHg9lONPRiUE4zcmOTGKzv5mrN+VGue5P8n4BEg8YoRJEa8t70t2bqYeINZEkx7WpEbKes2DWvENVSgXYaoE/p/FeQtQ2JBwE= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of groups.io designates 66.175.222.108 as permitted sender) smtp.mailfrom=bounce+27952+97096+1787277+3901457@groups.io; dmarc=fail header.from= (p=none dis=none) Received: from mail02.groups.io (mail02.groups.io [66.175.222.108]) by mx.zohomail.com with SMTPS id 1670430273476322.05321711555735; Wed, 7 Dec 2022 08:24:33 -0800 (PST) Return-Path: X-Received: by 127.0.0.2 with SMTP id 8rgkYY1788612xmjufbBo1TL; Wed, 07 Dec 2022 08:24:32 -0800 X-Received: from linux.microsoft.com (linux.microsoft.com [13.77.154.182]) by mx.groups.io with SMTP id smtpd.web10.20074.1670430272155835155 for ; Wed, 07 Dec 2022 08:24:32 -0800 X-Received: from localhost.localdomain (unknown [47.201.8.94]) by linux.microsoft.com (Postfix) with ESMTPSA id 2D6DA20B83E5; Wed, 7 Dec 2022 08:24:31 -0800 (PST) DKIM-Filter: OpenDKIM Filter v2.11.0 linux.microsoft.com 2D6DA20B83E5 From: "Michael Kubacki" To: devel@edk2.groups.io Cc: Sean Brogan , Michael D Kinney , Liming Gao Subject: [edk2-devel] [edk2-wiki][PATCH v3 3/4] Add top-level build instructions file Date: Wed, 7 Dec 2022 11:24:02 -0500 Message-Id: <20221207162403.337-4-mikuback@linux.microsoft.com> In-Reply-To: <20221207162403.337-1-mikuback@linux.microsoft.com> References: <20221207162403.337-1-mikuback@linux.microsoft.com> MIME-Version: 1.0 Precedence: Bulk List-Unsubscribe: List-Subscribe: List-Help: Sender: devel@edk2.groups.io List-Id: Mailing-List: list devel@edk2.groups.io; contact devel+owner@edk2.groups.io Reply-To: devel@edk2.groups.io,mikuback@linux.microsoft.com X-Gm-Message-State: rYKqwVKOtY068z1Ch7ABRiAcx1787277AA= Content-Transfer-Encoding: quoted-printable DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=groups.io; q=dns/txt; s=20140610; t=1670430272; bh=T/vs73UrXCFVp0elU61dkJ8S+KF+HYGAgXPr+FRW42s=; h=Cc:Date:From:Reply-To:Subject:To; b=La15n+t75QL8KtIX23Nzjmgx3IGsnED5VgIj/w+Jk8F0V4ZZ+gzoUJtMqrsbWHcsOMA YfjYo0OkGuvEBkbSIqczDW53y2eQL49u+sIdGcsJsQPt4sEoNVnBvTEcrhKbAjbO1jN/o 450KTqa9PJQV8KluXi3F6k57lGiReLCskt8= X-ZohoMail-DKIM: pass (identity @groups.io) X-ZM-MESSAGEID: 1670430274067100014 Content-Type: text/plain; charset="utf-8" From: Michael Kubacki Adds a file that describes various build approaches in edk2 at a high-level and points to the documents with specific instructions for each approach. This is a starting point for this file and it will likely be expanded upon in the future. Cc: Sean Brogan Cc: Michael D Kinney Cc: Liming Gao Signed-off-by: Michael Kubacki --- Build-Instructions.md | 35 ++++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/Build-Instructions.md b/Build-Instructions.md new file mode 100644 index 000000000000..2b6d19725c7d --- /dev/null +++ b/Build-Instructions.md @@ -0,0 +1,35 @@ +# EDK II Build Instructions + +Over the life of the project, EDK II has evolved it's build process. A com= mon theme has been reducing the number of +manual steps involved and easing environment setup and configuration so de= velopers can more quickly get started writing +firmware code. + +There's currently three high-level approaches to build (listed in recommen= ded order): + +1. [Containers](How-to-Develop-With-Containers.md) +2. [Stuart](How-to-Build-With-Stuart.md) +3. [build](Getting-Started-with-EDK-II.mediawiki) + +## Build Option Comparison + +Containers have seen widespread adoption in software development. The capa= bility to deploy well-defined, ready-to-go +images, results in unmatched performance, portability, and consistency of = build environments. By extension, TianoCore +leverages containers for both server-side builds (e.g. for pull requests a= nd continuous integration) and for local +developer builds. The TianoCore project maintains containers in +[tianocore/containers](https://github.com/tianocore/containers). + +If you just want to get started quickly and be able to receive the best su= pport possible (since issues in containers +are easy to reproduce, fix, and deploy), then start with the container ins= tructions. + +Prior to containers, building involved a lot of manual steps. Downloading = compilers, various dependencies, running +the right commands in the right order, and so on. A lot of that work was r= educed and moved into a tool that +orchestrates a lot of the underlying steps needed to simply set up a build= environment and start building code. That +tool is called "Stuart". So if you would like a local build environment wi= thout using containers, it is recommended +to use Stuart. Containers use Stuart and the CI system uses Stuart and man= y CI checks are performed by Stuart to allow +pull requests to be submitted. So running CI locally with Stuart will put = you in a great position to have code ready +for contribution to the project. + +At the core of the build is an application called `build`. Ultimately, con= tainers and Stuart will eventually call +`build` to actually build the code and prior to the introduction of those = two approaches, `build` was the primary +build path. So, you can still call `build` directly. This will result in m= ore manual steps and a lack of the feature +set brought by the other two options but you can produce a working firmwar= e image (in most cases) with `build`. --=20 2.28.0.windows.1 -=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D- Groups.io Links: You receive all messages sent to this group. View/Reply Online (#97096): https://edk2.groups.io/g/devel/message/97096 Mute This Topic: https://groups.io/mt/95518592/1787277 Group Owner: devel+owner@edk2.groups.io Unsubscribe: https://edk2.groups.io/g/devel/unsub [importer@patchew.org] -=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D- From nobody Mon Apr 29 13:21:08 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of groups.io designates 66.175.222.108 as permitted sender) client-ip=66.175.222.108; envelope-from=bounce+27952+97097+1787277+3901457@groups.io; helo=mail02.groups.io; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of groups.io designates 66.175.222.108 as permitted sender) smtp.mailfrom=bounce+27952+97097+1787277+3901457@groups.io; dmarc=fail(p=none dis=none) header.from=linux.microsoft.com ARC-Seal: i=1; a=rsa-sha256; t=1670430276; cv=none; d=zohomail.com; s=zohoarc; b=TRIn6GwZ8g3KZnhZdAgT/M6O62nJWVKRGM+KKovFHDuOC42nmxpLFxFdn8LVFodv4cwyLq0KAX3mgAiXVUt76ADokSR78ug8vVPlkSRdpAaR1EZliXoq1Gt7UZMxHinlSeP81nszsg7I4E/Oh2s/Q1x6+E8s3hJLdFDbSk4SMq4= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1670430276; h=Content-Type:Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Id:List-Help:List-Unsubscribe:MIME-Version:Message-ID:Reply-To:References:Sender:Subject:To; bh=AVsCePv1mMigdB0zSi+lYtVvXdcYuxw6grHW/vGe1iM=; b=RJbIEhfzxmL0XYXV+454xQ8MS1hsSOJEsLzwpsHMSUU5C8WmXEBd/XnuVOTpZfmxNKi9yYnmeX5I342gwp/NGereQKmIEdmvHs1LADs4ZY9OrO9oQkWUbpoULYWaD65C+ijL5gbH2/tJWYc80Ec3w07k+O5tVFveXKdFCeb/5PU= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of groups.io designates 66.175.222.108 as permitted sender) smtp.mailfrom=bounce+27952+97097+1787277+3901457@groups.io; dmarc=fail header.from= (p=none dis=none) Received: from mail02.groups.io (mail02.groups.io [66.175.222.108]) by mx.zohomail.com with SMTPS id 1670430276082861.9821569908681; Wed, 7 Dec 2022 08:24:36 -0800 (PST) Return-Path: X-Received: by 127.0.0.2 with SMTP id UC53YY1788612xbnFYvQZhOQ; Wed, 07 Dec 2022 08:24:35 -0800 X-Received: from linux.microsoft.com (linux.microsoft.com [13.77.154.182]) by mx.groups.io with SMTP id smtpd.web10.20076.1670430274755685986 for ; Wed, 07 Dec 2022 08:24:34 -0800 X-Received: from localhost.localdomain (unknown [47.201.8.94]) by linux.microsoft.com (Postfix) with ESMTPSA id 9B85D20B83E2; Wed, 7 Dec 2022 08:24:33 -0800 (PST) DKIM-Filter: OpenDKIM Filter v2.11.0 linux.microsoft.com 9B85D20B83E2 From: "Michael Kubacki" To: devel@edk2.groups.io Cc: Sean Brogan , Michael D Kinney , Liming Gao Subject: [edk2-devel] [edk2-wiki][PATCH v3 4/4] Update existing build instructions Date: Wed, 7 Dec 2022 11:24:03 -0500 Message-Id: <20221207162403.337-5-mikuback@linux.microsoft.com> In-Reply-To: <20221207162403.337-1-mikuback@linux.microsoft.com> References: <20221207162403.337-1-mikuback@linux.microsoft.com> MIME-Version: 1.0 Precedence: Bulk List-Unsubscribe: List-Subscribe: List-Help: Sender: devel@edk2.groups.io List-Id: Mailing-List: list devel@edk2.groups.io; contact devel+owner@edk2.groups.io Reply-To: devel@edk2.groups.io,mikuback@linux.microsoft.com X-Gm-Message-State: mWeggIWjjqka0b1NCQoCv2Prx1787277AA= Content-Transfer-Encoding: quoted-printable DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=groups.io; q=dns/txt; s=20140610; t=1670430275; bh=XQ9Ms7N35Lb/z+khxXHToYuBUE47YlwdYE2wx15vp0g=; h=Cc:Content-Type:Date:From:Reply-To:Subject:To; b=mOfKk+d33eqZ5wMo0SUN7bMbScdQfhEWnioCUivz6VXMEdYSl8F1mGYdr3XKEEAKNLj WAgtPb6CuuKxua4q5zz1ZhPbFNJK5fuF2x2htdhiIJGWiSuzYErlqIOOXI6SCIUnCJrV5 ORUBmsgulZewKwYWq4krkdEMdDDX0Gi9380= X-ZohoMail-DKIM: pass (identity @groups.io) X-ZM-MESSAGEID: 1670430278241100002 Content-Type: text/plain; charset="utf-8" From: Michael Kubacki Adds a reference to existing documents in the wiki with build instructions to point to the new top-level build file. The original files are left in place for information reference and to prevent breaking links that may be pointing to them. Cc: Sean Brogan Cc: Michael D Kinney Cc: Liming Gao Signed-off-by: Michael Kubacki --- Build.mediawiki | 229 +++++----- BuildTool-Setup-Guide.mediawiki | 89 ++-- Common-instructions-for-Unix.mediawiki | 377 +++++++-------- Common-instructions.mediawiki | 211 ++++----- Getting-Started-with-EDK-II.mediawiki | 16 +- UDK2017-How-to-Build.md | 252 +++++----- UDK2018-How-to-Build.md | 262 +++++------ Unix-like-systems.mediawiki | 425 ++++++++--------- Using-EDK-II-with-Native-GCC.mediawiki | 483 ++++++++++---------- Windows-systems.mediawiki | 314 ++++++------- 10 files changed, 1352 insertions(+), 1306 deletions(-) diff --git a/Build.mediawiki b/Build.mediawiki index 19517eaef4e3..8e16cb12576b 100644 --- a/Build.mediawiki +++ b/Build.mediawiki @@ -1,114 +1,115 @@ -=3DFrequently asked EDK II build questions=3D - -=3D=3DRegarding the Build for EDK II, how do you specify a different compi= ler tool chain on the command line?=3D=3D - -Use =E2=80=93t parameter for the build command. Example: Using the Microso= ft Visual Studio 2005 tool chain ...=20 - - build =E2=80=93t VS2005 - -For using other tools see [[Getting_Started_with_EDK_II]]. This provides s= ome detailed instructions for setting up some different tool chains? The fi= le Conf/tools_def.txt contains a list of targets. - -=3D=3DIs it possible to use PCDs @ build time?=3D=3D - -It depends on what you are trying to do. For use in code, yes.=20 -For example Featureflag PCD type can be used. For determining if something= should be built then it might be better to use the =E2=80=9CBuild =E2=80= =93D MACRO-NAME=E2=80=9D options. - -=3D=3DIs there information on Building on Linux?=3D=3D - -For EDK II, yes, the build tools will need to be recompiled for GCC. Link= for how to Build for GCC:=20 -* [[Using EDK II with Native GCC]] -* [[Unix-like systems]] (For older Linux distributions, or when using Cygw= in or Mac OS X) - -=3D=3DWhat is the state of Python?=3D=3D - -For Building EDK II Python of at least version 2.5 is needed. On Linux we'= ve used 2.6 & 2.7. Python 3+ is not supported and will not work currently.= On Windows, python is not required to be installed to build with EDK II.=20 -There is a Python interpreter that is part of the EFI toolkit on tianocor= e.org and is at the Python version level 2.4, There are long term plans to= move to EDK II and support a later version of Python as part of the [[AppP= kg]]. It is currently (01/2012) in Aplha stage. - -=3D=3DWhat does the parsing tool do?=3D=3D - -The parsing is part of the first stage of the build process. There are to= ols for parsing the set build description files and the target.txt for a p= ackage or platform and creates the intermediate make and autogen files - -=3D=3DRegarding writing UEFI Applications in EDK II, where is the output a= nd/or the binary UEFI application after doing a build?=3D=3D - -The Build output directory is defined in the defines section of a .DSC fil= e. -For example, Nt32Pkg\Nt32Pkg.dsc - the UEFI application would be in Build\= NT32\DEBUG_MYTOOLS\IA32 - - OUTPUT_DIRECTORY =3D Build/NT32 - SUPPORTED_ARCHITECTURES =3D IA32 - BUILD_TARGETS =3D DEBUG - -=3D=3DHow do I get my UEFI application to the target UEFI System?=3D=3D - -Copy the UEFI Binary image from the output directory after the build to a = USB thumb drive. Insert the USB drive in the UEFI target system. Boot to th= e EFI Shell. The USB thumb drive should be one of the file systems, e.g. F= S0:. Cd to that USB drive and run your UEFI application from the shell pro= mpt - -=3D=3DIs the Build tool source code part of the Build?=3D=3D - -No, the repository for the Tool Source is a separate project. The binaries= by default are for a Windows build machine. For building on a non Windows = machine there are instructions for recompiling the build tools. - -The sources are also in the BaseTools directory with the pre-build Windows= executables. These sources are provided because they are the sources that= were used to build the binaries. On Windows systems, the tools do not nee= d to be built. The pre-build binaries can be used. One Linux, Unix, and O= S/X systems, these sources are used to build the binaries for that OS, or i= n the case of Python, the Python sources are executed directly. - -The [[BaseTools]] Source Project is where advanced development is done on = the EDK II tools. Tool developers work in this separate project until a ne= w feature is stable, and only once it is stable is a feature added to the B= aseTools directory and new binaries are generated. - -=3D=3DCan we use Ifdefs?=3D=3D - -This is not recommended but can be used within the DSC or FDF as part of t= he build. -But here is an example: - - !ifdef $(SOURCE_DEBUG_ENABLE) - MSFT:*_*_X64_GENFW_FLAGS =3D --keepexceptiontable - GCC:*_*_X64_GENFW_FLAGS =3D --keepexceptiontable - INTEL:*_*_X64_GENFW_FLAGS =3D --keepexceptiontable - !endif - -=3D=3DWhen can the report generator show the protocols produced by modules= ?=3D=3D - -The report generator can show protocols produced by modules. The Runtime D= XE core will also report what is missing before handing off. - -=3D=3DWhy is the Buffer Security check flag (Build options) disabled for b= uilding EDK II UEFI applications and drivers but it is enabled for building= tools. =3D=3D - -UEFI applications and drivers are not executed in an Operating System envi= ronment. This is important, as the switches have very specific (and, in the= pre-boot space, negative) impacts on generated code. The switch does two t= hings in the code that are not acceptable for the pre-boot environment: - -* The switch enables additional code in the compiled code base, which requ= ires a larger stack space than may be available in the pre-boot environment=20 -* The switch injects a call to a compiler specific function that is not pr= esent in our Firmware builds, and which we do not have information on how t= o emulate.=20 - -We disable these settings, as enabling them would create non-functioning c= ode. - -However, please be aware that Detecting Stack Overflows in Firmware is cri= tical in validation and development, and we use other techniques in our cod= e to do so. We just cannot generically support the /Gs flags (as noted abo= ve). - -The tools do have this flag set, as they are used within the Operating Sys= tem environment, where the intrinsic added by the compiler can be processed= correctly.=20 -=20 -=3D=3DAre there Dual-mode drivers in EDK II?=3D=3D - -No. The EDK II build system does not support the dual mode drivers descri= bed in the PI Specification. These types of modules are very difficult to = implement correctly, so we recommend that developer implement two different= modules instead. The EDK II does allow them to share sources, but 2 diffe= rent PE/COFF images would be generated when built. - -=3D=3DIs there a tool to parse the BIOS Build tree?=3D=3D - -a) Use the report generator build into the build tool =E2=80=9CBUILD =E2= =80=93Y=E2=80=9D on the command line=20 - - -Y REPORTTYPE, --report-type=3DREPORTTYPE - Flags that control the type of build report to - generate. Must be one of: [PCD, LIBRARY, FLASH, = DEPEX,=20 - BUILD_FLAGS, FIXED_ADDRESS, EXECUTION_ORDER]. - To specify more than one flag, repeat this option= on - the command line and the default flag set is [PCD, - LIBRARY, FLASH, DEPEX, BUILD_FLAGS, FIXED_ADDRESS] - Use =E2=80=9C=E2=80=93Y DEPEX=E2=80=9D and this will generate = a text file with dependencies - - -b) Predicted dispatch order is limited because it makes assumptions about = the behavior of the modules. It cannot handle that some PPI and DXE protoco= ls that might be conditionally produced. Documented in the EDK2010 March 20= 10 release notes. - -c) Behavior of dispatch =E2=80=93 filter for DEBUG_DISPATCH in DSC in the = PCD for the error level PcdDebugPrintErrorLevel - -=3D=3DHow does the build tool load the reset vector at 0xFFFFFFF0?=3D=3D - -This is defined in the PI Specification, Volume 3. http://www.uefi.org/spe= cs - -In the FV (Firmware Volume) there is something called a Volume Top File in= f the FV . A Volume Top File (VTF) is a file that must be located such that= the last byte of the file is also the last byte of the firmware volume. Re= gardless of the file type, a VTF must have the file name GUID of EFI_FFS_VO= LUME_TOP_FILE_GUID as defined below. - -From a PI point of view the first module that runs is the SEC core. If you= look at the VTF file it is basically the code that contains the reset vect= or, and it jumps to the SEC code. - -Reference: https://github.com/tianocore/edk2/tree/master/UefiCpuPkg/ResetV= ector/Vtf0 - -So the hard code bit is the FV (Firmware Volume) that that contains the Vo= lume Top File needs to start at an address where the end of the FV will end= up at the magic reset vector address.=20 - -In general the EFI build system constructs relocatable PE/COFF images, and= every image is linked at zero. If the code executes from FLASH, then when = the FV is constructed the PE/COFF images that are XIP (eXecute In Place) ha= ve their PE/COFF image relocated based on where they end up in the FV (base= d on info in FDF file). This is done by the build system. If the EFI code r= uns from RAM then it is loaded by a PE/COFF loader and relocated to its loa= d address. +=3DFrequently asked EDK II build questions=3D + + Note: This page is retained for reference. Most of the content as of 202= 2 is still relevant but it is recommended to + view the new set of build instructions that describe how to develo= p using containers and build with the Stuart + application. + +New instructions: [[Build-Instructions.md|Build Instructions]] + +=3D=3DRegarding the Build for EDK II, how do you specify a different compi= ler tool chain on the command line?=3D=3D + +Use =E2=80=93t parameter for the build command. Example: Using the Microso= ft Visual Studio 2019 tool chain ... + + build =E2=80=93t VS2019 + +For using other tools see [[Getting_Started_with_EDK_II]]. This provides s= ome detailed instructions for setting up some different tool chains? The fi= le Conf/tools_def.txt contains a list of targets. + +=3D=3DIs it possible to use PCDs @ build time?=3D=3D + +It depends on what you are trying to do. For use in code, yes. +For example Featureflag PCD type can be used. For determining if something= should be built then it might be better to use the =E2=80=9CBuild =E2=80= =93D MACRO-NAME=E2=80=9D options. + +=3D=3DIs there information on Building on Linux?=3D=3D + +For EDK II, yes, the build tools will need to be recompiled for GCC. Link= for how to Build for GCC: +* [[Using EDK II with Native GCC]] +* [[Unix-like systems]] (For older Linux distributions, or when using Cygw= in or Mac OS X) + +=3D=3DWhat does the parsing tool do?=3D=3D + +The parsing is part of the first stage of the build process. There are to= ols for parsing the set build description files and the target.txt for a p= ackage or platform and creates the intermediate make and autogen files + +=3D=3DRegarding writing UEFI Applications in EDK II, where is the output a= nd/or the binary UEFI application after doing a build?=3D=3D + +The Build output directory is defined in the defines section of a .DSC fil= e. +For example, Nt32Pkg\Nt32Pkg.dsc - the UEFI application would be in Build\= NT32\DEBUG_MYTOOLS\IA32 + + OUTPUT_DIRECTORY =3D Build/NT32 + SUPPORTED_ARCHITECTURES =3D IA32 + BUILD_TARGETS =3D DEBUG + +=3D=3DHow do I get my UEFI application to the target UEFI System?=3D=3D + +Copy the UEFI Binary image from the output directory after the build to a = USB thumb drive. Insert the USB drive in the UEFI target system. Boot to th= e EFI Shell. The USB thumb drive should be one of the file systems, e.g. F= S0:. Cd to that USB drive and run your UEFI application from the shell pro= mpt + +=3D=3DIs the Build tool source code part of the Build?=3D=3D + +No, the repository for the Tool Source is a separate project. The binaries= by default are for a Windows build machine. For building on a non Windows = machine there are instructions for recompiling the build tools. + +The sources are also in the BaseTools directory with the pre-build Windows= executables. These sources are provided because they are the sources that= were used to build the binaries. On Windows systems, the tools do not nee= d to be built. The pre-build binaries can be used. One Linux, Unix, and O= S/X systems, these sources are used to build the binaries for that OS, or i= n the case of Python, the Python sources are executed directly. + +The [[BaseTools]] Source Project is where advanced development is done on = the EDK II tools. Tool developers work in this separate project until a ne= w feature is stable, and only once it is stable is a feature added to the B= aseTools directory and new binaries are generated. + +=3D=3DCan we use Ifdefs?=3D=3D + +This is not recommended but can be used within the DSC or FDF as part of t= he build. +But here is an example: + + !ifdef $(SOURCE_DEBUG_ENABLE) + MSFT:*_*_X64_GENFW_FLAGS =3D --keepexceptiontable + GCC:*_*_X64_GENFW_FLAGS =3D --keepexceptiontable + INTEL:*_*_X64_GENFW_FLAGS =3D --keepexceptiontable + !endif + +=3D=3DWhen can the report generator show the protocols produced by modules= ?=3D=3D + +The report generator can show protocols produced by modules. The Runtime D= XE core will also report what is missing before handing off. + +=3D=3DWhy is the Buffer Security check flag (Build options) disabled for b= uilding EDK II UEFI applications and drivers but it is enabled for building= tools. =3D=3D + +UEFI applications and drivers are not executed in an Operating System envi= ronment. This is important, as the switches have very specific (and, in the= pre-boot space, negative) impacts on generated code. The switch does two t= hings in the code that are not acceptable for the pre-boot environment: + +* The switch enables additional code in the compiled code base, which requ= ires a larger stack space than may be available in the pre-boot environment +* The switch injects a call to a compiler specific function that is not pr= esent in our Firmware builds, and which we do not have information on how t= o emulate. + +We disable these settings, as enabling them would create non-functioning c= ode. + +However, please be aware that Detecting Stack Overflows in Firmware is cri= tical in validation and development, and we use other techniques in our cod= e to do so. We just cannot generically support the /Gs flags (as noted abo= ve). + +The tools do have this flag set, as they are used within the Operating Sys= tem environment, where the intrinsic added by the compiler can be processed= correctly. + +=3D=3DAre there Dual-mode drivers in EDK II?=3D=3D + +No. The EDK II build system does not support the dual mode drivers descri= bed in the PI Specification. These types of modules are very difficult to = implement correctly, so we recommend that developer implement two different= modules instead. The EDK II does allow them to share sources, but 2 diffe= rent PE/COFF images would be generated when built. + +=3D=3DIs there a tool to parse the BIOS Build tree?=3D=3D + +a) Use the report generator build into the build tool =E2=80=9CBUILD =E2= =80=93Y=E2=80=9D on the command line + + -Y REPORTTYPE, --report-type=3DREPORTTYPE + Flags that control the type of build report to + generate. Must be one of: [PCD, LIBRARY, FLASH, = DEPEX, + BUILD_FLAGS, FIXED_ADDRESS, EXECUTION_ORDER]. + To specify more than one flag, repeat this option= on + the command line and the default flag set is [PCD, + LIBRARY, FLASH, DEPEX, BUILD_FLAGS, FIXED_ADDRESS] + Use =E2=80=9C=E2=80=93Y DEPEX=E2=80=9D and this will generate = a text file with dependencies + + +b) Predicted dispatch order is limited because it makes assumptions about = the behavior of the modules. It cannot handle that some PPI and DXE protoco= ls that might be conditionally produced. Documented in the EDK2010 March 20= 10 release notes. + +c) Behavior of dispatch =E2=80=93 filter for DEBUG_DISPATCH in DSC in the = PCD for the error level PcdDebugPrintErrorLevel + +=3D=3DHow does the build tool load the reset vector at 0xFFFFFFF0?=3D=3D + +This is defined in the PI Specification, Volume 3. http://www.uefi.org/spe= cs + +In the FV (Firmware Volume) there is something called a Volume Top File in= f the FV . A Volume Top File (VTF) is a file that must be located such that= the last byte of the file is also the last byte of the firmware volume. Re= gardless of the file type, a VTF must have the file name GUID of EFI_FFS_VO= LUME_TOP_FILE_GUID as defined below. + +From a PI point of view the first module that runs is the SEC core. If you= look at the VTF file it is basically the code that contains the reset vect= or, and it jumps to the SEC code. + +Reference: https://github.com/tianocore/edk2/tree/master/UefiCpuPkg/ResetV= ector/Vtf0 + +So the hard code bit is the FV (Firmware Volume) that that contains the Vo= lume Top File needs to start at an address where the end of the FV will end= up at the magic reset vector address. + +In general the EFI build system constructs relocatable PE/COFF images, and= every image is linked at zero. If the code executes from FLASH, then when = the FV is constructed the PE/COFF images that are XIP (eXecute In Place) ha= ve their PE/COFF image relocated based on where they end up in the FV (base= d on info in FDF file). This is done by the build system. If the EFI code r= uns from RAM then it is loaded by a PE/COFF loader and relocated to its loa= d address. diff --git a/BuildTool-Setup-Guide.mediawiki b/BuildTool-Setup-Guide.mediaw= iki index 445ef25af598..45a80406395f 100644 --- a/BuildTool-Setup-Guide.mediawiki +++ b/BuildTool-Setup-Guide.mediawiki @@ -1,43 +1,46 @@ -=3DGitHub Help=3D - -GitHub (https://help.github.com/index.html) provides step-by-step instruct= ions for user registration and basic features supported by GitHub=20 - -* Setup GitHub for Linux | Windows | MAC | All (https://help.github.com/ar= ticles/set-up-git) -* To download and install a Git GUI interface (http://git-scm.com/) - -=3D=3D'''GitHub EDK II Project Repositories'''=3D=3D - -* The EDK II BaseTools are part of the EDK II project repository.=20 -* The EDK II project repository is available at https://github.com/tianoco= re/edk2.=20 -* Prebuilt Windows tools are available at https://github.com/tianocore/edk= 2-BaseTools-win32.=20 -* Content that is not released under an accepted open source license can b= e found at https://github.com/tianocore/edk2-non-osi.
-=3D Getting the extra tools=3D -=3D=3D Compiler =3D=3D -For both the BuildTools and [http://www.tianocore.org/edk2/ EDK II] projec= ts, you will need to obtain a compiler from somewhere else. These instructi= ons do not cover obtaining or installation of a compiler tools chain. The B= aseTools build requires a C compiler; an assembler or ACPI assembler are no= t required to build tools in this project. BaseTools assume that a compiler= is already configured in the environment. - -=3D=3D Python =3D=3D -The BaseTools build supports the Makefile based build for EDK II. All Tool= s are written in either C or Python. The C tools must compile on all operat= ing systems with various compilers, so the code is written using simple, st= andard functions and libraries. The Python-based tools are written assuming= the features that were available in Python. GUI applications can be create= d in Python, using the wxPython package and all Python applications can be = converted to run under a native OS (Windows, Linux or OS/X.) via the [[Pyth= on Tools]]. - -The tools in this section are NOT required to build the EDK II project; th= ey are needed to compile the -BaseTools used to build the EDK II project. - -The Python 2.7.x tools may be obtained from http://www.python.org/, while = additional Python modules may be installed using setuptools or pip. Be sure= to check-out the appropriate tool set for your OS. - -*Linux and OS/X developers using a command line, create a directory that w= ill be used to hold the files, then change to that directory.=20 -**Replace URL with apropriate one from [[Python Tools]]. Installation and = configuration for these tools are left to the developer. - - - - -Refer to documentation in either the UserManuals or Source folders for mor= e information.=20 -* BuildTools [https://github.com/tianocore/buildtools-BaseTools/tree/maste= r/UserManuals User Manuals] - -=3D'''How to Setup the EDK II Tree'''=3D -See [[Getting Started with EDK II]] - -=3D=3D EDK II Development Process =3D=3D -After setting up your build environment see [[EDK II Development Process]= ] for making contributions to the EDK II Project. - -=3DFurther Help=3D - -If you have questions about the code or run into obstacles getting things = to work for you, please join our [[edk2-devel]] email list and ask your EDK= II related questions on the list. +=3DGitHub Help=3D + + Note: New build instructions are available. It is recommended to start w= ith the new instructions if learning how to + build edk2 for the first time. This page is retained for reference. + +New instructions: [[Build-Instructions.md|Build Instructions]] + +GitHub (https://help.github.com/index.html) provides step-by-step instruct= ions for user registration and basic features supported by GitHub + +* Setup GitHub for Linux | Windows | MAC | All (https://help.github.com/ar= ticles/set-up-git) +* To download and install a Git GUI interface (http://git-scm.com/) + +=3D=3D'''GitHub EDK II Project Repositories'''=3D=3D + +* The EDK II BaseTools are part of the EDK II project repository. +* The EDK II project repository is available at https://github.com/tianoco= re/edk2. +* Prebuilt Windows tools are available at https://github.com/tianocore/edk= 2-BaseTools-win32. +* Content that is not released under an accepted open source license can b= e found at https://github.com/tianocore/edk2-non-osi.
+=3D Getting the extra tools=3D +=3D=3D Compiler =3D=3D +For both the BuildTools and [http://www.tianocore.org/edk2/ EDK II] projec= ts, you will need to obtain a compiler from somewhere else. These instructi= ons do not cover obtaining or installation of a compiler tools chain. The B= aseTools build requires a C compiler; an assembler or ACPI assembler are no= t required to build tools in this project. BaseTools assume that a compiler= is already configured in the environment. + +=3D=3D Python =3D=3D +The BaseTools build supports the Makefile based build for EDK II. All Tool= s are written in either C or Python. The C tools must compile on all operat= ing systems with various compilers, so the code is written using simple, st= andard functions and libraries. The Python-based tools are written assuming= the features that were available in Python. GUI applications can be create= d in Python, using the wxPython package and all Python applications can be = converted to run under a native OS (Windows, Linux or OS/X.) via the [[Pyth= on Tools]]. + +The tools in this section are NOT required to build the EDK II project; th= ey are needed to compile the +BaseTools used to build the EDK II project. + +*Linux and OS/X developers using a command line, create a directory that w= ill be used to hold the files, then change to that directory. +**Replace URL with apropriate one from [[Python Tools]]. Installation and = configuration for these tools are left to the developer. + + + + +Refer to documentation in either the UserManuals or Source folders for mor= e information. +* BuildTools [https://github.com/tianocore/buildtools-BaseTools/tree/maste= r/UserManuals User Manuals] + +=3D'''How to Setup the EDK II Tree'''=3D +See [[Getting Started with EDK II]] + +=3D=3D EDK II Development Process =3D=3D +After setting up your build environment see [[EDK II Development Process]= ] for making contributions to the EDK II Project. + +=3DFurther Help=3D + +If you have questions about the code or run into obstacles getting things = to work for you, please join our [[edk2-devel]] email list and ask your EDK= II related questions on the list. diff --git a/Common-instructions-for-Unix.mediawiki b/Common-instructions-f= or-Unix.mediawiki index d15d3ffa0881..2432695e8844 100644 --- a/Common-instructions-for-Unix.mediawiki +++ b/Common-instructions-for-Unix.mediawiki @@ -1,186 +1,191 @@ -__NOTOC__ -=3D=3DCommon instructions for Unix =3D=3D - -A significant portion of the steps are common on the various UNIX-like pla= tforms. You should start with the instructions for the operating system th= at most closely matches your platform, and it will direct you here at the a= ppropriate time. - -Note these instructions are not for current Linux distributions, only UNIX= -like systems that do not work with the [[Using EDK II with Native GCC]] in= structions. Please follow the [[Using EDK II with Native GCC]] guide for ma= instream Linux distros. - -=3D=3D=3DGet the edk2 source tree using Git =3D=3D=3D - -
-bash$ mkdir ~/src
-bash$ cd ~/src
-bash$ git clone https://github.com/tianocore/edk2
-
- -=3D=3D=3D=3DFor EDKII project developers:=3D=3D=3D=3D -* Clone the EDK II project repository -** git clone https://github.com/tianocore/edk2 -* Change to the edk2 directory -* Build the tools -** make -C BaseTools -* Run the edksetup.sh script -** . edksetup.sh -When the above steps are done, you can work in the edk2 directory for code= development. - -=3D=3D=3DBuild the EDK II BaseTools=3D=3D=3D - -
-bash$ make -C edk2/BaseTools
-
- -=3D=3D=3DBuild gcc x64 UEFI cross compiler=3D=3D=3D - -In order to build UEFI images for x64, you will need to build a cross-comp= iler build of gcc. This can take quite a while to complete, possibly sever= al hours on older systems. But, a Python script has been provided to autom= ate this build process. - -Note: This is only needed if behind a internet firewall! -
-bash$ export http_proxy=3Dhttp://proxy.domain.com:proxy_port
-
- -To build gcc for x64, use these commands (this will take quite a while to = complete): - -
-bash$ cd ~/src/edk2/BaseTools/gcc
-bash$ ./mingw-gcc-build.py --arch=3Dx64 \
-  --prefix=3D~/programs/gcc/x64
-
- -=3D=3D=3DSetup build shell environment=3D=3D=3D - -
-bash$ cd ~/src/edk2
-bash$ export EDK_TOOLS_PATH=3D~/src/edk2/BaseTools
-bash$ . edksetup.sh BaseTools
-
- -=3D=3D=3DModify Conf Files=3D=3D=3D - -You will need to edit the Conf/tools_def.txt and Conf/target.txt files. T= hese changes will enable the MdeModulePkg to be built using the gcc x64 com= piler. - -=3D=3D=3D=3DEnable GCC X64 Cross-Compiler=3D=3D=3D=3D - -For the Conf/tools_def.txt file, find the following entry and comment the = line out: - -
-DEFINE UNIXGCC_X64_PETOOLS_PREFIX  =3D /opt/tiano/x86_64-pc-mingw64/x86_64=
-pc-mingw64/bin/
-
- -Next, find the following entry and uncomment the line: - -
-DEFINE UNIXGCC_X64_PETOOLS_PREFIX  =3D ENV(HOME)/programs/gcc/x64/bin/x86_=
64-pc-mingw32-
-
- -=3D=3D=3D=3DSet Build Target Information=3D=3D=3D=3D - -For the Conf/target.txt file, find the following lines: - -
-ACTIVE_PLATFORM       =3D Nt32Pkg/Nt32Pkg.dsc
-TARGET_ARCH           =3D IA32
-TOOL_CHAIN_TAG        =3D MYTOOLS
-
- -And change the cooresponding lines to match these: - -
-ACTIVE_PLATFORM       =3D MdeModulePkg/MdeModulePkg.dsc
-TARGET_ARCH           =3D X64
-TOOL_CHAIN_TAG        =3D UNIXGCC
-
- -=3D=3D=3DBuild Hello World! (and the rest of MdeModulePkg)=3D=3D=3D - -Now you should be able to simply run the build command to compile the MdeM= odulePkg. - -
-bash$ build
-
- -As a tangible result of the build, you should have the HelloWorld UEFI X64= application. If you have a X64 UEFI system available to you, then this ap= plication should be able to run successfully under the shell. - -
-bash$ ls Build/MdeModule/DEBUG_UNIXGCC/X64/HelloWorld.efi
-
- -=3D=3DEnabling Other Tools=3D=3D - -The above showed how to setup an X64 build environment for building the co= re MdeModulePkg. However, other packages may require additional tools such= as an IA32 cross-compiler and an ASL compiler. The steps to build these t= ools are described in this section. - -=3D=3D=3DBuild gcc IA32 UEFI cross compiler=3D=3D=3D - -In order to build UEFI images for IA32, you will need to build a cross-com= piler build of gcc. This can take quite a while to complete, possibly seve= ral hours on older systems. But, a Python script has been provided to auto= mate this build process. - -Note: This is only needed if behind a internet firewall! -
-bash$ export http_proxy=3Dhttp://proxy.domain.com:proxy_port
-
- -To build gcc for IA32, use these commands (this will take quite a while to= complete): - -
-bash$ cd ~/src/edk2/BaseTools/gcc
-bash$ ./mingw-gcc-build.py --arch=3Dia32 \
-  --prefix=3D~/programs/gcc/ia32
-
- -=3D=3D=3D=3DModify Conf Files=3D=3D=3D=3D - -Once the cross-compiler has been successfully built the Conf/tools_def.txt= will need to be updated so the cross-compiler can be used. - -Find the following statement in Conf/tools_def.txt and comment the line ou= t: - -
-DEFINE UNIXGCC_IA32_PETOOLS_PREFIX =3D /opt/tiano/i386-tiano-pe/i386-tiano=
-pe/bin/
-
- -Next, find the following statement and uncomment the line:=20 - -
-DEFINE UNIXGCC_IA32_PETOOLS_PREFIX =3D ENV(HOME)/programs/gcc/ia32/bin/i68=
6-pc-mingw32-
-
- -To enable building your target image with IA32 support the Conf/target.txt= will also need to be modified. - -Find the TARGET_ARCH definition in Conf/target.txt and change the correspo= nding line to match this - -
-TARGET_ARCH           =3D IA32
-
- -=3D=3D=3DBuild the Intel ASL (iasl) compiler=3D=3D=3D - -The Intel ASL compiler is not required for all edk2 developers. It is unl= ikely that UEFI Application or UEFI Driver builds will need an ASL compiler= . But, if you are building an entire system firmware image, then you may n= eed an ASL compiler. For example, the edk2 OVMF sample platform does requi= re an ASL compiler in order to be built. - -First, download the latest ACPI-CA release from http://www.acpica.org. - -'''OS X users''': At this time, the latest versions of ACPI-CA are not bui= lding on Mac OS X, so please use the release from 20081031 instead. - -
-bash$ cd ~/src
-bash$ wget http://www.acpica.org/download/acpica-unix-20090521.tar.gz
-bash$ tar -zxf acpica-unix-20090521.tar.gz
-bash$ make -C acpica-unix-20090521/compiler
-bash$ ln -s ~/src/acpica-unix-20090521/compiler/iasl ~/programs/iasl
-
- -=3D=3D=3D=3DModify Conf Files=3D=3D=3D=3D - -Once the Intel ASL compiler has been successfully built the Conf/tools_def= .txt will need to be updated so the ASL compiler can be used. - -Find the following statement in Conf/tools_def.txt and comment the line ou= t: - -
-DEFINE UNIX_IASL_BIN           =3D /usr/bin/iasl
-
- -Next, find the following statement and uncomment the line: - -
-DEFINE UNIX_IASL_BIN           =3D $(HOME)/programs/iasl
-
- -=3D=3D=3DBuild [http://www.tianocore.org/ovmf/ OVMF]=3D=3D=3D - -Once your build environment is set up you might be interested in building = the [http://www.tianocore.org/ovmf/ OVMF] platform which is included in the= main edk2 source tree. Since [http://www.tianocore.org/ovmf/ OVMF] builds= a full system firmware image this may be of interest to UEFI system firmwa= re developers. +__NOTOC__ +=3D=3DCommon instructions for Unix =3D=3D + + Note: New build instructions are available. It is recommended to start w= ith the new instructions if learning how to + build edk2 for the first time. This page is retained for reference. + +New instructions: [[Build-Instructions.md|Build Instructions]] + +A significant portion of the steps are common on the various UNIX-like pla= tforms. You should start with the instructions for the operating system th= at most closely matches your platform, and it will direct you here at the a= ppropriate time. + +Note these instructions are not for current Linux distributions, only UNIX= -like systems that do not work with the [[Using EDK II with Native GCC]] in= structions. Please follow the [[Using EDK II with Native GCC]] guide for ma= instream Linux distros. + +=3D=3D=3DGet the edk2 source tree using Git =3D=3D=3D + +
+bash$ mkdir ~/src
+bash$ cd ~/src
+bash$ git clone https://github.com/tianocore/edk2
+
+ +=3D=3D=3D=3DFor EDKII project developers:=3D=3D=3D=3D +* Clone the EDK II project repository +** git clone https://github.com/tianocore/edk2 +* Change to the edk2 directory +* Build the tools +** make -C BaseTools +* Run the edksetup.sh script +** . edksetup.sh +When the above steps are done, you can work in the edk2 directory for code= development. + +=3D=3D=3DBuild the EDK II BaseTools=3D=3D=3D + +
+bash$ make -C edk2/BaseTools
+
+ +=3D=3D=3DBuild gcc x64 UEFI cross compiler=3D=3D=3D + +In order to build UEFI images for x64, you will need to build a cross-comp= iler build of gcc. This can take quite a while to complete, possibly sever= al hours on older systems. But, a Python script has been provided to autom= ate this build process. + +Note: This is only needed if behind a internet firewall! +
+bash$ export http_proxy=3Dhttp://proxy.domain.com:proxy_port
+
+ +To build gcc for x64, use these commands (this will take quite a while to = complete): + +
+bash$ cd ~/src/edk2/BaseTools/gcc
+bash$ ./mingw-gcc-build.py --arch=3Dx64 \
+  --prefix=3D~/programs/gcc/x64
+
+ +=3D=3D=3DSetup build shell environment=3D=3D=3D + +
+bash$ cd ~/src/edk2
+bash$ export EDK_TOOLS_PATH=3D~/src/edk2/BaseTools
+bash$ . edksetup.sh BaseTools
+
+ +=3D=3D=3DModify Conf Files=3D=3D=3D + +You will need to edit the Conf/tools_def.txt and Conf/target.txt files. T= hese changes will enable the MdeModulePkg to be built using the gcc x64 com= piler. + +=3D=3D=3D=3DEnable GCC X64 Cross-Compiler=3D=3D=3D=3D + +For the Conf/tools_def.txt file, find the following entry and comment the = line out: + +
+DEFINE UNIXGCC_X64_PETOOLS_PREFIX  =3D /opt/tiano/x86_64-pc-mingw64/x86_64=
-pc-mingw64/bin/
+
+ +Next, find the following entry and uncomment the line: + +
+DEFINE UNIXGCC_X64_PETOOLS_PREFIX  =3D ENV(HOME)/programs/gcc/x64/bin/x86_=
64-pc-mingw32-
+
+ +=3D=3D=3D=3DSet Build Target Information=3D=3D=3D=3D + +For the Conf/target.txt file, find the following lines: + +
+ACTIVE_PLATFORM       =3D Nt32Pkg/Nt32Pkg.dsc
+TARGET_ARCH           =3D IA32
+TOOL_CHAIN_TAG        =3D MYTOOLS
+
+ +And change the cooresponding lines to match these: + +
+ACTIVE_PLATFORM       =3D MdeModulePkg/MdeModulePkg.dsc
+TARGET_ARCH           =3D X64
+TOOL_CHAIN_TAG        =3D UNIXGCC
+
+ +=3D=3D=3DBuild Hello World! (and the rest of MdeModulePkg)=3D=3D=3D + +Now you should be able to simply run the build command to compile the MdeM= odulePkg. + +
+bash$ build
+
+ +As a tangible result of the build, you should have the HelloWorld UEFI X64= application. If you have a X64 UEFI system available to you, then this ap= plication should be able to run successfully under the shell. + +
+bash$ ls Build/MdeModule/DEBUG_UNIXGCC/X64/HelloWorld.efi
+
+ +=3D=3DEnabling Other Tools=3D=3D + +The above showed how to setup an X64 build environment for building the co= re MdeModulePkg. However, other packages may require additional tools such= as an IA32 cross-compiler and an ASL compiler. The steps to build these t= ools are described in this section. + +=3D=3D=3DBuild gcc IA32 UEFI cross compiler=3D=3D=3D + +In order to build UEFI images for IA32, you will need to build a cross-com= piler build of gcc. This can take quite a while to complete, possibly seve= ral hours on older systems. But, a Python script has been provided to auto= mate this build process. + +Note: This is only needed if behind a internet firewall! +
+bash$ export http_proxy=3Dhttp://proxy.domain.com:proxy_port
+
+ +To build gcc for IA32, use these commands (this will take quite a while to= complete): + +
+bash$ cd ~/src/edk2/BaseTools/gcc
+bash$ ./mingw-gcc-build.py --arch=3Dia32 \
+  --prefix=3D~/programs/gcc/ia32
+
+ +=3D=3D=3D=3DModify Conf Files=3D=3D=3D=3D + +Once the cross-compiler has been successfully built the Conf/tools_def.txt= will need to be updated so the cross-compiler can be used. + +Find the following statement in Conf/tools_def.txt and comment the line ou= t: + +
+DEFINE UNIXGCC_IA32_PETOOLS_PREFIX =3D /opt/tiano/i386-tiano-pe/i386-tiano=
-pe/bin/
+
+ +Next, find the following statement and uncomment the line: + +
+DEFINE UNIXGCC_IA32_PETOOLS_PREFIX =3D ENV(HOME)/programs/gcc/ia32/bin/i68=
6-pc-mingw32-
+
+ +To enable building your target image with IA32 support the Conf/target.txt= will also need to be modified. + +Find the TARGET_ARCH definition in Conf/target.txt and change the correspo= nding line to match this + +
+TARGET_ARCH           =3D IA32
+
+ +=3D=3D=3DBuild the Intel ASL (iasl) compiler=3D=3D=3D + +The Intel ASL compiler is not required for all edk2 developers. It is unl= ikely that UEFI Application or UEFI Driver builds will need an ASL compiler= . But, if you are building an entire system firmware image, then you may n= eed an ASL compiler. For example, the edk2 OVMF sample platform does requi= re an ASL compiler in order to be built. + +First, download the latest ACPI-CA release from http://www.acpica.org. + +'''OS X users''': At this time, the latest versions of ACPI-CA are not bui= lding on Mac OS X, so please use the release from 20081031 instead. + +
+bash$ cd ~/src
+bash$ wget http://www.acpica.org/download/acpica-unix-20090521.tar.gz
+bash$ tar -zxf acpica-unix-20090521.tar.gz
+bash$ make -C acpica-unix-20090521/compiler
+bash$ ln -s ~/src/acpica-unix-20090521/compiler/iasl ~/programs/iasl
+
+ +=3D=3D=3D=3DModify Conf Files=3D=3D=3D=3D + +Once the Intel ASL compiler has been successfully built the Conf/tools_def= .txt will need to be updated so the ASL compiler can be used. + +Find the following statement in Conf/tools_def.txt and comment the line ou= t: + +
+DEFINE UNIX_IASL_BIN           =3D /usr/bin/iasl
+
+ +Next, find the following statement and uncomment the line: + +
+DEFINE UNIX_IASL_BIN           =3D $(HOME)/programs/iasl
+
+ +=3D=3D=3DBuild [http://www.tianocore.org/ovmf/ OVMF]=3D=3D=3D + +Once your build environment is set up you might be interested in building = the [http://www.tianocore.org/ovmf/ OVMF] platform which is included in the= main edk2 source tree. Since [http://www.tianocore.org/ovmf/ OVMF] builds= a full system firmware image this may be of interest to UEFI system firmwa= re developers. diff --git a/Common-instructions.mediawiki b/Common-instructions.mediawiki index 6e752e5699db..956813cda163 100644 --- a/Common-instructions.mediawiki +++ b/Common-instructions.mediawiki @@ -1,103 +1,108 @@ -__NOTOC__ -=3DCommon EDK II Build Instructions for Linux=3D - -These instructions assume you have installed Linux packages required for a= n [[EDK II]] build environment, including git (example: [https://github.com= /tianocore/tianocore.github.io/wiki/Using-EDK-II-with-Native-GCC#Ubuntu_160= 4_LTS__Ubuntu_1610|Ubuntu 16.04/16.10]). The following instructions are com= mon to the majority of Linux environments. - -=3D=3D=3DGet the edk2 source tree using Git =3D=3D=3D - -
-bash$ mkdir ~/src
-bash$ cd ~/src
-bash$ git clone https://github.com/tianocore/edk2
-
- -Note: the 'git clone' command above pulls the latest code from edk2. If yo= u want to work from a stable release, specify a release tag when cloning. E= xample: - -
-bash$ git clone https://github.com/tianocore/edk2.git vUDK2017
-
- -=3D=3D=3DInitialize submodules=3D=3D=3D - -
-bash$ git submodule update --init
-
- -=3D=3D=3DCompile build tools =3D=3D=3D - -
-bash$ cd ~/src/edk2
-bash$ make -C BaseTools
-bash$ . edksetup.sh
-
- -When the above steps are done, you can work in the edk2 directory for code= development. - -=3D=3D=3DBuild the EDK II BaseTools=3D=3D=3D - -
-bash$ make -C edk2/BaseTools
-
- -=3D=3D=3DSetup build shell environment=3D=3D=3D - -
-bash$ cd ~/src/edk2
-bash$ export EDK_TOOLS_PATH=3D$HOME/src/edk2/BaseTools
-bash$ . edksetup.sh BaseTools
-
- -=3D=3D=3DModify Conf Files=3D=3D=3D - -Running edksetup.sh populates the edk2/Conf dire= ctory with default configuration files. You will need to edit the Con= f/target.txt file to set the build platform, target architecture, to= ol chain, and multi-threading options. The example below is based on buildi= ng the MdeModulePkg using GCC5. - -=3D=3D=3D=3DSet Build Target Information=3D=3D=3D=3D - -For the Conf/target.txt file, find the following lines: - -
-ACTIVE_PLATFORM       =3D Nt32Pkg/Nt32Pkg.dsc
-TOOL_CHAIN_TAG        =3D MYTOOLS
-
- -And change the corresponding lines to match these: - -
-ACTIVE_PLATFORM       =3D MdeModulePkg/MdeModulePkg.dsc
-TOOL_CHAIN_TAG        =3D GCC5
-
- -:Note: The gcc --version command can be used to find out your= GCC version. Use the '''GCC45''' toolchain for gcc 4.5.* and the '''GCC46= ''' toolchain for gcc 4.6.*. - -:Note: for GCC5 please install the gcc-5 package. Example for Ubuntu: sudo apt-get install gcc-5 - -Locate the TARGET_ARCH setting: - -
-TARGET_ARCH           =3D IA32
-
- -Change this reflect the build architecture for the final UEFI binary. - -:Example: X64, IA32 X64 (which will build both a= rchitectures). - -Optional: enable multi-threaded build. The default value for MAX_CON= CURRENT_THREAD_NUMBER is 1, which disables multi-threaded build. Cha= nge this value based on your system's multi-threading capabilities. The for= mula is '1 + (2 x processor threads)'. - -:Example: for an Intel Core i5 (two processor cores w/ hyperthreading), th= e value is 9. - -=3D=3D=3DBuild Hello World! (and the rest of MdeModulePkg)=3D=3D=3D - -Now you should be able to simply run the build command to compile Md= eModulePkg. - -
-bash$ build
-
- -One result of the build is that you should have the HelloWorld UEFI applic= ation: -
-bash$ ls Build/MdeModule/DEBUG_*/*/HelloWorld.efi
-
- -=3D=3D=3DBuild [[OVMF]]=3D=3D=3D - -Once your build environment is set up you might be interested in [[How to = build OVMF|building the OVMF platform]] which is included in the main [[EDK= II]] source tree. Since [[OVMF]] builds a full system firmware image, thi= s may be of interest to UEFI system firmware developers. +__NOTOC__ +=3DCommon EDK II Build Instructions for Linux=3D + + Note: New build instructions are available. It is recommended to start w= ith the new instructions if learning how to + build edk2 for the first time. This page is retained for reference. + +New instructions: [[Build-Instructions.md|Build Instructions]] + +These instructions assume you have installed Linux packages required for a= n [[EDK II]] build environment, including git (example: [https://github.com= /tianocore/tianocore.github.io/wiki/Using-EDK-II-with-Native-GCC#Ubuntu_160= 4_LTS__Ubuntu_1610|Ubuntu 16.04/16.10]). The following instructions are com= mon to the majority of Linux environments. + +=3D=3D=3DGet the edk2 source tree using Git =3D=3D=3D + +
+bash$ mkdir ~/src
+bash$ cd ~/src
+bash$ git clone https://github.com/tianocore/edk2
+
+ +Note: the 'git clone' command above pulls the latest code from edk2. If yo= u want to work from a stable release, specify a release tag when cloning. E= xample: + +
+bash$ git clone https://github.com/tianocore/edk2.git vUDK2017
+
+ +=3D=3D=3DInitialize submodules=3D=3D=3D + +
+bash$ git submodule update --init
+
+ +=3D=3D=3DCompile build tools =3D=3D=3D + +
+bash$ cd ~/src/edk2
+bash$ make -C BaseTools
+bash$ . edksetup.sh
+
+ +When the above steps are done, you can work in the edk2 directory for code= development. + +=3D=3D=3DBuild the EDK II BaseTools=3D=3D=3D + +
+bash$ make -C edk2/BaseTools
+
+ +=3D=3D=3DSetup build shell environment=3D=3D=3D + +
+bash$ cd ~/src/edk2
+bash$ export EDK_TOOLS_PATH=3D$HOME/src/edk2/BaseTools
+bash$ . edksetup.sh BaseTools
+
+ +=3D=3D=3DModify Conf Files=3D=3D=3D + +Running edksetup.sh populates the edk2/Conf dire= ctory with default configuration files. You will need to edit the Con= f/target.txt file to set the build platform, target architecture, to= ol chain, and multi-threading options. The example below is based on buildi= ng the MdeModulePkg using GCC5. + +=3D=3D=3D=3DSet Build Target Information=3D=3D=3D=3D + +For the Conf/target.txt file, find the following lines: + +
+ACTIVE_PLATFORM       =3D Nt32Pkg/Nt32Pkg.dsc
+TOOL_CHAIN_TAG        =3D MYTOOLS
+
+ +And change the corresponding lines to match these: + +
+ACTIVE_PLATFORM       =3D MdeModulePkg/MdeModulePkg.dsc
+TOOL_CHAIN_TAG        =3D GCC5
+
+ +:Note: The gcc --version command can be used to find out your= GCC version. Use the '''GCC45''' toolchain for gcc 4.5.* and the '''GCC46= ''' toolchain for gcc 4.6.*. + +:Note: for GCC5 please install the gcc-5 package. Example for Ubuntu: sudo apt-get install gcc-5 + +Locate the TARGET_ARCH setting: + +
+TARGET_ARCH           =3D IA32
+
+ +Change this reflect the build architecture for the final UEFI binary. + +:Example: X64, IA32 X64 (which will build both a= rchitectures). + +Optional: enable multi-threaded build. The default value for MAX_CON= CURRENT_THREAD_NUMBER is 1, which disables multi-threaded build. Cha= nge this value based on your system's multi-threading capabilities. The for= mula is '1 + (2 x processor threads)'. + +:Example: for an Intel Core i5 (two processor cores w/ hyperthreading), th= e value is 9. + +=3D=3D=3DBuild Hello World! (and the rest of MdeModulePkg)=3D=3D=3D + +Now you should be able to simply run the build command to compile Md= eModulePkg. + +
+bash$ build
+
+ +One result of the build is that you should have the HelloWorld UEFI applic= ation: +
+bash$ ls Build/MdeModule/DEBUG_*/*/HelloWorld.efi
+
+ +=3D=3D=3DBuild [[OVMF]]=3D=3D=3D + +Once your build environment is set up you might be interested in [[How to = build OVMF|building the OVMF platform]] which is included in the main [[EDK= II]] source tree. Since [[OVMF]] builds a full system firmware image, thi= s may be of interest to UEFI system firmware developers. diff --git a/Getting-Started-with-EDK-II.mediawiki b/Getting-Started-with-E= DK-II.mediawiki index f616d1e86e4c..eb6da7dfdc56 100644 --- a/Getting-Started-with-EDK-II.mediawiki +++ b/Getting-Started-with-EDK-II.mediawiki @@ -1,4 +1,10 @@ __NOTOC__ + + Note: New build instructions are available. It is recommended to start w= ith the new instructions if learning how to + build edk2 for the first time. This page is retained for reference. + +New instructions: [[Build-Instructions.md|Build Instructions]] + =3DDownloading and Compiling Code=3D =20 This page shows the steps for downloading [[EDK II]] from GitHub and compi= ling projects under various OS/compiler environments. @@ -15,24 +21,24 @@ Several build environments are supported and documented= . If instructions are no '''Note:''' Some other build tools may be required depending on the projec= t or package: * [[Nasm Setup|Nasm]] * [[ASL Setup|ASL Compiler]] -* Install Python 3.7 or later (https://www.python.org/) to run python too= l from source=20 +* Install Python 3.7 or later (https://www.python.org/) to run python too= l from source ** Python 2.7.10 or later can still be used with PYTHON_HOME =20 -'''Note:''' Some of the examples use the [[Multiple_Workspace]] `PACKAGES_= PATH` feature to the configure EDK II build environment. For example, this = is required for using platform code based on edk2-platforms: (https://githu= b.com/tianocore/edk2-platforms).=20 +'''Note:''' Some of the examples use the [[Multiple_Workspace]] `PACKAGES_= PATH` feature to the configure EDK II build environment. For example, this = is required for using platform code based on edk2-platforms: (https://githu= b.com/tianocore/edk2-platforms). =20 Once you have a basic build environment running, you can build a project i= n RELEASE or [[EDK II Debugging|DEBUG]] mode. =20 =3D=3DGitHub Help=3D=3D =20 -GitHub (https://help.github.com/index.html) provides step-by-step instruct= ions for user registration and basic features supported by GitHub=20 +GitHub (https://help.github.com/index.html) provides step-by-step instruct= ions for user registration and basic features supported by GitHub =20 * Setup GitHub for Linux/Windows/MAC (https://help.github.com/articles/set= -up-git) * Download and install a git GUI interface: git GUI Clients (https://git-s= cm.com/download/gui/win) | TortoiseGit (https://tortoisegit.org/) =20 =3D=3D=3DGitHub EDK II Project Repositories=3D=3D=3D =20 -* The EDK II project repository is available at https://github.com/tianoco= re/edk2.=20 -* Prebuilt Windows tools are available at https://github.com/tianocore/edk= 2-BaseTools-win32.=20 +* The EDK II project repository is available at https://github.com/tianoco= re/edk2. +* Prebuilt Windows tools are available at https://github.com/tianocore/edk= 2-BaseTools-win32. * [[EDK II Platforms]] are available at https://github.com/tianocore/edk2-= platforms. * Content that is not released under an accepted open source license can b= e found at https://github.com/tianocore/edk2-non-osi. =20 diff --git a/UDK2017-How-to-Build.md b/UDK2017-How-to-Build.md index 4eca47f98e21..2f7f80125513 100644 --- a/UDK2017-How-to-Build.md +++ b/UDK2017-How-to-Build.md @@ -1,123 +1,129 @@ -# How to Build [[UDK2017]]=20 -Table of Contents -1) [HOW TO BUILD (WINDOWS SYSTEM)](#how-to-build-windows-system) -2) [ HOW TO BUILD (LINUX-LIKE SYSTEM)](#how-to-build-linux-like-system) - -## HOW TO BUILD (WINDOWS SYSTEM) - -The steps below are verified on Microsoft Windows 10 Enterprise*: - -1. Setup Build Environment - 1) Install Microsoft Visual Studio 2015* in the build machine and make - sure that AMD64 complier was selected when installing. - 2) Download NASM 2.0.7 or later from http://www.nasm.us/ and install = it to - C:\Nasm. Make sure C:\Nasm is added to system environment variable= 'PATH' - 3) Set up for using GitHub for Windows. See: - https://github.com/tianocore/tianocore.github.io/wiki/Getting-Started-= with-EDK-II#github-help - 4) Download and install Python2.7.x https://www.python.org/ for buil= ding the BaseTools - Default install directory is: C:/Python27 - -2. Create the full Source Code directory for the UDK2017 release - 1) Create a working space directory in the build machine, for example= , C:\MyWorkspace - 2) Download the official UDK2017 release .zip file from the [UDK2017 = Release Page](https://github.com/tianocore/edk2/releases/tag/vUDK2017) - 1) Download - UDK2017 edk-vUDK2017 Workspace [Source code (zip fil= e)](https://github.com/tianocore/edk2/archive/vUDK2017.zip)=20 - 2) Extract files in [edk2-vUDK2017] to the working space directory= C:\MyWorkspace. - 3) **OR** Checkout the vUDK2017 Tag from GitHub with the following "g= it" command
- 1) run `git clone https://github.com/tianocore/edk2.git vUDK2017` - 2) Move all files and folders under "vUDK2017" to "C:\MyWorkspace" - 4) **Optional** (See _Compile the BaseTools_ below) Checkout BaseTool= s binaries and copy them to BaseTools binary folder. Warning the Windows* = Binary tools are only valid for the tip of the https://github.com/tianocor= e/edk2 repository. - 1) `Cd C:\MyWorkspace` - 2) Run `git clone https://github.com/tianocore/edk2-BaseTools-wi= n32.git` - 3) Enter folder edk2-BaseTools-win32 - 4) Run the command `git checkout 0e088c19ab31fccd1d2f55d9e4fe031= 4b57c0097` - 5) `Cd C:\MyWorkSpace` - 6) Rename this folder from edk2-BaseTools-win32 to win32, then c= opy the win32 - directory into the BaseTools/Bin directory under the workspace.=20 - (e.g. "C:\MyWorkspace\BaseTools\Bin\") =20 -3. Generate OpenSSL* Crypto Library - 1) Open file "C:\MyWorkspace\CryptoPkg\Library\OpensslLib\OpenSSL-HOW= TO.txt" - and follow the instruction to install OpenSSL* for UEFI building. - For this release, please use OpenSSL-1.1.0e. - -4. Compile the BaseTools (Skip if Optional Step 2.iv was done above) See:=20 - https://github.com/tianocore/tianocore.github.io/wiki/Windows-systems= #compile-tools - 1) Open a Microsoft Visual Studio* command prompt, type `cd C:\MyWork= space` - to enter the workspace directory - 2) Compile the BaseTools C source tools =20 -
-	set PYTHON_HOME=3DC:\Python27
-        set EDK_TOOLS_PATH=3D%CD%\BaseTools
-        BaseTools\toolssetup.bat Rebuild
-
- -5. Build Steps - *** NT32 *** - - 1) Open a Microsoft Visual Studio* command prompt, type `cd C:\MyWork= space` - to enter the workspace directory - 2) Use edksetup.bat command to initialize the working environment. - `edksetup --nt32` - 3) Type following command to build Nt32 platform - `build -t VS2015x86` - 4) Upon the build completing successfully there should be the UEFI Ap= plication "`HelloWorld.efi`" in the C:\MyWorkspace\Build\MdeModule\DEBUG_V= S2015x86\IA32 directory - - ---- - -## HOW TO BUILD (LINUX-LIKE SYSTEM) -The below steps are verified on Ubuntu 16.04 LTS Desktop*: - -1. Setup Build Environment - 1) Follow instructions for setting up the build environment on tianoc= ore.org. - "https://github.com/tianocore/tianocore.github.io/wiki/Using-EDK-I= I-with-Native-GCC" - 2) Please notice that here the root is `"~/src/MyWorkspace"` instead - of `"~/src/edk2"` - 3) Make sure BaseTools is built and required software like iASL com= piler - are installed. Some operations need switch to user "root" to ex= ecute. - At Ubuntu, you can type `"sudo apt-get install git"` under termin= al prompt "Cnt-Alt-T" to - install git. - 2) Install NASM 2.0.7 or later. - At Ubuntu, you can type `"sudo apt-get install nasm"` under termin= al prompt to - install it. - You can also download the source package from http://www.nasm.us/ = and - install it following the instruction on the website. - 3) Install IASL 20150818 or later. - At Ubuntu, you can type `"sudo apt-get install iasl"` under termin= al prompt to - install it. - You can also download the source package from https://acpica.org/d= ownloads - and install it following the instruction on the website. - 4) Install the C Compiler- Ubuntu 16.04 LTS you can use GNU C compil= er (v5.4.0)=20 - At Ubuntu, you can type `"sudo apt-get install gcc-5"` under termi= nal prompt to install it. - - -2. Create the full Source Code directory for the UDK2017 release - 1) Create a working space directory in the build machine, for example= , ~/src/MyWorkspace - 2) Download the official UDK2017 release .tar file from the [UDK2017 = Release Page](https://github.com/tianocore/edk2/releases/tag/vUDK2017) - 1) Download - UDK2017 edk-vUDK2017 Workspace [Source code (tar.gz = file)](https://github.com/tianocore/edk2/archive/vUDK2017.tar.gz)=20 - 2) Extract files in [edk2-vUDK2017] to the working space directory= ~/src/MyWorkspace. - 3) **OR** Checkout the vUDK2017 tag from GitHub with the following "g= it" command=20 - 1) Run `"git clone https://github.com/tianocore/edk2.git vUDK2017= "` - 2) Move all files and folders under "vUDK2017" to "~/src/MyWorksp= ace" - =20 -3. Generate OpenSSL* Crypto Library - 1) Open file "~/src/MyWorkspace/CryptoPkg/Library/OpensslLib/OpenSSL-= HOWTO.txt" - and follow the instruction to install OpenSSL* for UEFI building. - For this release, please use OpenSSL-1.1.0e. - -4. Build Steps - *** MdeModulePkg *** - 1) Open a terminal and type `"cd ~/src/MyWorkspace"` to enter the wor= kspace - directory. - 2) First build the BaseTools by typing=20 - `"make -C BaseTools"` - 3) Initialize the build environment by typing=20 - `". edksetup.sh"`. - 4) Type following command to build platforms using GCC v5.4.0
- `"build -p MdeModulePkg/MdeModulePkg.dsc -t GCC5"` - 5) Upon the build completing successfully there should be the UEFI Ap= plication "`HelloWorld.efi`" in the ~/src/MyWorkspace/Build/MdeModule/DEBU= G_GCC5/IA32 directory -*** - -If you have questions please email the [[edk2-devel]] mail list. - -See also [[Getting Started with EDK II]] - +# How to Build [[UDK2017]] + +> Note: New build instructions are available. It is recommended to start w= ith the new instructions if learning how to +> build edk2 for the first time and not specifically targeting UDK2017. Th= is page is retained for reference. + +New instructions: [Build Instructions](Build-Instructions.md) + +Table of Contents +1) [HOW TO BUILD (WINDOWS SYSTEM)](#how-to-build-windows-system) +2) [ HOW TO BUILD (LINUX-LIKE SYSTEM)](#how-to-build-linux-like-system) + +## HOW TO BUILD (WINDOWS SYSTEM) + +The steps below are verified on Microsoft Windows 10 Enterprise*: + +1. Setup Build Environment + 1) Install Microsoft Visual Studio 2015* in the build machine and make + sure that AMD64 complier was selected when installing. + 2) Download NASM 2.0.7 or later from http://www.nasm.us/ and install = it to + C:\Nasm. Make sure C:\Nasm is added to system environment variable= 'PATH' + 3) Set up for using GitHub for Windows. See: + https://github.com/tianocore/tianocore.github.io/wiki/Getting-Started-= with-EDK-II#github-help + 4) Download and install Python2.7.x https://www.python.org/ for buil= ding the BaseTools + Default install directory is: C:/Python27 + +2. Create the full Source Code directory for the UDK2017 release + 1) Create a working space directory in the build machine, for example= , C:\MyWorkspace + 2) Download the official UDK2017 release .zip file from the [UDK2017 = Release Page](https://github.com/tianocore/edk2/releases/tag/vUDK2017) + 1) Download - UDK2017 edk-vUDK2017 Workspace [Source code (zip fil= e)](https://github.com/tianocore/edk2/archive/vUDK2017.zip) + 2) Extract files in [edk2-vUDK2017] to the working space directory= C:\MyWorkspace. + 3) **OR** Checkout the vUDK2017 Tag from GitHub with the following "g= it" command
+ 1) run `git clone https://github.com/tianocore/edk2.git vUDK2017` + 2) Move all files and folders under "vUDK2017" to "C:\MyWorkspace" + 4) **Optional** (See _Compile the BaseTools_ below) Checkout BaseTool= s binaries and copy them to BaseTools binary folder. Warning the Windows* = Binary tools are only valid for the tip of the https://github.com/tianocor= e/edk2 repository. + 1) `Cd C:\MyWorkspace` + 2) Run `git clone https://github.com/tianocore/edk2-BaseTools-wi= n32.git` + 3) Enter folder edk2-BaseTools-win32 + 4) Run the command `git checkout 0e088c19ab31fccd1d2f55d9e4fe031= 4b57c0097` + 5) `Cd C:\MyWorkSpace` + 6) Rename this folder from edk2-BaseTools-win32 to win32, then c= opy the win32 + directory into the BaseTools/Bin directory under the workspace. + (e.g. "C:\MyWorkspace\BaseTools\Bin\") +3. Generate OpenSSL* Crypto Library + 1) Open file "C:\MyWorkspace\CryptoPkg\Library\OpensslLib\OpenSSL-HOW= TO.txt" + and follow the instruction to install OpenSSL* for UEFI building. + For this release, please use OpenSSL-1.1.0e. + +4. Compile the BaseTools (Skip if Optional Step 2.iv was done above) See: + https://github.com/tianocore/tianocore.github.io/wiki/Windows-systems= #compile-tools + 1) Open a Microsoft Visual Studio* command prompt, type `cd C:\MyWork= space` + to enter the workspace directory + 2) Compile the BaseTools C source tools +
+	set PYTHON_HOME=3DC:\Python27
+        set EDK_TOOLS_PATH=3D%CD%\BaseTools
+        BaseTools\toolssetup.bat Rebuild
+
+ +5. Build Steps + *** NT32 *** + + 1) Open a Microsoft Visual Studio* command prompt, type `cd C:\MyWork= space` + to enter the workspace directory + 2) Use edksetup.bat command to initialize the working environment. + `edksetup --nt32` + 3) Type following command to build Nt32 platform + `build -t VS2015x86` + 4) Upon the build completing successfully there should be the UEFI Ap= plication "`HelloWorld.efi`" in the C:\MyWorkspace\Build\MdeModule\DEBUG_V= S2015x86\IA32 directory + + +--- + +## HOW TO BUILD (LINUX-LIKE SYSTEM) +The below steps are verified on Ubuntu 16.04 LTS Desktop*: + +1. Setup Build Environment + 1) Follow instructions for setting up the build environment on tianoc= ore.org. + "https://github.com/tianocore/tianocore.github.io/wiki/Using-EDK-I= I-with-Native-GCC" + 2) Please notice that here the root is `"~/src/MyWorkspace"` instead + of `"~/src/edk2"` + 3) Make sure BaseTools is built and required software like iASL com= piler + are installed. Some operations need switch to user "root" to ex= ecute. + At Ubuntu, you can type `"sudo apt-get install git"` under termin= al prompt "Cnt-Alt-T" to + install git. + 2) Install NASM 2.0.7 or later. + At Ubuntu, you can type `"sudo apt-get install nasm"` under termin= al prompt to + install it. + You can also download the source package from http://www.nasm.us/ = and + install it following the instruction on the website. + 3) Install IASL 20150818 or later. + At Ubuntu, you can type `"sudo apt-get install iasl"` under termin= al prompt to + install it. + You can also download the source package from https://acpica.org/d= ownloads + and install it following the instruction on the website. + 4) Install the C Compiler- Ubuntu 16.04 LTS you can use GNU C compil= er (v5.4.0) + At Ubuntu, you can type `"sudo apt-get install gcc-5"` under termi= nal prompt to install it. + + +2. Create the full Source Code directory for the UDK2017 release + 1) Create a working space directory in the build machine, for example= , ~/src/MyWorkspace + 2) Download the official UDK2017 release .tar file from the [UDK2017 = Release Page](https://github.com/tianocore/edk2/releases/tag/vUDK2017) + 1) Download - UDK2017 edk-vUDK2017 Workspace [Source code (tar.gz = file)](https://github.com/tianocore/edk2/archive/vUDK2017.tar.gz) + 2) Extract files in [edk2-vUDK2017] to the working space directory= ~/src/MyWorkspace. + 3) **OR** Checkout the vUDK2017 tag from GitHub with the following "g= it" command + 1) Run `"git clone https://github.com/tianocore/edk2.git vUDK2017= "` + 2) Move all files and folders under "vUDK2017" to "~/src/MyWorksp= ace" + +3. Generate OpenSSL* Crypto Library + 1) Open file "~/src/MyWorkspace/CryptoPkg/Library/OpensslLib/OpenSSL-= HOWTO.txt" + and follow the instruction to install OpenSSL* for UEFI building. + For this release, please use OpenSSL-1.1.0e. + +4. Build Steps + *** MdeModulePkg *** + 1) Open a terminal and type `"cd ~/src/MyWorkspace"` to enter the wor= kspace + directory. + 2) First build the BaseTools by typing + `"make -C BaseTools"` + 3) Initialize the build environment by typing + `". edksetup.sh"`. + 4) Type following command to build platforms using GCC v5.4.0
+ `"build -p MdeModulePkg/MdeModulePkg.dsc -t GCC5"` + 5) Upon the build completing successfully there should be the UEFI Ap= plication "`HelloWorld.efi`" in the ~/src/MyWorkspace/Build/MdeModule/DEBU= G_GCC5/IA32 directory +*** + +If you have questions please email the [[edk2-devel]] mail list. + +See also [[Getting Started with EDK II]] + diff --git a/UDK2018-How-to-Build.md b/UDK2018-How-to-Build.md index b981b2162cc4..06a963a8e1e2 100644 --- a/UDK2018-How-to-Build.md +++ b/UDK2018-How-to-Build.md @@ -1,128 +1,134 @@ -# How to Build [[UDK2018]]=20 -Table of Contents -1) [HOW TO BUILD (WINDOWS SYSTEM)](#how-to-build-windows-system) -2) [ HOW TO BUILD (LINUX-LIKE SYSTEM)](#how-to-build-linux-like-system) - -## HOW TO BUILD (WINDOWS SYSTEM) - -The steps below are verified on Microsoft Windows 10 Enterprise*: - -1. Setup Build Environment - 1) Install Microsoft Visual Studio 2015* in the build machine and make - sure that AMD64 complier was selected when installing. - 2) Download NASM 2.12.01 or later from http://www.nasm.us/ and instal= l it to - C:\Nasm. Make sure C:\Nasm is added to system environment variable= 'PATH' - 3) Set up for using GitHub for Windows. See: - https://github.com/tianocore/tianocore.github.io/wiki/Getting-Started-= with-EDK-II#github-help - 4) Download and install Python2.7.x https://www.python.org/ for buil= ding the BaseTools - Default install directory is: C:/Python27 - 5) Download the pre-compiled Openssl binary from https://wiki.openssl= .org/index.php/Binaries. Search for a - Windows binary in the list of "_Third Party OpenSSL Related Binary= Distributions_" table that will be=20 - Windows binary. Go to the third party site to download the latest = version of Windows x64 86 or Win32 binary. - Download and extract to C:\Openssl. Make sure C:\Openssl is added = to system environment=20 - variable 'PATH'.=20 - -2. Create the full Source Code directory for the UDK2018 release - 1) Create a working space directory in the build machine, for example= , C:\MyWorkspace - 2) Download the official UDK2018 release .zip file from the [UDK2018 = Release Page](https://github.com/tianocore/edk2/releases/tag/vUDK2018) - 1) Download - UDK2018 edk-vUDK2018 Workspace [Source code (zip fil= e)](https://github.com/tianocore/edk2/archive/vUDK2018.zip)=20 - 2) Extract files in [edk2-vUDK2018] to the working space directory= C:\MyWorkspace. - 3) **OR** Checkout the vUDK2018 Tag from GitHub with the following "g= it" command
- 1) run `git clone https://github.com/tianocore/edk2.git vUDK201= 8` - 2) Go to the vUDK2018 directory, and from there run: `git checkou= t tags/vUDK2018 -b vUDK2018` - 3) Move all files and folders under "vUDK2018" to "C:\MyWorkspace" - -3. Generate OpenSSL* Crypto Library - 1) Open file "C:\MyWorkspace\CryptoPkg\Library\OpensslLib\OpenSSL-HOW= TO.txt" - and follow the instruction to install OpenSSL* for UEFI building. - For this release, please use OpenSSL-1.1.0g. Download it from=20 - https://github.com/openssl/openssl/archive/OpenSSL_1_1_0g.zip - Extract it to C:\MyWorkspace\CryptoPkg\Library\OpensslLib, - and rename its directory name to openssl - -4. Compile the BaseTools See:=20 - https://github.com/tianocore/tianocore.github.io/wiki/Windows-systems= #compile-tools - 1) Open a Microsoft Visual Studio* command prompt, type `cd C:\MyWork= space` - to enter the workspace directory - 2) Compile the BaseTools C source tools =20 -
-	set PYTHON_HOME=3DC:\Python27
-        edksetup.bat Rebuild
-
- -5. Build Steps - *** NT32 *** - - 1) Open a Microsoft Visual Studio* command prompt, type `cd C:\MyWork= space` - to enter the workspace directory - 2) Use edksetup.bat command to initialize the working environment. - `edksetup --nt32` - 3) Type following command to build Nt32 platform - `build -t VS2015x86` - 4) Upon the build completing successfully there should be the UEFI Ap= plication "`HelloWorld.efi`" in the C:\MyWorkspace\Build\NT32IA32\DEBUG_VS= 2015x86\IA32 directory - - ---- - -## HOW TO BUILD (LINUX-LIKE SYSTEM) -The below steps are verified on Ubuntu 16.04 LTS Desktop*: - -1. Setup Build Environment - 1) Follow instructions for setting up the build environment on tianoc= ore.org. - "https://github.com/tianocore/tianocore.github.io/wiki/Using-EDK-I= I-with-Native-GCC" - - 2) Please notice that here the root is `"~/src/MyWorkspace`" inste= ad - of `"~/src/edk2"` - - 3) Make sure BaseTools is built and required software like iASL co= mpiler - is installed well. - a) Some operations need switch to user "root" to execute. - b) At Ubuntu, you can type `"sudo apt-get install git"` under = terminal "Cnt-Alt-T" to - install git. - 2) Install NASM 2.12.01 or later. - At Ubuntu, you can type "sudo apt-get install nasm" under terminal= to - install it. - You can also download the source package from http://www.nasm.us/ = and - install it following the instruction on the website. - 3) Install IASL 20150818 or later. - At Ubuntu, you can type `"sudo apt-get install iasl"` under termin= al to - install it. - You can also download the source package from https://acpica.org/d= ownloads - and install it following the instruction on the website. - -2. Create the full Source Code directory for the UDK2018 release - 1) Create a working space directory in the build machine, for example= , ~/src/MyWorkspace - 2) Download the official UDK2018 release .tar file from the [UDK2018 = Release Page](https://github.com/tianocore/edk2/releases/tag/vUDK2018) - 1) Download - UDK2018 edk-vUDK2018 Workspace [Source code (tar.gz = file)](https://github.com/tianocore/edk2/archive/vUDK2018.tar.gz)=20 - 2) Extract files in [edk2-vUDK2018] to the working space directory= ~/src/MyWorkspace. - 3) **OR** Checkout the vUDK2018 tag from GitHub with the following "g= it" command=20 - 1) Run `"git clone https://github.com/tianocore/edk2.git vUDK2018= "` - 2) Go to the vUDK2018 directory, and from there run: `git checkou= t tags/vUDK2018 -b vUDK2018` - 3) Move all files and folders under "vUDK2018" to "~/src/MyWorksp= ace" - =20 -3. Generate OpenSSL* Crypto Library - 1) Open file "~/src/MyWorkspace/CryptoPkg/Library/OpensslLib/OpenSSL-= HOWTO.txt" - and follow the instruction to install OpenSSL* for UEFI building. - For this release, please use OpenSSL-1.1.0g. Download it fro= m=20 - https://github.com/openssl/openssl/archive/OpenSSL_1_1_0g.zip - Extract it to ~/src/MyWorkspace/CryptoPkg/Library/OpensslLib, - and rename its directory name to openssl - - -4. Build Steps - *** MdeModulePkg *** - 1) Open a terminal and type `"cd ~/src/MyWorkspace"` to enter the wor= kspace - directory. - 2) First build the BaseTools by typing=20 - `"make -C BaseTools"` - 3) Initialize the build environment by typing=20 - `". edksetup.sh"`. - 4) Type following command to build platforms using GCC v5.4.0
- `"build -p MdeModulePkg/MdeModulePkg.dsc -t GCC5"` - 5) Upon the build completing successfully there should be the UEFI Ap= plication "`HelloWorld.efi`" in the ~/src/MyWorkspace/Build/MdeModule/DEBU= G_GCC5/IA32 directory -*** - -If you have questions please email the [[edk2-devel]] mail list. - -See also [[Getting Started with EDK II]] - +# How to Build [[UDK2018]] + +> Note: New build instructions are available. It is recommended to start w= ith the new instructions if learning how to +> build edk2 for the first time and not specifically targeting UDK2018. Th= is page is retained for reference. + +New instructions: [Build Instructions](Build-Instructions.md) + +Table of Contents +1) [HOW TO BUILD (WINDOWS SYSTEM)](#how-to-build-windows-system) +2) [ HOW TO BUILD (LINUX-LIKE SYSTEM)](#how-to-build-linux-like-system) + +## HOW TO BUILD (WINDOWS SYSTEM) + +The steps below are verified on Microsoft Windows 10 Enterprise*: + +1. Setup Build Environment + 1) Install Microsoft Visual Studio 2015* in the build machine and make + sure that AMD64 complier was selected when installing. + 2) Download NASM 2.12.01 or later from http://www.nasm.us/ and instal= l it to + C:\Nasm. Make sure C:\Nasm is added to system environment variable= 'PATH' + 3) Set up for using GitHub for Windows. See: + https://github.com/tianocore/tianocore.github.io/wiki/Getting-Started-= with-EDK-II#github-help + 4) Download and install Python2.7.x https://www.python.org/ for buil= ding the BaseTools + Default install directory is: C:/Python27 + 5) Download the pre-compiled Openssl binary from https://wiki.openssl= .org/index.php/Binaries. Search for a + Windows binary in the list of "_Third Party OpenSSL Related Binary= Distributions_" table that will be + Windows binary. Go to the third party site to download the latest = version of Windows x64 86 or Win32 binary. + Download and extract to C:\Openssl. Make sure C:\Openssl is added = to system environment + variable 'PATH'. + +2. Create the full Source Code directory for the UDK2018 release + 1) Create a working space directory in the build machine, for example= , C:\MyWorkspace + 2) Download the official UDK2018 release .zip file from the [UDK2018 = Release Page](https://github.com/tianocore/edk2/releases/tag/vUDK2018) + 1) Download - UDK2018 edk-vUDK2018 Workspace [Source code (zip fil= e)](https://github.com/tianocore/edk2/archive/vUDK2018.zip) + 2) Extract files in [edk2-vUDK2018] to the working space directory= C:\MyWorkspace. + 3) **OR** Checkout the vUDK2018 Tag from GitHub with the following "g= it" command
+ 1) run `git clone https://github.com/tianocore/edk2.git vUDK201= 8` + 2) Go to the vUDK2018 directory, and from there run: `git checkou= t tags/vUDK2018 -b vUDK2018` + 3) Move all files and folders under "vUDK2018" to "C:\MyWorkspace" + +3. Generate OpenSSL* Crypto Library + 1) Open file "C:\MyWorkspace\CryptoPkg\Library\OpensslLib\OpenSSL-HOW= TO.txt" + and follow the instruction to install OpenSSL* for UEFI building. + For this release, please use OpenSSL-1.1.0g. Download it from + https://github.com/openssl/openssl/archive/OpenSSL_1_1_0g.zip + Extract it to C:\MyWorkspace\CryptoPkg\Library\OpensslLib, + and rename its directory name to openssl + +4. Compile the BaseTools See: + https://github.com/tianocore/tianocore.github.io/wiki/Windows-systems= #compile-tools + 1) Open a Microsoft Visual Studio* command prompt, type `cd C:\MyWork= space` + to enter the workspace directory + 2) Compile the BaseTools C source tools +
+	set PYTHON_HOME=3DC:\Python27
+        edksetup.bat Rebuild
+
+ +5. Build Steps + *** NT32 *** + + 1) Open a Microsoft Visual Studio* command prompt, type `cd C:\MyWork= space` + to enter the workspace directory + 2) Use edksetup.bat command to initialize the working environment. + `edksetup --nt32` + 3) Type following command to build Nt32 platform + `build -t VS2015x86` + 4) Upon the build completing successfully there should be the UEFI Ap= plication "`HelloWorld.efi`" in the C:\MyWorkspace\Build\NT32IA32\DEBUG_VS= 2015x86\IA32 directory + + +--- + +## HOW TO BUILD (LINUX-LIKE SYSTEM) +The below steps are verified on Ubuntu 16.04 LTS Desktop*: + +1. Setup Build Environment + 1) Follow instructions for setting up the build environment on tianoc= ore.org. + "https://github.com/tianocore/tianocore.github.io/wiki/Using-EDK-I= I-with-Native-GCC" + + 2) Please notice that here the root is `"~/src/MyWorkspace`" inste= ad + of `"~/src/edk2"` + + 3) Make sure BaseTools is built and required software like iASL co= mpiler + is installed well. + a) Some operations need switch to user "root" to execute. + b) At Ubuntu, you can type `"sudo apt-get install git"` under = terminal "Cnt-Alt-T" to + install git. + 2) Install NASM 2.12.01 or later. + At Ubuntu, you can type "sudo apt-get install nasm" under terminal= to + install it. + You can also download the source package from http://www.nasm.us/ = and + install it following the instruction on the website. + 3) Install IASL 20150818 or later. + At Ubuntu, you can type `"sudo apt-get install iasl"` under termin= al to + install it. + You can also download the source package from https://acpica.org/d= ownloads + and install it following the instruction on the website. + +2. Create the full Source Code directory for the UDK2018 release + 1) Create a working space directory in the build machine, for example= , ~/src/MyWorkspace + 2) Download the official UDK2018 release .tar file from the [UDK2018 = Release Page](https://github.com/tianocore/edk2/releases/tag/vUDK2018) + 1) Download - UDK2018 edk-vUDK2018 Workspace [Source code (tar.gz = file)](https://github.com/tianocore/edk2/archive/vUDK2018.tar.gz) + 2) Extract files in [edk2-vUDK2018] to the working space directory= ~/src/MyWorkspace. + 3) **OR** Checkout the vUDK2018 tag from GitHub with the following "g= it" command + 1) Run `"git clone https://github.com/tianocore/edk2.git vUDK2018= "` + 2) Go to the vUDK2018 directory, and from there run: `git checkou= t tags/vUDK2018 -b vUDK2018` + 3) Move all files and folders under "vUDK2018" to "~/src/MyWorksp= ace" + +3. Generate OpenSSL* Crypto Library + 1) Open file "~/src/MyWorkspace/CryptoPkg/Library/OpensslLib/OpenSSL-= HOWTO.txt" + and follow the instruction to install OpenSSL* for UEFI building. + For this release, please use OpenSSL-1.1.0g. Download it from + https://github.com/openssl/openssl/archive/OpenSSL_1_1_0g.zip + Extract it to ~/src/MyWorkspace/CryptoPkg/Library/OpensslLib, + and rename its directory name to openssl + + +4. Build Steps + *** MdeModulePkg *** + 1) Open a terminal and type `"cd ~/src/MyWorkspace"` to enter the wor= kspace + directory. + 2) First build the BaseTools by typing + `"make -C BaseTools"` + 3) Initialize the build environment by typing + `". edksetup.sh"`. + 4) Type following command to build platforms using GCC v5.4.0
+ `"build -p MdeModulePkg/MdeModulePkg.dsc -t GCC5"` + 5) Upon the build completing successfully there should be the UEFI Ap= plication "`HelloWorld.efi`" in the ~/src/MyWorkspace/Build/MdeModule/DEBU= G_GCC5/IA32 directory +*** + +If you have questions please email the [[edk2-devel]] mail list. + +See also [[Getting Started with EDK II]] + diff --git a/Unix-like-systems.mediawiki b/Unix-like-systems.mediawiki index 36fd1a2b1299..1d037b51513a 100644 --- a/Unix-like-systems.mediawiki +++ b/Unix-like-systems.mediawiki @@ -1,210 +1,215 @@ -This page provides ''step-by-step instructions'' for setting up a [http://= www.tianocore.org/edk2/ EDK II] build environment on various Unix-like syst= ems. - -'''Note''': These instructions are not recommended for most EDK II develop= ers. If you are working with a supported Linux distribution, then the [[Usi= ng EDK II with Native GCC]] instructions are faster, easier, and produce a = smaller UEFI binary image. - -=3D=3DGetting started for UNIX-like operating systems=3D=3D - -These instructions will be written as a series of commands executed from a= command terminal. - -Often these instructions will contain a command which needs to be executed= in the terminal window. For example: - -
-bash$ echo this bold text is a sample command
-
- -To execute this command, highlight the bold text of the command in your we= b browser. Most web browsers should be able to copy the text by selecting = Copy under the Edit menu. Now, change back to the terminal application, an= d there should be a Paste operation under the Edit menu. After pasting the= command into the shell, you may need to press the enter or return key to e= xecute the command.=20 - -Of course, there may be other ways to copy and paste the command into the = terminal which are specific to the windowing environment and applications t= hat you are using. If all else fails, however, you can type the command by= hand. - -Some commands are very long, and we use the backslash character (\) to tel= l the shell program that the command is not finished. For example: - -
-bash$ echo this bold text is a sample command \
-        which is broken into two lines
-
- -When you copy and paste, make sure you include all lines of the command (i= ncluding the backslash (\) characters). If you are typing the command, you= can remove the backslash character (\) and combine the lines into a single= line if you prefer. - -If a command starts with the sudo command, then you may be prompted for yo= ur user password. This will be the same password as you used to login to t= he system. - -For the purposes of this set of instructions, we will be using the followi= ng paths. -{| -|Edk2 source tree: || ~/src/edk2 -|- -|GCC X64 cross-compiler installation: || ~/programs/gcc/x64 -|- -|GCC IA32 cross-compiler installation: || ~/programs/gcc/ia32 -|- -|Intel ASL Compiler installation: || ~/src/acpica-unix-20090521/compiler/i= asl (symlink to compiler at ~/programs/iasl) -|} - -You will need to change the commands if you want to use different location= s, but this is not recommended unless you are sure that you know what you a= re doing. - -=3D=3D=3DInternet proxies=3D=3D=3D - -If your network utilizes a firewall with a web proxy, then you may need to= configure your proxy information for various command line applications to = work. You may need to consult with your network administrator to find out = the computer name and port to use for proxy setup. The following commands = are common examples of how you would configure your proxy by setting an env= ironment variable: - -
-bash$ export http_proxy=3Dhttp://proxy.domain.com:proxy_port
-bash$ export ftp_proxy=3D$http_proxy
-
- -To utilize the subversion source control command behind an internet firewa= ll with a web proxy, you should configure the ~/.subversion/servers file. - -=3D=3D Cygwin 1.7.1 =3D=3D -Notes: -* Cygwin is not officially supported or tested by the edk2 project at this= time. -* Building of [http://www.tianocore.org/edk2/ EDK II] components will be d= one using bash. -Prerequisites: -* Cygwin 1.7.1 is currently installed on the system. -* Cygwin 1.7.1 setup.exe is available on the system to install additional = packages as needed. - -Run Cygwin setup.exe and install the following additional packages. -* bison -* flex -* libgmp-devel -* libiconv -* libmpfr-devel -* gcc (use the compiler upgrade helper option under Devel) -* make -* python -* subversion -* wget -* libuuid-devel -* util-linux (for uuidgen) - -When pulling source files using subversion you may choose to get them to a= more Windows friendly location. All system drives are mapped under /cygdr= ive when using CYGWIN and bash (ie. C:\ maps to /cygdrive/c). This allows = you to substitute ~/src/edk2 for an alternate path such as /cygdrive/c/src/= edk2 so files can be access at C:\src\edk2 as well. - - -Continue with common instructions for Unix - - -The [[Common instructions for Unix|remaining instructions]] are common for= most UNIX-like systems. - -=3D=3DFedora 11=3D=3D -Please note: -* Fedora 11 is not officially supported or tested by the edk2 project at t= his time. -* These instructions assume that the Software Development option was enabl= ed during the Fedora installation. - -=3D=3D=3DOpen the GNOME Terminal program=3D=3D=3D - -These instructions will utilize Fedora's built in command shell (bash) via= the GNOME Terminal application. To open the Terminal application, locate = it under the Applications menu and the System Tools sub-menu. - -=3D=3D=3DInstall MPFR library=3D=3D=3D - -The MPFR library must be installed to allow the gcc cross compiler to be b= uilt. - -
-bash$ mkdir ~/src
-bash$ cd ~/src
-bash$ wget http://www.mpfr.org/mpfr-current/mpfr-2.4.1.tar.bz2
-bash$ tar -jxf mpfr-2.4.1.tar.bz2
-bash$ cd mpfr-2.4.1
-bash$ ./configure --prefix=3D/usr
-bash$ make
-
- -To install the library, you must be root. Therefore we use 'su' to become= the root user, for the 'make install' command. - -
-bash$ su
-bash$ make install
-bash$ exit
-
- - -Continue with common instructions for Unix - - -The [[Common instructions for Unix |remaining instructions]] are common fo= r most UNIX-like systems. - -=3D=3DMac OS X 10.5=3D=3D -=3D=3D=3DXcode Tools=3D=3D=3D - -The first step is to install the Apple Xcode development environment: - http://developer.apple.com/tools/xcode - -To install Xcode, you must register as an Apple developer, and download th= e Xcode installation disk image (which is fairly large). These instruction= s were verified with Xcode 3.0. Within the Xcode Tools disk image, only th= e Xcode Tools.mpkg package needs to be installed. - -=3D=3D=3DOpen OS X Terminal program=3D=3D=3D - -Past this point, the remaining instructions will utilize OS X's built in c= ommand shell (bash) via the Terminal application. To open the command term= inal application, open Finder, then press the Cmd-Shift-U key combination. = (This opens the Applications =3D> Utilities folder.) In the Utilities fol= der, you should see the Terminal application. - -=3D=3D=3DGMP & MPFR (if behind a web proxy)=3D=3D=3D - -The gmp and mpfr libraries are needed to build the gcc cross compiler at a= later point in these instructions. Building these libraries on OS X can p= resent some difficulties, so if you are not behind a network firewall, then= consider using the macports project to install these libraries. (see below= ) Be sure to set the http_proxy and ftp_proxy environment variables before= using the 'curl' commands below. - -
-bash$ mkdir ~/src
-bash$ cd ~/src
-bash$ curl --remote-name \
-  ftp://ftp.gnu.org/gnu/gmp/gmp-4.2.2.tar.bz2
-bash$ tar jxvf gmp-4.2.2.tar.bz2
-bash$ cd gmp-4.2.2
-bash$ ./configure --prefix=3D/usr
-bash$ make
-bash$ make check
-bash$ sudo make install
-
- -Note: This might be needed for 64-bit machines if the MPFR configure fails= below. -
-bash$ export CFLAGS=3D"-m64"
-
- -
-bash$ cd ~/src
-bash$ curl --remote-name \
-  http://www.mpfr.org/mpfr-current/mpfr-2.4.1.tar.bz2
-bash$ tar -jxf mpfr-2.4.1.tar.bz2
-bash$ cd mpfr-2.4.1
-bash$ ./configure --prefix=3D/usr
-bash$ make
-bash$ sudo make install
-
- -=3D=3D=3DGMP & MPFR via Macports (if not behind web proxy)=3D=3D=3D - -If you are not behind a network firewall, then the http://www.macports.org= project can greatly simlify the installation of gmp & mpfr. (Macports doe= s not work easily with web proxies at this time.) After installing macports= you should be able to simply run this command at the shell prompt. - -
-bash$ sudo port install gmp mpfr
-
- - -Continue with common instructions for Unix - - -The [[Common instructions for Unix|remaining instructions]] are common for= most UNIX-like systems. - - - - -=3D=3DUbuntu 9.10=3D=3D -Note: The Ubuntu platform is not officially supported or tested by the edk= 2 project at this time. - -=3D=3D=3DOpen the GNOME Terminal program=3D=3D=3D - -These instructions will utilize Ubuntu's built in command shell (bash) via= the GNOME Terminal application. To open the Terminal application, locate = it under the Applications menu and the Accessories sub-menu. - -=3D=3D=3DInstall required software from apt=3D=3D=3D - -Several ubuntu packages will be needed to fully set up an edk2 build envir= onment. In order to easily install all the requirements, you need to run t= his command. - -
-bash$ sudo apt-get install build-essential uuid-dev texinfo \
-        bison flex libgmp3-dev libmpfr-dev subversion
-
- - -=3D=3DContinue with common instructions for Unix=3D=3D - - -The [[Common instructions for Unix|remaining instructions]] are common for= most UNIX-like systems. - + Note: New build instructions are available. It is recommended to start w= ith the new instructions if learning how to + build edk2 for the first time. This page is retained for reference. + +New instructions: [[Build-Instructions.md|Build Instructions]] + +This page provides ''step-by-step instructions'' for setting up a [http://= www.tianocore.org/edk2/ EDK II] build environment on various Unix-like syst= ems. + +'''Note''': These instructions are not recommended for most EDK II develop= ers. If you are working with a supported Linux distribution, then the [[Usi= ng EDK II with Native GCC]] instructions are faster, easier, and produce a = smaller UEFI binary image. + +=3D=3DGetting started for UNIX-like operating systems=3D=3D + +These instructions will be written as a series of commands executed from a= command terminal. + +Often these instructions will contain a command which needs to be executed= in the terminal window. For example: + +
+bash$ echo this bold text is a sample command
+
+ +To execute this command, highlight the bold text of the command in your we= b browser. Most web browsers should be able to copy the text by selecting = Copy under the Edit menu. Now, change back to the terminal application, an= d there should be a Paste operation under the Edit menu. After pasting the= command into the shell, you may need to press the enter or return key to e= xecute the command. + +Of course, there may be other ways to copy and paste the command into the = terminal which are specific to the windowing environment and applications t= hat you are using. If all else fails, however, you can type the command by= hand. + +Some commands are very long, and we use the backslash character (\) to tel= l the shell program that the command is not finished. For example: + +
+bash$ echo this bold text is a sample command \
+        which is broken into two lines
+
+ +When you copy and paste, make sure you include all lines of the command (i= ncluding the backslash (\) characters). If you are typing the command, you= can remove the backslash character (\) and combine the lines into a single= line if you prefer. + +If a command starts with the sudo command, then you may be prompted for yo= ur user password. This will be the same password as you used to login to t= he system. + +For the purposes of this set of instructions, we will be using the followi= ng paths. +{| +|Edk2 source tree: || ~/src/edk2 +|- +|GCC X64 cross-compiler installation: || ~/programs/gcc/x64 +|- +|GCC IA32 cross-compiler installation: || ~/programs/gcc/ia32 +|- +|Intel ASL Compiler installation: || ~/src/acpica-unix-20090521/compiler/i= asl (symlink to compiler at ~/programs/iasl) +|} + +You will need to change the commands if you want to use different location= s, but this is not recommended unless you are sure that you know what you a= re doing. + +=3D=3D=3DInternet proxies=3D=3D=3D + +If your network utilizes a firewall with a web proxy, then you may need to= configure your proxy information for various command line applications to = work. You may need to consult with your network administrator to find out = the computer name and port to use for proxy setup. The following commands = are common examples of how you would configure your proxy by setting an env= ironment variable: + +
+bash$ export http_proxy=3Dhttp://proxy.domain.com:proxy_port
+bash$ export ftp_proxy=3D$http_proxy
+
+ +To utilize the subversion source control command behind an internet firewa= ll with a web proxy, you should configure the ~/.subversion/servers file. + +=3D=3D Cygwin 1.7.1 =3D=3D +Notes: +* Cygwin is not officially supported or tested by the edk2 project at this= time. +* Building of [http://www.tianocore.org/edk2/ EDK II] components will be d= one using bash. +Prerequisites: +* Cygwin 1.7.1 is currently installed on the system. +* Cygwin 1.7.1 setup.exe is available on the system to install additional = packages as needed. + +Run Cygwin setup.exe and install the following additional packages. +* bison +* flex +* libgmp-devel +* libiconv +* libmpfr-devel +* gcc (use the compiler upgrade helper option under Devel) +* make +* python +* subversion +* wget +* libuuid-devel +* util-linux (for uuidgen) + +When pulling source files using subversion you may choose to get them to a= more Windows friendly location. All system drives are mapped under /cygdr= ive when using CYGWIN and bash (ie. C:\ maps to /cygdrive/c). This allows = you to substitute ~/src/edk2 for an alternate path such as /cygdrive/c/src/= edk2 so files can be access at C:\src\edk2 as well. + + +Continue with common instructions for Unix + + +The [[Common instructions for Unix|remaining instructions]] are common for= most UNIX-like systems. + +=3D=3DFedora 11=3D=3D +Please note: +* Fedora 11 is not officially supported or tested by the edk2 project at t= his time. +* These instructions assume that the Software Development option was enabl= ed during the Fedora installation. + +=3D=3D=3DOpen the GNOME Terminal program=3D=3D=3D + +These instructions will utilize Fedora's built in command shell (bash) via= the GNOME Terminal application. To open the Terminal application, locate = it under the Applications menu and the System Tools sub-menu. + +=3D=3D=3DInstall MPFR library=3D=3D=3D + +The MPFR library must be installed to allow the gcc cross compiler to be b= uilt. + +
+bash$ mkdir ~/src
+bash$ cd ~/src
+bash$ wget http://www.mpfr.org/mpfr-current/mpfr-2.4.1.tar.bz2
+bash$ tar -jxf mpfr-2.4.1.tar.bz2
+bash$ cd mpfr-2.4.1
+bash$ ./configure --prefix=3D/usr
+bash$ make
+
+ +To install the library, you must be root. Therefore we use 'su' to become= the root user, for the 'make install' command. + +
+bash$ su
+bash$ make install
+bash$ exit
+
+ + +Continue with common instructions for Unix + + +The [[Common instructions for Unix |remaining instructions]] are common fo= r most UNIX-like systems. + +=3D=3DMac OS X 10.5=3D=3D +=3D=3D=3DXcode Tools=3D=3D=3D + +The first step is to install the Apple Xcode development environment: + http://developer.apple.com/tools/xcode + +To install Xcode, you must register as an Apple developer, and download th= e Xcode installation disk image (which is fairly large). These instruction= s were verified with Xcode 3.0. Within the Xcode Tools disk image, only th= e Xcode Tools.mpkg package needs to be installed. + +=3D=3D=3DOpen OS X Terminal program=3D=3D=3D + +Past this point, the remaining instructions will utilize OS X's built in c= ommand shell (bash) via the Terminal application. To open the command term= inal application, open Finder, then press the Cmd-Shift-U key combination. = (This opens the Applications =3D> Utilities folder.) In the Utilities fol= der, you should see the Terminal application. + +=3D=3D=3DGMP & MPFR (if behind a web proxy)=3D=3D=3D + +The gmp and mpfr libraries are needed to build the gcc cross compiler at a= later point in these instructions. Building these libraries on OS X can p= resent some difficulties, so if you are not behind a network firewall, then= consider using the macports project to install these libraries. (see below= ) Be sure to set the http_proxy and ftp_proxy environment variables before= using the 'curl' commands below. + +
+bash$ mkdir ~/src
+bash$ cd ~/src
+bash$ curl --remote-name \
+  ftp://ftp.gnu.org/gnu/gmp/gmp-4.2.2.tar.bz2
+bash$ tar jxvf gmp-4.2.2.tar.bz2
+bash$ cd gmp-4.2.2
+bash$ ./configure --prefix=3D/usr
+bash$ make
+bash$ make check
+bash$ sudo make install
+
+ +Note: This might be needed for 64-bit machines if the MPFR configure fails= below. +
+bash$ export CFLAGS=3D"-m64"
+
+ +
+bash$ cd ~/src
+bash$ curl --remote-name \
+  http://www.mpfr.org/mpfr-current/mpfr-2.4.1.tar.bz2
+bash$ tar -jxf mpfr-2.4.1.tar.bz2
+bash$ cd mpfr-2.4.1
+bash$ ./configure --prefix=3D/usr
+bash$ make
+bash$ sudo make install
+
+ +=3D=3D=3DGMP & MPFR via Macports (if not behind web proxy)=3D=3D=3D + +If you are not behind a network firewall, then the http://www.macports.org= project can greatly simlify the installation of gmp & mpfr. (Macports doe= s not work easily with web proxies at this time.) After installing macports= you should be able to simply run this command at the shell prompt. + +
+bash$ sudo port install gmp mpfr
+
+ + +Continue with common instructions for Unix + + +The [[Common instructions for Unix|remaining instructions]] are common for= most UNIX-like systems. + + + + +=3D=3DUbuntu 9.10=3D=3D +Note: The Ubuntu platform is not officially supported or tested by the edk= 2 project at this time. + +=3D=3D=3DOpen the GNOME Terminal program=3D=3D=3D + +These instructions will utilize Ubuntu's built in command shell (bash) via= the GNOME Terminal application. To open the Terminal application, locate = it under the Applications menu and the Accessories sub-menu. + +=3D=3D=3DInstall required software from apt=3D=3D=3D + +Several ubuntu packages will be needed to fully set up an edk2 build envir= onment. In order to easily install all the requirements, you need to run t= his command. + +
+bash$ sudo apt-get install build-essential uuid-dev texinfo \
+        bison flex libgmp3-dev libmpfr-dev subversion
+
+ + +=3D=3DContinue with common instructions for Unix=3D=3D + + +The [[Common instructions for Unix|remaining instructions]] are common for= most UNIX-like systems. + diff --git a/Using-EDK-II-with-Native-GCC.mediawiki b/Using-EDK-II-with-Nat= ive-GCC.mediawiki index e17f5056b446..ea8c8f9326dc 100644 --- a/Using-EDK-II-with-Native-GCC.mediawiki +++ b/Using-EDK-II-with-Native-GCC.mediawiki @@ -1,241 +1,244 @@ - - -This page provides ''step-by-step instructions'' for setting up a [http://= www.tianocore.org/edk2/ EDK II] build environment on Linux using a native G= CC installation (4.4+). This EDK II setup does not require the Mingw versi= on of GCC to be built, and therefore can be much faster to setup. - -=3D=3DGetting Started=3D=3D - -These instructions will be written as a series of commands executed from a= command terminal.Often these instructions will contain a command which nee= ds to be executed in the terminal window. For example: - -
-bash$ echo this text is a sample command
-
- -To execute this command, highlight the text of the command in your web bro= wser. (Note that the 'bash$' text is not part of the command!) Most web b= rowsers should be able to copy the text by selecting Copy under the Edit me= nu. Now, change back to the terminal application, and there should be a Pa= ste operation under the Edit menu. After pasting the command into the shel= l, you may need to press the enter or return key to execute the command.=20 - -Of course, there may be other ways to copy and paste the command into the = terminal which are specific to the windowing environment and applications t= hat you are using. If all else fails, however, you can type the command by= hand. - -Some commands are very long, and we use the backslash character (\) to tel= l the shell program that the command is not finished. For example: - -
-bash$ echo this bold text is a sample command \
-        which is broken into two lines
-
- -When you copy and paste, make sure you include all lines of the command (i= ncluding the backslash (\) characters). If you are typing the command, you= can remove the backslash character (\) and combine the lines into a single= line if you prefer. - -If a command starts with the sudo command, then you may be prompted for yo= ur user password. This will be the same password as you used to login to t= he system. - -For the purposes of this set of instructions, we will be using the followi= ng paths. -{| -|Edk2 source tree: || $HOME/src/edk2 -|- -|Native GCC 4.x compiler installation: || /usr/bin/gcc -|- -|Intel ASL Compiler installation: || /usr/bin/iasl -|} - -You will need to change the commands if you want to use different location= s, but this is not recommended unless you are sure that you know what you a= re doing. - -=3D=3D=3DInternet proxies=3D=3D=3D - -If your network utilizes a firewall with a web proxy, then you may need to= configure your proxy information for various command line applications to = work. You may need to consult with your network administrator to find out = the computer name and port to use for proxy setup. The following commands = are common examples of how you would configure your proxy by setting an env= ironment variable: - -
-bash$ export http_proxy=3Dhttp://proxy.domain.com:proxy_port
-bash$ export ftp_proxy=3D$http_proxy
-
- -To utilize the subversion source control command behind an internet firewa= ll with a web proxy, you should configure the ~/.subversion/servers file. - -=3D=3D=3DUbuntu 20.04 LTS=3D=3D=3D - -Note: These instructions utilize GCC5 & NASM compiler support (added in ea= rly 2016), along with git (replaces subversion). GCC 4.x is still supported= . GCC5 is not mandatory. - -=3D=3D=3D=3DOpen the GNOME Terminal program=3D=3D=3D=3D - -These instructions will utilize Ubuntu's built in command shell (bash) via= the GNOME Terminal application. To open the Terminal application, locate = it under the Applications menu and the Accessories sub-menu. - -=3D=3D=3D=3DInstall required software from apt=3D=3D=3D=3D - -Several Ubuntu packages will be needed to set up the build environment for= EDK II. The following command will install all required packages: - -
-bash$ sudo apt install build-essential uuid-dev iasl git  nasm  python-is-=
python3
-
- -:build-essential - Informational list of build-essential packages=20 -:uuid-dev - Universally Unique ID library (headers and static libraries) -:iasl - Intel ASL compiler/decompiler (also provided by acpica-tools) -:git - support for git revision control system=20 -:nasm - General-purpose x86 assembler -:python-is-python3 - Ubuntu 20.04 python command is 'python3' but edk2 too= ls use 'python' - - -=3D=3D=3DContinue with common instructions=3D=3D=3D - -The [[Common instructions|remaining instructions]] are common for most UNI= X-like systems. - - - -=3D=3D=3DUbuntu 16.04 LTS / Ubuntu 16.10=3D=3D=3D - -Note: These instructions utilize GCC5 & NASM compiler support (added in ea= rly 2016), along with git (replaces subversion). GCC 4.x is still supported= . GCC5 is not mandatory. - -=3D=3D=3D=3DOpen the GNOME Terminal program=3D=3D=3D=3D - -These instructions will utilize Ubuntu's built in command shell (bash) via= the GNOME Terminal application. To open the Terminal application, locate = it under the Applications menu and the Accessories sub-menu. - -=3D=3D=3D=3DInstall required software from apt=3D=3D=3D=3D - -Several Ubuntu packages will be needed to set up the build environment for= EDK II. The following command will install all required packages: - -
-bash$ sudo apt-get install build-essential uuid-dev iasl git gcc-5 nasm py=
thon3-distutils
-
- -:build-essential - Informational list of build-essential packages=20 -:uuid-dev - Universally Unique ID library (headers and static libraries) -:iasl - Intel ASL compiler/decompiler (also provided by acpica-tools) -:git - support for git revision control system=20 -:gcc-5 - GNU C compiler (v5.4.0 as of Ubuntu 16.04 LTS) -:nasm - General-purpose x86 assembler -:python3-distutils - distutils module from the Python standard library - -=3D=3D=3DContinue with common instructions=3D=3D=3D - -The [[Common instructions|remaining instructions]] are common for most UNI= X-like systems. - - -=3D=3DInstructions for older Linux Environments=3D=3D - -Note: the instructions below have not been updated for compilers newer tha= n GCC 4.4, git (replaces subversion) or NASM. Newer builds may fail without= satisfying these dependecies. We recommend moving to newer Linux distribut= ions unless you have a dependency on a specific version. - -=3D=3D=3DNote: Limitations of GCC 4.4=3D=3D=3D - -Note: The GCC 4.4 toolchain only supports building images for the IA32 and= X64 architectures. We recommend using newer toolchains. - -Also, in some cases if GCC 4.4 is installed under Linux x86 (32-bit mode),= then it may only support building UEFI images for the IA32 architecture. - -=3D=3D=3DArch Linux 2010.05=3D=3D=3D -Note: Arch Linux is not officially supported or tested by the edk2 project= at this time. - -=3D=3D=3D=3DOpen the GNOME Terminal program=3D=3D=3D=3D - -These instructions will utilize Arch Linux's built in command shell (bash)= via the GNOME Terminal application. To open the Terminal application, loc= ate it under the Applications menu and the System Tools sub-menu. - -=3D=3D=3D=3DInstall required software with pacman=3D=3D=3D=3D - -To install the required packages, you must be root. Therefore we use 'su'= to become the root user. - -
-bash$ su -
-bash$ pacman -S base-devel glibc iasl python2 subversion
-bash$ exit
-
- - -Continue with common instructions - - -The [[Common instructions|remaining instructions]] are common for most UNI= X-like systems. - -=3D=3D=3DFedora 13=3D=3D=3D -Note: Fedora is not officially supported or tested by the edk2 project at = this time. - -Note: x86 (32-bit) Fedora will install GCC 4.4 which is only capable of bu= ilding UEFI for the IA32 architecture. - -=3D=3D=3D=3DOpen the GNOME Terminal program=3D=3D=3D=3D - -These instructions will utilize Fedora's built in command shell (bash) via= the GNOME Terminal application. To open the Terminal application, locate = it under the Applications menu and the System Tools sub-menu. - -=3D=3D=3D=3DInstall required software with yum=3D=3D=3D=3D - -To install the required packages, you must be root. Therefore we use 'su'= to become the root user. - -
-bash$ su -
-bash$ yum groupinstall development-tools
-bash$ yum install iasl libuuid-devel
-bash$ exit
-
- - -Continue with common instructions - - -The [[Common instructions|remaining instructions]] are common for most UNI= X-like systems. - -=3D=3D=3DMandriva 2010=3D=3D=3D -Note: Mandriva is not officially supported or tested by the edk2 project a= t this time. - -Note: x86 (32-bit) Mandriva will install GCC 4.4 which is only capable of = building UEFI for the IA32 architecture. - -=3D=3D=3D=3DOpen the Terminal program=3D=3D=3D=3D - -These instructions will utilize Mandriva's built in command shell (bash) v= ia the Terminal application. To open the Terminal application, locate it u= nder the Applications menu and the Tools sub-menu. - -=3D=3D=3D=3DInstall required software with urpmi=3D=3D=3D=3D - -To install the required packages, you must be root. Therefore we use 'su'= to become the root user. - -
-bash$ su -
-bash$ urpmi task-c++-devel iasl libuuid-devel subversion
-bash$ exit
-
- - -Continue with common instructions - - -The [[Common instructions|remaining instructions]] are common for most UNI= X-like systems. - -=3D=3D=3DopenSUSE 12.1=3D=3D=3D - -Note: openSUSE is not officially supported or tested by the edk2 project a= t this time. - -=3D=3D=3D=3DOpen the GNOME Terminal program=3D=3D=3D=3D - -These instructions will utilize openSUSE's built in command shell (bash) v= ia the GNOME Terminal application. To open the Terminal application, click= the 'Computer' menu, click the 'More Applications' button, and then enter = 'terminal' into the filter text box. - -=3D=3D=3D=3DInstall required software with zypper=3D=3D=3D=3D - -Several openSUSE packages will be needed to fully set up an edk2 build env= ironment. In order to easily install all the requirements, you need to run= this command. - -
-bash> sudo zypper in -t pattern devel_basis
-
- - -Continue with common instructions - - -The [[Common instructions|remaining instructions]] are common for most UNI= X-like systems. - -=3D=3D=3DUbuntu 10.10=3D=3D=3D -Notes: -* The Ubuntu platform is not officially supported or tested by the edk2 pr= oject at this time. -* Both the x86 (32-bit) and x86-64 (64-bit) Ubuntu versions will install G= CC 4.4 which is capable of building UEFI for both the IA32 and X64 architec= tures. -* These instructions should work for Ubuntu 10.04 as well - -=3D=3D=3D=3DOpen the GNOME Terminal program=3D=3D=3D=3D - -These instructions will utilize Ubuntu's built in command shell (bash) via= the GNOME Terminal application. To open the Terminal application, locate = it under the Applications menu and the Accessories sub-menu. - -=3D=3D=3D=3DInstall required software from apt=3D=3D=3D=3D - -Several ubuntu packages will be needed to fully set up an edk2 build envir= onment. In order to easily install all the requirements, you need to run t= his command. - -
-bash$ sudo apt-get install build-essential subversion uuid-dev iasl
-
- - -=3D=3D=3DContinue with common instructions=3D=3D=3D - -The [[Common instructions|remaining instructions]] are common for most UNI= X-like systems. - - -=3DSee Also=3D - + Note: New build instructions are available. It is recommended to start w= ith the new instructions if learning how to + build edk2 for the first time. This page is retained for reference. + +New instructions: [[Build-Instructions.md|Build Instructions]] + +This page provides ''step-by-step instructions'' for setting up a [http://= www.tianocore.org/edk2/ EDK II] build environment on Linux using a native G= CC installation (4.4+). This EDK II setup does not require the Mingw versi= on of GCC to be built, and therefore can be much faster to setup. + +=3D=3DGetting Started=3D=3D + +These instructions will be written as a series of commands executed from a= command terminal.Often these instructions will contain a command which nee= ds to be executed in the terminal window. For example: + +
+bash$ echo this text is a sample command
+
+ +To execute this command, highlight the text of the command in your web bro= wser. (Note that the 'bash$' text is not part of the command!) Most web b= rowsers should be able to copy the text by selecting Copy under the Edit me= nu. Now, change back to the terminal application, and there should be a Pa= ste operation under the Edit menu. After pasting the command into the shel= l, you may need to press the enter or return key to execute the command. + +Of course, there may be other ways to copy and paste the command into the = terminal which are specific to the windowing environment and applications t= hat you are using. If all else fails, however, you can type the command by= hand. + +Some commands are very long, and we use the backslash character (\) to tel= l the shell program that the command is not finished. For example: + +
+bash$ echo this bold text is a sample command \
+        which is broken into two lines
+
+ +When you copy and paste, make sure you include all lines of the command (i= ncluding the backslash (\) characters). If you are typing the command, you= can remove the backslash character (\) and combine the lines into a single= line if you prefer. + +If a command starts with the sudo command, then you may be prompted for yo= ur user password. This will be the same password as you used to login to t= he system. + +For the purposes of this set of instructions, we will be using the followi= ng paths. +{| +|Edk2 source tree: || $HOME/src/edk2 +|- +|Native GCC 4.x compiler installation: || /usr/bin/gcc +|- +|Intel ASL Compiler installation: || /usr/bin/iasl +|} + +You will need to change the commands if you want to use different location= s, but this is not recommended unless you are sure that you know what you a= re doing. + +=3D=3D=3DInternet proxies=3D=3D=3D + +If your network utilizes a firewall with a web proxy, then you may need to= configure your proxy information for various command line applications to = work. You may need to consult with your network administrator to find out = the computer name and port to use for proxy setup. The following commands = are common examples of how you would configure your proxy by setting an env= ironment variable: + +
+bash$ export http_proxy=3Dhttp://proxy.domain.com:proxy_port
+bash$ export ftp_proxy=3D$http_proxy
+
+ +To utilize the subversion source control command behind an internet firewa= ll with a web proxy, you should configure the ~/.subversion/servers file. + +=3D=3D=3DUbuntu 20.04 LTS=3D=3D=3D + +Note: These instructions utilize GCC5 & NASM compiler support (added in ea= rly 2016), along with git (replaces subversion). GCC 4.x is still supported= . GCC5 is not mandatory. + +=3D=3D=3D=3DOpen the GNOME Terminal program=3D=3D=3D=3D + +These instructions will utilize Ubuntu's built in command shell (bash) via= the GNOME Terminal application. To open the Terminal application, locate = it under the Applications menu and the Accessories sub-menu. + +=3D=3D=3D=3DInstall required software from apt=3D=3D=3D=3D + +Several Ubuntu packages will be needed to set up the build environment for= EDK II. The following command will install all required packages: + +
+bash$ sudo apt install build-essential uuid-dev iasl git  nasm  python-is-=
python3
+
+ +:build-essential - Informational list of build-essential packages +:uuid-dev - Universally Unique ID library (headers and static libraries) +:iasl - Intel ASL compiler/decompiler (also provided by acpica-tools) +:git - support for git revision control system +:nasm - General-purpose x86 assembler +:python-is-python3 - Ubuntu 20.04 python command is 'python3' but edk2 too= ls use 'python' + + +=3D=3D=3DContinue with common instructions=3D=3D=3D + +The [[Common instructions|remaining instructions]] are common for most UNI= X-like systems. + + + +=3D=3D=3DUbuntu 16.04 LTS / Ubuntu 16.10=3D=3D=3D + +Note: These instructions utilize GCC5 & NASM compiler support (added in ea= rly 2016), along with git (replaces subversion). GCC 4.x is still supported= . GCC5 is not mandatory. + +=3D=3D=3D=3DOpen the GNOME Terminal program=3D=3D=3D=3D + +These instructions will utilize Ubuntu's built in command shell (bash) via= the GNOME Terminal application. To open the Terminal application, locate = it under the Applications menu and the Accessories sub-menu. + +=3D=3D=3D=3DInstall required software from apt=3D=3D=3D=3D + +Several Ubuntu packages will be needed to set up the build environment for= EDK II. The following command will install all required packages: + +
+bash$ sudo apt-get install build-essential uuid-dev iasl git gcc-5 nasm py=
thon3-distutils
+
+ +:build-essential - Informational list of build-essential packages +:uuid-dev - Universally Unique ID library (headers and static libraries) +:iasl - Intel ASL compiler/decompiler (also provided by acpica-tools) +:git - support for git revision control system +:gcc-5 - GNU C compiler (v5.4.0 as of Ubuntu 16.04 LTS) +:nasm - General-purpose x86 assembler +:python3-distutils - distutils module from the Python standard library + +=3D=3D=3DContinue with common instructions=3D=3D=3D + +The [[Common instructions|remaining instructions]] are common for most UNI= X-like systems. + + +=3D=3DInstructions for older Linux Environments=3D=3D + +Note: the instructions below have not been updated for compilers newer tha= n GCC 4.4, git (replaces subversion) or NASM. Newer builds may fail without= satisfying these dependecies. We recommend moving to newer Linux distribut= ions unless you have a dependency on a specific version. + +=3D=3D=3DNote: Limitations of GCC 4.4=3D=3D=3D + +Note: The GCC 4.4 toolchain only supports building images for the IA32 and= X64 architectures. We recommend using newer toolchains. + +Also, in some cases if GCC 4.4 is installed under Linux x86 (32-bit mode),= then it may only support building UEFI images for the IA32 architecture. + +=3D=3D=3DArch Linux 2010.05=3D=3D=3D +Note: Arch Linux is not officially supported or tested by the edk2 project= at this time. + +=3D=3D=3D=3DOpen the GNOME Terminal program=3D=3D=3D=3D + +These instructions will utilize Arch Linux's built in command shell (bash)= via the GNOME Terminal application. To open the Terminal application, loc= ate it under the Applications menu and the System Tools sub-menu. + +=3D=3D=3D=3DInstall required software with pacman=3D=3D=3D=3D + +To install the required packages, you must be root. Therefore we use 'su'= to become the root user. + +
+bash$ su -
+bash$ pacman -S base-devel glibc iasl python2 subversion
+bash$ exit
+
+ + +Continue with common instructions + + +The [[Common instructions|remaining instructions]] are common for most UNI= X-like systems. + +=3D=3D=3DFedora 13=3D=3D=3D +Note: Fedora is not officially supported or tested by the edk2 project at = this time. + +Note: x86 (32-bit) Fedora will install GCC 4.4 which is only capable of bu= ilding UEFI for the IA32 architecture. + +=3D=3D=3D=3DOpen the GNOME Terminal program=3D=3D=3D=3D + +These instructions will utilize Fedora's built in command shell (bash) via= the GNOME Terminal application. To open the Terminal application, locate = it under the Applications menu and the System Tools sub-menu. + +=3D=3D=3D=3DInstall required software with yum=3D=3D=3D=3D + +To install the required packages, you must be root. Therefore we use 'su'= to become the root user. + +
+bash$ su -
+bash$ yum groupinstall development-tools
+bash$ yum install iasl libuuid-devel
+bash$ exit
+
+ + +Continue with common instructions + + +The [[Common instructions|remaining instructions]] are common for most UNI= X-like systems. + +=3D=3D=3DMandriva 2010=3D=3D=3D +Note: Mandriva is not officially supported or tested by the edk2 project a= t this time. + +Note: x86 (32-bit) Mandriva will install GCC 4.4 which is only capable of = building UEFI for the IA32 architecture. + +=3D=3D=3D=3DOpen the Terminal program=3D=3D=3D=3D + +These instructions will utilize Mandriva's built in command shell (bash) v= ia the Terminal application. To open the Terminal application, locate it u= nder the Applications menu and the Tools sub-menu. + +=3D=3D=3D=3DInstall required software with urpmi=3D=3D=3D=3D + +To install the required packages, you must be root. Therefore we use 'su'= to become the root user. + +
+bash$ su -
+bash$ urpmi task-c++-devel iasl libuuid-devel subversion
+bash$ exit
+
+ + +Continue with common instructions + + +The [[Common instructions|remaining instructions]] are common for most UNI= X-like systems. + +=3D=3D=3DopenSUSE 12.1=3D=3D=3D + +Note: openSUSE is not officially supported or tested by the edk2 project a= t this time. + +=3D=3D=3D=3DOpen the GNOME Terminal program=3D=3D=3D=3D + +These instructions will utilize openSUSE's built in command shell (bash) v= ia the GNOME Terminal application. To open the Terminal application, click= the 'Computer' menu, click the 'More Applications' button, and then enter = 'terminal' into the filter text box. + +=3D=3D=3D=3DInstall required software with zypper=3D=3D=3D=3D + +Several openSUSE packages will be needed to fully set up an edk2 build env= ironment. In order to easily install all the requirements, you need to run= this command. + +
+bash> sudo zypper in -t pattern devel_basis
+
+ + +Continue with common instructions + + +The [[Common instructions|remaining instructions]] are common for most UNI= X-like systems. + +=3D=3D=3DUbuntu 10.10=3D=3D=3D +Notes: +* The Ubuntu platform is not officially supported or tested by the edk2 pr= oject at this time. +* Both the x86 (32-bit) and x86-64 (64-bit) Ubuntu versions will install G= CC 4.4 which is capable of building UEFI for both the IA32 and X64 architec= tures. +* These instructions should work for Ubuntu 10.04 as well + +=3D=3D=3D=3DOpen the GNOME Terminal program=3D=3D=3D=3D + +These instructions will utilize Ubuntu's built in command shell (bash) via= the GNOME Terminal application. To open the Terminal application, locate = it under the Applications menu and the Accessories sub-menu. + +=3D=3D=3D=3DInstall required software from apt=3D=3D=3D=3D + +Several ubuntu packages will be needed to fully set up an edk2 build envir= onment. In order to easily install all the requirements, you need to run t= his command. + +
+bash$ sudo apt-get install build-essential subversion uuid-dev iasl
+
+ + +=3D=3D=3DContinue with common instructions=3D=3D=3D + +The [[Common instructions|remaining instructions]] are common for most UNI= X-like systems. + + +=3DSee Also=3D + * [[Unix-like systems]] - Instructions which walk through building the Min= gw GCC cross-compiler \ No newline at end of file diff --git a/Windows-systems.mediawiki b/Windows-systems.mediawiki index ebb717a22464..6be6e9187be8 100644 --- a/Windows-systems.mediawiki +++ b/Windows-systems.mediawiki @@ -1,156 +1,162 @@ -__NOTOC__ -This page provides step-by-step instructions or setting up a [http://www.t= ianocore.org/edk2/ EDK II] build environment on Windows systems. - -''Table of Contents'' -* [[Windows-systems#github-help|GitHub Help]] -* [[Windows-systems#how-to-setup-the-edk-ii-tree| How to Setup the EDK II = Tree]] -* [[Windows-systems#download| Download]] Checkout EDK II source tree from= Github=20 -* [[Windows-systems#compile-tools |Compile Tools]] Build EDK II BaseTools = for Windows=20 -* [[Windows-systems#build | BUILD]] EDK II - -=3D=3DGitHub Help=3D=3D - -GitHub (https://help.github.com/index.html) provides step-by-step instruct= ions for user registration and basic features supported by GitHub. - -=3D=3D=3D Git GUI Interface for Windows OS =3D=3D=3D -* Git for Windows OS is available at: (http://git-scm.com/download/win) -* TortoiseGit for windows OS is available at (https://tortoisegit.org/down= load/) - -=3D=3D'''GitHub EDK II Project Repositories'''=3D=3D - -* The EDK II project repository is available at https://github.com/tianoco= re/edk2.=20 - -Content that is not released under an accepted open source license can be = found at https://github.com/tianocore/edk2-non-osi.
- 
-Note: the steps below will pull the latest code from edk2 master. To work = from a stable release, please refer to the Microsoft Windows build steps fo= r [[UDK2017]]: https://github.com/tianocore/tianocore.github.io/wiki/UDK201= 7-How-to-Build#how-to-build-windows-system=20 - -=3D=3D=3DInternet proxies=3D=3D=3D - -If your network utilizes a firewall with a web proxy, then you may need to= configure your proxy information for various command line applications to = work. You may need to consult with your network administrator to find out = the computer name and port to use for proxy setup. The following commands = are common '''Git Bash''' examples of how you would configure your proxy by= setting an environment variable: - -
-    $ git config --global https.proxy .domain.com:
-    $ git config --global http.proxy .domain.com:
-
- - -=3D=3D'''How to Setup the EDK II Tree'''=3D=3D -'''Note:''' Some of the following examples use the Multiple Workspace feat= ure to configure the EDK II BaseTools. More information on the Multiple Wo= rkspace feature can be found at the following location.
-* [[Multiple_Workspace]] - -=3D=3D'''Download'''=3D=3D -Download/Checkout the EDK II source tree from Github -=3D=3D=3D Download Using a Web browser =3D=3D=3D - -# Download EDK II Project -## Open https://github.com/tianocore/edk2 in web browser -## Click on the ''Clone or Download'' button (Right Green) -## Click on Download ZIP -## Unzip to C:/ -## Rename directory =E2=80=9Cedk2-master=E2=80=9D to =E2=80=9Cedk2=E2=80= =9D =20 - -Continue to [[Windows-systems#compile-tools |Compile Tools]]=20 - -=3D=3D=3D Using '''Git for Windows''' Application =3D=3D=3D -=3D=3D=3D=3D ''Git GUI''=3D=3D=3D=3D -# Clone the EDK II project repository -## Open Git GUI -## Use ''Clone Exiting Repository'' with Source location https://github.co= m/tianocore/edk2.git -## Select a Target directory C:/edk2 -## Check Recursively clone submodules too -## click Clone button - -Continue to [[Windows-systems#compile-tools |Compile Tools]] section - -=3D=3D=3D=3D ''Git CMD'' =3D=3D=3D=3D -If you use the command line version, then you can easily checkout the edk2= to the C:\edk2 directory with the following git command: -Main repository: https://github.com/tianocore/edk2 -
-    $git clone https://github.com/tianocore/edk2
-
- -Continue to [[Windows-systems#compile-tools |Compile Tools]] and then [[Wi= ndows-systems#build | BUILD]] sections - -=3D=3D'''Compile Tools'''=3D=3D -=3D=3D=3D=3D=3DFor EDK II project developers on Windows with source BaseTo= ols:=3D=3D=3D=3D=3D -* Create a workspace directory -* Change to the workspace directory -* Clone the EDK II project repository (See [[Windows-systems#download| Dow= nload]] section above) -** Example: git clone https://github.com/tianocore/edk2 -* Install Python37 or late version (https://www.python.org/) to run pytho= n tool from source=20 -* Compile BaseTools C source tools -Example: -* Inside Git Bash -
-     $ git clone https://github.com/tianocore/edk2
-
-=3D=3D=3D=3D=3DCompile BaseTools=3D=3D=3D=3D=3D -Example: -*Open Command prompt and CD C:\edk2: -
+__NOTOC__
+
+  Note: New build instructions are available. It is recommended to start w=
ith the new instructions if learning how to
+        build edk2 for the first time. This page is retained for reference.
+
+New instructions: [[Build-Instructions.md|Build Instructions]]
+
+This page provides step-by-step instructions or setting up a [http://www.t=
ianocore.org/edk2/ EDK II] build environment on Windows systems.
+
+''Table of Contents''
+* [[Windows-systems#github-help|GitHub Help]]
+* [[Windows-systems#how-to-setup-the-edk-ii-tree| How to Setup the EDK II =
Tree]]
+* [[Windows-systems#download| Download]]  Checkout EDK II source tree from=
 Github
+* [[Windows-systems#compile-tools |Compile Tools]] Build EDK II BaseTools =
for Windows
+* [[Windows-systems#build | BUILD]] EDK II
+
+=3D=3DGitHub Help=3D=3D
+
+GitHub (https://help.github.com/index.html) provides step-by-step instruct=
ions for user registration and basic features supported by GitHub.
+
+=3D=3D=3D Git GUI Interface for Windows OS =3D=3D=3D
+* Git for Windows OS is available at: (http://git-scm.com/download/win)
+* TortoiseGit for windows OS is available at (https://tortoisegit.org/down=
load/)
+
+=3D=3D'''GitHub EDK II Project Repositories'''=3D=3D
+
+* The EDK II project repository is available at https://github.com/tianoco=
re/edk2.
+
+Content that is not released under an accepted open source license can be =
found at https://github.com/tianocore/edk2-non-osi.

+ 

+Note: the steps below will pull the latest code from edk2 master. To work =
from a stable release, please refer to the Microsoft Windows build steps fo=
r [[UDK2017]]: https://github.com/tianocore/tianocore.github.io/wiki/UDK201=
7-How-to-Build#how-to-build-windows-system
+
+=3D=3D=3DInternet proxies=3D=3D=3D
+
+If your network utilizes a firewall with a web proxy, then you may need to=
 configure your proxy information for various command line applications to =
work.  You may need to consult with your network administrator to find out =
the computer name and port to use for proxy setup.  The following commands =
are common '''Git Bash''' examples of how you would configure your proxy by=
 setting an environment variable:
+
+
+    $ git config --global https.proxy .domain.com:
+    $ git config --global http.proxy .domain.com:
+

+
+
+=3D=3D'''How to Setup the EDK II Tree'''=3D=3D
+'''Note:''' Some of the following examples use the Multiple Workspace feat=
ure to configure the EDK II BaseTools.  More information on the Multiple Wo=
rkspace feature can be found at the following location. 

+* [[Multiple_Workspace]]
+
+=3D=3D'''Download'''=3D=3D
+Download/Checkout the EDK II source tree from Github
+=3D=3D=3D Download Using a Web browser =3D=3D=3D
+
+# Download EDK II Project
+## Open https://github.com/tianocore/edk2 in web browser
+## Click on the ''Clone or Download'' button (Right Green)
+## Click on Download ZIP
+## Unzip to C:/
+## Rename directory =E2=80=9Cedk2-master=E2=80=9D to =E2=80=9Cedk2=E2=80=
=9D
+
+Continue to [[Windows-systems#compile-tools |Compile Tools]]
+
+=3D=3D=3D Using '''Git for Windows''' Application =3D=3D=3D
+=3D=3D=3D=3D ''Git GUI''=3D=3D=3D=3D
+# Clone the EDK II project repository
+## Open Git GUI
+## Use ''Clone Exiting Repository'' with Source location https://github.co=
m/tianocore/edk2.git
+## Select a Target directory C:/edk2
+## Check Recursively clone submodules too
+## click Clone button
+
+Continue to [[Windows-systems#compile-tools |Compile Tools]] section
+
+=3D=3D=3D=3D ''Git CMD'' =3D=3D=3D=3D
+If you use the command line version, then you can easily checkout the edk2=
 to the C:\edk2 directory with the following git command:
+Main repository: https://github.com/tianocore/edk2
+
+    $git clone https://github.com/tianocore/edk2
+

+
+Continue to [[Windows-systems#compile-tools |Compile Tools]] and then [[Wi=
ndows-systems#build | BUILD]] sections
+
+=3D=3D'''Compile Tools'''=3D=3D
+=3D=3D=3D=3D=3DFor EDK II project developers on Windows with source BaseTo=
ols:=3D=3D=3D=3D=3D
+*	Create a workspace directory
+*	Change to the workspace directory
+*	Clone the EDK II project repository (See [[Windows-systems#download| Dow=
nload]] section above)
+**	Example: git clone https://github.com/tianocore/edk2
+* Install Python37 or late version (https://www.python.org/)  to run pytho=
n tool from source
+* Compile BaseTools C source tools
+Example:
+* Inside Git Bash
+
+     $ git clone https://github.com/tianocore/edk2
+

+=3D=3D=3D=3D=3DCompile BaseTools=3D=3D=3D=3D=3D
+Example:
+*Open Command prompt and CD C:\edk2:
+
      C:\edk2> set PYTHON_HOME=3DC:\Python37
-     C:\edk2> edksetup.bat Rebuild
-

-
-
-=3D=3D'''Build'''=3D=3D
-* Set up the [[Nasm-Setup| Nasm]] open source assembly compiler
-* Set up the [[Asl Setup| ASL Compiler]]=20
-* [[Windows-systems#compile-tools |Compile Tools]] above
-* Open a Windows CMD prompt:
-* Change to the edk2 directory
-* Run the edksetup.bat script
-
-      C:\Users\MySid> CD \edk2
-      C:\edk2> edksetup
-
-=3D=3D=3DBuild MdeModulePkg=3D=3D=3D
-
-
-=3D=3D=3D=3DModify Conf files=3D=3D=3D=3D
-
-You will need to edit the Conf\target.txt file.  First, change the ACTIVE_=
PLATFORM to the MdeModulePkg:
-
-
-C:\edk2> notepad Conf\target.txt
-

-
-ACTIVE_PLATFORM should look like this in Conf\target.txt:
-
-
-ACTIVE_PLATFORM       =3D MdeModulePkg/MdeModulePkg.dsc
-

-
-Modify TOOL_CHAIN_TAG in target.txt for the toolchain installed on your sy=
stem. There are many options, so review the tools_def.txt to find the appro=
priate toolchain for your system.  Search for 'Supported Tool Chains' in to=
ols_def.txt to see the valid options for TOOL_CHAIN_TAG.=20
-
-TOOL_CHAIN_TAG        =3D VS2015x86
-

-
-
-
-See also: [[Windows-systems-ToolChain-Matrix]] for how to change the Tool =
Chain Tag.
-
-Also, consider if you want to build a different processor architecture by =
changing the TARGET_ARCH value in target.txt.  Please consider that certain=
 toolchains only support building certain processor architectures.
-
-=3D=3D=3D=3DBuild Hello World!  (and the rest of MdeModulePkg)=3D=3D=3D=3D
-
-Now you should be able to simply run the build command to compile the MdeM=
odulePkg.
-
-
-C:\edk2> build
-

-
-As a tangible result of the build, you should have the HelloWorld UEFI app=
lication.  If you have a UEFI system available to you which matches the pro=
cessor architecture that you built, then this application should be able to=
 run successfully under the shell.
-
-
-C:\edk2> dir /s Build\MdeModule\DEBUG_...\IA32\HelloWorld.efi
-

-
-=3D=3D=3DBuild [[OVMF]] (OPTIONAL)=3D=3D=3D
-
-Once your build environment is set up you might be interested in building =
the  [[OVMF]] platform which is included in the main edk2 source tree.  Sin=
ce [[OVMF]] builds a full system firmware image this may be of interest to =
UEFI system firmware developers.
-
-=3DSee Also=3D
-* [[Getting-Started-Writing-Simple-Application]]
-
+     C:\edk2> edksetup.bat Rebuild
+
+ + +=3D=3D'''Build'''=3D=3D +* Set up the [[Nasm-Setup| Nasm]] open source assembly compiler +* Set up the [[Asl Setup| ASL Compiler]] +* [[Windows-systems#compile-tools |Compile Tools]] above +* Open a Windows CMD prompt: +* Change to the edk2 directory +* Run the edksetup.bat script + + C:\Users\MySid> CD \edk2 + C:\edk2> edksetup + +=3D=3D=3DBuild MdeModulePkg=3D=3D=3D + + +=3D=3D=3D=3DModify Conf files=3D=3D=3D=3D + +You will need to edit the Conf\target.txt file. First, change the ACTIVE_= PLATFORM to the MdeModulePkg: + +
+C:\edk2> notepad Conf\target.txt
+
+ +ACTIVE_PLATFORM should look like this in Conf\target.txt: + +
+ACTIVE_PLATFORM       =3D MdeModulePkg/MdeModulePkg.dsc
+
+ +Modify TOOL_CHAIN_TAG in target.txt for the toolchain installed on your sy= stem. There are many options, so review the tools_def.txt to find the appro= priate toolchain for your system. Search for 'Supported Tool Chains' in to= ols_def.txt to see the valid options for TOOL_CHAIN_TAG. +
+TOOL_CHAIN_TAG        =3D VS2015x86
+
+ + + +See also: [[Windows-systems-ToolChain-Matrix]] for how to change the Tool = Chain Tag. + +Also, consider if you want to build a different processor architecture by = changing the TARGET_ARCH value in target.txt. Please consider that certain= toolchains only support building certain processor architectures. + +=3D=3D=3D=3DBuild Hello World! (and the rest of MdeModulePkg)=3D=3D=3D=3D + +Now you should be able to simply run the build command to compile the MdeM= odulePkg. + +
+C:\edk2> build
+
+ +As a tangible result of the build, you should have the HelloWorld UEFI app= lication. If you have a UEFI system available to you which matches the pro= cessor architecture that you built, then this application should be able to= run successfully under the shell. + +
+C:\edk2> dir /s Build\MdeModule\DEBUG_...\IA32\HelloWorld.efi
+
+ +=3D=3D=3DBuild [[OVMF]] (OPTIONAL)=3D=3D=3D + +Once your build environment is set up you might be interested in building = the [[OVMF]] platform which is included in the main edk2 source tree. Sin= ce [[OVMF]] builds a full system firmware image this may be of interest to = UEFI system firmware developers. + +=3DSee Also=3D +* [[Getting-Started-Writing-Simple-Application]] + \ No newline at end of file --=20 2.28.0.windows.1 -=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D- Groups.io Links: You receive all messages sent to this group. View/Reply Online (#97097): https://edk2.groups.io/g/devel/message/97097 Mute This Topic: https://groups.io/mt/95518594/1787277 Group Owner: devel+owner@edk2.groups.io Unsubscribe: https://edk2.groups.io/g/devel/unsub [importer@patchew.org] -=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-