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!

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