From 753a6c60f47f3ac4f270005b65e9d6481de8eb68 Mon Sep 17 00:00:00 2001 From: Ashlee Young Date: Fri, 23 Oct 2015 10:00:02 -0700 Subject: Adding maven and ant source trees Change-Id: I0a39b9add833a31b9c3f98d193983ae2f3a5a445 Signed-off-by: Ashlee Young --- .../ant/apache-ant-1.9.6/manual/Tasks/include.html | 344 +++++++++++++++++++++ 1 file changed, 344 insertions(+) create mode 100644 framework/src/ant/apache-ant-1.9.6/manual/Tasks/include.html (limited to 'framework/src/ant/apache-ant-1.9.6/manual/Tasks/include.html') diff --git a/framework/src/ant/apache-ant-1.9.6/manual/Tasks/include.html b/framework/src/ant/apache-ant-1.9.6/manual/Tasks/include.html new file mode 100644 index 00000000..e2109235 --- /dev/null +++ b/framework/src/ant/apache-ant-1.9.6/manual/Tasks/include.html @@ -0,0 +1,344 @@ + + + + + + + Include Task + + +

Include

+

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

+ +

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:

+ +
<!-- 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>
+
+ +

Parameters

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

Parameters specified as nested elements

+ +

any resource or resource +collection

+ +

The specified resources will be included.

+ +

Examples

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

+ +

How is <import> different + from <include>?

+ +

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.

+ +

Examples

+ +

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