youys
/
ant

 
			
							<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 &quot;inverts&quot; 
this relation to determine, for each class, which other classes are dependent 
upon it. This &quot;affects&quot; 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, &quot;closure&quot; 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 &lt;depend&gt; when up-to-date and no cache</td>
    <td>4 seconds (Depend takes 2 seconds)</td>
  </tr>
  <tr>
    <td>Running &lt;depend&gt; 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>    &lt;depend srcdir=&quot;${java.dir}&quot;
    destdir=&quot;${build.classes}&quot;
    cache=&quot;depcache&quot;
    closure=&quot;yes&quot;/&gt;</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 &copy; 2000,2001 Apache Software Foundation.
All rights
Reserved.</p>

</body>
</html>