diff options
Diffstat (limited to 'BaseTools/ReadMe.txt')
| -rw-r--r-- | BaseTools/ReadMe.txt | 170 |
1 files changed, 170 insertions, 0 deletions
diff --git a/BaseTools/ReadMe.txt b/BaseTools/ReadMe.txt new file mode 100644 index 0000000000..37691e98fd --- /dev/null +++ b/BaseTools/ReadMe.txt @@ -0,0 +1,170 @@ +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, other
+directory contatins tools source.
+
+1. Build step to generate the binary tools.
+
+=== 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 <PythonHome>\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.
+
+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:
+ r1911 <buildtools_project>\BaseTools\Source\.
+
+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 <PackageList> field in FrameworkDatabase.db lists all available packages in current workspace.
+ One example:
+ <PackageList>
+ <Filename>MdePkg/MdePkg.nspd</Filename>
+ <Filename>MdeModulePkg/MdeModulePkg.spd</Filename>
+ <Filename>IntelFrameworkPkg/IntelFrameworkPkg.spd</Filename>
+ </PackageList>
+ 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 <Protocol/DiskIo.h> 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 <Library/AbcLib.h> is based on library class naming convention: The header filename for "AbcLib" class are "AbcLib.h" by convention.
+ c. The #include <Guid/Xyz.h>, <Protocol/Xyz.h> and <Ppi/Xyz.h> 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
+ BaseTools\Source\Python\MigrationMsa2Inf
+
+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
+ 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
+ BaseTools\Source\Python\fpd2dsc
+
+4-Mar-2010
|