Section 3.4. Importing Other Build Files

3.4. Importing Other Build Files

With ant, you can execute build files outside the current build file, and you can include other build files in the current file. The old way of doing this was to rely on XML and the Ant XML parser to do the work for you. For example, if you wanted to include the entire contents of a document named shared.xml at a specific point in a build file, you could start by declaring an XML entity named, say, shared in your build file:

<?xml version="1.0"?> <!DOCTYPE project [     <!ENTITY shared SYSTEM "file:shared.xml"> ]>         .         .         .

To insert the contents of the shared.xml build file into the current build file, you can use an XML entity reference, &shared;, like this:

<?xml version="1.0"?> <!DOCTYPE project [     <!ENTITY shared SYSTEM "file:shared.xml"> ]> <project default="main" basedir=".">     &shared;     <target name="init">         .         .         .     </target>         .         .         . </project>

Since Ant 1.6, however, there is a new import task that can be used to include build files. The referenced files have to be complete Ant build files, which are inserted whole (minus the XML declaration and <project> and </project> tags). Here's how the above example would work using the import task:

<?xml version="1.0"?> <project default="main" basedir=".">   <import file="shared.xml"/>     <target name="init">         .         .         .     </target>         .         .         . </project>

The attributes of the import task appear in Table 3-8.

Table 3-8. The import task's attributes

Attribute	Description	Required	Default
file	Specifies the name of the build file you want to import	Yes
optional	Specifies whether you want to stop the build if the build file to import does not exist	No	false

Unlike entity includes, you can deference a property with ${ and } to set the name of the file to import with the import task. In addition, if a target with the same name exists, it takes precedence over the target you're importing.

The import task makes it easier to handle relative paths as defined in the imported build file. It does this by creating a new property corresponding to the absolute path of the imported build file so you can resolve relative file references.

Ant has a property called ant.file that contains the absolute path of the build file (see Chapter 1), so this task creates a new property based on the name of the file you're importing. For example, if you import a build file named newbuild, the new location property will be named ant.file.newbuild.

Now that you've built your application with the various tasks seen in this chapter, it's time for some documentation.