Description

Include another build file into the current project.

since Apache Ant 1.8.0

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

target rewriting

special properties

Target rewriting

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.

Note that prefixes nest, so if a build file includes a file with
prefix "a" and the included file includes another file with prefix
"b", then the targets of that last build file will be prefixed by
"a.b.".

<import> contribute to the prefix as well, but
only if their as attribute has been specified.

Special Properties

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.

If you need to know whether the current build file's source has
been a file or an URL you can consult the
property ant.file.type.projectname (using the same
example as above ant.file.type.builddocs) which either have
the value "file" or "url".

Resolving files against the included file

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:

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

The above description only works for included files that actually
are included from files and not from URLs. For files included from
URLs using resources relative to the included file requires you to
use tasks that can work on non-file resources in the first place.
To create a relative resource you'd use something like:

Parameters

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 or a nested resource collection

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
omitted, the name attribute of the project tag of the
included file will be used.

Yes, if the included file's
project tag doesn't specify a name attribute.

prefixSeparator

Specifies the separator to be used between the prefix and the
target name. Defaults to ".".

The short version: Use import if you intend to override a target,
otherwise use include.

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 targets cannot be overridden and
their depends attributes are 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.