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/import.html | 349 +++++++++++++++++++++ 1 file changed, 349 insertions(+) create mode 100644 framework/src/ant/apache-ant-1.9.6/manual/Tasks/import.html (limited to 'framework/src/ant/apache-ant-1.9.6/manual/Tasks/import.html') diff --git a/framework/src/ant/apache-ant-1.9.6/manual/Tasks/import.html b/framework/src/ant/apache-ant-1.9.6/manual/Tasks/import.html new file mode 100644 index 00000000..4cf8de08 --- /dev/null +++ b/framework/src/ant/apache-ant-1.9.6/manual/Tasks/import.html @@ -0,0 +1,349 @@ + + + + + + + Import Task + + +

Import

+

Description

+

+ Imports another build file into the current project. +

+ +

+ On execution it will select the proper ProjectHelper to parse the imported + file, using the same algorithm as the one executed at + startup. The selected ProjectHelper + instance will then be responsible to actually parse the imported file. +

+ +

+ Note as seen above, this task heavily relies on the ProjectHelper + implementation and doesn't really perform any work of its own. If + you have configured Apache Ant to use a ProjectHelper other than Ant's + default, this task may or may not work. +

+ +

+ In the common use case where only Ant's default project helper is + used, it basically works like the + Entity + Includes as explained in the Ant FAQ, as if the imported file was + contained in the importing file, minus the top <project> + tag. +

+ +

+ The import 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 overriding

+ +

If a target in the main file is also present in at least one of the +imported files, the one from the main file takes precedence.

+ +

So if I import for example a docsbuild.xml file named builddocs, +that contains a "docs" target, I can redefine it in my main +buildfile and that is the one that will be called. This makes it easy to +keep the same target name, so that the overriding target is still called +by any other targets--in either the main or imported buildfile(s)--for which +it is a dependency, with a different implementation. The target from docsbuild.xml is +made available by the name "builddocs.docs". +This enables the new implementation to call the old target, thus +enhancing it with tasks called before or after it.

+ +

If you use the as attribute of the task, its value will be + used to prefix the overridden target's name instead of the name + attribute of the project tag.

+ +

Special Properties

+ +

Imported 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 imported file, Ant adds a property that +contains the path to the imported buildfile. With this path, the +imported buildfile can keep resources and be able to reference them +relative to its position.

+ +

So if I import 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 imported project tag.

+

+ If the imported file does not have a name attribute, the ant.file.projectname + property will not be set. +

+ +

Since Ant 1.8.0 the task can also import resources from URLs or + classpath resources (which are URLs, really). 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 imported file

+ +

Suppose your main build file called importing.xml +imports a build file imported.xml, located anywhere on +the file system, and imported.xml reads a set of +properties from imported.properties:

+ +
<!-- importing.xml -->
+<project name="importing" basedir="." default="...">
+  <import file="${path_to_imported}/imported.xml"/>
+</project>
+
+<!-- imported.xml -->
+<project name="imported" basedir="." default="...">
+  <property file="imported.properties"/>
+</project>
+
+ +

This snippet however will resolve imported.properties +against the basedir of importing.xml, because the basedir +of imported.xml is ignored by Ant. The right way to use +imported.properties is:

+ +
+<!-- imported.xml -->
+<project name="imported" basedir="." default="...">
+  <dirname property="imported.basedir" file="${ant.file.imported}"/>
+  <property file="${imported.basedir}/imported.properties"/>
+</project>
+
+ +

As explained above ${ant.file.imported} stores the +path of the build script, that defines the project called +imported, (in short it stores the path to +imported.xml) and <dirname> takes its +directory. This technique also allows imported.xml to be +used as a standalone file (without being imported in other +project).

+ +

The above description only works for imported files that actually + are imported from files and not from URLs. For files imported from + URLs using resources relative to the imported 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.imported}"
+         relativePath="imported.properties"/>
+  </loadproperties>
+
+ +

Parameters

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + +
AttributeDescriptionRequired
+ file + + The file to import. If this is a relative file name, the file name will be resolved + relative to the importing 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 + imported file will be used. + No
+ 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 imported. Since Ant + 1.8.0

+ +

Examples

+
  <import file="../common-targets.xml"/>
+
+ +

Imports targets from the common-targets.xml file that is in a parent +directory.

+ +
  <import file="${deploy-platform}.xml"/>
+
+ +

Imports the project defined by the property deploy-platform

+ +
+  <import>
+    <javaresource name="common/targets.xml">
+      <classpath location="common.jar"/>
+    </javaresource>
+  </import>
+
+ +

Imports 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