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