diff options
Diffstat (limited to 'framework/src/ant/apache-ant-1.9.6/manual/Tasks/depend.html')
| -rw-r--r-- | framework/src/ant/apache-ant-1.9.6/manual/Tasks/depend.html | 216 |
1 files changed, 216 insertions, 0 deletions
diff --git a/framework/src/ant/apache-ant-1.9.6/manual/Tasks/depend.html b/framework/src/ant/apache-ant-1.9.6/manual/Tasks/depend.html new file mode 100644 index 00000000..a0943197 --- /dev/null +++ b/framework/src/ant/apache-ant-1.9.6/manual/Tasks/depend.html @@ -0,0 +1,216 @@ +<!-- + 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 + + http://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> + +<head> +<meta http-equiv="Content-Language" content="en-us"> +<link rel="stylesheet" type="text/css" href="../stylesheets/style.css"> +<title>Depend Task</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 analyzes 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://docs.oracle.com/javase/specs/">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> + +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 +<pre> +public final class Constants { + public final static boolean DEBUG=false; +} +</pre> will not be picked up by other classes. + +<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 containing jars and classes for which <code><depend></code> should also + check dependencies</td> + <td valign="top" align="center">No</td> + </tr> + <tr> + <td valign="top">warnOnRmiStubs</td> + <td valign="top">Flag to disable warnings about files that look like rmic generated stub/skeleton + classes, and which have no .java source. Useful when doing rmi development. </td> + <td valign="top" align="center">No, default=true</td> + </tr> +</table> + +<h3>Parameters specified as nested elements</h3> +<p>The <code>depend</code> task's <code>classpath</code> 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> (<code>dir</code> becomes <code>srcdir</code>), +as well as the nested <code><include></code>, +<code><exclude></code>, and <code><patternset></code> elements. + +<h3>Examples</h3> +<pre><depend srcdir="${java.dir}" + destdir="${build.classes}" + cache="depcache" + closure="yes"/></pre> + +<p>removes any classes in the <code>${build.classes}</code> directory +that depend on out-of-date classes. Classes are considered out-of-date with +respect to the source in the <code>${java.dir}</code> 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 <code>depcache</code> directory. </p> + +<pre> +<depend srcdir="${java.dir}" destdir="${build.classes}" + cache="depcache" closure="yes"> + <include name="**/*.java"/> + <excludesfile name="${java.dir}/build_excludes"/> +</depend> +</pre> +<p>does the same as the previous example, but explicitly includes all +<code>.java</code> files, except those that match the list given +in <code>${java.dir}/build_excludes</code>.</p> + + + +</body> +</html> + |