a. Added doxygen comments
[people/mcb30/basetools.git] / Source / Python / AutoGen / GenMake.py
index 19ac708..43ec941 100755 (executable)
@@ -23,7 +23,6 @@ from Common.EdkIIWorkspaceBuild import *
 from Common.EdkIIWorkspace import *\r
 from Common.BuildToolError import *\r
 from Common.Misc import *\r
-from BuildInfo import *\r
 from BuildEngine import *\r
 import Common.GlobalData as GlobalData\r
 \r
@@ -33,7 +32,7 @@ gIncludePattern = re.compile("^[ #]*include[ \t]+[\"<]*([^\"<>\n\r]+)[>\" ]*$",
 ## Regular expression for matching macro used in header file inclusion\r
 gMacroPattern = re.compile("([_A-Z][_A-Z0-9]*)[ \t]*\((.+)\)", re.UNICODE)\r
 \r
-##\r
+## pattern for include style in R8.x code\r
 gProtocolDefinition = "Protocol/%(HeaderKey)s/%(HeaderKey)s.h"\r
 gGuidDefinition = "Guid/%(HeaderKey)s/%(HeaderKey)s.h"\r
 gArchProtocolDefinition = "ArchProtocol/%(HeaderKey)s/%(HeaderKey)s.h"\r
@@ -54,6 +53,7 @@ gIncludeMacroConversion = {
   "EFI_PPI_DEPENDENCY"              :   gPpiDefinition,\r
 }\r
 \r
+## default makefile type\r
 gMakeType = ""\r
 if sys.platform == "win32":\r
     gMakeType = "nmake"\r
@@ -63,17 +63,20 @@ else:
 \r
 ## BuildFile class\r
 #\r
-#  This class encapsules makefie and its generation. It uses template to generate\r
-#  the content of makefile. The content of makefile will be got from PlatformBuildInfo\r
-#  or ModuleBuildInfo objects.\r
+#  This base class encapsules build file and its generation. It uses template to generate\r
+#  the content of build file. The content of build file will be got from AutoGen objects.\r
 #\r
 class BuildFile(object):\r
+    ## template used to generate the build file (i.e. makefile if using make)\r
     _TEMPLATE_ = ''\r
+\r
+    ## default file name for each type of build file\r
     _FILE_NAME_ = {\r
         "nmake" :   "Makefile",\r
         "gmake" :   "GNUmakefile"\r
     }\r
 \r
+    ## Fixed header string for makefile\r
     _MAKEFILE_HEADER = '''#\r
 # DO NOT EDIT\r
 # This file is auto-generated by build utility\r
@@ -87,13 +90,14 @@ class BuildFile(object):
 #   Auto-generated makefile for building modules, libraries or platform\r
 #\r
     '''\r
-    \r
+\r
+    ## Header string for each type of build file\r
     _FILE_HEADER_ = {\r
         "nmake" :   _MAKEFILE_HEADER % _FILE_NAME_["nmake"],\r
         "gmake" :   _MAKEFILE_HEADER % _FILE_NAME_["gmake"]\r
     }\r
 \r
-    #   \r
+    ## shell commands which can be used in build file in the form of macro\r
     #   $(CP)     copy file command\r
     #   $(MV)     move file command\r
     #   $(RM)     remove file command\r
@@ -118,31 +122,44 @@ class BuildFile(object):
         }\r
     }\r
 \r
+    ## directory separator\r
     _SEP_ = {\r
         "nmake" :   "\\", \r
         "gmake" :   "/"\r
     }\r
-    \r
+\r
+    ## directory creation template\r
     _MD_TEMPLATE_ = {\r
         "nmake" :   'if not exist %(dir)s $(MD) %(dir)s',\r
         "gmake" :   "test ! -e %(dir)s && $(MD) %(dir)s"\r
     }\r
 \r
+    ## directory removal template\r
     _RD_TEMPLATE_ = {\r
         "nmake" :   'if exist %(dir)s $(RD) %(dir)s',\r
         "gmake" :   "test -e %(dir)s && $(RD) %(dir)s"\r
     }\r
