Ant and PrimalScript, Part I

Jun 16 2005 Published by under Flash

One great thing that my excursion into Eclipse gave me was experience with Ant. I wanted to see if I could bring it back home to PrimalScript with me. And I was successful! So here is an Ant Primer (from a relative Ant newbie).

What is this Ant of which you speak?

Ant is basically a java program that reads an xml file and does stuff that the xml file says to do. Simple. The xml has to be formatted in a particular way of course. There are a lot of built in commands you can use in Ant, all kinds of things like creating and moving and deleting directories and files, zipping and unzipping things, on and on. You can also use it to run just about any executable file on your computer, along with parameters.

Ant is mainly used to compile programs, usually in Java.

How is this different than, say, the batch files that you were using before?

Not a whole lot different in the long run. Different format. More structured, better output, 21st century technology. 🙂

How do I get started?

Oh, before we even talk about Ant, I’m assuming you have MTASC installed. If not, that’s your first step.

As far as running Ant, first of all you need Ant. If you are using Eclipse, Ant is built in. If you are using PrimalScript, you need to install it.

And before that, you need to make sure you have Java installed. If not, or you’re not sure, go to java.sun.com and look for the JRE (Java Runtime Environment) for your platform. Most likely you want the SE version – Standard Edition. It should be around 15 megs. You can get the JDK if you want, which is the Java Development Kit, but that’s more than you need if you’re not writing Java programs.

OK. Once you have Java up, go to ant.apache.org and download Ant. You want the binary, not the source. Should be like a 9 meg zip file.

Unzip it in c:\ . You probably want to change the directory it makes from “apache-ant-1.65.0” or whatever to “ant”.

Now you gotta set some paths and environmental variables. Right click on My Computer, choose Properties, go to the Advanced tab and click on Environmental Variables. You have two sections there. In the top one click the New button. For variable name type “ANT_HOME” (no quotes). For variable value, input the directory that you just installed Ant into, i.e. “c:\ant”. Again, no quotes, but you know that by now. Also, loose the trailing backslash. Not “c:\ant\”. That hung me up for about 20 minutes.

Now, in the bottom section, scroll down to the item that says “Path”. Click on it and click the Edit button. In the variable value field, you’re going to see a long string of directory paths, each separated by a semicolon. Add another semicolon to the end of this, and then the path to the bin folder in your Ant folder, like so: “blah\blah\blah;c:\ant\bin”

Click OK until all the dialogs go away. Chances are you now need to restart your computer for the paths to take effect. If you know some way to make them take effect without a restart, please tell me.

To test it out, open up a command line and simply type “ant”. (If you’re still typing the quotes, you deserve all the aggravation you get.) It might tell you that it can’t find tools.jar. I’m pretty sure that’s not a problem. I think that comes in if you have the JDK installed. Again, if you know more about this, maybe how to get rid of the warning anyway, let me know.

It’s also going to tell you that it can’t find a build.xml file. That’s cool too. You didn’t make one yet. If it gives you any other errors, you’re on your own. Figure it out and come back when you do.

OK, now let’s use Ant.

Fire up PrimalScript and mke a new project. Add a class file, say “MyClass.as” Doesn’t have to be anything fancy, just a class definition and a constructor. Throw a public static main function in there that makes a new instance of the class. Like this:

class MyClass {

	public function MyClass()
	{
	}

	public static function main():Void
	{
		var mc:MyClass = new MyClass();
	}
}

Cool. Now we have a class ready to compile with MTASC. Let’s make an Ant xml file to do it for us. The usual name for an Ant file is “build.xml”. So create a new xml file with that name in the root directory of your project. Put this xml into it:

<project default="compile" basedir=".">
	<description>simple build file for flash projects</description>

	<!-- project specific properties -->
	<property name="targetswf" value="MyClass.swf"/>
	<property name="mainclass" value="MyClass.as"/>

	<!-- classpath info -->
	<property name="classpath1" value="C:\Documents and Settings\your_user_name\Local Settings\Application Data\Macromedia\Flash MX 2004\en\Configuration\Classes"/>

	<!-- tool info -->
	<property name="mtasc" location="C:/mtasc/mtasc.exe"/>
	<property name="flashplayer" value="C:\Program Files\Macromedia\Flash MX 2004\Players\SAFlashPlayer.exe"/>

	<!-- folder info -->
	<property name="source" location="."/>
	<property name="deploy" location="."/>

	<target name="compile">
		<exec executable="${mtasc}" failonerror="true">
			<arg value="-cp"/>
			<arg value="${classpath1}"/>
			<arg value="-cp"/>
			<arg value="${source}"/>
			<arg value="-swf"/>
			<arg value="${deploy}/${targetswf}"/>
			<arg value="-header"/>
			<arg value="800:600:31"/>
			<arg value="-main"/>
			<arg value="-v"/>
			<arg value="-strict"/>
			<arg value="${source}/${mainclass}"/>
		</exec>
		<exec executable="${flashplayer}" spawn="true">
			<arg value="${deploy}/${targetswf}"/>
		</exec>
	</target>
