| 1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|---|
| 2 | <html>
|
|---|
| 3 | <head>
|
|---|
| 4 | <meta http-equiv="Content-Language" content="en-us">
|
|---|
| 5 | <title>Import Task</title>
|
|---|
| 6 | <link rel="stylesheet" type="text/css" href="../stylesheets/antmanual.css">
|
|---|
| 7 | </head>
|
|---|
| 8 | <body>
|
|---|
| 9 | <h2><a name="import">Import</a></h2>
|
|---|
| 10 | <h3>Description</h3>
|
|---|
| 11 | <p>
|
|---|
| 12 | Imports another build file into the current project.
|
|---|
| 13 | </p>
|
|---|
| 14 | <p>
|
|---|
| 15 | On execution it will read another Ant file into
|
|---|
| 16 | the same Project. This means that it basically works like the
|
|---|
| 17 | <a href="http://ant.apache.org/faq.html#xml-entity-include">Entity
|
|---|
| 18 | Includes as explained in the Ant FAQ</a>, as if the imported file was
|
|---|
| 19 | contained in the importing file, minus the top <code><project></code>
|
|---|
| 20 | tag.
|
|---|
| 21 | </p>
|
|---|
| 22 | <p>
|
|---|
| 23 | The import task may only be used as a top-level task. This means that
|
|---|
| 24 | it may not be used in a target.
|
|---|
| 25 | </p>
|
|---|
| 26 | <p>
|
|---|
| 27 | There are two further functional aspects that pertain to this task and
|
|---|
| 28 | that are not possible with entity includes:
|
|---|
| 29 | <ul>
|
|---|
| 30 | <li>target overriding</li>
|
|---|
| 31 | <li>special properties</li>
|
|---|
| 32 | </ul>
|
|---|
| 33 | </p>
|
|---|
| 34 | <h4>Target overriding</h4>
|
|---|
| 35 |
|
|---|
| 36 | <p>If a target in the main file is also present in at least one of the
|
|---|
| 37 | imported files, the one from the main file takes precedence.</p>
|
|---|
| 38 |
|
|---|
| 39 | <p>So if I import for example a <i>docsbuild.xml</i> file named <b>builddocs</b>,
|
|---|
| 40 | that contains a "<b>docs</b>" target, I can redefine it in my main
|
|---|
| 41 | buildfile and that is the one that will be called. This makes it easy to
|
|---|
| 42 | keep the same target name, so that the overriding target is still called
|
|---|
| 43 | by any other targets--in either the main or imported buildfile(s)--for which
|
|---|
| 44 | it is a dependency, with a different implementation. The target from <i>docsbuild.xml</i> is
|
|---|
| 45 | made available by the name "<b>builddocs</b><b>.docs</b>".
|
|---|
| 46 | This enables the new implementation to call the old target, thus
|
|---|
| 47 | <i>enhancing</i> it with tasks called before or after it.</p>
|
|---|
| 48 |
|
|---|
| 49 | <h4>Special Properties</h4>
|
|---|
| 50 |
|
|---|
| 51 | <p>Imported files are treated as they are present in the main
|
|---|
| 52 | buildfile. This makes it easy to understand, but it makes it impossible
|
|---|
| 53 | for them to reference files and resources relative to their path.
|
|---|
| 54 | Because of this, for every imported file, Ant adds a property that
|
|---|
| 55 | contains the path to the imported buildfile. With this path, the
|
|---|
| 56 | imported buildfile can keep resources and be able to reference them
|
|---|
| 57 | relative to its position.</p>
|
|---|
| 58 |
|
|---|
| 59 | <p>So if I import for example a <i>docsbuild.xml</i> file named <b>builddocs</b>,
|
|---|
| 60 | I can get its path as <b>ant.file.builddocs</b>, similarly to the <b>ant.file</b>
|
|---|
| 61 | property of the main buildfile.</p>
|
|---|
| 62 |
|
|---|
| 63 | <p>Note that "builddocs" is not the filename, but the name attribute
|
|---|
| 64 | present in the imported project tag.</p>
|
|---|
| 65 |
|
|---|
| 66 | <h4>Resolving files against the imported file</h4>
|
|---|
| 67 |
|
|---|
| 68 | <p>Suppose your main build file called <code>importing.xml</code>
|
|---|
| 69 | imports a build file <code>imported.xml</code>, located anywhere on
|
|---|
| 70 | the file system, and <code>imported.xml</code> reads a set of
|
|---|
| 71 | properties from <code>imported.properties</code>:</p>
|
|---|
| 72 |
|
|---|
| 73 | <pre><!-- importing.xml -->
|
|---|
| 74 | <project name="importing" basedir="." default="...">
|
|---|
| 75 | <import file="${path_to_imported}/imported.xml"/>
|
|---|
| 76 | </project>
|
|---|
| 77 |
|
|---|
| 78 | <!-- imported.xml -->
|
|---|
| 79 | <project name="imported" basedir="." default="...">
|
|---|
| 80 | <property file="imported.properties"/>
|
|---|
| 81 | </project>
|
|---|
| 82 | </pre>
|
|---|
| 83 |
|
|---|
| 84 | <p>This snippet however will resolve <code>imported.properties</code>
|
|---|
| 85 | against the basedir of <code>importing.xml</code>, because the basedir
|
|---|
| 86 | of <code>imported.xml</code> is ignored by Ant. The right way to use
|
|---|
| 87 | <code>imported.properties</code> is:</p>
|
|---|
| 88 |
|
|---|
| 89 | <pre>
|
|---|
| 90 | <!-- imported.xml -->
|
|---|
| 91 | <project name="imported" basedir="." default="...">
|
|---|
| 92 | <dirname property="imported.basedir" file="${ant.file.imported}"/>
|
|---|
| 93 | <property file="${imported.basedir}/imported.properties"/>
|
|---|
| 94 | </project>
|
|---|
| 95 | </pre>
|
|---|
| 96 |
|
|---|
| 97 | <p>As explained above <code>${ant.file.imported}</code> stores the
|
|---|
| 98 | path of the build script, that defines the project called
|
|---|
| 99 | <code>imported</code>, (in short it stores the path to
|
|---|
| 100 | <code>imported.xml</code>) and <a
|
|---|
| 101 | href="dirname.html"><code><dirname></code></a> takes its
|
|---|
| 102 | directory. This technique also allows <code>imported.xml</code> to be
|
|---|
| 103 | used as a standalone file (without being imported in other
|
|---|
| 104 | project).</p>
|
|---|
| 105 |
|
|---|
| 106 | <h3>Parameters</h3>
|
|---|
| 107 | <table border="1" cellpadding="2" cellspacing="0">
|
|---|
| 108 | <tbody>
|
|---|
| 109 | <tr>
|
|---|
| 110 | <td valign="top"><b>Attribute</b></td>
|
|---|
| 111 | <td valign="top"><b>Description</b></td>
|
|---|
| 112 | <td align="center" valign="top"><b>Required</b></td>
|
|---|
| 113 | </tr>
|
|---|
| 114 | <tr>
|
|---|
| 115 | <td valign="top">
|
|---|
| 116 | file
|
|---|
| 117 | </td>
|
|---|
| 118 | <td valign="top">
|
|---|
| 119 | The file to import. If this is a relative file name, the file name will be resolved
|
|---|
| 120 | relative to the <i>importing</i> file. <b>Note</b>, this is unlike most other
|
|---|
| 121 | ant file attributes, where relative files are resolved relative to ${basedir}.
|
|---|
| 122 | </td>
|
|---|
| 123 | <td valign="top" align="center">Yes</td>
|
|---|
| 124 | </tr>
|
|---|
| 125 | <tr>
|
|---|
| 126 | <td valign="top">
|
|---|
| 127 | optional
|
|---|
| 128 | </td>
|
|---|
| 129 | <td valign="top">
|
|---|
| 130 | If true, do not stop the build if the file does not exist,
|
|---|
| 131 | default is false.
|
|---|
| 132 | </td>
|
|---|
| 133 | <td valign="top" align="center">No</td>
|
|---|
| 134 | </tr>
|
|---|
| 135 | </tbody>
|
|---|
| 136 | </table>
|
|---|
| 137 |
|
|---|
| 138 | <h3>Examples</h3>
|
|---|
| 139 | <pre> <import file="../common-targets.xml"/>
|
|---|
| 140 | </pre>
|
|---|
| 141 |
|
|---|
| 142 | <p>Imports targets from the common-targets.xml file that is in a parent
|
|---|
| 143 | directory.</p>
|
|---|
| 144 |
|
|---|
| 145 | <pre> <import file="${deploy-platform}.xml"/>
|
|---|
| 146 | </pre>
|
|---|
| 147 |
|
|---|
| 148 | <p>Imports the project defined by the property deploy-platform</p>
|
|---|
| 149 |
|
|---|
| 150 | <hr>
|
|---|
| 151 | <p align="center">Copyright © 2003-2005 The Apache Software
|
|---|
| 152 | Foundation. All rights
|
|---|
| 153 | Reserved.</p>
|
|---|
| 154 | </body>
|
|---|
| 155 | </html>
|
|---|
