Apache Ant

Creating your build file

Open your text editor and create a new file. Add the line below to the very beginning of the file. This line will identify this file as an XML file. It is very important that no text or whitespace preceed this line. Now save this file as build.xml under your [PROJECT_HOME] directory.

<?xml version="1.0" encoding="utf-8"?>

Next, we define our project using Ant's project tag. Using the tag's name and basedir attributes we specify a project name and base directory. Setting the basedir attribute to a period indcates that it will use the current directory. The remaining Ant tags we will be defining should be placed inside this project tag.

<project name="My Flex App" basedir=".">

</project>

To use the Flex Ant Task library we must define a task definition. We do this by adding the following task definition tag immediately after are opening project tag.

<taskdef resource="flexTasks.tasks"/>

After the task definition tag we define some Ant properties that we will be using in our build file. The first and most important property is the FLEX_HOME property. The FLEX_HOME property is required by the Flex Ant Task to locate the Flex compilers. Create a FLEX_HOME property and set its location attribute to the [FLEX_SDK] directory (example: C:\Flex). Create a app.name property and set its value attribute to any name you like. We will refer to this name as [APP_NAME]. The app.name property is used as the zip file name when you distribute your project and it is also passed to the mxmlc compiler as the context-root name. The context-root is used when referencing your Flex application on the URL so it is important that your app.name property not contain any special characters or spaces. We will refer to your server as [SERVER_NAME].

http://[SERVER_NAME]/[APP_NAME]

The remaining properties defined are used to provide short-cuts to directories in the [PROJECT_HOME] directory.

<property name="FLEX_HOME"   location="[FLEX_SDK]"/>
<property name="app.name"    value="[APP_NAME]"/>
<property name="build.home"  location="${basedir}/build"/>
<property name="src.home"    location="${basedir}/src"/>
<property name="web.home"    location="${basedir}/web"/>
<property name="lib.home"    location="${basedir}/lib"/>
<property name="config.home" location="${basedir}/config"/>
<property name="dist.home"   location="${basedir}/dist"/>
<property name="docs.home"   location="${basedir}/docs"/>

Now we define our first target. The clean target will be used to clean-up between builds and distributions.

<target name="clean">
   <delete includeemptydirs="true">
      <fileset dir="${build.home}" includes="**/*"/>
      <fileset dir="${dist.home}" includes="**/*"/>
   </delete>
</target>

The prepare target will prepare the build directory for distribution. It begins by creating the build/${app.name} directory if it does not already exist. It then copies our php source and web directories over to the build/${app.name} directory.

<target name="prepare">
   <mkdir dir="${build.home}/${app.name}"/>
   <copy todir="${build.home}/${app.name}">
      <fileset dir="${src.home}/php"/>
      <fileset dir="${web.home}"/>
   </copy>
</target>

The compile target will compile our Main.mxml file using the Flex Ant Task mxmlc tag. The mxmlc tags contains several attributes and subtags that control how Flex will complie our applicaton.

• The file attribute specifies the source file that the Flex compiler will use when compiling our application. Set this attribute to ${src.home}/flex/Main.mxml.
• The output attribute specifies the location and name of our resulting swf file. Set this attribute to ${build.home}/${app.name}/Main.swf .
• The context-root attribute specifies the context-root our Flex application will use. Set this attribute to ${app.name} so that it uses the ${app.name} property.
• The services attribute specifies the location of our services-config.xml file. Set this attribute to ${config.home}/flex/services-config.xml.
• The load-config subtag specifies the location of the flex-config.xml file using the filename attribute. Set the filename attribute to ${FLEX_HOME}/frameworks/flex-config.xml. This is the default Flex complier configuration file that is distributed with the Flex 2 SDK.
• The source-path subtag specifies the location of the source files using the path-element attribute. We declare two source-path subtags. Set the path-element on the first to ${FLEX_HOME}/frameworks to include the Flex 2 SDK in the source path. Set the path-element on the second to ${src.home}/flex to include our project's Actionscript source code.
• The subtag specifies the location of SWC library files using the . The library-path subtag contains several include subtags which are used to specify other files and directories to include. Set the dir attribute of the library-path subtag to ${FLEX_HOME}/frameworks. Set the name attribute of the first include subtag to include the Flex 2 SDK libraries. Set the name attribute of the second include subtag to include the Flex 2 SDK bundles. Set the name attribute of the third include subtag to include our project's Actionscript libraries.
• The default-size subtag specifies our Flex applications default size. Set the width attribute to 500 and the height attribute to 600.

<target name="compile" depends="prepare">
   <mxmlc
      file="${src.home}/flex/Main.mxml"
      output="${build.home}/${app.name}/Main.swf"
      actionscript-file-encoding="UTF-8"
      context-root="${app.name}"
      services="${config.home}/flex/services-config.xml">

      <!-- Get default compiler options. -->
      <load-config filename="${FLEX_HOME}/frameworks/flex-config.xml"/>

      <!-- List of path elements that form the roots of ActionScript class hierarchies. -->
      <source-path path-element="${FLEX_HOME}/frameworks"/>
      <source-path path-element="${src.home}/flex"/>

      <!-- List of SWC files or directories that contain SWC files. -->
      <compiler.library-path dir="${FLEX_HOME}/frameworks" append="true">
            <include name="libs" />
            <include name="../bundles/{locale}" />
            <include name="${lib.home}/flex/" />
      </compiler.library-path>

      <!-- Set size of output SWF file. -->
      <default-size width="500" height="600" />
   </mxmlc>
</target>

The distribute target will create a zip file of our project for easy distribution.

<target name="dist" depends="compile">
   <zip destfile="${dist.home}/${app.name}.zip"
      basedir="${build.home}"
      update="true"/>
</target>

The deploy target is optional. I provided it to make project deployment even easier for those using remote servers. If you want to use the FTP task ant provides you must have commons-net-1.4.1.jar and jakarta-oro-2.0.8.jar in the [ANT_HOME]/lib directory. Replace the server attribute with your server. The app.name property in the remotedir attribute must exist prior to running the deploy task. Do not remove the app.name property from the remotedir attribute because your Flex application was compiled using app.name as the context-root.

<target name="deploy" depends="compile">
   <ftp server="[SERVER_NAME]"
      remotedir="/home/username/www/${app.name}"
      userid="username"
      password="password"
      depends="yes">
      <fileset dir="${build.home}/${app.name}"/>
   </ftp>
</target>

Build,Deploy and Distribute your Project

Run the following commands from your [PROJECT_HOME] directory. Windows users can use the command-prompt. Linux and Mac users can use the terminal.

To compile your project run the compile task. When the compile task has finished executing you will have a directory in your [PROJECT_HOME]/build directory with the name you specified in the app.name property. Copy or ftp the app.name directory to your web server's document root directory.

ant compile

To deploy your project run the deploy task. This task will ftp the contents of the [PROJECT_HOME]/build directory to your web server's document root directory.

ant deploy

To distribute your project run the dist task. This task will zip the contents of the [PROJECT_HOME]/build directory. The zip file name will be the one you specified in the app.name property.

ant dist

Running your Application

Testing your PHP services

Before running our Flex application we need to test our php services to ensure that are functioning correctly. We can test our php services using the Amfphp services browser. Substitute <context-root> with the value you used for the app.name propery.

http://[SERVER_NAME]/[APP_NAME]/amfphp/browser/

Run your Application

http://[SERVER_NAME]/[APP_NAME]/Main.swf