[edk2-wiki][PATCH v3 0/4] Add new edk2 build instructions

[edk2-wiki][PATCH v3 0/4] Add new edk2 build instructions

[Michael Kubacki]

From: Michael Kubacki <michael.kubacki@microsoft.com>

This series adds a new set of build instructions and updates prior
instructions to point to the new version.

Some patches in this series are not being sent properly. Visit the
GitHub branch to see the changes:

https://github.com/makubacki/tianocore.github.io/tree/add_stuart_build_instructions_v3

Background
----------
Over the life of the project, EDK II has evolved it's build process.

A common theme has been reducing the number of manual steps involved
and easing environment setup and configuration so developers can more
quickly get started writing firmware code.

There's currently three general approaches to build:

1. [Containers](How-to-Develop-With-Containers.md)
2. [Stuart](How-to-Build-With-Stuart.md)
3. [build](Getting-Started-with-EDK-II.mediawiki)

Prior documentation focuses on directly calling build (3). The new
documentation focuses on (1) and (2) but all of the instructions for
(3) are left intact.

This is especially important given the transition to container based
builds on CI and introduction of more CI checks.

Changes
-------
Adds new documentation that describes containers and how to manually
set up a build environment using Stuart.

Containers document covers:

- Container background
- Docker background and installation
- Local development with containers
- How to manually configure a container
- Integration with VS Code
- Containers in pipelines

Stuart build background covers:

- Pre-requisites - Git, Python, compilers, SDKs, etc.
- Initial steps - Cloning the repo, set up Python virtual env, etc.
- Stuart command explanation and corresponding examples
- Common developer scenarios with examples showing what to do
- Common questions section with answers

In addition, a "top-level" document is added that is main landing
page for references to build instructions that briefly describes the
three approaches with links to each.

This is starting material for these topics, we plan to work with
the community to evolve them over time.

V3 Changes:

- Added instructions for updating dependencies to
  "How to Build with Stuart"

V2 Changes:

- Added Linux Mono instructions to "How to Build with Stuart"
  instructions
- Added `-v` argument recommendation to the
  "How do I get more detailed information if an error happens?"
  section in "How to Build with Stuart"
- Updated HTML style to include indentation toward end of the
  file

Cc: Sean Brogan <sean.brogan@microsoft.com>
Cc: Michael D Kinney <michael.d.kinney@intel.com>
Cc: Liming Gao <gaoliming@byosoft.com.cn>
Cc: Chris Fernald <chrisf671@gmail.com>
Signed-off-by: Michael Kubacki <michael.kubacki@microsoft.com>

Chris Fernald (1):
  Add initial container usage instructions

Michael Kubacki (3):
  Add initial How to Build with Stuart Document
  Add top-level build instructions file
  Update existing build instructions

 Build-Instructions.md                  |  35 +
 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 +-
 How-to-Build-With-Stuart.md            | 758 ++++++++++++++++++++
 How-to-Develop-With-Containers.md      | 120 ++++
 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 ++++----
 13 files changed, 2265 insertions(+), 1306 deletions(-)
 create mode 100644 Build-Instructions.md
 create mode 100644 How-to-Build-With-Stuart.md
 create mode 100644 How-to-Develop-With-Containers.md

-- 
2.28.0.windows.1

[edk2-wiki][PATCH v3 1/4] Add initial How to Build with Stuart Document

[Michael Kubacki]

From: Michael Kubacki <michael.kubacki@microsoft.com>

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 <sean.brogan@microsoft.com>
Cc: Michael D Kinney <michael.d.kinney@intel.com>
Cc: Liming Gao <gaoliming@byosoft.com.cn>
Signed-off-by: Michael Kubacki <michael.kubacki@microsoft.com>
---
 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".
