Flex Ant Tasks

From Adobe Labs

What's New

2/26/2007: An updated version of the Flex Ant tasks ZIP file is now available. It fixes the following issues:

When the compc or mxmlc tasks fail, Ant now throws a build error.
Some minor problems with the included build.xml file have been fixed.

Overview

The Flex Ant tasks provide a convenient way to build your Flex projects using an industry-standard build management tool.

If you are already using Ant projects to build Flex applications, then you can use the Flex Ant tasks to replace your exec or java commands that invoke the mxmlc and compc command-line compilers.

If you are not yet using Ant to build your Flex applications, you can take advantage of these custom tasks to quickly and easily set up complex build processes for your Flex applications. For more information on using Ant, see the Ant project web site.

The Flex Ant tasks feature includes two compiler tasks, mxmlc and compc. You can use these to compile Flex applications, modules, and component libraries. In addition, the Flex Ant tasks include the html-wrapper task that lets you generate custom HTML wrappers and the supporting files for those wrappers.

Installation

Installing the Flex Ant tasks is a simple process. You copy a single JAR file from the downloaded ZIP file to a target directory.

To install Flex Ant tasks:

1. Download the Flex Ant tasks ZIP file and view the license agreement.

Note: Your use of this site including software downloads, submission of comments, ideas, feature requests and techniques on this and other Adobe maintained forums, as well as Adobe’s rights to use such materials, is governed by the Terms of Use.

2. Extract the flexTasks.jar file from the ZIP file to a temporary directory.

3. Copy the flexTasks.jar file to Ant's lib directory ({ant_root}/lib). If you do not copy this file to the lib directory, you must specify it by using Ant's -lib option on the command line when you make a project.

Note that the ZIP file also includes the source code for the Flex Ant tasks.

Using Flex Ant tasks

You can use the Flex Ant tasks in your existing projects or create new Ant projects that use them.

There are three new tasks you can use in your Ant projects:

mxmlc — Invokes the application command-line compiler. You use this compiler to compile Flex applications, modules, and CSS SWF files.
compc — Invokes the component command-line compiler. You use this compiler to compile SWC files and RSLs.
html-wrapper — Generates the HTML wrapper and supporting files for your Flex application. By using this task, you can select the type of wrapper (with and without history management, with and without express install, and with and without player detection), as well as specify application settings such as the height, width, and background color.

To use the custom Flex Ant tasks in your Ant projects, you must add the flexTasks.jar file to your project's lib directory, and then point to that JAR file in the taskdef task. In addition, for most projects you set the value of the FLEX_HOME variable so that Ant can find your flex-config.xml file.

Note: From the previous paragraph onward a complete walkthrough is needed for those with no prior Eclipse / Ant experience

For example,

How to add the flexTasks.jar file to your project's lib directory
How to add a new taskdef task to your project
How to point to that JAR file in the taskdef task

To use the Flex tasks in Ant:

1. Add a new taskdef task to your project. In this task, specify the "flexTasks.tasks" file as the resource, and point to the flexTasks.jar file for the classpath. For example:

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

2. Define the FLEX_HOME and APP_ROOT properties. Use these properties to point to your Flex SDK's root directory and application's root directory. While not required, creating properties for these directories is a common practice because you will probably use them several times in your Ant tasks. For example:

 <property name="FLEX_HOME" value="C:/flex/sdk"/>
 <property name="APP_ROOT" value="myApps"/>

3. Write a target that uses the Flex Ant tasks. The following example defines the main target which uses the mxmlc task to compile the Main.mxml file:

  
 <target name="main">
     <mxmlc file="${APP_ROOT}/Main.mxml" keep-generated-actionscript="true">
         <load-config filename="${FLEX_HOME}/frameworks/flex-config.xml"/>
         <source-path path-element="${FLEX_HOME}/frameworks"/>
     </mxmlc>
 </target>

The following shows the complete example:

 <?xml version="1.0" encoding="utf-8"?>
 <!-- mySimpleBuild.xml -->
 <project name="My App Builder" basedir=".">
     <taskdef resource="flexTasks.tasks" classpath="${basedir}/flexTasks/lib/flexTasks.jar" />          
     <property name="FLEX_HOME" value="C:/flex/sdk"/>
     <property name="APP_ROOT" value="myApp"/>  
     <target name="main">
         <mxmlc file="${APP_ROOT}/Main.mxml" keep-generated-actionscript="true">
             <load-config filename="${FLEX_HOME}/frameworks/flex-config.xml"/>
             <source-path path-element="${FLEX_HOME}/frameworks"/>
         </mxmlc>
     </target>  
 </project>

