diff --git a/build.xml b/build.xml index 866c472f2..1b6faee37 100644 --- a/build.xml +++ b/build.xml @@ -772,7 +772,7 @@ - diff --git a/docs/manual/running.html b/docs/manual/running.html index 4a0a770ff..ca2d7bdca 100644 --- a/docs/manual/running.html +++ b/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 specifies a path to search for jars and classes -logfile <file> use given file for log -l <file> '' -logger <classname> the class which is to perform logging @@ -109,6 +110,45 @@ Options:

For more information about -inputhandler see InputHandler. +

Library Directories

+

+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. +

+ +

+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 +

+ +
    +
  • -lib jars in the order specified by the -lib elements on the command line
    • +
  • jars from ${user.home}/.ant/lib
    • +
  • jars from ANT_HOME/lib
    • +
+ +

+Note that the CLASSPATH environment variable is passed to Ant using a -lib +option. Ant itself is started with a very minimalistic classpath. +

+ +

+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 and Settings\username\.ant\lib. You should consult your +JVM documentation for more details. +

+

Examples

ant
@@ -132,6 +172,13 @@ the target called dist.

the target called dist, setting the build property to the value build/classes.

+
+ 
ant -lib /home/ant/extras
+
+

runs Ant picking up additional task and support jars from the +/home/ant/extras location +

+

Files

The Ant wrapper script for Unix will source (read and evaluate) the @@ -207,19 +254,35 @@ have some documentation inside.

Running Ant via Java

If you have installed Ant in the do-it-yourself way, Ant can be started -with:

+with two entry points:

java -Dant.home=c:\ant org.apache.tools.ant.Main [options] [target]
-

These instructions actually do exactly the same as the ant -command. The options and target are the same as when running Ant with the ant -command. This example assumes you have set your classpath to include:

+
+ 
java -Dant.home=c:\ant org.apache.tools.ant.launch.Launcher [options] [target]
+
+ +

+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: +

+
    -
  • ant.jar
    • +
  • ant.jar and ant-launcher.jar
  • jars/classes for your XML parser
  • the JDK's required jar/zip files
+ +

+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. +

+

Copyright © 2000-2003 Apache Software Foundation. All rights diff --git a/docs/manual/runninglist.html b/docs/manual/runninglist.html index 587aad9fd..8e973e7e8 100644 --- a/docs/manual/runninglist.html +++ b/docs/manual/runninglist.html @@ -13,6 +13,7 @@

Running Ant

Command Line
  Options
+  Library Directories
  Files
  Environment Variables
  Cygwin Users
diff --git a/src/main/org/apache/tools/ant/Main.java b/src/main/org/apache/tools/ant/Main.java index e355c883d..b5492dd20 100644 --- a/src/main/org/apache/tools/ant/Main.java +++ b/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 specifies a path to search for jars and classes" + lSep); msg.append(" -logfile use given file for log" + lSep); msg.append(" -l ''" + lSep); msg.append(" -logger the class which is to perform logging" + lSep); diff --git a/src/main/org/apache/tools/ant/launch/LaunchException.java b/src/main/org/apache/tools/ant/launch/LaunchException.java new file mode 100644 index 000000000..4ca8a2780 --- /dev/null +++ b/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 + * . + */ +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 null. + */ + public LaunchException(String message) { + super(message); + } + +} diff --git a/src/main/org/apache/tools/ant/launch/Launcher.java b/src/main/org/apache/tools/ant/launch/Launcher.java index af8bf1dcf..b23fe1d8d 100644 --- a/src/main/org/apache/tools/ant/launch/Launcher.java +++ b/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]); diff --git a/src/script/ant b/src/script/ant index f32a356b2..38407ec55 100644 --- a/src/script/ant +++ b/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