It took me months to consider using Ant scripts for my Flash Builder projects. True to my principle ‘Two days of mouse-clicking save two hours of reading’, I kept ignoring the jumble that the scripts seemed to me, whenever I encountered them in examples, promising to myself to go back and have a proper look at them later.
This is a summary of the eight basic things you need to get you started with Ant scripts. Ant scripts are a time saver, I promise.
1. What is Ant and how can I get it?
Apache Ant is a command-line tool for automating software builds.
You can download it from The Apache Ant Project website. To use it you write an Ant script, which tells it how your piece of software should be built.
2. How do I write an Ant Script?
An Ant script is an XML file, which you’ll normally save as build.xml.
It has two main types of entries: <target> and <property>.
<target>
Think of <target> as a particular goal that you ask Ant to accomplish for you, for example ‘clean the project’ or ‘copy resources for building’ or ‘build the project’. To let it do that, in each <target> you list the tasks that will need to be performed to achieve the goal, for example ‘run the mxml compiler and tell it to do a clean’.
Here is an example target, which runs Adobe’s mxmlc compiler and builds an AIR app, called AirMobileApp:
[sourcecode language=”xml”]
<target name="build">
<exec executable="/Applications/Adobe Flash Builder 4.6/sdks/4.6.0/bin/mxmlc">
<arg line="
+configname=airmobile
-output ../bin-debug/AirMobileApp.swf
AirMobileApp.mxml
-source-path+=../src
-external-library-path+=../libs
"/>
</exec>
</target>
[/sourcecode]
Do you see what it does?
It literally says: run the mxmlxc executable and pass it this list of command-line arguments – the list in this entry:
[sourcecode language=”xml”]<arg line=" … "/>[/sourcecode]
<property>
You might have noticed that my target in the code snippet above uses hard-coded paths and file names. When you put together an Ant script for building your project you’ll probably want to use pretty much the same steps with other projects too, without having to rewrite the script or fiddle with it every time.
Think of <property> as a variable, which you define either in the same script file or in a file, which the script can include. It allows you to reuse the same script with different <property> values for each of your projects.
You have a choice of either:
- defining a property in your build.xml:
[sourcecode language=”xml”]<property name="MXMLC" value="/Applications/Adobe Flash Builder 4.6/sdks/4.6.0/bin/mxmlc"/>[/sourcecode]
- or defining it in a different file, for example local.properties (it doesn’t matter how you name it):
[sourcecode language=”xml”]MXMLC=/Applications/Adobe Flash Builder 4.6/sdks/4.6.0/bin/mxmlc[/sourcecode]
and then include this file in build.xml:
[sourcecode language=”xml”]<property file="local.properties" />[/sourcecode]
Here is the same example, this time with paths and names defined as properties:
[sourcecode language=”xml”]
<property name="MXMLC" value="/Applications/Adobe Flash Builder 4.6/sdks/4.6.0/bin/mxmlc"/>
<property name="app.name" value="AirMobileApp"/>
<property name="app.srcdir" value="../src"/>
<property name="app.builddir" value="../bin-debug"/>
<property name="app.libdir" value="../libs"/>
<target name="build">
<exec executable="${MXMLC}">
<arg line="
+configname=airmobile
-output ../${app.builddir}/${app.name}.swf
${app.name}.mxml
-source-path+=${app.sourcedir}
-external-library-path+=${app.libdir}
"/>
</exec>
</target>
[/sourcecode]
As you can see, the syntax for using a property in the Ant script is
You can define a property, using the values of an already defined property:
<property name="app.rootdir" value=".."/>
<property name="app.srcdir" value="${app.rootdir}/src"/>
<property name="app.builddir" value="${app.rootdir}/bin-debug"/>
<property name="app.libdir" value="${app.rootdir}/libs"/>
[/sourcecode]
3. How do I run an Ant Script?
On the command line run
[sourcecode language=”bash”]ant "the name of the target you want to run"[/sourcecode]
For example, to execute the ‘build’ target we specified above, you can run the following:
[sourcecode language=”bash”]ant build[/sourcecode]
Note that quotes are only necessary if your target name has spaces in it. Yep, spaces are allowed.
You can also run and execute a target by just typing
[sourcecode language=”bash”]ant[/sourcecode]
on the command line.
Which target will Ant execute then? The one you specified as default – read below.
4. How do I define a default target?
This you do in your build.xml’s top-level entry, which is called <project>. For example:
[sourcecode language=”xml”]
<project name="AirMobileApp" default="build">
…
</project>
[/sourcecode]
5. How do run multiple targets in a specific order?
You can break your tasks up into chunks and get Ant to execute them in a strict order by defining dependencies between them. For example, before building your SWF you want to make sure all resource files have been copied to the build dir. You can define this in a separate target and make your ‘build’ target dependent on it. Then, when Ant executes your ‘build’ target it will makes sure to do it after it has executed all targets that ‘build’ depends on:
[sourcecode language=”xml”]
<target name="copy files for building">
…
</target>
<target name="build" depends="copy files for building">
…
</target>
[/sourcecode]
6. Got it. Now show me a complete Ant Script
Here is a very minimal version.
[sourcecode language=”xml”]
<project name="AirMobileApp" default="build">
<property name="MXMLC" value="/Applications/Adobe Flash Builder 4.6/sdks/4.6.0/bin/mxmlc"/>
<property name="app.name" value="AirMobileApp"/>
<property name="app.srcdir" value="../src"/>
<property name="app.builddir" value="../bin-debug"/>
<property name="app.libdir" value="../libs"/>
<target name="build">
<exec executable="${MXMLC}">
<arg line="
+configname=airmobile
-output ../${app.builddir}/${app.name}.swf
${app.name}.mxml
-source-path+=${app.sourcedir}
-external-library-path+=${app.libdir}
"/>
</exec>
</target>
</project>
[/sourcecode]
7. What can I use to edit Ant scripts?
Any text or XML editor would do. Flash Builder has nice syntax highlighting.
8. Bonus: Ant perversions
Or… what will you make your ants do? You can make an Ant script run pretty much anything, right?
If you have any crazy ideas, I’d love to hear them – leave me a comment below.