</project>

Basically, the root node is project. The default attribute points it to which target it should run. We’ll see our target in a second. Basedir we set as “.” or current directory.

We can add a description if we want.

Then we set some properties. These are just variables to be used later in the file. I set the name of my swf and main class, any class paths needed, the path to mtasc and the Flash player, and my source and deploy directories. Normally these would be separate folders, I just left them as the current directory for this simple example.

Then comes the target. You can make more than one target. I’m not sure how that all works because I’ve only used one! Anyway, since this is specified as the default above, it’s the one Ant will use.

It consists of two executables: MTASC and the Flash player. You can see how it uses the properties set earlier: ${property_name}.

Each executable can have a number of arguments, each has a value. It’s easy to see how you build out the command line for each executable. Also notice I say failonerror=”true” for MTASC. If that fails, it won’t run the Flash Player.

For the Flash player, I say spawn=”true”. That lets Ant finish up without waiting for the Flash player process to end.

OK, now you have your class, you have your Ant. Time to get it to run. Simple. In PrimalScript’s Tool menu, choose Options. Then Environment, Languages, ActionScript.

Now over there on the right under where it says Select a category, and Script Interpreter, type in “ant.bat”.

Under Initial Directory, type “$ProjectFolder$”.

Finally, click on Capture Output, to select it.

Ready to Build!

You’re done. Click OK to close the dialog, make sure your class file is open and hit F7.

If all goes well and your class is well written, you shoudl get output like this:

Buildfile: build.xml

compile:
     [exec] Classpath : C:\mtasc/std/;C:\Documents and Settings\Keith Peters\My Documents\test project/;C:\Documents and Settings\KeithPeters\Local Settings\Application Data\Macromedia\Flash MX 2004\en\Configuration\Classes/;C:\mtasc/;;/
     [exec] Parsed C:\mtasc/std/StdPresent.as
     [exec] Parsed C:\mtasc/std/Object.as
     [exec] Parsed C:\mtasc/std/Boolean.as
     [exec] Parsed C:\mtasc/std/Number.as
     [exec] Parsed C:\mtasc/std/String.as
     [exec] Parsed C:\mtasc/std/Array.as
     [exec] Parsed C:\mtasc/std/Function.as
     [exec] Parsed C:/Documents and Settings/Keith Peters/My Documents/test project/MyClass.as
     [exec] Typing MyClass.MyClass
     [exec] Typing MyClass.main
     [exec] Time spent : 0.14

BUILD SUCCESSFUL
Total time: 1 second
Exit code: 0 , 0000h

(I also still get the tools.jar warning.)

Also, if all goes well, the standalone Flash player should open up with your SWF in it. Of course for now, our SWF is empty, but should show up anyway.

Anyway, if there’s an error in your class, you’ll get something like this:

...
     [exec] Parsed C:\mtasc/std/MovieClip.as
     [exec] Parsed C:\mtasc/std/FunctionArguments.as
     [exec] C:/Documents and Settings/Keith Peters/My Documents/test project/MyClass.as:22: characters 19-23 : type error Unknown variable newt

BUILD FAILED
C:\Documents and Settings\Keith Peters\My Documents\test project\build.xml:20: exec returned: 1

Total time: 0 seconds
Exit code: 0 , 0000h

Now, if you double click on that last [exec] line that describes the error, you’ll be taken to the exact file and line where the error is. Cool, eh? Maybe next time I’ll cover putting swfmill in there, although you can probably figure that out on your own by now.

4 responses so far. Comments will be closed after post is one year old.

  • Sam Robbins says:

    Works like a charm! I like the fact that you can set up 3 different types of builds via the options, environment, langs menu. So you can make a setting for just flash with a jfsl and one for ant like in your tutorial. 😀

  • Ben says:

    Very nice tutorial Keith. Two questions though, one technical and one concerning your particular process. First, how do I capture the output of my trace() statements? Should I have the ant settings for all 3 dropdowns? (Debugger, interpretor, and compile/syntax check)

    The question about your process is how do you handle attaching symbols since you arent using the Flash IDE?

    Thanks again,
    Ben

  • Keith Peters says:

    1. http://www.bit-101.com/blog/archives/000119.html
    2. You can use the three different panels for three different things if you want. Like Sam said, have one use JSFL to compile the document in the Flash IDE, one for your Ant compile, and one for whatever else.
    3. Check out osflash.org

  • Ben says:

    OK I give up, which project on osflash.org are you referring to? I’ve read through a lot of the as2lib stuff, but the classes he mentions for importing assets doesn’t seem to be in the documentation and I can’t get his example files to work.

    Are you continuing to use the ‘publish the current .fla’ from PrimalScript method or have you gotten it to the point of not having to have Flash open via Ant?