Section 2.2. Using Property Files

2.2. Using Property Files

In larger build files, you might be working with dozens of properties, and storing them in property files is common. Setting tens, or hundreds, of properties all within a build file is a bad habit to get into and almost impossible to maintain.

Using property files means that you can quickly tailor a build file to different sets of circumstances by swapping property files. And you can store property values; though we've been using mostly true/false properties to make conditional processing easier, they can hold all kinds of textual data, such as copyright notices and legal information, in a central repository everyone can share.

You can specify a property file to use on the command line with the -propertyfile option.

Take a look at Example 2-2, which uses a property file to hold a property named message. This example points to the property file with the property task's file attribute, which can hold the fully qualified name of the file. You can use the property task's url attribute to point to a property file.

Example 2-2. Using a property file (ch02/properties/build.xml)

<?xml version="1.0" ?> <project default="main">     <property file="build.properties" />     <property name="src" location="source" />     <property name="output" location="bin" />     <target name="main" depends="init, compile, compress">         <echo>             ${message}         </echo>     </target>        <target name="init">         <mkdir dir="${output}" />     </target>        <target name="compile">         <javac srcdir="${src}" destdir="${output}" />     </target>      <target name="compress">         <jar destfile="${output}/Project.jar" basedir="${output}" includes="*.class" />   </target> </project>

Here are the entire contents of another sample file, build.properties, which uses a name=value format for each property:

message=Building the .jar file.

Using the build file from Example 2-2, here's the output from running Ant; note the value of the message property was picked up correctly from build.properties:

%ant  Buildfile: build.xml init:     [mkdir] Created dir: /home/steve/ch02/properties/bin compile:     [javac] Compiling 1 source file to /home/steve/ch02/properties/bin compress:       [jar] Building jar: /home/steve/ch02/properties/bin/Project.jar main:      [echo]      [echo]             Building the .jar file.      [echo] BUILD SUCCESSFUL Total time: 3 seconds

Properties in external files are stored as text strings, suitable for properties of the kind you'd set with the property task's value attribute.

Ant has an optional task, propertyfile, that lets you edit property files. This can be useful when you need to make unattended modifications to configuration files when deploying to servers.

2.2.1. Loading Text

You can use the loadfile task to load a text file into a single property. Here's an example that loads the property message with the text in the file message.txt:

<loadfile property="message"     srcFile="message.txt"/>

You can see the attributes of this task in Table 2-6.

Table 2-6. The loadfile task's attributes

Attribute	Description	Required	Default
srcFile	Indicates the source file	Yes
property	Indicates the property you want to store the text in	Yes
encoding	Indicates the encoding you want to use when reading text from the file	No
failonerror	Set to true if you want to halt the build if this task failed	No	TRue

2.2.2. Overriding Properties

Take a look at Example 2-3, defining a property named message twice ("Building the .jar file.") and then redefining it ("Compiling and compressing.").

Example 2-3. Overriding a property (ch02/overriding/build.xml)

<?xml version="1.0" ?> <project default="main">     <property name="message" value="Building the .jar file." />     <property name="src" location="source" />     <property name="output" location="bin" />     <property name="message" value="Compiling and compressing." />     <target name="main" depends="init, compile, compress">         <echo>             ${message}         </echo>     </target>        <target name="init">         <mkdir dir="${output}" />     </target>        <target name="compile">         <javac srcdir="${src}" destdir="${output}" />     </target>      <target name="compress">         <jar destfile="${output}/Project.jar" basedir="${output}" includes="*.class" />   </target> </project>

This attempts to override the property with a new definition. Once you define a property in a build file, it behaves much like a constantie., you can't redefine it inside the build file. So, when you run Ant using this build file, you'll see the first version of the property:

init:     [mkdir] Created dir: /home/steve/ch02/properties/bin compile:     [javac] Compiling 1 source file to /home/steve/ch02/properties/bin compress:       [jar] Building jar: /home/steve/ch02/properties/bin/Project.jar main:      [echo]      [echo]             Building the .jar file.      [echo] BUILD SUCCESSFUL Total time: 3 seconds

When Ant sees a property defined, whether in a build or a property file, it considers that property defined. You can't change it.

Except in one way. (Of course! Who wants a language without exceptions?)

If you want to override a property in a build file, you can set properties on the command line. That can be done with the -Dproperty=value option, where property is the name of the property and value is the value for that property. If you specify a property set in the build file, the value specified on the command line will override the value specified in the build file.

Here's how to do that:

%ant -Dmessage="Compiling and compressing" Buildfile: build.xml init:     [mkdir] Created dir: /home/steve/ch02/properties/bin compile:     [javac] Compiling 1 source file to /home/steve/ch02/properties/bin compress:       [jar] Building jar: /home/steve/ch02/properties/bin/Project.jar main:      [echo]      [echo]             Compiling and compressing      [echo] BUILD SUCCESSFUL Total time: 3 seconds

The value on the command line overrides both of the values within the build file.

2.2.3. Setting Properties Using Environment Variables

You can access environment variables with the property element's environment attribute, which sets the prefix to use for environment variables ("env" is customary in Ant files); after you set that prefix, you can reference environment variables by name using that prefix. Here's an example build file that displays the value of ANT_HOME:

<project default="main">     <property file="build.properties" />     <property name="src" location="source" />     <property name="output" location="bin" />     <property environment="env" />     <target name="main" depends="init, compile, compress">         <echo>             ${env.ANT_HOME}         </echo>     </target>         .         .         .

Here's the result of running Ant using this build file:

%ant  Buildfile: build.xml init: compile: compress: main:      [echo]      [echo]             C:\ant\apache-ant-1.6.1      [echo] BUILD SUCCESSFUL Total time: 2 seconds

It's easy to pass environment variables from the command line as well; use -DVAR=%ENV_VAR% (Windows) or -DVAR=$ENV_VAR (Unix). You can then access these variables inside your build file as ${VAR}.

You've got a good handle on properties at this point, and they're a major building block of Ant build files. The next step up is to work with the built-in Ant types.