1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
|
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Language" content="en-us">
<link rel="stylesheet" type="text/css" href="../stylesheets/style.css">
<title>Import Task</title>
</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 select the proper ProjectHelper to parse the imported
file, using the same algorithm as the one executed at
<a href="../projecthelper.html">startup</a>. The selected ProjectHelper
instance will then be responsible to actually parse the imported file.
</p>
<p>
<b>Note</b> as seen above, this task heavily relies on the ProjectHelper
implementation and doesn't really perform any work of its own. If
you have configured Apache Ant to use a ProjectHelper other than Ant's
default, this task may or may not work.
</p>
<p>
In the common use case where only Ant's default project helper is
used, 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>
<h4>Target overriding</h4>
<p>If a target in the main file is also present in at least one of the
imported files, the one from the main file takes precedence.</p>
<p>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. This makes it easy to
keep the same target name, so that the overriding target is still called
by any other targets--in either the main or imported buildfile(s)--for which
it is a dependency, with a different implementation. The target from <i>docsbuild.xml</i> is
made available by the name "<b>builddocs</b><b>.docs</b>".
This enables the new implementation to call the old target, thus
<i>enhancing</i> it with tasks called before or after it.</p>
<p>If you use the <i>as</i> attribute of the task, its value will be
used to prefix the overridden target's name instead of the name
attribute of the project tag.</p>
<h4>Special Properties</h4>
<p>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.</p>
<p>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.</p>
<p>Note that "builddocs" is not the filename, but the name attribute
present in the imported project tag.</p>
<p>
If the imported file does not have a name attribute, the ant.file.projectname
property will not be set.
</p>
<p>Since Ant 1.8.0 the task can also import resources from URLs or
classpath resources (which are URLs, really). If you need to know
whether the current build file's source has been a file or an URL
you can consult the
property <b>ant.file.type.<em>projectname</em></b> (using the same
example as above <b>ant.file.type.builddocs</b>) which either have
the value "file" or "url".</p>
<h4>Resolving files against the imported file</h4>
<p>Suppose your main build file called <code>importing.xml</code>
imports a build file <code>imported.xml</code>, located anywhere on
the file system, and <code>imported.xml</code> reads a set of
properties from <code>imported.properties</code>:</p>
<pre><!-- importing.xml -->
<project name="importing" basedir="." default="...">
<import file="${path_to_imported}/imported.xml"/>
</project>
<!-- imported.xml -->
<project name="imported" basedir="." default="...">
<property file="imported.properties"/>
</project>
</pre>
<p>This snippet however will resolve <code>imported.properties</code>
against the basedir of <code>importing.xml</code>, because the basedir
of <code>imported.xml</code> is ignored by Ant. The right way to use
<code>imported.properties</code> is:</p>
<pre>
<!-- imported.xml -->
<project name="imported" basedir="." default="...">
<dirname property="imported.basedir" file="${ant.file.imported}"/>
<property file="${imported.basedir}/imported.properties"/>
</project>
</pre>
<p>As explained above <code>${ant.file.imported}</code> stores the
path of the build script, that defines the project called
<code>imported</code>, (in short it stores the path to
<code>imported.xml</code>) and <a
href="dirname.html"><code><dirname></code></a> takes its
directory. This technique also allows <code>imported.xml</code> to be
used as a standalone file (without being imported in other
project).</p>
<p>The above description only works for imported files that actually
are imported from files and not from URLs. For files imported from
URLs using resources relative to the imported file requires you to
use tasks that can work on non-file resources in the first place.
To create a relative resource you'd use something like:</p>
<pre>
<loadproperties>
<url baseUrl="${ant.file.imported}"
relativePath="imported.properties"/>
</loadproperties>
</pre>
<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
</td>
<td valign="top">
The file to import. If this is a relative file name, the file name will be resolved
relative to the <i>importing</i> file. <b>Note</b>, this is unlike most other
ant file attributes, where relative files are resolved relative to ${basedir}.
</td>
<td valign="top" align="center">Yes or a nested resource collection</td>
</tr>
<tr>
<td valign="top">
optional
</td>
<td valign="top">
If true, do not stop the build if the file does not exist,
default is false.
</td>
<td valign="top" align="center">No</td>
</tr>
<tr>
<td valign="top">
as
</td>
<td valign="top">
Specifies the prefix prepended to the target names. If
omitted, the name attribute of the project tag of the
imported file will be used.
</td>
<td valign="top" align="center">No</td>
</tr>
<tr>
<td valign="top">
prefixSeparator
</td>
<td valign="top">
Specifies the separator to be used between the prefix and the
target name. Defaults to ".".
</td>
<td valign="top" align="center">No</td>
</tr>
</tbody>
</table>
<h3>Parameters specified as nested elements</h3>
<h4>any <a href="../Types/resources.html">resource</a> or resource
collection</h4>
<p>The specified resources will be imported. <em>Since Ant
1.8.0</em></p>
<h3>Examples</h3>
<pre> <import file="../common-targets.xml"/>
</pre>
<p>Imports targets from the common-targets.xml file that is in a parent
directory.</p>
<pre> <import file="${deploy-platform}.xml"/>
</pre>
<p>Imports the project defined by the property deploy-platform</p>
<pre>
<import>
<javaresource name="common/targets.xml">
<classpath location="common.jar"/>
</javaresource>
</import>
</pre>
<p>Imports targets from the targets.xml file that is inside the
directory common inside the jar file common.jar.</p>
<h3>How is <import> different
from <a href="include.html"><include></a>?</h3>
<p>The short version: Use import if you intend to override a target,
otherwise use include.</p>
<p>When using import the imported targets are available by up to two
names. Their "normal" name without any prefix and potentially with
a prefixed name (the value of the as attribute or the imported
project's name attribute, if any).</p>
<p>When using include the included targets are only available in the
prefixed form.</p>
<p>When using import, the imported target's depends attribute
remains unchanged, i.e. it uses "normal" names and allows you to
override targets in the dependency list.</p>
<p>When using include, the included targets cannot be overridden and
their depends attributes are rewritten so that prefixed names are
used. This allows writers of the included file to control which
target is invoked as part of the dependencies.</p>
<p>It is possible to include the same file more than once by using
different prefixes, it is not possible to import the same file more
than once.</p>
<h4>Examples</h4>
<p><i>nested.xml</i> shall be:</p>
<pre>
<project>
<target name="setUp">
<property name="prop" value="in nested"/>
</target>
<target name="echo" depends="setUp">
<echo>prop has the value ${prop}</echo>
</target>
</project>
</pre>
<p>When using import like in</p>
<pre>
<project default="test">
<target name="setUp">
<property name="prop" value="in importing"/>
</target>
<import file="nested.xml" as="nested"/>
<target name="test" depends="nested.echo"/>
</project>
</pre>
<p>Running the build file will emit:
<pre>
setUp:
nested.echo:
[echo] prop has the value in importing
test:
</pre>
<p>When using include like in</p>
<pre>
<project default="test">
<target name="setUp">
<property name="prop" value="in importing"/>
</target>
<include file="nested.xml" as="nested"/>
<target name="test" depends="nested.echo"/>
</project>
</pre>
<p>Running the target build file will emit:
<pre>
nested.setUp:
nested.echo:
[echo] prop has the value in nested
test:
</pre>
<p>and there won't be any target named "echo" on the including build file.</p>
</body>
</html>
|