-    \r
+\r
     _INC_FLAG_ = {"MSFT" : "/I", "GCC" : "-I", "INTEL" : "-I"}\r
     \r
     _LIB_GROUP_START_ = {"MSFT" : "", "GCC" : "-(", "INTEL" : ""}\r
-    _LIB_GROUP_END = {"MSFT" : "", "GCC" : "-)", "INTEL" : ""}\r
-    \r
+    _LIB_GROUP_END = {"MSFT" : "", "GCC" : "-)", "INTEL" : ""}    \r
 \r
+    ## Constructor of BuildFile\r
+    #\r
+    #   @param  AutoGenObject   Object of AutoGen class\r
+    # \r
     def __init__(self, AutoGenObject):\r
         self._AutoGenObject = AutoGenObject\r
         self._FileType = gMakeType\r
 \r
+    ## Create build file\r
+    #\r
+    #   @param  FileType    Type of build file. Only nmake and gmake are supported now.\r
+    # \r
+    #   @retval TRUE        The build file is created or re-created successfully\r
+    #   @retval FALSE       The build file exists and is the same as the one to be generated\r
+    # \r
     def Generate(self, FileType=gMakeType):\r
         self._FileType = FileType\r
         FileContent = TemplateString()\r
@@ -154,7 +171,6 @@ class BuildFile(object):
     ## Return a list of directory creation command string\r
     #\r
     #   @param      DirList     The list of directory to be created\r
-    #   @param      MakeType    GNU makefile or MS makefile\r
     #\r
     #   @retval     list        The directory creation command list\r
     #\r
@@ -164,7 +180,6 @@ class BuildFile(object):
     ## Return a list of directory removal command string\r
     #\r
     #   @param      DirList     The list of directory to be removed\r
-    #   @param      MakeType    GNU makefile or MS makefile\r
     #\r
     #   @retval     list        The directory removal command list\r
     #\r
@@ -172,7 +187,13 @@ class BuildFile(object):
         return [self._RD_TEMPLATE_[self._FileType] % {'dir':Dir} for Dir in DirList]\r
 \r
 \r
+## ModuleMakefile class\r
+#\r
+#  This class encapsules makefie and its generation for module. It uses template to generate\r
+#  the content of makefile. The content of makefile will be got from ModuleAutoGen object.\r
+#\r
 class ModuleMakefile(BuildFile):\r
+    ## template used to generate the makefile for module\r
     _TEMPLATE_ = '''\\r
 ${makefile_header}\r
 \r
@@ -362,7 +383,11 @@ cleanpch:
 cleanlib:\r
 \t${BEGIN}@cd ${dependent_library_build_directory} && "$(MAKE)" $(MAKE_FLAGS) cleanall\r
 \t${END}@cd $(MODULE_BUILD_DIR)\n'''\r
-    \r
+\r
+    ## Constructor of ModuleMakefile\r
+    #\r
+    #   @param  ModuleAutoGen   Object of ModuleAutoGen class\r
+    # \r
     def __init__(self, ModuleAutoGen):\r
         BuildFile.__init__(self, ModuleAutoGen)\r
         self.PlatformInfo = self._AutoGenObject.PlatformInfo\r
@@ -370,11 +395,11 @@ cleanlib:
         self.ResultFileList = []\r
         self.IntermediateDirectoryList = ["$(DEBUG_DIR)", "$(OUTPUT_DIR)"]\r
     \r
-        self.SourceFileDatabase = {}  # {file type : file path}\r
-        self.DestFileDatabase = {}  # {file type : file path}\r
-        self.FileBuildTargetList = [] # [(src, target string)]\r
-        self.BuildTargetList = [] # [target string]\r
-        self.PendingBuildTargetList = [] # [FileBuildRule objects]\r
+        self.SourceFileDatabase = {}        # {file type : file path}\r
+        self.DestFileDatabase = {}          # {file type : file path}\r
+        self.FileBuildTargetList = []       # [(src, target string)]\r
+        self.BuildTargetList = []           # [target string]\r
+        self.PendingBuildTargetList = []    # [FileBuildRule objects]\r
         self.CommonFileDependency = []\r
 \r
         self.FileDependency = []\r
