conor 2003/10/01 21:58:16
Modified: . Tag: ANT_16_BRANCH build.xml
docs/manual Tag: ANT_16_BRANCH running.html runninglist.html
src/main/org/apache/tools/ant Tag: ANT_16_BRANCH Main.java
src/main/org/apache/tools/ant/launch Tag: ANT_16_BRANCH
Launcher.java
src/script Tag: ANT_16_BRANCH ant
Added: src/main/org/apache/tools/ant/launch Tag: ANT_16_BRANCH
LaunchException.java
Log:
Add doco for -lib option
Add Steve-friendly error messages for incorrect -lib option
PR: 23454
Revision Changes Path
No revision
No revision
1.392.2.3 +1 -1 ant/build.xml
Index: build.xml
===================================================================
RCS file: /home/cvs/ant/build.xml,v
retrieving revision 1.392.2.2
retrieving revision 1.392.2.3
diff -u -w -u -r1.392.2.2 -r1.392.2.3
--- build.xml 25 Sep 2003 14:42:46 -0000 1.392.2.2
+++ build.xml 2 Oct 2003 04:58:15 -0000 1.392.2.3
@@ -771,7 +771,7 @@
</manifest>
</jar>
- <jar destfile="${build.lib}/nodeps.jar"
+ <jar destfile="${build.lib}/ant-nodeps.jar"
basedir="${build.classes}"
manifest="${manifest.tmp}">
<and>
No revision
No revision
1.21.2.1 +68 -5 ant/docs/manual/running.html
Index: running.html
===================================================================
RCS file: /home/cvs/ant/docs/manual/running.html,v
retrieving revision 1.21
retrieving revision 1.21.2.1
diff -u -w -u -r1.21 -r1.21.2.1
--- running.html 16 Jul 2003 14:14:38 -0000 1.21
+++ running.html 2 Oct 2003 04:58:15 -0000 1.21.2.1
@@ -87,6 +87,7 @@
-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 <file> use given file for log
-l <file> ''
-logger <classname> the class which is to perform logging
@@ -109,6 +110,45 @@
<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 and 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>, 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 @@
<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 © 2000-2003 Apache Software Foundation. All
rights
1.4.2.1 +1 -0 ant/docs/manual/runninglist.html
Index: runninglist.html
===================================================================
RCS file: /home/cvs/ant/docs/manual/runninglist.html,v
retrieving revision 1.4
retrieving revision 1.4.2.1
diff -u -w -u -r1.4 -r1.4.2.1
--- runninglist.html 23 Apr 2003 15:57:43 -0000 1.4
+++ runninglist.html 2 Oct 2003 04:58:15 -0000 1.4.2.1
@@ -13,6 +13,7 @@
<h3>Running Ant</h3>
<a href="running.html#commandline">Command Line</a><br>
<a href="running.html#options">Options</a><br>
+ <a href="running.html#libs">Library Directories</a><br>
<a href="running.html#files">Files</a><br>
<a href="running.html#envvars">Environment Variables</a><br>
<a href="running.html#cygwin">Cygwin Users</a><br>
No revision
No revision
1.95.2.2 +3 -1 ant/src/main/org/apache/tools/ant/Main.java
Index: Main.java
===================================================================
RCS file: /home/cvs/ant/src/main/org/apache/tools/ant/Main.java,v
retrieving revision 1.95.2.1
retrieving revision 1.95.2.2
diff -u -w -u -r1.95.2.1 -r1.95.2.2
--- Main.java 22 Sep 2003 21:15:41 -0000 1.95.2.1
+++ Main.java 2 Oct 2003 04:58:15 -0000 1.95.2.2
@@ -291,7 +291,8 @@
/**
* 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 @@
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);
No revision
No revision
1.5.2.4 +5 -3 ant/src/main/org/apache/tools/ant/launch/Launcher.java
Index: Launcher.java
===================================================================
RCS file: /home/cvs/ant/src/main/org/apache/tools/ant/launch/Launcher.java,v
retrieving revision 1.5.2.3
retrieving revision 1.5.2.4
diff -u -w -u -r1.5.2.3 -r1.5.2.4
--- Launcher.java 24 Sep 2003 14:32:10 -0000 1.5.2.3
+++ Launcher.java 2 Oct 2003 04:58:15 -0000 1.5.2.4
@@ -88,6 +88,8 @@
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 @@
* @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 @@
}
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 @@
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]);
No revision
Index: Launcher.java
===================================================================
RCS file: /home/cvs/ant/src/main/org/apache/tools/ant/launch/Launcher.java,v
retrieving revision 1.5.2.3
retrieving revision 1.5.2.4
diff -u -w -u -r1.5.2.3 -r1.5.2.4
--- Launcher.java 24 Sep 2003 14:32:10 -0000 1.5.2.3
+++ Launcher.java 2 Oct 2003 04:58:15 -0000 1.5.2.4
@@ -88,6 +88,8 @@
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 @@
* @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 @@
}
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 @@
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]);
No revision
Index: Launcher.java
===================================================================
RCS file: /home/cvs/ant/src/main/org/apache/tools/ant/launch/Launcher.java,v
retrieving revision 1.5.2.3
retrieving revision 1.5.2.4
diff -u -w -u -r1.5.2.3 -r1.5.2.4
--- Launcher.java 24 Sep 2003 14:32:10 -0000 1.5.2.3
+++ Launcher.java 2 Oct 2003 04:58:15 -0000 1.5.2.4
@@ -88,6 +88,8 @@
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 @@
* @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 @@
}
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 @@
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]);
1.1.2.1 +77 -0
ant/src/main/org/apache/tools/ant/launch/Attic/LaunchException.java
No revision
No revision
1.38.2.3 +1 -1 ant/src/script/ant
Index: ant
===================================================================
RCS file: /home/cvs/ant/src/script/ant,v
retrieving revision 1.38.2.2
retrieving revision 1.38.2.3
diff -u -w -u -r1.38.2.2 -r1.38.2.3
--- ant 23 Sep 2003 15:40:36 -0000 1.38.2.2
+++ ant 2 Oct 2003 04:58:15 -0000 1.38.2.3
@@ -34,7 +34,7 @@
;;
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
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
