Added comments and polished the code.

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

9 files changed, 611 insertions, 236 deletions

diff --git a/Tools/Source/GenBuild/org/tianocore/build/FrameworkBuildTask.java b/Tools/Source/GenBuild/org/tianocore/build/FrameworkBuildTask.java
index d236c5b..6cdbbe5 100644
--- a/Tools/Source/GenBuild/org/tianocore/build/FrameworkBuildTask.java
+++ b/Tools/Source/GenBuild/org/tianocore/build/FrameworkBuildTask.java
@@ -112,33 +112,38 @@ public class FrameworkBuildTask extends Task{
         //

         File buildFile = null;

         if (msaFiles.size() > 1) {

-            throw new BuildException("Having more than one MSA file in a directory is not allowed!");

-        } else if (msaFiles.size() == 1 && activePlatform == null) {

-            throw new BuildException("If trying to build a single module, please set ACTIVE_PLATFORM in file [Tool/Conf/target.txt]. ");

-        } else if (msaFiles.size() == 1 && activePlatform != null) {

+            throw new BuildException("More than one MSA file under current directory. It is not allowd. ");

+        }

+        else if (msaFiles.size() == 1 && activePlatform == null) {

+            throw new BuildException("If try to build a single module, please set ACTIVE_PLATFORM in file [Tool/Conf/target.txt]. ");

+        }

+        else if (msaFiles.size() == 1 && activePlatform != null) {

             //

             // Build the single module

             //

             buildFile = msaFiles.toArray(new File[1])[0];

-        } else if (activePlatform != null) {

+        }

+        else if (activePlatform != null) {

             buildFile = new File(GlobalData.getWorkspacePath() + File.separatorChar + activePlatform);

-        } else if (fpdFiles.size() == 1) {

+        }

+        else if (fpdFiles.size() == 1) {

             buildFile = fpdFiles.toArray(new File[1])[0];

-        } else if (fpdFiles.size() > 1) {

+        }

+        else if (fpdFiles.size() > 1) {

             buildFile = intercommuniteWithUser();

         }

         //

         // If there is no build files or FPD files or MSA files, stop build

         //

         else {

-            throw new BuildException("Can't find any FPD or MSA files in the current directory. ");

+            throw new BuildException("Can't find any FPD files or MSA files in current directory. ");

         }

 

         //

         // Build every FPD files (PLATFORM build)

         //

         if (buildFile.getName().endsWith(".fpd")) {

-            System.out.println("Processing the FPD file [" + buildFile.getPath() + "] ..>> ");

+            System.out.println("Start to build FPD file [" + buildFile.getPath() + "] ..>> ");

             FpdParserTask fpdParserTask = new FpdParserTask();

             fpdParserTask.setType(type);

             fpdParserTask.setProject(getProject());

@@ -151,8 +156,8 @@ public class FrameworkBuildTask extends Task{
         //

         else if (buildFile.getName().endsWith(".msa")) {

             File tmpFile = new File(GlobalData.getWorkspacePath() + File.separatorChar + activePlatform);

-            System.out.println("Using the FPD file [" + tmpFile.getPath() + "] for the active platform. ");

-            System.out.println("Processing the MSA file [" + buildFile.getPath() + "] ..>> ");

+            System.out.println("Using FPD file [" + tmpFile.getPath() + "] as active platform. ");

+            System.out.println("Start to build MSA file [" + buildFile.getPath() + "] ..>> ");

             GenBuildTask genBuildTask = new GenBuildTask();

             genBuildTask.setSingleModuleBuild(true);

             genBuildTask.setType(type);

@@ -186,22 +191,26 @@ public class FrameworkBuildTask extends Task{
 

     private File intercommuniteWithUser(){

         File file = null;

-        if (fpdFiles.size() > 1) {

-            File[] allFiles = new File[fpdFiles.size()];

+        if (fpdFiles.size() + msaFiles.size() > 1) {

+            File[] allFiles = new File[fpdFiles.size() + msaFiles.size()];

             int index = 0;

             Iterator<File> iter = fpdFiles.iterator();

             while (iter.hasNext()) {

                 allFiles[index] = iter.next();

                 index++;

             }

-

-            System.out.println("Finding " + allFiles.length + " FPD files: ");

+            iter = msaFiles.iterator();

+            while (iter.hasNext()) {

+                allFiles[index] = iter.next();

+                index++;

+            }

+            System.out.println("Find " + allFiles.length + " FPD and MSA files: ");

             for (int i = 0; i < allFiles.length; i++) {

                 System.out.println("[" + (i + 1) + "]: " + allFiles[i].getName());

             }

             

             boolean flag = true;

-            System.out.print("Please select one of the following FPD files to build:[1] ");

+            System.out.print("Please select one file to build:[1] ");

             do{

                 BufferedReader br = new BufferedReader(new InputStreamReader(System.in));

                 try {

@@ -225,9 +234,13 @@ public class FrameworkBuildTask extends Task{
                     flag = true;

                 }

             } while (flag);

-        } else if (fpdFiles.size() == 1) {

+        }

+        else if (fpdFiles.size() == 1) {

             file = fpdFiles.toArray(new File[1])[0];

         }

+        else if (msaFiles.size() == 1) {

+            file = msaFiles.toArray(new File[1])[0];

+        }

         return file;

     }

     

@@ -235,14 +248,17 @@ public class FrameworkBuildTask extends Task{
     public void setType(String type) {

         if (type.equalsIgnoreCase("clean") || type.equalsIgnoreCase("cleanall")) {

             this.type = type.toLowerCase();

-        } else {

+        }

+        else {

             this.type = "all";

         }

     }

     

     private void readTargetFile(){

         try {

-            String[][] targetFileInfo = ConfigReader.parse(getProject().getProperty("WORKSPACE_DIR"), "Tools" + File.separatorChar + "Conf" + File.separatorChar + targetFilename);

+            String targetFile = getProject().getProperty("WORKSPACE_DIR") + File.separatorChar 

+                + "Tools" + File.separatorChar + "Conf" + File.separatorChar + targetFilename;

+            String[][] targetFileInfo = ConfigReader.parse(targetFile);

             

             //

             // Get ToolChain Info from target.txt

@@ -251,19 +267,22 @@ public class FrameworkBuildTask extends Task{
             String str = getValue("TARGET", targetFileInfo);

             if (str == null || str.trim().equals("")) {

                 envToolChainInfo.addTargets("*");

-            } else {

+            }

+            else {

                 envToolChainInfo.addTargets(str);

             }

             str = getValue("TOOL_CHAIN_TAG", targetFileInfo);

             if (str == null || str.trim().equals("")) {

                 envToolChainInfo.addTagnames("*");

-            } else {

+            }

+            else {

                 envToolChainInfo.addTagnames(str);

             }

             str = getValue("TARGET_ARCH", targetFileInfo);

             if (str == null || str.trim().equals("")) {

                 envToolChainInfo.addArchs("*");

-            } else {

+            }

+            else {

                 envToolChainInfo.addArchs(str);

             }

             GlobalData.setToolChainEnvInfo(envToolChainInfo);

@@ -276,7 +295,7 @@ public class FrameworkBuildTask extends Task{
             str = getValue("ACTIVE_PLATFORM", targetFileInfo);

             if (str != null && ! str.trim().equals("")) {

                 if ( ! str.endsWith(".fpd")) {

-                    throw new BuildException("FPD file's extension must be \".fpd\"!");

+                    throw new BuildException("FPD file's file extension must be \".fpd\"");

                 }

                 activePlatform = str;

             }

diff --git a/Tools/Source/GenBuild/org/tianocore/build/global/GlobalData.java b/Tools/Source/GenBuild/org/tianocore/build/global/GlobalData.java
index 9778eaf..3a5d1dd 100644
--- a/Tools/Source/GenBuild/org/tianocore/build/global/GlobalData.java
+++ b/Tools/Source/GenBuild/org/tianocore/build/global/GlobalData.java
@@ -164,7 +164,11 @@ public class GlobalData {
         //

         File toolsDefFile = new File(workspaceDir + File.separatorChar + toolsDefFilename);

         System.out.println("Using tool definiton file [" + toolsDefFile.getPath() + "].");

-        toolsDef = new ToolChainConfig(toolsDefFile);

+        try {

+            toolsDef = new ToolChainConfig(toolsDefFile);

+        } catch (Exception e) {

+            throw new BuildException(e.getMessage());

+        }

 

         //

         // Parse Framework Database

diff --git a/Tools/Source/GenBuild/org/tianocore/build/toolchain/ConfigReader.java b/Tools/Source/GenBuild/org/tianocore/build/toolchain/ConfigReader.java
index 6e26ade..b6f58ce 100644
--- a/Tools/Source/GenBuild/org/tianocore/build/toolchain/ConfigReader.java
+++ b/Tools/Source/GenBuild/org/tianocore/build/toolchain/ConfigReader.java
@@ -1,8 +1,8 @@
 /** @file

   ConfigReader class.

-

-  ConfigReader is used to read tool chain config file with flat format.

-

+  

+  ConfigReader is used to read tool chain config file with flat format. 

+  

 Copyright (c) 2006, Intel Corporation

 All rights reserved. This program and the accompanying materials

 are licensed and made available under the terms and conditions of the BSD License

@@ -23,65 +23,65 @@ import java.util.ArrayList;
 import java.util.List;

 

 /**

-

+  

   ConfigReader is used to read tool chain config file with flat format. Comments

   is line starting with character '#'.

-

+  

   @since GenBuild 1.0

 **/

 public class ConfigReader {

 

-    private static String confPath = ".";

-

-

-    /**

-      Public construct method.

-    **/

-    public ConfigReader () {

-    }

-

     /**

-      Default filepath is ".".

+      Parse specified tool chain definition file.

+    

+      @param    filename    The config file name with full path

 

-      @param filename the config file name like "target.txt"

-      @return the variables defined in file

+      @return String[][]    The definition array

     **/

     public static synchronized String[][] parse(String filename) throws EdkException {

-        return parse(confPath, filename);

+        return parse(new File(filename));

     }

 

     /**

-      Get all variables defined in config file. the config file format is flat

-      with "A=B". If line started with '#' looks as comments.

-

-      @param confPath the path of config file

-      @param filename the file name of the config file

-      @return the variables defined in the config file

-      @throws BuildException

-              Config file's format is not valid

+      Get all definitions in config file. the config file format is flat

+      with "A=B". If line started with '#' looks as comments. 

+    

+      @param    configFile      The config file

+

+      @return   String[][]      The variables defined in the config file

+

+      @throws   EdkException

+                Config file's format is not valid

     **/

-    public static synchronized String[][] parse(String confPath, String filename) throws EdkException {

-        //Map<String, String> map = new TreeMap<String,String>(comparator);

+    public static synchronized String[][] parse(File configFile) throws EdkException {

         List<String> keyList = new ArrayList<String>(256);

         List<String> valueList = new ArrayList<String>(256);

+        int lines = 0;

 

         try {

-            File file = new File(confPath + File.separatorChar + filename);

-            FileReader reader = new FileReader(file);

+            FileReader reader = new FileReader(configFile);

             BufferedReader in = new BufferedReader(reader);

             String str;

 

             while ((str = in.readLine()) != null) {

+                ++lines;

                 str = str.trim();

                 //

-                // if str is empty line, comments (start with '#'),

-                // without '=', or start with '='

+                // skip empty line, comment (start with '#') 

                 //

-                int index;

-                if (str.length() == 0 || str.startsWith("#") ||

-                    (index = str.indexOf('=')) <= 0) {

+                if (str.length() == 0 || str.startsWith("#")) {

                     continue;

                 }

+

+                //

+                // stop if the definition line is not in "name=value" form

+                // 

+                int index;

+                if ((index = str.indexOf('=')) <= 0) {

+                    throw new EdkException("ERROR Processing file [" + configFile.getAbsolutePath() 

+                        + "] (line " + lines + ").\n");

+                }

+

                 //

                 // look as line "A = B"

                 //

@@ -89,7 +89,8 @@ public class ConfigReader {
                 valueList.add(str.substring(index + 1).trim());

             }

         } catch (Exception e) {

-            throw new EdkException("ERROR Processing file [" + filename + "].\n" + e.getMessage());

+            throw new EdkException("ERROR Processing file [" + configFile.getAbsolutePath() 

+                + "] (line " + lines + ").\n" + e.getMessage());

         }

 

         String[][] definitions = new String[2][keyList.size()];

@@ -98,39 +99,6 @@ public class ConfigReader {
 

         return definitions;

     }

-

-    public static synchronized ToolChainMap parseToolChainConfig(File ConfigFile) throws EdkException {

-        ToolChainMap map = new ToolChainMap();

-

-        try {

-            FileReader reader = new FileReader(ConfigFile);

-            BufferedReader in = new BufferedReader(reader);

-            String str;

-

-            while ((str = in.readLine()) != null) {

-                str = str.trim();

-                //

-                // if str is empty line, comments (start with '#'),

-                // without '=', or start with '='

-                //

-                int index;

-                if (str.length() == 0 || str.startsWith("#") ||

-                    (index = str.indexOf('=')) <= 0) {

-                    continue;

-                }

-                //

-                // look as line "A = B"

-                //

-                String key = str.substring(0, index).trim().toUpperCase();

-                String value = str.substring(index + 1).trim();

-                map.put(key, value);

-            }

-        } catch (Exception e) {

-            throw new EdkException("ERROR Processing file [" + ConfigFile.getAbsolutePath() + "].\n" + e.getMessage());

-        }

-

-        return map;

-    }

 }

 

 

diff --git a/Tools/Source/GenBuild/org/tianocore/build/toolchain/ToolChainAttribute.java b/Tools/Source/GenBuild/org/tianocore/build/toolchain/ToolChainAttribute.java
index fad10da..491d37c 100644
--- a/Tools/Source/GenBuild/org/tianocore/build/toolchain/ToolChainAttribute.java
+++ b/Tools/Source/GenBuild/org/tianocore/build/toolchain/ToolChainAttribute.java
@@ -1,5 +1,7 @@
 /** @file

-This file is to define  ToolChainAttribute class.

+ToolChainAttribute class

+

+This file is to define enumeration value for tool chain attribute names.

 

 Copyright (c) 2006, Intel Corporation

 All rights reserved. This program and the accompanying materials

@@ -22,9 +24,9 @@ package org.tianocore.build.toolchain;
 public class ToolChainAttribute {

     private static int nextValue = 0;

 

-    //

-    // "NAME", "PATH", "DPATH", "SPATH", "EXT", "FAMILY", "FLAGS"

-    // 

+    ///

+    /// "NAME", "PATH", "DPATH", "SPATH", "EXT", "FAMILY", "FLAGS"

+    /// 

     public final static ToolChainAttribute NAME = new ToolChainAttribute("NAME");

     public final static ToolChainAttribute PATH = new ToolChainAttribute("PATH");

     public final static ToolChainAttribute DPATH = new ToolChainAttribute("DPATH");

@@ -48,7 +50,3 @@ public class ToolChainAttribute {
     }

 }

 

-

-

-

-

diff --git a/Tools/Source/GenBuild/org/tianocore/build/toolchain/ToolChainConfig.java b/Tools/Source/GenBuild/org/tianocore/build/toolchain/ToolChainConfig.java
index 4082c6d..73e6615 100644
--- a/Tools/Source/GenBuild/org/tianocore/build/toolchain/ToolChainConfig.java
+++ b/Tools/Source/GenBuild/org/tianocore/build/toolchain/ToolChainConfig.java
@@ -1,8 +1,8 @@
 /** @file

   ToolChainConfig class.

-

-  ToolChainFactory class parse all config files and get tool chain information.

-

+  

+  ToolChainConfig class parse all config files and get tool chain information.

+  

 Copyright (c) 2006, Intel Corporation

 All rights reserved. This program and the accompanying materials

 are licensed and made available under the terms and conditions of the BSD License

@@ -15,8 +15,6 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
 **/

 package org.tianocore.build.toolchain;

 

-import org.apache.tools.ant.BuildException;

-

 import org.tianocore.common.exception.EdkException;

 import org.tianocore.build.toolchain.ToolChainKey;

 import org.tianocore.build.toolchain.ToolChainMap;

@@ -27,45 +25,53 @@ import java.util.Set;
 

 

 /**

-

-  ToolChainFactory class parse all config files and get tool chain information.

-

+ 

+  ToolChainConfig class parse all config files and get tool chain information.

+  

  **/

 public class ToolChainConfig {

-    ///

-    /// tool chain definitions

-    ///

+    //

+    // tool chain definitions

+    //

     private ToolChainMap config = null;

-    ///

-    /// tool chain information (how many targets, archs, etc.)

-    ///

+    //

+    // tool chain information (how many targets, archs, etc.)

+    // 

     private ToolChainInfo info = new ToolChainInfo();

 

     /**

       Public construct method.

-     **/

-    public ToolChainConfig () {

+      

+      @param toolChainFile File object representing the tool chain configuration file

+    **/

+    public ToolChainConfig (File toolChainFile) throws EdkException {

+        config = getToolChainConfig(toolChainFile);

+        parseToolChainDefKey(config.keySet());

     }

 

     /**

-      Public construct method.

+       Read tool chain definitions from specified file and put them in 

+       ToolChainMap class.

 

-      @param toolChainFile File object representing the tool chain configuration file

-    **/

-    public ToolChainConfig (File toolChainFile) {

-        try {

-            config = ConfigReader.parseToolChainConfig(toolChainFile);

-            parseToolChainDefKey(config.keySet());

-        }

-        catch (EdkException ex) {

-            throw new BuildException(ex.getMessage());

+       @param ConfigFile    The file containing tool chain definitions

+       

+       @return ToolChainMap

+     **/

+    private ToolChainMap getToolChainConfig(File ConfigFile) throws EdkException {

+        ToolChainMap map = new ToolChainMap();

+        String[][] toolChainDef = ConfigReader.parse(ConfigFile);

+    

+        for (int i = 0; i < toolChainDef[0].length; ++i) {

+            map.put(toolChainDef[0][i], toolChainDef[1][i]);

         }

+

+        return map;

     }

 

     /**

      Collect target, tool chain tag, arch and command information from key part

      of configuration

-

+      

      @param toolChainDefKey The set of keys in tool chain configuration

      **/

     private void parseToolChainDefKey (Set<ToolChainKey> toolChainDefKey) {

@@ -73,16 +79,16 @@ public class ToolChainConfig {
         while (it.hasNext()) {

             ToolChainKey key = (ToolChainKey)it.next();

             String[] keySet = key.getKeySet();

-            info.addTargets(keySet[0]);

-            info.addTagnames(keySet[1]);

-            info.addArchs(keySet[2]);

-            info.addCommands(keySet[1], keySet[3]);

+            info.addTargets(keySet[ToolChainElement.TARGET.value]);

+            info.addTagnames(keySet[ToolChainElement.TOOLCHAIN.value]);

+            info.addArchs(keySet[ToolChainElement.ARCH.value]);

+            info.addCommands(keySet[ToolChainElement.TOOLCODE.value]);

         }

     }

 

     /**

-     Return the tool chain configuration information in a Map form

-

+     Return the tool chain configuration information in a Map form 

+      

      @return ToolChainMap Tool chain configurations in a ToolChainMap

      **/

     public ToolChainMap getConfig() {

@@ -91,8 +97,8 @@ public class ToolChainConfig {
 

     /**

      Return the tool chain's target, arch, tag and commands information

-

-      @return ToolChainInfo

+     

+      @return ToolChainInfo Tool chain information summary

      **/

     public ToolChainInfo getConfigInfo() {

         return info;

@@ -100,7 +106,7 @@ public class ToolChainConfig {
 

     /**

      override toString()

-

+     

      @return String The converted configuration string in name=value form

      **/

     public String toString() {

diff --git a/Tools/Source/GenBuild/org/tianocore/build/toolchain/ToolChainElement.java b/Tools/Source/GenBuild/org/tianocore/build/toolchain/ToolChainElement.java
index 17c79c6..103b3a6 100644
--- a/Tools/Source/GenBuild/org/tianocore/build/toolchain/ToolChainElement.java
+++ b/Tools/Source/GenBuild/org/tianocore/build/toolchain/ToolChainElement.java
@@ -1,5 +1,7 @@
 /** @file

-This file is to define  ToolChainElement class.

+ToolChainElement class

+

+ToolChainElement class is defining enumeration value of key part names.

 

 Copyright (c) 2006, Intel Corporation

 All rights reserved. This program and the accompanying materials

diff --git a/Tools/Source/GenBuild/org/tianocore/build/toolchain/ToolChainInfo.java b/Tools/Source/GenBuild/org/tianocore/build/toolchain/ToolChainInfo.java
index 7bf9dd6..5fb15f3 100644
--- a/Tools/Source/GenBuild/org/tianocore/build/toolchain/ToolChainInfo.java
+++ b/Tools/Source/GenBuild/org/tianocore/build/toolchain/ToolChainInfo.java
@@ -1,5 +1,7 @@
 /** @file

-This file is to define  ToolChainInfo class.

+ToolChainInfo class

+

+This file is to define ToolChainInfo class.

 

 Copyright (c) 2006, Intel Corporation

 All rights reserved. This program and the accompanying materials

@@ -18,6 +20,10 @@ import java.util.LinkedHashSet;
 import java.util.Map;

 import java.util.Set;

 

+/**

+   ToolChainInfo collects valid build targets, tool chain tag, ARCHs and commands 

+   information for real build use.

+ **/

 public class ToolChainInfo {

     //

     // build target set

@@ -35,10 +41,7 @@ public class ToolChainInfo {
     // build commands set

     // 

     private Set<String> commands = new LinkedHashSet<String>();

-    //

-    // build commands for specific tool chain

-    // 

-    private Map<String, Set<String>> commandMap = new HashMap<String, Set<String>>();

+

     /**

      Add a list of targets in the form of string separated by space

 

@@ -48,134 +51,164 @@ public class ToolChainInfo {
         //

         // targetList some targets separated by space " "

         //

-        if (targetList == null) {

+        if (targetList == null || targetList.length() == 0) {

             targets.add("*");

-            return ;

+        } else {

+            addTargets(targetList.split(" "));

         }

-        addTargets(targetList.split(" "));

     }

+

     /**

      Add a list of targets in the form of string array

      

      @param targetArray target string array

      **/

     public void addTargets(String[] targetArray) {

-        if (targetArray == null ) {

-            return ;

-        }

-        for (int i = 0; i < targetArray.length; i++) {

-            targets.add(targetArray[i]);

+        if (targetArray != null ) {

+            for (int i = 0; i < targetArray.length; i++) {

+                targets.add(targetArray[i]);

+            }

         }

     }

+

     /**

      Add a list of target in the form of set

      

      @param targetSet target string set

      **/

     public void addTargets(Set<String> targetSet) {

-        targets.addAll(targetSet);

+        if (targetSet != null) {

+            targets.addAll(targetSet);

+        }

     }

+

     /**

        Add a list of tool chain tag name in the form of string separated by space

 

-       @param tagnameList

+       @param tagnameList   Tool chain tag name list string

      **/

     public void addTagnames(String tagnameList) {

         //

         // tagnameList some tagnames separated by space " "

         //

-        if (tagnameList == null) {

+        if (tagnameList == null || tagnameList.length() == 0) {

             tagnames.add("*");

-            return ;

+        } else {

+            addTagnames(tagnameList.split(" "));

         }

-        addTagnames(tagnameList.split(" "));

     }

-    

+

+    /**

+       Add a list of tool chain tag name in the form of string array

+       

+       @param tagnameArray  Tool chain tag names array

+     **/

     public void addTagnames(String[] tagnameArray) {

-        if (tagnameArray == null ) {

-            return ;

-        }

-        for (int i = 0; i < tagnameArray.length; i++) {

-            tagnames.add(tagnameArray[i]);

+        if (tagnameArray != null ) {

+            for (int i = 0; i < tagnameArray.length; i++) {

+                tagnames.add(tagnameArray[i]);

+            }

         }

     }

-    

+

+    /**

+       Add a list of tool chain tag name in the form of Set

+       

+       @param tagnameSet    Tool chain tag names set

+     **/

     public void addTagnames(Set<String> tagnameSet) {

-        tagnames.addAll(tagnameSet);

+        if (tagnameSet != null) {

+            tagnames.addAll(tagnameSet);

+        }

     }

-    

+

+    /**

+       Add a list of ARCH in the form of string

+       

+       @param archList  ARCH string

+     **/

     public void addArchs(String archList) {

         //

         // archList some archs separated by space " "

         //

-        if (archList == null) {

+        if (archList == null || archList.length() == 0) {

             archs.add("*");

-            return ;

+        } else {

+            addArchs(archList.split(" "));

         }

-        addArchs(archList.split(" "));

     }

-    

+

+    /**

+       Add a list of ARCH in the form of string array

+       

+       @param archArray ARCH array

+     **/

     public void addArchs(String[] archArray) {

-        if (archArray == null ) {

-            return ;

-        }

-        for (int i = 0; i < archArray.length; i++) {

-            archs.add(archArray[i]);

+        if (archArray != null ) {

+            for (int i = 0; i < archArray.length; i++) {

+                archs.add(archArray[i]);

+            }

         }

     }

-    

+

+    /**

+       Add a list of ARCH in the form of set

+       

+       @param archSet   ARCH set

+     **/

     public void addArchs(Set<String> archSet) {

-        archs.addAll(archSet);

+        if (archSet != null) {

+            archs.addAll(archSet);

+        }

     }

-    

-    public void addCommands(String toolChain, String commandList) {

+

+    /**

+       Add a list of command in the form of string

+       

+       @param commandList   Command list string

+     **/

+    public void addCommands(String commandList) {

         //

         // archList some archs separated by space " "

         //

         if (commandList == null || commandList.length() == 0) {

-            return ;

+            commands.add("*");

+        } else {

+            addCommands(commandList.split(" "));

         }

-        addCommands(commandList.split(" "));

     }

-    

+

+    /**

+       Add a list of ARCH in the form of array

+       

+       @param commandArray  Commands array

+     **/

     public void addCommands(String[] commandArray) {

-        if (commandArray == null ) {

-            return ;

-        }

-        for (int i = 0; i < commandArray.length; i++) {

-            commands.add(commandArray[i]);

+        if (commandArray != null ) {

+            for (int i = 0; i < commandArray.length; i++) {

+                commands.add(commandArray[i]);

+            }

         }

     }

-    

-    public void addCommands(String toolChain, String[] commandArray) {

-        if (commandArray == null) {

-            return ;

-        }

 

-        Set<String> toolChainCommandSet = commandMap.get(toolChain);

-        if (toolChainCommandSet == null) {

-            toolChainCommandSet = new LinkedHashSet<String>();

-            commandMap.put(toolChain, toolChainCommandSet);

-        }

-        for (int i = 0; i < commandArray.length; i++) {

-            commands.add(commandArray[i]);

-            toolChainCommandSet.add(commandArray[i]);

-        }

-    }

-    

-    public void addCommands(String toolChain, Set<String> commandSet) {

-        if (commandSet == null) {

-            return;

-        }

-        Set<String> toolChainCommandSet = commandMap.get(toolChain);

-        if (toolChainCommandSet == null) {

-            toolChainCommandSet = new LinkedHashSet<String>();

-            commandMap.put(toolChain, toolChainCommandSet);

+    /**

+       Add a list of ARCH in the form of set

+       

+       @param commandSet    Commands set

+     **/

+    public void addCommands(Set<String> commandSet) {

+        if (commandSet != null) {

+            commands.addAll(commandSet);

         }

-        commands.addAll(commandSet);

-        toolChainCommandSet.addAll(commandSet);

     }

-    

+

+    /**

+       Make a union operation on this ToolChainInfo and the given one.

+

+       @param info  Another ToolChainInfo object to merge with

+       

+       @return ToolChainInfo    Merged ToolChainInfo object

+     **/

     public ToolChainInfo union(ToolChainInfo info) {

         ToolChainInfo result = new ToolChainInfo();

         result.addTargets(union(this.targets, info.targets));

@@ -183,7 +216,14 @@ public class ToolChainInfo {
         result.addArchs(union(this.archs, info.archs));

         return result;

     }

-    

+

+    /**

+       Make a intersection operation on this ToolChainInfo and the given one

+

+       @param info  Another ToolChainInfo object to intersect with

+       

+       @return ToolChainInfo    Intersected ToolChainInfo object

+     **/

     public ToolChainInfo intersection(ToolChainInfo info) {

         ToolChainInfo result = new ToolChainInfo();

         result.addTargets(intersection(this.targets, info.targets));

@@ -191,7 +231,15 @@ public class ToolChainInfo {
         result.addArchs(intersection(this.archs, info.archs));

         return result;

     }

-    

+

+    /**

+       Make a union operation on two Sets

+

+       @param set1  One Set

+       @param set2  Another Set

+       

+       @return Set<String>  Merged Set object

+     **/

     private Set<String> union(Set<String> set1, Set<String> set2) {

         Set<String> result = new LinkedHashSet<String>();

         result.addAll(set1);

@@ -199,51 +247,96 @@ public class ToolChainInfo {
         result.remove("*");

         return result;

     }

-    

+

+    /**

+       Make a intersection operation on two Sets with the consideration of wildcard.

+

+       @param set1  One Set

+       @param set2  Another Set

+       

+       @return Set<String>  The intersected Set object

+     **/

     private Set<String> intersection(Set<String> set1, Set<String> set2) {

         Set<String> result = new LinkedHashSet<String>();

         boolean set1HasWildcard = set1.contains("*");

         boolean set2HasWildcard = set2.contains("*");

 

         if (set1HasWildcard && set2HasWildcard) {

+            //

+            // Both Sets have wildcard, the result will have all elements in them

+            // 

             result.addAll(set1);

             result.addAll(set2);

         } else if (set1HasWildcard) {

+            //

+            // Only set1 has wildcard, then result will have only set2 elements.

+            // 

             result.addAll(set2);

         } else if (set2HasWildcard) {

+            //

+            // Only set2 has wildcard, then result will have only set1 elements.

+            // 

             result.addAll(set1);

         } else {

+            //

+            // No wildcard in both Sets, the result will have the elements in both Sets.

+            // 

             result.addAll(set1);

             result.retainAll(set2);

         }

 

         return result;

     }

-    

+

+    /**

+       Get target array.

+

+       @return String[]

+     **/

     public String[] getTargets() {

         return (String[])targets.toArray(new String[targets.size()]);

     }

-    

+

+    /**

+       Get tool chain tag name array.

+

+       @return String[]

+     **/

     public String[] getTagnames() {

         return (String[])tagnames.toArray(new String[tagnames.size()]);

     }

-    

+

+    /**

+       Get ARCH array.

+

+       @return String[]

+     **/

     public String[] getArchs() {

         return (String[])archs.toArray(new String[archs.size()]);

     }

 

+    /**

+       Get command name array.

+

+       @return String[]

+     **/

     public String[] getCommands() {

         return (String[])commands.toArray(new String[commands.size()]);

     }

 

-    public Set<String> getCommands(String toolChain) {

-        return commandMap.get(toolChain);

-    }

-    

+    /**

+       Override the Object's toString().

+

+       @return String

+     **/

     public String toString() {

         return targets + "\n" + tagnames + "\n" + archs + "\n" + commands;

     }

-    

+

+    /**

+       Remove the wildcard element in the tool chain information because they

+       are useless when retrieved.

+     **/

     public void normalize() {

         targets.remove("*");

         tagnames.remove("*");

diff --git a/Tools/Source/GenBuild/org/tianocore/build/toolchain/ToolChainKey.java b/Tools/Source/GenBuild/org/tianocore/build/toolchain/ToolChainKey.java
index f71fe3a..765d6f9 100644
--- a/Tools/Source/GenBuild/org/tianocore/build/toolchain/ToolChainKey.java
+++ b/Tools/Source/GenBuild/org/tianocore/build/toolchain/ToolChainKey.java
@@ -1,4 +1,7 @@
-/*++

+/** @file

+ToolChainKey class

+

+ToolChainKey class is representing the "name" part of tool chain definition.

 

 Copyright (c) 2006, Intel Corporation

 All rights reserved. This program and the accompanying materials

@@ -9,36 +12,78 @@ http://opensource.org/licenses/bsd-license.php
 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,

 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.

 

---*/

+**/

 

 package org.tianocore.build.toolchain;

 

 import org.tianocore.common.exception.EdkException;

 

+/**

+   ToolChainKey class is the java class form of the "name" of tool chain definition.

+   It's primarily for the key of a Map data structure.

+ **/

 public class ToolChainKey implements java.io.Serializable, Comparable<ToolChainKey> {

     static final long serialVersionUID = -8034897190740066933L;

-    private String delimiter = "_";

 

+    ///

+    /// The part number of key. Currently we only support fixed five parts.

+    /// 

     public final static int keyLength = 5;

 

+    //

+    // Default delimiter which is used for concatenating the parts of key

+    // 

+    private String delimiter = "_";

+

+    //

+    // Key value in string array form

+    // 

     private String[] keySet = null;

 

+    //

+    // Key value in one string form

+    // 

     private String keyString = null;

 

+    //

+    // Key hash value used for hash table 

+    // 

     private int hashValue = 0;

 

-    public ToolChainKey(String keyString, String delimiter) throws Exception {

+    /**

+       Public constructor which can override default delimiter.

+

+       @param keyString     The key string value

+       @param delimiter     Delimiter charater concatenating the key parts

+     **/

+    public ToolChainKey(String keyString, String delimiter) throws EdkException {

         setKey(keyString, delimiter);

     }

 

+    /**

+       Public constructor which uses default delimiter.

+

+       @param keyString     The key string value

+     **/

     public ToolChainKey(String keyString) throws EdkException {

         setKey(keyString);

     }

 

+    /**

+       Public constructor which doesn't use any delimiter.

+

+       @param keySet

+     **/

     public ToolChainKey(String[] keySet) throws EdkException {

         setKey(keySet);

     }

 

+    /**

+       Calculate hash value of the key string (without the delimiter). It's used

+       for Hash Table kind of Map.

+

+       @return int      The hash value

+     **/

     public int hashCode() {

         if (hashValue != 0) {

             return hashValue;

@@ -56,6 +101,15 @@ public class ToolChainKey implements java.io.Serializable, Comparable<ToolChainK
         return hashValue;

     }

 

+    /**

+       Compare the string value of two keys . It's used for Tree kind of Map.

+       

+       @param dstKey    Another key to compare to.

+       

+       @retval  0       Two keys are equal

+       @retval  >0      This key is after the given key

+       @retval  <0      This key is before the given key

+     **/

     public int compareTo(ToolChainKey dstKey) {

         String[] dstKeySet = dstKey.getKeySet();

         int result = 0;

@@ -69,6 +123,13 @@ public class ToolChainKey implements java.io.Serializable, Comparable<ToolChainK
         return result;

     }

 

+    /**

+       Check if this key is the same as the given key.

+

+       @param o     Another key to compare to

+       

+       @return boolean

+     **/

     public boolean equals(Object o) {

         ToolChainKey dstKey = (ToolChainKey)o;

         String[] dstKeySet = dstKey.getKeySet();

@@ -90,11 +151,19 @@ public class ToolChainKey implements java.io.Serializable, Comparable<ToolChainK
         return true;

     }

 

+    /**

+       Set the key value in form of string array.

+

+       @param keySet    The string array of key value

+     **/

     public void setKey(String[] keySet) throws EdkException {

         if (keySet.length != this.keyLength) {

             throw new EdkException("Invalid ToolChain key");

         }

 

+        //

+        // Clone the string array because we don't want to change original one

+        // 

         this.keySet = new String[this.keyLength];

         System.arraycopy(keySet, 0, this.keySet, 0, this.keyLength);

         for (int i = 0; i < this.keyLength; ++i) {

@@ -102,23 +171,45 @@ public class ToolChainKey implements java.io.Serializable, Comparable<ToolChainK
                 this.keySet[i] = "*";

             }

         }

+

+        //

+        // We need to re-generate the single key string and hash value.

+        // 

         this.keyString = null;

         this.hashValue = 0;

     }

 

+    /**

+       Set key value at the specified key part .

+       

+       @param keySetString      The new value of "index" part of key

+       @param index             The key part index

+     **/

     public void setKey(String keySetString, int index) throws EdkException {

         if (index >= this.keyLength) {

             throw new EdkException("Invalid ToolChain key index");

         }

 

+        //

+        // Allow wildcard in key string

+        // 

         if (keySetString == null || keySetString.length() == 0) {

             keySetString = "*";

         }

         this.keySet[index] = keySetString;

+

+        //

+        // We need to re-generate the single key string and hash value.

+        // 

         this.keyString = null;

         this.hashValue = 0;

     }

 

+    /**

+       Set key value in the form of single string.

+       

+       @param keyString     The key value string

+     **/

     public void setKey(String keyString) throws EdkException {

         this.keySet = keyString.split(this.delimiter);

 

@@ -127,32 +218,53 @@ public class ToolChainKey implements java.io.Serializable, Comparable<ToolChainK
         }

 

         this.keyString = keyString;

+        //

+        // We need to re-generate hash value.

+        // 

         this.hashValue = 0;

     }

 

-    public void setKey(String keyString, String delimiter) throws Exception {

+    /**

+       Set key value in the form of single string with specified delimiter.

+       

+       @param keyString     The key value string

+       @param delimiter     The delimiter concatenating the key string

+     **/

+    public void setKey(String keyString, String delimiter) throws EdkException {

         this.keySet = keyString.split(delimiter);

 

         if (this.keySet.length != this.keyLength) {

-            throw new Exception("Invalid ToolChain key");

+            throw new EdkException("Invalid ToolChain key");

         }

 

         this.keyString = keyString;

         this.delimiter = delimiter;

+        //

+        // We need to re-generate hash value.

+        // 

         this.hashValue = 0;

     }

 

+    /**

+       Return the string array form of key

+

+       @return String[]

+     **/

     public String[] getKeySet() {

         return keySet;

     }

 

+    /**

+       Return the single string form of key.

+

+       @return String

+     **/

     public String toString() {

         if (this.keyString == null) {

             StringBuffer keyStringBuf = new StringBuffer(64);

-            int i = 0;

 

-            keyStringBuf.append(this.keySet[i++]);

-            for (; i < this.keyLength; ++i) {

+            keyStringBuf.append(this.keySet[0]);

+            for (int i = 1; i < this.keyLength; ++i) {

                 keyStringBuf.append(this.delimiter);

                 keyStringBuf.append(this.keySet[i]);

             }

diff --git a/Tools/Source/GenBuild/org/tianocore/build/toolchain/ToolChainMap.java b/Tools/Source/GenBuild/org/tianocore/build/toolchain/ToolChainMap.java
index 1bcaf0e..b9d24eb 100644
--- a/Tools/Source/GenBuild/org/tianocore/build/toolchain/ToolChainMap.java
+++ b/Tools/Source/GenBuild/org/tianocore/build/toolchain/ToolChainMap.java
@@ -1,4 +1,7 @@
-/*++

+/** @file

+ToolChainMap class

+

+ToolChainMap class is used for storing tool chain configurations.

 

 Copyright (c) 2006, Intel Corporation

 All rights reserved. This program and the accompanying materials

@@ -9,7 +12,7 @@ http://opensource.org/licenses/bsd-license.php
 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,

 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.

 

---*/

+**/

 

 package org.tianocore.build.toolchain;

 

@@ -17,16 +20,40 @@ import java.util.HashMap;
 import java.util.Map;

 import java.util.Set;

 

+/**

+ ToolChainMap is a wrapper class for a generic Map class which uses ToolChainKey

+ class as its key. It's used to store and retrieve tool chain configuration 

+ information.

+ **/

 public class ToolChainMap {

-

+    //

+    // From which part of key can be used to match "*"

+    // 

     private int matchLevel = ToolChainKey.keyLength - 2;

 

+    //

+    // A Map object in which tool chain configuration information will be stored

+    // 

     private Map<ToolChainKey, String> map = null;

 

+    /**

+       Public constructor. It just initializes the private Map object.

+     **/

     public ToolChainMap() {

         this.map = new HashMap<ToolChainKey, String>();

     }

 

+    /**

+       Wrapper function for Map.put(). It's used when default delimiter of

+       ToolChainKey is not wanted and will be overrided by "delimiter" parameter.

+

+       @param key           Key string which is concatenated with "delimiter"

+       @param delimiter     The delimiter string in the key string

+       @param value         Value string associated with the "key"

+       

+       @retval String       The "value" string if the "key" is valid.

+       @retval null         if the "key" is invalid

+     **/

     public String put(String key, String delimiter, String value) {

         ToolChainKey toolChainKey;

 

@@ -38,6 +65,15 @@ public class ToolChainMap {
         return (String)map.put(toolChainKey, value);

     }

 

+    /**

+       Wrapper function for Map.put().

+

+       @param key           Key string which is concatenated with default "delimiter"

+       @param value         Value string associated with the "key"

+       

+       @retval String       The "value" string if the "key" is valid.

+       @retval null         if the "key" is invalid

+     **/

     public String put(String key, String value) {

         ToolChainKey toolChainKey;

 

@@ -49,6 +85,16 @@ public class ToolChainMap {
         return (String)map.put(toolChainKey, value);

     }

 

+    /**

+       Wrapper function for Map.put(). The key is given in the form of string

+       array.

+

+       @param key           Key string array

+       @param value         Value string associated with the "key"

+       

+       @retval String       The "value" string if the "key" is valid.

+       @retval null         if the "key" is invalid

+     **/

     public String put(String[] key, String value) {

         ToolChainKey toolChainKey;

 

@@ -60,10 +106,26 @@ public class ToolChainMap {
         return (String)map.put(toolChainKey, value);

     }

 

+    /**

+       Wrapper function for Map.put(). The key is given in ToolChainKey class.

+

+       @param key           ToolChainKey class

+       @param value         Value string associated with the "key"

+       

+       @retval String       The "value" string if the "key" is valid.

+       @retval null         if the "key" is invalid

+     **/

     public String put(ToolChainKey key, String value) {

         return (String)map.put(key, value);

     }

 

+    /**

+       Wrapper function for Map.get().

+

+       @param key           Key string which is concatenated with default "delimiter"

+       

+       @return String

+     **/

     public String get(String key) {

         ToolChainKey toolChainKey;

 

@@ -75,6 +137,15 @@ public class ToolChainMap {
         return get(toolChainKey);

     }

 

+    /**

+       Wrapper function for Map.get(). It's used when default delimiter of

+       ToolChainKey is not wanted and will be overrided by "delimiter" parameter.

+

+       @param key           Key string which is concatenated with "delimiter"

+       @param delimiter     The delimiter string in the key string

+       

+       @return String

+     **/

     public String get(String key, String delimiter) {

         ToolChainKey toolChainKey;

 

@@ -86,6 +157,14 @@ public class ToolChainMap {
         return get(toolChainKey);

     }

 

+    /**

+       Wrapper function for Map.get(). The key is given in the form of string

+       array.

+

+       @param key           Key string array

+       

+       @return String

+     **/

     public String get(String[] key) {

         ToolChainKey toolChainKey;

 

@@ -97,12 +176,30 @@ public class ToolChainMap {
         return get(toolChainKey);

     }

 

+    /**

+       Wrapper function for Map.get(). The key is given in ToolChainKey class.

+       All other form of get() method will eventually call this form of get. It

+       will do real job of finding the value associated with the given key. Most

+       of the job is to try to match the key with "wildcard".

+

+       @param key           ToolChainKey class

+       

+       @return String       The value associated with the key

+     **/

     public String get(ToolChainKey key) {

+        ///

+        /// First, we'll try to get the value through the exact given key

+        /// 

         String result = map.get(key);

         if (result != null || map.containsKey(key)) {

             return result;

         }

 

+        ///

+        /// If nothing is found, then, we'll try all possible keys combined with

+        /// wildcard "*". In order not to change the original key value, we have

+        /// to clone one for later use. 

+        /// 

         String[] keySet = key.getKeySet();

         ToolChainKey tmpKey;

         try {

@@ -111,17 +208,68 @@ public class ToolChainMap {
             return null;

         }

 

+        ///

+        /// In the current tool chain definition format (in name/value pair), 

+        /// there're five parts in the "name". The last part of the "name" must

+        /// not be "wildcard". So we should start combining "*" from the fourth part.

+        /// We'll try all the possible combinations until the value can be fetched.

+        ///  

+        /// The following code implements the logic which will try to use, for example,

+        /// following key parts combinations sequentially to get the value.

+        /// 

+        /// TARGET_TOOLCHAIN_ARCH_TOOLCODE_ATTRIBUTE

+        /// TARGET_TOOLCHAIN_ARCH_*_ATTRIBUTE

+        /// TARGET_TOOLCHAIN_*_TOOLCODE_ATTRIBUTE

+        /// TARGET_TOOLCHAIN_*_*_ATTRIBUTE

+        /// TARGET_*_ARCH_TOOLCODE_ATTRIBUTE

+        /// TARGET_*_ARCH_*_ATTRIBUTE

+        /// TARGET_*_*_TOOLCODE_ATTRIBUTE

+        /// TARGET_*_*_*_ATTRIBUTE

+        /// *_TOOLCHAIN_ARCH_TOOLCODE_ATTRIBUTE

+        /// *_TOOLCHAIN_ARCH_*_ATTRIBUTE

+        /// *_TOOLCHAIN_*_TOOLCODE_ATTRIBUTE

+        /// *_TOOLCHAIN_*_*_ATTRIBUTE

+        /// *_*_ARCH_TOOLCODE_ATTRIBUTE

+        /// *_*_ARCH_*_ATTRIBUTE

+        /// *_*_*_TOOLCODE_ATTRIBUTE

+        /// *_*_*_*_ATTRIBUTE

+        /// 

+

+        //

+        // level is used to control if all parts of "name" have been "wildcarded"

+        // 

         int level = matchLevel;

         while (level >= 0) {

+            //

+            // tmplevel is used to control if all parts of "name" between first

+            // "*" and fourth name part have been "wildcarded".

+            // 

             int tmpLevel = level;

             while (tmpLevel >= level) {

                 String[] tmpKeySet = tmpKey.getKeySet();

                 try {

                     if (!tmpKeySet[tmpLevel].equals("*")) {

+                        //

+                        // If "tmplevel" part is not "*", set it to "*".

+                        // For example, at first loop, the key will become

+                        // TARGET_TOOLCHAIN_ARCH_*_ATTRIBUTE, and at next loop,

+                        // become TARGET_TOOLCHAIN_*_ARCH_ATTRIBUTE

+                        // 

                         tmpKey.setKey("*", tmpLevel);

+                        //

+                        // We'll try all possible combinations between current

+                        // part and the fourth part.

+                        // 

                         tmpLevel = matchLevel;

                     } else {

+                        //

+                        // Restore original value of key if "*" at "tmplevel"

+                        // part of "name" has been checked

+                        // 

                         tmpKey.setKey(keySet[tmpLevel], tmpLevel);

+                        //

+                        // Try "*" at part left to "tmplevel" part of "name"

+                        // 

                         --tmpLevel;

                         continue;

                     }

@@ -129,23 +277,48 @@ public class ToolChainMap {
                     return null;

                 }

 

+                //

+                // Try get the value from the map

+                // 

                 result = map.get(tmpKey);

                 if (result != null) {

+                    //

+                    // The map actually has no exact key as the given "key", 

+                    // putting it back into map can speed up the get() next time

+                    // 

                     map.put(key, result);

                     return result;

                 }

             }

+            ///

+            /// If all possible combinations of "wildcard" between "level" and 

+            /// the fourth part of "name" have been tried, try the left part

+            /// 

             --level;

         }

 

+        //

+        // The map actually has no exact key as the given "key", putting it back

+        // into map can speed up the get() next time even we got nothing.

+        // 

         map.put(key, result);

         return result;

     }

 

+    /**

+       Wrapper function for Map.size().

+

+       @return int  The size of map

+     **/

     public int size() {

         return map.size();

     }

 

+    /**

+       Wrapper function for Map.keySet().

+

+       @return Set<ToolChainKey>    A set of ToolChainKey objects

+     */

     public Set<ToolChainKey> keySet() {

         return (Set<ToolChainKey>)map.keySet();

     }