X-Git-Url: https://git.proxmox.com/?a=blobdiff_plain;f=BaseTools%2FReadMe.txt;h=a37501e8daf37a2bdcc9a548b30b52e5b145ead0;hb=19bf20e11acd88a02922201f97e6d64edcd16390;hp=81c52ef773a18d3438f732f29723be2bfb7f6bfb;hpb=53ca26a2d8fecb7ef41f8513ac09b65c51402980;p=mirror_edk2.git diff --git a/BaseTools/ReadMe.txt b/BaseTools/ReadMe.txt index 81c52ef773..a37501e8da 100644 --- a/BaseTools/ReadMe.txt +++ b/BaseTools/ReadMe.txt @@ -1,14 +1,193 @@ This directory contains the next generation of EDK II build tools and template files. Templates are located in the Conf directory, while the tools executables for -Microsoft Windows 32-bit Operating Systems are located in the Bin\Win32 directory. +Microsoft Windows 32-bit Operating Systems are located in the Bin\Win32 directory, other +directory contatins tools source. -The binary tools will be updated only after passing developer testing. +1. Build step to generate the binary tools. -The BaseTools package will be updated with new tools only after all testing on a set -of binary tools has successfully completed. +=== Windows/Visual Studio Notes === + +To build the BaseTools, you should run the standard vsvars32.bat script. + +In addition to this, you should set the following environment variables: + + * EDK_TOOLS_PATH - Path to the BaseTools sub directory under the edk2 tree + * BASE_TOOLS_PATH - The directory where the BaseTools source is located. + (It is the same directory where this README.txt is located.) + * PYTHON_FREEZER_PATH - Path to where the python freezer tool is installed + +After this, you can run the toolsetup.bat file, which is in the same +directory as this file. It should setup the remainder of the environment, +and build the tools if necessary. + +Please also refer to the 'BuildNotes.txt' file for more information on +building under Windows. + +=== Unix-like operating systems === + +To build on Unix-like operating systems, you only need to type 'make' in +the base directory of the project. + +=== Ubuntu Notes === + +On Ubuntu, the following command should install all the necessary build +packages to build all the C BaseTools: + + sudo apt-get install build-essentials uuid-dev + +=== Python sqlite3 module === +On Windows, the cx_freeze will not copy the sqlite3.dll to the frozen +binary directory (the same directory as build.exe and GenFds.exe). +Please copy it manually from \DLLs. + +The Python distributed with most recent Linux will have sqlite3 module +built in. If not, please install sqlit3 package separately. + +2. The binary tools will be updated only after passing developer testing. Current state of the tools is Proto-Type - not all tool functions have been implemented and there may be bugs in these tools. These tools are under constant development at this time. -20-Jun-2007 +3. Tool usage introduction. +BaseTools Simple Usage: +1) Change the directory to the EDK2 root directory, where the edksetup.bat is +2) Run "edksetup.bat NewBuild" +3) Set the ACTIVE_PLATFORM to your desired platform description file + (%WORKSPACE%\Conf\target.txt) +4) To build platform, run "build" command in non-module directory +5) To build module individually, run "build" command in module directory, i.e. where the + *.inf file is + +Notes: +1) The tree structure generated by build tools is similar to Ant build system. +2) Makefile can be called directly by nmake for both top level platform and module. But + after you call "nmake cleanall", you have to call "build" command to rebuild platform + or modules because the AutoGen.* files have been be removed. The "makefile" itself + cannot generate AutoGen.* files. Only "build" command can. +3) All .exe binary file including C and python tools are generated from: + r1655 \BaseTools\Source\ + r1662 VfrCompiler tool update + +Brief usage for Migration Tool MigrationMsa2Inf.exe: +1. Command line format: + MigrationMsa2Inf [options] +2. Input Files: + A syntactically valid MSA file +3. Output Files: + An extended INF file with possible auto-generated EntryPoint.c, CommonHeader.h/CommonHeader.txt, depending on options and module contents. +4. Prerequisite: + a. The workspace directory must be specified either by environment variable or -w option. + b. The Framework Database file must exist to specify the available packages in current workspace. + Two possible locations are: (The first location overrides the second) + $(WORKSPACE)\Tools\Conf\FrameworkDatabase.db + $(WORKSPACE)\Conf\FrameworkDatabase.db. + The field in FrameworkDatabase.db lists all available packages in current workspace. + One example: + + MdePkg/MdePkg.nspd + MdeModulePkg/MdeModulePkg.spd + IntelFrameworkPkg/IntelFrameworkPkg.spd + + The package list in FrameworkDatabase.db is important to the final quality of migration: + (1) It suggests the new package location: Translate package dependency Guid in MSA to Workspace relative path. + If the package dependency Guid cannot be found in current workspace a warning message is raised. + (2) It collects the Protocol/Guid/Ppi GuidCName a package contains. + The GuidCName acts as "clue" to add e.g. #include in CommonHeader.h + +5. Example: + WORKSAPCE has already been set: $(WORKSPACE) = c:\work\EdkII. + + a. MigrationMsa2Inf -f c:\work\EdkII\Nt32Pkg\WinNtThunkDxe\WinNtThunk.msa -o c:\work\EdkII\Nt32Pkg\WinNtThunkDxe\WinNtThunk.inf + b. MigrationMsa2Inf -f c:\work\EdkII\Nt32Pkg\WinNtThunkDxe\WinNtThunk.msa -a + Example a & b are equivalent to migrate WinNtThunk driver from EDKII to EDKII' code base. + + c. MigrationMsa2Inf -f c:\work\EdkII\Nt32Pkg\WinNtThunkDxe\WinNtThunk.msa -a -c + The extra "-c" option performs several hardcode mapping due to the naming change in EDKII': + OldMdePkg Guid -> MdePkgGuid, + EdkModulePkg Guid -> MdeModulePkgGuid, + EdkGraphicsLib -> GraphicsLib + HiiLib -> HiiLibFramework + ... + + d. MigrationMsa2Inf -f c:\work\EdkII\Nt32Pkg\WinNtThunkDxe\WinNtThunk.msa -m + The extra "-m" option suppresses the generation of "CommonHeader.h" and leave all C files intact. + Instead, it generates "CommonHeader.txt". Developers can manually copy its content to a local common header file in a module. + +6. Known Limitations: + a. Tool does not handle Exit Boot Services Callback & Virtual Address Changed Event. Developers need to handle it manually. + b. The #include is based on library class naming convention: The header filename for "AbcLib" class are "AbcLib.h" by convention. + c. The #include , and are added based on gGuidCName listed in MSA. + If a GuidCName cannot map to a package Guid/Protocol/Ppi header file, a warning message is raised. + If a module uses the definition in a pakcage Guid/Protocol/Ppi header file without list its associative GuidCName, the build will beak. Developer needs to manually add the include statement. + d. The [Depex] sections are generated from DXS files with Guid Macro translated to Guid CName by naming convention, etc. + If tool fails to "guess" the Guid CName from Guid Macro, it will leave the GuidMacro in [Depex] section for manual resolution. + e. When tool generates [Sources] section, the modifiers for source files are lost. (Need to add proper tool chain, etc) + f. When tool generates [LibraryClasses] section, the recommended library instances are lost. (No impact to build) + +7. Pyton Source + r682 \BaseTools\Source\Python\MigrationMsa2Inf + + +Brief Usage for PcdSyntax Update: +Usage: + PcdSyntaxUpdate.exe +It searches all INF, DEC and DSC file under and update them with the following rules: +1. Update INF files to conform to INF spec 0.44: + a. Rename PCD section name: e.g. [PcdsFeatureFlag] -> [FeaturePcd] + b. Adjust PCD section item format: e.g. PcdDebugClearMemoryValue|gEfiMdePkgTokenSpaceGuid -> gEfiMdePkgTokenSpaceGuid.PcdDebugClearMemoryValue + c. Update the syntax of binary INF file (not PCD related) +2. Update DEC files to confirm to DEC spec 0.36 + Adjust PCD section item format: e.g. PcdWinNtPhysicalDisk|0x00001000|gEfiNt32PkgTokenSpaceGuid|VOID*|L"E:RW;245760;512"-> gEfiNt32PkgTokenSpaceGuid.PcdWinNtFlashFvRecoverySize|0x0|UINT32|0x00001011 +3. Update DSC files to confirm to DSC spec + a. Adjust string/array typed PCD item format: e.g. PcdWinNtMemorySizeForSecMain|gEfiNt32PkgTokenSpaceGuid|L"64!64"|12 -> gEfiNt32PkgTokenSpaceGuid.PcdWinNtMemorySizeForSecMain|L"64!64"|VOID*|12 + b. Adjust non-string/array typed PCD item format: e.g. PcdWinNtBootMode|gEfiNt32PkgTokenSpaceGuid|1 -> gEfiNt32PkgTokenSpaceGuid.PcdWinNtBootMode|1 + c. Update the override library class in [Components] section: e.g. + { + PcdLib|MdePkg/Library/BasePcdLibNull/BasePcdLibNull.inf + } + To + { + PcdLib|MdePkg/Library/BasePcdLibNull/BasePcdLibNull.inf + } + +Brief usage for Migration Tool Spd2Dec.exe: +1. Command line format: + Spd2Dec [options] input_filename +2. Input File: + A syntactically valid SPD file +3. Output Files: + A DEC file whose syntax confirms to DEC spec. + +4. Example: + a. Spd2Dec -o c:\work\EdkII\Nt32Pkg\Nt32.spd c:\work\EdkII\Nt32Pkg\Nt32.dec + b. Spd2Dec -a c:\work\EdkII\Nt32Pkg\Nt32.spd + Example a & b are equivalent to migrate Nt32 package SPD file from EDKII to EDKII' snytax. + +6. Pyton Source + r777 \BaseTools\Source\Python\spd2Dec + +Brief usage for Migration Tool Fpd2Dsc.exe: +1. Command line format: + Fpd2Dsc [options] input_filename +2. Input File: + A syntactically valid FPD file +3. Output Files: + A DSC file which syntax confirms to DSC spec. +4. Prerequisite: + a. The workspace directory must be specified either by environment variable or -w option. + +5. Example: + WORKSAPCE has already been set: $(WORKSPACE) = c:\work\EdkII. + + a. Fpd2Dsc -o c:\work\EdkII\Nt32Pkg\Nt32.dsc c:\work\EdkII\Nt32Pkg\Nt32.fpd + b. Fpd2Dsc -a c:\work\EdkII\Nt32Pkg\Nt32.fpd + Example a & b are equivalent to migrate Nt32 platform description file from EDKII to EDKII' snytax. + +6. Known Limitations: + a. Tool does not handle Libraries Section since no related info in original FPD file. Developers need to handle it manually in the output DSC file. + b. If MSA file which is corresponds to module guid could not be found in currect workspace, tool will dump the module guid. + +7. Pyton Source + r767 \BaseTools\Source\Python\Fpd2Dsc + +17-July-2009