B.18 ImportTask
Prev | Appendix B. Core tasks | Next

## B.18 ImportTask

Imports another build file into the current project.

On execution it will read another Phing file into the same Project. Functionally it is nearly the same as copy and pasting the imported file onto the end of the importing file.

The import task may only be used as a top-level task. This means that it may not be used in a target.

Table B.19: Attributes

Name | Type | Description | Default | Required
--- | --- | --- | --- | ---
`file` | `String` | The file to import. | n/a | Yes
`optional` | `Boolean` | If true, do not stop the build if the file does not exist. | `false` | No

### B.18.1 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 `docs/build.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 `docs/build.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.

### B.18.2 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, Phing 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 `docs/build.xml` file named `builddocs`, I can get its path as `phing.file.builddocs`, similarly to the `phing.file` property of the main buildfile. Additionally, the directory will be stored in `phing.dir.builddocs`.

Note that "builddocs" is not the filename, but the name attribute present in the imported project tag.

If import file does not have a name attribute, the `phing.file.projectname` and `phing.dir.projectname` properties will not be set.

### B.18.3 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 Phing. The right way to use `imported.properties` is:

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

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

### B.18.4 Examples

    <import file="path/to/build.xml"/>
    <import file="path/to/build.xml" optional="true"/>

Prev | Up | Next
B.17 IfTask | Home | B.19 IncludePathTask