merge

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

build.xml

@@ -772,7 +772,7 @@
       </manifest>
     </jar>
 
-    <jar destfile="${build.lib}/nodeps.jar"
+    <jar destfile="${build.lib}/ant-nodeps.jar"
          basedir="${build.classes}"
          manifest="${manifest.tmp}">
       <and>

docs/manual/running.html

@@ -87,6 +87,7 @@ Options:
   -verbose, -v           be extra verbose
   -debug                 print debugging information
   -emacs                 produce logging information without adornments
+  -lib <path>            specifies a path to search for jars and classes
   -logfile &lt;file&gt;        use given file for log
     -l     &lt;file&gt;                ''
   -logger &lt;classname&gt;    the class which is to perform logging
@@ -109,6 +110,45 @@ Options:
 <p>For more information about <code>-inputhandler</code> see
 <a href="inputhandler.html">InputHandler</a>.
 
+<h3><a name="libs">Library Directories</a></h3>
+<p>
+Prior to Ant 1.6, all jars in the ANT_HOME/lib would be added to the CLASSPATH
+used to run Ant. This was done in the scripts that started Ant. From Ant 1.6,
+two directories are scanned by default and more can be added as required. The
+default directories scanned are ANT_HOME/lib and a user specific directory,
+${user.home}/.ant/lib. This arrangement allows the Ant installation to be
+shared by many users while still allowing each user to deploy additional jars.
+Such additional jars could be support jars for Ant's optional tasks or jars
+containing third-party tasks to be used in the build. It also allows the main Ant
+installation to be locked down which will please system adminstrators.
+</p>
+
+<p>
+Additional directories to be searched may be added by using the -lib option.
+The -lib option specifies a search path. Any jars or classes in the directories
+of the path will be added to Ant's classloader. The order in which jars are
+added to the classpath is as follows
+</p>
+
+<ul>
+  <li>-lib jars in the order specified by the -lib elements on the command line</li>
+  <li>jars from ${user.home}/.ant/lib</li>
+  <li>jars from ANT_HOME/lib</li>
+</ul>
+
+<p>
+Note that the CLASSPATH environment variable is passed to Ant using a -lib
+option. Ant itself is started with a very minimalistic classpath.
+</p>
+
+<p>
+The location of ${user.home}/.ant/lib is somewhat dependent on the JVM. On Unix
+systems ${user.home} maps to the user's home directory whilst on recent
+versions of Windows it will be somewhere such as
+C:\Documents&nbsp;and&nbsp;Settings\username\.ant\lib. You should consult your
+JVM documentation for more details.
+</p>
+
 <h3>Examples</h3>
 <blockquote>
   <pre>ant</pre>
@@ -132,6 +172,13 @@ the target called <code>dist</code>.</p>
 the target called <code>dist</code>, setting the <code>build</code> property
 to the value <code>build/classes</code>.</p>
 
+<blockquote>
+  <pre>ant -lib /home/ant/extras</pre>
+</blockquote>
+<p>runs Ant picking up additional task and support jars from the
+/home/ant/extras location
+</p>
+
 <h3><a name="files">Files</a></h3>
 
 <p>The Ant wrapper script for Unix will source (read and evaluate) the
@@ -207,19 +254,35 @@ have some documentation inside.</p>
 
 <h2><a name="viajava">Running Ant via Java</a></h2>
 <p>If you have installed Ant in the do-it-yourself way, Ant can be started
-with:</p>
+with two entry points:</p>
 <blockquote>
   <pre>java -Dant.home=c:\ant org.apache.tools.ant.Main [options] [target]</pre>
 </blockquote>
 
-<p>These instructions actually do exactly the same as the <code>ant</code>
-command. The options and target are the same as when running Ant with the <code>ant</code>
-command. This example assumes you have set your classpath to include:</p>
+<blockquote>
+  <pre>java -Dant.home=c:\ant org.apache.tools.ant.launch.Launcher [options] [target]</pre>
+</blockquote>
+
+<p>
+The first method runs Ant's traditional entry point. The second method uses
+the Ant Launcher introduced in Ant 1.6. The former method does not support
+the -lib option and all required classes are loaded from the CLASSPATH. You must
+ensure that all required jars are available. At a minimum the CLASSPATH should
+include:
+</p>
+
 <ul>
-<li><code>ant.jar</code></li>
+<li><code>ant.jar</code> and <code>ant-launcher.jar</code></li>
 <li>jars/classes for your XML parser</li>
 <li>the JDK's required jar/zip files</li>
 </ul>
+
+<p>
+The latter method supports the -lib option and will load jars from the
+specified ANT_HOME. You should start the latter with the most minimal
+classpath possible, generally just the ant-launcher.jar.
+</p>
+
 <br>
 <hr>
 <p align="center">Copyright &copy; 2000-2003 Apache Software Foundation. All rights

docs/manual/runninglist.html

@@ -13,6 +13,7 @@
 <h3>Running Ant</h3>
 <a href="running.html#commandline">Command Line</a><br>
 &nbsp;&nbsp;<a href="running.html#options">Options</a><br>
