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 +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
