Using Apache Ant with the SDK tools

This topic provides examples of using the Apache Ant build tool to compile, test, and package AIR applications.

Note: This discussion does not attempt to provide a comprehensive outline of Apache Ant. For Ant documentation, see http://Ant.Apache.org.

Contents

Using Ant for simple projects

This example illustrates building an AIR application using Ant and the AIR command-line tools. A simple project structure is used with all files stored in a single directory.

Note: This example assumes that you are using the command line tools in the Flex 3 SDK rather than Flex Builder. The tools and configuration files in the SDKs included with Flex Builder are stored in a different directory structure.

To make it easier to reuse the build script, these examples use several defined properties. One set of properties identifies the installed locations of the command-line tools:

    <property name="SDK_HOME" value="C:/Flex3SDK"/>
    <property name="MXMLC.JAR" value="${SDK_HOME}/lib/mxmlc.jar"/>
    <property name="ADL" value="${SDK_HOME}/bin/adl.exe"/>
    <property name="ADT.JAR" value="${SDK_HOME}/lib/adt.jar"/>

The second set of properties is project specific. These properties assume a naming convention in which the application descriptor and AIR files are named based on the root source file. Other conventions are easily supported. The properties also define the MXMLC debug parameter as true (by default).

    <property name="APP_NAME" value="ExampleApplication"/>
    <property name="APP_ROOT" value="."/>
    <property name="MAIN_SOURCE_FILE" value="${APP_ROOT}/${APP_NAME}.mxml"/>
    <property name="APP_DESCRIPTOR" value="${APP_ROOT}/${APP_NAME}-app.xml"/>
    <property name="AIR_NAME" value="${APP_NAME}.air"/>
    <property name="DEBUG" value="true"/>
    <property name="STORETYPE" value="pkcs12"/>
    <property name="KEYSTORE" value="ExampleCert.p12"/>

Invoking the compiler

To invoke the compiler, the example uses a Java task to run mxmlc.jar:

<target name="compile">
    <java jar="${MXMLC.JAR}" fork="true" failonerror="true">
        <arg value="-debug=${DEBUG}"/>
        <arg value="+flexlib=${SDK_HOME}/frameworks"/>
        <arg value="+configname=air"/>
        <arg value="-file-specs=${MAIN_SOURCE_FILE}"/>
    </java>
</target>

When invoking mxmlc using Java, you must specify the +flexlib parameter. The +configname=air parameter instructs mxmlc to load the supplied AIR configuration file along with the normal Flex config file.

Invoking ADL to test an application

To run the application with ADL, use an exec task:

<target name="test" depends="compile">
    <exec executable="${ADL}">
        <arg value="${APP_DESCRIPTOR}"/>
    </exec> 
</target>

Invoking ADT to package an application

To package the application use a Java task to run the adt.jar tool:

<target name="package" depends="compile">
    <java jar="${ADT.JAR}" fork="true" failonerror="true">
        <arg value="-package"/>
        <arg value="-storetype"/>
        <arg value="${STORETYPE}"/>
        <arg value="-keystore"/>
        <arg value="${KEYSTORE}"/>
        <arg value="${AIR_NAME}"/>
        <arg value="${APP_DESCRIPTOR}"/>
        <arg value="${APP_NAME}.swf"/>
        <arg value="*.png"/>
    </java>
</target>

If your application has more files to package, you can add additional <arg> elements.

Using Ant for more complex projects

The directory structure of a typical application is more complex than a single directory. The following example illustrates a build file used to compile, test, and package an AIR application which has a more practical project directory structure.

This sample project stores the application source files and other assets like icon files within a src directory. The build script creates the following working directories:

build

Stores the release (non-debug) versions of compiled SWF files.

debug

Stores an unpackaged debug version of the application, including any compiled SWFs and asset files. The ADL utility runs the application from this directory.

release

Stores the final AIR package

The AIR tools require the use of some additional options when operating on files outside the current working directory:

Compiling

The -output option of the mxmlc compiler allows you to specify where to put the compiled file, in this case, in the build or debug subdirectories. To specify the output file, the line:
<arg value="-output=${debug}/${APP_ROOT_FILE}"/>
is added to the compilation task.

Testing

The second argument passed to ADL specifies the root directory of the AIR application. To specify the application root directory, the following line is added to the testing task:

<arg value="${debug}"/>

Packaging

