Using Flex Ant Tasks to build Flex projects – Part 1: Creating a build script for Flex

When working in a team environment with other developers, it's important, and considered a best practice, to standardize the build process of your application. Most large-scale, enterprise projects use source control and automated tools to enable the team to work on the same code and keep track of numerous software revisions, while still producing repeatable builds. Many Java developers use Ant build scripts to automate the process of building new releases.

Things can get hectic when new releases of your Flex application are required with new builds of an enterprise project. Whose job is it to hand over the actual SWF file for a release? What about future builds? You, as a Flex developer, might be excited to know that you can use Adobe Flex Ant Tasks to build your projects using Ant.

With Flex Ant Tasks, you can create a script that makes your project's build process quick, painless, and repeatable. On top of that, if your team includes Java developers and Flex developers the Java developers can invoke your build script as part of their own build to get the latest version of your SWF file. Because the build no longer depends solely on one developer deploying the SWF file from Flex Builder, it provides the rest of the team with more flexibility in deploying the application.

In this article, I'll show you how to create a basic build script for a typical Flex project. For more information on Java Ant tasks, see the links in the Where to go from here section at the end of this article.

Ant (Another Neat Tool) is a scripting tool for creating an automated build processes for your project. Originally, it was created for Java projects. It uses an XML-based syntax to list targets and dependencies in a script file, which is invoked from a command prompt.

A target can be considered a "task". Examples of a task would be compiling the Flex application, creating or deleting a directory, or even invoking the ASDoc tool to create documentation for your project. You can link tasks together in a chain by making them dependant on other tasks running first. An example would be making a task to create a directory, and then creating another one to compile the Flex application to generate the SWF file in that directory.

Here's a brief list of some of the tasks you could add to your script to automate the build process:

• Compile Flex applications, modules, and component libraries
• Create project documentation with ASDoc
• Create an HTML wrapper for your project's output SWF file

Flex Ant tasks include the mxmlc and compc compiler tasks, which extend the Java Ant task. Because of this, you can use any of the Java Ant task's available attributes if you want to.

The first thing you'll need to do is install Ant. Here, you have two options: install Ant as a Flex Builder plug-in or install Ant as a standalone application

Installing Ant as a Flex Builder 3 plug-in

If you're using Flex Builder, you can install the Ant plug-in from the Eclipse Project Updates.

In Flex Builder, choose Help > Software Updates > Find and Install. Select "Search For New Features To Install" and click "Next". Ensure that the "Eclipse Project Updates" site is checked in the Update Sites view, and click "Finish".

Choose which mirror site to download from and click "Next". Select "Eclipse Project Updates" and search for your Eclipse SDK version. Under that entry, select "Eclipse Java Development Tools" (or JDT).

Accept the agreement, click "Next", and then "Finish". Flex Builder will download the files for the Java Development Tools. When it's finished, click "Install all".

Restart Flex Builder and choose Window > Other Views > Ant and you'll see the Ant view along with the other windows in the Flex Development perspective.

Installing Stand-alone Ant

Note: If you're not comfortable with using a command prompt to compile Flex applications, you should probably use the Ant plug-in configuration.

The alternative is to install Apache Ant and use a command prompt to compile your application. If you want to install Ant as a stand-alone tool, visit the Apache Ant Project page to download the latest release, and extract the ZIP file on your machine. At the time of this writing, the most up-to-date version of Ant is 1.7.1.

To install Ant on a PC, you might put the extracted folder in C:\apache-ant-1.7.1. On a Mac, the best location is your Applications folder. I'll refer to this folder as the Ant root or {ant_root}.

Important: You now have Ant installed, but before you can run it, you need to define some environment variables, including ANT_HOME, which should be set to the directory where you installed Ant. For more information, see Apache Ant documentation.

Once you have Ant installed and ready to run, you need access to the Adobe Flex Ant tasks. By default Ant doesn't know what Flex is, so you're going to introduce them next.

You'll need to grab a copy of the flexTasks.jar file, which contains the Flex Ant tasks created by Adobe. If you have Flex Builder 3 installed, copy the flexTasks.jar file from {flex_builder_3_install_folder}\sdks\{your_sdk_verion_number}\ant\lib, to your {ant_root}\lib directory.

