Using Flex Ant tasks to build Flex projects – Part 2: Adding build tasks

In Part 1 of this article, I showed you how to create a basic Ant script that made use of Flex Ant tasks to automate your project's build process.

In this article, I'll expand on what I covered in Part 1 and add more commonly used tasks to enhance the Ant build script. The following list includes the most typical types of tasks a developer would need to automate in their build script.

• ASDoc creation
• HTML wrapper
• RSL creation
• SWC creation

Beyond just compiling a SWF file, these tasks automate more of the build process and allow other developers on your team to create new releases of your Flex project. There are many variants that can be implemented with your script, and you can remove or add these tasks at your discretion.

If you've read Part 1 of this article, you probably have Ant installed already. For this article, you'll also need to download the new sample files. After you do, start up Flex Builder 3 and create a new Flex project called flex_ant_pt2_Tasks. Point it to the flex_ant_pt2_Tasks folder you downloaded and unzipped. Figure 1 shows the Flex project directory structure.

You'll notice the same build.properties and build.xml files in the root of the application, as siblings of the "src" folder. Open the build.properties file by right clicking it and selecting Open With > Text Editor. It's the same file from Part 1, but with a few new variables.

Starting at line 15, you'll see the FLEX_FRAMEWORK, DOC_DIR, DOC_TITLE, DOC_FOOTER, and asdoc.exe variables defined in order.

FLEX_FRAMEWORK defines the location of your Flex framework files. This will be used for the RSL (run-time shared libraries) task later.

DOC_DIR is a folder that the Ant script will create when it runs. This folder will hold all the HTML files created from the ASDoc task.

The DOC_TITLE and DOC_FOOTER simply set the title and footer values for the HTML pages created by the ASDoc tool. The remaining asdoc.exe variable specifies the location of the tool on the machine running the build script.

Open the build.xml file by right clicking on it and selecting Open With > Ant Editor (assuming you installed Ant as a Flex Builder plug-in). You'll notice the script has gained a lot of weight since you last saw it in Part 1.

I'm going to dissect it piece by piece to show you what changed from the Part 1 tasks and how the new tasks work.

The first change to note is in the project node at the very top. It no longer has the default attribute pointing to the "compile flex project" task, but rather, it points to a new task named "compile flex ant tasks project", which is defined on line 9:

Its purpose is to serve as a kind of entry point to wrap all the other tasks in the script (see Figure 2). The depends attribute lists all the tasks in order, so when the script is run it'll make sure all tasks are completed. In contrast, the Part 1 build script simply deleted and recreated the DEPLOY directory, and compiled the SWF file into it. By wrapping all the tasks together here, you have that one all-encompassing target to run all the tasks, or you can run each separately if you choose.

Further down in the build.xml file, you can see the "init" task now also creates and deletes the DOC directory set by the DOC_DIR variable in the build.properties file, which will become the new home for the HTML files created by the ASDoc tool.

On line 20 in the build script is the newly added "build doc" task, which looks like this:

You can include any argument in this task that you'd normally use with the ASDoc tool at the command prompt. Here, the script points the executable attribute to the asdoc.exe variable set in the build.properties file. The failonerror attribute is set to true so if there are problems, it will be brought to your attention right away.

The -doc-sources argument points to the project's main src folder. Further down, the script makes use of the DOC_TITLE and DOC_FOOTER variables set in the build.properties file. These will set the title and the footer note on each HTML page within the created files (see Figure 3). For a full list of the supported arguments, see Running the ASDoc tool.

The "compile flex project" task is a bit bigger now. That's because it has more to do than just compile the SWF file. You'll see a few new options listed inside this task that are needed for the RSL deployment option.

The runtime-shared-library-path node tells the mxmlc compiler that you want to use RSLs, and the path-element attribute points to the installed framework.swc that comes with the Flex SDK.

The url nodes specify the location of the SWF and SWZ files to be loaded at run time via the rsl-url attribute. This script shows the bare necessities needed to use RSLs; there are many other options you can employ. There's one more step here–copying the RSLs to the DEPLOY folder–but I'll cover it later in the article since it involves a different task. For now, this is how you'd compile the Flex application and have it make use of RSLs for Flash Player caching.

