bodewig 2004/06/29 02:05:33
Modified: docs/manual/CoreTasks Tag: ANT_16_BRANCH import.html
Log:
merge
Revision Changes Path
No revision
No revision
1.6.2.9 +71 -30 ant/docs/manual/CoreTasks/import.html
Index: import.html
===================================================================
RCS file: /home/cvs/ant/docs/manual/CoreTasks/import.html,v
retrieving revision 1.6.2.8
retrieving revision 1.6.2.9
diff -u -r1.6.2.8 -r1.6.2.9
--- import.html 29 Apr 2004 10:14:17 -0000 1.6.2.8
+++ import.html 29 Jun 2004 09:05:33 -0000 1.6.2.9
@@ -31,12 +31,12 @@
<li>special properties</li>
</ul>
</p>
-<b>Target overriding</b><br />
-<br />
-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>,
+<h4>Target overriding</h4>
+
+<p>If a target in the main file is also present in at least one of the
+imported files, it 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
@@ -44,24 +44,65 @@
it is a dependency, with a different implementation. The original target 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.<br />
-<br />
-<b>Special Properties</b><br />
-<br />
-Imported files are treated as they are present in the main
+<i>enhancing</i> it with tasks called before or after it.</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.<br />
-<br />
-So if I import for example a <i>docsbuild.xml</i> file named
<b>builddocs</b>,
+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.<br />
-Note that "builddocs" is not the filename, but the name attribute
-present in the imported project tag.<br />
-<br />
+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>
+
+<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>
+
<h3>Parameters</h3>
<table border="1" cellpadding="2" cellspacing="0">
<tbody>
@@ -93,19 +134,19 @@
</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 />
+<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>
+
<hr>
<p align="center">Copyright © 2003-2004 The Apache Software
Foundation. All rights
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
