Documentation for the Path elements, made nested src element of Javac

use Path as well.


git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@267783 13f79535-47bb-0310-9956-ffa450edef68

bootstrap.sh

@@ -1,5 +1,7 @@
 #!/bin/sh
 
+# You will need to specify JAVA_HOME if compiling with 1.2 or later.
+
 ANT_HOME=.
 export ANT_HOME
 

docs/index.html

@@ -395,6 +395,38 @@ this should not cause problems.</p>
 </pre>
 </blockquote>
 
+<h3><a name="path">PATH like structures</a></h3>
+<p>You can specify PATH and CLASSPATH variables using both
+&quot;:&quot; and &quot;;&quot; as separator characters, Ant will
+convert it to the correct character of the current operating
+system.</p>
+<p>Wherever PATH like values need to be specified a nested element can
+be used. This takes the general form of</p>
+<pre>
+    &lt;classpath&gt;
+      &lt;pathelement path=&quot;${classpath}&quot; /&gt;
+      &lt;pathelement location=&quot;lib/helper.jar&quot; /&gt;
+    &lt;/classpath&gt;
+</pre>
+<p>The <code>location</code> attribute specifies a single file or
+directory relative to the project's base directory (or an absolute
+filename), while the <code>path</code> attribute accepts &quot;:&quot;
+or &quot;;&quot; separated lists of locations. The <code>path</code>
+attribute is intended to be used with predefined paths - in any other
+case multiple elements with <code>location</code> attributes should be
+preferred.</p>
+<p>As a shortcut the surrounding PATH element supports path and
+location attributes of its own, so</p>
+<pre>
+    &lt;classpath&gt;
+      &lt;pathelement path=&quot;${classpath}&quot; /&gt;
+    &lt;/classpath&gt;
+</pre>
+<p>can be abreviated to</p>
+<pre>
+    &lt;classpath path=&quot;${classpath}&quot; /&gt;
+</pre>
+
 <hr>
 <h2><a name="directorybasedtasks">Directory based tasks</a></h2>
 <p>Some tasks use directory trees for the task they perform. For instance, the <a
@@ -1013,6 +1045,7 @@ relative to the <i>dir</i> directory.</p>
 </pre>
 <p>deletes all files with the extension &quot;<code>.bak</code>&quot from the current directory 
 and any sub-directories.</p>
+<hr>
 <h2><a name="deltree">Deltree</a></h2>
 <h3>Description</h3>
 <p>Deletes a directory with all its files and subdirectories.</p>
@@ -1607,6 +1640,19 @@ the one that is currently running Ant.</p>
     <td align="center" valign="top">No</td>
   </tr>
 </table>
+<h3>Parameters specified as nested elements</h3>
+<p><code>Java</code>'s <em>classpath</em> attribute is a <a
+href="#path">PATH like structure</a> and can also be set via a nested
+<em>classpath</em> element.</p>
+<h4>Example</h4>
+<pre>  
+       &lt;java classname=&quot;test.Main&quot; args=&quot;-h&quot; &gt;
+         &lt;classpath&gt;
+           &lt;pathelement location=&quot;\test.jar&quot; /&gt;
+           &lt;pathelement path=&quot;${java.class.path}&quot; /&gt;
+         &lt;/classpath&gt;
+       &lt;/java&gt;
+</pre>
 <h3>Examples</h3>
 <pre>  &lt;java classname=&quot;test.Main&quot; /&gt;</pre>
 <pre>  &lt;java classname=&quot;test.Main&quot; args=&quot;-h&quot; /&gt;</pre>
@@ -1747,21 +1793,12 @@ nested <code>&lt;src&gt;</code> element. This is used to specify multiple source
 Multiple <code>src</code> elements may be present and each specifies a source path which will be 
 searched by Javac for classes to compile.
 
