Now that you’ve been through 3 exhaustive tutorials on ant for flex, it’s time to use your knowledge you’ve gained to turn your back on the built-in Flex compiler and switch to ant for your builds. This part applies to FlexBuilder (and FlashBuilder) users only although it may apply if you’re using some other eclipse-based plugin. If you’re using another program like TextMate or Flash CSx, you can skip this article.

Replacing the default builder with your ant tasks

The rest of this article will show you how to use your ant build script to perform the building actions found in FlashBuilder.

In FlashBuilder, the following building actions can be executed

• Build Project – Occurs when the user manually builds the project.
• Build Automatically – When the option is checked in the Project menu, the code is automatically build when you save a file. Usually incrementally.
• Clean – ‘cleans’ the project folder by doing a complete, non-incremental build and removing temporary files.

These actions are all called by various actions and handled by one or more builders. In terms of the eclipse SDK, a builder is an XML file that describes how the various build actions will be executed. In FlashBuilder, all of these are set up to use the Flex “builder” by default. You can add new customized builders to supplement these build actions. You can also deactivate the default builder an just use your ant builds instead but you will lose the ability to see inline errors in your code.

In order for this to work however, you need to start out with some solid, well-tested ant tasks.

Step 1 – Create the appropriate ant targets

Create a target in your build.xml for each of the actions listed above. Call each target “build”, “autoBuild”, and “clean”. You can probably start with the “build” target and reuse it for the other two. To write an incremental build target (used for the build-automatically action) there is an example in Part 2 of this article.

Before moving on, please test your build script thoroughly to be sure there are no errors and that your files are compiling correctly.

Note, I’m not going to go into the details here about exactly how to write your ant script. If you’re considering switching to ant as your primary builder then A) your project has special needs that need to be addressed by a custom build script and I don’t know what those needs are and B) you need to know what you’re doing with ant before completely abandoning FlashBuilder’s defaults. I will say, save the fancy stuff for your release build targets and do incremental builds by default since you’ll be running these scripts quite a lot.

Step 2 – Create a builder for your ant build script

1. Open the properties for the project you want to edit. Project -> Properties
2. Select the Builders item in the left menu. You will see that the default builder “Flex” is already set up.
3. Click the New… button. A dialog will come up with templates for the new builder.
4. Choose the “Program” type. (On my configuration, I see an option for “Ant Builder” also which is what I should probably be using, however, I haven’t gotten it to work yet and it doesn’t seem to generate any specific errors when it fails so I gave up and went with Program. If you know how to fix this, let me know!)
5. Name the builder “flexAntBuilder”
6. Set the location field to the ant binary you’re using. If you’re not sure where the binary is located, you can use the command which ant in the command line. Mine is at /usr/bin/ant
7. Set the Working directory to your project’s home directory. If you’re not sure, browse to it.
8. In the arguments field, enter the name of the target you want to run. In this case build.
9. Optional: Click on the Refresh tab. Here you can chose whether to refresh the files in your workspace when the build completes.
10. Click on the Build Options tab. Here, under the “Run the Builder:” heading near the bottom, is where you’re going to set the properties that determine when this particular task is run. For the ‘build’ target, uncheck everything except “During Manual Builds”.
    • For your “autoBuild” target, you’re going to uncheck everything except “During auto builds”
    • For your “clean” target, you’re going to uncheck everything except “After a clean”
11. Repeat steps 1-10 for the other two targets.
12. When all targets are added, optionally uncheck the “flex” builder from the builders menu in your project properties to use the ant tasks exclusively. Now your ant scripts will be used instead of the flex builder.

That’s it! Be sure to test things and make sure you’re not getting any errors.

What to expect from here

So you’ve unchained yourself from the system and are using your ant scripts to build your project. Congratulations, you’re a huge nerd! From this point on, changing the compile settings in the Project Properties dialog (like the build path) may be ineffective. You’ll need to make changes to your build path in the ant file.

The results from your builds will appear in the Console view. Here you can see the progress of builds and check for errors in the code. As I mentioned before, if you deactivate the flex builder you won’t get inline errors in your code any longer.

Finally, adding the new builders will create a new invisible folder in your project’s root folder called .externalToolBuilders where your builder definitions will be kept. You don’t need to do anything with this folder, but be aware that it’s there.

That concludes this 4 part epic post about ant tasks for flex! I hope you found it useful. If you have anything to add, please post comments!

This third installment talks about tips and tricks for using ant with version control systems.

Defining external properties for each user

Since not everyone’s machine is the same and letting everyone build a project is a major reason to use ant, it’s good to avoid hard coding paths to files within your build.xml file. As such, I use a lot of <property> tags to set up paths and such. But you also don’t want to have several people constantly editing your build.xml because it could get broken or out of sync. Oh no! What do we do!?

Luckily, ant lets you define a set of properties in an external file. This is a simple text file containing name=value pairs and commented using #. By default, the recommended filename is build.properties. Here’s an example:

build.properties and version control

