youys
/
ant

 
			
			   
				 
					
						
						
							
							<!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>&lt;project&gt;</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>
&nbsp;<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>
    <tr>
      <td valign="top">optional<br>
      </td>
      <td valign="top">
        if true, do not issue stop the build if the file does not exist,
        default is false.<br>
      </td>
      <td valign="top" align="center">No</td>
    </tr>
  </tbody>
</table>
<h3><br>
</h3>
<h3>Examples</h3>
<pre>&nbsp; &lt;import file="../common-targets.xml" /&gt;<br></pre>
<br>
Imports targets from the common-targets.xml file that is in a parent
directory.<br>
<br>
<pre>&nbsp; &lt;import file="${deploy-platform}.xml" /&gt;<br></pre>
<br>
Imports the project defined by the property deploy-platform<br>
<br>
<br>
<hr>
<p align="center">Copyright &copy; 2003 Apache Software
Foundation. All rights
Reserved.</p>
</body>
</html>