Cari di Apache Ant 
    Apache Ant User Manual
Daftar Isi
(Sebelumnya) ImageInclude (Berikutnya)
Apache Ant Tasks

Import

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 andthat are not possible with entity includes:

  • target overriding
  • special properties

Target overriding

If a target in the main file is also present in at least one of theimported 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 mainbuildfile and that is the one that will be called. This makes it easy tokeep the same target name, so that the overriding target is still calledby any other targets--in either the main or imported buildfile(s)--for whichit is a dependency, with a different implementation. The target from docsbuild.xml ismade available by the name "builddocs.docs".This enables the new implementation to call the old target, thusenhancing 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 overriden target's name instead of the name attribute of the project tag.

Special Properties

Imported files are treated as they are present in the mainbuildfile. This makes it easy to understand, but it makes it impossiblefor them to reference files and resources relative to their path.Because of this, for every imported file, Ant adds a property thatcontains the path to the imported buildfile. With this path, theimported buildfile can keep resources and be able to reference themrelative 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.fileproperty of the main buildfile.

Note that "builddocs" is not the filename, but the name attributepresent 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.xmlimports a build file imported.xml, located anywhere onthe file system, and imported.xml reads a set ofproperties 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.propertiesagainst the basedir of importing.xml, because the basedirof imported.xml is ignored by Ant. The right way to useimported.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 thepath of the build script, that defines the project calledimported, (in short it stores the path toimported.xml) and <dirname> takes itsdirectory. This technique also allows imported.xml to beused as a standalone file (without being imported in otherproject).

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

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 ommitted, 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 resourcecollection

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

  <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 importingtest:

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 nestedtest:

and there won't be any target named "echo" on the including build file.

(Sebelumnya) ImageInclude (Berikutnya)