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

[Evan Lloyd <Evan.Lloyd@arm.com>]

Reviewed-by: Evan Lloyd <evan.lloyd@arm.com>

Leif - would it make sense/be acceptable to add a GNU make.exe image to edk2-non-osi?

Evan


> -----Original Message-----
> From: Leif Lindholm <leif.lindholm@linaro.org>
> Sent: 03 July 2018 11:24
> To: Chris Co <Christopher.Co@microsoft.com>
> Cc: edk2-devel@lists.01.org; Ard Biesheuvel <ard.biesheuvel@linaro.org>;
> Michael D Kinney <michael.d.kinney@intel.com>; Evan Lloyd
> <Evan.Lloyd@arm.com>
> Subject: Re: [PATCH edk2-platforms v2 3/3] Readme.md: Add instructions to
> build in a Windows Environment
>
> Hi Christopher,
>
> Patches 1-2 Reviewed-by: Leif Lindholm <leif.lindholm@linaro.org> Pushed
> as 5ed298efba..df5cbc93b8 - thanks!
>
> In general, I'm happy enough with the below that I might just push that as
> well, but I will give others a chance to pipe up.
> (Adding Evan to cc.)
>
> I have one comment below.
>
> On Tue, Jul 03, 2018 at 02:29:38AM +0000, Chris Co wrote:
> > 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
>
> Ideally, we would have a single section for this, regardless of build platform.
> You're adding info about submodule handling here that we'd otherwise need
> to duplicate to the Linux section, and keep in sync.
>
> /
>     Leif
>
> > +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/BuildNot
> es.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
> >
IMPORTANT NOTICE: The contents of this email and any attachments are confidential and may also be privileged. If you are not the intended recipient, please notify the sender immediately and do not disclose the contents to any other person, use it for any purpose, or store or copy the information in any medium. Thank you.