@@ -384,6 +409,7 @@ cleanlib:
         self.LibraryBuildDirectoryList = []\r
         self.SystemLibraryList = []\r
 \r
+    # Compose a dict object containing information used to do replacement in template\r
     def _CreateTemplateDict(self):\r
         if self._FileType not in self._SEP_:\r
             EdkLogger.error("build", PARAMETER_INVALID, "Invalid Makefile type", ExtraData=self._FileType)\r
@@ -523,8 +549,6 @@ cleanlib:
     #  build rules in $(WORKSPACE)/Conf/build_rule.txt. The dependencies of source\r
     #  file are figured out by search included files in the source file.\r
     #\r
-    #   @param      MakeType    GNU makefile or MS makefile\r
-    #\r
     def ProcessSourceFileList(self):\r
         Separator = self._SEP_[self._FileType]\r
 \r
@@ -743,8 +767,6 @@ cleanlib:
     #\r
     # All binary files are just copied to $(OUTPUT_DIR)\r
     # \r
-    #   @param      MakeType    GNU makefile or MS makefile\r
-    #\r
     def ProcessBinaryFileList(self):\r
         BinaryFiles = self._AutoGenObject.BinaryFileDict\r
         BuildTargetString = "%(dst)s : %(src)s\n"\\r
@@ -761,9 +783,6 @@ cleanlib:
                 self.BuildTargetList.append(BuildTargetString % {"dst":Dst, "src":Src})\r
 \r
     ## For creating makefile targets for dependent libraries\r
-    #\r
-    #   @param      MakeType    GNU makefile or MS makefile\r
-    #\r
     def ProcessDependentLibrary(self):\r
         for LibraryAutoGen in self._AutoGenObject.LibraryAutoGenList:\r
             self.LibraryBuildDirectoryList.append(LibraryAutoGen.BuildDir)\r
@@ -879,7 +898,13 @@ cleanlib:
 \r
     _TemplateDict = property(_CreateTemplateDict)\r
 \r
+## CustomMakefile class\r
+#\r
+#  This class encapsules makefie and its generation for module. It uses template to generate\r
+#  the content of makefile. The content of makefile will be got from ModuleAutoGen object.\r
+#\r
 class CustomMakefile(BuildFile):\r
+    ## template used to generate the makefile for module with custom makefile\r
     _TEMPLATE_ = '''\\r
 ${makefile_header}\r
 \r
@@ -969,29 +994,27 @@ init:
 ${BEGIN}\t-@${create_directory_command}\n${END}\\r
 \r
 '''\r
+    ## Constructor of CustomMakefile\r
+    #\r
+    #   @param  ModuleAutoGen   Object of ModuleAutoGen class\r
+    # \r
     def __init__(self, ModuleAutoGen):\r
         BuildFile.__init__(self, ModuleAutoGen)\r
         self.PlatformInfo = self._AutoGenObject.PlatformInfo\r
         self.IntermediateDirectoryList = ["$(DEBUG_DIR)", "$(OUTPUT_DIR)"]\r
 \r
-    ## Create customized makefile for a module\r
-    #\r
-    #   @param      File        The path of the makefile\r
-    #   @param      MakeType    GNU makefile or MS makefile\r
-    #\r
-    #   @retval     True        If the file is changed or doesn't exist\r
-    #   @retval     False       If the file exists and its content is not changed\r
-    #                           since last time\r
-    #\r
+    # Compose a dict object containing information used to do replacement in template\r
     def _CreateTemplateDict(self):\r
         Separator = self._SEP_[self._FileType]\r
         try:\r
-            CustomMakefile = open(\r
-                                os.path.join(\r
-                                            self._AutoGenObject.WorkspaceDir, \r
-                                            self._AutoGenObject.CustomMakefile[self._FileType]\r
-                                            ),\r
-                                'r').read()\r
+            if self._FileType not in self._AutoGenObject.CustomMakefile:\r
+                EdkLogger.error('build', OPTION_NOT_SUPPORTED, "No custom makefile for %s" % self._FileType,\r
+                                ExtraData=str(self._AutoGenObject))\r
+            MakefilePath = os.path.join(\r
+                                    self._AutoGenObject.WorkspaceDir, \r
+                                    self._AutoGenObject.CustomMakefile[self._FileType]\r
+                                    )\r
+            CustomMakefile = open(MakefilePath, 'r').read()\r
         except:\r
             EdkLogger.error('build', FILE_OPEN_FAILURE, ExtraData=self._AutoGenObject.CustomMakefile[self._FileType])\r
 \r
