| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> |
| <html> |
| <head> |
| <meta http-equiv="Content-Language" content="en-us"> |
| <title>Import Task</title> |
| <link rel="stylesheet" type="text/css" href="../stylesheets/antmanual.css"> |
| </head> |
| <body> |
| <h2><a name="import">Import</a></h2> |
| <h3>Description</h3> |
| <p> |
| Imports another build file into the current project. |
| </p> |
| <p> |
| On execution it will read another Ant file into |
| the same Project. This means that it basically works like the |
| <a href="http://ant.apache.org/faq.html#xml-entity-include">Entity |
| Includes as explained in the Ant FAQ</a>, as if the imported file was |
| contained in the importing file, minus the top <code><project></code> |
| tag. |
| </p> |
| <p> |
| The import task may only be used as a top-level task. This means that |
| it may not be used in a target. |
| </p> |
| <p> |
| There are two further functional aspects that pertain to this task and |
| that are not possible with entity includes: |
| <ul> |
| <li>target overriding</li> |
| <li>special properties</li> |
| </ul> |
| </p> |
| <b>Target overriding<br> |
| <br> |
| </b>If a target in the main file is also present in at least one of the |
| imported files, it takes precedence.<br> |
| <br> |
| So if I import for example a <i>docsbuild.xml</i> file named <b>builddocs</b>, |
| that contains a "<b>docs</b>" target, I can redefine it in my main |
| buildfile and that is the one that will be called. It makes it easy to |
| keep the same target name, that has the same dependencies (so it is |
| still called by the other targets), but use a different implementation.<br> |
| <br> |
| The original target is still available though, and is called <b>"builddocs</b><b>.docs"</b>. |
| This means that in my new implementation, I can still call the old |
| target, making it possible to <i>enhance </i>it with tasks called |
| before or after it.<br> |
| <b></b><b><br> |
| Special Properties<br> |
| <br> |
| </b>Imported files are treated as they are present in the main |
| buildfile. This makes it easy to understand, but it makes it impossible |
| for them to reference files and resources relative to their path. |
| Because of this, for every imported file, Ant adds a property that |
| contains the path to the imported buildfile. With this path, the |
| imported buildfile can keep resources and be able to reference them |
| relative to its position.<br> |
| <br> |
| So if I import for example a <i>docsbuild.xml</i> file named <b>builddocs</b>, |
| I can get its path as <b>ant.file.builddocs</b>, similarly to the <b>ant.file</b> |
| property of the main buildfile.<br> |
| Note that "builddocs" is not the filename, but the @name attribute |
| present in the imported project tag.<br> |
| <br> |
| <b>Important</b>: We have not finalized how relative file references |
| will be resolved in deep/complex build hierarchies -such as what |
| happens when an imported file imports another file. Use absolute |
| references for enhanced build file stability, especially in the |
| imported files.<br> |
| <br> |
| <h3>Parameters</h3> |
| <table border="1" cellpadding="2" cellspacing="0"> |
| <tbody> |
| <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">file<br> |
| </td> |
| <td valign="top">The file to import.<br> |
| </td> |
| <td valign="top" align="center">Yes</td> |
| </tr> |
| <tr> |
| <td valign="top">optional<br> |
| </td> |
| <td valign="top"> |
| if true, do not issue stop the build if the file does not exist, |
| default is false.<br> |
| </td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| </tbody> |
| </table> |
| <h3><br> |
| </h3> |
| <h3>Examples</h3> |
| <pre> <import file="../common-targets.xml" /><br></pre> |
| <br> |
| Imports targets from the common-targets.xml file that is in a parent |
| directory.<br> |
| <br> |
| <pre> <import file="${deploy-platform}.xml" /><br></pre> |
| <br> |
| Imports the project defined by the property deploy-platform<br> |
| <br> |
| <br> |
| <hr> |
| <p align="center">Copyright © 2003 Apache Software |
| Foundation. All rights |
| Reserved.</p> |
| </body> |
| </html> |