-<h4>src</h4>
-Define a source path to be search for source files.
-<H4>Parameters</h4>
-<table width="60%" border="1" cellpadding="2" cellspacing="0">
-  <tr>
-    <td valign="top"><b>Attribute</b></td>
-    <td valign="top"><b>Description</b></td>
-    <td align="center" valign="top"><b>Required</b></td>
-  </tr>
-  <tr>
-    <td valign="top">src</td>
-    <td valign="top">A source path. It may contain multiple elements separated with either a ';' or a ':'</td>
-    <td align="center" valign="top">Yes</td>
-  </tr>
-</table>
+<h4>src, classpath, bootclasspath and extdirs</h4>
+<p><code>Javac</code>'s <em>srcdir</em>, <em>classpath</em>,
+<em>bootclasspath</em> and <em>extdirs</em> attributes are <a
+href="#path">PATH like structure</a> and can also be set via nested
+<em>src</em>, <em>classpath</em>, <em>bootclasspath</em> and
+<em>extdirs</em> elements respectively.</p>
 
 <h3>Examples</h3>
 <pre>  &lt;javac srcdir=&quot;${src}&quot;
@@ -2181,6 +2218,13 @@ one group per table.
   </tr>
 </table>
 
+<h4>sourcepath, classpath and bootclasspath</h4>
+<p><code>Javadoc</code>'s <em>sourcepath</em>, <em>classpath</em> and
+<em>bootclasspath</em> attributes are <a href="#path">PATH like
+structure</a> and can also be set via nested <em>sourcepath</em>,
+<em>classpath</em> and <em>bootclasspath</em> elements
+respectively.</p>
+
 <h3>Example</h3>
 <pre>  &lt;javadoc packagenames=&quot;com.dummy.test.*&quot;
            sourcepath=&quot;src&quot;
@@ -2608,6 +2652,11 @@ relative to the <i>base</i> directory.</p>
     <td align="center" valign="top">No</td>
   </tr>
 </table>
+<h3>Parameters specified as nested elements</h3>
+<h4>classpath</h4>
+<p><code>Rmic</code>'s <em>classpath</em> attribute is a <a
+href="#path">PATH like structure</a> and can also be set via a nested
+<em>classpath</em> elements.</p>
 <h3>Examples</h3>
 <pre>  &lt;rmic classname=&quot;com.xyz.FooBar&quot; base=&quot;${build}/classes&quot; /&gt;</pre>
 <p>runs the rmic compiler for the class <code>com.xyz.FooBar</code>. The

src/main/org/apache/tools/ant/taskdefs/Javac.java

