Flash AS3 Project using Ant
Creating a pure AS3 (no Flex) project using Ant and command line tools has not been the easiest thing to learn. I wanted to summarize what I’d pulled together here so I have a reference for later projects and for any of you who might be starting down this path.
First, let me give you an overview of the file structure I’m using.
My main folders are “ant”, “build”, “html-template”, and “src”. The “ant” folder contains properties and configuration specific to the ant tasks. Everything in my build folder will be generated by the ant script. It’s completely empty right now. The “src” folder contains all of my Flash AS3 code, whether as AS files or SWCs.
In this example, I’m working with an extremely basic Flash document. Since we’re compiling with Ant and not Flash or Flex, we don’t need an FLA or an MXML, we just need an AS file. Here’s mine:
package org.tomasino.projects.antexample
{
import flash.display.Sprite;
import flash.events.Event;
[SWF(width="800", height="600", frameRate="30", backgroundColor="#FFFFFF")]
public class Example extends Sprite
{
public function Example ():void
{
if (this.stage) init();
else addEventListener (Event.ADDED_TO_STAGE, init);
}
private function init (e:Event = null):void
{
removeEventListener (Event.ADDED_TO_STAGE, init);
}
}
}
The “html-template” folder will have its contents and structure copied into “build” when we run the Ant script later on. I started using this habit with Eclipse and I’ve come to like it. I can keep my nice, clean, template code in a place all by itself. If necessary, I can do some processing on it with the Ant script later on, only including certain files in certain situations. For now, I’m just copying what I need, including the index file. Here it is:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
<head>
<title>Ant Flash Example</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<link rel="stylesheet" type="text/css" media="screen" href="css/styles.css.php" />
<script type="text/javascript" src="js/swfobject.js"></script>
<script type="text/javascript">
var swfVersionStr = "11.0.0";
var xiSwfUrlStr = "playerProductInstall.swf";
var flashvars = {};
var params = {};
var attributes = {};
var flashObject;
// When Flash is loaded, store reference to FlashObject for easy ExternalInterface calls
function flashReady (status)
{
if (status.success)
{
flashObject = status.ref;
}
}
params.quality = "high";
params.allowscriptaccess = "sameDomain";
params.allowfullscreen = "true";
params.wmode = "transparent";
swfobject.embedSWF( "example.swf", "flash", "800", "600", swfVersionStr, xiSwfUrlStr, flashvars, params, attributes, flashReady);
</script>
</head>
<body>
<div id="flash">
<h1>Adobe Flash Player Needed</h1>
<p><a href="http://www.adobe.com/go/getflashplayer"><img src="http://www.adobe.com/images/shared/download_buttons/get_flash_player.gif" alt="Get Adobe Flash player" /></a></p>
</div>
</body>
</html>
You might notice that I’m using the CSS optimizer from an earlier post. I’ve also included a callback method in my swfobject.embedSWF line, called “flashReady”. When SWFObject loads my SWF, this method will be called immediately where it will store a reference to the Flash object. If you’ve used ExternalInterface callbacks before, you know it can be difficult to figure out how to reference the Flash object in every browser. SWFObject makes it easy with this little trick.
Finally: the important stuff. The Ant script (build.xml in my folder) is the heart of the project. To run it, drop to terminal, change directory to the folder and type “ant”. It will run the “compile” target by default. Let’s take a look:
<project name="antExample" default="compile" basedir="." >
<description>
Ant Example
</description>
<property file="ant/local.properties" description="local build configuration."/>
<property file="ant/build.properties" description="build configuration."/>
<taskdef resource="flexTasks.tasks" classpath="${FLEX_HOME}/ant/lib/flexTasks.jar" />
<!-- Create the build folder for project -->
<target name="make_build">
<mkdir dir="${build.dir}"/>
</target>
<!-- Copy template folder to build -->
<target name="make_template" depends="make_build" unless="nochanges_template">
<copy todir="${build.dir}">
<fileset dir="${template.dir}">
<include name="**/css/**"/>
<include name="**/images/**"/>
<include name="**/js/**"/>
<include name="*.html"/>
</fileset>
</copy>
</target>
<!-- Compile SWF to build -->
<target name="make_swf" depends="make_template" unless="nochanges_flash">
<mxmlc
file="${src.dir}/org/tomasino/projects/antexample/Example.as"
output="${build.dir}/example.swf"
actionscript-file-encoding="UTF-8"
keep-generated-actionscript="false"
optimize="true"
>
<!-- Get default compiler options. Hand modified to remove extraneous Flex trash -->
<load-config filename="ant/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.dir}" />
<source-path path-element="${tomasinolibs.dir}" />
<!-- List of SWC files or directories that contain SWC files. -->
<compiler.library-path dir="${libs.dir}" append="true">
<!-- <include name="example.swc" /> -->
</compiler.library-path>
<!-- Flags -->
<compiler.debug>false</compiler.debug>
</mxmlc>
</target>
<!-- Test for dependencies and changes -->
<target name="init">
<uptodate property="nochanges_flash" targetfile="${build.dir}/example.swf">
<srcfiles dir="${src.dir}" includes="**/**"/>
</uptodate>
<uptodate property="nochanges_template" targetfile="${build.dir}/index.html">
<srcfiles dir="${template.dir}" includes="**/**"/>
</uptodate>
<condition property="build.exists">
<available file="${build.dir}" type="dir"/>
</condition>
</target>
<!-- Cleanup -->
<target name="clean" depends="init" if="build.exists">
<delete dir="${build.dir}"/>
</target>
<!-- Compile SWF -->
<target name="compile" depends="init, make_swf" />
</project>
build.properties file defines the common properties in the project.
FLEX_HOME = OVERRIDE IN LOCAL PROPERTIES src.dir = src libs.dir = src/libs build.dir = build template.dir = html-template
local.properties file defines the local properties that override defaults. These are used to dictate the developer-specific paths.
FLEX_HOME = /Applications/Adobe Flash Builder 4/sdks/4.5.1.21328 tomasinolibs.dir = /Users/artist/Documents/tomasino
The targets are listed in order of dependency for ease of use. The “compile” target depends on “make_swf” which depends on “make_template” which depends on “make_build”. I built those names and structure myself, so don’t think of it as a required way of doing things. It just helps me keep things straight.
The “make_swf” target performs the actual SWF compilation using the mxmlc task provided by flexTasks.jar. You’ll notice up near the top I am including this jar file. Without it, ant has no idea what a SWF is or what to do with it. I should also note that I’m including a property reference to the Flex SDK in the local.properties file. You can see we’re using that inside the mxmlc block. The mxmlc block gets its configuration settings from config.xml, included in the ant folder. I edited the Flex configuration file to remove all the non-Pure AS3 references. All of this is free stuff, of course.
Just to illustrate how to do it, I’m including my own “tomasino” source in this project. It’s not being used by my example, but it could be. The <source-path> element dictates where all these things are found. The <compiler.library-path> element would contain any SWCs you need to include. If it’s not easily relative to the project, you can go ahead and give it an absolute path (in the local.properties file).
The “make_template” target is copying the files from the “html-template” folder into the “build” folder. The “make_build” target creates the “build” folder (if it doesn’t exist already). The “clean” target deletes the “build” folder and its contents to make sure we always start fresh.
Just a few final notes about ant. Properties are your variables, of a sort, though they are generally not assigned multiple different values in a script. Ant is not a programming language, and you’ll continuously run into walls if you forget that. There are no loops, for instance (if you want them, check out ant-contrib). I’ve named my properties with “.dir” suffixes to let me know if it’s a directory versus a folder name, for example. It’s all style, though. FLEX_HOME seems to require that it be named with all-caps for some reason. It may just be a bug in the code when I was testing changing it, but I left it anyway.
That’s it. I hope it wasn’t overwhelming. I didn’t cover how to install ant, so if you’re on a Windows box, you might want to google that. Please, grab the project and play around with it. Let me know if you have any suggestions or questions.
Thank you, for your example