| <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> |
| |
| <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 following tests have been run when build Ant itself, on the |
| author's machine using JDK1.3 </p> |
| |
| <table border="1" cellpadding="2" cellspacing="0"> |
| <tr> |
| <td>Building Ant from clean using Javac</td> |
| <td>11 seconds</td> |
| </tr> |
| <tr> |
| <td>Building Ant from clean using Jikes</td> |
| <td>5 seconds</td> |
| </tr> |
| <tr> |
| <td>Running <depend> when up-to-date and no cache</td> |
| <td>4 seconds (Depend takes 2 seconds)</td> |
| </tr> |
| <tr> |
| <td>Running <depend> when up-to-date and with a cache</td> |
| <td>2 seconds (Depend takes 1 seconds)</td> |
| </tr> |
| </table> |
| |
| <p> This involves compiling 177 files. The above figures are indicative only. |
| 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 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. If you use multiple |
| source directories you can pass this 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> |
| </table> |
| |
| <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> |
| |