If you're using the stand-alone Flex SDK, you can find the flexTasks.jar in {flex_sdk_root}\ant\lib\. Copy it from that directory to your {ant_root}\lib directory.

You're now ready to start building Ant scripts that will take advantage of the Flex Ant tasks.

In a team environment, it makes the most sense to include the flexTasks.jar with your project for those developers who wouldn't necessarily have it on their machines. When working on a large enterprise project, it's a good idea to copy the flexTasks.jar into your project's lib folder. This way, you can distribute Flex Ant tasks to developers who may not have the file, and if they wanted to, they could pass a reference to that JAR file as an argument to Ant when compiling. To keep things simple for this article, it is easier to just add the JAR file to your Ant install.

After you download and unzip the sample files for this article, start Flex Builder 3, create a new project called flex_ant_pt1_Tasks, and set the project location to the Flex Ant Tasks directory. Main.mxml is the entry point for this simple application, and it's under the src directory (see Figure 1).

When you have the project up and running, you'll see a simple application that does nothing more than create a Label component, and retrieve a string value from the com.pxldesigns.flexTasks.LabelBuilder class. Run it to see the Label in the application as shown in Figure 2.

Build a properties file

You may have noticed the build.properties and build.xml files in the project's main folder. These files are not in the "src" folder, because they are used for your Ant build script.

Start by examining the build.properties file first. Right-click the build.properties file and select either Open with > Properties File Editor or Open with > Text Editor.

Typically, this file is where you'd define properties for your project to be used by the Ant script (the build.xml file). The file itself isn't a necessity, but it makes things much easier in the long run. By storing certain path variables, document titles, and other variables in a separate properties file, you make things much easier for other developers who won't necessarily have all the tools and SDKs installed in the same location on their machines as you do.

The build.properties file from the sample files contains the following:

You'll notice a comment, starting with a "#", on the first line of the build.properties file:

The FLEX_HOME variable is needed for Flex Ant tasks, and should point to your SDK version's folder (above is the typical location on a PC). If you're on a Mac, the typical location would be:

FLEX_HOME=/Applications/Adobe Flex Builder 3/sdks/{your_sdk_version}

There are a few more variables listed in this file. They don't need to be listed there, they could have been created in the build.xm file, but again, to make things as flexible as possible, it's best to include them in the properties file.

The SRC_DIR variable points to the Flex project's src folder, and the LIBS_DIR variable points to the project's libs folder. This is pretty obvious, but you can name these variables anything you like, it makes sense to set up some path variables for the build script's reference.

There is also a DEPLOY_DIR variable, which points to a DEPLOY folder that your script will create when it's run.

Now that you've looked at the build.properties file, you see it's just a storage file that defines some paths to tools and SDKs, and it can contain some other variables like titles and footers for ASDoc creation and so on. The next part of the equation is the actual Ant build script.

By convention, you should name the properties file and build script "build.properties" and "build.xml" respectively and store them in the project's main folder so other developers know where to find them and what they are. You'll want to follow this naming convention to be on the same page with the rest of the development world.

In Flex Builder, open build.xml by right-clicking it and selecting either Open With > Ant Editor or Open with > Text Editor. The Ant Editor provides code coloring and hints if you have the Ant Plug-in.

The first thing you'll notice is it's a standard XML file. Ant parses XML files that you provide in order to run all the tasks you assign. Here's what it looks like up close.

The first line has a project element and the name attribute has a value of "Flex Ant Tasks Build Script". You can give it any name you like. The default attribute simply points to the default target node defined later on in the file. In this case it's set to a target named "compile flex project". You'll recall that targets are just separated tasks.

The next line of code defines a property element. It's simply an import of the build.properties file.

The next element is a taskdef with an attribute called resource that points to flexTasks.tasks. The classpath attribute points to your {basedir}/libs/flexTasks.jar file. This is the JAR file provided by Adobe that contains the Flex Ant tasks. For this article, you copied it into the project's libs directory.

