23 February 2011

Automating Adobe Air builds using Ant and Flex

A script-based automated build procedure is an essential part of a development process. Not only does it make it easier to support iterative development and regular builds but it paves the way for continuous integration testing to be established.

The Flex SDK does contain some support for build scripting with Apache Ant. However, as with all automated build management, some script hacking is required to get a smooth automated build working for an AIR application.

Getting an automated build to work reliably with Adobe AIR is complicated by the different libraries involved in compilation as well as the need to package up the application after it has been compiled. The following walk though explains how to get a reliable build up and running based on an example AIR project.

Download the example project for Flex Builder 4.5 (ZIP archive, 9KB)

Installing Ant

You can download and install Ant by unzipping it into a local directory. You will also need a compatible version of the Java Development Kit. Once these are in place you should set the following environment variables so you can run Ant cleanly on the command line:

set ANT_HOME=C:\Program Files (x86)\ANT
set JAVA_HOME=C:\Program Files (x86)\Java\jdk1.7.0
set PATH=%PATH%;%ANT_HOME%\bin

You can check that Ant is working by running “ant” on your command line – the following result indicates that Ant has been properly installed:

Buildfile: build.xml does not exist!
Build failed

Creating the Ant scripts

Once you have Ant installed you will have to set up your AIR project so it can be built by an Ant script. Ant is driven by an XML-based script format that specified the instructions for the build in a series of separate tasks.

The properties file

Ant uses an XML format to configure the build tasks. These files can get very long and can also have a number of environment-specific settings buried in them such as the source code location. It is generally regarded as good practice to separate these environment-specific settings into a separate file by creating a file called build.properties that is referenced directly from the build script.

The listing below shows an example of a properties file:

# This sets the Flex SDK path that is used throughout the build
FLEX_HOME=C:/Program Files (x86)/Adobe/Adobe Flash Builder 4.5/sdks/4.5.1

# Project locations for source files, libraries and output
SRC_DIR=${basedir}/src
LIBS_DIR =${basedir}/libs
DEPLOY_DIR =${basedir}/deploy

# Compilation settings
DEBUG=false
OPTIMIZE=true
LOCALE=en_US

Remember that Ant is a cross-platform Java tool so it is unforgiving about the formats of your paths–always use the forward slash when specifying paths rather than the backslash preferred by Windows.

The build script file

The build script is an XML file called build.xml which is also located in the home directory of your solution. The most significant part of the build script are the “target” elements, each of which define a build task. In the case of this script there are three main tasks that are chained together:

  • Creating a new deployment directory
  • Compiling the applications into SWF files
  • Packaging the application files up into a signed Adobe AIR file

The script below illustrates the full build file.

<project name="Flex Ant Tasks Build Script" default="air">

    <!-- Load the environment-specific properties -->
    <property file="build.properties" />

    <!-- Sets the FlexTasks.jar file that contains the build tasks -->
    <taskdef resource="flexTasks.tasks" classpath="${FLEX_HOME}/ant/lib/flexTasks.jar"/> 

    <!-- Start off by recreating the deployment directory -->
    <target name="init">
        <delete dir="${DEPLOY_DIR}" />
        <mkdir dir="${DEPLOY_DIR}" />
    </target>

    <!-- Build and output the main SWF file - repeat this for each SWF in the solution -->
    <target name="compile" depends="init">
        <mxmlc  file="${SRC_DIR}/AntExample.mxml"
                output="${DEPLOY_DIR}/AntExample.swf"
                debug="${DEBUG}"
                optimize="${OPTIMIZE}"
                locale="${LOCALE}"
                configname="air">
            <load-config filename="${FLEX_HOME}/frameworks/flex-config.xml"/>
            <source-path path-element="${SRC_DIR}"/>
            <library-path dir="${FLEX_HOME}/frameworks/libs" includes="*.swc" append="true"/>
            <library-path dir="${FLEX_HOME}/frameworks/libs/air" includes="*.swc" append="true"/>
            <library-path dir="${FLEX_HOME}/frameworks/locale" includes="${LOCALE}" append="true"/>
        </mxmlc>
    </target>

    <!-- Now create the AIR package using the ADT utility -->
    <target name="air" description="Create the AIR package" depends="compile">
        <exec executable="${FLEX_HOME}/bin/adt.bat" failonerror="true">
            <arg line="-package" />
            <arg line="-tsa none" />
            <arg line="-storetype pkcs12" />
            <arg line="-keystore ${basedir}/keys/AntExample.p12" />
            <arg line="-storepass password" />
            <arg line="${DEPLOY_DIR}/AntExample.air" />
            <arg line="${SRC_DIR}/AntExample-app.xml" />
            <arg line="-C ${DEPLOY_DIR} AntExample.swf" />
        </exec>
    </target>

</project>

There are a couple of things to note about the way this file has been set up:

  • The library-path elements are required to ensure that Ant can pick up the extra libraries required for an Adobe AIR application
  • The AIR packaging task uses a pre-configured key file
  • The script currently compiles a simple application that contains a single SWF file. You can add new content to the AIR package by adding items to the –C switch on on the “compile” target.

Building the application

You should now be able to build the project in a command prompt by navigating to the project’s root folder and entering “Ant” in the command line. Ant will pick up the build script and execute the tasks leaving some pretty verbose logging as it works.

Useful links

Download the example project for Flex Builder 4.5 (ZIP archive, 9KB)

Installing Ant: http://ant.apache.org/bindownload.cgi

Ant manual: http://ant.apache.org/manual/index.html

Installing the Java Development Kit: http://www.oracle.com/technetwork/java/javase/downloads/index.html

Filed under Development process, UI Development.