ant-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ste...@apache.org
Subject cvs commit: ant/docs/manual/CoreTasks import.html
Date Wed, 09 Jul 2003 16:24:39 GMT
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>
       &lt;!DOCTYPE project [
         &lt;!ENTITY propertiesAndPaths SYSTEM &quot;propertiesAndPaths.xml&quot;&gt;
  @@ -773,12 +773,26 @@
           &amp;propertiesAndPaths;
           &amp;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>&lt;import&gt;</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>
  + &lt;import file="propertiesAndPaths.xml"&gt;
  + &lt;import file="taskdefs.xml"&gt;
  +</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>&lt;import&gt;</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>&lt;project&gt;</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>
  &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>
    </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; 2001-2003 Apache Software
  Foundation. All rights
  Reserved.</p>
  </body>
  </html>
  
  
  

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@ant.apache.org
For additional commands, e-mail: dev-help@ant.apache.org


Mime
View raw message