Using ANT to build an Application

Building a Flex project with an ANT build file is not a skill that every Flex developer will need, but once you get into Enterprise Application Development it really becomes a necessity. The interconnection between developers, system admins, and managers (that may or may not know anything) is a complicated beast to keep up.

It is wonderfule to be able to use ANT to build the entire enterprise application without you – the Flex dev – always having to be present.

If you have worked with ANT and building Flex Apps with ANT before this may be very simple for you, if you haven’t, this will get you right into it very easily. Over the next few weeks plan to see many more installments into this series, ending with an entire Continuous Integration Stack suitable for any Enterprise Environment.

Let’s Begin
Your application is made, now you need to make a build file to be run by ANT. My application being shown is really simple, just a Label in the Application, nothing special. What we are creating is just an XML file that gives basic commands to ANT that will compile your application just as if you were compiling your application in the Flash/Flex Builder.

First, the App

I know, completely blew your mind right?

Defining the ANT Build Files
My ANT setup includes two files, the first build.xml. Most people name their ANT build.xml, so there is nothing too special here. This build file includes all the targets and tasks to tell the ANT compiler what steps to take and in what order.

The second file is the properies file, labeled build.properties. This is a file full of properties to be used by the build file to run the build script. Traditionally this file is not included in your repository and unique to each computer. This makes it easier so that each computer can have their own properties without overriding other’s configurations. Also, you will notice some crazy names in this properties file, that is because you can use almost any naming syntax that you want in this file. I prefer to use a simple naming style such as name.type, for example: debug.boolean, or deploy.dir. A quick way to let people know what the property is describing. My main point is that these properties and their naming isn’t eluding to another sort of syntax and nothing that should freak you out at all.

Setting up the ANT Build Files
As mentioned previously, an ANT file is just an XML file, and an ANT file all starts with a project tag.

We will now add a bit more information to our XML. The project name (shown in outliner), the base directory (to determine relative linkage to the build file), a description (so future devs can understand what you are doing), and finally the link to the build.properties (to include the build properties). I also include a timestamp property so I can access it easier later for timestamped build files. You’ll notice that I use “.” for the baseDir, this states that the current directory level is the base directory level.

Our file now looks like…

FlexTasks
Now we need to include the FlexTasks jar to include the builder functionality provided by Adobe. To include this jar is a very simple matter, just add the taskdef.

Adding this one line allows for the use of the mxmlc and compc functions in ANT. You will also notice rather than a direct path I wrote ${FlexTasks.file}, this is an ANT variable that corresponds to a variable in the build.properties, specifically:

Targets
Now we need to define the steps that ANT will take to process our application. These steps are also called targets and our targets can be run via the outliner or your own ANT running GUI.

The main step that I am going to want ANT to accomplish is compileProject. This target has some subtasks or depends which are to clean the deploy file and compile the application. Below is my compileProject target.

Now we need to actually define the targets that compileProject depends on.

Clean and Create
The clean and create step is simple. We delete the old deploy folder and create a new one. This ensures a clean build.

Again I am referring to some ANT variables, but you can see that I am deleting and making the deploy directory. One new tag you may not know as a Flex/Flash dev is the echo tag. This just writes out a string to the console as it is being run. Basically, we are just keeping other devs aware of what is going on in case the ANT file craps out.

Compile The Application
The only task we have left is to actually build our application. For this step I am going to use the mxmlc compiler provided by Adobe via the FlexTasks.jar. Here I will load up the MXML application file, set its output, give the application a few properties, load in the Flex config file provided by Flex itself, add metadata, and finally compile in the source. The ANT code to accomplish this is shown below.

Expert Note:
One quick way to know the compiler options Flex/Flash Builder uses is to add this tag into your compiler options:

-dump-config your/drive/to/store/the/xmlfile.xml

This will output the entire ant compiler options and you can copy off the parts you want to keep.

Default Task
One last thing I like to do is to make sure to add a default target to my application. This makes it so you can select to run the ANT file and the ANT file knows which target to run by default. The change to my project tag looks as such:

The Application
In case you didn’t do it earlier, you can check out all the files I have via view source with the included Flex file.

FLEX_HOME
Make sure to include in your build file a reference titles “FLEX_HOME” and point it to a copy of the Flex SDK, this is required to build the Flex Application.

Memory Issues
If your build file keeps failing complaining about “not enough memory” there is one little change you will need to make to your JVM. Go to Run > External Tools > Open External Tools Dialog. Select your ANT File, the switch the tabs to JRE and look for VM Arguments. Make sure your options include (at least) -Xmx1024m. This allows for enough RAM to be dedicated to the VM during the build process.