Added comments and polished the code.
authorjwang36 <jwang36@6f19259b-4bc3-4df7-8a09-765794883524>
Wed, 16 Aug 2006 10:35:00 +0000 (10:35 +0000)
committerjwang36 <jwang36@6f19259b-4bc3-4df7-8a09-765794883524>
Wed, 16 Aug 2006 10:35:00 +0000 (10:35 +0000)
git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@1293 6f19259b-4bc3-4df7-8a09-765794883524

Tools/Source/GenBuild/org/tianocore/build/FrameworkBuildTask.java
Tools/Source/GenBuild/org/tianocore/build/global/GlobalData.java
Tools/Source/GenBuild/org/tianocore/build/toolchain/ConfigReader.java
Tools/Source/GenBuild/org/tianocore/build/toolchain/ToolChainAttribute.java
Tools/Source/GenBuild/org/tianocore/build/toolchain/ToolChainConfig.java
Tools/Source/GenBuild/org/tianocore/build/toolchain/ToolChainElement.java
Tools/Source/GenBuild/org/tianocore/build/toolchain/ToolChainInfo.java
Tools/Source/GenBuild/org/tianocore/build/toolchain/ToolChainKey.java
Tools/Source/GenBuild/org/tianocore/build/toolchain/ToolChainMap.java

