diff --git a/docs/ant_in_anger.html b/docs/ant_in_anger.html index bbd1425b3..ec4c828a4 100644 --- a/docs/ant_in_anger.html +++ b/docs/ant_in_anger.html @@ -762,8 +762,8 @@ C++.

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 @@ method is the most portable:-
         &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 @@ running a continuous integration/testing proces.

  • 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. +
  • diff --git a/docs/manual/CoreTasks/import.html b/docs/manual/CoreTasks/import.html new file mode 100644 index 000000000..e26e11526 --- /dev/null +++ b/docs/manual/CoreTasks/import.html @@ -0,0 +1,104 @@ + + + + + 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

    + + + + + + + + + + + + + +
    AttributeDescriptionRequired
    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.

    + + diff --git a/docs/manual/coretasklist.html b/docs/manual/coretasklist.html index 86e6d064b..634d2652d 100644 --- a/docs/manual/coretasklist.html +++ b/docs/manual/coretasklist.html @@ -51,6 +51,7 @@ Get
    GUnzip
    GZip
    +Import
    Input
    Jar
    Java