mostly a codeBlog

(Warning: lengthy and boring… and subsequently extremely useful)

I have been in the process of building an Ant script for the main project/customer at work.
It is an Air project that consists of 9 applications, each in their own project space. They get compiled into modules, they have
their own external assets and so forth. When we need to update/release these applications all the swf’s and assets are moved to a final package, which
essentially is a MainApp.swf that loads in these 9 applications at runtime.

Because we needed a way to test and develop the individual modules, without relying on the Main.swf, or any other modules to be present, each project had
a dummy Main, so checking out SubApp0 from SVN and running DummyMain.mxml inside it would result in the SubApp0.swf module being loaded. Modules can’t run by themselves.

There are two deployment cases, one where the customer needs an entire new MainApp.air file installed and a case where we only need an individual module recompiled and sent
to the customers installation. e.g. SubApp1 has been updated and the SubApp1.swf module file is to be moved into the MainApps application directory, so that MainApp can load it. (This is done via a completely different system that tests for files on our server with newer timestamps and moves the files out to the customers clients).

It was becoming a bit of a burden keeping track of 9 modules/projects and their assets, so 6 months back I wrote an applescript that moved the assets and the modules
into the main application, where I could ask Flex Builder to package them into an Air bundle. This however does not help my Windows colleagues, do any testing on the bundle or keep any track on versioning.
So now it is time to get out the magnifying glass and burn some Ant. I don’t know how many parts this will be (2-4) but I am hoping on getting it up and running with both automatic Unit testing, automatic retrieval of latest code from SVN and some sort of reporting system(mail, ftp, red blinking lights on my phone?)… oh yeah and the dreaded asdoc.

I’ll be referring to the two cases mentioned above as the “deploy case”" i.e. only compile and collect, and the “release case” i.e. compile, collect, version and package as an Air bundle.

The first part is how to set up Gumbo/Flash Builder 4 (Flex builder/Eclipse has the same procedure) for Ant tasks, the structure of these tasks, the different files and lastly a small example that compiles three swf’s and their SWC’s using a macro and finally move these to a directory called “deploy”.

The second part will then look at a conceptually similar case as the one I described in the introduction, MainApp, SubApp0 and SubApp1 are all to be compiled, have their assets moved and everything bundled into an Air package.

I will see how far I get over the next couple of weeks, if I get SVN and Unit testing up and running I will post that as well.

On with it!

Prerequisite

Your Eclipse/Gumbo/Flash Builder/Flex Builder, from now on just called “Eclipse”, will need the the “Java Development Tools” installed. This can be found under “help” ->”Software updates” -> “Find and install”. The “Java Development Tools” should be on the list.

An Ant build script consists of, at least, a build.xml file. The build file holds a set of instructions wrapped in targets, it is in essences an xml file with
commands and parameters to be run by the ant.jar “engine”.

For us to use Ant to compile flash files, Adobe must deliver command line tools we can point Ant at so it can compile and manipulate the raw classes, i.e. .as and .mxlm files. Luckily Adobe has made these for us:

• mxmlc.jar is the mxml compiler.
• adt.jar is the air debug tool
• adl is the air debug launcher (adl.exe on Windows)
• asdoc is the actionscript documenter (asdoc.exe on Windows)

There is some information on these command line tools at Adobes livedocs and the tools themselves you already have if you have an Flex/Flash Builder installation.
They reside in the “sdks” folder, which is located somewhere like ../users/applications/Adobe Flash Builder/sdks/4.0.0/
If you don’t have anything named like this anywhere, you maybe running Eclipse and haven’t installed the Flex builder plugin yet, this can be done from the Adobe downloads section.

Once we are ready we are going to start a new Air project called MainApp, so go into Eclipse, “File” -> “New Flex Project” -> make sure it is set to be an Air project and click “Finish”.
Right click on the project in the navigator view (package view in Gumbo) select new and click “folder”, name the folder “build-files”, right click that new “build-files” folder and select new and click “file”, name the file “build.xml”. We are almost ready now.

We are going to copy the “mxmlc.jar” and “flexTasks.jar” file into our project. This is done so the project sdk version always fit the current project, it is also done
to avoid referencing long different paths on e.g. Mac, Linux and Windows. The “adt.jar” and “adl” files are not copied as these rely on other tools located in the
sdk and moving these will make them behave irregular.
So before we move on find these files, on Mac, in:

/Applications/Adobe\ Flash\ Builder\ Beta/sdks/4.0.0/ant/lib/flexTasks.jar
/Applications/Adobe\ Flash\ Builder\ Beta/sdks/4.0.0/lib/mxmlc.jar

And copy them into the project we made in the “libs” folder.

Now we are ready and your project should look something like this

Let’s try out Ant

Open the “build.xml” file and type in these instructions:

