PageRenderTime 198ms CodeModel.GetById 19ms RepoModel.GetById 2ms app.codeStats 0ms

/projects/ant-1.8.2/docs/manual/Tasks/depend.html

https://gitlab.com/essere.lab.public/qualitas.class-corpus
HTML | 216 lines | 170 code | 30 blank | 16 comment | 0 complexity | c8fe4133bfbe272732343ce11d5862d3 MD5 | raw file
  1. <!--
  2. Licensed to the Apache Software Foundation (ASF) under one or more
  3. contributor license agreements. See the NOTICE file distributed with
  4. this work for additional information regarding copyright ownership.
  5. The ASF licenses this file to You under the Apache License, Version 2.0
  6. (the "License"); you may not use this file except in compliance with
  7. the License. You may obtain a copy of the License at
  8. http://www.apache.org/licenses/LICENSE-2.0
  9. Unless required by applicable law or agreed to in writing, software
  10. distributed under the License is distributed on an "AS IS" BASIS,
  11. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12. See the License for the specific language governing permissions and
  13. limitations under the License.
  14. -->
  15. <html>
  16. <head>
  17. <meta http-equiv="Content-Language" content="en-us">
  18. <link rel="stylesheet" type="text/css" href="../stylesheets/style.css">
  19. <title>Depend Task</title>
  20. </head>
  21. <body>
  22. <h2>Depend</h2>
  23. A task to manage Java class file dependencies.
  24. <h3>Description</h3>
  25. <p>
  26. The depend task works by determining which classes are out of date with
  27. respect to their source and then removing the class files of any other
  28. classes which depend on the out-of-date classes.
  29. </p>
  30. <p> To determine the class dependencies, the depend task analyses the class
  31. files of all class files passed to it. Depend does not parse your source code in
  32. any way but relies upon the class references encoded into the class files by the
  33. compiler. This is generally faster than parsing the Java source.</p>
  34. <p>
  35. To learn more about how this information is obtained from the class files,
  36. please refer to <a href="http://java.sun.com/docs/books/jvms/">the Java
  37. Virtual Machine Specification</a>
  38. </p>
  39. <p> Since a class' dependencies only change when the class itself changes, the
  40. depend task is able to cache dependency information. Only those class files
  41. which have changed will have their dependency information re-analysed. Note that
  42. if you change a class' dependencies by changing the source, it will be
  43. recompiled anyway. You can examine the dependency files created to understand
  44. the dependencies of your classes. Please do not rely, however, on the format of
  45. the information, as it may change in a later release. </p>
  46. <p> Once depend discovers all of the class dependencies, it &quot;inverts&quot;
  47. this relation to determine, for each class, which other classes are dependent
  48. upon it. This &quot;affects&quot; list is used to discover which classes are
  49. invalidated by the out of date class. The class files of the invalidated
  50. classes are removed, triggering the compilation of the affected classes. </p>
  51. <p> The depend task supports an attribute, &quot;closure&quot; which controls
  52. whether depend will only consider direct class-class relationships or whether it
  53. will also consider transitive, indirect relationships. For example, say there
  54. are three classes, A, which depends on B, which in-turn depend on C. Now say
  55. that class C is out of date. Without closure, only class B would be removed by
  56. depend. With closure set, class A would also be removed. Normally direct
  57. relationships are sufficient - it is unusual for a class to depend on another
  58. without having a direct relationship. With closure set, you will notice that
  59. depend typically removes far more class files. </p>
  60. <p>The classpath attribute for <code>&lt;depend&gt;</code> is optional. If it is present,
  61. depend will check class dependencies against classes and jars on this classpath.
  62. Any classes which depend on an element from this classpath and which are older
  63. than that element will be deleted. A typical example where you would use this
  64. facility would be where you are building a utility jar and want to make sure
  65. classes which are out of date with respect to this jar are rebuilt. You should
  66. <b>not</b> include jars in this classpath which you do not expect to change,
  67. such as the JDK runtime jar or third party jars, since doing so will just slow
  68. down the dependency check. This means that if you do use a classpath for the
  69. depend task it may be different from the classpath necessary to actually
  70. compile your code.</p>
  71. <h3>Performance</h3>
  72. <p> The performance of the depend task is dependent on a
  73. number of factors such as class relationship complexity and how many class files
  74. are out of date. The decision about whether it is cheaper to just recompile all
  75. classes or to use the depend task will depend on the size of your project and
  76. how interrelated your classes are. </p>
  77. <h3>Limitations</h3>
  78. <p> There are some source dependencies which depend will not detect. </p>
  79. <ul>
  80. <li>If the Java compiler optimizes away a class relationship,
  81. there can be a source dependency without a class dependency. </li>
  82. <li>Non public classes cause two problems. Firstly depend cannot relate
  83. the class file to a source file. In the future this may be addressed
  84. using the source file attribute in the classfile. Secondly, neither
  85. depend nor the compiler tasks can detect when a non public class is
  86. missing. Inner classes are handled by the depend task.</li>
  87. </ul>
  88. The most obvious example of these limitations is that the task can't tell
  89. which classes to recompile when a constant primitive data type exported
  90. by other classes is changed. For example, a change in the definition of
  91. something like
  92. <pre>
  93. public final class Constants {
  94. public final static boolean DEBUG=false;
  95. }
  96. </pre> will not be picked up by other classes.
  97. <h3>Parameters</h3>
  98. <table border="1" cellpadding="2" cellspacing="0">
  99. <tr>
  100. <td valign="top"><b>Attribute</b></td>
  101. <td valign="top"><b>Description</b></td>
  102. <td align="center" valign="top"><b>Required</b></td>
  103. </tr>
  104. <tr>
  105. <td valign="top">srcDir</td>
  106. <td valign="top">This is the directory where the source exists. depend
  107. will examine this to determine which classes are out of date. If you use multiple
  108. source directories you can pass this attribute a path of source directories.</td>
  109. <td valign="top" align="center">Yes</td>
  110. </tr>
  111. <tr>
  112. <td valign="top">destDir</td>
  113. <td valign="top">This is the root directory of the class files which
  114. will be analysed. If this is not present, the srcdir is used.</td>
  115. <td valign="top" align="center">No</td>
  116. </tr>
  117. <tr>
  118. <td valign="top">cache</td>
  119. <td valign="top">This is a directory in which depend can store and
  120. retrieve dependency information. If this is not present, depend will not
  121. use a cache </td>
  122. <td valign="top" align="center">No</td>
  123. </tr>
  124. <tr>
  125. <td valign="top">closure</td>
  126. <td valign="top">This attribute controls whether depend only removes
  127. classes which directly depend on out of date classes. If this is set to true,
  128. depend will traverse the class dependency graph deleting all affected
  129. classes. Defaults to false</td>
  130. <td valign="top" align="center">No</td>
  131. </tr>
  132. <tr>
  133. <td valign="top">dump</td>
  134. <td valign="top">If true the dependency information will be written to the debug level log
  135. </td>
  136. <td valign="top" align="center">No</td>
  137. </tr>
  138. <tr>
  139. <td valign="top">classpath</td>
  140. <td valign="top">The classpath containing jars and classes for which <code>&lt;depend&gt;</code> should also
  141. check dependencies</td>
  142. <td valign="top" align="center">No</td>
  143. </tr>
  144. <tr>
  145. <td valign="top">warnOnRmiStubs</td>
  146. <td valign="top">Flag to disable warnings about files that look like rmic generated stub/skeleton
  147. classes, and which have no .java source. Useful when doing rmi development. </td>
  148. <td valign="top" align="center">No, default=true</td>
  149. </tr>
  150. </table>
  151. <h3>Parameters specified as nested elements</h3>
  152. <p>The <code>depend</code> task's <code>classpath</code> attribute is a
  153. <a href="../using.html#path">PATH-like structure</a> and can also be set
  154. via a nested <code>&lt;classpath&gt;</code> element.</p>
  155. <p>Additionally,
  156. this task forms an implicit
  157. <a href="../Types/fileset.html">FileSet</a>
  158. and supports most attributes of
  159. <code>&lt;fileset&gt;</code> (<code>dir</code> becomes <code>srcdir</code>),
  160. as well as the nested <code>&lt;include&gt;</code>,
  161. <code>&lt;exclude&gt;</code>, and <code>&lt;patternset&gt;</code> elements.
  162. <h3>Examples</h3>
  163. <pre>&lt;depend srcdir=&quot;${java.dir}&quot;
  164. destdir=&quot;${build.classes}&quot;
  165. cache=&quot;depcache&quot;
  166. closure=&quot;yes&quot;/&gt;</pre>
  167. <p>removes any classes in the <code>${build.classes}</code> directory
  168. that depend on out-of-date classes. Classes are considered out-of-date with
  169. respect to the source in the <code>${java.dir}</code> directory, using the same
  170. mechanism as the <code>&lt;javac&gt;</code> task. In this example, the
  171. <code>&lt;depend&gt;</code> task caches its dependency
  172. information in the <code>depcache</code> directory. </p>
  173. <pre>
  174. &lt;depend srcdir=&quot;${java.dir}&quot; destdir=&quot;${build.classes}&quot;
  175. cache=&quot;depcache&quot; closure=&quot;yes&quot;&gt;
  176. &lt;include name=&quot;**/*.java&quot;/&gt;
  177. &lt;excludesfile name=&quot;${java.dir}/build_excludes&quot;/&gt;
  178. &lt;/depend&gt;
  179. </pre>
  180. <p>does the same as the previous example, but explicitly includes all
  181. <code>.java</code> files, except those that match the list given
  182. in <code>${java.dir}/build_excludes</code>.</p>
  183. </body>
  184. </html>