]>
Commit | Line | Data |
---|---|---|
aa0bf4f4 | 1 | Intel(R) Platform Innovation Framework for EFI\r |
6e4c64c0 | 2 | EFI Development Kit II (EDK II)\r |
362271d6 | 3 | Root Package 1.00\r |
b440dd8b | 4 | 2006-11-08\r |
aa0bf4f4 | 5 | \r |
6e4c64c0 | 6 | Intel is a trademark or registered trademark of Intel Corporation or its\r |
561e4a76 | 7 | subsidiaries in the United States and other countries.\r |
8 | * Other names and brands may be claimed as the property of others.\r | |
6e4c64c0 | 9 | Copyright (c) 2006 - 2007, Intel Corporation\r |
aa0bf4f4 | 10 | \r |
6e4c64c0 | 11 | This document provides updates to documentation, along with a description on\r |
362271d6 | 12 | how to install and build the EDK II.\r |
aa0bf4f4 | 13 | \r |
14 | Package Contents\r | |
15 | ----------------\r | |
3d4bdea9 | 16 | BuildNotes.txt - The build notes for this package.\r |
6e4c64c0 | 17 | OldMdePkg - Industry-standard headers and libraries\r |
18 | Tools - Build -specific tools that are designed to help the\r | |
561e4a76 | 19 | developer create and modify drivers and libraries\r |
20 | EdkModulePkg - Reference drivers\r | |
21 | EdkFatBinPkg - Binary DXE drivers for the Fat 32 file system\r | |
22 | EdkShellBinPkg - Binary Shell applications and commands\r | |
23 | EdkNt32Pkg - NT32 Emulation platform reference\r | |
c9b1cad8 | 24 | EdkUnixPkg - Posix/Unix Emulation platform reference (Currently this\r |
25 | builds only on ia32 Linux, but is meant to be portable.)\r | |
aa0bf4f4 | 26 | \r |
6e4c64c0 | 27 | Note: MDE and MDK that appear in other documentation refer to the OldMdePkg and\r |
28 | Tools packages, respectively. While, these two packages are the minimum\r | |
29 | requirement for developing EDK II Packages we recommend that you download all\r | |
561e4a76 | 30 | of the top-level files listed above.\r |
aa0bf4f4 | 31 | \r |
6e4c64c0 | 32 | The following package is available as a separate project, under a separate\r |
561e4a76 | 33 | license, on the TianoCore.org website: https://fat-driver2.tianocore.org\r |
c6c0039c | 34 | \r |
35 | EdkFatPkg - A package containing source DXE drivers for the Fat 32 file\r | |
36 | system\r | |
37 | \r | |
1910fbaf | 38 | Documents have the following filenames (to download these documents, see "Notes\r |
39 | on Documentation" later in these Release Notes):\r | |
6e4c64c0 | 40 | EDK II Module Development Environment Library Specification, v0.58\r |
561e4a76 | 41 | (MDE_Library_Spec_0_58.rtf)\r |
42 | EDK II Build and Packaging Architecture Specification, v0.53\r | |
43 | (Build_Packaging_Spec_0_53.rtf)\r | |
44 | EDK II Platform Configuration Database Infrastructure Description, v0.54\r | |
45 | (PCD_Infrastructure_0_54.rtf)\r | |
46 | EDK II Module Surface Area Specification, v0.51\r | |
aa0bf4f4 | 47 | (Module_Surface_Area_0_50.rtf)\r |
561e4a76 | 48 | EDK II Module Development Environment Package Specification, v0.51\r |
49 | (MDE_Package_Spec_0_51.rtf)\r | |
50 | EDK II C Coding Standards Specification v0.51\r | |
51 | (C_Coding_Standards_Specification_ 0_51.rtf)\r | |
dcfa7b15 | 52 | EDK II Subversion Setup Guide\r |
53 | (edk2-subversion-setup.rtf)\r | |
aa0bf4f4 | 54 | \r |
55 | Pre-Requisites\r | |
56 | --------------\r | |
57 | The following list of tools must be installed on the development workstation\r | |
561e4a76 | 58 | prior to using the EDK II.\r |
aa0bf4f4 | 59 | \r |
60 | Compiler Tool Chain\r | |
61 | Microsoft* Visual Studio .NET 2003* (http://www.microsoft.com)\r | |
62 | or\r | |
43475442 | 63 | A special GCC version 4.x or later (http://gcc.gnu.org). See below.\r |
aa0bf4f4 | 64 | \r |
65 | Assembler Tool Chain\r | |
66 | Microsoft Macro Assembler, version 6.15 or later\r | |
67 | or\r | |
8fb9e6b8 | 68 | GNU binutils 2.16.1 or later\r |
b440dd8b | 69 | (Http://ftp.gnu.org/gnu/binutils)\r |
aa0bf4f4 | 70 | \r |
71 | Java Development Kit ( Java 5.0 or later)\r | |
ef6e2efe | 72 | Sun* jdk-1.5.0_06 or later (http://java.sun.com)\r |
aa0bf4f4 | 73 | or\r |
74 | Bea Systems* jrockit-25.2.0-jdk1.5.0_03 or later (http://www.bea.com)\r | |
75 | \r | |
76 | Java Tools\r | |
77 | Apache-ANT, version 1.6.5 or later (http://ant.apache.org)\r | |
50518883 | 78 | Ant-contrib, version 1.0b2 or later\r |
782eb168 | 79 | (http://prdownloads.sourceforge.net/ant-contrib/ant-contrib-1.0b2-bin.zip?download)\r |
aa0bf4f4 | 80 | Saxon8, version 8.1.1\r |
81 | (http://prdownloads.sourceforge.net/saxon/saxonb8-1-1.zip?download)\r | |
782eb168 | 82 | XMLBeans, version 2.1.0 (http://xmlbeans.apache.org)\r |
6e4c64c0 | 83 | DO NOT download the latest XMLBeans, version 2.2.0. It is not compatible\r |
561e4a76 | 84 | with Saxon8, version 8.1.1.\r |
aa0bf4f4 | 85 | \r |
86 | Other Tools\r | |
87 | TortoiseSVN version 1.3.3. (http://tortoisesvn.tigris.org/)\r | |
88 | \r | |
89 | Optional Tools\r | |
90 | --------------\r | |
91 | Compiler Tool Chains:\r | |
561e4a76 | 92 | Intel(R) C++ Compiler for Windows*, ver. 9.0 or later (http://www.intel.com)\r |
6e4c64c0 | 93 | Intel(R) C Compiler for EFI Byte Code, ver. 1.2 or later\r |
8fb9e6b8 | 94 | (http://www.intel.com/cd/software/products/asmo-na/eng/compilers/efibc/index.htm)\r |
aa0bf4f4 | 95 | Microsoft Driver Development Kit, version 3790.1830 or later\r |
8fb9e6b8 | 96 | (http://www.microsoft.com/whdc/devtools/ddk/orderddkcd.mspx)\r |
aa0bf4f4 | 97 | Microsoft ACPI Source Language Assembler, Version 1.0.13NT or later\r |
98 | Intel ACPI Component Architecture, version 20060113\r | |
99 | \r | |
ba6930b1 | 100 | Python\r |
101 | \r | |
102 | There are several tools implemented in Python and wxPython Widgets in the\r | |
103 | Tools/Python directory. These are optional tools, and are not necessary in\r | |
104 | order to use or build the edk2 code. In order to use them you must\r | |
105 | install Python 2.4.x and wxWidgets 2.8.x for your platform. The tools\r | |
106 | have been tested and work correctly on OS X, Linux and Windows.\r | |
107 | \r | |
108 | There is a script called Install_Python_OSX.sh that will download and\r | |
109 | install the correct versions for OS X. For other platforms, please find\r | |
110 | the installers for your platform at the following sites:\r | |
111 | \r | |
112 | - http://www.python.org/download/releases/2.4.4/ (Python interpreter)\r | |
113 | - http://www.wxpython.org/download.php#binaries (Python GUI extensions)\r | |
114 | \r | |
115 | Your linux distribution may contain packages of python and wxPython, which\r | |
116 | should work, provided they are are compatible with the above specified\r | |
117 | versions.\r | |
118 | \r | |
561e4a76 | 119 | -----------------------------------------------\r |
120 | Notes on Required Tools (Source Control System)\r | |
121 | -----------------------------------------------\r | |
13421853 | 122 | The EDK II is being managed by the Subversion Source Control on Tianocore.org.\r |
561e4a76 | 123 | Subversion provides speed, security, and additional features. The\r |
6e4c64c0 | 124 | recommended client is TortoiseSVN version 1.3.3.\r |
aa0bf4f4 | 125 | (Available at http://tortoisesvn.tigris.org/)\r |
126 | \r | |
561e4a76 | 127 | The checkout procedures on the Tianocore.org Web site include\r |
128 | instructions for the use of Subversion Source Control.\r | |
aa0bf4f4 | 129 | \r |
13421853 | 130 | The URL of the EDK II repository is:\r |
aa0bf4f4 | 131 | https://edk2.tianocore.org/svn/edk2/trunk/edk2\r |
132 | \r | |
aa0bf4f4 | 133 | \r |
561e4a76 | 134 | --------------------------------------------------------------------\r |
6e4c64c0 | 135 | Notes On Required Tools (With examples for Windows, OS X, and Linux*)\r |
561e4a76 | 136 | --------------------------------------------------------------------\r |
aa0bf4f4 | 137 | Software Installation Order:\r |
6e4c64c0 | 138 | After installing the compiler tools and your Subversion client, install the\r |
139 | following required tools in this order:\r | |
561e4a76 | 140 | 1. Java JDK\r |
141 | 2. Apache-Ant\r | |
142 | 3. ant-contrib\r | |
143 | 4. xmlbeans\r | |
144 | 5. saxon8\r | |
aa0bf4f4 | 145 | \r |
146 | Java Development Kit:\r | |
6e4c64c0 | 147 | \r |
aa0bf4f4 | 148 | The Java Environment Variable must be set before attempting to build.\r |
b440dd8b | 149 | For Sun JDK (see note below?:\r |
6132429e | 150 | set JAVA_HOME=c:\Java\jdk1.5.0_06 (Windows example)\r |
151 | export JAVA_HOME=/Library/Java/Home/ (OS X example)\r | |
152 | export JAVA_HOME=/usr/lib/j2sdk1.5-sun/ (Linux example)\r | |
153 | For Bea Systems:\r | |
782eb168 | 154 | set JAVA_HOME=c:\Java\jrockit-R26.0.0-jdk1.5.0_04\r |
6e4c64c0 | 155 | \r |
1910fbaf | 156 | When using the Sun JDK5.0:\r |
aa0bf4f4 | 157 | During installation, you should specify the install directory as C:\Java\r |
158 | instead of C:\Program Files\(or some other drive letter.) While installing\r | |
6e4c64c0 | 159 | to this non-standard location is not required, in practice, it seems to work\r |
160 | more reliably.\r | |
561e4a76 | 161 | For the JDK, the install path is C:\Java\jdk1.5.0_06\r |
162 | For the JRE, the install path is C:\Java\jre1.5.0_06\r | |
aa0bf4f4 | 163 | Alternatively, you can specify C:\sunjavajdk and C:\sunjavajre.\r |
01d2ed5e | 164 | \r |
6e4c64c0 | 165 | NOTE: You cannot combine the location for the JDK and the JRE, because the\r |
561e4a76 | 166 | JRE install removes most of the binaries and libraries installed by the JDK\r |
aa0bf4f4 | 167 | install.\r |
168 | \r | |
169 | Java Tools:\r | |
170 | The Apache-ANT requires the ANT_HOME environment variable to be set before\r | |
171 | attempting to build:\r | |
561e4a76 | 172 | set ANT_HOME=c:\<full path to where ant was installed>\r |
6132429e | 173 | export ANT_HOME=~/ExternalTools/apache-ant (OS X and Linux example)\r |
aa0bf4f4 | 174 | \r |
6e4c64c0 | 175 | The ant-contrib.jar file should be installed in the %ANT_HOME%\lib\r |
aa0bf4f4 | 176 | directory.\r |
177 | \r | |
561e4a76 | 178 | XMLBeans, requires the XMLBEANS_HOME environment variable to be set\r |
aa0bf4f4 | 179 | before attempting to build:\r |
561e4a76 | 180 | set XMLBEANS_HOME=C:\<full path to where xmlbeans was installed>\r |
6132429e | 181 | export XMLBEANS_HOME=~/ExternalTools/xmlbeans (OS X and Linux example)\r |
aa0bf4f4 | 182 | \r |
561e4a76 | 183 | Copy the saxon8.jar file to the %XMLBEANS_HOME%\lib directory.\r |
aa0bf4f4 | 184 | \r |
561e4a76 | 185 | The Ant and XMLBean tools must be in the path.\r |
aa0bf4f4 | 186 | MS system example:\r |
187 | set PATH=%PATH%;%ANT_HOME%\bin;%XMLBEANS_HOME%\bin\r | |
188 | Linux/OS X bash shell example:\r | |
189 | export PATH=$PATH:${ANT_HOME}/bin:${XMLBEANS_HOME}/bin\r | |
dcfa7b15 | 190 | \r |
191 | --------------------\r | |
192 | A Word on Apache-ANT\r | |
193 | --------------------\r | |
194 | The Apache-ANT program is a build tool that uses XML-based project files.\r | |
195 | Similar to Makefiles, these project files may contain multiple targets. Most\r | |
196 | build.xml files in EDK II are auto-generated; any edits performed on the\r | |
561e4a76 | 197 | build.xml files will be overwritten by the next build.\r |
dcfa7b15 | 198 | \r |
199 | Pre-defined targets in the build.xml file include:\r | |
561e4a76 | 200 | all - This target builds binaries for defined architectures.\r |
201 | clean - This target removes object files generated by commands.\r | |
dcfa7b15 | 202 | cleanall - This target removes all generated files and directories.\r |
203 | \r | |
d0d0be58 | 204 | Use the ANT option, -emacs, to remove the [cc] characters when an error occurs\r |
205 | to provide a method for the Visual Studio IDE to open a file by double\r | |
206 | clicking the mouse on the file. Add -emacs to the end of the build command.\r | |
561e4a76 | 207 | ----------------------------\r |
208 | A Word on the GCC Tool Chain\r | |
209 | ----------------------------\r | |
7fe8ec4e | 210 | \r |
dcfa7b15 | 211 | EDK II will not compile with a standard Linux gcc tool chain. While Linux\r |
7fe8ec4e | 212 | distributions are usually based on ELF, EDK II requires a version of gcc that\r |
213 | is configured to produce PE-COFF images. You will find a script in <Root of\r | |
214 | EDK2 tree>/Tools/gcc/tianoCross-gcc-4.1 that will download, configure, compile,\r | |
215 | and install a gcc 4.1 cross-compile tool chain for EDK II development. This\r | |
216 | custom tool chain supports the IA-32 architecture. It can be built and run on\r | |
217 | Cygwin, Linux, and many other POSIX-compliant host operating environments. To\r | |
218 | compile the custom gcc tool chain, you need the following tools on your host\r | |
219 | computer: bash, gcc, gmake, curl (or wget).\r | |
dcfa7b15 | 220 | \r |
6e4c64c0 | 221 | Only the OldMdePkg, EdkModulePkg and EdkUnixPkg are currently supported by gcc\r |
c9b1cad8 | 222 | builds. Other builds, such as the EdkNt32Pkg, will not compile with gcc. By\r |
223 | default, the edk2 will try to build the NT32.fpd, which is not supported by\r | |
224 | gcc. So, you need to change the Tools/Conf/target.txt.\r | |
af9a0f8f | 225 | \r |
7fe8ec4e | 226 | The cross-compile build script has been tested on Cygwin, OS X and Linux. You\r |
227 | should expect to hack on these scripts to make them work on your system. You\r | |
228 | may need to install additional tools on your system to make the scripts work.\r | |
229 | \r | |
230 | You will need\r | |
231 | \r | |
232 | A recent version (3.0 or later should be fine) of gcc that is able to produce\r | |
233 | executables for the machine that you want to run this compiler on (the host\r | |
234 | machine).\r | |
235 | wget or curl (which enables the download of the gcc compiler source code)\r | |
236 | tar\r | |
237 | bzip\r | |
238 | gzip\r | |
239 | bash\r | |
240 | and possibly others\r | |
241 | \r | |
242 | CYGWIN Notes\r | |
243 | \r | |
244 | You should setup cygwin to use binmode on all mounts. When you initially\r | |
245 | install cygwin it gives you the choice of Unix file mode (recommended) or DOS\r | |
246 | file mode. Unix mode will cause all the cygwin directories to be mounted in\r | |
247 | binmode, while DOS will mount the dirs in textmode. Here is an example of a\r | |
248 | cygwin install where the dirs are (properly) mounted in binmode.\r | |
6e4c64c0 | 249 | To view mount information, type:\r |
1095e1fc | 250 | mount\r |
7fe8ec4e | 251 | \r |
252 | C:\cygwin\bin on /usr/bin type user (binmode)\r | |
253 | C:\cygwin\lib on /usr/lib type user (binmode)\r | |
254 | c:\workspace on /workspace type system (binmode)\r | |
255 | C:\cygwin on / type user (binmode)\r | |
256 | \r | |
257 | If you use textmode, it is likely that the build will fail in a way that is\r | |
1095e1fc | 258 | hard to debug. Textmode is required to retain or add the DOS ^M characters\r |
259 | in DOS batch files during file editing sessions.\r | |
260 | \r | |
6e4c64c0 | 261 | You can switch from textmode to binmode for compilation by executing the\r |
1095e1fc | 262 | following:\r |
263 | mount -b --change-cygdrive-prefix cygdrive\r | |
7fe8ec4e | 264 | \r |
265 | Cygwin is pretty slow, so it is not recommended for large builds.\r | |
266 | \r | |
267 | \r | |
268 | \r | |
269 | \r | |
270 | \r | |
af9a0f8f | 271 | The platform to be built is identified by the Tools/Conf/target.txt file:\r |
272 | \r | |
273 | #\r | |
274 | # PROPERTY Type Use Description\r | |
275 | # ---------------- -------- -------- -----------------------------------------------------------\r | |
6e4c64c0 | 276 | # ACTIVE_PLATFORM Filename Recommended Specify the WORKSPACE relative Path and Filename\r |
af9a0f8f | 277 | # of the platform FPD file that will be used for the build\r |
278 | # This line is required if and only if the current working\r | |
279 | # directory does not contain one or more FPD files.\r | |
280 | \r | |
281 | ACTIVE_PLATFORM =\r | |
6e4c64c0 | 282 | \r |
af9a0f8f | 283 | You can leave it black, as above, or set it to any .fpd file in the workspace.\r |
284 | If you leave it blank, then you just cd to the dir that contains the .fpd that\r | |
6e4c64c0 | 285 | you would like to build (OldMdePkg/ or EdkModulePkg/) and then type build.\r |
6329bec1 | 286 | \r |
287 | ----------------------------\r | |
288 | A Word on compiling on Linux\r | |
289 | ----------------------------\r | |
290 | \r | |
b440dd8b | 291 | In order to compile on Linux, you will need to have the e2fsprogs-devel package\r |
6329bec1 | 292 | installed. Check your distribution for the rpm, deb or other package format.\r |
293 | This package contains the uuid library and header that are used by some of the\r | |
294 | host tools.\r | |
295 | \r | |
296 | If you are running on x86_64 Linux, then you should install a 64 bit version of\r | |
297 | the Java JDK. The version that was used was jdk-1_5_0_07-linux-amd64-rpm.bin.\r | |
298 | It may be downloaded from sun.com.\r | |
dcfa7b15 | 299 | \r |
0a75428c | 300 | -----------------------------------------\r |
301 | A Word on compiling under Cygwin with gcc\r | |
302 | -----------------------------------------\r | |
303 | \r | |
304 | Cygwin is a POSIX style operating environment for Windows. It is possible to\r | |
6e4c64c0 | 305 | compile the EDK 2 using gcc and cygwin. Compiling under cygwin is slow, because\r |
306 | the underlying file accesses are slow in cygwin. For this reason, we do not\r | |
307 | encourage the use of cygwin. A true unix system will be a superior choice for\r | |
6f02e338 | 308 | those wishing to compile with gcc.\r |
0a75428c | 309 | \r |
310 | Make sure that you select the e2fsprogs development package when you install\r | |
311 | cygwin. It is necessary for the GenFvImage tool.\r | |
312 | \r | |
ea5254ee | 313 | ----------------------------------------\r |
314 | A Word on gcc for Processor Architectures\r | |
315 | ----------------------------------------\r | |
316 | \r | |
6e4c64c0 | 317 | Currently gcc support is limited to IA-32 builds, generating IA-32 PE32 images.\r |
ea5254ee | 318 | \r |
6e4c64c0 | 319 | The X64 bit (Intel 64, etc.) support under the gcc compiler does not support the EFIAPI\r |
320 | calling convention (as defined in the UEFI 2.0 specification Chapter 2), so it is not\r | |
321 | possible to build a working EFI image for an X64 environment. Since the x64 gcc does\r | |
322 | not support the EFIAPI calling convention the x64 tools do not support generating a\r | |
323 | PE32+ image. The EFIAPI calling convention is very similar to the Microsoft x64\r | |
6f02e338 | 324 | calling convention.\r |
ea5254ee | 325 | \r |
c9b1cad8 | 326 | We have added prelinary support for the MinGW64 Tool chain. This gcc tool\r |
327 | chain is ported to follow the Microsft X64 ABI, and therefore is compatible\r | |
328 | with the EFI specification.\r | |
329 | \r | |
b440dd8b | 330 | On Itanium?Processors the gcc compiler does not support generating a PE32+ image.\r |
ea5254ee | 331 | \r |
c9b1cad8 | 332 | ----------------------------------------\r |
333 | A Word on EdkUnixPkg -- The Unix simulator\r | |
334 | ----------------------------------------\r | |
335 | \r | |
336 | A unix port of the Nt32 simulator has been added to the project. It currently\r | |
337 | builds and runs on 32 bit Linux, but should be portable to other Unix\r | |
338 | variants. In order to build it, you should use the ELFGCC tool chain defintion\r | |
339 | in tools_def.txt, which is set in target.txt. These are two settings to make\r | |
340 | in Tools/Conf/target.txt:\r | |
341 | \r | |
342 | ACTIVE_PLATFORM = EdkUnixPkg/Unix.fpd\r | |
343 | TOOL_CHAIN_TAG = ELFGCC\r | |
344 | \r | |
345 | Once that is setup, type build, and then you will end up with the simulator in\r | |
6e4c64c0 | 346 | Build/Unix/DEBUG_ELFGCC/IA32/SecMain.exe.\r |
c9b1cad8 | 347 | \r |
348 | In order to use the gdb debugger with the simulator, you may need to load the\r | |
349 | correct symbol file for the various modules that are loaded. For example,\r | |
350 | \r | |
351 | add-symbol-file EdkModulePkg/Bus/Pci/PciBus/Dxe/PciBus/DEBUG/./PciBus.dll\r | |
352 | 0x45dc6000\r | |
353 | \r | |
354 | You can see the names of the symbol files (they are in ELF format even though\r | |
355 | the extension is .dll) printed on the screen as the simulator comes up.\r | |
356 | \r | |
dcfa7b15 | 357 | -----------------------\r |
561e4a76 | 358 | Notes on Documentation\r |
dcfa7b15 | 359 | -----------------------\r |
360 | The documents are being managed by the Subversion Source Control on\r | |
361 | Tianocore.org. The document repository is "docs" and must be checked out\r | |
362 | separately from the EDK II source tree. Refer to the checkout procedures on\r | |
561e4a76 | 363 | the Tianocore.org Web site for EDK II.\r |
dcfa7b15 | 364 | \r |
365 | The URL of the document repository is:\r | |
366 | https://edk2.tianocore.org/svn/edk2/trunk/docs\r | |
367 | \r | |
6e4c64c0 | 368 | \r |
aa0bf4f4 | 369 | -------------------------------------------------------------------------------\r |
561e4a76 | 370 | Quick Start\r |
a032fb4d | 371 | -----------\r |
6e4c64c0 | 372 | (assumes Microsoft Tools and OS environment, for GCC Tools or Linux, see\r |
dcfa7b15 | 373 | "Detailed Starting Instructions" below)\r |
374 | \r | |
375 | Follow the instructions at https://edk2.tianocore.org/servlets/ProjectSource to\r | |
561e4a76 | 376 | check out the entire EDK II source tree.\r |
dcfa7b15 | 377 | \r |
561e4a76 | 378 | In a command window, change to the top-level directory of the EDK II source.\r |
dcfa7b15 | 379 | \r |
561e4a76 | 380 | To test your tool chain setup and to build the supplied tools, execute:\r |
80d1b384 | 381 | c:\MyWork\edk2\> edksetup ForceRebuild\r |
dcfa7b15 | 382 | \r |
6e4c64c0 | 383 | (The edksetup script is referred to as the setup command throughout the\r |
dcfa7b15 | 384 | rest of this document.)\r |
385 | NOTE: You should run the setup command at the start of every session.\r | |
386 | This configures the environment to include the TianoTools and the\r | |
387 | Java applications and libraries.\r | |
388 | \r | |
389 | You will need to set the WORKSPACE environment variable, or run the edksetup\r | |
561e4a76 | 390 | script (without any arguments), any time you want to build.\r |
dcfa7b15 | 391 | \r |
392 | Set the WORKSPACE environment variable, e.g.:\r | |
393 | \r | |
80d1b384 | 394 | c:\> set WORKSPACE=C:\MyWork\edk2\r |
dcfa7b15 | 395 | \r |
561e4a76 | 396 | You may need to edit the text files Tools/Conf/target.txt and\r |
6e4c64c0 | 397 | Tools/Conf/tools_def.txt (created by edksetup) using your favorite\r |
398 | text editor to ensure that the paths to the tools you want to use\r | |
399 | to build EDK II binaries are correct. These files contain the default\r | |
400 | paths (as per the default installation of the tools), so a customized\r | |
dcfa7b15 | 401 | install may require this manual process.\r |
402 | \r | |
561e4a76 | 403 | Once this is completed, you are ready to test the build, by executing:\r |
80d1b384 | 404 | c:\MyWork\edk2\> build\r |
dcfa7b15 | 405 | \r |
6e4c64c0 | 406 | This command builds the active platform specified in text file target.txt. If\r |
407 | the active platform is not specified target.txt, you must execute the build\r | |
408 | command from the sub-directory that contains FPD files. For more information\r | |
689b2d72 | 409 | about the active platform policy, see the "EDK II Build and Packaging\r |
410 | Architecture Specification."\r | |
dcfa7b15 | 411 | \r |
412 | -------------------------------------------------------------------------------\r | |
561e4a76 | 413 | Detailed Starting Instructions\r |
414 | ------------------------------\r | |
dcfa7b15 | 415 | \r |
aa0bf4f4 | 416 | Follow the instructions at https://edk2.tianocore.org/servlets/ProjectSource to\r |
561e4a76 | 417 | check out the entire EDK II source tree.\r |
aa0bf4f4 | 418 | \r |
561e4a76 | 419 | In a command window, change to the top-level directory of the EDK II source.\r |
aa0bf4f4 | 420 | \r |
65a1d8a9 | 421 | If the active compiler tool chain is GCC, you must set the\r |
422 | environment variable, TOOL_CHAIN to "gcc" before running the\r | |
423 | edksetup script. Example: export TOOL_CHAIN=gcc\r | |
aa0bf4f4 | 424 | \r |
561e4a76 | 425 | To test your tool chain setup and to build the supplied tools, execute:\r |
80d1b384 | 426 | c:\MyWork\edk2\> edksetup ForceRebuild\r |
aa0bf4f4 | 427 | \r |
561e4a76 | 428 | On Linux systems, you must source the edksetup.sh file to load the correct\r |
6132429e | 429 | settings into your shell.\r |
430 | \r | |
431 | . edksetup.sh # Note the dot.\r | |
432 | \r | |
a5760d04 | 433 | If you have recently updated your code from subversion, the tools will need to\r |
434 | be rebuilt if there were any code changes made to them. You can request that\r | |
435 | the tools get rebuilt by typing:\r | |
436 | \r | |
437 | . edksetup.sh Rebuild # Unix-like systems\r | |
438 | edksetup.bat Rebuild # Windows\r | |
439 | \r | |
6e4c64c0 | 440 | The edksetup script is referred to as the setup command throughout the\r |
561e4a76 | 441 | rest of this document.\r |
6e4c64c0 | 442 | NOTE: You should run the setup command (edksetup)at the start of every\r |
443 | session. This configures the environment to include the\r | |
b440dd8b | 444 | TianoTools and the Java applications and libraries.\r |
aa0bf4f4 | 445 | \r |
561e4a76 | 446 | Any changes to the tool source code or XML Schema documents require that\r |
447 | you execute the following:\r | |
80d1b384 | 448 | c:\MyWork\edk2\> edksetup ForceRebuild\r |
65a1d8a9 | 449 | \r |
561e4a76 | 450 | You must set the WORKSPACE environment variable, or run the edksetup\r |
451 | script (without any arguments), any time you want to build.\r | |
65a1d8a9 | 452 | \r |
453 | Set the WORKSPACE environment variable, e.g.:\r | |
454 | \r | |
80d1b384 | 455 | c:\> set WORKSPACE=C:\MyWork\edk2\r |
65a1d8a9 | 456 | \r |
561e4a76 | 457 | You may need to edit the text files Tools/Conf/target.txt and\r |
6e4c64c0 | 458 | Tools/Conf/tools_def.txt (created by edksetup) using your favorite\r |
459 | text editor to ensure that the paths to the tools you want to use\r | |
460 | to build EDK II binaries are correct. These files contain the default\r | |
461 | paths (as per the default installation of the tools), so a customized\r | |
dcfa7b15 | 462 | tool installation may require this manual process.\r |
a032fb4d | 463 | \r |
561e4a76 | 464 | Once this is completed, you are ready to test the build, by executing:\r |
80d1b384 | 465 | c:\MyWork\edk2\> build\r |
aa0bf4f4 | 466 | \r |
6e4c64c0 | 467 | This command builds the active platform specified in text file target.txt. If\r |
468 | the active platform is not specified, go to the sub-directory that contains FPD\r | |
469 | files and execute the build command. For more information about the active\r | |
689b2d72 | 470 | platform policy, see the "EDK II Build and Packaging Architecture\r |
471 | Specification."\r | |
90f7b6a8 | 472 | \r |
561e4a76 | 473 | --------------------------\r |
e3f236c8 | 474 | Individual Platform Builds\r |
561e4a76 | 475 | --------------------------\r |
e3f236c8 | 476 | After running the setup command, you can build individual platforms.\r |
561e4a76 | 477 | In the command window:\r |
478 | Set the active platform in target.txt, and execute this command:\r | |
479 | c:\<directory>\> build\r | |
480 | or\r | |
481 | cd to the platform (FPD file) that you want to build and execute this command:\r | |
80d1b384 | 482 | c:\MyWork\edk2\EdkNt32Pkg\> build\r |
e3f236c8 | 483 | \r |
6e4c64c0 | 484 | Note that the active platform specified in target.txt overrides the platform\r |
485 | specified by any FPD file in the current directory. For more information\r | |
689b2d72 | 486 | about active platform policy, see the "EDK II Build and Packaging Architecture\r |
487 | Specification."\r | |
561e4a76 | 488 | \r |
6e4c64c0 | 489 | To run the Nt32 emulation platform under Microsoft Windows, go to\r |
70edbc34 | 490 | <full build path>\DEBUG\MSFT\IA32 and execute SecMain.exe\r |
561e4a76 | 491 | \r |
689b2d72 | 492 | To exit the Nt32 emulation platform, type "reset" at the EFI Shell>\r |
561e4a76 | 493 | command prompt. Alternatively, from the graphical interface, select the Boot\r |
689b2d72 | 494 | Maintenance Manager's "Reset System" command.\r |
aa0bf4f4 | 495 | \r |
020fa45d | 496 | NOTE: When creating a new platform, the Platform Name is restricted\r |
6e4c64c0 | 497 | to a single word containing alphanumeric characters, underscore, dash,\r |
498 | and period. The space character and other special characters are\r | |
020fa45d | 499 | not allowed.\r |
70edbc34 | 500 | \r |
561e4a76 | 501 | -----------------------\r |
502 | Notes on Symbolic Debug\r | |
503 | -----------------------\r | |
504 | To enable EFI Symbolic Debugging, make sure the target output is set to DEBUG\r | |
505 | in the text file Tools/Conf/target.txt and then modify the FPD <BuildOptions>\r | |
506 | <Options><Option BuildTargets="DEBUG" ToolCode="CC"> and append the following\r | |
507 | compiler options to the string:\r | |
508 | "/D EFI_GENERATE_SYM_FILE", "/D EFI_SYMBOLIC_DEBUG"\r | |
aa0bf4f4 | 509 | \r |
561e4a76 | 510 | (If the Option line does not contain "/D EFI_DEBUG", you must add that\r |
511 | option as well.)\r | |
03fed93e | 512 | \r |
aa0bf4f4 | 513 | ------------------------\r |
514 | Individual Module Builds\r | |
515 | ------------------------\r | |
516 | After running the setup command, you can build individual modules.\r | |
561e4a76 | 517 | In the command window, cd to the module that you want to build, and\r |
518 | execute the build command:\r | |
6e4c64c0 | 519 | c:\MyWork\edk2\OldMdePkg\Library\BaseLib\> build\r |
e3f236c8 | 520 | \r |
6e4c64c0 | 521 | You must set the active platform in target.txt for individual module builds.\r |
aa0bf4f4 | 522 | \r |
aa0bf4f4 | 523 | -------------------------------------------------------------------------------\r |
524 | \r | |
525 | General Information:\r | |
6e4c64c0 | 526 | ===============================================================\r |
561e4a76 | 527 | Mechanisms\r |
aa0bf4f4 | 528 | ----------\r |
8fb9e6b8 | 529 | A brief overview:\r |
aa0bf4f4 | 530 | \r |
6e4c64c0 | 531 | A) The Surface Area Package Description (SPD) file contains information about\r |
532 | the modules that the package contains, including the location of all MSA files,\r | |
561e4a76 | 533 | and public library names and headers that might be provided by a module in the\r |
aa0bf4f4 | 534 | package. Packages are defined by SPD files. (Found in the root of the Package\r |
689b2d72 | 535 | subdirectory (i.e. EdkNt32Pkg).) The SPD file is further explained in "EDK II\r |
536 | Build and Packaging Architecture Specification."\r | |
6e4c64c0 | 537 | \r |
538 | B) Module Surface Area Definition (MSA) files. A description of a module's\r | |
aa0bf4f4 | 539 | surface area, with all module specific default flags and features specified.\r |
6e4c64c0 | 540 | For additional details, see the "EDK II Module Surface Area Specification" and\r |
561e4a76 | 541 | the "EDK II Build and Packaging Architecture Specification."\r |
a032fb4d | 542 | \r |
543 | C) Framework Platform Description (FPD) files. A description of a platform's\r | |
544 | surface are, including a list of modules that are needed by the platform. To\r | |
545 | support individual module builds, developers are not required to provide\r | |
6e4c64c0 | 546 | information about specific flash devices, nor flash device layout.\r |
547 | Specific sections in the FPD file control aspects of the build, such\r | |
548 | as the Supported Architectures and Build Targets, as well as the tool flags\r | |
549 | that are used to create the binary files. A valid platform file can specify\r | |
a032fb4d | 550 | zero or more modules, so individual modules can be compiled within the context\r |
551 | of a platform (FPD) definition.\r | |
552 | \r | |
561e4a76 | 553 | D) Platform Configuration Database (PCD). A platform database that contains a\r |
6e4c64c0 | 554 | variety of current platform settings or directives that can be accessed by a\r |
561e4a76 | 555 | driver or application. The PCD is defined by the PCD_Protocol (This is\r |
6e4c64c0 | 556 | further explained in the "EDK II Platform Configuration Database Infrastructure\r |
561e4a76 | 557 | Description."\r |
aa0bf4f4 | 558 | \r |
a032fb4d | 559 | E) Library Class. A library class is a logical grouping of similar functions.\r |
aa0bf4f4 | 560 | When developing components, the module surface area declares the class of\r |
a032fb4d | 561 | libraries that can be used by the component. The MSA and SPD files can specify\r |
6e4c64c0 | 562 | a recommended instance of the library that a platform integrator (PI) may\r |
563 | select, however this is only a recommendation. The PI may choose to select a\r | |
564 | different library instance to be used during compilation and linking. All\r | |
565 | library type modules must include header files in their distribution package,\r | |
566 | as well as their MSA files. Components, on the other hand, need provide only an\r | |
567 | MSA file and either source or binary files when distributing packages. The\r | |
568 | Library Classes are further explained in the "EDK II Build and Packaging\r | |
561e4a76 | 569 | Architecture Specification."\r |
aa0bf4f4 | 570 | \r |
571 | =========================================================================\r | |
572 | The common operations by developers of new modules are:\r | |
561e4a76 | 573 | -----------------------------------------------\r |
574 | 1) Manually creating a new module in a package:\r | |
aa0bf4f4 | 575 | - The module source code must first be created in an appropriate directory\r |
6e4c64c0 | 576 | (under the package the module is to be a part of.)\r |
aa0bf4f4 | 577 | - An MSA file must be created, spelling out all aspects of the module.\r |
578 | - The MSA must be added to the SPD for the package to include the module.\r | |
579 | \r | |
561e4a76 | 580 | -----------------------------------------------------\r |
581 | 2) Adding and Removing modules to and from a package:\r | |
582 | \r | |
583 | - Set up environment as Build\r | |
584 | - Adding a module to a package:\r | |
585 | - Generate the MSA file\r | |
586 | - Add a new <Filename> element under <MsaFiles> into\r | |
587 | <PackageDir>\<PackageName>.spd, using arelative path to the package\r | |
588 | - Add a new <ModuleSA> entry under each <FrameworkModules> into the\r | |
6e4c64c0 | 589 | <PackageDir>\<PackageName>.fpd file if necessary.\r |
aa0bf4f4 | 590 | \r |
561e4a76 | 591 | - Removing a module from a package:\r |
6e4c64c0 | 592 | - Comment out or remove the corresponding <Filename> element under\r |
561e4a76 | 593 | <MsaFiles> from <PackageDir>\<PackageName>.spd\r |
594 | - Comment out or remove the corresponding <ModuleSA> entry under each\r | |
6e4c64c0 | 595 | <FrameworkModules> from <PackageDir>\<PackageName>.fpd if necessary.\r |
aa0bf4f4 | 596 | \r |
561e4a76 | 597 | -------------------------------\r |
598 | 3) Manually creating a package:\r | |
aa0bf4f4 | 599 | - Identify the modules that are to be members of the project.\r |
600 | - Identify the Variables and Guids required in and of the Package (including\r | |
561e4a76 | 601 | consumption and production information).\r |
aa0bf4f4 | 602 | - Create an SPD file defining these modules and calling out their MSA files.\r |
6e4c64c0 | 603 | - Add a new <Filename> element under <PackageList> into\r |
604 | Tools\Conf\FrameworkDatabase.db, using the relative path to the workspace.\r | |
aa0bf4f4 | 605 | \r |
561e4a76 | 606 | -----------------------------------------\r |
6e4c64c0 | 607 | 4) Declaring a new Protocol in a package:\r |
aa0bf4f4 | 608 | - This release requires manual editing of the SPD file, adding the protocol\r |
6e4c64c0 | 609 | to the ProtocolDeclarations section of the file.\r |
aa0bf4f4 | 610 | - Add the Protocol .h file to the Include\Protocol directory.\r |
6e4c64c0 | 611 | - Add an <Entry> to the <ProtocolDeclarations> element in the\r |
64fcaead | 612 | <PackageName>.spd file\r |
6e4c64c0 | 613 | - Each line contains Protocol base name, followed by the global variable\r |
561e4a76 | 614 | name, and the hex value of the Protocol GUID.\r |
aa0bf4f4 | 615 | \r |
6e4c64c0 | 616 | Example Protocol Entries (NOTE: The Guid entry is a single line in the SPD\r |
561e4a76 | 617 | file):\r |
64fcaead | 618 | <ProtocolDeclarations>\r |
e3f236c8 | 619 | <Entry Name="Bds">\r |
620 | <C_Name>gEfiBdsArchProtocolGuid</C_Name>\r | |
621 | <GuidValue>665E3FF6-46CC-11D4-9A38-0090273FC14D</GuidValue>\r | |
622 | <HelpText/>\r | |
623 | </Entry>\r | |
624 | <Entry Name="Cpu">\r | |
625 | <C_Name>gEfiCpuArchProtocolGuid</C_Name>\r | |
626 | <GuidValue>26BACCB1-6F42-11D4-BCE7-0080C73C8881</GuidValue>\r | |
627 | <HelpText/>\r | |
628 | </Entry>\r | |
629 | </ProtocolDeclarations>\r | |
aa0bf4f4 | 630 | \r |
561e4a76 | 631 | ------------------------------------\r |
632 | 5) Declaring a new PPI in a package:\r | |
633 | - This release requires manual editing of the SPD file\r | |
aa0bf4f4 | 634 | - Add the PPI .h file to the Include\Ppi directory.\r |
6e4c64c0 | 635 | - Add an <Entry> to the package <PpiDeclarations> element in the\r |
64fcaead | 636 | <PackageName>.spd file\r |
6e4c64c0 | 637 | - Each line contains the PPI base name, followed by the global variable\r |
561e4a76 | 638 | name and the hex value of the PPI GUID.\r |
aa0bf4f4 | 639 | \r |
64fcaead | 640 | Example Ppi Entries (NOTE: The Guid entry is a single line in the SPD file):\r |
641 | <PpiDeclarations>\r | |
e3f236c8 | 642 | <Entry Name="BootInRecoveryMode">\r |
643 | <C_Name>gEfiPeiBootInRecoveryModePpiGuid</C_Name>\r | |
644 | <GuidValue>17EE496A-D8E4-4B9A-94D1-CE8272300850</GuidValue>\r | |
645 | <HelpText/>\r | |
64fcaead | 646 | </Entry>\r |
e3f236c8 | 647 | <Entry Name="CpuIo">\r |
648 | <C_Name>gEfiPeiCpuIoPpiInServiceTableGuid</C_Name>\r | |
649 | <GuidValue>E6AF1F7B-FC3F-46DA-A828-A3B457A44282</GuidValue>\r | |
650 | <HelpText/>\r | |
64fcaead | 651 | </Entry>\r |
652 | </PpiDeclarations>\r | |
653 | \r | |
561e4a76 | 654 | -------------------------------------\r |
655 | 6) Declaring a new GUID in a package:\r | |
aa0bf4f4 | 656 | - This release requires manual editing of the SPD file to include the new\r |
64fcaead | 657 | Guid. This is identical to adding a ProtocolDeclaration or PpiDeclaration\r |
561e4a76 | 658 | element, as described above.\r |
aa0bf4f4 | 659 | \r |
561e4a76 | 660 | ------------------------------------------\r |
661 | 7) Declaring a new PCD entry in a package:\r | |
aa0bf4f4 | 662 | - This release requires manual editing of the SPD file to include the new\r |
64fcaead | 663 | PCD. New Pcd entries are added to the PcdDefinitions section of the\r |
561e4a76 | 664 | <PackageName>.spd file using the following example for the format\r |
665 | (NOTE: The hex <Token> value must be unique):\r | |
64fcaead | 666 | \r |
54c9f9ed | 667 | <PcdDeclarations>\r |
64fcaead | 668 | <PcdEntry ItemType="FIXED_AT_BUILD">\r |
669 | <C_Name>PcdMaximumUnicodeStringLength</C_Name>\r | |
670 | <Token>0x00000001</Token>\r | |
54c9f9ed | 671 | <TokenSpaceGuidCName>gEfiMdePkgTokenSpaceGuid</TokenSpaceGuidCName>\r |
64fcaead | 672 | <DatumType>UINT32</DatumType>\r |
54c9f9ed | 673 | <ValidUsage>FIXED_AT_BUILD</ValidUsage>\r |
64fcaead | 674 | <DefaultValue>1000000</DefaultValue>\r |
54c9f9ed | 675 | <HelpText>The maximum lengh for unicode string.</HelpText>\r |
64fcaead | 676 | </PcdEntry>\r |
54c9f9ed | 677 | </PcdDeclarations>\r |
6e4c64c0 | 678 | \r |
aa0bf4f4 | 679 | ------------------------------\r |
561e4a76 | 680 | 8) Declaring a new Library Class:\r |
aa0bf4f4 | 681 | - This release requires manual editing of the SPD file to include the new\r |
6e4c64c0 | 682 | Library Class. New Library Class entries are added to the\r |
561e4a76 | 683 | LibraryClassDeclarations section of the <PackageName>.spd file using\r |
64fcaead | 684 | the following example for the format:\r |
685 | \r | |
686 | <LibraryClassDeclarations>\r | |
e3f236c8 | 687 | <LibraryClass Name="BaseLib">\r |
64fcaead | 688 | <IncludeHeader>Include/Library/BaseLib.h</IncludeHeader>\r |
e3f236c8 | 689 | <HelpText/>\r |
690 | </LibraryClass>\r | |
691 | <LibraryClass Name="BaseMemoryLib">\r | |
692 | <IncludeHeader>Include/Library/BaseMemoryLib.h</IncludeHeader>\r | |
693 | <HelpText/>\r | |
694 | </LibraryClass>\r | |
64fcaead | 695 | </LibraryClassDeclarations>\r |
aa0bf4f4 | 696 | \r |
aa0bf4f4 | 697 | =======================================================\r |
561e4a76 | 698 | EDK II Changes Relative to the original EDK:\r |
699 | --------------------------------------------\r | |
13421853 | 700 | The EDK II represents significant changes in the structure of the EDK.\r |
561e4a76 | 701 | Therefore, it is very difficult to isolate all of the changes of this version of\r |
702 | the EDK with the original EDK.\r | |
aa0bf4f4 | 703 | \r |
704 | Of particular note:\r | |
705 | \r | |
13421853 | 706 | 1) EDK II contains new hardware feature support for the ICH SMBUS Libraries.\r |
aa0bf4f4 | 707 | These libraries are provided to make Memory Reference Code (MRC) development\r |
708 | easier.\r | |
561e4a76 | 709 | 2) The MDE libraries represent significant changes in source\r |
aa0bf4f4 | 710 | (with only limited changes in functionality.) These new libraries conform\r |
b440dd8b | 711 | to the "EDK II Module Development Environment Library Specification.?\r |
aa0bf4f4 | 712 | 3) The Fat Binary and the EDK Shell Binary Packages are functionally identical\r |
561e4a76 | 713 | to the original EDK.\r |
aa0bf4f4 | 714 | 4) The EDK tools directory has been expanded to include more tools and more\r |
715 | tool functionality.\r | |
716 | 5) The EDK NT32 section has been ported to the new build process, but\r | |
561e4a76 | 717 | functionally remains the same as the original EDK.\r |
13421853 | 718 | 6) The Application "HelloWorld" has been ported to EDK II as well.\r |
aa0bf4f4 | 719 | \r |
720 | =======================================================\r | |
b440dd8b | 721 | Virus scanned by McAfee VirusScan Enterprise 8.0.0, Virus Definitions 4890, no\r |
aa0bf4f4 | 722 | virus detected.\r |
ba6930b1 | 723 | \r |
c9b1cad8 | 724 | vim:tw=78:ts=2:com=fb\:- :ai\r |