Ant: The Definitive Guide

Environment DataType

The apply and exec tasks, which execute system commands, accept zero or more nested <env> elements. These elements specify which environment variables are passed to the system command being executed, and they are implemented by the org.apache.tools.ant.types.Environment.Variable class. The <env> element accepts the following attributes:

file (all, File,*)

A filename as the value of the environment variable. The name is converted to an absolute path.

key (all, String,Y)

The environment variable name.

path (all, Path, *)

A path as the value of the environment variable. Ant converts this to local conventions, as explained in “Path DataType.” For instance, foo.txt is converted into C:\path\to\file\foo.txt on Windows platforms.

value (all, String, *)

A literal value for the environment variable.

Exactly one of file, path, or value is required.

Example

The following example calls a batch file named deploy.bat. Within the batch file, the TOMCAT_HOME environment variable is available because of the <env> element:

<property name="tomcat.home" value="/path/to/tomcat"/>

<target name="deploy">
    <!-- Call a deployment script, setting up the TOMCAT_HOME -->
    <!-- environment variable.                                -->
    <exec executable="deploy.bat">
      <env key="TOMCAT_HOME" value="${tomcat.home}"/>
    </exec>
  </target>

Using Environment Variables in Buildfiles

The preceding example shows how you can pass environment variables to system commands using exec and env. Ant also allows you to use environment variables within your own buildfiles. This is an excellent way to avoid hardcoding, although it can limit portability. Because it deals with environment variables, using environment variables in buildfiles is closely related to the environment DataType. However, the environment DataType is not used to access environment variables from within Ant. Instead, this use of environment variables is implemented as a special feature of the property task, which is described in Chapter 7.

Warning

JDK 1.1.x applications can access environment variables using the System.getenv( ) method. As of JDK 1.2, however, System.getenv( ) is no longer supported. It is deprecated and throws an Error when called. Sun made the decision to deprecate this method because environment variables are not available on all platforms supported by Java. The designers of Ant, however, have implemented their own support for reading environment variables — but only on some platforms. Test this feature on platforms you are interested in before relying on it.

As an example, consider a weakness of the buildfile presented in Example 4-1. Look at this line:

  <property name="xalan.home" value="C:/java/xalan-j_2_1_0"/>

While this might work on your PC, it is highly unlikely to work on most other developers’ PCs. This is because they probably installed Xalan to a different directory. It is better if your buildfile requires developers to set the XALAN_HOME environment variable before they run it. Here are some changes to Example 4-1 that make this possible:

<?xml version="1.0"?>
<project name="arg demo" default="xslt" basedir=".">
  <!-- Set up the 'env' prefix for environment variables -->
  <property environment="env"/>
  <property name="xalan.home" value="${env.XALAN_HOME}"/>

  <!-- Abort the build if XALAN_HOME is not set -->
  <target name="checkXalanHome" unless="env.XALAN_HOME">
    <fail message="XALAN_HOME must be set!"/>
  </target>

  <target name="xslt" depends="checkXalanHome">
    ...
  </target>

</project>

The magic happens in this line:

  <property environment="env"/>

Now, you can reference any environment variable by prefixing the variable name with "env.". We also added another target that verifies the environment variable is set. If not, it warns the user and fails the build:

  <target name="checkXalanHome" unless="env.XALAN_HOME">
    <fail message="XALAN_HOME must be set!"/>
  </target>