From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received-SPF: Pass (sender SPF authorized) identity=mailfrom; client-ip=104.47.36.92; helo=nam02-sn1-obe.outbound.protection.outlook.com; envelope-from=christopher.co@microsoft.com; receiver=edk2-devel@lists.01.org Received: from NAM02-SN1-obe.outbound.protection.outlook.com (mail-sn1nam02on0092.outbound.protection.outlook.com [104.47.36.92]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-SHA384 (256/256 bits)) (No client certificate requested) by ml01.01.org (Postfix) with ESMTPS id 50EC8210F200C for ; Mon, 2 Jul 2018 19:29:41 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com; s=selector1; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=bNj+TNT4dNT+R9nilqYgHaSDswr/0NIkPJltZHIcL3Q=; b=P8iTvCzTKrvLM5YGkol+1+woiR9vr2myFQidoIeQawYkRF0Usv8wKeHbNpzPJCp+dNkQNKwxujWg5m4xCCGwW+u+ienhyy7iZDHAe2s9qSkpk4kemizl1eimzrLvnBVXnB7aSUvQKJUmrQOtiOQVpL3P/ZJ6hdfN61oBR/dPsdc= Received: from DM5PR2101MB1128.namprd21.prod.outlook.com (52.132.133.20) by DM5PR2101MB0903.namprd21.prod.outlook.com (52.132.132.160) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.952.4; Tue, 3 Jul 2018 02:29:38 +0000 Received: from DM5PR2101MB1128.namprd21.prod.outlook.com ([fe80::28cb:9380:49e8:e0d0]) by DM5PR2101MB1128.namprd21.prod.outlook.com ([fe80::28cb:9380:49e8:e0d0%2]) with mapi id 15.20.0952.005; Tue, 3 Jul 2018 02:29:38 +0000 From: Chris Co To: "edk2-devel@lists.01.org" CC: Ard Biesheuvel , Leif Lindholm , Michael D Kinney Thread-Topic: [PATCH edk2-platforms v2 3/3] Readme.md: Add instructions to build in a Windows Environment Thread-Index: AQHUEnWw9M2+zOEEY0yjc+iimdpz7w== Date: Tue, 3 Jul 2018 02:29:38 +0000 Message-ID: <20180703022925.53408-4-christopher.co@microsoft.com> References: <20180703022925.53408-1-christopher.co@microsoft.com> In-Reply-To: <20180703022925.53408-1-christopher.co@microsoft.com> Accept-Language: en-US X-MS-Has-Attach: X-MS-TNEF-Correlator: x-clientproxiedby: MWHPR22CA0034.namprd22.prod.outlook.com (2603:10b6:300:69::20) To DM5PR2101MB1128.namprd21.prod.outlook.com (2603:10b6:4:a8::20) x-ms-exchange-messagesentrepresentingtype: 1 x-originating-ip: [2001:4898:80e8:9:84f4:cf5:da9e:d4ad] x-ms-publictraffictype: Email x-microsoft-exchange-diagnostics: 1; DM5PR2101MB0903; 7:kC9dsg0U0PJvvJjiOTHjLlfW9cQCSUkdIujiyijwDv+Q1AAnH/52ffNeNQFHkI1oHuJ4e1ETLrTCmKGJJrLtdP8b0pL6SDw0h1kibjvPT2g2zMzEFJ4HoLMVF/nYIDxWf0yjkeSv6fU+HBdmcqdv2uf8vAf9zJxOddIfCh5g4E9MM7AP+dbsWySwwB2f5VhfQcLgth4Z76JqXHLxc4fd85/o4LPfS7cQRS5/9xE2PC9tJyhWmoS9SxPWsqQ1wfZ5 x-ms-office365-filtering-ht: Tenant x-ms-office365-filtering-correlation-id: 4bf4c0a3-40c4-4bcf-3eb9-08d5e08cd2f2 x-microsoft-antispam: UriScan:; BCL:0; PCL:0; RULEID:(7020095)(4652040)(8989117)(48565401081)(5600053)(711020)(4534165)(4627221)(201703031133081)(201702281549075)(8990107)(2017052603328)(7193020); SRVR:DM5PR2101MB0903; x-ms-traffictypediagnostic: DM5PR2101MB0903: x-microsoft-antispam-prvs: x-exchange-antispam-report-test: UriScan:(28532068793085)(89211679590171)(166708455590820)(111885846020525)(42262312472803)(5213294742642)(228905959029699); x-ms-exchange-senderadcheck: 1 x-exchange-antispam-report-cfa-test: BCL:0; PCL:0; RULEID:(8211001083)(6040522)(2401047)(8121501046)(5005006)(3231274)(2018427008)(944501410)(52105095)(10201501046)(3002001)(93006095)(93001095)(6055026)(149027)(150027)(6041310)(20161123560045)(20161123564045)(20161123558120)(20161123562045)(201703131423095)(201702281528075)(20161123555045)(201703061421075)(201703061406153)(6072148)(201708071742011)(7699016); SRVR:DM5PR2101MB0903; BCL:0; PCL:0; RULEID:; SRVR:DM5PR2101MB0903; x-forefront-prvs: 0722981D2A x-forefront-antispam-report: SFV:NSPM; SFS:(10019020)(376002)(366004)(39860400002)(136003)(346002)(396003)(174874002)(199004)(189003)(305945005)(52116002)(486006)(2900100001)(106356001)(105586002)(476003)(478600001)(86362001)(7736002)(72206003)(10290500003)(4326008)(25786009)(5250100002)(8936002)(86612001)(53936002)(14454004)(966005)(76176011)(2501003)(8676002)(53376002)(6116002)(446003)(97736004)(99286004)(6512007)(6306002)(256004)(14444005)(6486002)(46003)(5640700003)(6436002)(6506007)(2616005)(2351001)(386003)(1076002)(6916009)(2906002)(36756003)(68736007)(10090500001)(11346002)(5660300001)(186003)(54906003)(81156014)(22452003)(81166006)(6346003)(316002)(102836004)(460985005)(134885004); DIR:OUT; SFP:1102; SCL:1; SRVR:DM5PR2101MB0903; H:DM5PR2101MB1128.namprd21.prod.outlook.com; FPR:; SPF:None; LANG:en; PTR:InfoNoRecords; A:1; MX:1; received-spf: None (protection.outlook.com: microsoft.com does not designate permitted sender hosts) authentication-results: spf=none (sender IP is ) smtp.mailfrom=Christopher.Co@microsoft.com; x-microsoft-antispam-message-info: hxuMkmgxzBP4Jrl7YWa8sZplRyjYVM9zFaFAgBOQQWOuKdjstlE11Eqi40+ShDwflQs4t6q0A72QfTpQvlc7mdwSNXxIXt6SHa3DE1Lg4hG1O+LfNv1/nAdbo2AFeJfZe+upnzvzfSbbYqUalkk77xZUePROHzrBKc3TWTaTShhqVlBjVC1NqpZrRsFR5bq0ObyZj0S29iaRT0ERLR4UKYdHBfdbX/N/lie2uLobjHPDHSFdz2RUwvSyk7dHQtzVX/m67Y6rhGNVIgtNiNvZ4X1v1IY5BnY5CZDGQ8pGbaB1o2e5lHLGZSSnyUqQHtnr60WaOxhxLDZvs/MuLotutZMZdMf6GsZGyBFfbvDxOYs= spamdiagnosticoutput: 1:99 spamdiagnosticmetadata: NSPM MIME-Version: 1.0 X-OriginatorOrg: microsoft.com X-MS-Exchange-CrossTenant-Network-Message-Id: 4bf4c0a3-40c4-4bcf-3eb9-08d5e08cd2f2 X-MS-Exchange-CrossTenant-originalarrivaltime: 03 Jul 2018 02:29:38.6781 (UTC) X-MS-Exchange-CrossTenant-fromentityheader: Hosted X-MS-Exchange-CrossTenant-id: 72f988bf-86f1-41af-91ab-2d7cd011db47 X-MS-Exchange-Transport-CrossTenantHeadersStamped: DM5PR2101MB0903 Subject: [PATCH edk2-platforms v2 3/3] Readme.md: Add instructions to build in a Windows Environment X-BeenThere: edk2-devel@lists.01.org X-Mailman-Version: 2.1.26 Precedence: list List-Id: EDK II Development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 03 Jul 2018 02:29:41 -0000 Content-Language: en-US Content-Type: text/plain; charset="iso-8859-1" Content-Transfer-Encoding: quoted-printable 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 Cc: Ard Biesheuvel Cc: Leif Lindholm Cc: Michael D Kinney --- 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 =20 # How To Build (Windows Environment) =20 -(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 w= ith GCC. =20 +## Prerequisites +You will need Git for Windows and Visual Studio installed to build EDK2 fr= om source. +If you wish to build the build tools, you will also need Python 2.7 for Wi= ndows +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-compatibl= e +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=3DC:\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 buildi= ng + 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-no= n-osi, + do not add it to your **PACKAGES_PATH**. Otherwise, you will get errors= during build. + + `> set PACKAGES_PATH=3D%WORKSPACE%\edk2;%WORKSPACE%\edk2-platforms;%WOR= KSPACE%\edk2-non-osi` + +### If cross-compiling with GCC +#### GNU Make +These instructions will walk through getting and setting up mingw32-make.e= xe. You are +free to use other GNU make tools if those are more comfortable for you. Ju= st make sure +the GNU make is Windows-compatible and in your PATH. + +1. Download the latest [MinGW setup installer](https://sourceforge.net/pro= jects/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 **ming= w32-make.exe**. + +1. Go to the Installation drop down menu and `Apply Changes`. This will s= tart +the download of the `mingw32-make` package into your installation director= y from earlier. +Once it is done, you should have a **mingw32-make.exe** and a few other .d= lls in `\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 loade= d libraries. + ``` + > mkdir %WORKSPACE%\GNUMake + > pushd %WORKSPACE%\GNUMake + > copy \bin %WORKSPACE%\GNUMake + > popd + ``` + +1. Update PATH to have GNUMake folder so you can run **mingw32-make.exe** = from anywhere. + + `> set PATH=3D%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=3Dmingw32-` + +#### GCC Cross Compiler +1. Download your desired GCC cross-compiler. For ARM32, use +[arm-eabi](https://releases.linaro.org/components/toolchain/binaries/lates= t/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 w= orkspace. + ``` + > mkdir %WORKSPACE%\Toolchains + > pushd %WORKSPACE%\Toolchains + > copy %WORKSPACE%\Toolchains + > popd + ``` + + At this point, you should have the gcc executables in `%WORKSPACE%\Tool= chains\bin`. + +1. Update PATH to have the Toolchains\bin folder so you can run the toolch= ain binaries from anywhere. + + `> set PATH=3D%WORKSPACE%\Toolchains\bin;%PATH%` + +## Manual building +1. Install the latest Microsoft Visual Studio from the [Visual Studio webs= ite](https://visualstudio.microsoft.com/downloads/). + +1. Get the BaseTools. You can either build them from source or fetch preb= uilt binaries. + * To build from source, follow the Windows instructions found [here](ht= tps://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-win3= 2) + and set **EDK_TOOLS_BIN** to point to this location. + ``` + > git clone https://github.com/tianocore/edk2-BaseTools-win32.git + ... + > set EDK_TOOLS_BIN=3D%WORKSPACE%\edk2-BaseTools-win32 + ``` + +1. Set **PATH** to include the location of the BaseTools. For example: + + `> set PATH=3D%WORKSPACE%\edk2-BaseTools-win32;%PATH%` + +1. Set up the build environment (this will modify your environment variabl= es) + + `> %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 t= o 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.githu= b.io/wiki/Asl-Setup) to install +the official ASL compiler. + + Note: certain Windows IoT platforms may require the Microsoft ASL compi= ler. + The Microsoft ASL compiler (asl.exe) can be obtained from the Windows D= river Kit + ([WDK](https://docs.microsoft.com/en-us/windows-hardware/drivers/downlo= ad-the-wdk)). + It can be found in the `\tools\\ACPIVe= rify\` folder. + +1. Update **PATH** to include the location of the ASL compiler + + `> set PATH=3D;%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 ar= e +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 ord= er 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 whi= ch toolchain to use. +We do this by setting the environment variable `{TOOL_CHAIN_TAG}_{TARGET_A= RCH}_PREFIX` + +So if we are using GCC5 cross compiler toolchain, we should set + + > set GCC5_ARM_PREFIX=3Darm-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 thre= ads 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 tha= t: +``` +> set /A NUM_CPUS=3D%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/wik= i/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/SAB= RESD_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` fo= lder 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 re= commended +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 Nam= e}\{TARGET}_{TOOL_CHAIN_TAG}`) +to remove any stale Makefiles and configurations generated during from the= previous build. =20 # Supported Platforms =20 --=20 2.16.2.gvfs.1.33.gf5370f1