Hi Christopher, Patches 1-2 Reviewed-by: Leif Lindholm <[email protected]> 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 <[email protected]> > Cc: Ard Biesheuvel <[email protected]> > Cc: Leif Lindholm <[email protected]> > Cc: Michael D Kinney <[email protected]> > --- > 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/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 > _______________________________________________ edk2-devel mailing list [email protected] https://lists.01.org/mailman/listinfo/edk2-devel
