Include another build file into the current project.
Note this task heavily relies on the ProjectHelper implementation and doesn't really perform any work of its own. If you have configured Ant to use a ProjectHelper other than Ant's default, this task may or may not work.
On execution it will read another Ant file into the same Project rewriting the included target names and depends lists. This is different from Entity Includes as explained in the Ant FAQ in so far as the target names get prefixed by the included project's name or the as attribute and do not appear as if the file was contained in the including file.
The include task may only be used as a top-level task. This means that it may not be used in a target.
There are two further functional aspects that pertain to this task and that are not possible with entity includes:
Any target in the included file will be renamed to prefix.name where name is the original target's name and prefix is either the value of the as attribute or the name attribute of the project tag of the included file.
The depends attribute of all included targets is rewritten so that all target names are prefixed as well. This makes the included file self-contained.
Included 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 included file, Ant adds a property that contains the path to the included buildfile. With this path, the included buildfile can keep resources and be able to reference them relative to its position.
So if I include 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 included project tag.
If the included file does not have a name attribute, the ant.file.projectname property will not be set.
Suppose your main build file called including.xml
includes a build file included.xml, located anywhere on
the file system, and included.xml reads a set of
properties from included.properties:
<!-- including.xml -->
<project name="including" basedir="." default="...">
<include file="${path_to_included}/included.xml"/>
</project>
<!-- included.xml -->
<project name="included" basedir="." default="...">
<property file="included.properties"/>
</project>
This snippet however will resolve included.properties
against the basedir of including.xml, because the basedir
of included.xml is ignored by Ant. The right way to use
included.properties is:
<!-- included.xml -->
<project name="included" basedir="." default="...">
<dirname property="included.basedir" file="${ant.file.included}"/>
<property file="${included.basedir}/included.properties"/>
</project>
As explained above ${ant.file.included} stores the
path of the build script, that defines the project called
included, (in short it stores the path to
included.xml) and <dirname> takes its
directory. This technique also allows included.xml to be
used as a standalone file (without being included in other
project).
| Attribute | Description | Required |
| file | The file to include. If this is a relative file name, the file name will be resolved relative to the including file. Note, this is unlike most other ant file attributes, where relative files are resolved relative to ${basedir}. | Yes |
| optional | If true, do not stop the build if the file does not exist, default is false. | No |
| as | Specifies the prefix prepended to the target names. If ommitted, the name attribute of the project tag of the imported file will be used. | Yes, if the included file's project tag doesn't specify a name attribute. |
<include file="../common-targets.xml"/>
Includes targets from the common-targets.xml file that is in a parent directory.
<include file="${deploy-platform}.xml"/>
Includes the project defined by the property deploy-platform
When using import the imported targets are available by up to two names. Their "normal" name without any prefix and potentially with a prefixed name (the value of the as attribute or the imported project's name attribute, if any).
When using include the included targets are only available in the prefixed form.
When using import, the imported target's depends attribute remains unchanged, i.e. it uses "normal" names and allows you to override targets in the dependency list.
When using include, the included target's depends attribute is rewritten so that prefixed names are used. This allows writers of the included file to control which target is invoked as part of the dependencies.
It is possible to include the same file more than once by using different prefixes, it is not possible to import the same file more than once.
Use import if you intend to override a target, otherwise use include.
nested.xml shall be:
<project>
<target name="setUp">
<property name="prop" value="in nested"/>
</target>
<target name="echo" depends="setUp">
<echo>prop has the value ${prop}</echo>
</target>
</project>
When using import like in
<project>
<target name="setUp">
<property name="prop" value="in importing"/>
</target>
<import file="nested.xml" as="nested"/>
</project>
Running the target nested.echo will emit:
setUp:
nested.echo:
[echo] prop has the value in importing
When using include like in
<project>
<target name="setUp">
<property name="prop" value="in importing"/>
</target>
<include file="nested.xml" as="nested"/>
</project>
Running the target nested.echo will emit:
nested.setUp:
nested.echo:
[echo] prop has the value in nested
and there won't be any target named "echo" on the including build file.