This example shows how to use different types of options for the mxmlc task. You can specify the value of the keep-generated-actionscript option as an attribute of the mxmlc task's tag because it does not take any child tags. To specify the values of the load-config and source-path options, you create child tags of the mxmlc task's tag. Using options is discussed in the #Working with compiler options section.

4. Execute the Ant project; for example:

> ant -buildfile mySimpleBuild.xml main

If you did not copy the flexTasks.jar file to Ant's lib directory as described in #Installation, then you must include the JAR file by using Ant's -lib option. For example:

 > ant -lib c:/ant/lib/flexTasks.jar -buildfile mySimpleBuild.xml main

The output of these commands should be similar to the following:

 Buildfile: mySimpleBuild.xml  
 main:
    [mxmlc] Loading configuration file C:\flex\sdk\frameworks\flex-config.xml
    [mxmlc] C:\myfiles\flex2\ant_tests\apps\Main.swf (150035 bytes)
 BUILD SUCCESSFUL
 Total time: 10 seconds
 >

Working with compiler options

The compc and mxmlc command-line compilers share a very similar set of options. As a result, the behavior of the mxmlc and compc Ant tasks are similar as well. The discussion of compiler options in this section applies to both the mxmlc and compc Flex tasks.

You can specify options for the mxmlc and compc Flex tasks in a number of ways:

Task attributes
Single argument options
Multiple argument options
Nested elements
Implicit FileSets

Task attributes

The simplest method of specifying options for the Flex Ant tasks is by specifying the name and value of command-line options as a task attribute. In the following example, the file and keep-generated-actionscript options are specified as attributes of the mxmlc task:

 <mxmlc file="${APP_ROOT}/Main.mxml" keep-generated-actionscript="true">

Many mxmlc and compc command-line options have aliases (alternative shorter names). The Flex Ant tasks support all documented aliases for these options.

Single argument options

Many command-line compiler options specify the value of a single parameter by turning a Boolean on or off or specifying a single String parameter. You set these types of options by including an attribute in the task element whose name is the option name and whose value is the value of the option.

The following example sets the values of the load-config and source-path options:

 <mxmlc ... >
     <load-config filename="${FLEX_HOME}/frameworks/flex-config.xml"/>
     <source-path path-element="${FLEX_HOME}/frameworks"/>
 </mxmlc>

Multiple argument options

Some command-line compiler options take more than one argument, such as the default-size option. You set this type of option by using a nested element of the same name, with the attributes of the element corresponding to the arguments of the option as shown in the online help.

For example, the online help for mxmlc shows the following syntax for the default-size option:

 -default-size <width> <height>

To pass the option -default-size 800 600 to the mxmlc task, use the following syntax:

 <mxmlc ...>
     <default-size width="800" height="600" />
 </mxmlc>

Repeatable options

Some command-line compiler options are reapeatable. The online help shows their arguments in square brackets, followed by a bracketed elipses; for example:

 -compiler.source-path [path-element] [...]

You set the value of repeatable options by using a nested element of the same name as the option, along with attributes of the same name as they appear in the online help.

The following example sets two values for the compiler.source-path option:

 <mxmlc ...>
     <compiler.source-path path-element="src"/>
     <compiler.source-path path-element="../bar/src"/>
 </mxmlc>

Nested elements

In some situations, options that are closely related are grouped together in a nested element of the main task element. For example, the command-line compiler options with the compiler.fonts and metadata prefixes can be grouped into nested elements. The compiler.fonts options use the element name fonts and the metadata options use the element name metadata.

The following example shows how to use the metadata nested element:

 <mxmlc ...>
     <metadata description="foo app">
         <contributor name="Joe" />
         <contributor name="Nick" />
     </metadata>
 </mxmlc>

In this example, you drop the metadata prefix when setting the description and contributor options as a nested element.

This is a uniformly-applied rule with a single exception being the compiler.fonts.languages.language-range option, which is set using a nested element with the name language-range, rather than languages.language-range.

Implicit FileSets

There are many examples in the Apache Ant project where tasks behave as implicit FileSets. For example, the delete task, while supporting additional attributes, supports all of the attributes (such as dir and includes) and nested elements (such as include and exclude) of a FileSet to specifiy the files to be deleted.

Some Flex Ant tasks allow nested attributes that are implicit FileSets. These nested attributes support all the attributes and nested elements of an Ant FileSet while adding additional functionality. These elements are usually used to specify repeatable arguments that take a file name as an argument.

The following example uses the implicit FileSet syntax with the include-sources nested element:

 <include-sources dir="player/avmplus/core" includes="builtin.as, Date.as, Error.as, Math.as, RegExp.as, XML.as"/>

