mirror of
https://github.com/apache/ant.git
synced 2025-05-18 14:04:48 +00:00
5741bedf4c
git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@275268 13f79535-47bb-0310-9956-ffa450edef68
107 lines
3.7 KiB
HTML
107 lines
3.7 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<html>
|
|
<head>
|
|
<meta http-equiv="Content-Language" content="en-us">
|
|
<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 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>
|
|
</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>
|