Building ASDocs and SWC with Flex Ant Tasks (flexTasks) for both Mac and PC

I wanted to write a quick post because I am just exploring the ability to build ASDocs using ANT from within Flex Builder 3. 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 (thanks Joseph and Avani for your help).

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

<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. You need to download and install the flexTasks.jar file from Adobe into your Flex Builder 3 plugins folder. On my machine, I placed the jar file into /Applications/Adobe Flex Builder 3/plugins/org.apache.ant_1.7.0.v200706080842. I also placed the flexTasks.jar file into /Applications/Adobe Flex Builder 3/sdks/3.0.0/ant/lib. Grab the files from http://labs.adobe.com/wiki/index.php/Flex_Ant_Tasks.

Here is the code for the build.xml:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101

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


<property file="./build.properties">


<taskdef resource="flexTasks.tasks" classpath="${basedir}/flexTasks/lib/flexTasks.jar">

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


<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">



<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>doc directory cleaned</echo>

</mkdir>



<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>



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

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


<include-libraries file="${basedir}/${libpath}/">

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


<include-sources dir="${basedir}/${domainextensions}" includes="*">

</include-sources>

<echo>SWC created</echo>

</source-path>

</include-libraries>

Here is the code for the build.properties:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

# Window and document title for the documentation
title = ASDocs Test Library

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

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

# The Location of the output folder for your generated documents
docsoutputfolder = bin/docs

# Home directory for flex sdk 3, change this to build for Mac or PC using # as comment
# FLEX_HOME = C:/Program Files/Adobe/Flex Builder 3/sdks/3.0.0
FLEX_HOME = /Applications/Adobe Flex Builder 3/sdks/3.0.0

# 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

Once you have the Ant plugin installed for Flex Builder 3 and you 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.

ASDocsTest.zip

- Mister