index d236c5b..6cdbbe5 100644 (file)
@@ -112,33 +112,38 @@ public class FrameworkBuildTask extends Task{
         //\r
         File buildFile = null;\r
         if (msaFiles.size() > 1) {\r
-            throw new BuildException("Having more than one MSA file in a directory is not allowed!");\r
-        } else if (msaFiles.size() == 1 && activePlatform == null) {\r
-            throw new BuildException("If trying to build a single module, please set ACTIVE_PLATFORM in file [Tool/Conf/target.txt]. ");\r
-        } else if (msaFiles.size() == 1 && activePlatform != null) {\r
+            throw new BuildException("More than one MSA file under current directory. It is not allowd. ");\r
+        }\r
+        else if (msaFiles.size() == 1 && activePlatform == null) {\r
+            throw new BuildException("If try to build a single module, please set ACTIVE_PLATFORM in file [Tool/Conf/target.txt]. ");\r
+        }\r
+        else if (msaFiles.size() == 1 && activePlatform != null) {\r
             //\r
             // Build the single module\r
             //\r
             buildFile = msaFiles.toArray(new File[1])[0];\r
-        } else if (activePlatform != null) {\r
+        }\r
+        else if (activePlatform != null) {\r
             buildFile = new File(GlobalData.getWorkspacePath() + File.separatorChar + activePlatform);\r
-        } else if (fpdFiles.size() == 1) {\r
+        }\r
+        else if (fpdFiles.size() == 1) {\r
             buildFile = fpdFiles.toArray(new File[1])[0];\r
-        } else if (fpdFiles.size() > 1) {\r
+        }\r
+        else if (fpdFiles.size() > 1) {\r
             buildFile = intercommuniteWithUser();\r
         }\r
         //\r
         // If there is no build files or FPD files or MSA files, stop build\r
         //\r
         else {\r
-            throw new BuildException("Can't find any FPD or MSA files in the current directory. ");\r
+            throw new BuildException("Can't find any FPD files or MSA files in current directory. ");\r
         }\r
 \r
         //\r
         // Build every FPD files (PLATFORM build)\r
         //\r
         if (buildFile.getName().endsWith(".fpd")) {\r
-            System.out.println("Processing the FPD file [" + buildFile.getPath() + "] ..>> ");\r
+            System.out.println("Start to build FPD file [" + buildFile.getPath() + "] ..>> ");\r
             FpdParserTask fpdParserTask = new FpdParserTask();\r
             fpdParserTask.setType(type);\r
             fpdParserTask.setProject(getProject());\r
@@ -151,8 +156,8 @@ public class FrameworkBuildTask extends Task{
         //\r
         else if (buildFile.getName().endsWith(".msa")) {\r
             File tmpFile = new File(GlobalData.getWorkspacePath() + File.separatorChar + activePlatform);\r
-            System.out.println("Using the FPD file [" + tmpFile.getPath() + "] for the active platform. ");\r
-            System.out.println("Processing the MSA file [" + buildFile.getPath() + "] ..>> ");\r
+            System.out.println("Using FPD file [" + tmpFile.getPath() + "] as active platform. ");\r
+            System.out.println("Start to build MSA file [" + buildFile.getPath() + "] ..>> ");\r
             GenBuildTask genBuildTask = new GenBuildTask();\r
             genBuildTask.setSingleModuleBuild(true);\r
             genBuildTask.setType(type);\r
@@ -186,22 +191,26 @@ public class FrameworkBuildTask extends Task{
 \r
     private File intercommuniteWithUser(){\r
         File file = null;\r
-        if (fpdFiles.size() > 1) {\r
-            File[] allFiles = new File[fpdFiles.size()];\r
+        if (fpdFiles.size() + msaFiles.size() > 1) {\r
+            File[] allFiles = new File[fpdFiles.size() + msaFiles.size()];\r
             int index = 0;\r
             Iterator<File> iter = fpdFiles.iterator();\r
             while (iter.hasNext()) {\r
                 allFiles[index] = iter.next();\r
                 index++;\r
             }\r
-\r
-            System.out.println("Finding " + allFiles.length + " FPD files: ");\r
+            iter = msaFiles.iterator();\r
+            while (iter.hasNext()) {\r
+                allFiles[index] = iter.next();\r
+                index++;\r
+            }\r
+            System.out.println("Find " + allFiles.length + " FPD and MSA files: ");\r
             for (int i = 0; i < allFiles.length; i++) {\r
                 System.out.println("[" + (i + 1) + "]: " + allFiles[i].getName());\r
             }\r
             \r
             boolean flag = true;\r
-            System.out.print("Please select one of the following FPD files to build:[1] ");\r
+            System.out.print("Please select one file to build:[1] ");\r
             do{\r
                 BufferedReader br = new BufferedReader(new InputStreamReader(System.in));\r
                 try {\r
@@ -225,9 +234,13 @@ public class FrameworkBuildTask extends Task{
                     flag = true;\r
                 }\r
             } while (flag);\r
-        } else if (fpdFiles.size() == 1) {\r
+        }\r
+        else if (fpdFiles.size() == 1) {\r
             file = fpdFiles.toArray(new File[1])[0];\r
         }\r
+        else if (msaFiles.size() == 1) {\r
+            file = msaFiles.toArray(new File[1])[0];\r
+        }\r
         return file;\r
     }\r
     \r
@@ -235,14 +248,17 @@ public class FrameworkBuildTask extends Task{
     public void setType(String type) {\r
         if (type.equalsIgnoreCase("clean") || type.equalsIgnoreCase("cleanall")) {\r
             this.type = type.toLowerCase();\r
-        } else {\r
+        }\r
+        else {\r
             this.type = "all";\r
         }\r
     }\r
     \r
     private void readTargetFile(){\r
         try {\r
-            String[][] targetFileInfo = ConfigReader.parse(getProject().getProperty("WORKSPACE_DIR"), "Tools" + File.separatorChar + "Conf" + File.separatorChar + targetFilename);\r
+            String targetFile = getProject().getProperty("WORKSPACE_DIR") + File.separatorChar \r
+                + "Tools" + File.separatorChar + "Conf" + File.separatorChar + targetFilename;\r
+            String[][] targetFileInfo = ConfigReader.parse(targetFile);\r
             \r
             //\r
             // Get ToolChain Info from target.txt\r
@@ -251,19 +267,22 @@ public class FrameworkBuildTask extends Task{
             String str = getValue("TARGET", targetFileInfo);\r
             if (str == null || str.trim().equals("")) {\r
                 envToolChainInfo.addTargets("*");\r
-            } else {\r
+            }\r
+            else {\r
                 envToolChainInfo.addTargets(str);\r
             }\r
             str = getValue("TOOL_CHAIN_TAG", targetFileInfo);\r
             if (str == null || str.trim().equals("")) {\r
                 envToolChainInfo.addTagnames("*");\r
-            } else {\r
+            }\r
+            else {\r
                 envToolChainInfo.addTagnames(str);\r
             }\r
             str = getValue("TARGET_ARCH", targetFileInfo);\r
             if (str == null || str.trim().equals("")) {\r
                 envToolChainInfo.addArchs("*");\r
-            } else {\r
+            }\r
+            else {\r
                 envToolChainInfo.addArchs(str);\r
             }\r
             GlobalData.setToolChainEnvInfo(envToolChainInfo);\r
@@ -276,7 +295,7 @@ public class FrameworkBuildTask extends Task{
             str = getValue("ACTIVE_PLATFORM", targetFileInfo);\r
             if (str != null && ! str.trim().equals("")) {\r
                 if ( ! str.endsWith(".fpd")) {\r
-                    throw new BuildException("FPD file's extension must be \".fpd\"!");\r
+                    throw new BuildException("FPD file's file extension must be \".fpd\"");\r
                 }\r
                 activePlatform = str;\r
             }\r
index 9778eaf..3a5d1dd 100644 (file)
@@ -164,7 +164,11 @@ public class GlobalData {
         //\r
         File toolsDefFile = new File(workspaceDir + File.separatorChar + toolsDefFilename);\r
         System.out.println("Using tool definiton file [" + toolsDefFile.getPath() + "].");\r
-        toolsDef = new ToolChainConfig(toolsDefFile);\r
+        try {\r
+            toolsDef = new ToolChainConfig(toolsDefFile);\r
+        } catch (Exception e) {\r
+            throw new BuildException(e.getMessage());\r
+        }\r
 \r
         //\r
         // Parse Framework Database\r
index 6e26ade..b6f58ce 100644 (file)
@@ -1,8 +1,8 @@
 /** @file\r
   ConfigReader class.\r
-\r
-  ConfigReader is used to read tool chain config file with flat format.\r
-\r
+  \r
+  ConfigReader is used to read tool chain config file with flat format. \r
+  \r
 Copyright (c) 2006, Intel Corporation\r
 All rights reserved. This program and the accompanying materials\r
 are licensed and made available under the terms and conditions of the BSD License\r
@@ -23,65 +23,65 @@ import java.util.ArrayList;
 import java.util.List;\r
 \r
 /**\r
-\r
+  \r
   ConfigReader is used to read tool chain config file with flat format. Comments\r
   is line starting with character '#'.\r
-\r
+  \r
   @since GenBuild 1.0\r
 **/\r
 public class ConfigReader {\r
 \r
-    private static String confPath = ".";\r
-\r
-\r
-    /**\r
-      Public construct method.\r
-    **/\r
-    public ConfigReader () {\r
-    }\r
-\r
     /**\r
-      Default filepath is ".".\r
+      Parse specified tool chain definition file.\r
+    \r
+      @param    filename    The config file name with full path\r
 \r
-      @param filename the config file name like "target.txt"\r
-      @return the variables defined in file\r
+      @return String[][]    The definition array\r
     **/\r
     public static synchronized String[][] parse(String filename) throws EdkException {\r
-        return parse(confPath, filename);\r
+        return parse(new File(filename));\r
     }\r
 \r
     /**\r
-      Get all variables defined in config file. the config file format is flat\r
-      with "A=B". If line started with '#' looks as comments.\r
-\r
-      @param confPath the path of config file\r
-      @param filename the file name of the config file\r
-      @return the variables defined in the config file\r
-      @throws BuildException\r
-              Config file's format is not valid\r
+      Get all definitions in config file. the config file format is flat\r
+      with "A=B". If line started with '#' looks as comments. \r
+    \r
+      @param    configFile      The config file\r
+\r
+      @return   String[][]      The variables defined in the config file\r
+\r
+      @throws   EdkException\r
+                Config file's format is not valid\r
     **/\r
-    public static synchronized String[][] parse(String confPath, String filename) throws EdkException {\r
-        //Map<String, String> map = new TreeMap<String,String>(comparator);\r
+    public static synchronized String[][] parse(File configFile) throws EdkException {\r
         List<String> keyList = new ArrayList<String>(256);\r
         List<String> valueList = new ArrayList<String>(256);\r
+        int lines = 0;\r
 \r
         try {\r
-            File file = new File(confPath + File.separatorChar + filename);\r
-            FileReader reader = new FileReader(file);\r
+            FileReader reader = new FileReader(configFile);\r
             BufferedReader in = new BufferedReader(reader);\r
             String str;\r
 \r
             while ((str = in.readLine()) != null) {\r
+                ++lines;\r
                 str = str.trim();\r
                 //\r
-                // if str is empty line, comments (start with '#'),\r
-                // without '=', or start with '='\r
+                // skip empty line, comment (start with '#') \r
                 //\r
-                int index;\r
-                if (str.length() == 0 || str.startsWith("#") ||\r
-                    (index = str.indexOf('=')) <= 0) {\r
+                if (str.length() == 0 || str.startsWith("#")) {\r
                     continue;\r
                 }\r
+\r
+                //\r
+                // stop if the definition line is not in "name=value" form\r
+                // \r
+                int index;\r
+                if ((index = str.indexOf('=')) <= 0) {\r
+                    throw new EdkException("ERROR Processing file [" + configFile.getAbsolutePath() \r
+                        + "] (line " + lines + ").\n");\r
+                }\r
+\r
                 //\r
                 // look as line "A = B"\r
                 //\r
@@ -89,7 +89,8 @@ public class ConfigReader {
                 valueList.add(str.substring(index + 1).trim());\r
             }\r
         } catch (Exception e) {\r
-            throw new EdkException("ERROR Processing file [" + filename + "].\n" + e.getMessage());\r
+            throw new EdkException("ERROR Processing file [" + configFile.getAbsolutePath() \r
+                + "] (line " + lines + ").\n" + e.getMessage());\r
         }\r
 \r
         String[][] definitions = new String[2][keyList.size()];\r
@@ -98,39 +99,6 @@ public class ConfigReader {
 \r
         return definitions;\r
     }\r
-\r
-    public static synchronized ToolChainMap parseToolChainConfig(File ConfigFile) throws EdkException {\r
-        ToolChainMap map = new ToolChainMap();\r
-\r
-        try {\r
-            FileReader reader = new FileReader(ConfigFile);\r
-            BufferedReader in = new BufferedReader(reader);\r
-            String str;\r
-\r
-            while ((str = in.readLine()) != null) {\r
-                str = str.trim();\r
-                //\r
-                // if str is empty line, comments (start with '#'),\r
-                // without '=', or start with '='\r
-                //\r
-                int index;\r
-                if (str.length() == 0 || str.startsWith("#") ||\r
-                    (index = str.indexOf('=')) <= 0) {\r
-                    continue;\r
-                }\r
-                //\r
-                // look as line "A = B"\r
-                //\r
-                String key = str.substring(0, index).trim().toUpperCase();\r
-                String value = str.substring(index + 1).trim();\r
-                map.put(key, value);\r
-            }\r
-        } catch (Exception e) {\r
-            throw new EdkException("ERROR Processing file [" + ConfigFile.getAbsolutePath() + "].\n" + e.getMessage());\r
-        }\r
-\r
-        return map;\r
-    }\r
 }\r
 \r
 \r
index fad10da..491d37c 100644 (file)
@@ -1,5 +1,7 @@
 /** @file\r
-This file is to define  ToolChainAttribute class.\r
+ToolChainAttribute class\r
+\r
+This file is to define enumeration value for tool chain attribute names.\r
 \r
 Copyright (c) 2006, Intel Corporation\r
 All rights reserved. This program and the accompanying materials\r
@@ -22,9 +24,9 @@ package org.tianocore.build.toolchain;
 public class ToolChainAttribute {\r
     private static int nextValue = 0;\r
 \r
-    //\r
-    // "NAME", "PATH", "DPATH", "SPATH", "EXT", "FAMILY", "FLAGS"\r
-    // \r
+    ///\r
+    /// "NAME", "PATH", "DPATH", "SPATH", "EXT", "FAMILY", "FLAGS"\r
+    /// \r
     public final static ToolChainAttribute NAME = new ToolChainAttribute("NAME");\r
     public final static ToolChainAttribute PATH = new ToolChainAttribute("PATH");\r
     public final static ToolChainAttribute DPATH = new ToolChainAttribute("DPATH");\r
@@ -48,7 +50,3 @@ public class ToolChainAttribute {
     }\r
 }\r
 \r
-\r
-\r
-\r
-\r
index 4082c6d..73e6615 100644 (file)
@@ -1,8 +1,8 @@
 /** @file\r
   ToolChainConfig class.\r
-\r
-  ToolChainFactory class parse all config files and get tool chain information.\r
-\r
+  \r
+  ToolChainConfig class parse all config files and get tool chain information.\r
+  \r
 Copyright (c) 2006, Intel Corporation\r
 All rights reserved. This program and the accompanying materials\r
 are licensed and made available under the terms and conditions of the BSD License\r
@@ -15,8 +15,6 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
 **/\r
 package org.tianocore.build.toolchain;\r
 \r
-import org.apache.tools.ant.BuildException;\r
-\r
 import org.tianocore.common.exception.EdkException;\r
 import org.tianocore.build.toolchain.ToolChainKey;\r
 import org.tianocore.build.toolchain.ToolChainMap;\r
@@ -27,45 +25,53 @@ import java.util.Set;
 \r
 \r
 /**\r
-\r
-  ToolChainFactory class parse all config files and get tool chain information.\r
-\r
\r
+  ToolChainConfig class parse all config files and get tool chain information.\r
+  \r
  **/\r
 public class ToolChainConfig {\r
-    ///\r
-    /// tool chain definitions\r
-    ///\r
+    //\r
+    // tool chain definitions\r
+    //\r
     private ToolChainMap config = null;\r
-    ///\r
-    /// tool chain information (how many targets, archs, etc.)\r
-    ///\r
+    //\r
+    // tool chain information (how many targets, archs, etc.)\r
+    // \r
     private ToolChainInfo info = new ToolChainInfo();\r
 \r
     /**\r
       Public construct method.\r
-     **/\r
-    public ToolChainConfig () {\r
+      \r
+      @param toolChainFile File object representing the tool chain configuration file\r
+    **/\r
+    public ToolChainConfig (File toolChainFile) throws EdkException {\r
+        config = getToolChainConfig(toolChainFile);\r
+        parseToolChainDefKey(config.keySet());\r
     }\r
 \r
     /**\r
-      Public construct method.\r
+       Read tool chain definitions from specified file and put them in \r
+       ToolChainMap class.\r
 \r
-      @param toolChainFile File object representing the tool chain configuration file\r
-    **/\r
-    public ToolChainConfig (File toolChainFile) {\r
-        try {\r
-            config = ConfigReader.parseToolChainConfig(toolChainFile);\r
-            parseToolChainDefKey(config.keySet());\r
-        }\r
-        catch (EdkException ex) {\r
-            throw new BuildException(ex.getMessage());\r
+       @param ConfigFile    The file containing tool chain definitions\r
+       \r
+       @return ToolChainMap\r
+     **/\r
+    private ToolChainMap getToolChainConfig(File ConfigFile) throws EdkException {\r
+        ToolChainMap map = new ToolChainMap();\r
+        String[][] toolChainDef = ConfigReader.parse(ConfigFile);\r
+    \r
+        for (int i = 0; i < toolChainDef[0].length; ++i) {\r
+            map.put(toolChainDef[0][i], toolChainDef[1][i]);\r
         }\r
+\r
+        return map;\r
     }\r
 \r
     /**\r
      Collect target, tool chain tag, arch and command information from key part\r
      of configuration\r
-\r
+      \r
      @param toolChainDefKey The set of keys in tool chain configuration\r
      **/\r
     private void parseToolChainDefKey (Set<ToolChainKey> toolChainDefKey) {\r
@@ -73,16 +79,16 @@ public class ToolChainConfig {
         while (it.hasNext()) {\r
             ToolChainKey key = (ToolChainKey)it.next();\r
             String[] keySet = key.getKeySet();\r
-            info.addTargets(keySet[0]);\r
-            info.addTagnames(keySet[1]);\r
-            info.addArchs(keySet[2]);\r
-            info.addCommands(keySet[1], keySet[3]);\r
+            info.addTargets(keySet[ToolChainElement.TARGET.value]);\r
+            info.addTagnames(keySet[ToolChainElement.TOOLCHAIN.value]);\r
+            info.addArchs(keySet[ToolChainElement.ARCH.value]);\r
+            info.addCommands(keySet[ToolChainElement.TOOLCODE.value]);\r
         }\r
     }\r
 \r
     /**\r
-     Return the tool chain configuration information in a Map form\r
-\r
+     Return the tool chain configuration information in a Map form \r
+      \r
      @return ToolChainMap Tool chain configurations in a ToolChainMap\r
      **/\r
     public ToolChainMap getConfig() {\r
@@ -91,8 +97,8 @@ public class ToolChainConfig {
 \r
     /**\r
      Return the tool chain's target, arch, tag and commands information\r
-\r
-      @return ToolChainInfo\r
+     \r
+      @return ToolChainInfo Tool chain information summary\r
      **/\r
     public ToolChainInfo getConfigInfo() {\r
         return info;\r
@@ -100,7 +106,7 @@ public class ToolChainConfig {
 \r
     /**\r
      override toString()\r
-\r
+     \r
      @return String The converted configuration string in name=value form\r
      **/\r
     public String toString() {\r
index 17c79c6..103b3a6 100644 (file)
@@ -1,5 +1,7 @@
 /** @file\r
-This file is to define  ToolChainElement class.\r
+ToolChainElement class\r
+\r
+ToolChainElement class is defining enumeration value of key part names.\r
 \r
 Copyright (c) 2006, Intel Corporation\r
 All rights reserved. This program and the accompanying materials\r
index 7bf9dd6..5fb15f3 100644 (file)
@@ -1,5 +1,7 @@
 /** @file\r
-This file is to define  ToolChainInfo class.\r
+ToolChainInfo class\r
+\r
+This file is to define ToolChainInfo class.\r
 \r
 Copyright (c) 2006, Intel Corporation\r
 All rights reserved. This program and the accompanying materials\r
@@ -18,6 +20,10 @@ import java.util.LinkedHashSet;
 import java.util.Map;\r
 import java.util.Set;\r
 \r
+/**\r
+   ToolChainInfo collects valid build targets, tool chain tag, ARCHs and commands \r
+   information for real build use.\r
+ **/\r
 public class ToolChainInfo {\r
     //\r
     // build target set\r
@@ -35,10 +41,7 @@ public class ToolChainInfo {
     // build commands set\r
     // \r
     private Set<String> commands = new LinkedHashSet<String>();\r
-    //\r
-    // build commands for specific tool chain\r
-    // \r
-    private Map<String, Set<String>> commandMap = new HashMap<String, Set<String>>();\r
+\r
     /**\r
      Add a list of targets in the form of string separated by space\r
 \r
@@ -48,134 +51,164 @@ public class ToolChainInfo {
         //\r
         // targetList some targets separated by space " "\r
         //\r
-        if (targetList == null) {\r
+        if (targetList == null || targetList.length() == 0) {\r
             targets.add("*");\r
-            return ;\r
+        } else {\r
+            addTargets(targetList.split(" "));\r
         }\r
-        addTargets(targetList.split(" "));\r
     }\r
+\r
     /**\r
      Add a list of targets in the form of string array\r
      \r
      @param targetArray target string array\r
      **/\r
     public void addTargets(String[] targetArray) {\r
-        if (targetArray == null ) {\r
-            return ;\r
-        }\r
-        for (int i = 0; i < targetArray.length; i++) {\r
-            targets.add(targetArray[i]);\r
+        if (targetArray != null ) {\r
+            for (int i = 0; i < targetArray.length; i++) {\r
+                targets.add(targetArray[i]);\r
+            }\r
         }\r
     }\r
+\r
     /**\r
      Add a list of target in the form of set\r
      \r
      @param targetSet target string set\r
      **/\r
     public void addTargets(Set<String> targetSet) {\r
-        targets.addAll(targetSet);\r
+        if (targetSet != null) {\r
+            targets.addAll(targetSet);\r
+        }\r
     }\r
+\r
     /**\r
        Add a list of tool chain tag name in the form of string separated by space\r
 \r
-       @param tagnameList\r
+       @param tagnameList   Tool chain tag name list string\r
      **/\r
     public void addTagnames(String tagnameList) {\r
         //\r
         // tagnameList some tagnames separated by space " "\r
         //\r
-        if (tagnameList == null) {\r
+        if (tagnameList == null || tagnameList.length() == 0) {\r
             tagnames.add("*");\r
-            return ;\r
+        } else {\r
+            addTagnames(tagnameList.split(" "));\r
         }\r
-        addTagnames(tagnameList.split(" "));\r
     }\r
-    \r
+\r
+    /**\r
+       Add a list of tool chain tag name in the form of string array\r
+       \r
+       @param tagnameArray  Tool chain tag names array\r
+     **/\r
     public void addTagnames(String[] tagnameArray) {\r
-        if (tagnameArray == null ) {\r
-            return ;\r
-        }\r
-        for (int i = 0; i < tagnameArray.length; i++) {\r
-            tagnames.add(tagnameArray[i]);\r
+        if (tagnameArray != null ) {\r
+            for (int i = 0; i < tagnameArray.length; i++) {\r
+                tagnames.add(tagnameArray[i]);\r
+            }\r
         }\r
     }\r
-    \r
+\r
+    /**\r
+       Add a list of tool chain tag name in the form of Set\r
+       \r
+       @param tagnameSet    Tool chain tag names set\r
+     **/\r
     public void addTagnames(Set<String> tagnameSet) {\r
-        tagnames.addAll(tagnameSet);\r
+        if (tagnameSet != null) {\r
+            tagnames.addAll(tagnameSet);\r
+        }\r
     }\r
-    \r
+\r
+    /**\r
+       Add a list of ARCH in the form of string\r
+       \r
+       @param archList  ARCH string\r
+     **/\r
     public void addArchs(String archList) {\r
         //\r
         // archList some archs separated by space " "\r
         //\r
-        if (archList == null) {\r
+        if (archList == null || archList.length() == 0) {\r
             archs.add("*");\r
-            return ;\r
+        } else {\r
+            addArchs(archList.split(" "));\r
         }\r
-        addArchs(archList.split(" "));\r
     }\r
-    \r
+\r
+    /**\r
+       Add a list of ARCH in the form of string array\r
+       \r
+       @param archArray ARCH array\r
+     **/\r
     public void addArchs(String[] archArray) {\r
-        if (archArray == null ) {\r
-            return ;\r
-        }\r
-        for (int i = 0; i < archArray.length; i++) {\r
-            archs.add(archArray[i]);\r
+        if (archArray != null ) {\r
+            for (int i = 0; i < archArray.length; i++) {\r
+                archs.add(archArray[i]);\r
+            }\r
         }\r
     }\r
-    \r
+\r
+    /**\r
+       Add a list of ARCH in the form of set\r
+       \r
+       @param archSet   ARCH set\r
+     **/\r
     public void addArchs(Set<String> archSet) {\r
-        archs.addAll(archSet);\r
+        if (archSet != null) {\r
+            archs.addAll(archSet);\r
+        }\r
     }\r
-    \r
-    public void addCommands(String toolChain, String commandList) {\r
+\r
+    /**\r
+       Add a list of command in the form of string\r
+       \r
+       @param commandList   Command list string\r
+     **/\r
+    public void addCommands(String commandList) {\r
         //\r
         // archList some archs separated by space " "\r
         //\r
         if (commandList == null || commandList.length() == 0) {\r
-            return ;\r
+            commands.add("*");\r
+        } else {\r
+            addCommands(commandList.split(" "));\r
         }\r
-        addCommands(commandList.split(" "));\r
     }\r
-    \r
+\r
+    /**\r
+       Add a list of ARCH in the form of array\r
+       \r
+       @param commandArray  Commands array\r
+     **/\r
     public void addCommands(String[] commandArray) {\r
-        if (commandArray == null ) {\r
-            return ;\r
-        }\r
-        for (int i = 0; i < commandArray.length; i++) {\r
-            commands.add(commandArray[i]);\r
+        if (commandArray != null ) {\r
+            for (int i = 0; i < commandArray.length; i++) {\r
+                commands.add(commandArray[i]);\r
+            }\r
         }\r
     }\r
-    \r
-    public void addCommands(String toolChain, String[] commandArray) {\r
-        if (commandArray == null) {\r
-            return ;\r
-        }\r
 \r
-        Set<String> toolChainCommandSet = commandMap.get(toolChain);\r
-        if (toolChainCommandSet == null) {\r
-            toolChainCommandSet = new LinkedHashSet<String>();\r
-            commandMap.put(toolChain, toolChainCommandSet);\r
-        }\r
-        for (int i = 0; i < commandArray.length; i++) {\r
-            commands.add(commandArray[i]);\r
-            toolChainCommandSet.add(commandArray[i]);\r
-        }\r
-    }\r
-    \r
-    public void addCommands(String toolChain, Set<String> commandSet) {\r
-        if (commandSet == null) {\r
-            return;\r
-        }\r
-        Set<String> toolChainCommandSet = commandMap.get(toolChain);\r
-        if (toolChainCommandSet == null) {\r
-            toolChainCommandSet = new LinkedHashSet<String>();\r
-            commandMap.put(toolChain, toolChainCommandSet);\r
+    /**\r
+       Add a list of ARCH in the form of set\r
+       \r
+       @param commandSet    Commands set\r
+     **/\r
+    public void addCommands(Set<String> commandSet) {\r
+        if (commandSet != null) {\r
+            commands.addAll(commandSet);\r
         }\r
-        commands.addAll(commandSet);\r
-        toolChainCommandSet.addAll(commandSet);\r
     }\r
-    \r
+\r
+    /**\r
+       Make a union operation on this ToolChainInfo and the given one.\r
+\r
+       @param info  Another ToolChainInfo object to merge with\r
+       \r
+       @return ToolChainInfo    Merged ToolChainInfo object\r
+     **/\r
     public ToolChainInfo union(ToolChainInfo info) {\r
         ToolChainInfo result = new ToolChainInfo();\r
         result.addTargets(union(this.targets, info.targets));\r
@@ -183,7 +216,14 @@ public class ToolChainInfo {
         result.addArchs(union(this.archs, info.archs));\r
         return result;\r
     }\r
-    \r
+\r
+    /**\r
+       Make a intersection operation on this ToolChainInfo and the given one\r
+\r
+       @param info  Another ToolChainInfo object to intersect with\r
+       \r
+       @return ToolChainInfo    Intersected ToolChainInfo object\r
+     **/\r
     public ToolChainInfo intersection(ToolChainInfo info) {\r
         ToolChainInfo result = new ToolChainInfo();\r
         result.addTargets(intersection(this.targets, info.targets));\r
@@ -191,7 +231,15 @@ public class ToolChainInfo {
         result.addArchs(intersection(this.archs, info.archs));\r
         return result;\r
     }\r
-    \r
+\r
+    /**\r
+       Make a union operation on two Sets\r
+\r
+       @param set1  One Set\r
+       @param set2  Another Set\r
+       \r
+       @return Set<String>  Merged Set object\r
+     **/\r
     private Set<String> union(Set<String> set1, Set<String> set2) {\r
         Set<String> result = new LinkedHashSet<String>();\r
         result.addAll(set1);\r
@@ -199,51 +247,96 @@ public class ToolChainInfo {
         result.remove("*");\r
         return result;\r
     }\r
-    \r
+\r
+    /**\r
+       Make a intersection operation on two Sets with the consideration of wildcard.\r
+\r
+       @param set1  One Set\r
+       @param set2  Another Set\r
+       \r
+       @return Set<String>  The intersected Set object\r
+     **/\r
     private Set<String> intersection(Set<String> set1, Set<String> set2) {\r
         Set<String> result = new LinkedHashSet<String>();\r
         boolean set1HasWildcard = set1.contains("*");\r
         boolean set2HasWildcard = set2.contains("*");\r
 \r
         if (set1HasWildcard && set2HasWildcard) {\r
+            //\r
+            // Both Sets have wildcard, the result will have all elements in them\r
+            // \r
             result.addAll(set1);\r
             result.addAll(set2);\r
         } else if (set1HasWildcard) {\r
+            //\r
+            // Only set1 has wildcard, then result will have only set2 elements.\r
+            // \r
             result.addAll(set2);\r
         } else if (set2HasWildcard) {\r
+            //\r
+            // Only set2 has wildcard, then result will have only set1 elements.\r
+            // \r
             result.addAll(set1);\r
         } else {\r
+            //\r
+            // No wildcard in both Sets, the result will have the elements in both Sets.\r
+            // \r
             result.addAll(set1);\r
             result.retainAll(set2);\r
         }\r
 \r
         return result;\r
     }\r
-    \r
+\r
+    /**\r
+       Get target array.\r
+\r
+       @return String[]\r
+     **/\r
     public String[] getTargets() {\r
         return (String[])targets.toArray(new String[targets.size()]);\r
     }\r
-    \r
+\r
+    /**\r
+       Get tool chain tag name array.\r
+\r
+       @return String[]\r
+     **/\r
     public String[] getTagnames() {\r
         return (String[])tagnames.toArray(new String[tagnames.size()]);\r
     }\r
-    \r
+\r
+    /**\r
+       Get ARCH array.\r
+\r
+       @return String[]\r
+     **/\r
     public String[] getArchs() {\r
         return (String[])archs.toArray(new String[archs.size()]);\r
     }\r
 \r
+    /**\r
+       Get command name array.\r
+\r
+       @return String[]\r
+     **/\r
     public String[] getCommands() {\r
         return (String[])commands.toArray(new String[commands.size()]);\r
     }\r
 \r
-    public Set<String> getCommands(String toolChain) {\r
-        return commandMap.get(toolChain);\r
-    }\r
-    \r
+    /**\r
+       Override the Object's toString().\r
+\r
+       @return String\r
+     **/\r
     public String toString() {\r
         return targets + "\n" + tagnames + "\n" + archs + "\n" + commands;\r
     }\r
-    \r
+\r
+    /**\r
+       Remove the wildcard element in the tool chain information because they\r
+       are useless when retrieved.\r
+     **/\r
     public void normalize() {\r
         targets.remove("*");\r
         tagnames.remove("*");\r
index f71fe3a..765d6f9 100644 (file)
@@ -1,4 +1,7 @@
-/*++\r
+/** @file\r
+ToolChainKey class\r
+\r
+ToolChainKey class is representing the "name" part of tool chain definition.\r
 \r
 Copyright (c) 2006, Intel Corporation\r
 All rights reserved. This program and the accompanying materials\r
@@ -9,36 +12,78 @@ http://opensource.org/licenses/bsd-license.php
 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
 \r
---*/\r
+**/\r
 \r
 package org.tianocore.build.toolchain;\r
 \r
 import org.tianocore.common.exception.EdkException;\r
 \r
+/**\r
+   ToolChainKey class is the java class form of the "name" of tool chain definition.\r
+   It's primarily for the key of a Map data structure.\r
+ **/\r
 public class ToolChainKey implements java.io.Serializable, Comparable<ToolChainKey> {\r
     static final long serialVersionUID = -8034897190740066933L;\r
-    private String delimiter = "_";\r
 \r
+    ///\r
+    /// The part number of key. Currently we only support fixed five parts.\r
+    /// \r
     public final static int keyLength = 5;\r
 \r
+    //\r
+    // Default delimiter which is used for concatenating the parts of key\r
+    // \r
+    private String delimiter = "_";\r
+\r
+    //\r
+    // Key value in string array form\r
+    // \r
     private String[] keySet = null;\r
 \r
+    //\r
+    // Key value in one string form\r
+    // \r
     private String keyString = null;\r
 \r
+    //\r
+    // Key hash value used for hash table \r
+    // \r
     private int hashValue = 0;\r
 \r
-    public ToolChainKey(String keyString, String delimiter) throws Exception {\r
+    /**\r
+       Public constructor which can override default delimiter.\r
+\r
+       @param keyString     The key string value\r
+       @param delimiter     Delimiter charater concatenating the key parts\r
+     **/\r
+    public ToolChainKey(String keyString, String delimiter) throws EdkException {\r
         setKey(keyString, delimiter);\r
     }\r
 \r
+    /**\r
+       Public constructor which uses default delimiter.\r
+\r
+       @param keyString     The key string value\r
+     **/\r
     public ToolChainKey(String keyString) throws EdkException {\r
         setKey(keyString);\r
     }\r
 \r
+    /**\r
+       Public constructor which doesn't use any delimiter.\r
+\r
+       @param keySet\r
+     **/\r
     public ToolChainKey(String[] keySet) throws EdkException {\r
         setKey(keySet);\r
     }\r
 \r
+    /**\r
+       Calculate hash value of the key string (without the delimiter). It's used\r
+       for Hash Table kind of Map.\r
+\r
+       @return int      The hash value\r
+     **/\r
     public int hashCode() {\r
         if (hashValue != 0) {\r
             return hashValue;\r
@@ -56,6 +101,15 @@ public class ToolChainKey implements java.io.Serializable, Comparable<ToolChainK
         return hashValue;\r
     }\r
 \r
+    /**\r
+       Compare the string value of two keys . It's used for Tree kind of Map.\r
+       \r
+       @param dstKey    Another key to compare to.\r
+       \r
+       @retval  0       Two keys are equal\r
+       @retval  >0      This key is after the given key\r
+       @retval  <0      This key is before the given key\r
+     **/\r
     public int compareTo(ToolChainKey dstKey) {\r
         String[] dstKeySet = dstKey.getKeySet();\r
         int result = 0;\r
@@ -69,6 +123,13 @@ public class ToolChainKey implements java.io.Serializable, Comparable<ToolChainK
         return result;\r
     }\r
 \r
+    /**\r
+       Check if this key is the same as the given key.\r
+\r
+       @param o     Another key to compare to\r
+       \r
+       @return boolean\r
+     **/\r
     public boolean equals(Object o) {\r
         ToolChainKey dstKey = (ToolChainKey)o;\r
         String[] dstKeySet = dstKey.getKeySet();\r
@@ -90,11 +151,19 @@ public class ToolChainKey implements java.io.Serializable, Comparable<ToolChainK
         return true;\r
     }\r
 \r
+    /**\r
+       Set the key value in form of string array.\r
+\r
+       @param keySet    The string array of key value\r
+     **/\r
     public void setKey(String[] keySet) throws EdkException {\r
         if (keySet.length != this.keyLength) {\r
             throw new EdkException("Invalid ToolChain key");\r
         }\r
 \r
+        //\r
+        // Clone the string array because we don't want to change original one\r
+        // \r
         this.keySet = new String[this.keyLength];\r
         System.arraycopy(keySet, 0, this.keySet, 0, this.keyLength);\r
         for (int i = 0; i < this.keyLength; ++i) {\r
@@ -102,23 +171,45 @@ public class ToolChainKey implements java.io.Serializable, Comparable<ToolChainK
                 this.keySet[i] = "*";\r
             }\r
         }\r
+\r
+        //\r
+        // We need to re-generate the single key string and hash value.\r
+        // \r
         this.keyString = null;\r
         this.hashValue = 0;\r
     }\r
 \r
+    /**\r
+       Set key value at the specified key part .\r
+       \r
+       @param keySetString      The new value of "index" part of key\r
+       @param index             The key part index\r
+     **/\r
     public void setKey(String keySetString, int index) throws EdkException {\r
         if (index >= this.keyLength) {\r
             throw new EdkException("Invalid ToolChain key index");\r
         }\r
 \r
+        //\r
+        // Allow wildcard in key string\r
+        // \r
         if (keySetString == null || keySetString.length() == 0) {\r
             keySetString = "*";\r
         }\r
         this.keySet[index] = keySetString;\r
+\r
+        //\r
+        // We need to re-generate the single key string and hash value.\r
+        // \r
         this.keyString = null;\r
         this.hashValue = 0;\r
     }\r
 \r
+    /**\r
+       Set key value in the form of single string.\r
+       \r
+       @param keyString     The key value string\r
+     **/\r
     public void setKey(String keyString) throws EdkException {\r
         this.keySet = keyString.split(this.delimiter);\r
 \r
@@ -127,32 +218,53 @@ public class ToolChainKey implements java.io.Serializable, Comparable<ToolChainK
         }\r
 \r
         this.keyString = keyString;\r
+        //\r
+        // We need to re-generate hash value.\r
+        // \r
         this.hashValue = 0;\r
     }\r
 \r
-    public void setKey(String keyString, String delimiter) throws Exception {\r
+    /**\r
+       Set key value in the form of single string with specified delimiter.\r
+       \r
+       @param keyString     The key value string\r
+       @param delimiter     The delimiter concatenating the key string\r
+     **/\r
+    public void setKey(String keyString, String delimiter) throws EdkException {\r
         this.keySet = keyString.split(delimiter);\r
 \r
         if (this.keySet.length != this.keyLength) {\r
-            throw new Exception("Invalid ToolChain key");\r
+            throw new EdkException("Invalid ToolChain key");\r
         }\r
 \r
         this.keyString = keyString;\r
         this.delimiter = delimiter;\r
+        //\r
+        // We need to re-generate hash value.\r
+        // \r
         this.hashValue = 0;\r
     }\r
 \r
+    /**\r
+       Return the string array form of key\r
+\r
+       @return String[]\r
+     **/\r
     public String[] getKeySet() {\r
         return keySet;\r
     }\r
 \r
+    /**\r
+       Return the single string form of key.\r
+\r
+       @return String\r
+     **/\r
     public String toString() {\r
         if (this.keyString == null) {\r
             StringBuffer keyStringBuf = new StringBuffer(64);\r
-            int i = 0;\r
 \r
-            keyStringBuf.append(this.keySet[i++]);\r
-            for (; i < this.keyLength; ++i) {\r
+            keyStringBuf.append(this.keySet[0]);\r
+            for (int i = 1; i < this.keyLength; ++i) {\r
                 keyStringBuf.append(this.delimiter);\r
                 keyStringBuf.append(this.keySet[i]);\r
             }\r
index 1bcaf0e..b9d24eb 100644 (file)
@@ -1,4 +1,7 @@
-/*++\r
+/** @file\r
+ToolChainMap class\r
+\r
+ToolChainMap class is used for storing tool chain configurations.\r
 \r
 Copyright (c) 2006, Intel Corporation\r
 All rights reserved. This program and the accompanying materials\r
@@ -9,7 +12,7 @@ http://opensource.org/licenses/bsd-license.php
 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
 \r
---*/\r
+**/\r
 \r
 package org.tianocore.build.toolchain;\r
 \r
@@ -17,16 +20,40 @@ import java.util.HashMap;
 import java.util.Map;\r
 import java.util.Set;\r
 \r
+/**\r
+ ToolChainMap is a wrapper class for a generic Map class which uses ToolChainKey\r
+ class as its key. It's used to store and retrieve tool chain configuration \r
+ information.\r
+ **/\r
 public class ToolChainMap {\r
-\r
+    //\r
+    // From which part of key can be used to match "*"\r
+    // \r
     private int matchLevel = ToolChainKey.keyLength - 2;\r
 \r
+    //\r
+    // A Map object in which tool chain configuration information will be stored\r
+    // \r
     private Map<ToolChainKey, String> map = null;\r
 \r
+    /**\r
+       Public constructor. It just initializes the private Map object.\r
+     **/\r
     public ToolChainMap() {\r
         this.map = new HashMap<ToolChainKey, String>();\r
     }\r
 \r
+    /**\r
+       Wrapper function for Map.put(). It's used when default delimiter of\r
+       ToolChainKey is not wanted and will be overrided by "delimiter" parameter.\r
+\r
+       @param key           Key string which is concatenated with "delimiter"\r
+       @param delimiter     The delimiter string in the key string\r
+       @param value         Value string associated with the "key"\r
+       \r
+       @retval String       The "value" string if the "key" is valid.\r
+       @retval null         if the "key" is invalid\r
+     **/\r
     public String put(String key, String delimiter, String value) {\r
         ToolChainKey toolChainKey;\r
 \r
@@ -38,6 +65,15 @@ public class ToolChainMap {
         return (String)map.put(toolChainKey, value);\r
     }\r
 \r
+    /**\r
+       Wrapper function for Map.put().\r
+\r
+       @param key           Key string which is concatenated with default "delimiter"\r
+       @param value         Value string associated with the "key"\r
+       \r
+       @retval String       The "value" string if the "key" is valid.\r
+       @retval null         if the "key" is invalid\r
+     **/\r
     public String put(String key, String value) {\r
         ToolChainKey toolChainKey;\r
 \r
@@ -49,6 +85,16 @@ public class ToolChainMap {
         return (String)map.put(toolChainKey, value);\r
     }\r
 \r
+    /**\r
+       Wrapper function for Map.put(). The key is given in the form of string\r
+       array.\r
+\r
+       @param key           Key string array\r
+       @param value         Value string associated with the "key"\r
+       \r
+       @retval String       The "value" string if the "key" is valid.\r
+       @retval null         if the "key" is invalid\r
+     **/\r
     public String put(String[] key, String value) {\r
         ToolChainKey toolChainKey;\r
 \r
@@ -60,10 +106,26 @@ public class ToolChainMap {
         return (String)map.put(toolChainKey, value);\r
     }\r
 \r
+    /**\r
+       Wrapper function for Map.put(). The key is given in ToolChainKey class.\r
+\r
+       @param key           ToolChainKey class\r
+       @param value         Value string associated with the "key"\r
+       \r
+       @retval String       The "value" string if the "key" is valid.\r
+       @retval null         if the "key" is invalid\r
+     **/\r
     public String put(ToolChainKey key, String value) {\r
         return (String)map.put(key, value);\r
     }\r
 \r
+    /**\r
+       Wrapper function for Map.get().\r
+\r
+       @param key           Key string which is concatenated with default "delimiter"\r
+       \r
+       @return String\r
+     **/\r
     public String get(String key) {\r
         ToolChainKey toolChainKey;\r
 \r
@@ -75,6 +137,15 @@ public class ToolChainMap {
         return get(toolChainKey);\r
     }\r
 \r
+    /**\r
+       Wrapper function for Map.get(). It's used when default delimiter of\r
+       ToolChainKey is not wanted and will be overrided by "delimiter" parameter.\r
+\r
+       @param key           Key string which is concatenated with "delimiter"\r
+       @param delimiter     The delimiter string in the key string\r
+       \r
+       @return String\r
+     **/\r
     public String get(String key, String delimiter) {\r
         ToolChainKey toolChainKey;\r
 \r
@@ -86,6 +157,14 @@ public class ToolChainMap {
         return get(toolChainKey);\r
     }\r
 \r
+    /**\r
+       Wrapper function for Map.get(). The key is given in the form of string\r
+       array.\r
+\r
+       @param key           Key string array\r
+       \r
+       @return String\r
+     **/\r
     public String get(String[] key) {\r
         ToolChainKey toolChainKey;\r
 \r
@@ -97,12 +176,30 @@ public class ToolChainMap {
         return get(toolChainKey);\r
     }\r
 \r
+    /**\r
+       Wrapper function for Map.get(). The key is given in ToolChainKey class.\r
+       All other form of get() method will eventually call this form of get. It\r
+       will do real job of finding the value associated with the given key. Most\r
+       of the job is to try to match the key with "wildcard".\r
+\r
+       @param key           ToolChainKey class\r
+       \r
+       @return String       The value associated with the key\r
+     **/\r
     public String get(ToolChainKey key) {\r
+        ///\r
+        /// First, we'll try to get the value through the exact given key\r
+        /// \r
         String result = map.get(key);\r
         if (result != null || map.containsKey(key)) {\r
             return result;\r
         }\r
 \r
+        ///\r
+        /// If nothing is found, then, we'll try all possible keys combined with\r
+        /// wildcard "*". In order not to change the original key value, we have\r
+        /// to clone one for later use. \r
+        /// \r
         String[] keySet = key.getKeySet();\r
         ToolChainKey tmpKey;\r
         try {\r
@@ -111,17 +208,68 @@ public class ToolChainMap {
             return null;\r
         }\r
 \r
+        ///\r
+        /// In the current tool chain definition format (in name/value pair), \r
+        /// there're five parts in the "name". The last part of the "name" must\r
+        /// not be "wildcard". So we should start combining "*" from the fourth part.\r
+        /// We'll try all the possible combinations until the value can be fetched.\r
+        ///  \r
+        /// The following code implements the logic which will try to use, for example,\r
+        /// following key parts combinations sequentially to get the value.\r
+        /// \r
+        /// TARGET_TOOLCHAIN_ARCH_TOOLCODE_ATTRIBUTE\r
+        /// TARGET_TOOLCHAIN_ARCH_*_ATTRIBUTE\r
+        /// TARGET_TOOLCHAIN_*_TOOLCODE_ATTRIBUTE\r
+        /// TARGET_TOOLCHAIN_*_*_ATTRIBUTE\r
+        /// TARGET_*_ARCH_TOOLCODE_ATTRIBUTE\r
+        /// TARGET_*_ARCH_*_ATTRIBUTE\r
+        /// TARGET_*_*_TOOLCODE_ATTRIBUTE\r
+        /// TARGET_*_*_*_ATTRIBUTE\r
+        /// *_TOOLCHAIN_ARCH_TOOLCODE_ATTRIBUTE\r
+        /// *_TOOLCHAIN_ARCH_*_ATTRIBUTE\r
+        /// *_TOOLCHAIN_*_TOOLCODE_ATTRIBUTE\r
+        /// *_TOOLCHAIN_*_*_ATTRIBUTE\r
+        /// *_*_ARCH_TOOLCODE_ATTRIBUTE\r
+        /// *_*_ARCH_*_ATTRIBUTE\r
+        /// *_*_*_TOOLCODE_ATTRIBUTE\r
+        /// *_*_*_*_ATTRIBUTE\r
+        /// \r
+\r
+        //\r
+        // level is used to control if all parts of "name" have been "wildcarded"\r
+        // \r
         int level = matchLevel;\r
         while (level >= 0) {\r
+            //\r
+            // tmplevel is used to control if all parts of "name" between first\r
+            // "*" and fourth name part have been "wildcarded".\r
+            // \r
             int tmpLevel = level;\r
             while (tmpLevel >= level) {\r
                 String[] tmpKeySet = tmpKey.getKeySet();\r
                 try {\r
                     if (!tmpKeySet[tmpLevel].equals("*")) {\r
+                        //\r
+                        // If "tmplevel" part is not "*", set it to "*".\r
+                        // For example, at first loop, the key will become\r
+                        // TARGET_TOOLCHAIN_ARCH_*_ATTRIBUTE, and at next loop,\r
+                        // become TARGET_TOOLCHAIN_*_ARCH_ATTRIBUTE\r
+                        // \r
                         tmpKey.setKey("*", tmpLevel);\r
+                        //\r
+                        // We'll try all possible combinations between current\r
+                        // part and the fourth part.\r
+                        // \r
                         tmpLevel = matchLevel;\r
                     } else {\r
+                        //\r
+                        // Restore original value of key if "*" at "tmplevel"\r
+                        // part of "name" has been checked\r
+                        // \r
                         tmpKey.setKey(keySet[tmpLevel], tmpLevel);\r
+                        //\r
+                        // Try "*" at part left to "tmplevel" part of "name"\r
+                        // \r
                         --tmpLevel;\r
                         continue;\r
                     }\r
@@ -129,23 +277,48 @@ public class ToolChainMap {
                     return null;\r
                 }\r
 \r
+                //\r
+                // Try get the value from the map\r
+                // \r
                 result = map.get(tmpKey);\r
                 if (result != null) {\r
+                    //\r
+                    // The map actually has no exact key as the given "key", \r
+                    // putting it back into map can speed up the get() next time\r
+                    // \r
                     map.put(key, result);\r
                     return result;\r
                 }\r
             }\r
+            ///\r
+            /// If all possible combinations of "wildcard" between "level" and \r
+            /// the fourth part of "name" have been tried, try the left part\r
+            /// \r
             --level;\r
         }\r
 \r
+        //\r
+        // The map actually has no exact key as the given "key", putting it back\r
+        // into map can speed up the get() next time even we got nothing.\r
+        // \r
         map.put(key, result);\r
         return result;\r
     }\r
 \r
+    /**\r
+       Wrapper function for Map.size().\r
+\r
+       @return int  The size of map\r
+     **/\r
     public int size() {\r
         return map.size();\r
     }\r
 \r
+    /**\r
+       Wrapper function for Map.keySet().\r
+\r
+       @return Set<ToolChainKey>    A set of ToolChainKey objects\r
+     */\r
     public Set<ToolChainKey> keySet() {\r
         return (Set<ToolChainKey>)map.keySet();\r
     }\r