boostworthyisryantaylor

FDT 3 is almost here - fans of FDT 1.5 know how awesome that is. I've been fortunate enough to be involved in the private beta, so I have had my hands on it for some time now. I must say, I like it better than version 1.5 for sure (and not just because it supports AS3 now). I'll save the review for another time though; this long post is all about Ant support in Eclipse and how you can use it to compile your AS3 projects. Though I am using FDT 3 for this tutorial, if you aren't in the private beta group you can still follow along using Flex Builder. If you are using the standalone version, you will need to use the 'Software Updates > Find and Install' tool to get 'Eclipse Java Development Tools' downloaded and installed so that you can use the Ant panel which I speak of throughout this article.

Moving along, you will need to download a copy of the Flex 3 SDK to your machine. It contains everything you will need to compile, test, and document your various AS3 projects. Also, the examples below are for Windows users, however the same rules apply for Mac users, you will simply need to change some file extensions and so forth.

Setting Up Eclipse

If the Ant panel is not already open, you can find it here:

Window > Show View > Ant

This is what you should see if it is open:

With the Ant panel open, it is time to create a build file.

Constructing An Ant Build File

First off, you will need to create a 'build.xml' file which Ant will use to automate your build. At it's simplest form, it should look something like this:

Breaking down the project node attributes, 'name' is the name that will appear in the Ant panel of Eclipse. The 'default' attribute is a reference to the target in which Ant will run by default, say if you double-click the build file in the Ant panel for instance. Finally, there is the 'basedir' attribute which basically tells Ant what directory the property 'basedir' should represent. If you are going to store your build file(s) in a directory other than the root directory of your project, then you will want to change that path to reflect this. For instance, if you created a directory called 'build' and stored your build file(s) in there, you would want to make your basedir point towards '../' and so forth.

Before moving on - now that you have a 'build.xml' file in the works, you can go ahead and add it to the Ant panel. The simplest way to do this is by dragging the build file from the Flash Explorer panel down into the Ant panel. Upon dropping the file it should become listed in the panel. As tasks get added they will show up listed under that particular file like so:

Double-clicking the tasks is how you will run them.

Ok, so now that we have a foundation for our build file, we need to add some properties so that we can easily reference commonly used paths and whatnot. You can define properties directly inside the 'build.xml' file or create a separate 'build.properties' file to store them externally from the build file itself. Below are demonstrations of both practices. Also note that once you define a property, you call upon it using the following notation: ${propertyname}.

Defining properties inside the build file:

Defining properties inside a separate build properties file (name it 'build.properties' and save it in the same directory as the build file(s):

As shown above, build.properties files are very simple and easy to create. The advantage to using one is basically the same as using a config XML file in a Flash project to prevent needing to make changes directly in Flash (but in this case the build file).

Ok, so now on to the good stuff. Let's create a simple task to compile our 'main.swf' file.

Each target needs to have a unique name which represents that task. Using an 'exec' node, you can specify an executable to call. In our case, we pass it the property we created which points to the mxmlc compiler. Last but not least we have an 'arg' node which is used to pass arguments to the executable just like we would in the command-line. Note that you can create a separate 'arg' node for each argument if you wish. I prefer keeping everything on one line to prevent the document from being super long, however it can make things a little less readable if that is a concern.

You will want to create a task like this one for each SWF you need to compile. I usually just copy and paste one to a new line, give it a new name, and change the SWF file name and document class. As your application grows, you will likely want to create a 'compileAll' task for compiling each SWF instead of having to run each task on it's own. Fortunately, there is a very nice way we can reuse all of our existing tasks. Here is an example of how you could run three different tasks with ease:

The 'depends' attribute is very handy. It simply states that Ant must do each task listed prior to running that task. In this case, we just simply list out each compile task we would like it to run, then never specify any actions to be taken for the 'compileAll' task itself.

Ok, so now that we have SWF files compiling, how can we launch our app to see it in action? Again, we will need to create a new task.

Very similar to the task we created for compiling, however this time we are launching Flash Player and passing the SWF file we would like to open as an argument. The 'spawn' attribute of the 'exec' node is set to 'false' by default (meaning if you do not list it), however I wanted to show it here because flipping it to 'true' will disable trace outputs in the console which may be desirable.

So far so good. Currently, to build and test our app we must first run the task 'compileAll' then 'launch'. This is ok, but we could easily reduce this to one step.

Again, using the beautiful 'depends' attribute, we simply specify to run the task 'compileAll' followed by 'launch'.

At this point, Ant is saving us a ton of time. We can easily compile each SWF file individually or all of them at once. We can also launch the app to see it in action and choose to receive trace outputs in the console. One additional task that I always use is a task for generating documentation. If you have been using JavaDoc commenting throughout your code, you can use the Adobe ASDoc tool that is supplied with the Flex 3 SDK.

This task simply goes into the specified source directory and outputs html documentation. You can specify the title that appears on the top of the documents as well. The 'delete' node at the beginning simply clears the docs directory prior to generating the new documentation.

Before moving on to the next section, I also wanted to mention that you can just as easily use these same techniques to compile, test, and deploy AIR applications. You will need to create some additional properties that point towards the necessary directories and command-line tools. Some sample AIR properties:

Instead of mxmlc and Flash Player, you will want to compile and test your app using 'adl'. When it comes time to package your application as an AIR file, something like this will suffice using 'adt':

That pretty much covers most of the basics for compiling your AS3 with Ant. Now let's move on to some lesser-known things you can do (in the Flash world at least).

Advanced Ant

Ant can do more than just compile and launch your projects. You can even use it to handle SVN requests, FTP files to a server, and package your applications for hand-off to a client. One of my favorites is that last one - packaging up your goods for a client hand-off. What I like to do is create an empty directory, copy only certain file types and directories into it, then zip it up so I can email it or whatever.

By using 'fileset' nodes, a collection of directories/files can be specified and filters can be put in place using 'include' and 'exclude' nodes. In the example above, I am copying all files over except for the FDT project files and SVN databases.

Another cool thing that you can do is check to ensure that certain properties have been set prior to running a task to prevent unwanted bad happenings.

Now, thanks to the 'depends' attribute, 'checkForASDoc' will be called prior to the 'generateDocs' task taking action. If the 'asdoc' property has not been set, the specified message will be output to the console.

We can go one step further and create actual conditionals as well. Let's say we created a property named 'createdocs' and we wanted to be able to set it to 'true' or 'false'; the intent being to create docs or not create docs based on the value that is set.

It's a little weird how it reads, but essentially you create a 'condition' node and it's child nodes specify the comparisons. In this case, we use an 'equals' node to compare 'arg1' to 'arg2'. If the statement is true, the specified local property 'docstarget' is set to the value specified by the 'value' attribute in the 'condition' node.

Final Word

This post could go on forever discussing the cool stuff you can do with Ant, but I think you get the idea. Complete documentation for Ant and it's many tasks can be found here.

On a final note, if you run into any problems while running mxmlc, specifically ones complaining about 'jvm.dll', you most likely have JRE 6+ installed. Uninstall it and grab JRE 5 from the archive located on the Java site. Hopefully Adobe will address this in the months to come.

If any of you have additional tasks that you find especially useful that I didn't cover in this post, feel free to post away in the comments.