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

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

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!