When a nested element in a Flex Ant task is an implicit FileSet, it supports one additional attribute: append. The reason for this is that some repeatable options for compc and mxmlc have default values. When setting these options in a command line, you can append new values to the default value of the option, or replace the default value with the specified values. Setting the append value to true adds the new option to the list of existing options. Setting the append value to false replaces the existing options with the new option. By default, append is set to false in implicit FileSets.

The following example sets append to true and uses the Ant include element of an implicit FileSet to add multiple SWC files to the include-libraries option:

 <compiler.include-libraries dir="${swf.output}" append="true">
     <include name="MyComponents.swc" />
     <include name="AcmeComponents.swc" />
     <include name="DharmaComponents.swc" />
 </compiler.include-libraries>

The following options are implemented as implicit FileSets:

 compiler.external-library-path 
 compiler.include-libraries 
 compiler.library-path 
 compiler.theme 
 compiler.include-sources (compc only)

The Flex Ant task's implicit FileSets are also different from the Ant project's implicit FileSets in that they support being empty; for example:

 <external-library-path/>

This is equivalent to using external-library-path= on the command line.

Using the mxmlc task

You use the mxmlc Flex Ant task to compile application and module SWF files. This task supports most mxmlc command-line compiler options, including aliases.

For more information on using the mxmlc command-line compiler, see Using the application compiler in Building & Deploying Flex Applications.

Required attributes

The mxmlc task requires the file attribute. The file attribute specifies the MXML file to compile. This attribute does not have a command-line equivalent because it is the default option on the command line.

Unsupported options

The following mxmlc command-line compiler options are not supported by the mxmlc task:

help
version

Example

The following example mxmlc task explicitly defines the source-path and library-path options, in addition to other properties such as incremental and keep-generated-actionscript. This example also specifies an output location for the resulting SWF file.

<?xml version="1.0" encoding="utf-8"?>
<!-- myMXMLCBuild.xml -->
<project name="My App Builder" basedir=".">
    <taskdef resource="flexTasks.tasks" classpath="${basedir}/flexTasks/lib/flexTasks.jar" />        
    <property name="FLEX_HOME" value="C:/flex/sdk"/>
    <property name="APP_ROOT" value="apps"/>
    <property name="DEPLOY_DIR" value="c:/jrun4/servers/default/default-war"/>
    <target name="main">
        <mxmlc 
            file="${APP_ROOT}/Main.mxml" 
            output="${DEPLOY_DIR}/Main.swf"
            actionscript-file-encoding="UTF-8"
            keep-generated-actionscript="true"
            incremental="true"
        >
            <!-- Get default compiler options. -->
            <load-config filename="${FLEX_HOME}/frameworks/flex-config.xml"/>            
            <!-- List of path elements that form the roots of ActionScript class hierarchies. -->
            <source-path path-element="${FLEX_HOME}/frameworks"/>
            <!-- List of SWC files or directories that contain SWC files. -->
            <compiler.library-path dir="${FLEX_HOME}/frameworks" append="true">
                <include name="libs" />
                <include name="../bundles/{locale}" />
            </compiler.library-path>
            <!-- Set size of output SWF file. -->
            <default-size width="500" height="600" />
        </mxmlc>
    </target>
    <target name="clean">
        <delete dir="${APP_ROOT}/generated"/>
        <delete>
            <fileset dir="${DEPLOY_DIR}" includes="Main.swf"/>
        </delete>    
    </target>        
</project>

Note : if you want use Flex Data Services, you must specifiy the configuration file as attribute of the mxmlc tag, depending on your projet, like below :

[...]
    <mxmlc services="..../WEB-INF/flex/services-config.xml"
[...]

Using the compc task

You use the compc Flex Ant task to compile component SWC files. This task supports most compc command-line compiler options, including aliases.

For more information on using the compc command-line compiler, see Using the component compiler in Building & Deploying Flex Applications.

Required attributes

The only required attribute for the compc task is the output attribute, which specifies the name of the SWC file that the compc task creates.

Special attributes

The include-classes attribute takes a space-delimited list of class names. For example:

 <compc include-classes="custom.MyPanel custom.MyButton" ... >
  ...
 </compc>

When using the include-resource-bundles attribute, you should not specify them as a comma or space-delimited list in a single entry. Instead, add a separate nested tag for each resource bundle you want to include, as the following example shows:

 <compc output="${swf.output}/compc_rb.swc" locale="en_US">
     <include-resource-bundles string="ErrorLog"/>
     <include-resource-bundles string="LabelResource"/>
     <sp path-element="locale/{locale}" /> 
 </compc>

