Flash Builder 4: Building ASDocs and SWC with Ant

This post has been updated to work with Flash Builder 4

I wanted to write a quick post because I am just exploring the ability to build ASDocs using ANT from within FB 4. Adobe Labs has a post about using Flex Ant Tasks to manage builds from Flex. With this tool you can compile Flex applications, modules, libraries, and HTML wrapper code, as well as build your documentation with ASDocs. I created a sample Flex Library project that uses the compc feature of the Flex Ant tasks to compile my library into a SWC. I also use exec command in the same build file to create the ASDocs for the project. The path names in the build file have been abstracted into properties file. This properties file can be changed to build the project on both Mac and PC.

The only problems I ran into for this project was pointing to the path of the asdocs on my Mac when compared to the paths on a PC. The asdoc (asdoc.exe on PC and just asdoc on Mac) doesn’t like spaces in the path names to the output and source directories. So if you place these values directly in the build XML file you have to use single quotes for the values, something like this:

<target name="asDocs">

		<exec executable="${FLEX_HOME}/bin/asdoc" failonerror="true">

		<arg line="-doc-sources '/Users/xmritchie/Documents/Flex Builder 3/as3xdrivelib/com'">

		<arg line="-window-title 'Xdrive AS3 Library'">

		<arg line="-output='/Users/xmritchie/Documents/Flex Builder 3/as3xdrivelib/docs'">

		<arg line="-external-library-path='/Users/xmritchie/Documents/Flex Builder 3/as3xdrivelib/libs'">

		</arg>

		<echo>docs created</echo>

	</arg>

However, if you abstract these value into a properties file you won’t have any issues with paths. The build.xml file and the properties file go into the root level of your library project. Be sure you have the flexTasks.jar file in the properly location, you can get more information here: Flex_Ant_Tasks Adobe.

Here is the code for the build.xml:

<!-- Flex Library Project ASDocs -->

<project name="ASDocsTest" default="compile" basedir=".">

	<!-- import our build properties file -->
	<property file="${basedir}/build.properties" />

	<!-- Flex Ant Tasks used to perform compc and mxml compiling more info at http://labs.adobe.com/wiki/index.php/Flex_Ant_Tasks -->
	<taskdef resource="flexTasks.tasks" classpath="${FLEX_HOME}/ant/lib/flexTasks.jar" />

	<target name="setup" description="perform an setup operations">

	<!-- Execute the ASDoc Compile wich runs 3 seperate tasks in a series -->
	<target name="compile" description="series of tasks to create docs and swc">

		<antcall target="cleanDir" description="clean the docs directory">

		<antcall target="asDocs" description="full build of asdocs">

		<antcall target="buildSWC" description="build the SWC file">

	</antcall>

	<target name="deploy" description="perform an deployment operations">

	<target name="install" description="perform an installation operations">

	<!--

	DELETE the existing output folder and files and then re-generate the output folder

	-->

	<target name="cleanDir" description="DELETE the existing output folder and files and then re-generate the output folder">

		<delete dir="${basedir}/${docsoutputfolder}" failonerror="true" includeemptydirs="true">

		<mkdir dir="${basedir}/${docsoutputfolder}">

		<!-- echo dumps output to the console window -->
		<echo>doc directory cleaned</echo>

	</mkdir>


	<!--

	Run the ASDoc executable and generate the ASDocs to the new output folder

	-->

	<target name="asDocs" description="Run the ASDoc executable and generate the ASDocs to the new output folder">

		<exec executable="${asdoc.exe}" failonerror="true">

			<arg line="-doc-sources ${domainextensions}">

			<arg value="-window-title">
			<arg value="'${title}'">

			<arg value="-output">
			<arg value="${basedir}/${docsoutputfolder}">

			<arg value="-external-library-path">
			<arg value="${basedir}/${libpath}">

		</arg>

		<echo>docs created</echo>

	</arg>

	<!--

	Compile the  SWC file library including libs folder and the path to our classes, we use compc for library, but we
	would use mxml for MXML files, check the docs for Flex Ant Tasks, http://labs.adobe.com/wiki/index.php/Flex_Ant_Tasks.

	-->

	<target name="buildSWC" description="Compile the SWC file for the Librayr Project">

		<compc output="${basedir}/${liboutputfolder}/${liboutputfile}">

			<!--
				Include the path to any external SWC files used in our document, you may have to place name of SWC (corelib.swc) at end of path
				I didn't include it because I didn't want to redistribute the corelib.swc. So file path would be file="${basedir}/${libpath}/corelib.swc"
			 -->
			<include-libraries file="${basedir}/${libpath}/">

			<source-path path-element="${basedir}/src">

			<!-- include our Class packages into the build (com folder) -->
			<include-sources dir="${basedir}/${domainextensions}" includes="*">

		</include-sources>

		<echo>SWC created</echo>

	</source-path>