@@ -88,26 +88,13 @@ import java.util.*;
 
 public class Javac extends MatchingTask {
 
-    public class SourcePathElement {
-        private String path;
-        
-        public void setPath(String path) {
-            this.path = path;
-        }
-        
-        public String getPath() {
-            return path;
-        }
-    };
-
     /**
      * Integer returned by the "Modern" jdk1.3 compiler to indicate success.
      */
     private static final int
         MODERN_COMPILER_SUCCESS = 0;
 
-    private Vector srcPathElements = new Vector();
-    private Vector srcDirs= new Vector();
+    private Path src;
     private File destDir;
     private Path compileClasspath;
     private boolean debug = false;
@@ -127,53 +114,22 @@ public class Javac extends MatchingTask {
      *
      * @return a nexted src element.
      */
-    public SourcePathElement createSrc() {
-        SourcePathElement element = new SourcePathElement();
-        srcPathElements.addElement(element);
-        return element;
-    }
-
-    /**
-     * Add a single directory to the collection of directories that
-     * make up the source path.
-     *
-     * @param srcDirName the name of the directory to add to the list of source directories.
-     */
-    private void addSrcDir(String srcDirName) {
-        addSrcDir(project.resolveFile(srcDirName));
-    }
-
-    /**
-     * Add a single directory to the collection of directories that
-     * make up the source path.
-     *
-     * @param srcDir the directory to add to the list of source directories.
-     */
-    private void addSrcDir(File srcDir) {
-        srcDirs.addElement(srcDir);
-    }
-
-    /**
-     * Add a set of source directories specified as path.
-     *
-     * @param srcPath the list of source directories.
-     */
-    private void addSrcPath(String srcPath) {
-        // use a Path tokenizer to find the paths and add them to 
-        // the vector of source paths.
-        PathTokenizer tokenizer = new PathTokenizer(srcPath);
-        while (tokenizer.hasMoreTokens()) {
-            addSrcDir(tokenizer.nextToken());
+    public Path createSrc() {
+        if (src != null) {
+            src = new Path();
         }
-    }        
+        return src;
+    }
 
     /**
      * Set the source dirs to find the source Java files.
      */
-    public void setSrcdir(String srcPath) {
-        // clean out the list of source dirs
-        srcDirs = new Vector();
-        addSrcPath(srcPath);
+    public void setSrcdir(Path srcDir) {
+        if (src == null) {
+            src = srcDir;
+        } else {
+            src.append(srcDir);
+        }
     }
 
     /**
@@ -291,23 +247,15 @@ public class Javac extends MatchingTask {
     public void execute() throws BuildException {
         // first off, make sure that we've got a srcdir and destdir
 
-        // process the source elements into the srcDirs collection
-        for (Enumeration e = srcPathElements.elements(); e.hasMoreElements(); ) {
-            SourcePathElement element = (SourcePathElement)e.nextElement();
-            addSrcPath(element.getPath());
-        }
-
-        if (srcDirs.size() == 0) {
+        if (src == null) {
             throw new BuildException("srcdir attribute must be set!");
         }
         
-        for (Enumeration e = srcDirs.elements(); e.hasMoreElements(); ) {
-            File srcDir = (File)e.nextElement();
-            if (!srcDir.exists()) {
-                throw new BuildException("srcdir " + srcDir.getPath() + " does not exist!");
-            }
+        String [] list = src.list();
+        if (list.length == 0) {
+            throw new BuildException("srcdir attribute must be set!");
         }
-
+        
         if (destDir == null) {
             throw new BuildException("destdir attribute must be set!");
         }
@@ -315,15 +263,19 @@ public class Javac extends MatchingTask {
         // scan source directories and dest directory to build up both copy lists and
         // compile lists
         resetFileLists();
-        for (Enumeration e = srcDirs.elements(); e.hasMoreElements(); ) {
-            File srcDir = (File)e.nextElement();
+        for (int i=0; i<list.length; i++) {
+            File srcDir = (File)project.resolveFile(list[i]);
+            if (!srcDir.exists()) {
+                throw new BuildException("srcdir " + srcDir.getPath() + " does not exist!");
+            }
+
             DirectoryScanner ds = this.getDirectoryScanner(srcDir);
 
             String[] files = ds.getIncludedFiles();
 
             scanDir(srcDir, destDir, files);
         }
-
+        
         // compile the source files
 
         String compiler = project.getProperty("build.compiler");
@@ -499,25 +451,6 @@ public class Javac extends MatchingTask {
         }
     }
 
-    /**
-     * Get the list of source directories separated by a platform specific
-     * path separator.
-     *
-     * @return the current source directories in a single path separated using the 
-     * platform specific path separator.
-     */
-    private String getSourcePath() {
-        String sourcePath = "";
-        for (Enumeration e = srcDirs.elements(); e.hasMoreElements(); ) {
-            File srcDir = (File)e.nextElement();
-            if (sourcePath.length() != 0) {
-                sourcePath += File.pathSeparator;
-            }
-            sourcePath += srcDir.getAbsolutePath();
-        }
-        return sourcePath;
-    }
-
     /**
      * Peforms a copmile using the classic compiler that shipped with
      * JDK 1.1 and 1.2.
@@ -537,11 +470,11 @@ public class Javac extends MatchingTask {
         // Just add "sourcepath" to classpath ( for JDK1.1 )
         if (Project.getJavaVersion().startsWith("1.1")) {
             argList.addElement(classpath.toString() + File.pathSeparator +
-                               getSourcePath());
+                               src.toString());
         } else {
             argList.addElement(classpath.toString());
             argList.addElement("-sourcepath");
-            argList.addElement(getSourcePath());
+            argList.addElement(src.toString());
             if (target != null) {
                 argList.addElement("-target");
                 argList.addElement(target);
@@ -624,7 +557,7 @@ public class Javac extends MatchingTask {
         argList.addElement("-classpath");
         argList.addElement(classpath.toString());
         argList.addElement("-sourcepath");
-        argList.addElement(getSourcePath());
+        argList.addElement(src.toString());
         if (target != null) {
             argList.addElement("-target");
             argList.addElement(target);
@@ -717,7 +650,7 @@ public class Javac extends MatchingTask {
 
         // Jikes has no option for source-path so we
         // will add it to classpath.
-        classpath.setPath(getSourcePath());
+        classpath.append(src);
 
         Vector argList = new Vector();