From 753a6c60f47f3ac4f270005b65e9d6481de8eb68 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 1.2.3-korg