From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received-SPF: Pass (sender SPF authorized) identity=mailfrom; client-ip=104.47.34.113; helo=nam01-by2-obe.outbound.protection.outlook.com; envelope-from=christopher.co@microsoft.com; receiver=edk2-devel@lists.01.org Received: from NAM01-BY2-obe.outbound.protection.outlook.com (mail-by2nam01on0113.outbound.protection.outlook.com [104.47.34.113]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-SHA384 (256/256 bits)) (No client certificate requested) by ml01.01.org (Postfix) with ESMTPS id 1FE09202E5469 for ; Thu, 28 Jun 2018 20:42:39 -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=vF8PJYDy0SkhUsrjNGwEzDs1Krg/nE7KJ3cLTCoedNY=; b=jKi/U0cqOynUT55XNjANk37JDWUdDnfGKfOH++YVYqpcszzcf2LuqQkY26PK52V0WMUZO5C8WFWtvjghabbqAWZOMnQNKqBDCRZocxe8KVOQeCSR796/fGMiMKsBjRwDKXDT+qJgxTCgMjhHL4N7zHip1ojeYfaUheRi1iubvbQ= Received: from DM5PR2101MB1128.namprd21.prod.outlook.com (52.132.133.20) by DM5PR2101MB1045.namprd21.prod.outlook.com (52.132.128.14) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.930.2; Fri, 29 Jun 2018 03:42:37 +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.0930.012; Fri, 29 Jun 2018 03:42:37 +0000 From: Chris Co To: "edk2-devel@lists.01.org" CC: Ard Biesheuvel , Leif Lindholm , Michael D Kinney Thread-Topic: [PATCH edk2-platforms v1 1/1] Readme: Add instructions to build in a Windows Environment Thread-Index: AQHUD1s4ZMjr/Ewye0WnKVRO0hplMg== Date: Fri, 29 Jun 2018 03:42:37 +0000 Message-ID: <20180629034227.26568-2-christopher.co@microsoft.com> References: <20180629034227.26568-1-christopher.co@microsoft.com> In-Reply-To: <20180629034227.26568-1-christopher.co@microsoft.com> Accept-Language: en-US X-MS-Has-Attach: X-MS-TNEF-Correlator: x-clientproxiedby: MW2PR16CA0070.namprd16.prod.outlook.com (2603:10b6:907:1::47) To DM5PR2101MB1128.namprd21.prod.outlook.com (2603:10b6:4:a8::20) x-ms-exchange-messagesentrepresentingtype: 1 x-originating-ip: [2001:4898:80e8:0:e82e:53e:4748:2d54] x-ms-publictraffictype: Email x-microsoft-exchange-diagnostics: 1; DM5PR2101MB1045; 7:Qs8TlbaOOjeIPnvoCp8gTHOS6Wy/QGSlGOVsEZfRz1ickHvCIb+YNfUbfBXeKMVFQbaWLr9tWQ54A/qnHo9QaMUg5JQqb3pqDsaVXtnPaus09hgVxhoggshYCxJBkkoTyWW56N7b72baQA/WYzo46DltzGrC6cl4DFOamIqfMRTWPDtTKjmlvpFdfRwTAoanJ2PjMKBYdBq5fWGc9IusStKGZ2dGDrbiwH7ZOR7KRG8hesOg719GnGNTgsjR/Cy2 x-ms-office365-filtering-correlation-id: 2743885d-42f0-41b9-37c1-08d5dd725b30 x-ms-office365-filtering-ht: Tenant x-microsoft-antispam: UriScan:; BCL:0; PCL:0; RULEID:(7020095)(4652037)(8989117)(4534165)(4627221)(201703031133081)(201702281549075)(8990107)(5600026)(711020)(48565401081)(2017052603328)(7193020); SRVR:DM5PR2101MB1045; x-ms-traffictypediagnostic: DM5PR2101MB1045: x-microsoft-antispam-prvs: x-exchange-antispam-report-test: UriScan:(28532068793085)(89211679590171)(166708455590820)(111885846020525)(228905959029699); x-ms-exchange-senderadcheck: 1 x-exchange-antispam-report-cfa-test: BCL:0; PCL:0; RULEID:(8211001083)(6040522)(2401047)(5005006)(8121501046)(3002001)(10201501046)(93006095)(93001095)(3231270)(2018427008)(944501410)(52105095)(6055026)(149027)(150027)(6041310)(20161123564045)(20161123558120)(20161123560045)(201703131423095)(201702281528075)(20161123555045)(201703061421075)(201703061406153)(20161123562045)(6072148)(201708071742011)(7699016); SRVR:DM5PR2101MB1045; BCL:0; PCL:0; RULEID:; SRVR:DM5PR2101MB1045; x-forefront-prvs: 0718908305 x-forefront-antispam-report: SFV:NSPM; SFS:(10019020)(366004)(346002)(396003)(376002)(136003)(39860400002)(199004)(189003)(174874002)(2906002)(6506007)(386003)(5660300001)(6116002)(5250100002)(76176011)(316002)(52116002)(6346003)(102836004)(46003)(10090500001)(2900100001)(1076002)(8936002)(53946003)(2351001)(86612001)(54906003)(97736004)(22452003)(2501003)(476003)(11346002)(186003)(486006)(2616005)(86362001)(446003)(72206003)(14454004)(10290500003)(6436002)(8676002)(81166006)(6512007)(6306002)(5640700003)(81156014)(6916009)(966005)(99286004)(68736007)(106356001)(25786009)(105586002)(256004)(6486002)(14444005)(478600001)(4326008)(305945005)(7736002)(53376002)(53936002)(36756003)(559001)(579004)(460985005)(134885004); DIR:OUT; SFP:1102; SCL:1; SRVR:DM5PR2101MB1045; 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: MBELKKg+JcJ7v3YXwmh1QI6uXaUUiS1spIoCFXWhwlARQ9MPpVEhkkQHcy/M9RVk1jsrujPJuzyiuLSVOqf9ac0v+8GBggFdPdJYATOhNVqG8Ox2DvYb/QmOyUcBYJA8hqB09AL/+kN4pbmJEuG33w81e30KsqmUGX5NZfKNT8xa29RS4vi1La8DDYVK5jRLjoywxjQeARJEyq1cZ3n4vHiMtF74n+YfMSvjQ5KtvQpn4FHa8gNc6pOtAdizI8u9zys6uLVFRZhi2UszjEDAQINfWQGtF4u4zfTpbz4lGIvKgJd2VqTQlaEOqY3dhWgYqNDm/bD70HZNsst8f60MNw9gYBb7QE6pQOaAuPWir0Q= spamdiagnosticoutput: 1:99 spamdiagnosticmetadata: NSPM MIME-Version: 1.0 X-OriginatorOrg: microsoft.com X-MS-Exchange-CrossTenant-Network-Message-Id: 2743885d-42f0-41b9-37c1-08d5dd725b30 X-MS-Exchange-CrossTenant-originalarrivaltime: 29 Jun 2018 03:42:37.3323 (UTC) X-MS-Exchange-CrossTenant-fromentityheader: Hosted X-MS-Exchange-CrossTenant-id: 72f988bf-86f1-41af-91ab-2d7cd011db47 X-MS-Exchange-Transport-CrossTenantHeadersStamped: DM5PR2101MB1045 Subject: [PATCH edk2-platforms v1 1/1] Readme: 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: Fri, 29 Jun 2018 03:42:39 -0000 Content-Language: en-US Content-Type: text/plain; charset="iso-8859-1" Content-Transfer-Encoding: quoted-printable These instructions detail how to setup a Windows build environment and 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 | 614 ++++++++++++-------- 1 file changed, 387 insertions(+), 227 deletions(-) diff --git a/Readme.md b/Readme.md index 3104144634b9..c9f2af9a6948 100644 --- a/Readme.md +++ b/Readme.md @@ -1,227 +1,387 @@ -This branch holds all platforms actively maintained against the -[edk2](https://github.com/tianocore/edk2) master branch. - -For generic information about the edk2-platforms repository, and the proce= ss -under which _stable_ and _devel_ branches can be added for individual plat= forms, -please see -[the introduction on the about branch](https://github.com/tianocore/edk2-p= latforms/blob/about/Readme.md). - -# INDEX -* [Overview](#overview) -* [How To Build (Linux Environment)](#how-to-build-linux-environment) - * [Manual building](#manual-building) - * [Using uefi-tools helper scripts](#using-uefi-tools-helper-scripts) -* [How To Build (Windows Environment)](#how-to-build-windows-environment) -* [Supported Platforms](#supported-platforms) -* [Maintainers](#maintainers) - -# Overview - -Platform description files can be found under `Platform/{Vendor}/{Platform= }`. - -Many platforms require additional image processing beyond the EDK2 build. -Any such steps should be documented (as a Readme.md), and any necessary he= lper -scripts be contained, under said platform directory. - -Any contributions to this branch should be submitted via email to the -edk2-devel mailing list with a subject prefix of `[platforms]`. See -[Laszlo's excellent guide](https://github.com/tianocore/tianocore.github.i= o/wiki/Laszlo's-unkempt-git-guide-for-edk2-contributors-and-maintainers) fo= r details -on how to do this successfully. - -# How to build (Linux Environment) - -## Prerequisites -The build tools themselves depend on Python (2) and libuuid. Most Linux sy= stems -will come with a Python environment installed by default, but you usually = need -to install uuid-dev (or uuid-devel, depending on distribution) manually. - -## If cross compiling -If building EDK2 for a different archtecture than the build machine, you n= eed 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 ---------------------|------------------------- -AARCH64 | aarch64-linux-gnu- -ARM | arm-linux-gnueabihf- -IA32 | i?86-linux-gnu-* _or_ x86_64-linux-gnu- -IPF | ia64-linux-gnu -X64 | x86_64-linux-gnu- - -\* i386, i486, i586 or i686 - -### GCC -Linaro provides GCC toolchains for -[aarch64-linux-gnu](https://releases.linaro.org/components/toolchain/binar= ies/latest/aarch64-linux-gnu/) -and [arm-linux-gnueabihf](https://releases.linaro.org/components/toolchain= /binaries/latest/arm-linux-gnueabihf/) -compiled to run on x86_64/i686 Linux and i686 Windows. Some Linux distribu= tions -provide their own packaged cross-toolchains. - -### clang -Clang does not require separate cross compilers, but it does need a -target-specific binutils. These are included with any prepackaged GCC tool= chain -(see above), or can be installed or built separately. - -## Obtaining source code -1. Create a new folder (directory) on your local development machine - for use as your workspace. This example uses `/work/git/tianocore`, mod= ify as - appropriate for your needs. - ``` - $ export WORKSPACE=3D/work/git/tianocore - $ mkdir -p $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. Set up a **PACKAGES_PATH** to point to the locations of these three - repositories: - - `$ export PACKAGES_PATH=3D$PWD/edk2:$PWD/edk2-platforms:$PWD/edk2-non-o= si` - -## Manual building - -1. Set up the build environment (this will modify your environment variabl= es) - - `$ . edk2/edksetup.sh` - - (This step _depends_ on **WORKSPACE** being set as per above.) -1. Build BaseTools - - `make -C edk2/BaseTools` - - (BaseTools can currently not be built in parallel, so do not specify an= y `-j` - option, either on the command line or in a **MAKEFLAGS** environment - variable.) - -### 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 -`Build/{Platform Name}/{TARGET}_{TOOL_CHAIN_TAG}/FV`. - -### Build a platform -The main build process _can_ run in parallel - so figure out how many thre= ads we -have available. - -``` -$ getconf _NPROCESSORS_ONLN -8 -``` -OK, so we have 8 CPUs - let's tell the build to use a little more than tha= t: -``` -$ NUM_CPUS=3D$((`getconf _NPROCESSORS_ONLN` + 2)) -``` -For the toolchain tag, use GCC5 for gcc version 5 or later, GCC4x for -earlier versions, or CLANG35/CLANG38 as appropriate when building with cla= ng. -``` -$ build -n $NUM_CPUS -a AARCH64 -t GCC5 -p Platform/ARM/JunoPkg/ArmJuno.ds= c -``` -(Note that the description file gets resolved by the build command through -searching in all locations specified in **PACKAGES_PATH**.) - -#### If cross-compiling -When cross-compiling, or building with a different version of the compiler= than -the default `gcc` or `clang`(/binutils), we additionally need to inform th= e -build command which toolchain to use. We do this by setting the environmen= t -variable `{TOOL_CHAIN_TAG}_{TARGET_ARCH}_PREFIX` - in the case above, -**GCC5_AARCH64_PREFIX**. - -So, referring to the cross compiler toolchain table above, we should prepe= nd the `build` command line with `GCC5_AARCH64_PREFIX=3Daarch64-linux-gnu-`= . - -## Using uefi-tools helper scripts -uefi-tools is a completely unofficial set of helper-scripts developed by L= inaro. -They automate figuring out all of the manual options above, and store the = paths -to platform description files in a separate configuration file. Additional= ly, -they simplify bulk-building large numbers of platforms. - -The (best effort) intent is to keep this configuration up to date with all -platforms that exist in the edk2-platforms master branch. - -The equivalent of the manual example above would be -``` -$ git clone https://git.linaro.org/uefi/uefi-tools.git -... -$ ./uefi-tools/edk2-build.sh juno -... ------------------------------------------------------------- - aarch64 Juno (AARCH64) RELEASE pass ------------------------------------------------------------- -pass 1 -fail 0 -``` -The build finishes with a summary of which platforms/targets were built, w= hich -succeeded and which failed (and the total number of either). - -Like the `build` command itself, `edk2-build.sh` it supports specifying mu= ltiple -targets on a single command line, but it also lets you specify multiple -platforms (or `all` for building all known platforms). So in order to buil= d all -platforms described by the configuration file, for both DEBUG and RELEASE -targets: -``` -$ ./uefi-tools/edk2-build.sh -b DEBUG -b RELEASE -``` - -# How To Build (Windows Environment) - -(I genuinely have no idea. Please help!) - - -# Supported Platforms - -These are the platforms currently supported by this tree - grouped by -Processor/SoC vendor, rather than platform vendor. - -If there are any additional build steps beyond the generic ones listed abo= ve, -they will be documented with the platform. - -## AMD -* [Cello](Platform/LeMaker/CelloBoard) -* [Overdrive](Platform/AMD/OverdriveBoard) -* [Overdrive 1000](Platform/SoftIron/Overdrive1000Board) - -## ARM -* [Juno](Platform/ARM/JunoPkg) -* [Versatile Express](Platform/ARM/VExpressPkg) - -## Hisilicon -* [D02](Platform/Hisilicon/D02) -* [D03](Platform/Hisilicon/D03) -* [D05](Platform/Hisilicon/D05) -* [HiKey](Platform/Hisilicon/HiKey) - -## Marvell -* [Armada 70x0](Platform/Marvell/Armada) - -## Socionext -* [SynQuacer](Platform/Socionext/DeveloperBox) - -# Maintainers - -See [Maintainers.txt](Maintainers.txt). +This branch holds all platforms actively maintained against the +[edk2](https://github.com/tianocore/edk2) master branch. + +For generic information about the edk2-platforms repository, and the proce= ss +under which _stable_ and _devel_ branches can be added for individual plat= forms, +please see +[the introduction on the about branch](https://github.com/tianocore/edk2-p= latforms/blob/about/Readme.md). + +# INDEX +* [Overview](#overview) +* [How To Build (Linux Environment)](#how-to-build-linux-environment) + * [Manual building](#manual-building) + * [Using uefi-tools helper scripts](#using-uefi-tools-helper-scripts) +* [How To Build (Windows Environment)](#how-to-build-windows-environment) +* [Supported Platforms](#supported-platforms) +* [Maintainers](#maintainers) + +# Overview + +Platform description files can be found under `Platform/{Vendor}/{Platform= }`. + +Many platforms require additional image processing beyond the EDK2 build. +Any such steps should be documented (as a Readme.md), and any necessary he= lper +scripts be contained, under said platform directory. + +Any contributions to this branch should be submitted via email to the +edk2-devel mailing list with a subject prefix of `[platforms]`. See +[Laszlo's excellent guide](https://github.com/tianocore/tianocore.github.i= o/wiki/Laszlo's-unkempt-git-guide-for-edk2-contributors-and-maintainers) fo= r details +on how to do this successfully. + +# How to build (Linux Environment) + +## Prerequisites +The build tools themselves depend on Python (2) and libuuid. Most Linux sy= stems +will come with a Python environment installed by default, but you usually = need +to install uuid-dev (or uuid-devel, depending on distribution) manually. + +## If cross compiling +If building EDK2 for a different archtecture than the build machine, you n= eed 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 +--------------------|------------------------- +AARCH64 | aarch64-linux-gnu- +ARM | arm-linux-gnueabihf- +IA32 | i?86-linux-gnu-* _or_ x86_64-linux-gnu- +IPF | ia64-linux-gnu +X64 | x86_64-linux-gnu- + +\* i386, i486, i586 or i686 + +### GCC +Linaro provides GCC toolchains for +[aarch64-linux-gnu](https://releases.linaro.org/components/toolchain/binar= ies/latest/aarch64-linux-gnu/) +and [arm-linux-gnueabihf](https://releases.linaro.org/components/toolchain= /binaries/latest/arm-linux-gnueabihf/) +compiled to run on x86_64/i686 Linux and i686 Windows. Some Linux distribu= tions +provide their own packaged cross-toolchains. + +### clang +Clang does not require separate cross compilers, but it does need a +target-specific binutils. These are included with any prepackaged GCC tool= chain +(see above), or can be installed or built separately. + +## Obtaining source code +1. Create a new folder (directory) on your local development machine + for use as your workspace. This example uses `/work/git/tianocore`, mod= ify as + appropriate for your needs. + ``` + $ export WORKSPACE=3D/work/git/tianocore + $ mkdir -p $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. Set up a **PACKAGES_PATH** to point to the locations of these three + repositories: + + `$ export PACKAGES_PATH=3D$PWD/edk2:$PWD/edk2-platforms:$PWD/edk2-non-o= si` + +## Manual building + +1. Set up the build environment (this will modify your environment variabl= es) + + `$ . edk2/edksetup.sh` + + (This step _depends_ on **WORKSPACE** being set as per above.) +1. Build BaseTools + + `make -C edk2/BaseTools` + + (BaseTools can currently not be built in parallel, so do not specify an= y `-j` + option, either on the command line or in a **MAKEFLAGS** environment + variable.) + +### 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 +`Build/{Platform Name}/{TARGET}_{TOOL_CHAIN_TAG}/FV`. + +### Build a platform +The main build process _can_ run in parallel - so figure out how many thre= ads we +have available. + +``` +$ getconf _NPROCESSORS_ONLN +8 +``` +OK, so we have 8 CPUs - let's tell the build to use a little more than tha= t: +``` +$ NUM_CPUS=3D$((`getconf _NPROCESSORS_ONLN` + 2)) +``` +For the toolchain tag, use GCC5 for gcc version 5 or later, GCC4x for +earlier versions, or CLANG35/CLANG38 as appropriate when building with cla= ng. +``` +$ build -n $NUM_CPUS -a AARCH64 -t GCC5 -p Platform/ARM/JunoPkg/ArmJuno.ds= c +``` +(Note that the description file gets resolved by the build command through +searching in all locations specified in **PACKAGES_PATH**.) + +#### If cross-compiling +When cross-compiling, or building with a different version of the compiler= than +the default `gcc` or `clang`(/binutils), we additionally need to inform th= e +build command which toolchain to use. We do this by setting the environmen= t +variable `{TOOL_CHAIN_TAG}_{TARGET_ARCH}_PREFIX` - in the case above, +**GCC5_AARCH64_PREFIX**. + +So, referring to the cross compiler toolchain table above, we should prepe= nd the `build` command line with `GCC5_AARCH64_PREFIX=3Daarch64-linux-gnu-`= . + +## Using uefi-tools helper scripts +uefi-tools is a completely unofficial set of helper-scripts developed by L= inaro. +They automate figuring out all of the manual options above, and store the = paths +to platform description files in a separate configuration file. Additional= ly, +they simplify bulk-building large numbers of platforms. + +The (best effort) intent is to keep this configuration up to date with all +platforms that exist in the edk2-platforms master branch. + +The equivalent of the manual example above would be +``` +$ git clone https://git.linaro.org/uefi/uefi-tools.git +... +$ ./uefi-tools/edk2-build.sh juno +... +------------------------------------------------------------ + aarch64 Juno (AARCH64) RELEASE pass +------------------------------------------------------------ +pass 1 +fail 0 +``` +The build finishes with a summary of which platforms/targets were built, w= hich +succeeded and which failed (and the total number of either). + +Like the `build` command itself, `edk2-build.sh` it supports specifying mu= ltiple +targets on a single command line, but it also lets you specify multiple +platforms (or `all` for building all known platforms). So in order to buil= d all +platforms described by the configuration file, for both DEBUG and RELEASE +targets: +``` +$ ./uefi-tools/edk2-build.sh -b DEBUG -b RELEASE +``` + +# How To Build (Windows Environment) + +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. + +## 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 CxFreeze. + +## 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 GCC envi= ronment +like [MinGW](http://mingw.org/). Specifically you will need the GNU make = tool. + +## 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: + + `> set PACKAGES_PATH=3D%WORKSPACE%/edk2;%WORKSPACE%/edk2-platforms;%WOR= KSPACE%/edk2-non-osi` + +### If cross-compiling with GCC +1. Download [MinGW](http://mingw.org/) and get the **make** executable. C= opy +make.exe and any library dependencies to a folder in your workspace. + ``` + > mkdir %WORKSPACE%\MinGW + > pushd %WORKSPACE%\MinGW + ... copy make.exe and any library dependencies into MinGW folder ... + > popd + ``` +(Note sometimes the MinGW installer prepends **mingw32-** before **make.ex= e**. +You should rename the exe to make before proceeding.) + +1. Download your GCC cross-compiler and place it in your workspace + ``` + > mkdir %WORKSPACE%\Toolchains + > pushd %WORKSPACE%\Toolchains + ... copy GCC cross-compiler into Toolchains folder ... + > popd + ``` + +## Manual building +1. Set up the build environment (this will modify your environment variabl= es) + + `> edk2\edk2setup.bat` + + (This step _depends_ on **WORKSPACE** being set as per above.) + +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](h= ttps://github.com/tianocore/edk2/blob/master/BaseTools/BuildNotes.txt). + * To use prebuilt binaries, clone + [edk2-BaseTools-win32](https://github.com/tianocore/edk2-BaseTools-win= 32) + and set **EDK_TOOLS_DIR** to point to this location. + ``` + > git clone https://github.com/tianocore/edk2-BaseTools-win32.git + ... + > set EDK_TOOLS_DIR=3D%WORKSPACE%/edk2-BaseTools-win32 + ``` + +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). + +### If cross-compiling with GCC +1. Set **PATH** to include the location of your MinGW make executable and = cross-compiling toolchain bin folder. + + `> set PATH=3D%WORKSPACE%\MinGW;%WORKSPACE%\Toolchains\\bin;%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`. + +### 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**.) + +#### If cross-compiling +When cross-compiling, we additionally need to inform the +build command which toolchain to use. We do this by setting the environmen= t +variable `{TOOL_CHAIN_TAG}_{TARGET_ARCH}_PREFIX` - in the case above, +**GCC5_ARM_PREFIX**. + +So, referring to the cross compiler toolchain table above, we should prepe= nd the `build` command line with + + > set GCC5_ARM_PREFIX=3Darm-eabi- + +# Supported Platforms + +These are the platforms currently supported by this tree - grouped by +Processor/SoC vendor, rather than platform vendor. + +If there are any additional build steps beyond the generic ones listed abo= ve, +they will be documented with the platform. + +## AMD +* [Cello](Platform/LeMaker/CelloBoard) +* [Overdrive](Platform/AMD/OverdriveBoard) +* [Overdrive 1000](Platform/SoftIron/Overdrive1000Board) + +## ARM +* [Juno](Platform/ARM/JunoPkg) +* [Versatile Express](Platform/ARM/VExpressPkg) + +## Hisilicon +* [D02](Platform/Hisilicon/D02) +* [D03](Platform/Hisilicon/D03) +* [D05](Platform/Hisilicon/D05) +* [HiKey](Platform/Hisilicon/HiKey) + +## Marvell +* [Armada 70x0](Platform/Marvell/Armada) + +## Socionext +* [SynQuacer](Platform/Socionext/DeveloperBox) + +# Maintainers + +See [Maintainers.txt](Maintainers.txt). --=20 2.16.2.gvfs.1.33.gf5370f1