From: hche10x Date: Wed, 8 Nov 2006 06:12:54 +0000 (+0000) Subject: 1. Rename ReleaseNotes.txt to BuildNotes.txt. X-Git-Tag: edk2-stable201903~23962 X-Git-Url: https://git.proxmox.com/?p=mirror_edk2.git;a=commitdiff_plain;h=b440dd8b952b98831aa85b672b8bf5ec21cdac62;hp=e4764daec7e4132ca033d5d6d35ab403e344307c 1. Rename ReleaseNotes.txt to BuildNotes.txt. 2. Update BuildNotes.txt for some typo issue. git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@1915 6f19259b-4bc3-4df7-8a09-765794883524 --- diff --git a/BuildNotes.txt b/BuildNotes.txt new file mode 100644 index 0000000000..00c2e4238e --- /dev/null +++ b/BuildNotes.txt @@ -0,0 +1,669 @@ +Intel(R) Platform Innovation Framework for EFI +EFI Development Kit II (EDK II) +Root Package 1.00 +2006-11-08 + +Intel is a trademark or registered trademark of Intel Corporation or its +subsidiaries in the United States and other countries. +* Other names and brands may be claimed as the property of others. +Copyright (c) 2006, Intel Corporation + +This document provides updates to documentation, along with a description on +how to install and build the EDK II. + +Package Contents +---------------- + ReleaseNote.txt- These release notes for the package. + MdePkg - Industry-standard headers and libraries + Tools - Build -specific tools that are designed to help the + developer create and modify drivers and libraries + EdkModulePkg - Reference drivers + EdkFatBinPkg - Binary DXE drivers for the Fat 32 file system + EdkShellBinPkg - Binary Shell applications and commands + EdkNt32Pkg - NT32 Emulation platform reference + +Note: MDE and MDK that appear in other documentation refer to the MdePkg and +Tools packages, respectively. While, these two packages are the minimum +requirement for developing EDK II Packages we recommend that you download all +of the top-level files listed above. + +The following package is available as a separate project, under a separate +license, on the TianoCore.org website: https://fat-driver2.tianocore.org + + EdkFatPkg - A package containing source DXE drivers for the Fat 32 file + system + +Documents have the following filenames (to download these documents, see “Notes +on Documentation?later in these Release Notes): + EDK II Module Development Environment Library Specification, v0.58 + (MDE_Library_Spec_0_58.rtf) + EDK II Build and Packaging Architecture Specification, v0.53 + (Build_Packaging_Spec_0_53.rtf) + EDK II Platform Configuration Database Infrastructure Description, v0.54 + (PCD_Infrastructure_0_54.rtf) + EDK II Module Surface Area Specification, v0.51 + (Module_Surface_Area_0_50.rtf) + EDK II Module Development Environment Package Specification, v0.51 + (MDE_Package_Spec_0_51.rtf) + EDK II C Coding Standards Specification v0.51 + (C_Coding_Standards_Specification_ 0_51.rtf) + EDK II Subversion Setup Guide + (edk2-subversion-setup.rtf) + +Pre-Requisites +-------------- +The following list of tools must be installed on the development workstation +prior to using the EDK II. + +Compiler Tool Chain + Microsoft* Visual Studio .NET 2003* (http://www.microsoft.com) + or + A special GCC version 4.x or later (http://gcc.gnu.org). See below. + +Assembler Tool Chain + Microsoft Macro Assembler, version 6.15 or later + or + GNU binutils 2.16.1 or later + (Http://ftp.gnu.org/gnu/binutils) + +Java Development Kit ( Java 5.0 or later) + Sun* jdk-1.5.0_06 or later (http://java.sun.com) + or + Bea Systems* jrockit-25.2.0-jdk1.5.0_03 or later (http://www.bea.com) + +Java Tools + Apache-ANT, version 1.6.5 or later (http://ant.apache.org) + Ant-contrib, version 1.0b2 or later + (http://prdownloads.sourceforge.net/ant-contrib/ant-contrib-1.0b2-bin.zip?download) + Saxon8, version 8.1.1 + (http://prdownloads.sourceforge.net/saxon/saxonb8-1-1.zip?download) + XMLBeans, version 2.1.0 (http://xmlbeans.apache.org) + DO NOT download the latest XMLBeans, version 2.2.0. It is not compatible + with Saxon8, version 8.1.1. + +Other Tools + TortoiseSVN version 1.3.3. (http://tortoisesvn.tigris.org/) + +Optional Tools +-------------- +Compiler Tool Chains: + Intel(R) C++ Compiler for Windows*, ver. 9.0 or later (http://www.intel.com) + Intel(R) C Compiler for EFI Byte Code, ver. 1.2 or later + (http://www.intel.com/cd/software/products/asmo-na/eng/compilers/efibc/index.htm) + Microsoft Driver Development Kit, version 3790.1830 or later + (http://www.microsoft.com/whdc/devtools/ddk/orderddkcd.mspx) + Microsoft ACPI Source Language Assembler, Version 1.0.13NT or later + Intel ACPI Component Architecture, version 20060113 + +----------------------------------------------- +Notes on Required Tools (Source Control System) +----------------------------------------------- +The EDK II is being managed by the Subversion Source Control on Tianocore.org. +Subversion provides speed, security, and additional features. The +recommended client is TortoiseSVN version 1.3.3. + (Available at http://tortoisesvn.tigris.org/) + +The checkout procedures on the Tianocore.org Web site include +instructions for the use of Subversion Source Control. + +The URL of the EDK II repository is: + https://edk2.tianocore.org/svn/edk2/trunk/edk2 + + +-------------------------------------------------------------------- +Notes On Required Tools (With examples for Windows, OS X, and Linux*) +-------------------------------------------------------------------- +Software Installation Order: + After installing the compiler tools and your Subversion client, install the + following required tools in this order: + 1. Java JDK + 2. Apache-Ant + 3. ant-contrib + 4. xmlbeans + 5. saxon8 + +Java Development Kit: + + The Java Environment Variable must be set before attempting to build. + For Sun JDK (see note below?: + set JAVA_HOME=c:\Java\jdk1.5.0_06 (Windows example) + export JAVA_HOME=/Library/Java/Home/ (OS X example) + export JAVA_HOME=/usr/lib/j2sdk1.5-sun/ (Linux example) + For Bea Systems: + set JAVA_HOME=c:\Java\jrockit-R26.0.0-jdk1.5.0_04 + + ?When using the Sun JDK5.0: + During installation, you should specify the install directory as C:\Java + instead of C:\Program Files\(or some other drive letter.) While installing + to this non-standard location is not required, in practice, it seems to work + more reliably. + For the JDK, the install path is C:\Java\jdk1.5.0_06 + For the JRE, the install path is C:\Java\jre1.5.0_06 + Alternatively, you can specify C:\sunjavajdk and C:\sunjavajre. + + NOTE: You cannot combine the location for the JDK and the JRE, because the + JRE install removes most of the binaries and libraries installed by the JDK + install. + +Java Tools: + The Apache-ANT requires the ANT_HOME environment variable to be set before + attempting to build: + set ANT_HOME=c:\ + export ANT_HOME=~/ExternalTools/apache-ant (OS X and Linux example) + + The ant-contrib.jar file should be installed in the %ANT_HOME%\lib + directory. + + XMLBeans, requires the XMLBEANS_HOME environment variable to be set + before attempting to build: + set XMLBEANS_HOME=C:\ + export XMLBEANS_HOME=~/ExternalTools/xmlbeans (OS X and Linux example) + + Copy the saxon8.jar file to the %XMLBEANS_HOME%\lib directory. + + The Ant and XMLBean tools must be in the path. + MS system example: + set PATH=%PATH%;%ANT_HOME%\bin;%XMLBEANS_HOME%\bin + Linux/OS X bash shell example: + export PATH=$PATH:${ANT_HOME}/bin:${XMLBEANS_HOME}/bin + +-------------------- +A Word on Apache-ANT +-------------------- +The Apache-ANT program is a build tool that uses XML-based project files. +Similar to Makefiles, these project files may contain multiple targets. Most +build.xml files in EDK II are auto-generated; any edits performed on the +build.xml files will be overwritten by the next build. + +Pre-defined targets in the build.xml file include: + all - This target builds binaries for defined architectures. + clean - This target removes object files generated by commands. + cleanall - This target removes all generated files and directories. + +---------------------------- +A Word on the GCC Tool Chain +---------------------------- + +EDK II will not compile with a standard Linux gcc tool chain. While Linux +distributions are usually based on ELF, EDK II requires a version of gcc that +is configured to produce PE-COFF images. You will find a script in /Tools/gcc/tianoCross-gcc-4.1 that will download, configure, compile, +and install a gcc 4.1 cross-compile tool chain for EDK II development. This +custom tool chain supports the IA-32 architecture. It can be built and run on +Cygwin, Linux, and many other POSIX-compliant host operating environments. To +compile the custom gcc tool chain, you need the following tools on your host +computer: bash, gcc, gmake, curl (or wget). + +Only the MdePkg and EdkModulePkg are currently supported by gcc builds. Other +builds, such as the EdkNt32Pkg, will not compile with gcc. By default, the edk2 +will try to build the NT32.fpd, which is not supported by gcc. So, you need to +change the Tools/Conf/target.txt. + +The cross-compile build script has been tested on Cygwin, OS X and Linux. You +should expect to hack on these scripts to make them work on your system. You +may need to install additional tools on your system to make the scripts work. + +You will need + + A recent version (3.0 or later should be fine) of gcc that is able to produce + executables for the machine that you want to run this compiler on (the host + machine). + wget or curl (which enables the download of the gcc compiler source code) + tar + bzip + gzip + bash + and possibly others + +CYGWIN Notes + +You should setup cygwin to use binmode on all mounts. When you initially +install cygwin it gives you the choice of Unix file mode (recommended) or DOS +file mode. Unix mode will cause all the cygwin directories to be mounted in +binmode, while DOS will mount the dirs in textmode. Here is an example of a +cygwin install where the dirs are (properly) mounted in binmode. +To view mount information, type: + mount + +C:\cygwin\bin on /usr/bin type user (binmode) +C:\cygwin\lib on /usr/lib type user (binmode) +c:\workspace on /workspace type system (binmode) +C:\cygwin on / type user (binmode) + +If you use textmode, it is likely that the build will fail in a way that is +hard to debug. Textmode is required to retain or add the DOS ^M characters +in DOS batch files during file editing sessions. + +You can switch from textmode to binmode for compilation by executing the +following: + mount -b --change-cygdrive-prefix cygdrive + +Cygwin is pretty slow, so it is not recommended for large builds. + + + + + +The platform to be built is identified by the Tools/Conf/target.txt file: + +# +# PROPERTY Type Use Description +# ---------------- -------- -------- ----------------------------------------------------------- +# ACTIVE_PLATFORM Filename Recommended Specify the WORKSPACE relative Path and Filename +# of the platform FPD file that will be used for the build +# This line is required if and only if the current working +# directory does not contain one or more FPD files. + +ACTIVE_PLATFORM = + +You can leave it black, as above, or set it to any .fpd file in the workspace. +If you leave it blank, then you just cd to the dir that contains the .fpd that +you would like to build (MdePkg/ or EdkModulePkg/) and then type build. + +---------------------------- +A Word on compiling on Linux +---------------------------- + +In order to compile on Linux, you will need to have the e2fsprogs-devel package +installed. Check your distribution for the rpm, deb or other package format. +This package contains the uuid library and header that are used by some of the +host tools. + +If you are running on x86_64 Linux, then you should install a 64 bit version of +the Java JDK. The version that was used was jdk-1_5_0_07-linux-amd64-rpm.bin. +It may be downloaded from sun.com. + +----------------------------------------- +A Word on compiling under Cygwin with gcc +----------------------------------------- + +Cygwin is a POSIX style operating environment for Windows. It is possible to +compile the EDK 2 using gcc and cygwin. Compiling under cygwin is slow, because +the underlying file accesses are slow in cygwin. For this reason, we do not +encourage the use of cygwin. A true unix system will be a superior choice for +those wishing to compile with gcc. + +Make sure that you select the e2fsprogs development package when you install +cygwin. It is necessary for the GenFvImage tool. + +---------------------------------------- +A Word on gcc for Processor Architectures +---------------------------------------- + +Currently gcc support is limited to IA-32 builds, generating IA-32 PE32 images. + +The X64 bit (Intel 64, etc.) support under the gcc compiler does not support the EFIAPI +calling convention (as defined in the UEFI 2.0 specification Chapter 2), so it is not +possible to build a working EFI image for an X64 environment. Since the x64 gcc does +not support the EFIAPI calling convention the x64 tools do not support generating a +PE32+ image. The EFIAPI calling convention is very similar to the Microsoft x64 +calling convention. + +On Itanium?Processors the gcc compiler does not support generating a PE32+ image. + +----------------------- +Notes on Documentation +----------------------- +The documents are being managed by the Subversion Source Control on +Tianocore.org. The document repository is "docs" and must be checked out +separately from the EDK II source tree. Refer to the checkout procedures on +the Tianocore.org Web site for EDK II. + +The URL of the document repository is: + https://edk2.tianocore.org/svn/edk2/trunk/docs + + +------------------------------------------------------------------------------- +Quick Start +----------- +(assumes Microsoft Tools and OS environment, for GCC Tools or Linux, see +"Detailed Starting Instructions" below) + +Follow the instructions at https://edk2.tianocore.org/servlets/ProjectSource to +check out the entire EDK II source tree. + +In a command window, change to the top-level directory of the EDK II source. + +To test your tool chain setup and to build the supplied tools, execute: + c:\MyWork\edk2\> edksetup ForceRebuild + +(The edksetup script is referred to as the setup command throughout the +rest of this document.) + NOTE: You should run the setup command at the start of every session. + This configures the environment to include the TianoTools and the + Java applications and libraries. + +You will need to set the WORKSPACE environment variable, or run the edksetup +script (without any arguments), any time you want to build. + + Set the WORKSPACE environment variable, e.g.: + + c:\> set WORKSPACE=C:\MyWork\edk2 + +You may need to edit the text files Tools/Conf/target.txt and +Tools/Conf/tools_def.txt (created by edksetup) using your favorite +text editor to ensure that the paths to the tools you want to use +to build EDK II binaries are correct. These files contain the default +paths (as per the default installation of the tools), so a customized +install may require this manual process. + +Once this is completed, you are ready to test the build, by executing: + c:\MyWork\edk2\> build + +This command builds the active platform specified in text file target.txt. If +the active platform is not specified target.txt, you must execute the build +command from the sub-directory that contains FPD files. For more information +about the active platform policy, see the “EDK II Build and Packaging +Architecture Specification.? + +------------------------------------------------------------------------------- +Detailed Starting Instructions +------------------------------ + +Follow the instructions at https://edk2.tianocore.org/servlets/ProjectSource to +check out the entire EDK II source tree. + +In a command window, change to the top-level directory of the EDK II source. + +If the active compiler tool chain is GCC, you must set the +environment variable, TOOL_CHAIN to "gcc" before running the +edksetup script. Example: export TOOL_CHAIN=gcc + +To test your tool chain setup and to build the supplied tools, execute: + c:\MyWork\edk2\> edksetup ForceRebuild + +On Linux systems, you must source the edksetup.sh file to load the correct +settings into your shell. + + . edksetup.sh # Note the dot. + +If you have recently updated your code from subversion, the tools will need to +be rebuilt if there were any code changes made to them. You can request that +the tools get rebuilt by typing: + + . edksetup.sh Rebuild # Unix-like systems + edksetup.bat Rebuild # Windows + +The edksetup script is referred to as the setup command throughout the +rest of this document. + NOTE: You should run the setup command (edksetup)at the start of every + session. This configures the environment to include the + TianoTools and the Java applications and libraries. + +Any changes to the tool source code or XML Schema documents require that +you execute the following: + c:\MyWork\edk2\> edksetup ForceRebuild + +You must set the WORKSPACE environment variable, or run the edksetup +script (without any arguments), any time you want to build. + + Set the WORKSPACE environment variable, e.g.: + + c:\> set WORKSPACE=C:\MyWork\edk2 + +You may need to edit the text files Tools/Conf/target.txt and +Tools/Conf/tools_def.txt (created by edksetup) using your favorite +text editor to ensure that the paths to the tools you want to use +to build EDK II binaries are correct. These files contain the default +paths (as per the default installation of the tools), so a customized +tool installation may require this manual process. + +Once this is completed, you are ready to test the build, by executing: + c:\MyWork\edk2\> build + +This command builds the active platform specified in text file target.txt. If +the active platform is not specified, go to the sub-directory that contains FPD +files and execute the build command. For more information about the active +platform policy, see the “EDK II Build and Packaging Architecture +Specification.? + +-------------------------- +Individual Platform Builds +-------------------------- +After running the setup command, you can build individual platforms. +In the command window: + Set the active platform in target.txt, and execute this command: + c:\\> build +or + cd to the platform (FPD file) that you want to build and execute this command: + c:\MyWork\edk2\EdkNt32Pkg\> build + + Note that the active platform specified in target.txt overrides the platform + specified by any FPD file in the current directory. For more information + about active platform policy, see the “EDK II Build and Packaging Architecture + Specification.? + +To run the Nt32 emulation platform under Microsoft Windows, go to +\DEBUG\MSFT\IA32 and execute SecMain.exe + +To exit the Nt32 emulation platform, type “reset?at the EFI Shell> +command prompt. Alternatively, from the graphical interface, select the Boot +Maintenance Manager's “Reset System?command. + + NOTE: When creating a new platform, the Platform Name is restricted + to a single word containing alphanumeric characters, underscore, dash, + and period. The space character and other special characters are + not allowed. + +----------------------- +Notes on Symbolic Debug +----------------------- +To enable EFI Symbolic Debugging, make sure the target output is set to DEBUG +in the text file Tools/Conf/target.txt and then modify the FPD +