Restoring $WORKSPACE/BaseTools location, as the plan is to deprecate

$WORKSPACE/Tools instead.


git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@4147 6f19259b-4bc3-4df7-8a09-765794883524

1 files changed, 164 insertions, 0 deletions

diff --git a/BaseTools/ReadMe.txt b/BaseTools/ReadMe.txt
new file mode 100644
index 0000000000..2ebc06d297
--- /dev/null
+++ b/BaseTools/ReadMe.txt
@@ -0,0 +1,164 @@
+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.

+

+The binary tools will be updated only after passing developer testing.

+

+The BaseTools package will be updated with new tools only after all testing on a set

+of binary tools has successfully completed.

+

+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.

+

+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) build.exe in %WORKSPACE%\BaseTools\Bin\Win32 is generated from following revision of

+   Python source code:

+        r827 <buildtools_project>\BaseTools\Source\Python\Autogen

+        r827 <buildtools_project>\BaseTools\Source\Python\build

+        r827 <buildtools_project>\BaseTools\Source\Python\Common

+        r827 <buildtools_project>\BaseTools\Source\Python\CommonDataClass

+        r827 <buildtools_project>\BaseTools\Source\Python\GenFds

+        

+4) GenFds.exe has is a combo of the follow python source.(This is a temporary branch)

+        r827 <buildtools_project>\BaseTools\Source\Python\Common

+        r827 <buildtools_project>\BaseTools\Source\Python\CommonDataClass

+        r827 <buildtools_project>\BaseTools\Source\Python\GenFds

+	

+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

+   r682 <buildtools_project>\BaseTools\Source\Python\MigrationMsa2Inf

+

+

+Brief Usage for PcdSyntax Update:

+Usage:

+  PcdSyntaxUpdate.exe <directory_name>

+It searches all INF, DEC and DSC file under <directory_name> 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.

+   <LibraryClass> {

+      PcdLib|MdePkg/Library/BasePcdLibNull/BasePcdLibNull.inf

+   }

+   To 

+   <LibraryClasses> {

+      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 <buildtools_project>\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 <buildtools_project>\BaseTools\Source\Python\Fpd2Dsc

+

+27-September-2007