If you’re working with multiple people, you are probably using a version control system like svn. If you are and you want to avoid people accidentally checking in a build.properties file there are a couple of simple tricks. First, create a copy of build.properties and call it built.properties.template and check that into the repository. Then each user can make a local copy called build.properties. You can also add build.properties to the ignore list for your folder using SVN so that noone will accidentally check it in. Run svn pe svn:ignore and add build.properties to the list. Finally, if you need to make sure that your users have a local copy of build.properties, there’s a task for that!â„¢

Adding SVN tasks

As I work with SVN quite a lot, I found that including SVN in my builds can be quite useful. For example you could:

• Update your working copy when doing a clean build.
• Check in a release build automatically.
• Export your source code without those pesky .svn files to be included in a zip file.
• Include the revision number of the working copy as a constant definition in the code using conditional compiliation.

To do this, you’ll need to first download the SVN tasks for ant. They can be found on the Tigris.org website. Please note, that these tasks are a part of SubClipse, which is a free interface for working with Subversion from within Eclipse. I don’t know if the tasks will work without subclispe, but if you haven’t used it, I’d definitely recommend trying it out anyway. By the way, if you use CVS, there are already tasks included in ant. Once they’re downloaded, add the task .jars to the libs/ant folder in your project. You’ll need to use another <typedef> tag in your build script to get these to work. Here’s an example snippet that simply runs an update on the working copy. You can see all the available commands in the svnant documentation.

That’s it for part 3. In Part 4, I’ll talk about setting up a builder for your ant file in FlashBuilder.

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.

After spending hours wrangling with my ant build script and finally making everything work correctly, I am convinced of two things:

1. ant is a very powerful tool for compiling code but it can also do so much more.
2. The support for ant for flex online is abysmally frustrating.

So, I’d love to share with you some of the tips I’ve picked up after tweaking my script to the point where it finally worked!

Introducing ant

First of all, let me introduce the basics of what ant is. I couldn’t really say it better than the thousands of nameless editors of WikiPedia.

Apache Ant is a software tool for automating software build processes. It is similar to Make but is implemented using the Java language, requires the Java platform, and is best suited to building Java projects.

The most immediately noticeable difference between Ant and Make is that Ant uses XML to describe the build process and its dependencies, whereas Make has its Makefile format. By default the XML file is named build.xml.

Ant is an Apache project. It is open source software, and is released under the Apache Software License.

So in short, ant lets you use an XML based script to run a series of commands typically used to build software projects. It was originally designed to be “for Java, in Java” but it’s popularity and ease of use has created interest beyond the Java community. For flex, ant can be used for compiling ActionScript and Flex projects into SWFs, creating SWC files, generating documentation with ASDocs, and other actions associated with compiling.

There are a lot of great tutorials online that can cover the basics of how ant works so I’m not going to go into a general overview in this article. Instead, I’m going to try to focus on some of the practical aspects of getting a build set up when working with Flex. However, here are some links to the official ant documentation some helpful tutorials for the basics:

Ant Basics tutorial

Another basics tutorial (this time for Flex)

Official Flex documentations

Ant Folklore

After the jump, I’ll get into some of the ways that ant can be useful for Flash and Flex projects.

Applications for Flex users

Is ant right for you? It depends. For most cases, using the standard Run and Debug functions in FlashBuilder or Flash will be completely sufficient. However, if you work on a large development team or on a project with a complicated build process, it might save the group a lot of headache. Here’s a list of situations where I think Flex ant tasks can be helpful.

• Whenever your project requires you to make adjustments to the standard build process. For example, when you need to add additional flags to your compiler string.
• For Flex projects that are distributed widely, e.g. open source projects, where the configuration of the users’ dev environment is unknown. Build scripts allow users of various versions of FlexBuilder, FDT, or Flex SDK users on different operating systems to all be able to compile a project with more or less the same settings.
• If running or building your project requires you to configure options in the command line or to run a local server.
• For building release versions of an app and for deploying your app. For example, compiling, zipping and copying an app to a server using FTP.
• When you’re a total nerd and you want to use ant just so you can say you did it.

Beyond Compiling

One of the main benefits of using ant is that I think many people are unaware of is that it can be used for many things beyond running compilers. For example, in KitchenSync, I use a build script to create a temp folder, compile a SWC file into the temp folder, create an SVN export of the source folder into the temp folder, zip the source and SWC and name it with the current version number, then delete the temp folder.

There are loads of core tasks that are already defined within the ant library. They handle all types of common actions in the command line. There are even additional optional tasks that add higher-level functionality like copying files to a server using SSH or validating an XML file. Finally, additional tasks can be added simply by creating a new Java class that is a subclass of org.apache.tools.ant.Task. You probably won’t do this yourself, but there are a number of third-party programs that have created ‘plug-in’ tasks for ant such as SVN.

Once Flex projects became larger and more complex, many users began to look for more customizable options and began using ant. A couple of years back, Adobe released some official ant tasks which can now be found bundled in every version of the Flex SDK. However, as I said before the documentation of exactly how to get these tasks running is vague at best.

In part 2, I’ll talk about the details of getting flex ant tasks running.

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