|
|
|
@@ -0,0 +1,104 @@ |
|
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> |
|
|
|
<html> |
|
|
|
<head> |
|
|
|
<meta http-equiv="Content-Language" content="en-us"> |
|
|
|
<title>Input Task</title> |
|
|
|
</head> |
|
|
|
<body> |
|
|
|
<h2><a name="input">Import</a></h2> |
|
|
|
<h3>Description</h3> |
|
|
|
Imports another build file into the current project.<br> |
|
|
|
<br> |
|
|
|
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.<br> |
|
|
|
<br> |
|
|
|
<b>Important</b>: there is one limitation related to the top level |
|
|
|
elements in the imported files. The current implementation will add |
|
|
|
them at the end of the top-level ( instead of replacing the import |
|
|
|
element - which would be more intuitive ).<br> |
|
|
|
<br> |
|
|
|
There are two further functional aspects that pertain to this task and |
|
|
|
that are not possible with entity includes:<br> |
|
|
|
<ul> |
|
|
|
<li>target overriding</li> |
|
|
|
<li>special properties<br> |
|
|
|
</li> |
|
|
|
</ul> |
|
|
|
<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 © 2001-2003 Apache Software |
|
|
|
Foundation. All rights |
|
|
|
Reserved.</p> |
|
|
|
</body> |
|
|
|
</html> |
Steve Loughran