| <!DOCTYPE html> |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to You under the Apache License, Version 2.0 |
| (the "License"); you may not use this file except in compliance with |
| the License. You may obtain a copy of the License at |
| |
| https://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| <html lang="en"> |
| |
| <head> |
| <link rel="stylesheet" type="text/css" href="../stylesheets/style.css"> |
| <title>Depend Task</title> |
| </head> |
| |
| <body> |
| |
| <h2>Depend</h2> |
| |
| <p>A task to manage Java class file dependencies.</p> |
| |
| <h3>Description</h3> |
| |
| <p>The <code>depend</code> 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 <code>depend</code> task analyzes the class files of all |
| class files passed to it. The task 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 files.</p> |
| |
| <p>To learn more about how this information is obtained from the class files, please refer |
| to <a href="https://docs.oracle.com/javase/specs/" target="_top">the Java Virtual Machine |
| Specification</a></p> |
| |
| <p>Since a class' dependencies only change when the class itself changes, the |
| <code>depend</code> 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 <code>depend</code> 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 <code>depend</code> task supports an attribute, <var>closure</var>, which controls |
| whether <code>depend</code> 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 depends on C. Now say that class C is out of |
| date. Without <var>closure</var>, only class B would be removed |
| by <code>depend</code>. With <var>closure</var> 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 <var>closure</var> set, you will notice that <code>depend</code> typically |
| removes far more class files.</p> |
| |
| <p>The <var>classpath</var> attribute for <code><depend></code> is optional. If it is |
| present, <code>depend</code> 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. In this classpath, you should <strong>not</strong> include jars that 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 <code>depend</code> task it may |
| be different from the classpath necessary to actually compile your code.</p> |
| |
| <h3>Performance</h3> |
| |
| <p>The performance of the <code>depend</code> 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 <code>depend</code> 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 <code>depend</code> 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 <code>depend</code> nor the compiler tasks can detect when a non-public |
| class is missing. Inner classes are handled by the <code>depend</code> task.</li> |
| </ul> |
| |
| <p>The most obvious example of these limitations is that the task can't tell which classes to |
| recompile when a constant primitive data type exported by other classes is changed. For example, a |
| change in the definition of something like</p> |
| <pre> |
| public final class Constants { |
| public final static boolean DEBUG=false; |
| }</pre> |
| <p>will not be picked up by other classes.</p> |
| |
| <h3>Parameters</h3> |
| <table class="attr"> |
| <tr> |
| <th scope="col">Attribute</th> |
| <th scope="col">Description</th> |
| <th scope="col">Required</th> |
| </tr> |
| <tr> |
| <td>srcDir</td> |
| <td>This is the directory where the source exists. <code>depend</code> 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>Yes</td> |
| </tr> |
| <tr> |
| <td>destDir</td> |
| <td>This is the root directory of the class files which will be analysed.</td> |
| <td>No; defaults to <var>srcdir</var></td> |
| </tr> |
| <tr> |
| <td>cache</td> |
| <td>This is a directory in which <code>depend</code> can store and retrieve dependency |
| information.</td> |
| <td>No; defaults to no cache</td> |
| </tr> |
| <tr> |
| <td>closure</td> |
| <td>This attribute controls whether <code>depend</code> only removes classes which directly |
| depend on out of date classes. If this is set to <q>true</q>, <code>depend</code> will |
| traverse the class dependency graph deleting all affected classes.</td> |
| <td>No; defaults to <q>false</q></td> |
| </tr> |
| <tr> |
| <td>dump</td> |
| <td>If true the dependency information will be written to the debug level log</td> |
| <td>No; default is <q>false</q></td> |
| </tr> |
| <tr> |
| <td>classpath</td> |
| <td>The classpath containing jars and classes for which <code><depend></code> should also |
| check dependencies</td> |
| <td>No</td> |
| </tr> |
| <tr> |
| <td>warnOnRmiStubs</td> |
| <td>Flag to disable warnings about files that look like <kbd>rmic</kbd> generated |
| stub/skeleton classes and have no <samp>.java</samp> source. Useful when doing RMI |
| development.</td> |
| <td>No; default <q>true</q></td> |
| </tr> |
| </table> |
| |
| <h3>Parameters specified as nested elements</h3> |
| <p>The <code>depend</code> task's <var>classpath</var> attribute is |
| a <a href="../using.html#path">path-like structure</a> and can also be set via a |
| nested <code><classpath></code> element.</p> |
| |
| <p>Additionally, this task forms an implicit <a href="../Types/fileset.html">FileSet</a> and |
| supports most attributes of <code><fileset></code> (<var>dir</var> becomes <var>srcdir</var>), |
| as well as the nested <code><include></code>, <code><exclude></code>, |
| and <code><patternset></code> elements.</p> |
| |
| <h3>Examples</h3> |
| |
| <p>Remove any classes in the <samp>${build.classes}</samp> directory that depend on out-of-date |
| classes. Classes are considered out-of-date with respect to the source in |
| the <samp>${java.dir}</samp> directory, using the same mechanism as the <code><javac></code> |
| task. In this example, the <code><depend></code> task caches its dependency information in |
| the <samp>depcache</samp> directory.</p> |
| <pre> |
| <depend srcdir="${java.dir}" |
| destdir="${build.classes}" |
| cache="depcache" |
| closure="yes"/></pre> |
| |
| <p>Do the same as the previous example, but explicitly include all <samp>.java</samp> files, except |
| those that match the list given in <samp>${java.dir}/build_excludes</samp>.</p> |
| <pre> |
| <depend srcdir="${java.dir}" destdir="${build.classes}" |
| cache="depcache" closure="yes"> |
| <include name="**/*.java"/> |
| <excludesfile name="${java.dir}/build_excludes"/> |
| </depend></pre> |
| |
| </body> |
| </html> |