| <html> |
| |
| <head> |
| <meta http-equiv="Content-Language" content="en-us"> |
| <title>Ant User Manual</title> |
| </head> |
| |
| <body> |
| |
| <h2>Depend</h2> |
| |
| A task to manage Java class file dependencies. |
| |
| <h3>Description</h3> |
| |
| <p> |
| The depend task works by determining which classes are out of date with |
| respect to their source and then removing the class files of any other |
| classes which depend on the out-of-date classes. |
| </p> |
| |
| <p> To determine the class dependencies, the depend task analyses the class |
| files of all class files passed to it. Depend does not parse your source code in |
| any way but relies upon the class references encoded into the class files by the |
| compiler. This is generally faster than parsing the Java source.</p> |
| |
| <p> |
| To learn more about how this information is obtained from the class files, |
| please refer to <a href="http://java.sun.com/docs/books/vmspec/">the Java |
| Virtual Machine Specification</a> |
| </p> |
| |
| <p> Since a class' dependencies only change when the class itself changes, the |
| depend task is able to cache dependency information. Only those class files |
| which have changed will have their dependency information re-analysed. Note that |
| if you change a class' dependencies by changing the source, it will be |
| recompiled anyway. You can examine the dependency files created to understand |
| the dependencies of your classes. Please do not rely, however, on the format of |
| the information, as it may change in a later release. </p> |
| |
| <p> Once depend discovers all of the class dependencies, it "inverts" |
| this relation to determine, for each class, which other classes are dependent |
| upon it. This "affects" list is used to discover which classes are |
| invalidated by the out of date class. The class files of the invalidated |
| classes are removed, triggering the compilation of the affected classes. </p> |
| |
| <p> The depend task supports an attribute, "closure" which controls |
| whether depend will only consider direct class-class relationships or whether it |
| will also consider transitive, indirect relationships. For example, say there |
| are three classes, A, which depends on B, which in-turn depend on C. Now say |
| that class C is out of date. Without closure, only class B would be removed by |
| depend. With closure set, class A would also be removed. Normally direct |
| relationships are sufficient - it is unusual for a class to depend on another |
| without having a direct relationship. With closure set, you will notice that |
| depend typically removes far more class files. </p> |
| |
| <p>The classpath attribute for <code><depend></code> is optional. If it is present, |
| depend will check class dependencies against classes and jars on this classpath. |
| Any classes which depend on an element from this classpath and which are older |
| than that element will be deleted. A typical example where you would use this |
| facility would be where you are building a utility jar and want to make sure |
| classes which are out of date with respect to this jar are rebuilt. You should |
| <b>not</b> include jars in this classpath which you do not expect to change, |
| such as the JDK runtime jar or third party jars, since doing so will just slow |
| down the dependency check. This means that if you do use a classpath for the |
| depend task it may be different from the classpath necessary to actually |
| compile your code.</p> |
| |
| <h3>Performance</h3> |
| |
| <p> The performance of the depend task is dependent on a |
| number of factors such as class relationship complexity and how many class files |
| are out of date. The decision about whether it is cheaper to just recompile all |
| classes or to use the depend task will depend on the size of your project and |
| how interrelated your classes are. </p> |
| |
| |
| <h3>Limitations</h3> |
| |
| <p> There are some source dependencies which depend will not detect. </p> |
| |
| <ul> |
| <li>If the Java compiler optimizes away a class relationship, |
| there can be a source dependency without a class dependency. </li> |
| |
| <li>Non public classes cause two problems. Firstly depend cannot relate |
| the class file to a source file. In the future this may be addressed |
| using the source file attribute in the classfile. Secondly, neither |
| depend nor the compiler tasks can detect when a non public class is |
| missing. Inner classes are handled by the depend task.</li> |
| </ul> |
| |
| |
| <h3>Parameters</h3> |
| <table 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">srcDir</td> |
| <td valign="top">This is the directory where the source exists. depend |
| will examine this to determine which classes are out of date. If you use multiple |
| source directories you can pass this attribute a path of source directories.</td> |
| <td valign="top" align="center">Yes</td> |
| </tr> |
| <tr> |
| <td valign="top">destDir</td> |
| <td valign="top">This is the root directory of the class files which |
| will be analysed. If this is not present, the srcdir is used.</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">cache</td> |
| <td valign="top">This is a directory in which depend can store and |
| retrieve dependency information. If this is not present, depend will not |
| use a cache </td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">closure</td> |
| <td valign="top">This attribute controls whether depend only removes |
| classes which directly depend on out of date classes. If this is set to true, |
| depend will traverse the class dependency graph deleting all affected |
| classes. Defaults to false</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">dump</td> |
| <td valign="top">If true the dependency information will be written to the debug level log |
| </td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">classpath</td> |
| <td valign="top">The classpath containg jars and classes for which <code><depend></code> should also |
| check dependencies</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| </table> |
| |
| <h3>Nested Elements</h3> |
| <p><code>depend</code>'s <i>classpath</i> attribute is a |
| <a href="../using.html#path">PATH like structure</a> and can also be set |
| via a nested <i>classpath</i> element.</p> |
| |
| <h3>Examples</h3> |
| <blockquote> |
| <pre><depend srcdir="${java.dir}" |
| destdir="${build.classes}" |
| cache="depcache" |
| closure="yes"/></pre> |
| </blockquote> |
| |
| <p> In this example classes in the ${build.classes} directory will be removed if |
| they depend on out-of-date classes. Classes are considered out of date with |
| respect to the source in the ${java.dir} directory using the same mechanism as |
| the javac task. In this instance the depend task caches its dependency |
| information in the depcache directory. </p> |
| |
| <hr> |
| <p align="center">Copyright © 2000,2001 Apache Software Foundation. |
| All rights |
| Reserved.</p> |
| |
| </body> |
| </html> |
| |