Unsupported options

The following compc command-line compiler options are not supported by the compc task:

help
version

Example

The following example compc task builds a new SWC file that contains two custom components and other assets. The components are added to the SWC file using the include-classes attribute. The source files for the components are in a subdirectory called components. The other assets, including four images and a CSS file, are added to the SWC file using the include-file element.

<?xml version="1.0" encoding="utf-8"?>
<project name="My Component Builder" basedir=".">
   <taskdef resource="flexTasks.tasks" classpath="${basedir}/flexTasks/lib/flexTasks.jar" />
   <property name="FLEX_HOME" value="C:/flex/sdk"/>        
   <property name="DEPLOY_DIR" value="c:/jrun4/servers/default/default-war"/>
   <property name="COMPONENT_ROOT" value="components"/>
   <target name="main">
       <compc 
           output="${DEPLOY_DIR}/MyComps.swc"
           include-classes="custom.MyButton custom.MyLabel"
       >
           <source-path path-element="${basedir}/components"/>            
           <include-file name="f1-1.jpg" path="assets/images/f1-1.jpg"/>
           <include-file name="f1-2.jpg" path="assets/images/f1-2.jpg"/>
           <include-file name="f1-3.jpg" path="assets/images/f1-3.jpg"/>
           <include-file name="f1-4.jpg" path="assets/images/f1-4.jpg"/>
           <include-file name="main.css" path="assets/css/main.css"/>            
       </compc>        
   </target>
   <target name="clean">
       <delete>
           <fileset dir="${DEPLOY_DIR}" includes="MyComps.swc"/>
       </delete>    
   </target>        
</project>

Using the html-wrapper task

The html-wrapper Flex Ant task generates files that you use to deploy your Flex applications. In its simplest form, an HTML wrapper consists of an <object> and an <embed> tag that embed the SWF file in an HTML page.

The html-wrapper task outputs an index.html and AC_OETags.js file for your Flex application. If you enable history management, then the html-wrapper task also outputs the history.swf, history.js, and history.htm files. If you enable express installation, then the html-wrapper task also outputs the playerProductInstall.swf file.

You typically deploy these files, along with your application's SWF file, to a web server. Users request the HTML wrapper, which embeds the SWF file. You can customize the output of the wrapper and its supporting files once it is generated by Ant.

For more information on the HTML wrapper, see Creating A Wrapper in Building & Deploying Flex Applications.

About the templates

There are six types of HTML wrapper templates that you can generate with the html-wrapper Flex Ant task:

Client-side detection only — Provides scripts that detect the version of the client's player and return alternate content if the client's player does not meet the minimum required version.
Client-side detection with history — Provides the same scripts as those in the client-side-detection template, but adds history management support.
Express installation — Provides scripts that support Express Install.
Express installation with history — Provides scripts that support Express Install and history management.
No player detection — Provides a basic wrapper.
No player detection with history — Provides a basic wrapper with history management support.

You determine which template is used by using a combination of the history and template attributes of the html-wrapper task.

Supported attributes

The attributes of the html-wrapper task correspond to some of the attributes and parameters of the <object> and <embed> tags in the HTML wrapper. The task also supports some attributes that specify the output location and the type of wrapper to generate.

The following table describes the supported attributes of the html-wrapper task:

