From b9421dc80af485591a9c50cc8921f912e0def11e Mon Sep 17 00:00:00 2001
From: Ashlee Young
- 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
- 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:
-Import
- Description
- <project>
- tag.
-
-
-
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.
- -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".
- -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> -- -
Attribute | -Description | -Required | -
- 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 | -
The specified resources will be imported. Since Ant - 1.8.0
- -<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.
- -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