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 @@

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:-

       <!DOCTYPE project [
         <!ENTITY propertiesAndPaths SYSTEM "propertiesAndPaths.xml">
  @@ -773,12 +773,26 @@
           &propertiesAndPaths;
           &taskdefs;
   
-The cleaner method using XInclude/Xpath will let you include named -targets from one build file or another, using - -the xpointer syntax. 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 <import> task that imports +whole build files into other projects. The entity inclusion example +could almost be replaced by two import statements:- +
  + <import file="propertiesAndPaths.xml">
  + <import file="taskdefs.xml">
  +
+ +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. + +

+ +The <import> 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 +documentation for the specifics of +these features.

@@ -1124,9 +1138,8 @@

  • Java Development with Ant; - Erik Hatcher and Steve Loughran.
    - Arguably the only book on Ant worth owning; - certainly it's the only one written by Ant developers. + Erik Hatcher and Steve Loughran. +
  • 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 @@ Get
    GUnzip
    GZip
    +Import
    Input
    Jar
    Java
    1.1 ant/docs/manual/CoreTasks/import.html Index: import.html =================================================================== Input Task

    Import

    Description

    Imports another build file into the current project.

    On execution it will read another Ant file into the same Project. This means that it basically works like the Entity Includes as explained in the Ant FAQ, as if the imported file was contained in the importing file, minus the top <project> tag.

    Important: 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 ).

    There are two further functional aspects that pertain to this task and that are not possible with entity includes:
    Target overriding

    If a target in the main file is also present in at least one of the imported files, it takes precedence.

    So if I import for example a docsbuild.xml file named builddocs, that contains a "docs" 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.

    The original target is still available though, and is called "builddocs.docs". This means that in my new implementation, I can still call the old target, making it possible to enhance it with tasks called before or after it.

    Special Properties

    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.

    So if I import for example a docsbuild.xml file named builddocs, I can get its path as ant.file.builddocs, similarly to the ant.file property of the main buildfile.
    Note that "builddocs" is not the filename, but the @name attribute present in the imported project tag.

    Important: 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.
     

    Parameters

    Attribute Description Required
    file
    The file to import.
    Yes


    Examples

      <import file="../common-targets.xml" />

    Imports targets from the common-targets.xml file that is in a parent directory.

      <import file="${deploy-platform}.xml" />

    Imports the project defined by the property deploy-platform



    Copyright © 2001-2003 Apache Software Foundation. All rights Reserved.

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