Ant, Apparat and FlashDevelop: a total beginner’s guide
Posted by Kerry Turner on March 8, 2011
Filed under: How to
Tags: ant, ant tasks, apparat, as3, flashdevelop, flex, joa ebert, reducer
Before we start, a quick heads up: I’m new to both Ant and Apparat. If you know a better way of doing anything that I talk about here, please let me know! I should probably also clarify that this guide is for Windows users only, and that these steps apply only to projects that are compiled using the Flex SDK rather than the Flash IDE.
So, I was using FlashDevelop to compile my AS3 project, and then running the published swf through Apparat’s Reducer to reduce its file size. I wanted to automate that process so that compiling and reducing could be done as one action. Turns out you can do it all from within FlashDevelop. Let me show you how.
This guide is in two parts. The first is a guide to downloading and installing Apparat itself. If you’ve already got Apparat working, skip straight to part two where I explain how to get started with Ant and how to set up an Ant task to compile a swf and then run Reducer on it.
Part 1: getting started with Joa Ebert’s Apparat
1. First things first, you’ll need to download the following files (version numbers are specified where important for compatibility – please note them).
Install 7zip using the provided installer, and extract Scala and Apparat and put them somewhere useful/memorable. I created a folder called C:\Tools and put them in there. I renamed the Apparat folder to APPARAT_HOME and the Scala folder to SCALA_HOME, but this is personal preference.
2. Now you need to add/edit a couple of environment variables.
First, add the root folders of Apparat and 7Zip and the bin folder of Scala to your PATH variable.
To do this, go to Control panel > (Windows 7 and Vista users only: System and Security) > System > Advanced system settings.
Under “System variables”, select the variable called Path and choose “Edit”. Now append the existing line of text with a semicolon and the location of Apparat (in my case, C:/Tools/APPARAT_HOME). Repeat for 7Zip (in my case, C:\Program Files (x86)\7-Zip). For Scala, append the existing text with a semicolon and the location of the bin folder within the Scala folder (in my case, C:/Tools/SCALA_HOME/bin).
Next, under “System variables”, choose “New” and create a variable with the name SCALA_HOME and the value of the root folder for Scala (in my case, C:/Tools/SCALA_HOME).
3. OK! You should now be able to run Apparat from the command line. To test this, open the command line and type “apparat” (without the quotation marks). If you get a response that begins with “Welcome to the Apparat!”, you’re good.
There’s an awful lot more to Apparat then I’m going to cover in this tutorial – I’d seriously recommend starting by digging around the documentation and Joa’s blog to get an idea of what it’s capable of. But for the purposes of this example, we’re just going to look at one very simple example of using Reducer.
4. Do a quick test on any swf you’ve got lying around. Open the command prompt and type the following into the command line: “reducer -i [your file path, e.g. C:/TestProject/bin/testswf.swf] -q 0.7” (without quotation marks, case sensitive and making sure there is one space between each part of the command).
This will run Reducer on the specified swf, setting all pngs within it to 70% quality. As you didn’t specify an output swf, this will replace the input swf with the reduced version.
Part 2: let’s Ant!
1. OK, Apparat’s great fun and all, but the command line is a pain. So let’s download Ant. You’ll also need at least version 1.4 of the Java Development Kit. It’s vital that it’s a 32 bit version, as the Flex compiler doesn’t get on with the 64 bit version (you’ll get an “Error loading: [path to Java]\jre\bin\server\jvm.dll” when you try to build).
2. Install the JDK, and ensure that the environment variable JAVA_HOME points to the root of where it’s installed (in my case, C:\Program Files (x86)\Java\jdk1.6.0_24). If this variable doesn’t exist, or points to the wrong place (most likely the JRE instead of the JDK), you’ll get an “unable to locate tools.jar” error when you run Ant. You may find that you need to restart your machine at this point.
3. Put Ant somewhere – in my case, good old C:/Tools. Please note that the plugin I’ll be linking to in a bit will not work if the path to Ant contains spaces. Add the bin folder to your PATH variable, and create an environment variable called ANT_HOME that points to its root folder.
You can test if you’ve done this successfully by opening a command prompt and typing “ant” (without quotation marks). If you get an error message that starts with “Buildfile: build.xml does not exist!”, you’ve set it up correctly.
4. So, we want to tell Ant to compile a swf using the Flex SDK and then run it through Reducer, like we did with the sample swf earlier. To do this, we need to create an Ant script – a script that tells it which Ant tasks to execute, and in what order.
An Ant script consists of an XML file called build.xml and, optionally, a config file called build.properties. I’m not going to go into any great detail about Ant scripts, other than to say that it’s easy to find tutorials on them. Instead, I’ll just point you towards a build folder I made earlier, containing both of these files:
Unzip it and drop it into your project folder (the folder that contains your bin and src folders and your FlashDevelop project file).
Open build.properties in a text editor and add the full paths to your Flex SDK, Scala root folder and Apparat root folder (in my case, C:\Tools\FLEX_SDKS\4.1, C:/Tools/SCALA_HOME and C:/Tools/APPARAT_HOME).
Open build.xml and replace the value of the property file.swf – currently “test.swf” – with the name of the swf your project builds. If required, replace the value of file.main – currently “Main.as” – with the path to your main class, e.g. “com.reallyfancy.Main.as”.
5. You’re on the home stretch! Now we just need to get our Ant tasks running from within FlashDevelop. I use this plugin, created by FlashDevelop forum user Canab:
Download and unzip it, and drop the .dll file into your FlashDevelop/Plugins folder.
Now when you open FlashDevelop, the Ant window will be immediately visible – and also available in the View menu. In the Ant window, select “Add” and then point to your build.xml file. You’ll see that you have the option to run individual tasks or – as we’re going to do – just run the default task which, in this case, will call all the others in the appropriate order.
So, here goes: select the project name “compile-and-reduce” and click “Run”. Ta da!
Part 3: seriously, don’t stop here
There’s a lot more – a LOT more – you can do with the things I’ve mentioned here. Ant, Apparat and FlashDevelop can save you ridiculous amounts of time and energy if you learn how to use them properly. But don’t take my word for it! Start playing around, and automate yourself out of a job in no time at all.
A great place to start is this very helpful post by Ryan Taylor on compiling Flex projects with Ant – you’ll find all the syntax you need for setting swf dimensions, compile options, etc.
March 8th, 2011 at 10:32 pm
This is pretty awesome! There were a few hiccups I came across, but were easily remedied. For instance, if you don’t keep your Main.as in the root of your source, but rather have a different namespace, then you need to update the following line of the build.xml file:
Also, I added a property and replaced all references to ${dir.bin}/YOURSWFNAME.swf with ${dir.swf}:
Other than that, smooth as butter! Thanks!
March 9th, 2011 at 12:14 am
Thanks so much for taking the time to go through it and give me feedback. Both excellent suggestions, too! I’ve updated the build.xml so they’re both properties, and amended that step in the tutorial.
April 14th, 2011 at 9:28 am
Love the tutorial; it’s been useful to get apparat up and running at the very least.
I’m 2 days out debugging why the very last step is failing for me. Seems Ant is choking on the command line when running on Windows XP.
Currently have a thread going on the FD forums:
http://www.flashdevelop.org/community/viewtopic.php?f=13&t=8162
If you (or another reader) has any thoughts; would love to figure out how to make this last step work.
Cheers.
April 15th, 2011 at 1:48 am
(Just a quick note to say that Tronster managed to resolve his problem – and I’ve slightly tweaked the tutorial as a result, to make sure that bit’s as clear as it can be.)