3.6 Passing Arguments to a Buildfile

3.6.1 Problem

You want to pass system properties to a buildfile. Java system properties are a more portable alternative to environment variables.

3.6.2 Solution

Pass the system properties to Ant using the -D command-line argument. For example:

ant -Dprop1="My Property" run

Within the buildfile, refer to the property using Ant's ${prop1} syntax. You can specify default values for properties using the <property> tag, and you can pass system properties to Java applications using the <sysproperty> tag nested within the <java> element.

3.6.3 Discussion

Example 3-3 shows an Ant buildfile that demonstrates system properties. It echoes the property name/value pairs to the console, and then invokes a Java application that echoes the same properties.

Example 3-3. Buildfile demonstrating system properties

<?xml version="1.0"?>
<project name="sysprops" default="run" basedir=".">
  <!-- define two properties -->
  <property name="prop1" value="Property 1 from Buildfile"/>
  <property name="prop2" value="Property 2 from Buildfile"/>

  <target name="clean">
    <delete dir="com"/>
  </target>

  <target name="compile">
    <javac srcdir="." destdir=".">
      <classpath path="."/>
    </javac>
  </target>

  <target name="run" depends="compile">
    <!-- echo each of the properties to the console -->
    <echo message="Now in buildfile..."/>
    <echo message="prop1     = ${prop1}"/>
    <echo message="prop2     = ${prop2}"/>
    <!-- The 'prop3' property must be defined on the command 
         line or it shows up like '${prop3}' -->
    <echo message="prop3     = ${prop3}"/>
    <echo message="user.home = ${user.home}"/>

    <!-- execute the main(  ) method in a Java class -->
    <java classname="com.oreilly.javaxp.ShowProps">
      <classpath path="."/>
      <!-- pass one of the properties -->
      <sysproperty key="prop1" value="${prop1}"/>
    </java>
  </target>

</project>

Our buildfile defines two properties. Regardless of where properties are defined, they are globally visible:

<property name="prop1" value="Property 1 from Buildfile"/>
<property name="prop2" value="Property 2 from Buildfile"/>

Properties are always name/value pairs, and can be overridden from the command line (shown shortly). They are referenced later in the buildfile using the ${prop1} and ${prop2} syntax. The run target echoes these property name/value pairs, and you can override them from the command-line:

<echo message="prop1     = ${prop1}"/>
<echo message="prop2     = ${prop2}"/>
<!-- The 'prop3' property must be defined on the command 
     line or it shows up like '${prop3}' -->
<echo message="prop3     = ${prop3}"/>
<echo message="user.home = ${user.home}"/>

As you can see, the buildfile tries to echo prop3 and user.home, even though they were not defined earlier. As the comment indicates, the value for prop3 must be specified on the command-line or it will be undefined. The user.home property is a standard Java system property, so it will have a default value.

Finally, the buildfile invokes a Java application, but passes only one of the properties:

<!-- pass one of the properties -->
<sysproperty key="prop1" value="${prop1}"/>

Now let's look at a little Java program that displays the same properties. Example 3-4 shows how you use System.getProperty( ) to retrieve system properties.

Example 3-4. Java application to print properties

package com.oreilly.javaxp;

public class ShowProps {
    public static void main(String[] args) {
        System.out.println("Now in ShowProps class...");
        System.out.println("prop1     = " + System.getProperty("prop1"));
        System.out.println("prop2     = " + System.getProperty("prop2"));
        System.out.println("prop3     = " + System.getProperty("prop3"));
        System.out.println("user.home = " + 
                System.getProperty("user.home"));
    }
}

To tie this all together, let's look at some sample output. When the user types ant, they see the output shown next. This is the result of the default target, run, being executed.

     [echo] Now in buildfile...
     [echo] prop1     = Property 1 from Buildfile
     [echo] prop2     = Property 2 from Buildfile
     [echo] prop3     = ${prop3}
     [echo] user.home = C:\Documents and Settings\ericb
     [java] Now in ShowProps class...
     [java] prop1     = Property 1 from Buildfile
     [java] prop2     = null
     [java] prop3     = null
     [java] user.home = C:\Documents and Settings\ericb

As you can see, prop3 is undefined in the buildfile because it was not specified on the command line. The user.home property is available because the Java runtime sets it for us. Once the demonstration enters the ShowProps class, we see that properties are not automatically propagated from the Ant buildfile to Java applications. The value for prop1 is available to the ShowProps application because it was explicitly passed using <sysproperty>.

Here is the output when you type ant -Dprop1="First Prop" -Dprop3="Third Prop" on the command line:

     [echo] Now in buildfile...
     [echo] prop1     = First Prop
     [echo] prop2     = Property 2 from Buildfile
     [echo] prop3     = Third Prop
     [echo] user.home = C:\Documents and Settings\ericb
     [java] Now in ShowProps class...
     [java] prop1     = First Prop
     [java] prop2     = null
     [java] prop3     = null
     [java] user.home = C:\Documents and Settings\ericb

To summarize, this shows how we can pass system properties from the command line to the Ant buildfile. Once inside the buildfile, we can use <sysproperty> to pass the properties to Java applications. This is a useful technique because we can use properties to avoid hardcoded values in buildfiles and Java programs.

3.6.4 See Also

See the JavaDoc for java.lang.System for a list of standard system properties. Use Ant's echoproperties task to list all properties in the current project.