+
+>💡 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.
+
+<details>
+  <summary>Pre-requisites (Git, Python, Compiler)</summary>
+  <hr>
+
+  <ul>
+  <li>
+  <strong>Git - Source Control Management (SCM) Tool</strong>
+
+  Git is the source control management tool used by this project.
+
+  You need <code>git</code> to pull the edk2 source code onto your system, make changes in the code, and submit
+  your changes back to the GitHub repository.
+
+  <a href="https://git-scm.com/downloads" target="_blank">Git Download Page</a>
+  </li>
+  <li>
+  <strong>Python</strong>
+
+  Python is a programming language that many of the edk2 build tools are written in.
+
+  You will need Python to run the edk2 build tools including <code>stuart</code>, which is written in Python.
+
+  It is recommended you install a Python version that is equal to the version used in the
+  <code>UsePythonVersion@0</code> step in this file
+  <a href="https://github.com/tianocore/edk2/blob/master/.azurepipelines/templates/pr-gate-steps.yml" target="_blank">.azurepipelines/templates/pr-gate-steps.yml</a>.
+
+  That version is constantly tested against the code in the repository.
+
+  <a href="https://www.python.org/downloads/" target="_blank">Python Download Page</a>
+  </li>
+  <li>
+  <strong>C Compiler</strong>
+
+  A C compiler is needed to compile the firmware code.
+
+  Several options are available. This is an area where direct guidance cannot be provided.
+
+  You will need to choose a compiler supported on your host operating system and the particular firmware packages
+  you are building.
+
+  However, it is common to use:
+  <ul>
+    <li><a href="https://gcc.gnu.org/" target="_blank">GCC</a> on Linux</li>
+    <details>
+      <summary>Ubuntu GCC Installation Instructions</summary>
+      <code>apt-get update && apt-get install -y build-essential git nasm wget m4 bison flex uuid-dev python unzip acpica-tools gcc-multilib</code>
+    </details>
+    <li><a href="https://visualstudio.microsoft.com/downloads/" target="_blank">Visual Studio</a> on Windows</li>
+    <details>
+      <summary>Visual Studio Installation Instructions (Windows)</summary>
+      <br>
+      <details>
+        <summary>Visual Studio 2022 Installation Instructions</summary>
+        <hr>
+        <p>
+          Click to download <a href="https://aka.ms/vs/17/release/vs_BuildTools.exe" target="_blank">Visual Studio 2022 Build Tools</a>
+        </p>
+        <ol>
+          <li>
+            Open an <strong>Administrator Command Prompt</strong> by right-clicking on <strong>Command Prompt</strong>
+            and select <strong>Run as Administrator</strong>
+          </li>
+          <li>
+            Change to the directory where you downloaded the <code>vs_BuildTools.exe</code> file
+            (e.g. <code>C:\Downloads</code>)
+          </li>
+          <li>
+            Enter the following command:
+            <br>
+            <kbd>
+              start /w vs_BuildTools.exe --quiet --wait --norestart --nocache --installPath C:\BuildTools ^
+              --add Microsoft.VisualStudio.Component.VC.CoreBuildTools --add 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
+            </kbd>
+          </li>
+        </ol>
+        <hr>
+    </details>
+    <details>
+      <summary>Visual Studio 2019 Installation Instructions</summary>
+      <hr>
+      <p>
+        Click to download <a href="https://aka.ms/vs/16/release/vs_BuildTools.exe" target="_blank">Visual Studio 2019 Build Tools</a>
+      </p>
+      <ol>
+        <li>
+          Open an <strong>Administrator Command Prompt</strong> by right-clicking on <strong>Command Prompt</strong>
+          and select <strong>Run as Administrator</strong>
+        </li>
+        <li>
+          Change to the directory where you downloaded the <code>vs_BuildTools.exe</code> file
+          (e.g. <code>C:\Downloads</code>)
+        </li>
+        <li>
+          Enter the following command:
+          <br>
+          <kbd>
+            start /w vs_BuildTools.exe --quiet --wait --norestart --nocache --installPath C:\BuildTools ^
+            --add Microsoft.VisualStudio.Component.VC.CoreBuildTools --add Microsoft.VisualStudio.Component.VC.Tools.x86.x64 ^
+            --add Microsoft.VisualStudio.Component.Windows10SDK.19041 --add Microsoft.VisualStudio.Component.VC.Tools.ARM ^
+            --add Microsoft.VisualStudio.Component.VC.Tools.ARM64
+          </kbd>
+        </li>
+      </ol>
+      <hr>
+    </details>
+    <details>
+      <summary>Visual Studio 2017 Installation Instructions</summary>
+      <hr>
+      <p>
+        Click to download <a href="https://aka.ms/vs/15/release/vs_BuildTools.exe" target="_blank">Visual Studio 2017 Build Tools</a>
+      </p>
+      <ol>
+        <li>
+        Open an <strong>Administrator Command Prompt</strong> by right-clicking on <strong>Command Prompt</strong> and
+        select <strong>Run as Administrator</strong>
+        </li>
+        <li>
+        Change to the directory where you downloaded the <code>vs_BuildTools.exe</code> file
+        (e.g. <code>C:\Downloads</code>)
+        </li>
+        <li>
+          Enter the following command:
+          <br>
+          <kbd>
+            start /w vs_BuildTools.exe --quiet --wait --norestart --nocache --installPath C:\BuildTools ^
+            --add Microsoft.VisualStudio.Component.VC.CoreBuildTools --add Microsoft.VisualStudio.Component.VC.Tools.x86.x64 ^
+            --add Microsoft.VisualStudio.Component.Windows10SDK.17763 --add Microsoft.VisualStudio.Component.VC.Tools.ARM ^
+            --add Microsoft.VisualStudio.Component.VC.Tools.ARM64
+          </kbd>
+        </li>
+      </ol>
+      <hr>
+    </details>
+    <p>
+      <ul>
+        <li>
+          Note: You can find the latest version of Visual Studio supported by edk2 on the
+          <a href="https://github.com/tianocore/edk2#core-ci-build-status" target="_blank">CI Status</a> section of the
+          repo readme file.
+        </li>
+        <li>
+          Note: If you still run into build problems finding tools in the SDK, try installing the Windows SDK manually
+          using the following instructions.
+        </li>
+      </ul>
+    </p>
+    <details>
+      <summary>Optional: Install the Windows SDK manually</summary>
+      <hr>
+      <p>
+        Download the Windows Software Development Kit (SDK) from
+        <a href="https://developer.microsoft.com/en-us/windows/downloads/windows-sdk/" target="_blank">Windows Dev Center - Windows SDK</a>
+      </p>
+      <p>
+        Follow the default options until you reach the "<strong>Select the features you want to install</strong>" page.
+      </p>
+      Select the following options:
+      <ul>
+        <li>Windows SDK Signing Tools for Desktop Apps</li>
+        <li>Windows SDK for UWP Managed Apps</li>
+        <li>Windows SDK for UWP C++ Apps</li>
+        <li>Windows SDK for Desktop C++ x86 Apps</li>
+        <li>Windows SDK for Desktop C++ amd64 Apps</li>
+        <li>Windows SDK for Desktop C++ arm Apps</li>
+      </ul>
+      <p>
+        Click <strong>Download</strong> and complete the installation process.
+      </p>
+      <hr>
+    </details>
+  </ul>
+  </li>
+  <li>
+  <strong>Mono (Linux)</strong>
+    <p><a href="https://www.mono-project.com" target="_blank">Mono</a> needs to be installed on Linux.</p>
+    <kbd>apt-get install mono-complete</kbd>
+  </li>
+  </ul>
+  <hr>
+</details>
+
+1. Clone the edk2 repo
+   - Open a command-prompt in the directory where you would like to keep the 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.
+      - <details>
+        <summary>Linux Instructions</summary>
+        <code>python -m venv .venv</code>
+        <br>
+        <code>source .venv/bin/activate</code>
+        </details>
+      - <details>
+        <summary>Windows Instructions</summary>
+        <code>py -m venv .venv</code>
+        <br>
+        <code>.venv\Scripts\activate.bat</code>
+        </details>
+
+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 environments in this repository.
+
+That's it!
+
+Your terminal may now indicate that a virtual environment is active by showing `(.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 example, it depends on git submodules, Python pip
+modules, tools in the form of application binaries, etc. If the corresponding 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=<your tag here>`
+
+      - Common options:
+        - `-p <pkg1,pkg2,pkg3>`: To build only certain packages use a comma-separated list
+        - `-a <arch1,arch2,arch3>`: To run only certain architectures use a comma-separated list
+        - `-t <target1,target2>`: To run only tests related to certain targets 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_build` and `stuart_build` commands.
+
+---
+
+## Examples
+
+<details>
+  <summary>Example: I want to build MdeModulePkg to test a change I made there.</summary>
+  <hr>
+  <p>
+    The important parameter here is the <code>-p</code> parameter which specifies that <code>MdeModulePkg</code>
+    should be built.
+  </p>
+  <p>
+    The example below uses:
+    <ul>
+      <li>
+        The <code>TOOL_CHAIN_TAG</code> parameter to specify the build should use <code>VS2019</code>
+        (Visual Studio 2019).
+      </li>
+      <li>
+        The <code>-a</code> parameter is used to specify that the <code>IA32</code> and <code>X64</code> architectures
+        should be built.
+      </li>
+    </ul>
+  </p>
+
+  <kbd>stuart_ci_build -c .pytool/CISettings.py -p MdeModulePkg -a IA32,X64 TOOL_CHAIN_TAG=VS2019</kbd>
+  <hr>
+</details>
+
+<details>
+  <summary>Example: I want to build OvmfPkg to test a change I made there.</summary>
+  <hr>
+  <p>
+    OvmfPkg is considered a "platform firmware" for the
+    <a href="https://www.qemu.org/" target="_blank">QEMU open-source emulator</a>.
+  </p>
+  <ul>
+    <li>
+      Therefore, it provides a platform build file (see <a href="#what-is-platformbuild-py">What is PlatformBuild.py?</a>)
+      <ul>
+        <li>
+          Located at <a href="https://github.com/tianocore/edk2/blob/master/OvmfPkg/PlatformCI/PlatformBuild.py" target="_blank">OvmfPkg/PlatformCI/PlatformBuild.py</a>
+        </li>
+      </ul>
+    </li>
+    <li>
+      Because we are building a platform build file, the build command will be <code>stuart_build</code> instead of
+      <code>stuart_ci_build</code> to compile the code
+    </li>
+  </ul>
+
+  <kbd>stuart_build -c PlatformBuild.py -p OvmfPkg -a IA32,X64 TOOL_CHAIN_TAG=VS2019</kbd>
+
+  <p>
+    If you want to run CI checks such as CI plugins, you can use <code>stuart_ci_build</code> with the CI build file.
+  </p>
+
+  <kbd>stuart_ci_build -c .pytool/CISettings.py -p OvmfPkg -a IA32,X64 TOOL_CHAIN_TAG=VS2019</kbd>
+  <hr>
+</details>
+
+<details>
+  <summary>Example: I want to build OvmfPkg and automatically run with my firmware after build.</summary>
+  <hr>
+  <p>
+    OvmfPkg is considered a "platform firmware" for the
+    <a href="https://www.qemu.org/" target="_blank">QEMU open-source emulator</a>.
+  </p>
+
+  <ul>
+    <li>
+      Therefore, it provides a platform build file (see <a href="#what-is-platformbuild-py">What is PlatformBuild.py?</a>)
+      <ul>
+        <li>
+        Located at <a href="https://github.com/tianocore/edk2/blob/master/OvmfPkg/PlatformCI/PlatformBuild.py" target="_blank">OvmfPkg/PlatformCI/PlatformBuild.py</a>
+        </li>
+      </ul>
+    </li>
+    <li>
+      Because we are building a platform build file, the build command will be <code>stuart_build</code> instead of
+      <code>stuart_ci_build</code>
+    </li>
+  </ul>
+
+  <p>
+    To see what parameters are supported by this platform build file (at the time this page was written), we can pass
+    the <code>--help</code> argument to the <code>stuart_build</code> command:
+  </p>
+
+  <pre>
+    ❯ stuart_build -c PlatformBuild.py --help
+    usage: stuart_build [-h] [--SKIPBUILD] [--SKIPPREBUILD] [--SKIPPOSTBUILD] [--FLASHONLY] [--FLASHROM]
+                        [--UPDATECONF] [--CLEAN] [--CLEANONLY] [--OUTPUTCONFIG 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 replaced with latest template files
+      --CLEAN, --clean, --CLEAN
+                            Clean. Remove all old build artifacts and intermediate files
+      --CLEANONLY, --cleanonly, --CleanOnly
+                            Clean Only. Do clean operation and don't build just exit.
+      --OUTPUTCONFIG OUTPUTCONFIG, --outputconfig OUTPUTCONFIG, --OutputConfig 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 IA32 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:
+      <key>=<value>              - Set an env variable for the pre/post build process
+      BLD_*_<key>=<value>        - Set a build flag for all build types
+                                  (key=value will get passed to build process)
+      BLD_<TARGET>_<key>=<value> - Set a build flag for build type of <target>
+                                  (key=value will get passed to build process for given build type)
+  </pre>
+  <p>
+    The <code>--flashonly</code> and <code>--flashrom</code> commands are especially useful with OvmfPkg. They
+    automatically load QEMU with the newly built firmware.
+  </p>
+  <p>
+    The example below uses:
+    <ul>
+      <li>
+        The <code>TOOL_CHAIN_TAG</code> parameter to specify that the build should use <code>GCC5</code>
+        to build with GCC.
+      </li>
+      <li>
+        The <code>-a</code> parameter is used to specify the <code>IA32</code> and <code>X64</code> architectures should be
+        built.
+      </li>
+      <li>
+        The <code>--flashrom</code> parameter is used to load the firmware in QEMU and boot QEMU after the firmware build
+        is completed.
+      </li>
+    </ul>
+  </p>
+
+  <kbd>stuart_build -c PlatformBuild.py -p OvmfPkg -a IA32,X64 TOOL_CHAIN_TAG=GCC5 --flashrom</kbd>
+  <hr>
+</details>
+
+<details>
+  <summary id="example-i-want-to-build-basetools">Example: I want to build BaseTools.</summary>
+  <hr>
+  <a href="#what-are-basetools">BaseTools</a> has its own build script that leverages
+  <a href="#what-are-edk2-pytools">edk2-pytools</a> to build the BaseTools applications.
+  <br>
+  <br>
+  <details>
+    <summary>Linux (Ubuntu) Pre-Steps</summary>
+    <kbd>sudo apt update</kbd>
+    <br>
+    <kbd>sudo apt install build-essential uuid-dev</kbd>
+  </details>
+  <p>
+    The file <a href="https://github.com/tianocore/edk2/blob/master/BaseTools/Edk2ToolsBuild.py" target="_blank">BaseTools/Edk2ToolsBuild.py</a>
+    can be called as a standalone Python script. You just need to pass the tool chain tag you would like to build with.
+  </p>
+  <p>
+    Example:
+    <kbd>python BaseTools/Edk2ToolsBuild.py -t GCC5</kbd>
+  </p>
+  <hr>
+</details>
+
+<details>
+  <summary>Example: I just want to check if my changes will pass all the non-compiler checks in CI.</summary>
+  <hr>
+  <p>
+    The <code>NO-TARGET</code> build target specifies that the actual firmware 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
+    (<a href="#what-are-plugins">plugins</a>).
+  </p>
+  <p>
+    In the following example, the CI plugins will be run against all packages supported by the
+    <a href="#what-is-ci-settings-py">CISettings.py</a> file.
+  </p>
+  <kbd>stuart_ci_build -c .pytool/CISettings.py -t NO-TARGET</kbd>
+  <p>
+    The CI checks could be run against a single package (or a selection of packages) by passing the package names to
+    with the <code>-p</code> parameter.
+  </p>
+  <kbd>stuart_ci_build -c .pytool/CISettings.py -p MdePkg,UefiCpuPkg -t NO-TARGET</kbd>
+  <hr>
+</details>
+
+<details>
+  <summary>
+    Example: I want to fix all the spelling errors in my package. How do I just run the spell check plugin?
+  </summary>
+  <hr>
+  <p>
+    Plugins are automatically discovered in the workspace by stuart.
+  </p>
+  <p>
+    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 can then test with the remaining plugins and
+    then use git to restore the deleted plugin directories back when done testing.
+  </p>
+  <p>
+    For example, to only test with the <code>SpellCheck</code> plugin, delete every other plugin folder from
+    <a href="https://github.com/tianocore/edk2/tree/master/.pytool/Plugin" target="_blank">.pytool/Plugin</a> in your
+    workspace.
+  </p>
+  <p>
+    Run the command to only perform CI checks:
+    <br>
+    <kbd>stuart_ci_build -c .pytool/CISettings.py -t NO-TARGET</kbd>
+  </p>
+  <p>
+    When done, restore the other plugin directories:
+    <br>
+    <kbd>git restore .pytool/Plugin/**</kbd>
+  </p>
+  <hr>
+</details>
+
+## Common Questions
+
+<details>
+  <summary id="what-is-ci">What is CI?</summary>
+  <hr>
+  <p>
+    <a href="https://en.wikipedia.org/wiki/Continuous_integration" target="_blank">Continuous Integration</a>
+  </p>
+  <p>
+    Continuous integration is used in edk2 to test new contributions before they are merged to the edk2 main branch.
+    Stuart is used within the edk2 CI process to pull build dependencies and build the code.
+  </p>
+  <p>
+    You can use stuart to perform the same CI checks locally that are done on the server (see the examples section).
+  </p>
+  <p>
+    Also see <a href="https://github.com/tianocore/tianocore.github.io/wiki/EDK-II-Continuous-Integration" target="_blank">EDK II Continuous Integration</a>.
+  </p>
+  <hr>
+</details>
+
+<details>
+  <summary id="what-are-basetools">What are BaseTools?</summary>
+  <hr>
+  <p>A collection of build related tools for edk2.</p>
+  <p>
+    Examples:
+
+    <ul>
+      <li>AutoGen</li>
+      <li>Build</li>
+      <li>GenSec</li>
+      <li>GenFV</li>
+      <li>GenFW</li>
+      <li>GenRds</li>
+    </ul>
+  </p>
+  <p>
+    Each tool has a user manual located in <a href="https://github.com/tianocore/edk2/tree/master/BaseTools/UserManuals" target="_blank">BaseTools/UserManuals</a>.
+  </p>
+  <p>
+    A more complete list of BaseTools is located in the <a href="https://github.com/tianocore/edk2/tree/master/BaseTools/UserManuals" target="_blank">EDK II Tools List</a>.
+  </p>
+  <hr>
+</details>
+
+<details>
+  <summary id="what-are-edk2-pytools">What are edk2-pytools?</summary>
+  <hr>
+  <p>A collection of Python code for working with edk2.</p>
+  <ul>
+    <li>
+      <a href="https://github.com/tianocore/edk2-pytool-library" target="_blank">edk2-pytool-library</a> - 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.
+    </li>
+    <li>
+      <a href="https://github.com/tianocore/edk2-pytool-extensions" target="_blank">edk2-pytool-extensions</a> - A
+      Python project that consists of command line and other tools and extensions for building and maintaining an edk2
+      based UEFI firmware code tree.
+    </li>
+  </ul>
+  <hr>
+</details>
+
+<details>
+  <summary id="what-is-ci-settings-py">What is CISettings.py?</summary>
+  <hr>
+  <p>
+    <code>CISettings.py</code> is a common name given to a configuration file used with Stuart for CI. It is often
+    stored in a folder named <code>.pytools</code> in the root of a repository. So you'll likely encounter commands
+    like the following be used with the file:
+  </p>
+
+  <ul>
+    <li>
+      <kbd>
+      stuart_ci_setup -c .pytool/CISettings.py TOOL_CHAIN_TAG=PUT_TAG_VALUE_HERE
+      </kbd>
+    </li>
+    <li>
+      <kbd>
+      stuart_update -c .pytool/CISettings.py TOOL_CHAIN_TAG=PUT_TAG_VALUE_HERE
+      </kbd>
+    </li>
+    <li>
+      <kbd>
+      stuart_ci_build -c .pytool/CISettings.py TOOL_CHAIN_TAG=PUT_TAG_VALUE_HERE
+      </kbd>
+    </li>
+  </ul>
+  <hr>
+</details>
+
+<details>
+  <summary id="what-is-platformbuild-py">What is PlatformBuild.py?</summary>
+  <hr>
+  <p>
+    <code>PlatformBuild.py</code> is a common name given to a configuration file used with Stuart for platform build.
+    It is often stored in the root directory of the package it builds.
+  </p>
+  <p>
+    For example:
+  </p>
+  <ul>
+    <li>
+      <kbd>
+      stuart_setup -c SomePkg/PlatformBuild.py TOOL_CHAIN_TAG=PUT_TAG_VALUE_HERE
+      </kbd>
+    </li>
+    <li>
+      <kbd>
+      stuart_update -c SomePkg/PlatformBuild.py TOOL_CHAIN_TAG=PUT_TAG_VALUE_HERE
+      </kbd>
+    </li>
+    <li>
+      <kbd>
+      stuart_build -c SomePkg/PlatformBuild.py TOOL_CHAIN_TAG=PUT_TAG_VALUE_HERE
+      </kbd>
+    </li>
+  </ul>
+  <p>
+    Like Stuart CI has "CI plugins", the build process has "build plugins". These can hook into the build in
+    "pre-build" or "post-build".
+  </p>
+  <blockquote>
+    Note: Build plugins will also run during CI if a CompilerPlugin is present that builds the code.
+  </blockquote>
+  <hr>
+</details>
+
+<details>
+  <summary id="stuart-ci-build-vs-stuart-build">
+    What is the difference between <code>stuart_ci_build</code> and <code>stuart_build</code>?
+  </summary>
+  <hr>
+  <ul>
+    <li>
+      <code>stuart_ci_build</code> - Runs CI plugins. By default, often runs CI on several packages at once. This
+      includes all of the checks needed to consider the code ready for integration to the mainline.
+    </li>
+    <li>
+      <code>stuart_build</code> - Does not run CI plugins. Builds one platform. Platforms often expose
+      platform-specific parameters as defined in their <code>PlatformBuild.py</code> file.
+    </li>
+  </ul>
+  <hr>
+</details>
+
+<details>
+  <summary id="what-does-stuart-ci-build-do">What does <code>stuart_ci_build</code> do exactly?</summary>
+  <hr>
+  <p>
+    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) compilation is performed during CI by a compiler
+    CI plugin.
+  </p>
+  <p>
+    Each plugin reports back a pass/fail status. If any plugin fails, CI fails. However, plugins usually provide some
+    level of customization in a "CI package configuration file". If this file is present, it is in the root of the
+    package with the naming convention <code>PkgName.ci.yaml</code>. For example,
+    <a href="https://github.com/tianocore/edk2/blob/master/MdePkg/MdePkg.ci.yaml" target="_blank">MdePkg.ci.yaml</a> is
+    the CI package configuration file for <code>MdePkg</code>. 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.
+  </p>
+  <p>
+    The two main places to look for CI settings are:
+    <ul>
+      <li>The CISettings.py file - Usually has repo-wide CI settings</li>
+      <li>The CI package configuration file - Has package-specific CI settings for a given package</li>
+    </ul>
+  </p>
+  <hr>
+</details>
+
+<details>
+  <summary id="how-do-i-get-more-detailed-error-info">
+    How do I get more detailed information if an error happens?
+  </summary>
+  <hr>
+  <p>
+    You can pass the <code>-v</code> argument to Stuart commands to get more detailed output.
+  </p>
+  <p>
+    Also, look in your <code>/Build</code> directory.
+  </p>
+  <p>
+    Each Stuart command produces a separate file. Open the file corresponding to the command you're using that has the
+    failure.
+  </p>
+  <ul>
+    <li><code>stuart_ci_setup</code> - <code>CISETUP.txt</code></li>
+    <li><code>stuart_setup</code> - <code>SETUPLOG.txt</code></li>
+    <li><code>stuart_update</code> - <code>UPDATE_LOG.txt</code></li>
+    <li><code>stuart_ci_build</code> - <code>CI_BUILDLOG.txt</code></li>
+    <li><code>stuart_build</code> - <code>BUILDLOG_PACKAGENAME.txt</code></li>
+  </ul>
+  <hr>
+</details>
+
+<details>
+  <summary id="what-are-plugins">What are "plugins"?</summary>
+  <hr>
+  <p>
+    The different types of plugins supported by Stuart and details about each type are available in the
+    <a href="https://github.com/tianocore/edk2-pytool-extensions/blob/master/docs/user/features/plugin_manager.md" target="_blank">edk2-pytool-extensions Plugin Manager</a>
+    page.
+  </p>
+  <hr>
+</details>
+
+<details>
+  <summary id="how-do-i-get-lower-level-technical-details">How do I get lower-level technical details?</summary>
+  <hr>
+  <p>
+    Start in the
+    <a href="https://github.com/tianocore/edk2-pytool-extensions/blob/master/docs/user/index.md" target="_blank">edk2-pytool-extensions User Documentation</a>.
+  </p>
+  <hr>
+</details>
-- 
2.28.0.windows.1

Re: [edk2-devel] [edk2-wiki][PATCH v3 1/4] Add initial How to Build with Stuart Document

[Rebecca Cran]

What tool do you use to write the pages?

It seems to be a mixture of markdown and HTML: for example I'm surprised 
to see things like "<strong>C Compiler</strong>" - I'd expect something 
like "**C Compiler**" instead.

-- 
Rebecca Cran


On 12/7/22 09:24, Michael Kubacki wrote:
> From: Michael Kubacki <michael.kubacki@microsoft.com>
> 
> 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 <sean.brogan@microsoft.com>
> Cc: Michael D Kinney <michael.d.kinney@intel.com>
> Cc: Liming Gao <gaoliming@byosoft.com.cn>
> Signed-off-by: Michael Kubacki <michael.kubacki@microsoft.com>
> ---
>   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".
> +
> +>💡 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.
> +
> +<details>
> +  <summary>Pre-requisites (Git, Python, Compiler)</summary>
> +  <hr>
> +
> +  <ul>
> +  <li>
> +  <strong>Git - Source Control Management (SCM) Tool</strong>
> +
> +  Git is the source control management tool used by this project.
> +
> +  You need <code>git</code> to pull the edk2 source code onto your system, make changes in the code, and submit
> +  your changes back to the GitHub repository.
> +
> +  <a href="https://git-scm.com/downloads" target="_blank">Git Download Page</a>
> +  </li>
> +  <li>
> +  <strong>Python</strong>
> +
> +  Python is a programming language that many of the edk2 build tools are written in.
> +
> +  You will need Python to run the edk2 build tools including <code>stuart</code>, which is written in Python.
> +
> +  It is recommended you install a Python version that is equal to the version used in the
> +  <code>UsePythonVersion@0</code> step in this file
> +  <a href="https://github.com/tianocore/edk2/blob/master/.azurepipelines/templates/pr-gate-steps.yml" target="_blank">.azurepipelines/templates/pr-gate-steps.yml</a>.
> +
> +  That version is constantly tested against the code in the repository.
> +
> +  <a href="https://www.python.org/downloads/" target="_blank">Python Download Page</a>
> +  </li>
> +  <li>
> +  <strong>C Compiler</strong>
> +
> +  A C compiler is needed to compile the firmware code.
> +
> +  Several options are available. This is an area where direct guidance cannot be provided.
> +
> +  You will need to choose a compiler supported on your host operating system and the particular firmware packages
> +  you are building.
> +
> +  However, it is common to use:
> +  <ul>
> +    <li><a href="https://gcc.gnu.org/" target="_blank">GCC</a> on Linux</li>
> +    <details>
> +      <summary>Ubuntu GCC Installation Instructions</summary>
> +      <code>apt-get update && apt-get install -y build-essential git nasm wget m4 bison flex uuid-dev python unzip acpica-tools gcc-multilib</code>
> +    </details>
> +    <li><a href="https://visualstudio.microsoft.com/downloads/" target="_blank">Visual Studio</a> on Windows</li>
> +    <details>
> +      <summary>Visual Studio Installation Instructions (Windows)</summary>
> +      <br>
> +      <details>
> +        <summary>Visual Studio 2022 Installation Instructions</summary>
> +        <hr>
> +        <p>
> +          Click to download <a href="https://aka.ms/vs/17/release/vs_BuildTools.exe" target="_blank">Visual Studio 2022 Build Tools</a>
> +        </p>
> +        <ol>
> +          <li>
> +            Open an <strong>Administrator Command Prompt</strong> by right-clicking on <strong>Command Prompt</strong>
> +            and select <strong>Run as Administrator</strong>
> +          </li>
> +          <li>
> +            Change to the directory where you downloaded the <code>vs_BuildTools.exe</code> file
> +            (e.g. <code>C:\Downloads</code>)
> +          </li>
> +          <li>
> +            Enter the following command:
> +            <br>
> +            <kbd>
> +              start /w vs_BuildTools.exe --quiet --wait --norestart --nocache --installPath C:\BuildTools ^
> +              --add Microsoft.VisualStudio.Component.VC.CoreBuildTools --add 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
> +            </kbd>
> +          </li>
> +        </ol>
> +        <hr>
> +    </details>
> +    <details>
> +      <summary>Visual Studio 2019 Installation Instructions</summary>
> +      <hr>
> +      <p>
> +        Click to download <a href="https://aka.ms/vs/16/release/vs_BuildTools.exe" target="_blank">Visual Studio 2019 Build Tools</a>
> +      </p>
> +      <ol>
> +        <li>
> +          Open an <strong>Administrator Command Prompt</strong> by right-clicking on <strong>Command Prompt</strong>
> +          and select <strong>Run as Administrator</strong>
> +        </li>
> +        <li>
> +          Change to the directory where you downloaded the <code>vs_BuildTools.exe</code> file
> +          (e.g. <code>C:\Downloads</code>)
> +        </li>
> +        <li>
> +          Enter the following command:
> +          <br>
> +          <kbd>
> +            start /w vs_BuildTools.exe --quiet --wait --norestart --nocache --installPath C:\BuildTools ^
> +            --add Microsoft.VisualStudio.Component.VC.CoreBuildTools --add Microsoft.VisualStudio.Component.VC.Tools.x86.x64 ^
> +            --add Microsoft.VisualStudio.Component.Windows10SDK.19041 --add Microsoft.VisualStudio.Component.VC.Tools.ARM ^
> +            --add Microsoft.VisualStudio.Component.VC.Tools.ARM64
> +          </kbd>
> +        </li>
> +      </ol>
> +      <hr>
> +    </details>
> +    <details>
> +      <summary>Visual Studio 2017 Installation Instructions</summary>
> +      <hr>
> +      <p>
> +        Click to download <a href="https://aka.ms/vs/15/release/vs_BuildTools.exe" target="_blank">Visual Studio 2017 Build Tools</a>
> +      </p>
> +      <ol>
> +        <li>
> +        Open an <strong>Administrator Command Prompt</strong> by right-clicking on <strong>Command Prompt</strong> and
> +        select <strong>Run as Administrator</strong>
> +        </li>
> +        <li>
> +        Change to the directory where you downloaded the <code>vs_BuildTools.exe</code> file
> +        (e.g. <code>C:\Downloads</code>)
> +        </li>
> +        <li>
> +          Enter the following command:
> +          <br>
> +          <kbd>
> +            start /w vs_BuildTools.exe --quiet --wait --norestart --nocache --installPath C:\BuildTools ^
> +            --add Microsoft.VisualStudio.Component.VC.CoreBuildTools --add Microsoft.VisualStudio.Component.VC.Tools.x86.x64 ^
> +            --add Microsoft.VisualStudio.Component.Windows10SDK.17763 --add Microsoft.VisualStudio.Component.VC.Tools.ARM ^
> +            --add Microsoft.VisualStudio.Component.VC.Tools.ARM64
> +          </kbd>
> +        </li>
> +      </ol>
> +      <hr>
> +    </details>
> +    <p>
> +      <ul>
> +        <li>
> +          Note: You can find the latest version of Visual Studio supported by edk2 on the
> +          <a href="https://github.com/tianocore/edk2#core-ci-build-status" target="_blank">CI Status</a> section of the
> +          repo readme file.
> +        </li>
> +        <li>
> +          Note: If you still run into build problems finding tools in the SDK, try installing the Windows SDK manually
> +          using the following instructions.
> +        </li>
> +      </ul>
> +    </p>
> +    <details>
> +      <summary>Optional: Install the Windows SDK manually</summary>
> +      <hr>
> +      <p>
> +        Download the Windows Software Development Kit (SDK) from
> +        <a href="https://developer.microsoft.com/en-us/windows/downloads/windows-sdk/" target="_blank">Windows Dev Center - Windows SDK</a>
> +      </p>
> +      <p>
> +        Follow the default options until you reach the "<strong>Select the features you want to install</strong>" page.
> +      </p>
> +      Select the following options:
> +      <ul>
> +        <li>Windows SDK Signing Tools for Desktop Apps</li>
> +        <li>Windows SDK for UWP Managed Apps</li>
> +        <li>Windows SDK for UWP C++ Apps</li>
> +        <li>Windows SDK for Desktop C++ x86 Apps</li>
> +        <li>Windows SDK for Desktop C++ amd64 Apps</li>
> +        <li>Windows SDK for Desktop C++ arm Apps</li>
> +      </ul>
> +      <p>
> +        Click <strong>Download</strong> and complete the installation process.
> +      </p>
> +      <hr>
> +    </details>
> +  </ul>
> +  </li>
> +  <li>
> +  <strong>Mono (Linux)</strong>
> +    <p><a href="https://www.mono-project.com" target="_blank">Mono</a> needs to be installed on Linux.</p>
> +    <kbd>apt-get install mono-complete</kbd>
> +  </li>
> +  </ul>
> +  <hr>
> +</details>
> +
> +1. Clone the edk2 repo
> +   - Open a command-prompt in the directory where you would like to keep the 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.
> +      - <details>
> +        <summary>Linux Instructions</summary>
> +        <code>python -m venv .venv</code>
> +        <br>
> +        <code>source .venv/bin/activate</code>
> +        </details>
> +      - <details>
> +        <summary>Windows Instructions</summary>
> +        <code>py -m venv .venv</code>
> +        <br>
> +        <code>.venv\Scripts\activate.bat</code>
> +        </details>
> +
> +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 environments in this repository.
> +
> +That's it!
> +
> +Your terminal may now indicate that a virtual environment is active by showing `(.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 example, it depends on git submodules, Python pip
> +modules, tools in the form of application binaries, etc. If the corresponding 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=<your tag here>`
> +
> +      - Common options:
> +        - `-p <pkg1,pkg2,pkg3>`: To build only certain packages use a comma-separated list
> +        - `-a <arch1,arch2,arch3>`: To run only certain architectures use a comma-separated list
> +        - `-t <target1,target2>`: To run only tests related to certain targets 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_build` and `stuart_build` commands.
> +
> +---
> +
> +## Examples
> +
> +<details>
> +  <summary>Example: I want to build MdeModulePkg to test a change I made there.</summary>
> +  <hr>
> +  <p>
> +    The important parameter here is the <code>-p</code> parameter which specifies that <code>MdeModulePkg</code>
> +    should be built.
> +  </p>
> +  <p>
> +    The example below uses:
> +    <ul>
> +      <li>
> +        The <code>TOOL_CHAIN_TAG</code> parameter to specify the build should use <code>VS2019</code>
> +        (Visual Studio 2019).
> +      </li>
> +      <li>
> +        The <code>-a</code> parameter is used to specify that the <code>IA32</code> and <code>X64</code> architectures
> +        should be built.
> +      </li>
> +    </ul>
> +  </p>
> +
> +  <kbd>stuart_ci_build -c .pytool/CISettings.py -p MdeModulePkg -a IA32,X64 TOOL_CHAIN_TAG=VS2019</kbd>
> +  <hr>
> +</details>
> +
> +<details>
> +  <summary>Example: I want to build OvmfPkg to test a change I made there.</summary>
> +  <hr>
> +  <p>
> +    OvmfPkg is considered a "platform firmware" for the
> +    <a href="https://www.qemu.org/" target="_blank">QEMU open-source emulator</a>.
> +  </p>
> +  <ul>
> +    <li>
> +      Therefore, it provides a platform build file (see <a href="#what-is-platformbuild-py">What is PlatformBuild.py?</a>)
> +      <ul>
> +        <li>
> +          Located at <a href="https://github.com/tianocore/edk2/blob/master/OvmfPkg/PlatformCI/PlatformBuild.py" target="_blank">OvmfPkg/PlatformCI/PlatformBuild.py</a>
> +        </li>
> +      </ul>
> +    </li>
> +    <li>
> +      Because we are building a platform build file, the build command will be <code>stuart_build</code> instead of
> +      <code>stuart_ci_build</code> to compile the code
> +    </li>
> +  </ul>
> +
> +  <kbd>stuart_build -c PlatformBuild.py -p OvmfPkg -a IA32,X64 TOOL_CHAIN_TAG=VS2019</kbd>
> +
> +  <p>
> +    If you want to run CI checks such as CI plugins, you can use <code>stuart_ci_build</code> with the CI build file.
> +  </p>
> +
> +  <kbd>stuart_ci_build -c .pytool/CISettings.py -p OvmfPkg -a IA32,X64 TOOL_CHAIN_TAG=VS2019</kbd>
> +  <hr>
> +</details>
> +
> +<details>
> +  <summary>Example: I want to build OvmfPkg and automatically run with my firmware after build.</summary>
> +  <hr>
> +  <p>
> +    OvmfPkg is considered a "platform firmware" for the
> +    <a href="https://www.qemu.org/" target="_blank">QEMU open-source emulator</a>.
> +  </p>
> +
> +  <ul>
> +    <li>
> +      Therefore, it provides a platform build file (see <a href="#what-is-platformbuild-py">What is PlatformBuild.py?</a>)
> +      <ul>
> +        <li>
> +        Located at <a href="https://github.com/tianocore/edk2/blob/master/OvmfPkg/PlatformCI/PlatformBuild.py" target="_blank">OvmfPkg/PlatformCI/PlatformBuild.py</a>
> +        </li>
> +      </ul>
> +    </li>
> +    <li>
> +      Because we are building a platform build file, the build command will be <code>stuart_build</code> instead of
> +      <code>stuart_ci_build</code>
> +    </li>
> +  </ul>
> +
> +  <p>
> +    To see what parameters are supported by this platform build file (at the time this page was written), we can pass
> +    the <code>--help</code> argument to the <code>stuart_build</code> command:
> +  </p>
> +
> +  <pre>
> +    ❯ stuart_build -c PlatformBuild.py --help
> +    usage: stuart_build [-h] [--SKIPBUILD] [--SKIPPREBUILD] [--SKIPPOSTBUILD] [--FLASHONLY] [--FLASHROM]
> +                        [--UPDATECONF] [--CLEAN] [--CLEANONLY] [--OUTPUTCONFIG 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 replaced with latest template files
> +      --CLEAN, --clean, --CLEAN
> +                            Clean. Remove all old build artifacts and intermediate files
> +      --CLEANONLY, --cleanonly, --CleanOnly
> +                            Clean Only. Do clean operation and don't build just exit.
> +      --OUTPUTCONFIG OUTPUTCONFIG, --outputconfig OUTPUTCONFIG, --OutputConfig 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 IA32 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:
> +      <key>=<value>              - Set an env variable for the pre/post build process
> +      BLD_*_<key>=<value>        - Set a build flag for all build types
> +                                  (key=value will get passed to build process)
> +      BLD_<TARGET>_<key>=<value> - Set a build flag for build type of <target>
> +                                  (key=value will get passed to build process for given build type)
> +  </pre>
> +  <p>
> +    The <code>--flashonly</code> and <code>--flashrom</code> commands are especially useful with OvmfPkg. They
> +    automatically load QEMU with the newly built firmware.
> +  </p>
> +  <p>
> +    The example below uses:
> +    <ul>
> +      <li>
> +        The <code>TOOL_CHAIN_TAG</code> parameter to specify that the build should use <code>GCC5</code>
> +        to build with GCC.
> +      </li>
> +      <li>
> +        The <code>-a</code> parameter is used to specify the <code>IA32</code> and <code>X64</code> architectures should be
> +        built.
> +      </li>
> +      <li>
> +        The <code>--flashrom</code> parameter is used to load the firmware in QEMU and boot QEMU after the firmware build
> +        is completed.
> +      </li>
> +    </ul>
> +  </p>
> +
> +  <kbd>stuart_build -c PlatformBuild.py -p OvmfPkg -a IA32,X64 TOOL_CHAIN_TAG=GCC5 --flashrom</kbd>
> +  <hr>
> +</details>
> +
> +<details>
> +  <summary id="example-i-want-to-build-basetools">Example: I want to build BaseTools.</summary>
> +  <hr>
> +  <a href="#what-are-basetools">BaseTools</a> has its own build script that leverages
> +  <a href="#what-are-edk2-pytools">edk2-pytools</a> to build the BaseTools applications.
> +  <br>
> +  <br>
> +  <details>
> +    <summary>Linux (Ubuntu) Pre-Steps</summary>
> +    <kbd>sudo apt update</kbd>
> +    <br>
> +    <kbd>sudo apt install build-essential uuid-dev</kbd>
> +  </details>
> +  <p>
> +    The file <a href="https://github.com/tianocore/edk2/blob/master/BaseTools/Edk2ToolsBuild.py" target="_blank">BaseTools/Edk2ToolsBuild.py</a>
> +    can be called as a standalone Python script. You just need to pass the tool chain tag you would like to build with.
> +  </p>
> +  <p>
> +    Example:
> +    <kbd>python BaseTools/Edk2ToolsBuild.py -t GCC5</kbd>
> +  </p>
> +  <hr>
> +</details>
> +
> +<details>
> +  <summary>Example: I just want to check if my changes will pass all the non-compiler checks in CI.</summary>
> +  <hr>
> +  <p>
> +    The <code>NO-TARGET</code> build target specifies that the actual firmware 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
> +    (<a href="#what-are-plugins">plugins</a>).
> +  </p>
> +  <p>
> +    In the following example, the CI plugins will be run against all packages supported by the
> +    <a href="#what-is-ci-settings-py">CISettings.py</a> file.
> +  </p>
> +  <kbd>stuart_ci_build -c .pytool/CISettings.py -t NO-TARGET</kbd>
> +  <p>
> +    The CI checks could be run against a single package (or a selection of packages) by passing the package names to
> +    with the <code>-p</code> parameter.
> +  </p>
> +  <kbd>stuart_ci_build -c .pytool/CISettings.py -p MdePkg,UefiCpuPkg -t NO-TARGET</kbd>
> +  <hr>
> +</details>
> +
> +<details>
> +  <summary>
> +    Example: I want to fix all the spelling errors in my package. How do I just run the spell check plugin?
> +  </summary>
> +  <hr>
> +  <p>
> +    Plugins are automatically discovered in the workspace by stuart.
> +  </p>
> +  <p>
> +    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 can then test with the remaining plugins and
> +    then use git to restore the deleted plugin directories back when done testing.
> +  </p>
> +  <p>
> +    For example, to only test with the <code>SpellCheck</code> plugin, delete every other plugin folder from
> +    <a href="https://github.com/tianocore/edk2/tree/master/.pytool/Plugin" target="_blank">.pytool/Plugin</a> in your
> +    workspace.
> +  </p>
> +  <p>
> +    Run the command to only perform CI checks:
> +    <br>
> +    <kbd>stuart_ci_build -c .pytool/CISettings.py -t NO-TARGET</kbd>
> +  </p>
> +  <p>
> +    When done, restore the other plugin directories:
> +    <br>
> +    <kbd>git restore .pytool/Plugin/**</kbd>
> +  </p>
> +  <hr>
> +</details>
> +
> +## Common Questions
> +
> +<details>
> +  <summary id="what-is-ci">What is CI?</summary>
> +  <hr>
> +  <p>
> +    <a href="https://en.wikipedia.org/wiki/Continuous_integration" target="_blank">Continuous Integration</a>
> +  </p>
> +  <p>
> +    Continuous integration is used in edk2 to test new contributions before they are merged to the edk2 main branch.
> +    Stuart is used within the edk2 CI process to pull build dependencies and build the code.
> +  </p>
> +  <p>
> +    You can use stuart to perform the same CI checks locally that are done on the server (see the examples section).
> +  </p>
> +  <p>
> +    Also see <a href="https://github.com/tianocore/tianocore.github.io/wiki/EDK-II-Continuous-Integration" target="_blank">EDK II Continuous Integration</a>.
> +  </p>
> +  <hr>
> +</details>
> +
> +<details>
> +  <summary id="what-are-basetools">What are BaseTools?</summary>
> +  <hr>
> +  <p>A collection of build related tools for edk2.</p>
> +  <p>
> +    Examples:
> +
> +    <ul>
> +      <li>AutoGen</li>
> +      <li>Build</li>
> +      <li>GenSec</li>
> +      <li>GenFV</li>
> +      <li>GenFW</li>
> +      <li>GenRds</li>
> +    </ul>
> +  </p>
> +  <p>
> +    Each tool has a user manual located in <a href="https://github.com/tianocore/edk2/tree/master/BaseTools/UserManuals" target="_blank">BaseTools/UserManuals</a>.
> +  </p>
> +  <p>
> +    A more complete list of BaseTools is located in the <a href="https://github.com/tianocore/edk2/tree/master/BaseTools/UserManuals" target="_blank">EDK II Tools List</a>.
> +  </p>
> +  <hr>
> +</details>
> +
> +<details>
> +  <summary id="what-are-edk2-pytools">What are edk2-pytools?</summary>
> +  <hr>
> +  <p>A collection of Python code for working with edk2.</p>
> +  <ul>
> +    <li>
> +      <a href="https://github.com/tianocore/edk2-pytool-library" target="_blank">edk2-pytool-library</a> - 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.
> +    </li>
> +    <li>
> +      <a href="https://github.com/tianocore/edk2-pytool-extensions" target="_blank">edk2-pytool-extensions</a> - A
> +      Python project that consists of command line and other tools and extensions for building and maintaining an edk2
> +      based UEFI firmware code tree.
> +    </li>
> +  </ul>
> +  <hr>
> +</details>
> +
> +<details>
> +  <summary id="what-is-ci-settings-py">What is CISettings.py?</summary>
> +  <hr>
> +  <p>
> +    <code>CISettings.py</code> is a common name given to a configuration file used with Stuart for CI. It is often
> +    stored in a folder named <code>.pytools</code> in the root of a repository. So you'll likely encounter commands
> +    like the following be used with the file:
> +  </p>
> +
> +  <ul>
> +    <li>
> +      <kbd>
> +      stuart_ci_setup -c .pytool/CISettings.py TOOL_CHAIN_TAG=PUT_TAG_VALUE_HERE
> +      </kbd>
> +    </li>
> +    <li>
> +      <kbd>
> +      stuart_update -c .pytool/CISettings.py TOOL_CHAIN_TAG=PUT_TAG_VALUE_HERE
> +      </kbd>
> +    </li>
> +    <li>
> +      <kbd>
> +      stuart_ci_build -c .pytool/CISettings.py TOOL_CHAIN_TAG=PUT_TAG_VALUE_HERE
> +      </kbd>
> +    </li>
> +  </ul>
> +  <hr>
> +</details>
> +
> +<details>
> +  <summary id="what-is-platformbuild-py">What is PlatformBuild.py?</summary>
> +  <hr>
> +  <p>
> +    <code>PlatformBuild.py</code> is a common name given to a configuration file used with Stuart for platform build.
> +    It is often stored in the root directory of the package it builds.
> +  </p>
> +  <p>
> +    For example:
> +  </p>
> +  <ul>
> +    <li>
> +      <kbd>
> +      stuart_setup -c SomePkg/PlatformBuild.py TOOL_CHAIN_TAG=PUT_TAG_VALUE_HERE
> +      </kbd>
> +    </li>
> +    <li>
> +      <kbd>
> +      stuart_update -c SomePkg/PlatformBuild.py TOOL_CHAIN_TAG=PUT_TAG_VALUE_HERE
> +      </kbd>
> +    </li>
> +    <li>
> +      <kbd>
> +      stuart_build -c SomePkg/PlatformBuild.py TOOL_CHAIN_TAG=PUT_TAG_VALUE_HERE
> +      </kbd>
> +    </li>
> +  </ul>
> +  <p>
> +    Like Stuart CI has "CI plugins", the build process has "build plugins". These can hook into the build in
> +    "pre-build" or "post-build".
> +  </p>
> +  <blockquote>
> +    Note: Build plugins will also run during CI if a CompilerPlugin is present that builds the code.
> +  </blockquote>
> +  <hr>
> +</details>
> +
> +<details>
> +  <summary id="stuart-ci-build-vs-stuart-build">
> +    What is the difference between <code>stuart_ci_build</code> and <code>stuart_build</code>?
> +  </summary>
> +  <hr>
> +  <ul>
> +    <li>
> +      <code>stuart_ci_build</code> - Runs CI plugins. By default, often runs CI on several packages at once. This
> +      includes all of the checks needed to consider the code ready for integration to the mainline.
> +    </li>
> +    <li>
> +      <code>stuart_build</code> - Does not run CI plugins. Builds one platform. Platforms often expose
> +      platform-specific parameters as defined in their <code>PlatformBuild.py</code> file.
> +    </li>
> +  </ul>
> +  <hr>
> +</details>
> +
> +<details>
> +  <summary id="what-does-stuart-ci-build-do">What does <code>stuart_ci_build</code> do exactly?</summary>
> +  <hr>
> +  <p>
> +    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) compilation is performed during CI by a compiler
> +    CI plugin.
> +  </p>
> +  <p>
> +    Each plugin reports back a pass/fail status. If any plugin fails, CI fails. However, plugins usually provide some
> +    level of customization in a "CI package configuration file". If this file is present, it is in the root of the
> +    package with the naming convention <code>PkgName.ci.yaml</code>. For example,
> +    <a href="https://github.com/tianocore/edk2/blob/master/MdePkg/MdePkg.ci.yaml" target="_blank">MdePkg.ci.yaml</a> is
> +    the CI package configuration file for <code>MdePkg</code>. 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.
> +  </p>
> +  <p>
> +    The two main places to look for CI settings are:
> +    <ul>
> +      <li>The CISettings.py file - Usually has repo-wide CI settings</li>
> +      <li>The CI package configuration file - Has package-specific CI settings for a given package</li>
> +    </ul>
> +  </p>
> +  <hr>
> +</details>
> +
> +<details>
> +  <summary id="how-do-i-get-more-detailed-error-info">
> +    How do I get more detailed information if an error happens?
> +  </summary>
> +  <hr>
> +  <p>
> +    You can pass the <code>-v</code> argument to Stuart commands to get more detailed output.
> +  </p>
> +  <p>
> +    Also, look in your <code>/Build</code> directory.
> +  </p>
> +  <p>
> +    Each Stuart command produces a separate file. Open the file corresponding to the command you're using that has the
> +    failure.
> +  </p>
> +  <ul>
> +    <li><code>stuart_ci_setup</code> - <code>CISETUP.txt</code></li>
> +    <li><code>stuart_setup</code> - <code>SETUPLOG.txt</code></li>
> +    <li><code>stuart_update</code> - <code>UPDATE_LOG.txt</code></li>
> +    <li><code>stuart_ci_build</code> - <code>CI_BUILDLOG.txt</code></li>
> +    <li><code>stuart_build</code> - <code>BUILDLOG_PACKAGENAME.txt</code></li>
> +  </ul>
> +  <hr>
> +</details>
> +
> +<details>
> +  <summary id="what-are-plugins">What are "plugins"?</summary>
> +  <hr>
> +  <p>
> +    The different types of plugins supported by Stuart and details about each type are available in the
> +    <a href="https://github.com/tianocore/edk2-pytool-extensions/blob/master/docs/user/features/plugin_manager.md" target="_blank">edk2-pytool-extensions Plugin Manager</a>
> +    page.
> +  </p>
> +  <hr>
> +</details>
> +
> +<details>
> +  <summary id="how-do-i-get-lower-level-technical-details">How do I get lower-level technical details?</summary>
> +  <hr>
> +  <p>
> +    Start in the
> +    <a href="https://github.com/tianocore/edk2-pytool-extensions/blob/master/docs/user/index.md" target="_blank">edk2-pytool-extensions User Documentation</a>.
> +  </p>
> +  <hr>
> +</details>

Re: [edk2-devel] [edk2-wiki][PATCH v3 1/4] Add initial How to Build with Stuart Document

[Michael Kubacki]

I write it by hand. HTML comes in because I'm using collapsing content 
via <summary> sections. Once in those sections, normal markdown 
formatting does not apply. I've limited HTML usage in those sections to 
very simple tags that mostly map directly to features allowed in 
markdown formatting as well (<strong> -> **, <a> -> [](), <code> -> ``, 
etc.)

Thanks,
Michael

On 12/7/2022 11:47 PM, Rebecca Cran wrote:
> What tool do you use to write the pages?
> 
> It seems to be a mixture of markdown and HTML: for example I'm surprised 
> to see things like "<strong>C Compiler</strong>" - I'd expect something 
> like "**C Compiler**" instead.
> 

Re: [edk2-devel] [edk2-wiki][PATCH v3 1/4] Add initial How to Build with Stuart Document

[Rebecca Cran]

Ah, thanks for the explanation!

On 12/8/22 07:21, Michael Kubacki wrote:
> I write it by hand. HTML comes in because I'm using collapsing content 
> via <summary> sections. Once in those sections, normal markdown 
> formatting does not apply. I've limited HTML usage in those sections to 
> very simple tags that mostly map directly to features allowed in 
> markdown formatting as well (<strong> -> **, <a> -> [](), <code> -> ``, 
> etc.)
> 
> Thanks,
> Michael
> 
> On 12/7/2022 11:47 PM, Rebecca Cran wrote:
>> What tool do you use to write the pages?
>>
>> It seems to be a mixture of markdown and HTML: for example I'm 
>> surprised to see things like "<strong>C Compiler</strong>" - I'd 
>> expect something like "**C Compiler**" instead.
>>

Re: [edk2-devel] [edk2-wiki][PATCH v3 1/4] Add initial How to Build with Stuart Document

[Rebecca Cran]

According to 
https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-collapsed-sections, 
it looks like normal markdown _should_ apply within collapsed sections?


I noticed a few problems with 
https://github.com/tianocore/tianocore.github.io/wiki/How-to-Build-With-Stuart 
:


Example: git clone edk2

Should probably be: git clone https://github.com/tianocore/edk2.git


The Linux instructions for creating a python virtual environment should 
probably be:

python3 -m venv .venv


Though I've been installing the stuart tools into ~/.local/bin which 
allows you to skip the step of using a virtual environment.


Lastly, the Git Submodules step says to use --recursive, which I seem to 
recall other instructions suggesting _not_ to use, since it's not needed.


-- 
Rebecca Cran


On 12/8/22 07:21, Michael Kubacki wrote:
> I write it by hand. HTML comes in because I'm using collapsing content 
> via <summary> sections. Once in those sections, normal markdown 
> formatting does not apply. I've limited HTML usage in those sections 
> to very simple tags that mostly map directly to features allowed in 
> markdown formatting as well (<strong> -> **, <a> -> [](), <code> -> 
> ``, etc.)
>
> Thanks,
> Michael
>
> On 12/7/2022 11:47 PM, Rebecca Cran wrote:
>> What tool do you use to write the pages?
>>
>> It seems to be a mixture of markdown and HTML: for example I'm 
>> surprised to see things like "<strong>C Compiler</strong>" - I'd 
>> expect something like "**C Compiler**" instead.
>>
>
>
> 
>
>

Re: [edk2-devel] [edk2-wiki][PATCH v3 1/4] Add initial How to Build with Stuart Document

[Michael Kubacki]

On 12/13/2022 12:25 AM, Rebecca Cran wrote:
> According to 
> https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-collapsed-sections, 
> it looks like normal markdown _should_ apply within collapsed sections?
> 
> 
It did not work consistently in some markdown previewers I was using 
locally and linking to sections was problematic. I did not spend a lot 
of time to force markdown because I don't mind HTML. It might be 
possible to convert if someone wants to do that.

> I noticed a few problems with 
> https://github.com/tianocore/tianocore.github.io/wiki/How-to-Build-With-Stuart 
> :
> 
> 
> Example: git clone edk2
> 
> Should probably be: git clone https://github.com/tianocore/edk2.git
> 
Thanks. This was a placeholder when writing that needed to be updated. 
Its updated now.
> 
> The Linux instructions for creating a python virtual environment should 
> probably be:
> 
> python3 -m venv .venv
> 
Changed python to python3.
> 
> Though I've been installing the stuart tools into ~/.local/bin which 
> allows you to skip the step of using a virtual environment.
> 
> 
> Lastly, the Git Submodules step says to use --recursive, which I seem to 
> recall other instructions suggesting _not_ to use, since it's not needed.
> 
I use it because there are nested submodules in edk2 such as those in 
CryptoPkg/Library/OpensslLib/openssl and I've run into problems in the 
past with its submodules not in sync.

Thanks,
Michael

[edk2-wiki][PATCH v3 2/4] Add initial container usage instructions

[Michael Kubacki]

From: Chris Fernald <chrisf671@gmail.com>

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 <sean.brogan@microsoft.com>
Cc: Michael D Kinney <michael.d.kinney@intel.com>
Cc: Liming Gao <gaoliming@byosoft.com.cn>
Cc: Michael Kubacki <michael.kubacki@microsoft.com>
Signed-off-by: Chris Fernald <chfernal@microsoft.com>
---
 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-Containers.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 environment requirements
+it can be beneficial to use a container build environment for local development.
+TianoCore maintains container images for various Operating Systems and tool 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 platform 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 personal or
+> Business subscription. Users should verify their use is licensed for their organization
+> if necessary.
+
+The existing TianoCore container images are created for use with Docker. On Linux,
+docker can be installed through the distributions package management application.
+For specific builds and for other operating systems, see the [Docker install page](https://docs.docker.com/engine/install/).
+
+### Windows Docker Setup
+
+It is strongly recommended to use the WSL 2 based engine when running Docker on
+Windows. This can be configured in the General settings in Docker Desktop. Generally,
+this provides better performance and overall design over the legacy. Details on
+this framework can be found in the [Docker documentation](https://docs.docker.com/desktop/windows/wsl/).
+
+## Local Development
+
+To use the build container images to develop locally, there are several configurations
+depending the developers preferences. This section details some tools and tips that
+make using containers for local development easier. This section is not comprehensive
+however and it is encouraged users experiment and consider contributing back 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 between Windows
+> and WSL 2 causes a very significant performance reduction. Instead, clone 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 useful
+for using editors that do not have native support for containers or the specific
+type of containers used.
+
+First, select the image most appropriate from the [TianoCore containers list](https://github.com/tianocore/containers#current-status)
+or a custom image for a specific platform or project. This image can be pulled down
+from the docker command line.
+
+```bash
+docker pull ghcr.io/tianocore/containers/<image>:<tag>
+```
+
+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 from the
+host as well as the container.
+
+```bash
+docker run -i -v <local-code-directory>:<container-directory> --workdir=<container directory> --name=<name> ghcr.io/tianocore/containers/<image>:<tag>
+```
+
+After the container is existed, it can be resume by using the start command.
+
+```bash
+docker start -i <name>
+```
+
+When running in the container, the build instructions should be used as they 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 development. At
+the time of writing, this extension only supports Linux based containers. This
+extension provides a number of useful additions to the specified docker image 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 creating a
+.devcontainer file in the repository. Some useful configurations are details below.
+
+| Configuration          | Purpose |
+| :------------          | :------ |
+| "privileged": true     | This may be needed for access to KVM for QEMU acceleration.  |
+| "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 "postCreateCommand"
+option. Specifically running `git config --global --add safe.directory ${containerWorkspaceFolder}`
+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 below.
+
+```json
+{
+  "image": "ghcr.io/tianocore/containers/fedora-35-dev:latest",
+  "postCreateCommand": "git config --global --add safe.directory ${containerWorkspaceFolder} && pip install --upgrade -r pip-requirements.txt",
+  "forwardPorts": [5000],
+  "privileged": true
+}
+```
+
+## Pipeline Builds
+
+Both Azure pipelines and github workflows have native support for containers. Information
+on this can be found in the [Azure Pipeline Documentation](https://learn.microsoft.com/en-us/azure/devops/pipelines/process/container-phases?view=azure-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 user in the
+docker image during the pipeline. This user is used for all tasks and operations
+and so certain local user install locations may not be by default on the path.
-- 
2.28.0.windows.1

[edk2-wiki][PATCH v3 3/4] Add top-level build instructions file

[Michael Kubacki]

From: Michael Kubacki <michael.kubacki@microsoft.com>

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 <sean.brogan@microsoft.com>
Cc: Michael D Kinney <michael.d.kinney@intel.com>
Cc: Liming Gao <gaoliming@byosoft.com.cn>
Signed-off-by: Michael Kubacki <michael.kubacki@microsoft.com>
---
 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 common theme has been reducing the number of
+manual steps involved and easing environment setup and configuration so developers can more quickly get started writing
+firmware code.
+
+There's currently three high-level approaches to build (listed in recommended 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 capability 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 and 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 support possible (since issues in containers
+are easy to reproduce, fix, and deploy), then start with the container instructions.
+
+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 reduced 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 without using containers, it is recommended
+to use Stuart. Containers use Stuart and the CI system uses Stuart and many 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, containers 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 more manual steps and a lack of the feature
+set brought by the other two options but you can produce a working firmware image (in most cases) with `build`.
-- 
2.28.0.windows.1

[edk2-wiki][PATCH v3 4/4] Update existing build instructions

[Michael Kubacki]

From: Michael Kubacki <michael.kubacki@microsoft.com>

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 <sean.brogan@microsoft.com>
Cc: Michael D Kinney <michael.d.kinney@intel.com>
Cc: Liming Gao <gaoliming@byosoft.com.cn>
Signed-off-by: Michael Kubacki <michael.kubacki@microsoft.com>
---
 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 @@
-=Frequently asked EDK II build questions=
-
-==Regarding the Build for EDK II, how do you specify a different compiler tool chain on the command line?==
-
-Use –t parameter for the build command. Example: Using the Microsoft Visual Studio 2005 tool chain ... 
-
-    build –t VS2005
-
-For using other tools see [[Getting_Started_with_EDK_II]]. This provides some detailed instructions for setting up some different tool chains? The file Conf/tools_def.txt contains a list of targets.
-
-==Is it possible to use PCDs @ build time?==
-
-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 “Build –D MACRO-NAME” options.
-
-==Is there information on Building on Linux?==
-
-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 Cygwin or Mac OS X)
-
-==What is the state of Python?==
-
-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. 
-There is a Python interpreter that  is part of the EFI toolkit on tianocore.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 [[AppPkg]].  It is currently (01/2012) in Aplha stage.
-
-==What does the parsing tool do?==
-
-The parsing is part of the first stage of the build process.  There are tools for parsing  the set build description files and the target.txt for a package or platform and creates the intermediate make and autogen files
-
-==Regarding writing UEFI Applications in EDK II, where is the output and/or the binary UEFI application after doing a build?==
-
-The Build output directory is defined in the defines section of a .DSC file.
-For example, Nt32Pkg\Nt32Pkg.dsc - the UEFI application would be in Build\NT32\DEBUG_MYTOOLS\IA32
-
-    OUTPUT_DIRECTORY   	        = Build/NT32
-    SUPPORTED_ARCHITECTURES	= IA32
-    BUILD_TARGETS	        = DEBUG
-
-==How do I get my UEFI application to the target UEFI System?==
-
-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 the EFI Shell.  The USB thumb drive should be one of the file systems, e.g. FS0:. Cd to that USB drive and run your UEFI application from the shell  prompt
-
-==Is the Build tool source code part of the Build?==
-
-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 need to be built.  The pre-build binaries can be used.  One Linux, Unix, and OS/X systems, these sources are used to build the binaries for that OS, or in 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 new feature is stable, and only once it is stable is a feature added to the BaseTools directory and new binaries are generated.
-
-==Can we use Ifdefs?==
-
-This is not recommended but can be used within the DSC or FDF as part of the build.
-But here is an example:
-
-   !ifdef $(SOURCE_DEBUG_ENABLE)
-     MSFT:*_*_X64_GENFW_FLAGS  = --keepexceptiontable
-     GCC:*_*_X64_GENFW_FLAGS   = --keepexceptiontable
-     INTEL:*_*_X64_GENFW_FLAGS = --keepexceptiontable
-   !endif
-
-==When can the report generator show the protocols produced by modules?==
-
-The report generator can show protocols produced by modules. The Runtime DXE core will also report what is missing before handing off.
-
-==Why is the Buffer Security check flag (Build options) disabled for building EDK II UEFI applications and drivers but it is enabled for building tools. ==
-
-UEFI applications and drivers are not executed in an Operating System environment. This is important, as the switches have very specific (and, in the pre-boot space, negative) impacts on generated code. The switch does two things in the code that are not acceptable for the pre-boot environment:
-
-* The switch enables additional code in the compiled code base, which requires 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 present in our Firmware builds, and which we do not have information on how to emulate. 
-
-We disable these settings, as enabling them would create non-functioning code.
-
-However, please be aware that Detecting Stack Overflows in Firmware is critical in validation and development, and we use other techniques in our code to do so.  We just cannot generically support the /Gs flags (as noted above).
-
-The tools do have this flag set, as they are used within the Operating System environment, where the intrinsic added by the compiler can be processed correctly. 
- 
-==Are there Dual-mode drivers in EDK II?==
-
-No.  The EDK II build system does not support the dual mode drivers described 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 different PE/COFF images would be generated when built.
-
-==Is there a tool to parse the BIOS Build tree?==
-
-a) Use the report generator build into the build tool  “BUILD –Y” on the command line 
-
-  -Y REPORTTYPE, --report-type=REPORTTYPE
-                   	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 “–Y DEPEX” 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 protocols that might be conditionally produced. Documented in the EDK2010 March 2010 release notes.
-
-c) Behavior of dispatch – filter for DEBUG_DISPATCH in DSC in the PCD for the error level PcdDebugPrintErrorLevel
-
-==How does the build tool load the reset vector at 0xFFFFFFF0?==
-
-This is defined in the PI Specification, Volume 3. http://www.uefi.org/specs
-
-In the FV (Firmware Volume) there is something called a Volume Top File inf 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. Regardless of the file type, a VTF must have the file name GUID of EFI_FFS_VOLUME_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 vector, and it jumps to the SEC code.
-
-Reference: https://github.com/tianocore/edk2/tree/master/UefiCpuPkg/ResetVector/Vtf0
-
-So the hard code bit is the FV (Firmware Volume) that that contains the Volume 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) have their PE/COFF image relocated based on where they end up in the FV (based on info in FDF file). This is done by the build system. If the EFI code runs from RAM then it is loaded by a PE/COFF loader and relocated to its load address.
+=Frequently asked EDK II build questions=
+
+  Note: This page is retained for reference. Most of the content as of 2022 is still relevant but it is recommended to
+        view the new set of build instructions that describe how to develop using containers and build with the Stuart
+        application.
+
+New instructions: [[Build-Instructions.md|Build Instructions]]
+
+==Regarding the Build for EDK II, how do you specify a different compiler tool chain on the command line?==
+
+Use –t parameter for the build command. Example: Using the Microsoft Visual Studio 2019 tool chain ...
+
+    build –t VS2019
+
+For using other tools see [[Getting_Started_with_EDK_II]]. This provides some detailed instructions for setting up some different tool chains? The file Conf/tools_def.txt contains a list of targets.
+
+==Is it possible to use PCDs @ build time?==
+
+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 “Build –D MACRO-NAME” options.
+
+==Is there information on Building on Linux?==
+
+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 Cygwin or Mac OS X)
+
+==What does the parsing tool do?==
+
+The parsing is part of the first stage of the build process.  There are tools for parsing  the set build description files and the target.txt for a package or platform and creates the intermediate make and autogen files
+
+==Regarding writing UEFI Applications in EDK II, where is the output and/or the binary UEFI application after doing a build?==
+
+The Build output directory is defined in the defines section of a .DSC file.
+For example, Nt32Pkg\Nt32Pkg.dsc - the UEFI application would be in Build\NT32\DEBUG_MYTOOLS\IA32
+
+    OUTPUT_DIRECTORY   	        = Build/NT32
+    SUPPORTED_ARCHITECTURES	= IA32
+    BUILD_TARGETS	        = DEBUG
+
+==How do I get my UEFI application to the target UEFI System?==
+
+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 the EFI Shell.  The USB thumb drive should be one of the file systems, e.g. FS0:. Cd to that USB drive and run your UEFI application from the shell  prompt
+
+==Is the Build tool source code part of the Build?==
+
+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 need to be built.  The pre-build binaries can be used.  One Linux, Unix, and OS/X systems, these sources are used to build the binaries for that OS, or in 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 new feature is stable, and only once it is stable is a feature added to the BaseTools directory and new binaries are generated.
+
+==Can we use Ifdefs?==
+
+This is not recommended but can be used within the DSC or FDF as part of the build.
+But here is an example:
+
+   !ifdef $(SOURCE_DEBUG_ENABLE)
+     MSFT:*_*_X64_GENFW_FLAGS  = --keepexceptiontable
+     GCC:*_*_X64_GENFW_FLAGS   = --keepexceptiontable
+     INTEL:*_*_X64_GENFW_FLAGS = --keepexceptiontable
+   !endif
+
+==When can the report generator show the protocols produced by modules?==
+
+The report generator can show protocols produced by modules. The Runtime DXE core will also report what is missing before handing off.
+
+==Why is the Buffer Security check flag (Build options) disabled for building EDK II UEFI applications and drivers but it is enabled for building tools. ==
+
+UEFI applications and drivers are not executed in an Operating System environment. This is important, as the switches have very specific (and, in the pre-boot space, negative) impacts on generated code. The switch does two things in the code that are not acceptable for the pre-boot environment:
+
+* The switch enables additional code in the compiled code base, which requires 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 present in our Firmware builds, and which we do not have information on how to emulate.
+
+We disable these settings, as enabling them would create non-functioning code.
+
+However, please be aware that Detecting Stack Overflows in Firmware is critical in validation and development, and we use other techniques in our code to do so.  We just cannot generically support the /Gs flags (as noted above).
+
+The tools do have this flag set, as they are used within the Operating System environment, where the intrinsic added by the compiler can be processed correctly.
+
+==Are there Dual-mode drivers in EDK II?==
+
+No.  The EDK II build system does not support the dual mode drivers described 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 different PE/COFF images would be generated when built.
+
+==Is there a tool to parse the BIOS Build tree?==
+
+a) Use the report generator build into the build tool  “BUILD –Y” on the command line
+
+  -Y REPORTTYPE, --report-type=REPORTTYPE
+                   	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 “–Y DEPEX” 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 protocols that might be conditionally produced. Documented in the EDK2010 March 2010 release notes.
+
+c) Behavior of dispatch – filter for DEBUG_DISPATCH in DSC in the PCD for the error level PcdDebugPrintErrorLevel
+
+==How does the build tool load the reset vector at 0xFFFFFFF0?==
+
+This is defined in the PI Specification, Volume 3. http://www.uefi.org/specs
+
+In the FV (Firmware Volume) there is something called a Volume Top File inf 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. Regardless of the file type, a VTF must have the file name GUID of EFI_FFS_VOLUME_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 vector, and it jumps to the SEC code.
+
+Reference: https://github.com/tianocore/edk2/tree/master/UefiCpuPkg/ResetVector/Vtf0
+
+So the hard code bit is the FV (Firmware Volume) that that contains the Volume 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) have their PE/COFF image relocated based on where they end up in the FV (based on info in FDF file). This is done by the build system. If the EFI code runs from RAM then it is loaded by a PE/COFF loader and relocated to its load address.
diff --git a/BuildTool-Setup-Guide.mediawiki b/BuildTool-Setup-Guide.mediawiki
index 445ef25af598..45a80406395f 100644
--- a/BuildTool-Setup-Guide.mediawiki
+++ b/BuildTool-Setup-Guide.mediawiki
@@ -1,43 +1,46 @@
-=GitHub Help=
-
-GitHub (https://help.github.com/index.html) provides step-by-step instructions for user registration and basic features supported by GitHub 
-
-* Setup GitHub for Linux | Windows | MAC | All (https://help.github.com/articles/set-up-git)
-* To download and install a Git GUI interface (http://git-scm.com/)
-
-=='''GitHub EDK II Project Repositories'''==
-
-* The EDK II BaseTools are part of the EDK II project repository. 
-* The EDK II project repository is available at https://github.com/tianocore/edk2. 
-* Prebuilt Windows tools are available at https://github.com/tianocore/edk2-BaseTools-win32. 
-* Content that is not released under an accepted open source license can be found at https://github.com/tianocore/edk2-non-osi.<BR>
-= Getting the extra tools=
-== Compiler ==
-For both the BuildTools and [http://www.tianocore.org/edk2/ EDK II] projects, you will need to obtain a compiler from somewhere else. These instructions do not cover obtaining or installation of a compiler tools chain. The BaseTools build requires a C compiler; an assembler or ACPI assembler are not required to build tools in this project. BaseTools assume that a compiler is already configured in the environment.
-
-== Python ==
-The BaseTools build supports the Makefile based build for EDK II. All Tools are written in either C or Python. The C tools must compile on all operating systems with various compilers, so the code is written using simple, standard functions and libraries. The Python-based tools are written assuming the features that were available in Python. GUI applications can be created 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 [[Python Tools]].
-
-The tools in this section are NOT required to build the EDK II project; they 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 will 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 more information. 
-* BuildTools [https://github.com/tianocore/buildtools-BaseTools/tree/master/UserManuals User Manuals]
-
-='''How to Setup the EDK II Tree'''=
-See [[Getting Started with EDK II]]
-
-==  EDK II Development Process ==
-After setting up your build environment see  [[EDK II Development Process]] for making contributions to the EDK II Project.
-
-=Further Help=
-
-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.
+=GitHub Help=
+
+  Note: New build instructions are available. It is recommended to start with 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 instructions for user registration and basic features supported by GitHub
+
+* Setup GitHub for Linux | Windows | MAC | All (https://help.github.com/articles/set-up-git)
+* To download and install a Git GUI interface (http://git-scm.com/)
+
+=='''GitHub EDK II Project Repositories'''==
+
+* The EDK II BaseTools are part of the EDK II project repository.
+* The EDK II project repository is available at https://github.com/tianocore/edk2.
+* Prebuilt Windows tools are available at https://github.com/tianocore/edk2-BaseTools-win32.
+* Content that is not released under an accepted open source license can be found at https://github.com/tianocore/edk2-non-osi.<BR>
+= Getting the extra tools=
+== Compiler ==
+For both the BuildTools and [http://www.tianocore.org/edk2/ EDK II] projects, you will need to obtain a compiler from somewhere else. These instructions do not cover obtaining or installation of a compiler tools chain. The BaseTools build requires a C compiler; an assembler or ACPI assembler are not required to build tools in this project. BaseTools assume that a compiler is already configured in the environment.
+
+== Python ==
+The BaseTools build supports the Makefile based build for EDK II. All Tools are written in either C or Python. The C tools must compile on all operating systems with various compilers, so the code is written using simple, standard functions and libraries. The Python-based tools are written assuming the features that were available in Python. GUI applications can be created 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 [[Python Tools]].
+
+The tools in this section are NOT required to build the EDK II project; they 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 will 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 more information.
+* BuildTools [https://github.com/tianocore/buildtools-BaseTools/tree/master/UserManuals User Manuals]
+
+='''How to Setup the EDK II Tree'''=
+See [[Getting Started with EDK II]]
+
+==  EDK II Development Process ==
+After setting up your build environment see  [[EDK II Development Process]] for making contributions to the EDK II Project.
+
+=Further Help=
+
+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-for-Unix.mediawiki
index d15d3ffa0881..2432695e8844 100644
--- a/Common-instructions-for-Unix.mediawiki
+++ b/Common-instructions-for-Unix.mediawiki
@@ -1,186 +1,191 @@
-__NOTOC__
-==Common instructions for Unix ==
-
-A significant portion of the steps are common on the various UNIX-like platforms.  You should start with the instructions for the operating system that most closely matches your platform, and it will direct you here at the appropriate 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]] instructions. Please follow the [[Using EDK II with Native GCC]] guide for mainstream Linux distros.
-
-===Get the edk2 source tree using Git ===
-
-<pre>
-bash$ mkdir ~/src
-bash$ cd ~/src
-bash$ git clone https://github.com/tianocore/edk2
-</pre>
-
-====For EDKII project developers:====
-*	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.
-
-===Build the EDK II BaseTools===
-
-<pre>
-bash$ make -C edk2/BaseTools
-</pre>
-
-===Build gcc x64 UEFI cross compiler===
-
-In order to build UEFI images for x64, you will need to build a cross-compiler build of gcc.  This can take quite a while to complete, possibly several hours on older systems.  But, a Python script has been provided to automate this build process.
-
-Note: This is only needed if behind a internet firewall!
-<pre>
-bash$ export http_proxy=http://proxy.domain.com:proxy_port
-</pre>
-
-To build gcc for x64, use these commands (this will take quite a while to complete):
-
-<pre>
-bash$ cd ~/src/edk2/BaseTools/gcc
-bash$ ./mingw-gcc-build.py --arch=x64 \
-  --prefix=~/programs/gcc/x64
-</pre>
-
-===Setup build shell environment===
-
-<pre>
-bash$ cd ~/src/edk2
-bash$ export EDK_TOOLS_PATH=~/src/edk2/BaseTools
-bash$ . edksetup.sh BaseTools
-</pre>
-
-===Modify Conf Files===
-
-You will need to edit the Conf/tools_def.txt and Conf/target.txt files.  These changes will enable the MdeModulePkg to be built using the gcc x64 compiler.
-
-====Enable GCC X64 Cross-Compiler====
-
-For the Conf/tools_def.txt file, find the following entry and comment the line out:
-
-<pre>
-DEFINE UNIXGCC_X64_PETOOLS_PREFIX  = /opt/tiano/x86_64-pc-mingw64/x86_64-pc-mingw64/bin/
-</pre>
-
-Next, find the following entry and uncomment the line:
-
-<pre>
-DEFINE UNIXGCC_X64_PETOOLS_PREFIX  = ENV(HOME)/programs/gcc/x64/bin/x86_64-pc-mingw32-
-</pre>
-
-====Set Build Target Information====
-
-For the Conf/target.txt file, find the following lines:
-
-<pre>
-ACTIVE_PLATFORM       = Nt32Pkg/Nt32Pkg.dsc
-TARGET_ARCH           = IA32
-TOOL_CHAIN_TAG        = MYTOOLS
-</pre>
-
-And change the cooresponding lines to match these:
-
-<pre>
-ACTIVE_PLATFORM       = MdeModulePkg/MdeModulePkg.dsc
-TARGET_ARCH           = X64
-TOOL_CHAIN_TAG        = UNIXGCC
-</pre>
-
-===Build Hello World!  (and the rest of MdeModulePkg)===
-
-Now you should be able to simply run the build command to compile the MdeModulePkg.
-
-<pre>
-bash$ build
-</pre>
-
-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 application should be able to run successfully under the shell.
-
-<pre>
-bash$ ls Build/MdeModule/DEBUG_UNIXGCC/X64/HelloWorld.efi
-</pre>
-
-==Enabling Other Tools==
-
-The above showed how to setup an X64 build environment for building the core MdeModulePkg.  However, other packages may require additional tools such as an IA32 cross-compiler and an ASL compiler.  The steps to build these tools are described in this section.
-
-===Build gcc IA32 UEFI cross compiler===
-
-In order to build UEFI images for IA32, you will need to build a cross-compiler build of gcc.  This can take quite a while to complete, possibly several hours on older systems.  But, a Python script has been provided to automate this build process.
-
-Note: This is only needed if behind a internet firewall!
-<pre>
-bash$ export http_proxy=http://proxy.domain.com:proxy_port
-</pre>
-
-To build gcc for IA32, use these commands (this will take quite a while to complete):
-
-<pre>
-bash$ cd ~/src/edk2/BaseTools/gcc
-bash$ ./mingw-gcc-build.py --arch=ia32 \
-  --prefix=~/programs/gcc/ia32
-</pre>
-
-====Modify Conf Files====
-
-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 out:
-
-<pre>
-DEFINE UNIXGCC_IA32_PETOOLS_PREFIX = /opt/tiano/i386-tiano-pe/i386-tiano-pe/bin/
-</pre>
-
-Next, find the following statement and uncomment the line: 
-
-<pre>
-DEFINE UNIXGCC_IA32_PETOOLS_PREFIX = ENV(HOME)/programs/gcc/ia32/bin/i686-pc-mingw32-
-</pre>
-
-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 corresponding line to match this
-
-<pre>
-TARGET_ARCH           = IA32
-</pre>
-
-===Build the Intel ASL (iasl) compiler===
-
-The Intel ASL compiler is not required for all edk2 developers.  It is unlikely 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 need an ASL compiler.  For example, the edk2 OVMF sample platform does require 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 building on Mac OS X, so please use the release from 20081031 instead.
-
-<pre>
-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
-</pre>
-
-====Modify Conf Files====
-
-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 out:
-
-<pre>
-DEFINE UNIX_IASL_BIN           = /usr/bin/iasl
-</pre>
-
-Next, find the following statement and uncomment the line:
-
-<pre>
-DEFINE UNIX_IASL_BIN           = $(HOME)/programs/iasl
-</pre>
-
-===Build [http://www.tianocore.org/ovmf/ OVMF]===
-
-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 firmware developers.
+__NOTOC__
+==Common instructions for Unix ==
+
+  Note: New build instructions are available. It is recommended to start with 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 platforms.  You should start with the instructions for the operating system that most closely matches your platform, and it will direct you here at the appropriate 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]] instructions. Please follow the [[Using EDK II with Native GCC]] guide for mainstream Linux distros.
+
+===Get the edk2 source tree using Git ===
+
+<pre>
+bash$ mkdir ~/src
+bash$ cd ~/src
+bash$ git clone https://github.com/tianocore/edk2
+</pre>
+
+====For EDKII project developers:====
+*	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.
+
+===Build the EDK II BaseTools===
+
+<pre>
+bash$ make -C edk2/BaseTools
+</pre>
+
+===Build gcc x64 UEFI cross compiler===
+
+In order to build UEFI images for x64, you will need to build a cross-compiler build of gcc.  This can take quite a while to complete, possibly several hours on older systems.  But, a Python script has been provided to automate this build process.
+
+Note: This is only needed if behind a internet firewall!
+<pre>
+bash$ export http_proxy=http://proxy.domain.com:proxy_port
+</pre>
+
+To build gcc for x64, use these commands (this will take quite a while to complete):
+
+<pre>
+bash$ cd ~/src/edk2/BaseTools/gcc
+bash$ ./mingw-gcc-build.py --arch=x64 \
+  --prefix=~/programs/gcc/x64
+</pre>
+
+===Setup build shell environment===
+
+<pre>
+bash$ cd ~/src/edk2
+bash$ export EDK_TOOLS_PATH=~/src/edk2/BaseTools
+bash$ . edksetup.sh BaseTools
+</pre>
+
+===Modify Conf Files===
+
+You will need to edit the Conf/tools_def.txt and Conf/target.txt files.  These changes will enable the MdeModulePkg to be built using the gcc x64 compiler.
+
+====Enable GCC X64 Cross-Compiler====
+
+For the Conf/tools_def.txt file, find the following entry and comment the line out:
+
+<pre>
+DEFINE UNIXGCC_X64_PETOOLS_PREFIX  = /opt/tiano/x86_64-pc-mingw64/x86_64-pc-mingw64/bin/
+</pre>
+
+Next, find the following entry and uncomment the line:
+
+<pre>
+DEFINE UNIXGCC_X64_PETOOLS_PREFIX  = ENV(HOME)/programs/gcc/x64/bin/x86_64-pc-mingw32-
+</pre>
+
+====Set Build Target Information====
+
+For the Conf/target.txt file, find the following lines:
+
+<pre>
+ACTIVE_PLATFORM       = Nt32Pkg/Nt32Pkg.dsc
+TARGET_ARCH           = IA32
+TOOL_CHAIN_TAG        = MYTOOLS
+</pre>
+
+And change the cooresponding lines to match these:
+
+<pre>
+ACTIVE_PLATFORM       = MdeModulePkg/MdeModulePkg.dsc
+TARGET_ARCH           = X64
+TOOL_CHAIN_TAG        = UNIXGCC
+</pre>
+
+===Build Hello World!  (and the rest of MdeModulePkg)===
+
+Now you should be able to simply run the build command to compile the MdeModulePkg.
+
+<pre>
+bash$ build
+</pre>
+
+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 application should be able to run successfully under the shell.
+
+<pre>
+bash$ ls Build/MdeModule/DEBUG_UNIXGCC/X64/HelloWorld.efi
+</pre>
+
+==Enabling Other Tools==
+
+The above showed how to setup an X64 build environment for building the core MdeModulePkg.  However, other packages may require additional tools such as an IA32 cross-compiler and an ASL compiler.  The steps to build these tools are described in this section.
+
+===Build gcc IA32 UEFI cross compiler===
+
+In order to build UEFI images for IA32, you will need to build a cross-compiler build of gcc.  This can take quite a while to complete, possibly several hours on older systems.  But, a Python script has been provided to automate this build process.
+
+Note: This is only needed if behind a internet firewall!
+<pre>
+bash$ export http_proxy=http://proxy.domain.com:proxy_port
+</pre>
+
+To build gcc for IA32, use these commands (this will take quite a while to complete):
+
+<pre>
+bash$ cd ~/src/edk2/BaseTools/gcc
+bash$ ./mingw-gcc-build.py --arch=ia32 \
+  --prefix=~/programs/gcc/ia32
+</pre>
+
+====Modify Conf Files====
+
+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 out:
+
+<pre>
+DEFINE UNIXGCC_IA32_PETOOLS_PREFIX = /opt/tiano/i386-tiano-pe/i386-tiano-pe/bin/
+</pre>
+
+Next, find the following statement and uncomment the line:
+
+<pre>
+DEFINE UNIXGCC_IA32_PETOOLS_PREFIX = ENV(HOME)/programs/gcc/ia32/bin/i686-pc-mingw32-
+</pre>
+
+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 corresponding line to match this
+
+<pre>
+TARGET_ARCH           = IA32
+</pre>
+
+===Build the Intel ASL (iasl) compiler===
+
+The Intel ASL compiler is not required for all edk2 developers.  It is unlikely 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 need an ASL compiler.  For example, the edk2 OVMF sample platform does require 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 building on Mac OS X, so please use the release from 20081031 instead.
+
+<pre>
+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
+</pre>
+
+====Modify Conf Files====
+
+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 out:
+
+<pre>
+DEFINE UNIX_IASL_BIN           = /usr/bin/iasl
+</pre>
+
+Next, find the following statement and uncomment the line:
+
+<pre>
+DEFINE UNIX_IASL_BIN           = $(HOME)/programs/iasl
+</pre>
+
+===Build [http://www.tianocore.org/ovmf/ OVMF]===
+
+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 firmware 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__
-=Common EDK II Build Instructions for Linux=
-
-These instructions assume you have installed Linux packages required for an [[EDK II]] build environment, including git (example: [https://github.com/tianocore/tianocore.github.io/wiki/Using-EDK-II-with-Native-GCC#Ubuntu_1604_LTS__Ubuntu_1610|Ubuntu 16.04/16.10]). The following instructions are common to the majority of Linux environments.
-
-===Get the edk2 source tree using Git ===
-
-<pre>
-bash$ mkdir ~/src
-bash$ cd ~/src
-bash$ git clone https://github.com/tianocore/edk2
-</pre>
-
-Note: the 'git clone' command above pulls the latest code from edk2. If you want to work from a stable release, specify a release tag when cloning. Example:
-
-<pre>
-bash$ git clone https://github.com/tianocore/edk2.git vUDK2017
-</pre>
-
-===Initialize submodules===
-
-<pre>
-bash$ git submodule update --init
-</pre>
-
-===Compile build tools ===
-
-<pre>
-bash$ cd ~/src/edk2
-bash$ make -C BaseTools
-bash$ . edksetup.sh
-</pre>
-
-When the above steps are done, you can work in the edk2 directory for code development.
-
-===Build the EDK II BaseTools===
-
-<pre>
-bash$ make -C edk2/BaseTools
-</pre>
-
-===Setup build shell environment===
-
-<pre>
-bash$ cd ~/src/edk2
-bash$ export EDK_TOOLS_PATH=$HOME/src/edk2/BaseTools
-bash$ . edksetup.sh BaseTools
-</pre>
-
-===Modify Conf Files===
-
-Running <code>edksetup.sh</code> populates the <code>edk2/Conf</code> directory with default configuration files. You will need to edit the <code>Conf/target.txt</code> file to set the build platform, target architecture, tool chain, and multi-threading options. The example below is based on building the <code>MdeModulePkg</code> using GCC5.
-
-====Set Build Target Information====
-
-For the <code>Conf/target.txt</code> file, find the following lines:
-
-<pre>
-ACTIVE_PLATFORM       = Nt32Pkg/Nt32Pkg.dsc
-TOOL_CHAIN_TAG        = MYTOOLS
-</pre>
-
-And change the corresponding lines to match these:
-
-<pre>
-ACTIVE_PLATFORM       = MdeModulePkg/MdeModulePkg.dsc
-TOOL_CHAIN_TAG        = GCC5
-</pre>
-
-:Note: The <code>gcc --version</code> 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: <code>sudo apt-get install gcc-5</code>
-
-Locate the TARGET_ARCH setting:
-
-<pre>
-TARGET_ARCH           = IA32
-</pre>
-
-Change this reflect the build architecture for the final UEFI binary.
-
-:Example: <code>X64</code>, <code>IA32 X64</code> (which will build both architectures).
-
-Optional: enable multi-threaded build. The default value for <code>MAX_CONCURRENT_THREAD_NUMBER</code> is 1, which disables multi-threaded build. Change this value based on your system's multi-threading capabilities. The formula is '1 + (2 x processor threads)'.
-
-:Example: for an Intel Core i5 (two processor cores w/ hyperthreading), the value is <code>9</code>.
-
-===Build Hello World!  (and the rest of MdeModulePkg)===
-
-Now you should be able to simply run the build command to compile <code>MdeModulePkg</code>.
-
-<pre>
-bash$ build
-</pre>
-
-One result of the build is that you should have the HelloWorld UEFI application:
-<pre>
-bash$ ls Build/MdeModule/DEBUG_*/*/HelloWorld.efi
-</pre>
-
-===Build [[OVMF]]===
-
-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, this may be of interest to UEFI system firmware developers.
+__NOTOC__
+=Common EDK II Build Instructions for Linux=
+
+  Note: New build instructions are available. It is recommended to start with 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 an [[EDK II]] build environment, including git (example: [https://github.com/tianocore/tianocore.github.io/wiki/Using-EDK-II-with-Native-GCC#Ubuntu_1604_LTS__Ubuntu_1610|Ubuntu 16.04/16.10]). The following instructions are common to the majority of Linux environments.
+
+===Get the edk2 source tree using Git ===
+
+<pre>
+bash$ mkdir ~/src
+bash$ cd ~/src
+bash$ git clone https://github.com/tianocore/edk2
+</pre>
+
+Note: the 'git clone' command above pulls the latest code from edk2. If you want to work from a stable release, specify a release tag when cloning. Example:
+
+<pre>
+bash$ git clone https://github.com/tianocore/edk2.git vUDK2017
+</pre>
+
+===Initialize submodules===
+
+<pre>
+bash$ git submodule update --init
+</pre>
+
+===Compile build tools ===
+
+<pre>
+bash$ cd ~/src/edk2
+bash$ make -C BaseTools
+bash$ . edksetup.sh
+</pre>
+
+When the above steps are done, you can work in the edk2 directory for code development.
+
+===Build the EDK II BaseTools===
+
+<pre>
+bash$ make -C edk2/BaseTools
+</pre>
+
+===Setup build shell environment===
+
+<pre>
+bash$ cd ~/src/edk2
+bash$ export EDK_TOOLS_PATH=$HOME/src/edk2/BaseTools
+bash$ . edksetup.sh BaseTools
+</pre>
+
+===Modify Conf Files===
+
+Running <code>edksetup.sh</code> populates the <code>edk2/Conf</code> directory with default configuration files. You will need to edit the <code>Conf/target.txt</code> file to set the build platform, target architecture, tool chain, and multi-threading options. The example below is based on building the <code>MdeModulePkg</code> using GCC5.
+
+====Set Build Target Information====
+
+For the <code>Conf/target.txt</code> file, find the following lines:
+
+<pre>
+ACTIVE_PLATFORM       = Nt32Pkg/Nt32Pkg.dsc
+TOOL_CHAIN_TAG        = MYTOOLS
+</pre>
+
+And change the corresponding lines to match these:
+
+<pre>
+ACTIVE_PLATFORM       = MdeModulePkg/MdeModulePkg.dsc
+TOOL_CHAIN_TAG        = GCC5
+</pre>
+
+:Note: The <code>gcc --version</code> 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: <code>sudo apt-get install gcc-5</code>
+
+Locate the TARGET_ARCH setting:
+
+<pre>
+TARGET_ARCH           = IA32
+</pre>
+
+Change this reflect the build architecture for the final UEFI binary.
+
+:Example: <code>X64</code>, <code>IA32 X64</code> (which will build both architectures).
+
+Optional: enable multi-threaded build. The default value for <code>MAX_CONCURRENT_THREAD_NUMBER</code> is 1, which disables multi-threaded build. Change this value based on your system's multi-threading capabilities. The formula is '1 + (2 x processor threads)'.
+
+:Example: for an Intel Core i5 (two processor cores w/ hyperthreading), the value is <code>9</code>.
+
+===Build Hello World!  (and the rest of MdeModulePkg)===
+
+Now you should be able to simply run the build command to compile <code>MdeModulePkg</code>.
+
+<pre>
+bash$ build
+</pre>
+
+One result of the build is that you should have the HelloWorld UEFI application:
+<pre>
+bash$ ls Build/MdeModule/DEBUG_*/*/HelloWorld.efi
+</pre>
+
+===Build [[OVMF]]===
+
+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, this may be of interest to UEFI system firmware developers.
diff --git a/Getting-Started-with-EDK-II.mediawiki b/Getting-Started-with-EDK-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 with 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]]
+
 =Downloading and Compiling Code=
 
 This page shows the steps for downloading [[EDK II]] from GitHub and compiling 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 project or package:
 * [[Nasm Setup|Nasm]]
 * [[ASL Setup|ASL Compiler]]
-* Install Python 3.7 or later (https://www.python.org/)  to run python tool from source 
+* Install Python 3.7 or later (https://www.python.org/)  to run python tool from source
 **  Python 2.7.10 or later can still be used with PYTHON_HOME
 
-'''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://github.com/tianocore/edk2-platforms). 
+'''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://github.com/tianocore/edk2-platforms).
 
 Once you have a basic build environment running, you can build a project in RELEASE or [[EDK II Debugging|DEBUG]] mode.
 
 ==GitHub Help==
 
-GitHub (https://help.github.com/index.html) provides step-by-step instructions for user registration and basic features supported by GitHub 
+GitHub (https://help.github.com/index.html) provides step-by-step instructions for user registration and basic features supported by GitHub
 
 * 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-scm.com/download/gui/win) | TortoiseGit (https://tortoisegit.org/)
 
 ===GitHub EDK II Project Repositories===
 
-* The EDK II project repository is available at https://github.com/tianocore/edk2. 
-* Prebuilt Windows tools are available at https://github.com/tianocore/edk2-BaseTools-win32. 
+* The EDK II project repository is available at https://github.com/tianocore/edk2.
+* Prebuilt Windows tools are available at https://github.com/tianocore/edk2-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 be found at https://github.com/tianocore/edk2-non-osi.
 
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]] 
-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 building 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 file)](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 "git" command <br>
-        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 BaseTools binaries and copy them to BaseTools binary folder.  Warning the Windows* Binary tools are only valid for the tip of the  https://github.com/tianocore/edk2 repository.
-         1)  `Cd C:\MyWorkspace`
-         2)  Run `git clone https://github.com/tianocore/edk2-BaseTools-win32.git`
-         3)  Enter folder edk2-BaseTools-win32
-         4)  Run the command `git checkout 0e088c19ab31fccd1d2f55d9e4fe0314b57c0097`
-         5)  `Cd C:\MyWorkSpace`
-         6)  Rename this folder from edk2-BaseTools-win32 to win32, then copy 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-HOWTO.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:\MyWorkspace`
-        to enter the  workspace directory
-    2)  Compile the BaseTools C source tools  
-<pre>
-	set PYTHON_HOME=C:\Python27
-        set EDK_TOOLS_PATH=%CD%\BaseTools
-        BaseTools\toolssetup.bat Rebuild
-</pre>
-
-5.  Build Steps
-    *** NT32 ***
-
-    1)  Open a Microsoft Visual Studio* command prompt, type `cd C:\MyWorkspace`
-        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 Application "`HelloWorld.efi`"  in the C:\MyWorkspace\Build\MdeModule\DEBUG_VS2015x86\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 tianocore.org.
-        "https://github.com/tianocore/tianocore.github.io/wiki/Using-EDK-II-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 compiler
-           are installed. Some operations need switch to user "root" to execute.
-         At Ubuntu, you can type `"sudo apt-get install git"` under terminal 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 terminal 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 terminal prompt to
-        install it.
-        You can also download the source package from https://acpica.org/downloads
-        and install it following the instruction on the website.
-     4) Install the C Compiler- Ubuntu 16.04 LTS  you can use GNU C compiler (v5.4.0) 
-        At Ubuntu, you can type `"sudo apt-get install gcc-5"` under terminal 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 "git" command 
-        1)  Run `"git clone https://github.com/tianocore/edk2.git vUDK2017"`
-        2)  Move all files and folders under "vUDK2017" to "~/src/MyWorkspace"
-	 
-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 workspace
-        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 <BR>
-        `"build  -p MdeModulePkg/MdeModulePkg.dsc -t GCC5"`
-    5)  Upon the build completing successfully there should be the UEFI Application "`HelloWorld.efi`"  in the ~/src/MyWorkspace/Build/MdeModule/DEBUG_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 with the new instructions if learning how to
+> build edk2 for the first time and not specifically targeting UDK2017. This 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 building 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 file)](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 "git" command <br>
+        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 BaseTools binaries and copy them to BaseTools binary folder.  Warning the Windows* Binary tools are only valid for the tip of the  https://github.com/tianocore/edk2 repository.
+         1)  `Cd C:\MyWorkspace`
+         2)  Run `git clone https://github.com/tianocore/edk2-BaseTools-win32.git`
+         3)  Enter folder edk2-BaseTools-win32
+         4)  Run the command `git checkout 0e088c19ab31fccd1d2f55d9e4fe0314b57c0097`
+         5)  `Cd C:\MyWorkSpace`
+         6)  Rename this folder from edk2-BaseTools-win32 to win32, then copy 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-HOWTO.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:\MyWorkspace`
+        to enter the  workspace directory
+    2)  Compile the BaseTools C source tools
+<pre>
+	set PYTHON_HOME=C:\Python27
+        set EDK_TOOLS_PATH=%CD%\BaseTools
+        BaseTools\toolssetup.bat Rebuild
+</pre>
+
+5.  Build Steps
+    *** NT32 ***
+
+    1)  Open a Microsoft Visual Studio* command prompt, type `cd C:\MyWorkspace`
+        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 Application "`HelloWorld.efi`"  in the C:\MyWorkspace\Build\MdeModule\DEBUG_VS2015x86\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 tianocore.org.
+        "https://github.com/tianocore/tianocore.github.io/wiki/Using-EDK-II-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 compiler
+           are installed. Some operations need switch to user "root" to execute.
+         At Ubuntu, you can type `"sudo apt-get install git"` under terminal 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 terminal 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 terminal prompt to
+        install it.
+        You can also download the source package from https://acpica.org/downloads
+        and install it following the instruction on the website.
+     4) Install the C Compiler- Ubuntu 16.04 LTS  you can use GNU C compiler (v5.4.0)
+        At Ubuntu, you can type `"sudo apt-get install gcc-5"` under terminal 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 "git" command
+        1)  Run `"git clone https://github.com/tianocore/edk2.git vUDK2017"`
+        2)  Move all files and folders under "vUDK2017" to "~/src/MyWorkspace"
+
+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 workspace
+        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 <BR>
+        `"build  -p MdeModulePkg/MdeModulePkg.dsc -t GCC5"`
+    5)  Upon the build completing successfully there should be the UEFI Application "`HelloWorld.efi`"  in the ~/src/MyWorkspace/Build/MdeModule/DEBUG_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]] 
-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 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 building 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 file)](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 "git" command <br>
-        1)  run  `git clone  https://github.com/tianocore/edk2.git vUDK2018`
-        2)  Go to the vUDK2018 directory, and from there run: `git checkout 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-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 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:\MyWorkspace`
-        to enter the  workspace directory
-    2)  Compile the BaseTools C source tools  
-<pre>
-	set PYTHON_HOME=C:\Python27
-        edksetup.bat Rebuild
-</pre>
-
-5.  Build Steps
-    *** NT32 ***
-
-    1)  Open a Microsoft Visual Studio* command prompt, type `cd C:\MyWorkspace`
-        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 Application "`HelloWorld.efi`"  in the C:\MyWorkspace\Build\NT32IA32\DEBUG_VS2015x86\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 tianocore.org.
-        "https://github.com/tianocore/tianocore.github.io/wiki/Using-EDK-II-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 compiler
-           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 terminal to
-        install it.
-        You can also download the source package from https://acpica.org/downloads
-        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 "git" command 
-        1)  Run `"git clone https://github.com/tianocore/edk2.git vUDK2018"`
-        2)  Go to the vUDK2018 directory, and from there run: `git checkout tags/vUDK2018 -b vUDK2018`
-        3)  Move all files and folders under "vUDK2018" to "~/src/MyWorkspace"
-	 
-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 workspace
-        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 <BR>
-        `"build  -p MdeModulePkg/MdeModulePkg.dsc -t GCC5"`
-    5)  Upon the build completing successfully there should be the UEFI Application "`HelloWorld.efi`"  in the ~/src/MyWorkspace/Build/MdeModule/DEBUG_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 with the new instructions if learning how to
+> build edk2 for the first time and not specifically targeting UDK2018. This 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 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 building 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 file)](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 "git" command <br>
+        1)  run  `git clone  https://github.com/tianocore/edk2.git vUDK2018`
+        2)  Go to the vUDK2018 directory, and from there run: `git checkout 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-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 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:\MyWorkspace`
+        to enter the  workspace directory
+    2)  Compile the BaseTools C source tools
+<pre>
+	set PYTHON_HOME=C:\Python27
+        edksetup.bat Rebuild
+</pre>
+
+5.  Build Steps
+    *** NT32 ***
+
+    1)  Open a Microsoft Visual Studio* command prompt, type `cd C:\MyWorkspace`
+        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 Application "`HelloWorld.efi`"  in the C:\MyWorkspace\Build\NT32IA32\DEBUG_VS2015x86\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 tianocore.org.
+        "https://github.com/tianocore/tianocore.github.io/wiki/Using-EDK-II-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 compiler
+           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 terminal to
+        install it.
+        You can also download the source package from https://acpica.org/downloads
+        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 "git" command
+        1)  Run `"git clone https://github.com/tianocore/edk2.git vUDK2018"`
+        2)  Go to the vUDK2018 directory, and from there run: `git checkout tags/vUDK2018 -b vUDK2018`
+        3)  Move all files and folders under "vUDK2018" to "~/src/MyWorkspace"
+
+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 workspace
+        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 <BR>
+        `"build  -p MdeModulePkg/MdeModulePkg.dsc -t GCC5"`
+    5)  Upon the build completing successfully there should be the UEFI Application "`HelloWorld.efi`"  in the ~/src/MyWorkspace/Build/MdeModule/DEBUG_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 systems.
-
-'''Note''': These instructions are not recommended for most EDK II developers. If you are working with a supported Linux distribution, then the [[Using EDK II with Native GCC]] instructions are faster, easier, and produce a smaller UEFI binary image.
-
-==Getting started for UNIX-like operating systems==
-
-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:
-
-<pre>
-bash$ echo this bold text is a sample command
-</pre>
-
-To execute this command, highlight the bold text of the command in your web 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, and 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 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 that 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 tell the shell program that the command is not finished.  For example:
-
-<pre>
-bash$ echo this bold text is a sample command \
-        which is broken into two lines
-</pre>
-
-When you copy and paste, make sure you include all lines of the command (including 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 your user password.  This will be the same password as you used to login to the system.
-
-For the purposes of this set of instructions, we will be using the following 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/iasl (symlink to compiler at ~/programs/iasl)
-|}
-
-You will need to change the commands if you want to use different locations, but this is not recommended unless you are sure that you know what you are doing.
-
-===Internet proxies===
-
-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 environment variable:
-
-<pre>
-bash$ export http_proxy=http://proxy.domain.com:proxy_port
-bash$ export ftp_proxy=$http_proxy
-</pre>
-
-To utilize the subversion source control command behind an internet firewall with a web proxy, you should configure the ~/.subversion/servers file.
-
-== Cygwin 1.7.1 ==
-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 done 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 /cygdrive 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.
-
-<big>
-Continue with common instructions for Unix
-</big>
-
-The [[Common instructions for Unix|remaining instructions]] are common for most UNIX-like systems.
-
-==Fedora 11==
-Please note:
-* Fedora 11 is not officially supported or tested by the edk2 project at this time.
-* These instructions assume that the Software Development option was enabled during the Fedora installation.
-
-===Open the GNOME Terminal program===
-
-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.
-
-===Install MPFR library===
-
-The MPFR library must be installed to allow the gcc cross compiler to be built.
-
-<pre>
-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=/usr
-bash$ make
-</pre>
-
-To install the library, you must be root.  Therefore we use 'su' to become the root user, for the 'make install' command.
-
-<pre>
-bash$ su
-bash$ make install
-bash$ exit
-</pre>
-
-<big>
-Continue with common instructions for Unix
-</big>
-
-The [[Common instructions for Unix |remaining instructions]] are common for most UNIX-like systems.
-
-==Mac OS X 10.5==
-===Xcode Tools===
-
-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 the Xcode installation disk image (which is fairly large).  These instructions were verified with Xcode 3.0.  Within the Xcode Tools disk image, only the Xcode Tools.mpkg package needs to be installed.
-
-===Open OS X Terminal program===
-
-Past this point, the remaining instructions will utilize OS X's built in command shell (bash) via the Terminal application.  To open the command terminal application, open Finder, then press the Cmd-Shift-U key combination.  (This opens the Applications => Utilities folder.)  In the Utilities folder, you should see the Terminal application.
-
-===GMP & MPFR (if behind a web proxy)===
-
-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 present 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.
-
-<pre>
-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=/usr
-bash$ make
-bash$ make check
-bash$ sudo make install
-</pre>
-
-Note: This might be needed for 64-bit machines if the MPFR configure fails below.
-<pre>
-bash$ export CFLAGS="-m64"
-</pre>
-
-<pre>
-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=/usr
-bash$ make
-bash$ sudo make install
-</pre>
-
-===GMP & MPFR via Macports (if not behind web proxy)===
-
-If you are not behind a network firewall, then the http://www.macports.org project can greatly simlify the installation of gmp & mpfr.  (Macports does 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.
-
-<pre>
-bash$ sudo port install gmp mpfr
-</pre>
-
-<big>
-Continue with common instructions for Unix
-</big>
-
-The [[Common instructions for Unix|remaining instructions]] are common for most UNIX-like systems.
-
-<!--
-==Red Hat Enterprise Linux 4 Desktop==
-Coming soon...
--->
-<!--
-==SuSE Linux Enterprise 10 Desktop==
-Coming soon...
--->
-
-==Ubuntu 9.10==
-Note: The Ubuntu platform is not officially supported or tested by the edk2 project at this time.
-
-===Open the GNOME Terminal program===
-
-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.
-
-===Install required software from apt===
-
-Several ubuntu packages will be needed to fully set up an edk2 build environment.  In order to easily install all the requirements, you need to run this command.
-
-<pre>
-bash$ sudo apt-get install build-essential uuid-dev texinfo \
-        bison flex libgmp3-dev libmpfr-dev subversion
-</pre>
-
-
-==Continue with common instructions for Unix==
-
-
-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 with 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 systems.
+
+'''Note''': These instructions are not recommended for most EDK II developers. If you are working with a supported Linux distribution, then the [[Using EDK II with Native GCC]] instructions are faster, easier, and produce a smaller UEFI binary image.
+
+==Getting started for UNIX-like operating systems==
+
+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:
+
+<pre>
+bash$ echo this bold text is a sample command
+</pre>
+
+To execute this command, highlight the bold text of the command in your web 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, and 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 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 that 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 tell the shell program that the command is not finished.  For example:
+
+<pre>
+bash$ echo this bold text is a sample command \
+        which is broken into two lines
+</pre>
+
+When you copy and paste, make sure you include all lines of the command (including 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 your user password.  This will be the same password as you used to login to the system.
+
+For the purposes of this set of instructions, we will be using the following 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/iasl (symlink to compiler at ~/programs/iasl)
+|}
+
+You will need to change the commands if you want to use different locations, but this is not recommended unless you are sure that you know what you are doing.
+
+===Internet proxies===
+
+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 environment variable:
+
+<pre>
+bash$ export http_proxy=http://proxy.domain.com:proxy_port
+bash$ export ftp_proxy=$http_proxy
+</pre>
+
+To utilize the subversion source control command behind an internet firewall with a web proxy, you should configure the ~/.subversion/servers file.
+
+== Cygwin 1.7.1 ==
+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 done 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 /cygdrive 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.
+
+<big>
+Continue with common instructions for Unix
+</big>
+
+The [[Common instructions for Unix|remaining instructions]] are common for most UNIX-like systems.
+
+==Fedora 11==
+Please note:
+* Fedora 11 is not officially supported or tested by the edk2 project at this time.
+* These instructions assume that the Software Development option was enabled during the Fedora installation.
+
+===Open the GNOME Terminal program===
+
+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.
+
+===Install MPFR library===
+
+The MPFR library must be installed to allow the gcc cross compiler to be built.
+
+<pre>
+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=/usr
+bash$ make
+</pre>
+
+To install the library, you must be root.  Therefore we use 'su' to become the root user, for the 'make install' command.
+
+<pre>
+bash$ su
+bash$ make install
+bash$ exit
+</pre>
+
+<big>
+Continue with common instructions for Unix
+</big>
+
+The [[Common instructions for Unix |remaining instructions]] are common for most UNIX-like systems.
+
+==Mac OS X 10.5==
+===Xcode Tools===
+
+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 the Xcode installation disk image (which is fairly large).  These instructions were verified with Xcode 3.0.  Within the Xcode Tools disk image, only the Xcode Tools.mpkg package needs to be installed.
+
+===Open OS X Terminal program===
+
+Past this point, the remaining instructions will utilize OS X's built in command shell (bash) via the Terminal application.  To open the command terminal application, open Finder, then press the Cmd-Shift-U key combination.  (This opens the Applications => Utilities folder.)  In the Utilities folder, you should see the Terminal application.
+
+===GMP & MPFR (if behind a web proxy)===
+
+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 present 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.
+
+<pre>
+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=/usr
+bash$ make
+bash$ make check
+bash$ sudo make install
+</pre>
+
+Note: This might be needed for 64-bit machines if the MPFR configure fails below.
+<pre>
+bash$ export CFLAGS="-m64"
+</pre>
+
+<pre>
+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=/usr
+bash$ make
+bash$ sudo make install
+</pre>
+
+===GMP & MPFR via Macports (if not behind web proxy)===
+
+If you are not behind a network firewall, then the http://www.macports.org project can greatly simlify the installation of gmp & mpfr.  (Macports does 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.
+
+<pre>
+bash$ sudo port install gmp mpfr
+</pre>
+
+<big>
+Continue with common instructions for Unix
+</big>
+
+The [[Common instructions for Unix|remaining instructions]] are common for most UNIX-like systems.
+
+<!--
+==Red Hat Enterprise Linux 4 Desktop==
+Coming soon...
+-->
+<!--
+==SuSE Linux Enterprise 10 Desktop==
+Coming soon...
+-->
+
+==Ubuntu 9.10==
+Note: The Ubuntu platform is not officially supported or tested by the edk2 project at this time.
+
+===Open the GNOME Terminal program===
+
+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.
+
+===Install required software from apt===
+
+Several ubuntu packages will be needed to fully set up an edk2 build environment.  In order to easily install all the requirements, you need to run this command.
+
+<pre>
+bash$ sudo apt-get install build-essential uuid-dev texinfo \
+        bison flex libgmp3-dev libmpfr-dev subversion
+</pre>
+
+
+==Continue with common instructions for Unix==
+
+
+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-Native-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 GCC installation (4.4+).  This EDK II setup does not require the Mingw version of GCC to be built, and therefore can be much faster to setup.
-
-==Getting Started==
-
-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:
-
-<pre>
-bash$ echo this text is a sample command
-</pre>
-
-To execute this command, highlight the text of the command in your web browser.  (Note that the 'bash$' text is not part of the command!)  Most web browsers should be able to copy the text by selecting Copy under the Edit menu.  Now, change back to the terminal application, and 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 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 that 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 tell the shell program that the command is not finished.  For example:
-
-<pre>
-bash$ echo this bold text is a sample command \
-        which is broken into two lines
-</pre>
-
-When you copy and paste, make sure you include all lines of the command (including 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 your user password.  This will be the same password as you used to login to the system.
-
-For the purposes of this set of instructions, we will be using the following 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 locations, but this is not recommended unless you are sure that you know what you are doing.
-
-===Internet proxies===
-
-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 environment variable:
-
-<pre>
-bash$ export http_proxy=http://proxy.domain.com:proxy_port
-bash$ export ftp_proxy=$http_proxy
-</pre>
-
-To utilize the subversion source control command behind an internet firewall with a web proxy, you should configure the ~/.subversion/servers file.
-
-===Ubuntu 20.04 LTS===
-
-Note: These instructions utilize GCC5 & NASM compiler support (added in early 2016), along with git (replaces subversion). GCC 4.x is still supported. GCC5 is not mandatory.
-
-====Open the GNOME Terminal program====
-
-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.
-
-====Install required software from apt====
-
-Several Ubuntu packages will be needed to set up the build environment for EDK II. The following command will install all required packages:
-
-<pre>
-bash$ sudo apt install build-essential uuid-dev iasl git  nasm  python-is-python3
-</pre>
-
-: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 tools use 'python'
-
-
-===Continue with common instructions===
-
-The [[Common instructions|remaining instructions]] are common for most UNIX-like systems.
-
-
-
-===Ubuntu 16.04 LTS / Ubuntu 16.10===
-
-Note: These instructions utilize GCC5 & NASM compiler support (added in early 2016), along with git (replaces subversion). GCC 4.x is still supported. GCC5 is not mandatory.
-
-====Open the GNOME Terminal program====
-
-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.
-
-====Install required software from apt====
-
-Several Ubuntu packages will be needed to set up the build environment for EDK II. The following command will install all required packages:
-
-<pre>
-bash$ sudo apt-get install build-essential uuid-dev iasl git gcc-5 nasm python3-distutils
-</pre>
-
-: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
-
-===Continue with common instructions===
-
-The [[Common instructions|remaining instructions]] are common for most UNIX-like systems.
-
-
-==Instructions for older Linux Environments==
-
-Note: the instructions below have not been updated for compilers newer than GCC 4.4, git (replaces subversion) or NASM. Newer builds may fail without satisfying these dependecies. We recommend moving to newer Linux distributions unless you have a dependency on a specific version.
-
-===Note: Limitations of GCC 4.4===
-
-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.
-
-===Arch Linux 2010.05===
-Note: Arch Linux is not officially supported or tested by the edk2 project at this time.
-
-====Open the GNOME Terminal program====
-
-These instructions will utilize Arch Linux'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.
-
-====Install required software with pacman====
-
-To install the required packages, you must be root.  Therefore we use 'su' to become the root user.
-
-<pre>
-bash$ su -
-bash$ pacman -S base-devel glibc iasl python2 subversion
-bash$ exit
-</pre>
-
-<big>
-Continue with common instructions
-</big>
-
-The [[Common instructions|remaining instructions]] are common for most UNIX-like systems.
-
-===Fedora 13===
-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 building UEFI for the IA32 architecture.
-
-====Open the GNOME Terminal program====
-
-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.
-
-====Install required software with yum====
-
-To install the required packages, you must be root.  Therefore we use 'su' to become the root user.
-
-<pre>
-bash$ su -
-bash$ yum groupinstall development-tools
-bash$ yum install iasl libuuid-devel
-bash$ exit
-</pre>
-
-<big>
-Continue with common instructions
-</big>
-
-The [[Common instructions|remaining instructions]] are common for most UNIX-like systems.
-
-===Mandriva 2010===
-Note: Mandriva is not officially supported or tested by the edk2 project at this time.
-
-Note: x86 (32-bit) Mandriva will install GCC 4.4 which is only capable of building UEFI for the IA32 architecture.
-
-====Open the Terminal program====
-
-These instructions will utilize Mandriva's built in command shell (bash) via the Terminal application.  To open the Terminal application, locate it under the Applications menu and the Tools sub-menu.
-
-====Install required software with urpmi====
-
-To install the required packages, you must be root.  Therefore we use 'su' to become the root user.
-
-<pre>
-bash$ su -
-bash$ urpmi task-c++-devel iasl libuuid-devel subversion
-bash$ exit
-</pre>
-
-<big>
-Continue with common instructions
-</big>
-
-The [[Common instructions|remaining instructions]] are common for most UNIX-like systems.
-
-===openSUSE 12.1===
-
-Note: openSUSE is not officially supported or tested by the edk2 project at this time.
-
-====Open the GNOME Terminal program====
-
-These instructions will utilize openSUSE's built in command shell (bash) via 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.
-
-====Install required software with zypper====
-
-Several openSUSE packages will be needed to fully set up an edk2 build environment.  In order to easily install all the requirements, you need to run this command.
-
-<pre>
-bash> sudo zypper in -t pattern devel_basis
-</pre>
-
-<big>
-Continue with common instructions
-</big>
-
-The [[Common instructions|remaining instructions]] are common for most UNIX-like systems.
-
-===Ubuntu 10.10===
-Notes:
-* The Ubuntu platform is not officially supported or tested by the edk2 project at this time.
-* Both the x86 (32-bit) and x86-64 (64-bit) Ubuntu versions will install GCC 4.4 which is capable of building UEFI for both the IA32 and X64 architectures.
-* These instructions should work for Ubuntu 10.04 as well
-
-====Open the GNOME Terminal program====
-
-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.
-
-====Install required software from apt====
-
-Several ubuntu packages will be needed to fully set up an edk2 build environment.  In order to easily install all the requirements, you need to run this command.
-
-<pre>
-bash$ sudo apt-get install build-essential subversion uuid-dev iasl
-</pre>
-
-
-===Continue with common instructions===
-
-The [[Common instructions|remaining instructions]] are common for most UNIX-like systems.
-
-
-=See Also=
-
+  Note: New build instructions are available. It is recommended to start with 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 GCC installation (4.4+).  This EDK II setup does not require the Mingw version of GCC to be built, and therefore can be much faster to setup.
+
+==Getting Started==
+
+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:
+
+<pre>
+bash$ echo this text is a sample command
+</pre>
+
+To execute this command, highlight the text of the command in your web browser.  (Note that the 'bash$' text is not part of the command!)  Most web browsers should be able to copy the text by selecting Copy under the Edit menu.  Now, change back to the terminal application, and 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 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 that 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 tell the shell program that the command is not finished.  For example:
+
+<pre>
+bash$ echo this bold text is a sample command \
+        which is broken into two lines
+</pre>
+
+When you copy and paste, make sure you include all lines of the command (including 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 your user password.  This will be the same password as you used to login to the system.
+
+For the purposes of this set of instructions, we will be using the following 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 locations, but this is not recommended unless you are sure that you know what you are doing.
+
+===Internet proxies===
+
+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 environment variable:
+
+<pre>
+bash$ export http_proxy=http://proxy.domain.com:proxy_port
+bash$ export ftp_proxy=$http_proxy
+</pre>
+
+To utilize the subversion source control command behind an internet firewall with a web proxy, you should configure the ~/.subversion/servers file.
+
+===Ubuntu 20.04 LTS===
+
+Note: These instructions utilize GCC5 & NASM compiler support (added in early 2016), along with git (replaces subversion). GCC 4.x is still supported. GCC5 is not mandatory.
+
+====Open the GNOME Terminal program====
+
+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.
+
+====Install required software from apt====
+
+Several Ubuntu packages will be needed to set up the build environment for EDK II. The following command will install all required packages:
+
+<pre>
+bash$ sudo apt install build-essential uuid-dev iasl git  nasm  python-is-python3
+</pre>
+
+: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 tools use 'python'
+
+
+===Continue with common instructions===
+
+The [[Common instructions|remaining instructions]] are common for most UNIX-like systems.
+
+
+
+===Ubuntu 16.04 LTS / Ubuntu 16.10===
+
+Note: These instructions utilize GCC5 & NASM compiler support (added in early 2016), along with git (replaces subversion). GCC 4.x is still supported. GCC5 is not mandatory.
+
+====Open the GNOME Terminal program====
+
+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.
+
+====Install required software from apt====
+
+Several Ubuntu packages will be needed to set up the build environment for EDK II. The following command will install all required packages:
+
+<pre>
+bash$ sudo apt-get install build-essential uuid-dev iasl git gcc-5 nasm python3-distutils
+</pre>
+
+: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
+
+===Continue with common instructions===
+
+The [[Common instructions|remaining instructions]] are common for most UNIX-like systems.
+
+
+==Instructions for older Linux Environments==
+
+Note: the instructions below have not been updated for compilers newer than GCC 4.4, git (replaces subversion) or NASM. Newer builds may fail without satisfying these dependecies. We recommend moving to newer Linux distributions unless you have a dependency on a specific version.
+
+===Note: Limitations of GCC 4.4===
+
+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.
+
+===Arch Linux 2010.05===
+Note: Arch Linux is not officially supported or tested by the edk2 project at this time.
+
+====Open the GNOME Terminal program====
+
+These instructions will utilize Arch Linux'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.
+
+====Install required software with pacman====
+
+To install the required packages, you must be root.  Therefore we use 'su' to become the root user.
+
+<pre>
+bash$ su -
+bash$ pacman -S base-devel glibc iasl python2 subversion
+bash$ exit
+</pre>
+
+<big>
+Continue with common instructions
+</big>
+
+The [[Common instructions|remaining instructions]] are common for most UNIX-like systems.
+
+===Fedora 13===
+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 building UEFI for the IA32 architecture.
+
+====Open the GNOME Terminal program====
+
+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.
+
+====Install required software with yum====
+
+To install the required packages, you must be root.  Therefore we use 'su' to become the root user.
+
+<pre>
+bash$ su -
+bash$ yum groupinstall development-tools
+bash$ yum install iasl libuuid-devel
+bash$ exit
+</pre>
+
+<big>
+Continue with common instructions
+</big>
+
+The [[Common instructions|remaining instructions]] are common for most UNIX-like systems.
+
+===Mandriva 2010===
+Note: Mandriva is not officially supported or tested by the edk2 project at this time.
+
+Note: x86 (32-bit) Mandriva will install GCC 4.4 which is only capable of building UEFI for the IA32 architecture.
+
+====Open the Terminal program====
+
+These instructions will utilize Mandriva's built in command shell (bash) via the Terminal application.  To open the Terminal application, locate it under the Applications menu and the Tools sub-menu.
+
+====Install required software with urpmi====
+
+To install the required packages, you must be root.  Therefore we use 'su' to become the root user.
+
+<pre>
+bash$ su -
+bash$ urpmi task-c++-devel iasl libuuid-devel subversion
+bash$ exit
+</pre>
+
+<big>
+Continue with common instructions
+</big>
+
+The [[Common instructions|remaining instructions]] are common for most UNIX-like systems.
+
+===openSUSE 12.1===
+
+Note: openSUSE is not officially supported or tested by the edk2 project at this time.
+
+====Open the GNOME Terminal program====
+
+These instructions will utilize openSUSE's built in command shell (bash) via 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.
+
+====Install required software with zypper====
+
+Several openSUSE packages will be needed to fully set up an edk2 build environment.  In order to easily install all the requirements, you need to run this command.
+
+<pre>
+bash> sudo zypper in -t pattern devel_basis
+</pre>
+
+<big>
+Continue with common instructions
+</big>
+
+The [[Common instructions|remaining instructions]] are common for most UNIX-like systems.
+
+===Ubuntu 10.10===
+Notes:
+* The Ubuntu platform is not officially supported or tested by the edk2 project at this time.
+* Both the x86 (32-bit) and x86-64 (64-bit) Ubuntu versions will install GCC 4.4 which is capable of building UEFI for both the IA32 and X64 architectures.
+* These instructions should work for Ubuntu 10.04 as well
+
+====Open the GNOME Terminal program====
+
+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.
+
+====Install required software from apt====
+
+Several ubuntu packages will be needed to fully set up an edk2 build environment.  In order to easily install all the requirements, you need to run this command.
+
+<pre>
+bash$ sudo apt-get install build-essential subversion uuid-dev iasl
+</pre>
+
+
+===Continue with common instructions===
+
+The [[Common instructions|remaining instructions]] are common for most UNIX-like systems.
+
+
+=See Also=
+
 * [[Unix-like systems]] - Instructions which walk through building the Mingw 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.tianocore.org/edk2/ EDK II] build environment on Windows systems.
-
-<u>''Table of Contents''</u>
-* [[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
-
-==GitHub Help==
-
-GitHub (https://help.github.com/index.html) provides step-by-step instructions for user registration and basic features supported by GitHub.
-
-=== Git GUI Interface for Windows OS ===
-* Git for Windows OS is available at: (http://git-scm.com/download/win)
-* TortoiseGit for windows OS is available at (https://tortoisegit.org/download/)
-
-=='''GitHub EDK II Project Repositories'''==
-
-* The EDK II project repository is available at https://github.com/tianocore/edk2. 
-
-Content that is not released under an accepted open source license can be found at https://github.com/tianocore/edk2-non-osi.<br />
-&nbsp;<br />
-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 for [[UDK2017]]: https://github.com/tianocore/tianocore.github.io/wiki/UDK2017-How-to-Build#how-to-build-windows-system 
-
-===Internet proxies===
-
-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:
-
-<pre>
-    $ git config --global https.proxy <proxyname>.domain.com:<port>
-    $ git config --global http.proxy <proxyname>.domain.com:<port>
-</pre>
-
-
-=='''How to Setup the EDK II Tree'''==
-'''Note:''' Some of the following examples use the Multiple Workspace feature to configure the EDK II BaseTools.  More information on the Multiple Workspace feature can be found at the following location. <BR>
-* [[Multiple_Workspace]]
-
-=='''Download'''==
-Download/Checkout the EDK II source tree from Github
-=== Download Using a Web browser ===
-
-# 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 “edk2-master” to “edk2”  
-
-Continue to [[Windows-systems#compile-tools |Compile Tools]] 
-
-=== Using '''Git for Windows''' Application ===
-==== ''Git GUI''====
-# Clone the EDK II project repository
-## Open Git GUI
-## Use ''Clone Exiting Repository'' with Source location https://github.com/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
-
-==== ''Git CMD'' ====
-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
-<pre>
-    $git clone https://github.com/tianocore/edk2
-</pre>
-
-Continue to [[Windows-systems#compile-tools |Compile Tools]] and then [[Windows-systems#build | BUILD]] sections
-
-=='''Compile Tools'''==
-=====For EDK II project developers on Windows with source BaseTools:=====
-*	Create a workspace directory
-*	Change to the workspace directory
-*	Clone the EDK II project repository (See [[Windows-systems#download| Download]] section above)
-**	Example: git clone https://github.com/tianocore/edk2
-* Install Python37 or late version (https://www.python.org/)  to run python tool from source 
-* Compile BaseTools C source tools
-Example:
-* Inside Git Bash
-<pre>
-     $ git clone https://github.com/tianocore/edk2
-</pre>
-=====Compile BaseTools=====
-Example:
-*Open Command prompt and CD C:\edk2:
-<pre>
+__NOTOC__
+
+  Note: New build instructions are available. It is recommended to start with 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.tianocore.org/edk2/ EDK II] build environment on Windows systems.
+
+<u>''Table of Contents''</u>
+* [[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
+
+==GitHub Help==
+
+GitHub (https://help.github.com/index.html) provides step-by-step instructions for user registration and basic features supported by GitHub.
+
+=== Git GUI Interface for Windows OS ===
+* Git for Windows OS is available at: (http://git-scm.com/download/win)
+* TortoiseGit for windows OS is available at (https://tortoisegit.org/download/)
+
+=='''GitHub EDK II Project Repositories'''==
+
+* The EDK II project repository is available at https://github.com/tianocore/edk2.
+
+Content that is not released under an accepted open source license can be found at https://github.com/tianocore/edk2-non-osi.<br />
+&nbsp;<br />
+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 for [[UDK2017]]: https://github.com/tianocore/tianocore.github.io/wiki/UDK2017-How-to-Build#how-to-build-windows-system
+
+===Internet proxies===
+
+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:
+
+<pre>
+    $ git config --global https.proxy <proxyname>.domain.com:<port>
+    $ git config --global http.proxy <proxyname>.domain.com:<port>
+</pre>
+
+
+=='''How to Setup the EDK II Tree'''==
+'''Note:''' Some of the following examples use the Multiple Workspace feature to configure the EDK II BaseTools.  More information on the Multiple Workspace feature can be found at the following location. <BR>
+* [[Multiple_Workspace]]
+
+=='''Download'''==
+Download/Checkout the EDK II source tree from Github
+=== Download Using a Web browser ===
+
+# 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 “edk2-master” to “edk2”
+
+Continue to [[Windows-systems#compile-tools |Compile Tools]]
+
+=== Using '''Git for Windows''' Application ===
+==== ''Git GUI''====
+# Clone the EDK II project repository
+## Open Git GUI
+## Use ''Clone Exiting Repository'' with Source location https://github.com/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
+
+==== ''Git CMD'' ====
+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
+<pre>
+    $git clone https://github.com/tianocore/edk2
+</pre>
+
+Continue to [[Windows-systems#compile-tools |Compile Tools]] and then [[Windows-systems#build | BUILD]] sections
+
+=='''Compile Tools'''==
+=====For EDK II project developers on Windows with source BaseTools:=====
+*	Create a workspace directory
+*	Change to the workspace directory
+*	Clone the EDK II project repository (See [[Windows-systems#download| Download]] section above)
+**	Example: git clone https://github.com/tianocore/edk2
+* Install Python37 or late version (https://www.python.org/)  to run python tool from source
+* Compile BaseTools C source tools
+Example:
+* Inside Git Bash
+<pre>
+     $ git clone https://github.com/tianocore/edk2
+</pre>
+=====Compile BaseTools=====
+Example:
+*Open Command prompt and CD C:\edk2:
+<pre>
      C:\edk2> set PYTHON_HOME=C:\Python37
-     C:\edk2> edksetup.bat Rebuild
-</pre>
-
-
-=='''Build'''==
-* 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
-
-===Build MdeModulePkg===
-
-
-====Modify Conf files====
-
-You will need to edit the Conf\target.txt file.  First, change the ACTIVE_PLATFORM to the MdeModulePkg:
-
-<pre>
-C:\edk2> notepad Conf\target.txt
-</pre>
-
-ACTIVE_PLATFORM should look like this in Conf\target.txt:
-
-<pre>
-ACTIVE_PLATFORM       = MdeModulePkg/MdeModulePkg.dsc
-</pre>
-
-Modify TOOL_CHAIN_TAG in target.txt for the toolchain installed on your system. There are many options, so review the tools_def.txt to find the appropriate toolchain for your system.  Search for 'Supported Tool Chains' in tools_def.txt to see the valid options for TOOL_CHAIN_TAG. 
-<pre>
-TOOL_CHAIN_TAG        = VS2015x86
-</pre>
-
-
-
-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.
-
-====Build Hello World!  (and the rest of MdeModulePkg)====
-
-Now you should be able to simply run the build command to compile the MdeModulePkg.
-
-<pre>
-C:\edk2> build
-</pre>
-
-As a tangible result of the build, you should have the HelloWorld UEFI application.  If you have a UEFI system available to you which matches the processor architecture that you built, then this application should be able to run successfully under the shell.
-
-<pre>
-C:\edk2> dir /s Build\MdeModule\DEBUG_...\IA32\HelloWorld.efi
-</pre>
-
-===Build [[OVMF]] (OPTIONAL)===
-
-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.  Since [[OVMF]] builds a full system firmware image this may be of interest to UEFI system firmware developers.
-
-=See Also=
-* [[Getting-Started-Writing-Simple-Application]]
-
+     C:\edk2> edksetup.bat Rebuild
+</pre>
+
+
+=='''Build'''==
+* 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
+
+===Build MdeModulePkg===
+
+
+====Modify Conf files====
+
+You will need to edit the Conf\target.txt file.  First, change the ACTIVE_PLATFORM to the MdeModulePkg:
+
+<pre>
+C:\edk2> notepad Conf\target.txt
+</pre>
+
+ACTIVE_PLATFORM should look like this in Conf\target.txt:
+
+<pre>
+ACTIVE_PLATFORM       = MdeModulePkg/MdeModulePkg.dsc
+</pre>
+
+Modify TOOL_CHAIN_TAG in target.txt for the toolchain installed on your system. There are many options, so review the tools_def.txt to find the appropriate toolchain for your system.  Search for 'Supported Tool Chains' in tools_def.txt to see the valid options for TOOL_CHAIN_TAG.
+<pre>
+TOOL_CHAIN_TAG        = VS2015x86
+</pre>
+
+
+
+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.
+
+====Build Hello World!  (and the rest of MdeModulePkg)====
+
+Now you should be able to simply run the build command to compile the MdeModulePkg.
+
+<pre>
+C:\edk2> build
+</pre>
+
+As a tangible result of the build, you should have the HelloWorld UEFI application.  If you have a UEFI system available to you which matches the processor architecture that you built, then this application should be able to run successfully under the shell.
+
+<pre>
+C:\edk2> dir /s Build\MdeModule\DEBUG_...\IA32\HelloWorld.efi
+</pre>
+
+===Build [[OVMF]] (OPTIONAL)===
+
+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.  Since [[OVMF]] builds a full system firmware image this may be of interest to UEFI system firmware developers.
+
+=See Also=
+* [[Getting-Started-Writing-Simple-Application]]
+
 <!-- [[Category:EDKII]] -->
\ No newline at end of file
-- 
2.28.0.windows.1