Packaging files from subdirectories that should not be part of the final package structure requires using the -C directive to change the ADT working directory. When you use the -C directive, files and directories in the new working directory are copied to the root level of the AIR package file. Thus, -C build file.png copies file.png to the root of the application directoy. Likewise, -C assets icons copies the icon folder to the root level, and copies all the files and directories within the icons folder as well. For example, the following sequence of lines in the package task adds the icons directory directly to the root level of the application package file:

<arg value="-C"/>
<arg value="${assets}"/>
<arg value="icons"/>

Note: If you need to move many resources and assets into different relative locations, it is typically easier to marshall them into a temporary directory using Ant tasks than it is to build a complex argument list for ADT. Once your resources are organized, a simple ADT argument list can be used to package them.

<?xml version="1.0" ?>
<project>
    <!-- SDK properties -->
    <property name="SDK_HOME" value="C:/Flex3SDK"/>
    <property name="MXMLC.JAR" value="${SDK_HOME}/lib/mxmlc.jar"/>
    <property name="ADL" value="${SDK_HOME}/bin/adl.exe"/>
    <property name="ADT.JAR" value="${SDK_HOME}/lib/adt.jar"/>

    <!-- Project properties -->
    <property name="APP_NAME" value="ExampleApplication"/>
    <property name="APP_ROOT_DIR" value="."/>
    <property name="MAIN_SOURCE_FILE" value="${APP_ROOT_DIR}/src/${APP_NAME}.mxml"/>
    <property name="APP_ROOT_FILE" value="${APP_NAME}.swf"/>
    <property name="APP_DESCRIPTOR" value="${APP_ROOT_DIR}/${APP_NAME}-app.xml"/>
    <property name="AIR_NAME" value="${APP_NAME}.air"/>
    <property name="build" location="${APP_ROOT}/build"/>
    <property name="debug"  location="${APP_ROOT_DIR}/debug"/>
    <property name="release"  location="${APP_ROOT_DIR}/release"/>
    <property name="assets"  location="${APP_ROOT_DIR}/src/assets"/>
    <property name="STORETYPE" value="pkcs12"/>
    <property name="KEYSTORE" value="ExampleCert.p12"/>
    
     <target name="init" depends="clean">
        <mkdir dir="${build}"/>
        <mkdir dir="${debug}"/>
        <mkdir dir="${release}"/>
    </target>

    <target name="debugcompile" depends="init">
        <java jar="${MXMLC.JAR}" fork="true" failonerror="true">
            <arg value="-debug=true"/>
            <arg value="+flexlib=${SDK_HOME}/frameworks"/>
            <arg value="+configname=air"/>
            <arg value="-file-specs=${MAIN_SOURCE}"/>
            <arg value="-output=${debug}/${APP_ROOT_FILE}"/>
        </java>
        <copy todir="${debug}">
                <fileset dir="${assets}"/>
          </copy>
    </target>

    <target name="releasecompile" depends="init">
        <java jar="${MXMLC.JAR}" fork="true" failonerror="true">
            <arg value="-debug=false"/>
            <arg value="+flexlib=${SDK_HOME}/frameworks"/>
            <arg value="+configname=air"/>
            <arg value="-file-specs=${MAIN_SOURCE_FILE}"/>
            <arg value="-output=${build}/${APP_ROOT_FILE}"/>
        </java>
    </target>

    <target name="test" depends="debugcompile">
        <exec executable="${ADL}">
                <arg value="${APP_DESCRIPTOR}"/>
            <arg value="${debug}"/>
          </exec> 
    </target>

    <target name="package" depends="releasecompile">
        <java jar="${ADT.JAR}" fork="true" failonerror="true">
            <arg value="-package"/>
            <arg value="-storetype"/>
            <arg value="${STORETYPE}"/>
            <arg value="-keystore"/>
            <arg value="${KEYSTORE}"/>
            <arg value="${release}/${AIR_NAME}"/>
            <arg value="${APP_DESCRIPTOR}"/>
            <arg value="-C"/>
            <arg value="${build}"/>
            <arg value="${APP_ROOT_FILE}"/>
            <arg value="-C"/>
            <arg value="${assets}"/>
            <arg value="icons"/>
        </java>
    </target>

    <target name="clean" description="clean up">
        <delete dir="${build}"/>
        <delete dir="${debug}"/>
        <delete dir="${release}"/>
    </target>
</project>