Import Task

Import

Description

Imports another build file into the current project.

On execution it will read another Ant file into the same Project. This means that 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
special properties

Target overriding

If a target in the main file is also present in at least one of the imported files, it 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 original target 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.

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.

Important: We have not finalized how relative file references will be resolved in deep/complex build hierarchies -such as what happens when an imported file imports another file. Use absolute references for enhanced build file stability, especially in the imported files.

Parameters

Attribute	Description	Required
file	The file to import.	Yes
optional	if true, do not issue stop the build if the file does not exist, default is false.	No

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