+&nbsp;&nbsp;<a href="running.html#libs">Library Directories</a><br>
 &nbsp;&nbsp;<a href="running.html#files">Files</a><br>
 &nbsp;&nbsp;<a href="running.html#envvars">Environment Variables</a><br>
 &nbsp;&nbsp;<a href="running.html#cygwin">Cygwin Users</a><br>

src/main/org/apache/tools/ant/Main.java

@@ -291,7 +291,8 @@ public class Main implements AntMain {
 
     /**
      * Process command line arguments.
-     * When ant is started from Launcher, the -lib argument does not get passed through to this routine.
+     * When ant is started from Launcher, the -lib argument does not get
+     * passed through to this routine.
      *
      * @param args the command line arguments.
      *
@@ -808,6 +809,7 @@ public class Main implements AntMain {
         msg.append("  -verbose, -v           be extra verbose" + lSep);
         msg.append("  -debug, -d             print debugging information" + lSep);
         msg.append("  -emacs, -e             produce logging information without adornments" + lSep);
+        msg.append("  -lib <path>            specifies a path to search for jars and classes" + lSep);
         msg.append("  -logfile <file>        use given file for log" + lSep);
         msg.append("    -l     <file>                ''" + lSep);
         msg.append("  -logger <classname>    the class which is to perform logging" + lSep);

src/main/org/apache/tools/ant/launch/LaunchException.java

@@ -0,0 +1,77 @@
+/*
+ * The Apache Software License, Version 1.1
+ *
+ * Copyright (c) 2003 The Apache Software Foundation.  All rights
+ * reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright
+ *    notice, this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright
+ *    notice, this list of conditions and the following disclaimer in
+ *    the documentation and/or other materials provided with the
+ *    distribution.
+ *
+ * 3. The end-user documentation included with the redistribution, if
+ *    any, must include the following acknowlegement:
+ *       "This product includes software developed by the
+ *        Apache Software Foundation (http://www.apache.org/)."
+ *    Alternately, this acknowlegement may appear in the software itself,
+ *    if and wherever such third-party acknowlegements normally appear.
+ *
+ * 4. The names "Ant" and "Apache Software
+ *    Foundation" must not be used to endorse or promote products derived
+ *    from this software without prior written permission. For written
+ *    permission, please contact apache@apache.org.
+ *
+ * 5. Products derived from this software may not be called "Apache"
+ *    nor may "Apache" appear in their names without prior written
+ *    permission of the Apache Group.
+ *
+ * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
+ * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+ * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+ * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
+ * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
+ * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+ * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
+ * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+ * SUCH DAMAGE.
+ * ====================================================================
+ *
+ * This software consists of voluntary contributions made by many
+ * individuals on behalf of the Apache Software Foundation.  For more
+ * information on the Apache Software Foundation, please see
+ * <http://www.apache.org/>.
+ */
+package org.apache.tools.ant.launch;
+
+import java.io.PrintStream;
+import java.io.PrintWriter;
+
+/**
+ * Signals an error condition during launching
+ *
+ * @author Conro MacNeill
+ * @since Ant 1.6
+ */
+public class LaunchException extends Exception {
+
+    /**
+     * Constructs an exception with the given descriptive message.
+     *
+     * @param message A description of or information about the exception.
+     *            Should not be <code>null</code>.
+     */
+    public LaunchException(String message) {
+        super(message);
+    }
+
+}

src/main/org/apache/tools/ant/launch/Launcher.java

@@ -88,6 +88,8 @@ public class Launcher {
         try {
             Launcher launcher = new Launcher();
             launcher.run(args);
+        } catch (LaunchException e) {
+            System.err.println(e.getMessage());
         } catch (Throwable t) {
             t.printStackTrace();
         }
@@ -102,7 +104,7 @@ public class Launcher {
      * @exception MalformedURLException if the URLs required for the classloader
      *            cannot be created.
      */
-    private void run(String[] args) throws MalformedURLException {
+    private void run(String[] args) throws LaunchException, MalformedURLException {
         String antHomeProperty = System.getProperty(ANTHOME_PROPERTY);
         File antHome = null;
 
@@ -119,7 +121,7 @@ public class Launcher {
         }
 
         if (!antHome.exists()) {
-            throw new IllegalStateException("Ant home is set incorrectly or "
+            throw new LaunchException("Ant home is set incorrectly or "
                 + "ant could not be located");
         }
 
@@ -130,7 +132,7 @@ public class Launcher {
         for (int i = 0; i < args.length; ++i) {
             if (args[i].equals("-lib")) {
                 if (i == args.length - 1) {
-                    throw new IllegalStateException("The -lib argument must "
+                    throw new LaunchException("The -lib argument must "
                         + "be followed by a library location");
                 }
                 libPaths.add(args[++i]);

src/script/ant

@@ -34,7 +34,7 @@ case "`uname`" in
            ;;
 esac
 
-if [ -z "$ANT_HOME" ] ; then
+if [ -z "$ANT_HOME" -o ! -d "$ANT_HOME" ] ; then
   # try to find ANT
   if [ -d /opt/ant ] ; then
     ANT_HOME=/opt/ant