</include-libraries>

Here is the code for the build.properties:

# Window and document title for the documentation
title = ActionScript 3 Library
maintitle = ActionScript 3 Library

# Class-folders you want to search for classes to be included in the docs, seperated by spaces (for example   ../src/ ../net/  )
# to include every .as and .mxml file within your project, just state   ../
domainextensions = ./src/

# The Location of deployment library on your Computer (PC/Mac) for compiled SWC file
liboutputfolder = bin
liboutputfile = as3library.swc
libpath = libs

# The Location of the output folder for your generated documents
docsoutputfolder = asdocs

# Home directory for flex sdk 3, change this to build for Mac or PC using # as comment
# FLEX_HOME = C:/Program Files/Adobe/Adobe Flash Builder 4/sdks/4.1.0
FLEX_HOME = /Applications/Adobe Flash Builder 4/sdks/4.1.0
	
# The location of your asdoc.exe, change this to build for Mac or PC using # as comment
#asdoc.exe = C:/Program Files/Adobe/Adobe Flash Builder 4/sdks/4.1.0/bin/asdoc.exe
asdoc.exe = /Applications/Adobe Flash Builder 4/sdks/4.1.0/bin/asdoc

Once you have the Ant plugin installed for Flash Builder and restart, go to Widows –> Other Views and select Ant. Drag the build.xml file to the Ant dialog window, then double-click on compile to run the script. This is how you build the docs and the SWC file. You can also use those same build and properties files in the SDK.

Here is the example file, just download the file directly from link, unzip the file, and import into your Flex builder (this has not been updated to Flash Builder 4!).

ASDocsTest.zip

Additional Resources

http://www.unitedmindset.com/jonbcampos/2010/06/22/building-an-air-application-with-ant/

http://elromdesign.com/blog/2010/07/08/flashbuilder-4-tip-install-ant-prospective-in-eclipse-version-351/

– Mister

9 Comments

  1. El rancho grande! I’ve spent hours perusing the web to find this solution. Muchas gracias, amigo!

  2. Hi, quick question you may or may not be able to shed light on.

    I’m using the properties method above and without the single quotes I get a command line error: Error: unable to open ‘/Applications/Adobe’ which is what you get from terminal if you do it that way. So I need to use single quotes it appears.

    However when I do that using Ant I get the following: Execute failed: java.io.IOException: ‘/Applications/Adobe Flex Builder 3/sdks/3.3.0/bin/asdoc’: not found

    I’m using 3.3.0 and the path to the adoc program is at /Applications/Adobe Flex Builder 3/sdks/3.3.0/bin/asdoc and I can verify that by running it in my terminal (os x leopard 10.5.8)

    So I’m stuck – any thoughts on this would be much appreciated!

    Thanks

  3. Is this section correct?
    # The location of your asdoc.exe, change this to build for Mac or PC using # as comment
    #asdoc.exe = C:/Program Files/Adobe/Flex Builder 3/sdks/3.0.0/bin/asdoc.exe
    asdoc.exe = /Applications/Adobe Flex Builder 3/sdks/3.0.0/bin/asdoc

    the asdoc is not an .exe on the Mac?

  4. I am getting below result, for the above example: can you give me suggestion why it is like this…………

    Buildfile: C:\dev\sources\eclipse\eou.06.01.03.dev.magellan.t3\flex\acdoc\build.xml

    compile:

    cleanDir:
    [delete] Deleting directory C:\dev\sources\eclipse\eou.06.01.03.dev.magellan.t3\flex\acdoc\bin\docs
    [mkdir] Created dir: C:\dev\sources\eclipse\eou.06.01.03.dev.magellan.t3\flex\acdoc\bin\docs
    [echo] doc directory cleaned

    asDocs:
    [exec] Loading configuration file C:\Program Files\Adobe\Adobe Flash Builder 4\sdks\3.5.0\frameworks\flex-config.xml
    [exec] Adobe ASDoc
    [exec] Version 3.5.0 build 12683
    [exec] Copyright (c) 2004-2007 Adobe Systems, Inc. All rights reserved.
    [exec]
    [exec] Error: ” is not a directory
    [exec]
    [exec] Use ‘asdoc -help’ for information about using the command line.

    BUILD FAILED
    C:\dev\sources\eclipse\eou.06.01.03.dev.magellan.t3\flex\acdoc\build.xml:20: The following error occurred while executing this line:
    C:\dev\sources\eclipse\eou.06.01.03.dev.magellan.t3\flex\acdoc\build.xml:56: exec returned: 1

    Total time: 0 seconds

Comments are closed.