See About cross-domain RSLs for other options, XML configuration file nodes, and attributes you can set in your Ant script that are passed to the mxmlc compiler.

The HTML wrapper task, starting on line 48 of build.xml, is another Flex Ant task that gives you many options. In this case the options are used in creating the files that you deploy with your Flex application.

This task is simply another target containing an html-wrapper node with some attributes you may want to set for your HTML page. The application attribute points to Main.mxml (the .mxml extension is automatically appended, so don't add it here).

The template attribute is set to use the express-installation template in conjunction with the history attribute set to true. This particular combination will also output the deep-linking files necessary for history management, but there are other combinations that are beyond the scope of this article.

The output attribute points to the DEPLOY directory, where the task will place the HTML, AC_OETags.js, and any deep linking files. Use the file attribute to specify the name of the HTML page and the swf attribute to specify the name of the output SWF file. The rest of the attributes are self-explanatory. To keep things simple in this article, I'm only listing the basic options for each task; for more details, see Using the html-wrapper task.

Starting on line 66 of the build.xml file is the "createSWC" task:

To create the SWC, the task invokes the compc compiler. For this article, the task points to a single ActionScript class: the LabelBuilder class. The include-classes attribute in this case points to the one class, but if you were to add multiple classes in the creation of your SWC, you'd provide a space-delimited list of class names.

The output attribute points to your DEPLOY directory and names the SWC file MyComps.swc. The path-element attribute of the source-path node sets the source directory of the project so the compc compiler knows where to find your ActionScript files when the task is run.

Unlike the include-classes attribute, you would not use a space-delimited list of names to include multiple assets, such as images, in your SWC. Instead you would use <include-file> nodes.

This is another very simple example; to read more on the options for this task, see Using the compc task.

Remember that earlier, I mentioned one more step regarding RSLs? This is it. The last task in the build script, shown on line 75, is named "copyRSLs". When you run the script, the "compile flex project" task will set your SWF to use the RSLs, but it won't copy them into the DEPLOY folder for you. This task performs the copy operation.

This article is about automating your build process to make things as easy as possible in a team environment. So this is another cool way to take advantage of Flex Ant tasks to do some more work for you. You'll recall from Part 1 that Flex Ant tasks extend Java Ant tasks. As a result, you have access to everything the Java Ant tasks are capable of, like creating directories, copying and moving files, deleting folders, and so on.

This last task in the build script uses the copy todir command to copy the Flex framework RSLs from their default location to the DEPLOY folder for easy deployment. Just like the "init" task, which uses delete and mkdir commands to remove and recreate the DEPLOY and DOC folders, you can have this task use file operations to make life easier for everyone on the team.

The copy node points to the DEPLOY folder with the todir attribute, and the file attribute points to the default location of the framework RSL that you're using in this script.

If you've installed the Flex Ant plug-in, simply drag the build.xml file into the Ant view and double click it within the view. This will set off all the tasks you chained together in the "compile flex ant tasks project" target in the beginning of the script. If you want to run one particular task, just double click it inside the Ant view in Flex Builder.

To run the build script with stand-alone Ant, open a command prompt, navigate to your base directory for the project (where the build.xml is located), and type:

This will ensure that developers running the script who don't have access to the flexTasks.jar file can use the one you provide them in the libs directory.

Whether you used the Ant plug-in in Flex Builder or the stand-alone version, you will see output in the console listing the commands for each task as they run, and at the bottom you should see something like:

Inside of the DEPLOY and DOC directories, you can now find all the files created by each task in the Ant script (see Figure 4).

Where to go from here

In this article you added new functionality, taking advantage of Flex Ant tasks to fully automate the build process with some of the more commonly used features in Flex projects.

There's still some creative license involved in constructing your own build script. You've seen some very simple examples in this article, but I would strongly recommend that you read through Adobe's help pages to learn more about the different options available for each task.