bodewig 2005/05/10 00:39:37
Modified: docs Tag: ANT_16_BRANCH faq.html
xdocs Tag: ANT_16_BRANCH faq.xml
Log:
Merge FAQ changes from HEAD
Revision Changes Path
No revision
No revision
1.77.2.24 +128 -33 ant/docs/faq.html
Index: faq.html
===================================================================
RCS file: /home/cvs/ant/docs/faq.html,v
retrieving revision 1.77.2.23
retrieving revision 1.77.2.24
diff -u -r1.77.2.23 -r1.77.2.24
--- faq.html 28 Apr 2005 13:12:32 -0000 1.77.2.23
+++ faq.html 10 May 2005 07:39:37 -0000 1.77.2.24
@@ -354,6 +354,14 @@
<style> or <junit> ignores my
<classpath>
</a></li>
+ <li><a href="#delegating-classloader-1.5">
+ <style> or <junit> ignores my
+ <classpath> - Ant 1.5.x version
+ </a></li>
+ <li><a href="#delegating-classloader-1.6">
+ <style> or <junit> ignores my
+ <classpath> - Ant 1.6.x version
+ </a></li>
<li><a href="#winxp-jdk14-ant14">
When running Ant 1.4 on Windows XP and JDK 1.4, I get
various errors when trying to <code><exec></code>, fork
@@ -1610,31 +1618,23 @@
</p>
<p>These tasks don't ignore your classpath setting, you
are facing a common problem with delegating classloaders.</p>
- <p>First of all let's state that Ant adds all
- <code>.jar</code> files from <code>ANT_HOME/lib</code> to
- <code>CLASSPATH</code>, therefore "in
- <code>CLASSPATH</code>" shall mean "either in your
- <code>CLASSPATH</code> environment variable or
- <code>ANT_HOME/lib</code>" for the rest of this
- answer.</p>
- <p>Technically the sentence above isn't true for Ant
1.6
- and later anymore, but the result is the same. For the sake
- of this discussion, <code>CLASSPATH</code> and
- <code>ANT_HOME/lib</code> are identical.</p>
<p>This question collects a common type of problem:
A task
needs an external library and it has a nested classpath
element so that you can point it to this external library, but
- that doesn't work unless you put the external library into the
- <code>CLASSPATH</code>.</p>
- <p>The root of the problem is that the class that
needs the
- external library is on the <code>CLASSPATH</code>.</p>
+ that doesn't work unless you put the external library
+ into the <code>CLASSPATH</code> or place it in
+ <code>ANT_HOME/lib</code>.</p>
+ <p>Some background is necessary before we can discuss
+ solutions for <a href="#delegating-classloader-1.5">Ant
+ 1.5.x</a> and <a href="#delegating-classloader-1.6">Ant
+ 1.6.x</a>.</p>
<p>When you specify a nested
<code><classpath></code> in
Ant, Ant creates a new class loader that uses the path you
have specified. It then tries to load additional classes from
this classloader.</p>
- <p>In most cases - for example the two cases above -
Ant
- doesn't load the external library directly, it is the loaded
- class that does so.</p>
+ <p>In most cases - for example using <style> or
+ <junit> - Ant doesn't load the external library
+ directly, it is the loaded class that does so.</p>
<p>In the case of <code><junit></code> it is
the task
implementation itself and in the case of
<code><style></code> it is the implementation of the
@@ -1654,16 +1654,37 @@
class loader, does not itself have a parent but may serve as
the parent of a <code>ClassLoader</code>
instance.</blockquote>
- <p>This means, Ant's class loader will consult the
+ <p>The possible solutions depend on the version of
Ant you
+ use, see the next sections.</p>
+ <p class="faq">
+ <a name="delegating-classloader-1.5"></a>
+ <style> or <junit> ignores my
+ <classpath> - Ant 1.5.x version
+ </p>
+ <p>Please read <a href="#delegating-classloader">the
previous
+ entry</a> before you go ahead.</p>
+ <p>First of all let's state that Ant's wrapper script
+ (<code>ant</code> or <code>ant.bat</code>) adds all
+ <code>.jar</code> files from <code>ANT_HOME/lib</code> to
+ <code>CLASSPATH</code>, therefore "in
+ <code>CLASSPATH</code>" shall mean "either in your
+ <code>CLASSPATH</code> environment variable or
+ <code>ANT_HOME/lib</code>" for the rest of this
+ answer.</p>
+ <p>The root of the problem is that the class that
needs the
+ external library is on the <code>CLASSPATH</code>.</p>
+ <p>Let's see what happens when you load the
<junit>
+ task. Ant's class loader will consult the
bootstrap class loader first, which tries to load classes from
<code>CLASSPATH</code>. The bootstrap class loader
doesn't know anything about Ant's class loader or
even the path you have specified.</p>
<p>If the bootstrap class loader can load the class
Ant has
- asked it to load, this class will try to load the external
- library from <code>CLASSPATH</code> as well - it doesn't
- know anything else - and will not find it unless the library
- is in <code>CLASSPATH</code> as well.</p>
+ asked it to load (which it can if <code>optional.jar</code> is
+ part of <code>CLASSPATH</code>), this class will try to load
+ the external library from <code>CLASSPATH</code> as well - it
+ doesn't know anything else - and will not find it unless
+ the library is in <code>CLASSPATH</code> as well.</p>
<p>To solve this, you have two major options:</p>
<ol>
<li>put all external libraries you need in
@@ -1673,8 +1694,6 @@
<li>remove the class that loads the external library from
the <code>CLASSPATH</code>.</li>
</ol>
- <p><strong>Using The Second Option with Ant 1.5.4 and
- Earlier:</strong></p>
<p>The easiest way to do this is to remove
<code>optional.jar</code> from <code>ANT_HOME/lib</code>. If
you do so, you will have to <code><taskdef></code> all
@@ -1701,22 +1720,98 @@
directory, in the <code><style></code> case it is one of
the <code>*Liaison</code> classes in
<code>org/apache/tools/ant/taskdefs/optional</code>.</p>
- <p><strong>Using The Second Option with Ant 1.6 and
- later:</strong></p>
+ <p>If you use the option to break up
<code>optional.jar</code>
+ for <code><junit></code> or remove
+ <code>ant-junit.jar</code>, you still have to use a
+ <code><taskdef></code> with a nested
+ <code><classpath></code> to define the junit task.</p>
+ <p class="faq">
+ <a name="delegating-classloader-1.6"></a>
+ <style> or <junit> ignores my
+ <classpath> - Ant 1.6.x version
+ </p>
+ <p>Please read <a href="#delegating-classloader">the
general
+ entry</a> before you go ahead.</p>
+ <p>The wrapper script of Ant 1.6.x no longer adds
the contents
+ of <code>ANT_HOME/lib</code> to <code>CLASSPATH</code>,
+ instead Ant will create a classloader on top of the bootstrap
+ classloader - let's call it the coreloader for the rest of
+ this answer - which holds the contents of
+ <code>ANT_HOME/lib</code>. Ant's core and its tasks will be
+ loaded through this classloader and not the bootstrap
+ classloader.</p>
+ <p>This causes some small but notable differences
between Ant
+ 1.5.x and 1.6.x. Most importantly, a third-party task that is
+ part of <code>CLASSPATH</code> will no longer work in Ant
+ 1.6.x since the task now can't find Ant's classes. In a sense
+ this is the same problem this entry is about, only
+ <code>ant.jar</code> has become the external library in
+ question now.</p>
+ <p>This coreloader also holds the contents of
+ <code>~/.ant/lib</code> and any file or directory that has
+ been specified using Ant's <code>-lib</code> command line
+ argument.</p>
+ <p>Let's see what happens when you load the
<junit>
+ task. Ant's class loader will consult the bootstrap
+ class loader first, which tries to load classes from
+ <code>CLASSPATH</code>. The bootstrap class loader
+ doesn't know anything about Ant's class loader or
+ even the path you have specified. If it fails to find the
+ class using the bootstrap classloader it will try the
+ coreloader next. Again, the coreloader doesn't know anything
+ about your path.</p>
+ <p>If the coreloader can load the class Ant has
asked it to
+ load (which it can if <code>ant-junit.jar</code> is in
+ <code>ANT_HOME/lib</code>), this class will try to load the
+ external library from coreloader as well - it doesn't
+ know anything else - and will not find it unless the library
+ is in <code>CLASSPATH</code> or the coreloader as well.</p>
+ <p>To solve this, you have the following major
options:</p>
+ <ol>
+ <li>put all external libraries you need in
+ <code>CLASSPATH</code> as well this is not what you want,
+ otherwise you wouldn't have found this FAQ entry.</li>
+
+ <li>put all external libraries you need in
+ <code>ANT_HOME/lib</code> or <code>.ant/lib</code>. This
+ probably still isn't what you want, but you might reconsider
+ the <code>.ant/lib</code> option.</li>
+
+ <li>Always start Ant with the <code>-lib</code> command line
+ switch and point to your external libraries (or the
+ directories holding them).</li>
+
+ <li>remove the class that loads the external library from
+ the coreloader.</li>
+ </ol>
<p>In Ant 1.6 <code>optional.jar</code> has been
split into
multiple jars, each one containing classes with the same
dependencies on external libraries. You can move the
- "offending" jar out of ANT_HOME/lib. For the
+ "offending" jar out of <code>ANT_HOME/lib</code>. For the
<code><junit></code> task it would be
<code>ant-junit.jar</code> and for <code><style></code>
it would be <code>ant-trax.jar</code>,
<code>ant-xalan1.jar</code> or <code>ant-xslp.jar</code> -
depending on the processor you use.</p>
- <p>If you use the option to break up
<code>optional.jar</code>
- for <code><junit></code> or remove
- <code>ant-junit.jar</code>, you still have to use a
- <code><taskdef></code> with a nested
- <code><classpath></code> to define the junit task.</p>
+ <p>If you do so, you will have to
<code><taskdef></code>
+ all optional tasks that need the external libary and use
+ nested <code><classpath></code> elements in the
+ <code><taskdef></code> tasks that point to the new
+ location of <code>ant-*.jar</code>. Also, don't forget
+ to add the new location of <code>ant-*.jar</code> to the
+ <code><classpath></code> of your
+ <code><style></code> or <code><junit></code>
+ task.</p>
+ <p>For example</p>
+ <pre class="code">
+ <taskdef name="junit"
+
class="org.apache.tools.ant.taskdefs.optional.junit.JUnitTask">
+ <classpath>
+ <pathelement location="HOME-OF/junit.jar"/>
+ <pathelement location="NEW-HOME-OF/ant-junit.jar"/>
+ </classpath>
+ </taskdef>
+</pre>
<p class="faq">
<a name="winxp-jdk14-ant14"></a>
When running Ant 1.4 on Windows XP and JDK 1.4, I get
No revision
No revision
1.38.2.22 +139 -37 ant/xdocs/faq.xml
Index: faq.xml
===================================================================
RCS file: /home/cvs/ant/xdocs/faq.xml,v
retrieving revision 1.38.2.21
retrieving revision 1.38.2.22
diff -u -r1.38.2.21 -r1.38.2.22
--- faq.xml 28 Apr 2005 13:12:30 -0000 1.38.2.21
+++ faq.xml 10 May 2005 07:39:37 -0000 1.38.2.22
@@ -1346,36 +1346,26 @@
<p>These tasks don't ignore your classpath setting, you
are facing a common problem with delegating classloaders.</p>
- <p>First of all let's state that Ant adds all
- <code>.jar</code> files from <code>ANT_HOME/lib</code> to
- <code>CLASSPATH</code>, therefore "in
- <code>CLASSPATH</code>" shall mean "either in your
- <code>CLASSPATH</code> environment variable or
- <code>ANT_HOME/lib</code>" for the rest of this
- answer.</p>
-
- <p>Technically the sentence above isn't true for Ant 1.6
- and later anymore, but the result is the same. For the sake
- of this discussion, <code>CLASSPATH</code> and
- <code>ANT_HOME/lib</code> are identical.</p>
-
<p>This question collects a common type of problem: A task
needs an external library and it has a nested classpath
element so that you can point it to this external library, but
- that doesn't work unless you put the external library into the
- <code>CLASSPATH</code>.</p>
-
- <p>The root of the problem is that the class that needs the
- external library is on the <code>CLASSPATH</code>.</p>
+ that doesn't work unless you put the external library
+ into the <code>CLASSPATH</code> or place it in
+ <code>ANT_HOME/lib</code>.</p>
+
+ <p>Some background is necessary before we can discuss
+ solutions for <a href="#delegating-classloader-1.5">Ant
+ 1.5.x</a> and <a href="#delegating-classloader-1.6">Ant
+ 1.6.x</a>.</p>
<p>When you specify a nested <code><classpath></code> in
Ant, Ant creates a new class loader that uses the path you
have specified. It then tries to load additional classes from
this classloader.</p>
- <p>In most cases - for example the two cases above - Ant
- doesn't load the external library directly, it is the loaded
- class that does so.</p>
+ <p>In most cases - for example using <style> or
+ <junit> - Ant doesn't load the external library
+ directly, it is the loaded class that does so.</p>
<p>In the case of <code><junit></code> it is the task
implementation itself and in the case of
@@ -1400,17 +1390,45 @@
the parent of a <code>ClassLoader</code>
instance.</blockquote>
- <p>This means, Ant's class loader will consult the
+ <p>The possible solutions depend on the version of Ant you
+ use, see the next sections.</p>
+ </answer>
+ </faq>
+
+ <faq id="delegating-classloader-1.5">
+ <question><style> or <junit> ignores my
+ <classpath> - Ant 1.5.x version</question>
+
+ <answer>
+
+ <p>Please read <a href="#delegating-classloader">the previous
+ entry</a> before you go ahead.</p>
+
+ <p>First of all let's state that Ant's wrapper script
+ (<code>ant</code> or <code>ant.bat</code>) adds all
+ <code>.jar</code> files from <code>ANT_HOME/lib</code> to
+ <code>CLASSPATH</code>, therefore "in
+ <code>CLASSPATH</code>" shall mean "either in your
+ <code>CLASSPATH</code> environment variable or
+ <code>ANT_HOME/lib</code>" for the rest of this
+ answer.</p>
+
+ <p>The root of the problem is that the class that needs the
+ external library is on the <code>CLASSPATH</code>.</p>
+
+ <p>Let's see what happens when you load the <junit>
+ task. Ant's class loader will consult the
bootstrap class loader first, which tries to load classes from
<code>CLASSPATH</code>. The bootstrap class loader
doesn't know anything about Ant's class loader or
even the path you have specified.</p>
<p>If the bootstrap class loader can load the class Ant has
- asked it to load, this class will try to load the external
- library from <code>CLASSPATH</code> as well - it doesn't
- know anything else - and will not find it unless the library
- is in <code>CLASSPATH</code> as well.</p>
+ asked it to load (which it can if <code>optional.jar</code> is
+ part of <code>CLASSPATH</code>), this class will try to load
+ the external library from <code>CLASSPATH</code> as well - it
+ doesn't know anything else - and will not find it unless
+ the library is in <code>CLASSPATH</code> as well.</p>
<p>To solve this, you have two major options:</p>
@@ -1423,9 +1441,6 @@
the <code>CLASSPATH</code>.</li>
</ol>
- <p><strong>Using The Second Option with Ant 1.5.4 and
- Earlier:</strong></p>
-
<p>The easiest way to do this is to remove
<code>optional.jar</code> from <code>ANT_HOME/lib</code>. If
you do so, you will have to <code><taskdef></code> all
@@ -1455,24 +1470,111 @@
the <code>*Liaison</code> classes in
<code>org/apache/tools/ant/taskdefs/optional</code>.</p>
- <p><strong>Using The Second Option with Ant 1.6 and
- later:</strong></p>
+ <p>If you use the option to break up <code>optional.jar</code>
+ for <code><junit></code> or remove
+ <code>ant-junit.jar</code>, you still have to use a
+ <code><taskdef></code> with a nested
+ <code><classpath></code> to define the junit task.</p>
+ </answer>
+ </faq>
+
+ <faq id="delegating-classloader-1.6">
+ <question><style> or <junit> ignores my
+ <classpath> - Ant 1.6.x version</question>
+
+ <answer>
+ <p>Please read <a href="#delegating-classloader">the general
+ entry</a> before you go ahead.</p>
+
+ <p>The wrapper script of Ant 1.6.x no longer adds the contents
+ of <code>ANT_HOME/lib</code> to <code>CLASSPATH</code>,
+ instead Ant will create a classloader on top of the bootstrap
+ classloader - let's call it the coreloader for the rest of
+ this answer - which holds the contents of
+ <code>ANT_HOME/lib</code>. Ant's core and its tasks will be
+ loaded through this classloader and not the bootstrap
+ classloader.</p>
+
+ <p>This causes some small but notable differences between Ant
+ 1.5.x and 1.6.x. Most importantly, a third-party task that is
+ part of <code>CLASSPATH</code> will no longer work in Ant
+ 1.6.x since the task now can't find Ant's classes. In a sense
+ this is the same problem this entry is about, only
+ <code>ant.jar</code> has become the external library in
+ question now.</p>
+
+ <p>This coreloader also holds the contents of
+ <code>~/.ant/lib</code> and any file or directory that has
+ been specified using Ant's <code>-lib</code> command line
+ argument.</p>
+
+ <p>Let's see what happens when you load the <junit>
+ task. Ant's class loader will consult the bootstrap
+ class loader first, which tries to load classes from
+ <code>CLASSPATH</code>. The bootstrap class loader
+ doesn't know anything about Ant's class loader or
+ even the path you have specified. If it fails to find the
+ class using the bootstrap classloader it will try the
+ coreloader next. Again, the coreloader doesn't know anything
+ about your path.</p>
+
+ <p>If the coreloader can load the class Ant has asked it to
+ load (which it can if <code>ant-junit.jar</code> is in
+ <code>ANT_HOME/lib</code>), this class will try to load the
+ external library from coreloader as well - it doesn't
+ know anything else - and will not find it unless the library
+ is in <code>CLASSPATH</code> or the coreloader as well.</p>
+
+ <p>To solve this, you have the following major options:</p>
+
+ <ol>
+ <li>put all external libraries you need in
+ <code>CLASSPATH</code> as well this is not what you want,
+ otherwise you wouldn't have found this FAQ entry.</li>
+
+ <li>put all external libraries you need in
+ <code>ANT_HOME/lib</code> or <code>.ant/lib</code>. This
+ probably still isn't what you want, but you might reconsider
+ the <code>.ant/lib</code> option.</li>
+
+ <li>Always start Ant with the <code>-lib</code> command line
+ switch and point to your external libraries (or the
+ directories holding them).</li>
+
+ <li>remove the class that loads the external library from
+ the coreloader.</li>
+ </ol>
<p>In Ant 1.6 <code>optional.jar</code> has been split into
multiple jars, each one containing classes with the same
dependencies on external libraries. You can move the
- "offending" jar out of ANT_HOME/lib. For the
+ "offending" jar out of <code>ANT_HOME/lib</code>. For the
<code><junit></code> task it would be
<code>ant-junit.jar</code> and for <code><style></code>
it would be <code>ant-trax.jar</code>,
<code>ant-xalan1.jar</code> or <code>ant-xslp.jar</code> -
depending on the processor you use.</p>
- <p>If you use the option to break up <code>optional.jar</code>
- for <code><junit></code> or remove
- <code>ant-junit.jar</code>, you still have to use a
- <code><taskdef></code> with a nested
- <code><classpath></code> to define the junit task.</p>
+ <p>If you do so, you will have to <code><taskdef></code>
+ all optional tasks that need the external libary and use
+ nested <code><classpath></code> elements in the
+ <code><taskdef></code> tasks that point to the new
+ location of <code>ant-*.jar</code>. Also, don't forget
+ to add the new location of <code>ant-*.jar</code> to the
+ <code><classpath></code> of your
+ <code><style></code> or <code><junit></code>
+ task.</p>
+
+ <p>For example</p>
+ <source><![CDATA[
+ <taskdef name="junit"
+ class="org.apache.tools.ant.taskdefs.optional.junit.JUnitTask">
+ <classpath>
+ <pathelement location="HOME-OF/junit.jar"/>
+ <pathelement location="NEW-HOME-OF/ant-junit.jar"/>
+ </classpath>
+ </taskdef>
+]]></source>
</answer>
</faq>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
