stevel 2003/07/09 09:24:38
Modified: docs ant_in_anger.html
docs/manual coretasklist.html
Added: docs/manual/CoreTasks import.html
Log:
documenting the import task
Revision Changes Path
1.16 +24 -11 ant/docs/ant_in_anger.html
Index: ant_in_anger.html
===================================================================
RCS file: /home/cvs/ant/docs/ant_in_anger.html,v
retrieving revision 1.15
retrieving revision 1.16
diff -u -r1.15 -r1.16
--- ant_in_anger.html 10 Feb 2003 14:44:21 -0000 1.15
+++ ant_in_anger.html 9 Jul 2003 16:24:35 -0000 1.16
@@ -762,8 +762,8 @@
<p>
There are two inclusion mechanisms, an ugly one for all parsers and a
-clean one. For now, the ugly
-method is the most portable:-
+clean one. The ugly method is the only one that was available on Ant1.5 and
+earlier:-
<pre>
<!DOCTYPE project [
<!ENTITY propertiesAndPaths SYSTEM
"propertiesAndPaths.xml">
@@ -773,12 +773,26 @@
&propertiesAndPaths;
&taskdefs;
</pre>
-The cleaner method using XInclude/Xpath will let you include named
-targets from one build file or another, using
-<a href="http://www.w3.org/XML/Linking";>
-the xpointer syntax</a>. You'll need to wait for the W3C proposals
-to finalise and the java XML parsers to implement it before
-using xpointer references.
+The cleaner method in Ant1.6 is the <tt><import></tt> task that imports
+whole build files into other projects. The entity inclusion example
+could <i>almost</i> be replaced by two import statements:-
+<pre>
+ <import file="propertiesAndPaths.xml">
+ <import file="taskdefs.xml">
+</pre>
+
+We say almost as top level declarations (properties and taskdefs)
+do not get inserted into the XML file exactly where the import statement
+goes, but added to the end of the file. This is because the import process
+takes place after the main build file is parsed, during execution, whereas
+XML entity expansion is handled during the parsing process.
+
+<p>
+
+The <tt><import></tt> task does powerful things, such as let you
override targets,
+and use ant properties to name the location of the file to import. Consult
the
+<a href="manual/CoreTasks/import.html">documentation</a> for the specifics of
+these features.
<p>
@@ -1124,9 +1138,8 @@
<li><a href="http://manning.com/antbook/";><i>Java Development with
Ant</i></a>;
- Erik Hatcher and Steve Loughran. <br>
- Arguably the only book on Ant worth owning;
- certainly it's the only one written by Ant developers.
+ Erik Hatcher and Steve Loughran.
+
<li>
<a href="http://www.iseran.com/Steve/papers/when_web_services_go_bad.html";>
1.49 +1 -0 ant/docs/manual/coretasklist.html
Index: coretasklist.html
===================================================================
RCS file: /home/cvs/ant/docs/manual/coretasklist.html,v
retrieving revision 1.48
retrieving revision 1.49
diff -u -r1.48 -r1.49
--- coretasklist.html 14 May 2003 11:52:07 -0000 1.48
+++ coretasklist.html 9 Jul 2003 16:24:35 -0000 1.49
@@ -51,6 +51,7 @@
<a href="CoreTasks/get.html">Get</a><br>
<a href="CoreTasks/unpack.html">GUnzip</a><br>
<a href="CoreTasks/pack.html">GZip</a><br>
+<a href="CoreTasks/import.html">Import</a><br>
<a href="CoreTasks/input.html">Input</a><br>
<a href="CoreTasks/jar.html">Jar</a><br>
<a href="CoreTasks/java.html">Java</a><br>
1.1 ant/docs/manual/CoreTasks/import.html
Index: import.html
===================================================================
<!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>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