Notice the path property “MAIN” this should of course be changed to fit the path on your system. Select “Window” -> “Other views” -> “Ant” in Eclipse to open the Ant view. Drag the “build.xml” onto this window, if it is not already there, right click on the “clean” target and select “Run As” -> “Ant Build”. Now you should see that Ant has made a “deploy” folder in your “MainApp” project root. Ok things to notice here: the “target” node holds the tasks we want to carry out, the “property” is a way to set an alias that will be used instead of a long path. In the amount of blog posts and manual I have been through the last couple of days it seems there are two conventions when typing these out. One is “ALL_CAPS” and the other is “source.dir”. I like using the ALL_CAPS, like constants in programming, for the paths.
You can type them as you like, no problem. Notice that in the target, we reference a property name using ${MAIN}, we will utilize this a lot more, not just to make smaller build scripts, but also to make it possible to have this script running on other developers computers, who probably don’t have folders and sdks in the same location. Now right click the “build-files” folder and select “New” -> “File” name the file “build.properties” this file will hold all the aliases that we deem necessary.

	project.name=MainApp
	author=Ricki Gregersen
	project.version=0.1.0

	#System depend paths
	FLEX_ROOT=/Users/rickigregersen/Documents/Programming/FlashBuilder
	FLEX_HOME=/Applications/Adobe Flash Builder Beta/sdks/4.0.0
	AIR_HOME = /Applications/Adobe Flash Builder Beta/sdks/4.0.0/frameworks/libs/air

Now change the “build.xml” file to look like this:

Notice the “build.properties” is included as a property file. So why not just put the ${MAIN} alias into the “build.properties” as well? We surely could, but the ${MAIN} alias is only valid for this particular “build.xml” and not a general path. So we leave it in here for a developer to see. The goal is for a developer to pull down this project from, say, subversion, edit the three aliases in the “build.properties” and then be able to build everything of the bat. But we are not really doing anything interesting yet, Ant can make directories, delete directories, move files, replaces files and so on. Lets compile our MainApp. This time I made quite a few add-ons to the script, but I’ll explain them all:

Ok this just got interesting, a few new aliases turned up, we covered how to do that already. A new target was included, yes this it how it goes.
You can just add as many targets as you need inside the project node, notice that this new target “compile” also turned up in the Ant window in eclipse.
You can now click either “clean” or “compile” and have that target run. The “compile” target has a new attribute called “depends”. This means exactly what it says: this task depends on the clean task being successfully run before it starts! This is great, we can now determine what tasks should run and in what order. Selecting “compile” in the Ant window and running it will make “clean” execute and when it is done, “compile” will run.
This new compile target has an tag. If you have ever used a terminal, this is the xml equivalent. The “grep” command in Unix has this description
grep [options] PATTERN [FILE...] which means, type grep -any_options a_string in_a_file.txt, so when you give the terminal this command it understands how to search for the “a_string” in the “in_a_file.txt” with “-any_options” in mind. This is the same thing, the mxmlc.jar file is executed, with the attributes as parameters. This makes sense, it needs to know the location of the MAIN_APP_MXML file, which holds our code, it needs to know where to put it and the “debug” and “optimize” parameters are the options. You should now have a “MainApp.swf” in your “deploy” folder.
I have included some code in the mxmlc tag, this is to show how external SWC files can be compiled into the swf. When the mxmlc runs the MainApp.mxml will raise a flag saying that a swc is needed, if you have a swc included in the library path og MainApp of course, this takes care of that.

Now it makes sense to have the “clean” target as we would like to ensure that only freshly compiled code ends up in the “deploy” folder.
The last thing we will look at in this walk-through is to write a macro to bundle functionality together, compile and move two additional mxml files into the deploy folder.

A macro is a way of having Ant carry out a number of tasks in sequence. Before we get into to macroes, make two new projects called “SubApp0″ and “SubApp1″, just like we made the “MainApp” project, like in the picture above. These projects will have nothing in their “libs” folder, they will not have “deploy” folder or any of the functionality/assets we added to the “MainApp”. I also made 2 new Library Projects called “AntSwc0″ and “AntSwc1″, I then right clicked “MainApp”, “SubApp0″ and “SubApp1″ and selected “Properties” -> “Flex Build Path” -> “Library Path” and include the “AntSwc0″ and “AntSwc1″. This is just to show this functionality, if you have no need for swcs, just omit compiler.library-path tag from the macro.

This is how the “build.xml” looks like now:

The macro takes the parameters you specify, here it is “source” and “target”, notice that in the tag, these properties are
accessed using @ instead of $, this is so the macro can distinguish between global aliases and local aliases. Everything you put between
the will be run by the macro.

I added a last target called “run_all”, you can see it is empty but the clever thing is that it depends on “clean” and “compile” to run before it will
execute, so this essentially runs all.