From b9421dc80af485591a9c50cc8921f912e0def11e Mon Sep 17 00:00:00 2001
From: Ashlee Young
- 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:
-Include
- Description
-
-
-
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.
-
-
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".
- -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).
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:
- -- <loadproperties> - <url baseUrl="${ant.file.included}" - relativePath="included.properties"/> - </loadproperties> -- -
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 ".". - | -No | -
The specified resources will be included.
- -<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
- -- <include> - <javaresource name="common/targets.xml"> - <classpath location="common.jar"/> - </javaresource> - </include> -- -
Includes targets from the targets.xml file that is inside the - directory common inside the jar file common.jar.
- -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.
- -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 default="test"> - <target name="setUp"> - <property name="prop" value="in importing"/> - </target> - - <import file="nested.xml" as="nested"/> - - <target name="test" depends="nested.echo"/> -</project> -- -
Running the build file will emit: - -
-setUp: - -nested.echo: - [echo] prop has the value in importing - -test: - -- -
When using include like in
- --<project default="test"> - <target name="setUp"> - <property name="prop" value="in importing"/> - </target> - - <include file="nested.xml" as="nested"/> - - <target name="test" depends="nested.echo"/> -</project> -- -
Running the target build file will emit: - -
-nested.setUp: - -nested.echo: - [echo] prop has the value in nested - -test: - -- -
and there won't be any target named "echo" on the including build file.
- - - -- cgit