@@ -1035,7 +1058,14 @@ ${BEGIN}\t-@${create_directory_command}\n${END}\
 \r
     _TemplateDict = property(_CreateTemplateDict)\r
 \r
+## PlatformMakefile class\r
+#\r
+#  This class encapsules makefie and its generation for platform. It uses \r
+# template to generate the content of makefile. The content of makefile will be\r
+# got from PlatformAutoGen object.\r
+#\r
 class PlatformMakefile(BuildFile):\r
+    ## template used to generate the makefile for platform\r
     _TEMPLATE_ = '''\\r
 ${makefile_header}\r
 \r
@@ -1129,6 +1159,10 @@ cleanlib:
 \t${END}@cd $(BUILD_DIR)\n\r
 '''\r
 \r
+    ## Constructor of PlatformMakefile\r
+    #\r
+    #   @param  ModuleAutoGen   Object of PlatformAutoGen class\r
+    # \r
     def __init__(self, PlatformAutoGen):\r
         BuildFile.__init__(self, PlatformAutoGen)\r
         self.ModuleBuildCommandList = []\r
@@ -1137,15 +1171,7 @@ cleanlib:
         self.ModuleBuildDirectoryList = []\r
         self.LibraryBuildDirectoryList = []\r
 \r
-    ## Create makefile of platform\r
-    #\r
-    #   @param      File        The path of the makefile\r
-    #   @param      MakeType    GNU makefile or MS makefile\r
-    #\r
-    #   @retval     True        If the file is changed or doesn't exist\r
-    #   @retval     False       If the file exists and its content is not changed\r
-    #                           since last time\r
-    #\r
+    # Compose a dict object containing information used to do replacement in template\r
     def _CreateTemplateDict(self):\r
         Separator = self._SEP_[self._FileType]\r
 \r
@@ -1208,7 +1234,14 @@ cleanlib:
 \r
     _TemplateDict = property(_CreateTemplateDict)\r
 \r
+## TopLevelMakefile class\r
+#\r
+#  This class encapsules makefie and its generation for entrance makefile. It \r
+# uses template to generate the content of makefile. The content of makefile \r
+# will be got from WorkspaceAutoGen object.\r
+#\r
 class TopLevelMakefile(BuildFile):\r
+    ## template used to generate toplevel makefile\r
     _TEMPLATE_ = '''\\r
 ${makefile_header}\r
 \r
@@ -1304,19 +1337,15 @@ ${BEGIN}\t@cd $(BUILD_DIR)${separator}${arch} && "$(MAKE)" $(MAKE_FLAGS) cleanli
 ${END}\t@cd $(BUILD_DIR)\n\r
 '''\r
 \r
+    ## Constructor of TopLevelMakefile\r
+    #\r
+    #   @param  Workspace   Object of WorkspaceAutoGen class\r
+    # \r
     def __init__(self, Workspace):\r
         BuildFile.__init__(self, Workspace)\r
         self.IntermediateDirectoryList = []\r
 \r
-    ## Create makefile of platform\r
-    #\r
-    #   @param      File        The path of the makefile\r
-    #   @param      MakeType    GNU makefile or MS makefile\r
-    #\r
-    #   @retval     True        If the file is changed or doesn't exist\r
-    #   @retval     False       If the file exists and its content is not changed\r
-    #                           since last time\r
-    #\r
+    # Compose a dict object containing information used to do replacement in template\r
     def _CreateTemplateDict(self):\r
         Separator = self._SEP_[self._FileType]\r
 \r
@@ -1403,7 +1432,7 @@ ${END}\t@cd $(BUILD_DIR)\n
 \r
     _TemplateDict = property(_CreateTemplateDict)\r
 \r
-\r
 # This acts like the main() function for the script, unless it is 'import'ed into another script.\r
 if __name__ == '__main__':\r
     pass\r
+\r