You can not select more than 25 topics Topics must start with a chinese character,a letter or number, can include dashes ('-') and can be up to 35 characters long.

import.html 11 KiB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349
  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. <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
  16. <html>
  17. <head>
  18. <meta http-equiv="Content-Language" content="en-us">
  19. <link rel="stylesheet" type="text/css" href="../stylesheets/style.css">
  20. <title>Import Task</title>
  21. </head>
  22. <body>
  23. <h2><a name="import">Import</a></h2>
  24. <h3>Description</h3>
  25. <p>
  26. Imports another build file into the current project.
  27. </p>
  28. <p>
  29. On execution it will select the proper ProjectHelper to parse the imported
  30. file, using the same algorithm as the one executed at
  31. <a href="../projecthelper.html">startup</a>. The selected ProjectHelper
  32. instance will then be responsible to actually parse the imported file.
  33. </p>
  34. <p>
  35. <b>Note</b> as seen above, this task heavily relies on the ProjectHelper
  36. implementation and doesn't really perform any work of its own. If
  37. you have configured Ant to use a ProjectHelper other than Ant's
  38. default, this task may or may not work.
  39. </p>
  40. <p>
  41. In the common use case where only Ant's default project helper is
  42. used, it basically works like the
  43. <a href="http://ant.apache.org/faq.html#xml-entity-include">Entity
  44. Includes as explained in the Ant FAQ</a>, as if the imported file was
  45. contained in the importing file, minus the top <code>&lt;project&gt;</code>
  46. tag.
  47. </p>
  48. <p>
  49. The import task may only be used as a top-level task. This means that
  50. it may not be used in a target.
  51. </p>
  52. <p>
  53. There are two further functional aspects that pertain to this task and
  54. that are not possible with entity includes:
  55. <ul>
  56. <li>target overriding</li>
  57. <li>special properties</li>
  58. </ul>
  59. </p>
  60. <h4>Target overriding</h4>
  61. <p>If a target in the main file is also present in at least one of the
  62. imported files, the one from the main file takes precedence.</p>
  63. <p>So if I import for example a <i>docsbuild.xml</i> file named <b>builddocs</b>,
  64. that contains a &quot;<b>docs</b>&quot; target, I can redefine it in my main
  65. buildfile and that is the one that will be called. This makes it easy to
  66. keep the same target name, so that the overriding target is still called
  67. by any other targets--in either the main or imported buildfile(s)--for which
  68. it is a dependency, with a different implementation. The target from <i>docsbuild.xml</i> is
  69. made available by the name &quot;<b>builddocs</b><b>.docs</b>&quot;.
  70. This enables the new implementation to call the old target, thus
  71. <i>enhancing</i> it with tasks called before or after it.</p>
  72. <p>If you use the <i>as</i> attribute of the task, its value will be
  73. used to prefix the overriden target's name instead of the name
  74. attribute of the project tag.</p>
  75. <h4>Special Properties</h4>
  76. <p>Imported files are treated as they are present in the main
  77. buildfile. This makes it easy to understand, but it makes it impossible
  78. for them to reference files and resources relative to their path.
  79. Because of this, for every imported file, Ant adds a property that
  80. contains the path to the imported buildfile. With this path, the
  81. imported buildfile can keep resources and be able to reference them
  82. relative to its position.</p>
  83. <p>So if I import for example a <i>docsbuild.xml</i> file named <b>builddocs</b>,
  84. I can get its path as <b>ant.file.builddocs</b>, similarly to the <b>ant.file</b>
  85. property of the main buildfile.</p>
  86. <p>Note that &quot;builddocs&quot; is not the filename, but the name attribute
  87. present in the imported project tag.</p>
  88. <p>
  89. If the imported file does not have a name attribute, the ant.file.projectname
  90. property will not be set.
  91. </p>
  92. <p>Since Ant 1.8.0 the task can also import resources from URLs or
  93. classpath resources (which are URLs, really). If you need to know
  94. whether the current build file's source has been a file or an URL
  95. you can consult the
  96. property <b>ant.file.type.<em>projectname</em></b> (using the same
  97. example as above <b>ant.file.type.builddocs</b>) which either have
  98. the value "file" or "url".</p>
  99. <h4>Resolving files against the imported file</h4>
  100. <p>Suppose your main build file called <code>importing.xml</code>
  101. imports a build file <code>imported.xml</code>, located anywhere on
  102. the file system, and <code>imported.xml</code> reads a set of
  103. properties from <code>imported.properties</code>:</p>
  104. <pre>&lt;!-- importing.xml --&gt;
  105. &lt;project name="importing" basedir="." default="..."&gt;
  106. &nbsp; &lt;import file="${path_to_imported}/imported.xml"/&gt;
  107. &lt;/project&gt;
  108. &lt;!-- imported.xml --&gt;
  109. &lt;project name="imported" basedir="." default="..."&gt;
  110. &nbsp; &lt;property file="imported.properties"/&gt;
  111. &lt;/project&gt;
  112. </pre>
  113. <p>This snippet however will resolve <code>imported.properties</code>
  114. against the basedir of <code>importing.xml</code>, because the basedir
  115. of <code>imported.xml</code> is ignored by Ant. The right way to use
  116. <code>imported.properties</code> is:</p>
  117. <pre>
  118. &lt;!-- imported.xml --&gt;
  119. &lt;project name="imported" basedir="." default="..."&gt;
  120. &nbsp; &lt;dirname property="imported.basedir" file="${ant.file.imported}"/&gt;
  121. &nbsp; &lt;property file="${imported.basedir}/imported.properties"/&gt;
  122. &lt;/project&gt;
  123. </pre>
  124. <p>As explained above <code>${ant.file.imported}</code> stores the
  125. path of the build script, that defines the project called
  126. <code>imported</code>, (in short it stores the path to
  127. <code>imported.xml</code>) and <a
  128. href="dirname.html"><code>&lt;dirname&gt;</code></a> takes its
  129. directory. This technique also allows <code>imported.xml</code> to be
  130. used as a standalone file (without being imported in other
  131. project).</p>
  132. <p>The above description only works for imported files that actually
  133. are imported from files and not from URLs. For files imported from
  134. URLs using resources relative to the imported file requires you to
  135. use tasks that can work on non-file resources in the first place.
  136. To create a relative resource you'd use something like:</p>
  137. <pre>
  138. &lt;loadproperties&gt;
  139. &lt;url baseUrl="${ant.file.imported}"
  140. relativePath="imported.properties"/&gt;
  141. &lt;/loadproperties&gt;
  142. </pre>
  143. <h3>Parameters</h3>
  144. <table border="1" cellpadding="2" cellspacing="0">
  145. <tbody>
  146. <tr>
  147. <td valign="top"><b>Attribute</b></td>
  148. <td valign="top"><b>Description</b></td>
  149. <td align="center" valign="top"><b>Required</b></td>
  150. </tr>
  151. <tr>
  152. <td valign="top">
  153. file
  154. </td>
  155. <td valign="top">
  156. The file to import. If this is a relative file name, the file name will be resolved
  157. relative to the <i>importing</i> file. <b>Note</b>, this is unlike most other
  158. ant file attributes, where relative files are resolved relative to ${basedir}.
  159. </td>
  160. <td valign="top" align="center">Yes or a nested resource collection</td>
  161. </tr>
  162. <tr>
  163. <td valign="top">
  164. optional
  165. </td>
  166. <td valign="top">
  167. If true, do not stop the build if the file does not exist,
  168. default is false.
  169. </td>
  170. <td valign="top" align="center">No</td>
  171. </tr>
  172. <tr>
  173. <td valign="top">
  174. as
  175. </td>
  176. <td valign="top">
  177. Specifies the prefix prepended to the target names. If
  178. ommitted, the name attribute of the project tag of the
  179. imported file will be used.
  180. </td>
  181. <td valign="top" align="center">No</td>
  182. </tr>
  183. <tr>
  184. <td valign="top">
  185. prefixSeparator
  186. </td>
  187. <td valign="top">
  188. Specifies the separator to be used between the prefix and the
  189. target name. Defaults to ".".
  190. </td>
  191. <td valign="top" align="center">No</td>
  192. </tr>
  193. </tbody>
  194. </table>
  195. <h3>Parameters specified as nested elements</h3>
  196. <h4>any <a href="../Types/resources.html">resource</a> or resource
  197. collection</h4>
  198. <p>The specified resources will be imported. <em>Since Ant
  199. 1.8.0</em></p>
  200. <h3>Examples</h3>
  201. <pre>&nbsp; &lt;import file=&quot;../common-targets.xml&quot;/&gt;
  202. </pre>
  203. <p>Imports targets from the common-targets.xml file that is in a parent
  204. directory.</p>
  205. <pre>&nbsp; &lt;import file=&quot;${deploy-platform}.xml&quot;/&gt;
  206. </pre>
  207. <p>Imports the project defined by the property deploy-platform</p>
  208. <pre>
  209. &lt;import&gt;
  210. &lt;javaresource name="common/targets.xml"&gt;
  211. &lt;classpath location="common.jar"/&gt;
  212. &lt;/javaresource&gt;
  213. &lt;/import&gt;
  214. </pre>
  215. <p>Imports targets from the targets.xml file that is inside the
  216. directory common inside the jar file common.jar.</p>
  217. <h3>How is &lt;import&gt; different
  218. from <a href="include.html">&lt;include&gt;</a>?</h3>
  219. <p>The short version: Use import if you intend to override a target,
  220. otherwise use include.</p>
  221. <p>When using import the imported targets are available by up to two
  222. names. Their "normal" name without any prefix and potentially with
  223. a prefixed name (the value of the as attribute or the imported
  224. project's name attribute, if any).</p>
  225. <p>When using include the included targets are only available in the
  226. prefixed form.</p>
  227. <p>When using import, the imported target's depends attribute
  228. remains unchanged, i.e. it uses "normal" names and allows you to
  229. override targets in the dependency list.</p>
  230. <p>When using include, the included targets cannot be overridden and
  231. their depends attributes are rewritten so that prefixed names are
  232. used. This allows writers of the included file to control which
  233. target is invoked as part of the dependencies.</p>
  234. <p>It is possible to include the same file more than once by using
  235. different prefixes, it is not possible to import the same file more
  236. than once.</p>
  237. <h4>Examples</h4>
  238. <p><i>nested.xml</i> shall be:</p>
  239. <pre>
  240. &lt;project&gt;
  241. &lt;target name="setUp"&gt;
  242. &lt;property name="prop" value="in nested"/&gt;
  243. &lt;/target&gt;
  244. &lt;target name="echo" depends="setUp"&gt;
  245. &lt;echo&gt;prop has the value ${prop}&lt;/echo&gt;
  246. &lt;/target&gt;
  247. &lt;/project&gt;
  248. </pre>
  249. <p>When using import like in</p>
  250. <pre>
  251. &lt;project default="test"&gt;
  252. &lt;target name="setUp"&gt;
  253. &lt;property name="prop" value="in importing"/&gt;
  254. &lt;/target&gt;
  255. &lt;import file="nested.xml" as="nested"/&gt;
  256. &lt;target name="test" depends="nested.echo"/&gt;
  257. &lt;/project&gt;
  258. </pre>
  259. <p>Running the build file will emit:
  260. <pre>
  261. setUp:
  262. nested.echo:
  263. [echo] prop has the value in importing
  264. test:
  265. </pre>
  266. <p>When using include like in</p>
  267. <pre>
  268. &lt;project default="test"&gt;
  269. &lt;target name="setUp"&gt;
  270. &lt;property name="prop" value="in importing"/&gt;
  271. &lt;/target&gt;
  272. &lt;include file="nested.xml" as="nested"/&gt;
  273. &lt;target name="test" depends="nested.echo"/&gt;
  274. &lt;/project&gt;
  275. </pre>
  276. <p>Running the target build file will emit:
  277. <pre>
  278. nested.setUp:
  279. nested.echo:
  280. [echo] prop has the value in nested
  281. test:
  282. </pre>
  283. <p>and there won't be any target named "echo" on the including build file.</p>
  284. </body>
  285. </html>