Using FlashBuilder and Ant to Build SWCs with ASDoc Comments (on Windows 7)

It’s always an adventure when you try to use Ant to include your ASDoc comments into an Adobe Flex SWC library. I am completely baffled that Adobe can’t make this an automated step in Flash Builder, because it typically takes a alot of time to make things work correctly the “manual” way. So, I’m adding this blog post to the many already out there in hopes that my work can also help someone else.

I started off with a script that used to work on my old 32-bit laptop, but my new laptop is 64-bit. I kept getting Java Heap errors and I tried everything under the sun including changing FlashBuilder.ini and jvm.config to bump up the max heap size (-Xmx1024m). Nothing would work. What finally fixed this was adding the following line in my compc and asdoc sections of my build.xml file. If I made my settings any larger Flash Builder would throw an error. At some point I want to know why that is:

<jvmarg value="-Xmx1024m"/>

Here’s a few other tips-n-tricks:

  1. A lot of the blog posts I read were written for Mac’s…which I don’t have, so all the directory slashes were going the wrong direction.
  2. You need to install the Ant tools into FlashBuilder first. To do that go to Help > Install New Software and use this link: http://download.eclipse.org/releases/galileo
  3. When that loads its packages, look under Programming Languages for the option called Eclipse Development Tools and install that.
  4. Create a new Flex Library Project and drop in the actionscript class you want to convert.
  5. Create a file called build.xml and place it in the root directory of your project.
  6. Right click on the build.xml file and choose Run As > Ant Build.
  7. If you have errors, use echo statements to try and find out what’s going on.
  8. You absolutely must have a <taskdef> reference that points to flexTasks.jar.
  9. I also needed to include another class library into the build. You can see how I did that under the asdoc section using this pattern:
<compiler.source-path path-element="${basedir}\src"/>
<arg value="-external-library-path=${basedir}\bin\agslib-2.2-2010-12-08.swc"/>

References:

Adobe – Use the ASDoc Tool
Gaurev’s Blog – Creating Swc Files with ASDoc Comments


<?xml version="1.0"?>
<project name="mapsaverlib-1.0" default="main" basedir=".">

	<property name="FLEX_HOME" value="C:\Program Files (x86)\Adobe\Adobe Flash Builder 4\sdks\4.0.0"/>
	<taskdef resource="flexTasks.tasks"
		classpath="C:\Program Files (x86)\Adobe\Adobe Flash Builder 4\sdks\4.0.0\ant\lib\flexTasks.jar" />

	<echo message="Flex Home ${FLEX_HOME} "/>

	<!--<target name="main" depends="clean, compile, doc" description="Clean build of <filename>.swc">-->
	<target name="main" depends="compile, doc" description="Clean build of mapserverlib-1.0.swc" />

	<echo message="clean"/>

	<target name="clean" depends="clean-temp-docs">
		<delete failonerror="false">
			<fileset dir="${basedir}\bin">
				<include name="${ant.project.name}.swc"/>
			</fileset>
		</delete>
	</target>

	<target name="compile" depends="" description="Compile SWC">

		<echo message="Compiling ${ant.project.name}.swc"/>

		<compc fork="true" output="${basedir}\bin\${ant.project.name}.swc">
		    <source-path path-element="${basedir}\src"/>
		    <include-sources dir="${basedir}\src" includes="**\*.as **\*.mxml"/>
			<compiler.include-libraries dir="${basedir}\bin\" append="true">
				<include name="agslib-2.2-2010-12-08.swc" />
			</compiler.include-libraries>
			<jvmarg value="-Xmx1024m"/>
		</compc>

	</target>

	<target name="doc" depends="clean-temp-docs, compile"
		description="Updates SWC with ASDoc XML">
		<echo message="Compiling ASDoc for ${ant.project.name}.swc"/>

		<!-- Call asdoc to generate dita xml files -->
		<asdoc output="${basedir}\tempDoc" lenient="true"
			failonerror="true" keep-xml="true" skip-xsl="true" fork="true">
		    <compiler.source-path path-element="${basedir}\src"/>
			<arg value="-external-library-path=${basedir}\bin\agslib-2.2-2010-12-08.swc"/>
			<doc-sources path-element="${basedir}\src"/>
			<jvmarg value="-Xmx1024m"/>
		</asdoc>

		<!-- updates swc with asdoc xml -->
		<zip destfile="${basedir}\bin\${ant.project.name}.swc" update="true">
		    <zipfileset dir="${basedir}\tempDoc\tempdita" prefix="docs">
			    <include name="*.*"/>
				<exclude name="ASDoc_Config.xml"/>
				<exclude name="overviews.xml"/>
		    </zipfileset>
		</zip>
	</target>

	<target name="clean-temp-docs">
		<delete dir="${basedir}\tempDoc" failonerror="false" includeEmptyDirs="true"/>
	</target>

</project>