Using ant for Flex – a no B.S. guide – Part 2 of 4

• Part 1
• Part 2
• Part 3
• Part 4

In this part, I get more nitty-gritty about working with flex’s ant tasks.

Using the flex ant tasks

I spent quite a lot of time making tweaks to get my scripts to use the Flex tasks and hopefully, now you won’t have to. In the end, there’s very little benefit to using the official Flex ant tasks over using a generic <exec> task (a type of ant task that simply runs an executable file with nested <arg> tags for command line arguments) and if you’re having trouble with them, I’d recommend abandoning the flex tasks and using $lt;exec>. The main thing I had trouble with was getting the <taskdef> tag to work correctly.

For those new to ant, a <taskdef> tag is a required tag that defines a third-party ant task within the build.xml file. It associates a task name with a .jar file (compiled from the java code for the task). In the case of flex tasks, the java file is typically located within your flexbuilder sdk directory. On my mac, that’s here:

/Applications/Adobe\ Flash\ Builder\ Plug-in\ Beta\ 2/sdks/${SDK_VERSION}/ant/lib

Where ${SDK_VERSION} is your target sdk version (e.g. 4.0.0). There are a few ways to load additional tasks into your build.xml file. All of them require you to reference the .jar’s location somehow and then define a new task using <taskdef>.

1. Copy the .jar file for the task into ant’s lib directory. I don’t personally like this option because it makes it very difficult to switch between different versions of the sdk. Also, it requires all users of the script to copy the files on their local machines. (You can also add it to ~/.ant/lib to control the libraries on a user level)
2. Reference the .jar file’s location using a command line argument -lib. Even worse than the first option since it requires each user to add the library manually every time the build script is run.
3. Include the .jar’s location inside the build script. It took me a long time to figure this one out since I didn’t see it in the manual for ant, but it’s certainly my preferred method for adding tasks. It allows you to keep everything self contained within the build.xml so changing the location of the .jar is as simple as setting a property in the build script.

When using the 3rd option, you then have the question of where is the best place to put the .jar files you want to link to. There are two options that make sense to me.

1. The best place to put non-core tasks required by your build (for a Flex project) is in ${project_home}/libs/ant. This allows you to check your tasks into a repository along with your other referenced files (like .swc files).
2. Optionally, for the flex tasks you could reference the .jar file directly in the sdk folder. Use this option if the version number of the SDK doesn’t matter. If it does matter, use the first option. I use this option in my snippet below.

Linking to the official Flex ant tasks

Here’s a sample of my flex task definition along with some path definitions that point to various parts of Flex. I said this was a no B.S. guide so if you paste this snippet into your build script, you should be able to use the Flex tasks.

Using the tasks

Now we have the <typedef> in place and we can actually create a task to compile something. Again, I’m not going to go into all the details of what targets are all about or go into all the details about the flex compilers. There are plenty of other tutorials about that. Instead, I’ll show you a basic target to build an mxml file that is adequate for 95% of projects. Note: you may need to edit the properties defined in these scripts so that they point to the right paths for your project.

The toughest part about using these tasks is the seemingly arbitrary words that they expect for the attribute names of some tags (like using path-element in the <source-path> tag but dir in the <library-path> tag). Now the same but this time building a library SWC.

Making an incremental build

By default, FlexBuilder uses incremental builds when compiling your source code (except for clean builds). This is a very useful feature of the compiler because it saves time by only compiling the parts of your code that have changed since the last build. You can create an incremental build simply using ant by defining a second task that adds a flag for incremental building like so. Note that allows you to run other targets from within a target.

What about ASDocs?

Even though there are tasks for asc, compc, mxmlc, and generating HTML wrappers, they didn’t bother to include an asdoc task (actually, they did in Flex SDK 4.0.0). But that’s okay! As I hinted at earlier, you can still use the task to run this (as you can for all the other commands) and not only that, it’s way easier to set up than the official flex tasks! In fact, the only reason that I can think of to use the flex tasks is that they would automatically use the windows or mac version of the executable depending on your platform. Here’s an example for asdoc.

That concludes part 2. In Part 3, I’ll talk about working with version control systems in ant.