[PATCH edk2-platforms v2 3/3] Readme.md: Add instructions to build in a Windows Environment

[Chris Co <Christopher.Co@microsoft.com>]

These instructions explain how to setup a Windows build environment
with extra instructions to build for ARM platforms
using the GCC cross-compiler toolchain.

Contributed-under: TianoCore Contribution Agreement 1.1
Signed-off-by: Christopher Co <christopher.co@microsoft.com>
Cc: Ard Biesheuvel <ard.biesheuvel@linaro.org>
Cc: Leif Lindholm <leif.lindholm@linaro.org>
Cc: Michael D Kinney <michael.d.kinney@intel.com>
---
 Readme.md | 249 +++++++++++++++++++-
 1 file changed, 248 insertions(+), 1 deletion(-)

diff --git a/Readme.md b/Readme.md
index 6ad5953093d6..9916db7f3a1f 100644
--- a/Readme.md
+++ b/Readme.md
@@ -190,8 +190,255 @@ $ ./uefi-tools/edk2-build.sh -b DEBUG -b RELEASE
 
 # How To Build (Windows Environment)
 
-(I genuinely have no idea. Please help!)
+These instructions will be a summary of the
+[Windows Systems wiki entry](https://github.com/tianocore/tianocore.github.io/wiki/Windows-systems).
+The wiki entry is targeted towards using the Visual Studio compiler.  The
+instructions below will have some extra steps if you are cross-compiling with GCC.
 
+## Prerequisites
+You will need Git for Windows and Visual Studio installed to build EDK2 from source.
+If you wish to build the build tools, you will also need Python 2.7 for Windows
+and cx_Freeze.
+
+## If cross compiling
+If building EDK2 for a different architecture than the build machine, you need to
+obtain an appropriate cross-compiler. X64 (x86_64) compilers also support IA32,
+but the reverse may not always be true.
+
+Target architecture | Cross compilation prefix
+--------------------|-------------------------
+ARM                 | arm-eabi-
+
+### GCC
+Linaro provides a Windows-compatible GCC toolchain for [arm-eabi](https://releases.linaro.org/components/toolchain/binaries/latest/arm-eabi/)
+compiled to run on x86_64/i686 Windows.  Select the i686 mingw32 variant.
+
+To use the GCC toolchain, you will also need a Windows-compatible GNU Make.  These
+instructions will use [MinGW](http://mingw.org/) but any Windows-compatible
+GNU Make tool will work.
+
+## Obtaining source code
+1. Create a new folder (directory) on your local development machine
+   for use as your workspace. This example uses `C:\git\tianocore`, modify as
+   appropriate for your needs.
+
+1. In a Windows command prompt:
+   ```
+   > set WORKSPACE=C:\git\tianocore
+   > mkdir %WORKSPACE%
+   > cd %WORKSPACE%
+   ```
+
+1. Into that folder, clone:
+   1. [edk2](https://github.com/tianocore/edk2)
+   1. [edk2-platforms](https://github.com/tianocore/edk2-platforms)
+   1. [edk2-non-osi](https://github.com/tianocore/edk2-non-osi) (if building
+      platforms that need it)
+   ```
+   > git clone https://github.com/tianocore/edk2.git
+   ...
+   > git clone https://github.com/tianocore/edk2-platforms.git
+   ...
+   > git clone https://github.com/tianocore/edk2-non-osi.git
+   ```
+
+1. Clone submodules
+   ```
+   > pushd edk2
+   > git submodule update --init --recursive
+   > popd
+   ```
+
+1. Set up a **PACKAGES_PATH** to point to the locations of these three
+   repositories.
+
+   Note: only set the path with valid locations.  If you don't use edk2-non-osi,
+   do not add it to your **PACKAGES_PATH**. Otherwise, you will get errors during build.
+
+   `> set PACKAGES_PATH=%WORKSPACE%\edk2;%WORKSPACE%\edk2-platforms;%WORKSPACE%\edk2-non-osi`
+
+### If cross-compiling with GCC
+#### GNU Make
+These instructions will walk through getting and setting up mingw32-make.exe. You are
+free to use other GNU make tools if those are more comfortable for you. Just make sure
+the GNU make is Windows-compatible and in your PATH.
+
+1. Download the latest [MinGW setup installer](https://sourceforge.net/projects/mingw/files/).
+
+1. Run the setup and make sure you note down the installation directory.
+This is where you will grab the binary tools later.
+
+   Note: According to the
+   [MinGW Getting Started](http://mingw.org/wiki/Getting_Started),
+do not use an installation path which contains containing spaces as
+the spaces may be problems.
+
+1. Once the setup is done, launch the MinGW Installation Manager.
+
+1. Now you will get the **make** executable.  In this case, you will get **mingw32-make.exe**
+since this will work directly in a Windows environment.  In the installer, select
+**All Packages**.  Scroll through the list and select the packages named `mingw32-make`.
+Specifically, you will need the `bin` class package, which contains **mingw32-make.exe**.
+
+1. Go to the Installation drop down menu and `Apply Changes`.  This will start
+the download of the `mingw32-make` package into your installation directory from earlier.
+Once it is done, you should have a **mingw32-make.exe** and a few other .dlls in `<MinGW folder>\bin`
+
+1. Copy the contents of the bin folder to a folder in your workspace.
+You need to copy **mingw32-make.exe** and its associated dynamically loaded libraries.
+   ```
+   > mkdir %WORKSPACE%\GNUMake
+   > pushd %WORKSPACE%\GNUMake
+   > copy <path to MinGW folder>\bin %WORKSPACE%\GNUMake
+   > popd
+   ```
+
+1. Update PATH to have GNUMake folder so you can run **mingw32-make.exe** from anywhere.
+
+   `> set PATH=%WORKSPACE%\GNUMake;%PATH%`
+
+1. By default, the EDK2 tools will invoke **make** and not **mingw32-make**.  To fix this,
+set **GNU_HOST_BIN** to add the `mingw32-` prefix.
+
+   `> set GNU_HOST_BIN=mingw32-`
+
+#### GCC Cross Compiler
+1. Download your desired GCC cross-compiler.  For ARM32, use
+[arm-eabi](https://releases.linaro.org/components/toolchain/binaries/latest/arm-eabi/)
+provided by Linaro.  Make sure to download the i686 mingw version.
+
+1. Extract the cross compiler.  You can use 7-zip or Windows Subsystem for Linux
+`tar xvf` to extract the contents to a folder.
+
+1. Create a new folder in your workspace and copy the contents into your workspace.
+   ```
+   > mkdir %WORKSPACE%\Toolchains
+   > pushd %WORKSPACE%\Toolchains
+   > copy <path to extracted GCC cross compiler> %WORKSPACE%\Toolchains
+   > popd
+   ```
+
+   At this point, you should have the gcc executables in `%WORKSPACE%\Toolchains\bin`.
+
+1. Update PATH to have the Toolchains\bin folder so you can run the toolchain binaries from anywhere.
+
+   `> set PATH=%WORKSPACE%\Toolchains\bin;%PATH%`
+
+## Manual building
+1. Install the latest Microsoft Visual Studio from the [Visual Studio website](https://visualstudio.microsoft.com/downloads/).
+
+1. Get the BaseTools.  You can either build them from source or fetch prebuilt binaries.
+   * To build from source, follow the Windows instructions found [here](https://github.com/tianocore/edk2/blob/master/BaseTools/BuildNotes.txt).
+   Note that this requires Python 2.7 and cx_Freeze.
+   * To use prebuilt binaries, clone
+   [edk2-BaseTools-win32](https://github.com/tianocore/edk2-BaseTools-win32)
+   and set **EDK_TOOLS_BIN** to point to this location.
+   ```
+   > git clone https://github.com/tianocore/edk2-BaseTools-win32.git
+   ...
+   > set EDK_TOOLS_BIN=%WORKSPACE%\edk2-BaseTools-win32
+   ```
+
+1. Set **PATH** to include the location of the BaseTools.  For example:
+
+   `> set PATH=%WORKSPACE%\edk2-BaseTools-win32;%PATH%`
+
+1. Set up the build environment (this will modify your environment variables)
+
+   `> %WORKSPACE%\edk2\edksetup.bat`
+
+   (This step _depends_ on **WORKSPACE** being set as per above.)
+
+   You may see a few warnings or errors:
+   * PYTHON_HOME environment variable is only needed if you plan to build the BaseTools
+   from source in the next step.
+   * You may see warnings for NASM or CYGWIN paths not being set.
+   These could be benign depending on your build toolchain.
+   For our GCC cross-compile setup, we do not use NASM or Cygwin.
+
+   `edksetup.bat` script will generate config files into the `%WORKSPACE%\edk2\Conf` folder.
+   If you have made changes to your general configuration, you will need to rerun this
+   script with the `Reconfig` argument to regenerate the files in the Conf folder.
+
+1. Install the ASL compiler (if necessary) for your platform. Follow
+the instructions found [here](https://github.com/tianocore/tianocore.github.io/wiki/Asl-Setup) to install
+the official ASL compiler.
+
+   Note: certain Windows IoT platforms may require the Microsoft ASL compiler.
+   The Microsoft ASL compiler (asl.exe) can be obtained from the Windows Driver Kit
+   ([WDK](https://docs.microsoft.com/en-us/windows-hardware/drivers/download-the-wdk)).
+   It can be found in the `<path to Windows Kits>\tools\<host arch>\ACPIVerify\` folder.
+
+1. Update **PATH** to include the location of the ASL compiler
+
+   `> set PATH=<path to your ASL compiler>;%PATH%`
+
+### Build options
+There are a number of options that can (or must) be specified at the point of
+building. Their default values are set in `edk2\Conf\target.txt`. If we are
+working only on a single platform, it makes sense to just update this file.
+
+target.txt option | command line | Description
+------------------|--------------|------------
+ACTIVE_PLATFORM   | `-p`         | Description file (.dsc) of platform.
+TARGET            | `-b`         | One of DEBUG, RELEASE or NOOPT.
+TARGET_ARCH       | `-a`         | Architecture to build for.
+TOOL_CHAIN_TAG    | `-t`         | Toolchain profile to use for building.
+
+There is also MAX_CONCURRENT_THREAD_NUMBER (`-n`), roughly equivalent to
+`make -j`.
+
+When specified on command line, `-b` can be repeated multiple times in order to
+build multiple targets sequentially.
+
+After a successful build, the resulting images can be found in
+`%WORKSPACE%\Build\{Platform Name}\{TARGET}_{TOOL_CHAIN_TAG}\FV`.
+
+#### If cross-compiling
+When cross-compiling, we additionally need to inform the build command which toolchain to use.
+We do this by setting the environment variable `{TOOL_CHAIN_TAG}_{TARGET_ARCH}_PREFIX`
+
+So if we are using GCC5 cross compiler toolchain, we should set
+
+   > set GCC5_ARM_PREFIX=arm-eabi-
+
+to prepend the **gcc** build command line with **arm-eabi-**
+
+### Build a platform
+The main build process _can_ run in parallel - so figure out how many threads we
+have available.
+
+```
+> echo %NUMBER_OF_PROCESSORS%
+8
+```
+OK, so we have 8 CPUs - let's tell the build to use a little more than that:
+```
+> set /A NUM_CPUS=%NUMBER_OF_PROCESSORS%+2
+```
+For the toolchain tag, select a toolchain that is compatible with building in a Windows Environment. Search for 'Supported Tool Chains' in tools_def.txt to see the valid options for `TOOL_CHAIN_TAG`.  If using Visual Studio Compiler, consult the
+[VS Toolchain Matrix](https://github.com/tianocore/tianocore.github.io/wiki/Windows-systems-ToolChain-Matrix)
+to determine the proper VS `TOOL_CHAIN_TAG`.
+
+```
+> build -n %NUM_CPUS% -a ARM -t GCC5 -p Platform/NXP/SABRESD_IMX6Q_1GB/SABRESD_IMX6Q_1GB.dsc
+```
+
+(Note that the description file gets resolved by the build command through
+searching in all locations specified in **PACKAGES_PATH**.)
+
+### Clean Rebuild
+EDK2 build system will cache the build configuration in the `edk2\Conf` folder when you
+first you invoke a build.  Subsequent builds will reference this cached
+configuration.  If you make a minor change to the build template, it is recommended
+to run:
+
+   `> %WORKSPACE%\edk2\edksetup.bat Reconfig`
+
+which will regenerate the contents of `edk2\Conf` folder.
+
+You should also delete the output folder (`%WORKSPACE%\Build\{Platform Name}\{TARGET}_{TOOL_CHAIN_TAG}`)
+to remove any stale Makefiles and configurations generated during from the previous build.
 
 # Supported Platforms
 
-- 
2.16.2.gvfs.1.33.gf5370f1