If you're going to distribute your project, include the JAR file to ensure that other team members can build your project. If they don't have the flexTasks.jar installed along with their copy of Ant, they would need to pass a reference to this file using Ant's –lib option from the command prompt when invoking your script. I'll cover that later in this article.

At this point, Ant knows where to find Adobe's Flex Ant tasks for Flex projects, so you're ready to start creating actual tasks for your script to perform.

Adding tasks to your script

The next two nodes in the build script (build.xml) are target nodes named "init", and "compile flex project" (see Figure 3). The depends attribute of the "compile flex project" target is set to init". Setting the project element's default attribute to the "compile flex project" target made this (build the Flex application) the main task for the build script to handle. The depends attribute to this target node tells Ant "don't bother running me until you run the task I depend on first".

So taking a look at the target named "init", you'll see there are two simple elements nested inside. The delete and mkdir nodes simply tell Ant to delete the DEPLOY folder if it exists in the base directory, and recreate it with the mkdir command. This is good practice to make sure the environment is clean and ready to go.

Since the "compile flex project" target depends on the "init" target, "init" will run first. You have chained together the two targets to run in sequence.

The mxmlc node within the "compile flex project" target node is part of the Adobe Flex Ant tasks project. It tells Ant to send these commands to the mxmlc application compiler to actually build your project when you run the script. The file attribute points to Main.mxml, which is the project's entry point, and the output attribute uses the DEPLOY_DIR variable together with the name you want your SWF file to have (Main.swf in this case).

The commands are the same as what you'd use with the mxmlc compiler from the command prompt, and they pass the values you enter into your XML file. Much of the following may be familiar to you; it's just written a bit differently because of Ant's syntax.

The remaining three nodes inside the mxmlc node load the flex-config.xml file, set and point to the Flex framework, and disable the debug output for the resulting SWF file. Since this is a simple build script, there are not many options for now. You can, however, add many others just as you would if you were using the mxmlc command prompt and passing arguments to the compiler. In part two of this article, I'll go over more options to expand and enhance the build script. The task at hand, however, is getting up-to-speed with a basic build script.

Now that you understand the basic structure for an Ant build script that uses the Flex Ant tasks, let's see it in action.

There are several ways to execute an Ant build script. If you're using Flex Builder 3 with the Ant plug-in, you can simply drag and drop the build.xml file into the Ant view. First, ensure that you have the view open by choosing Window > Other Views > Ant. Drag the build.xml file into the view, and then double-click the Ant icon next to "Flex Ant Tasks Build Script" (the title you set earlier).

Alternatively, you could right-click the build.xml file, and select Run As > 1 Ant Build. You can also expand the "Flex Ant Tasks Build Script" and double-click the "compile flex project [default]" task. You can run individual tasks in your script if you're using Flex Builder, as shown in Figure 4.

If you're using Ant to compile your script, you can start up a command prompt, navigate to your flex_ant_pt1_Tasks folder that contains the build.xml file, type "ant", and then press "Enter". Developers using Ant who don't have access to the flexTasks.jar would invoke Ant from the command line with the –lib argument like so:

If all goes well, you should see something similar to the following output in your command prompt window or in the console view in Flex Builder:

The script also created a DEPLOY directory in your project's main folder, and inside you'll find the Main.swf file. If you received an error, you'll need to verify that all your paths are correct in the build.properties file.

The importance of automating your build and deploy process while working on an enterprise project should be more apparent now. The key factors for build scripts are to keep the process:

• Clean and simple
• Repeatable
• Easy for current and future members of your team to use

With Flex Ant tasks you'll be able to incorporate this build process on any of your projects. By keeping paths and other variables in the properties file, and limiting the build script to the most basic functions needed for your build, you're establishing a clean, easy process for all developers on your team to use when they need to deploy a SWF file from your code.

Where to go from here

In this article, I covered the set-up, creation, and execution of a very basic Ant build script using the Adobe Flex Ant tasks. In Part 2 of the series, I'll incorporate some more common tasks such as creating ASDocs and HTML wrappers, using and deploying RSLs, and more.

You can use the following links and resources to learn more about Ant and Flex.

• Download Ant from Apache.org
• Apache Ant Documentation and Installation
• Adobe's Help Resource Center