Attribute	Description
`application`	The name of the SWF object in the HTML wrapper. You use this name to refer to the SWF object in JavaScript or when using the ExternalInterface API. This value should not contain any spaces or special characters. This attribute sets the value of the `<embed>` tag's `name` attribute and the `<object>` tag's `id` attribute.
`bgcolor`	Specifies the background color of the application. Use this property to override the background color setting specified in the SWF file. This property does not affect the background color of the HTML page. This attribute sets the value of the `<embed>` tag's `bgcolor` attribute and the `<object>` tag's `bgcolor` parameter. The default value is "white".
`height`	Defines the height, in pixels, of the SWF file. Flash Player makes a best guess to determine the height of the application if none is provided. This attribute sets the value of the `<embed>` tag's `height` attribute and the `<object>` tag's `height` attribute. The default value is "400".
`history`	Set to "true" to include history management capabilities in the HTML wrapper. Set to "false" to exclude history management from the wrapper. Use this attribute in combination with the `template` attribute to determine which template is used. The default value is "false".
`output`	Sets the directory that Ant writes the generated files to.
`swf`	Sets the name of the SWF file that the HTML wrapper embeds. For example, "Main". Do not include the *.swf extension; the extension is appended to the name for you. This attribute sets the value of the `<embed>` tag's `src` attribute and the `<object>` tag's `movie` parameter. This SWF file does not have to exist when you generate the HTML wrapper. It is used by the `<object>` and `<embed>` tags to point to the location of the SWF file at deployment time.
`template`	The type of template to output. The value of this attribute must be one of the following: "client-side-detection" "express-installation" "no-player-detection" Use this attribute in combination with the `history` attribute to determine which template is used. The default value is "express-installation".
`title`	Sets the value of the `<title>` tag in the head of the HTML page. The default value is "Flex Application".
`version-major`	Sets the value of the `requiredMajorVersion` global JavaScript variable in the HTML wrapper. The default value is "9". The value of this attribute only matters if you include version detection in your wrapper by setting the `template` attribute to "express-installation" or "client-side-detection".
`version-minor`	Sets the value of the `requiredMinorVersion` global JavaScript variable in the HTML wrapper. The default value is "0". The value of this attribute only matters if you include version detection in your wrapper by setting the template attribute to "express-installation" or "client-side-detection".
`version-revision`	Sets the value of the `requiredRevision` global JavaScript variable in the HTML wrapper. The default value is "0". The value of this attribute only matters if you include version detection in your wrapper by setting the `template` attribute to "express-installation" or "client-side-detection".
`width`	Defines the width, in pixels, of the SWF file. Flash Player makes a best guess to determine the width of the application if none is provided. This attribute sets the value of the `<embed>` tag's `width` attribute and the `<object>` tag's `width` attribute. The default value is "400".

Required attributes

The html-wrapper task requires the swf attribute. In addition, if you only specify the swf attribute, the default wrapper will have the following default settings:

height="400"
width="400"
template="express-installation"
bgcolor="white"
history="false"
title="Title"

Be sure to use only the filename and not the filename+extension when specifying the value of the swf attribute. The html-wrapper task appends ".swf" to the end of its value.

For example, do this:

 swf="Main"

Don't do this:

 swf="Main.swf"

Unsupported options

You cannot set all the available <object> and <embed> tag parameters using the html-wrapper task. Parameters you cannot set include quality, allowScriptAccess, classid, pluginspage, and type.

Example

The following example project includes a wrapper target that uses the html-wrapper task to generate a wrapper with history management and Player detection logic. This target also sets the height and width of the SWF file. The project also includes a clean target that deletes all the files generated by the wrapper target.

<?xml version="1.0" encoding="utf-8"?>
<!-- myWrapperBuild.xml -->
<project name="My Wrapper Builder" basedir=".">
    <taskdef resource="flexTasks.tasks" classpath="${basedir}/flexTasks/lib/flexTasks.jar" />        
    <property name="FLEX_HOME" value="C:/home/dev/depot/flex/branches/flex_201_gmc/sdk"/>
    <property name="APP_ROOT" value="apps"/>
    <target name="wrapper">
        <html-wrapper 
              title="Welcome to My Flex App"
              height="300"
              width="400"
              bgcolor="red"
              application="app"
              swf="Main"
              version-major="9"
              version-minor="0"
              version-revision="0"
              history="true"              
              template="express-installation"
              output="${APP_ROOT}"/>
    </target>
    <target name="clean">
        <delete>
            <!-- Deletes history.swf -->
            <fileset dir="${APP_ROOT}" includes="history.swf" defaultexcludes="false"/>
            <!-- Deletes playerProductInstall.swf -->
            <fileset dir="${APP_ROOT}" includes="playerProductInstall.swf" defaultexcludes="false"/>
            <!-- Deletes index.html -->
            <fileset dir="${APP_ROOT}" includes="*.html" defaultexcludes="false"/>
            <!-- Deletes history.htm -->
            <fileset dir="${APP_ROOT}" includes="*.htm" defaultexcludes="false"/>
            <!-- Deletes history.js and AC_OETags.js -->
            <fileset dir="${APP_ROOT}" includes="*.js" defaultexcludes="false"/>
        </delete>    
    </target>    
</project>

Retrieved from "http://labs.adobe.com/wiki/index.php/Flex_Ant_Tasks"

Search

Personal tools

Views

Flex Ant Tasks

From Adobe Labs

What's New

Overview

Installation

Using Flex Ant tasks

Working with compiler options

Task attributes

Single argument options

Multiple argument options

Repeatable options

Nested elements

Implicit FileSets

Using the mxmlc task

Required attributes

Unsupported options

Example

Using the compc task

Required attributes

Special attributes

Unsupported options

Example

Using the html-wrapper task

About the templates

Supported attributes

Required attributes

Unsupported options

Example