Working with compiler options

The compc and mxmlc compilers share a very similar set of options. As a result, the behavior of the mxmlc and compc Ant tasks are similar as well.

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 to specify 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 options have aliases (alternative shorter names). The Flex Ant tasks support all documented aliases for these options.

Single argument options

Many compiler options must specify the value of one or more parameters. For example, the load-config option takes a parameter named filename.

To specify the option in an Ant task, you add a child tag with that option as the tag name. You set the values of the arguments by including an attribute in the tag whose name is the option name and whose value is the value of the argument.

The following example sets the values of the load-config and source-path options, which have arguments named filename and path-element respectively:

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

The source-path option can take more than one path-element parameter. For more information, see Repeatable options.

You can see which options take parameters by looking at the mxmlc command-line syntax. In the Flex bin directory, enter the following command:

mxmlc -help list advanced

The output includes all options for the mxmlc compiler. The syntax for the load-config option appears like the following:

-load-config <filename>

This indicates that the load-config option takes a single argument called filename.

Multiple argument options

Some compiler options, such as the default-size option, take more than one argument. The default-size option takes a height and a width argument. You set the values of options that take multiple arguments 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 command-line compiler’s 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 compiler options are repeatable. The online help shows their arguments in square brackets, followed by a bracketed ellipses, like this:

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

You set the value of repeatable options by using multiple nested elements 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 one exception: the compiler.fonts.languages.language-range option 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 specific 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 filename 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 the Flex compilers 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, the value of the append attribute is false in implicit FileSets.

The following example sets the value of the append attribute 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, as in the following example:

<external-library-path/>

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