Skip to any available Digital Media Help Center chapter of Flex 3 Cookbook: Chapter 8 | Chapter 20 | Chapter 21

Chapter 21: Compiling and Debugging

Compiling Flex applications is most often done through Flex Builder or through invoking the MXML compiler (mxmlc) on the command line, but there are many other tools that let you compile an application, move files, or invoke applications. Tools such as make, Ant, or Rake, for example, enable you to simplify an entire compilation and deployment routine so that you can invoke it from a single command.

Debugging in Flex is done through the debug version of the Flash Player, which enables you to see the results of trace statements. With Flex Builder 3, you can step through code line by line and inspect the properties of variables. Flex Builder 3 also introduces a new profiling view that lets you examine memory usage and the creation and deletion of objects. Outside of Flex Builder, numerous open source tools expand your options. With Xray and Console.as for Firebug, for example, you can inspect the values of objects, or you can view the output of trace statements with FlashTracer or the Output Panel utility instead of using the Flex Builder IDE. The recipes in this chapter cover debugging with both the tools provided in Flex Builder as well as tracing values and inspecting objects by using Xray and FlashTracer.

Section 21.1: Use Trace Statements Without Flex Builder

Problem

You want to create trace statements that will assist you in debugging your application, but you do not have Flex Builder 3.

Solution

Download and use one of the many open source tracing tools available.

Discussion

Since Adobe made the Flex 3 library and compiler freely available, developers have gained more options for viewing trace statements output by the Flash Player. No longer are you limited to using the Flash IDE or Flex Builder IDE; now you can choose from several tools. For example, Xray (developed by John Grden) creates trace statement viewers within Flash. Xray allows for not only the viewing of trace statements during application execution, but also the basic inspection of objects during execution (Figure 21-1)

A third option is the FlashTrace utility (developed by Alessandro Crugnola). Installing this plug-in in the Firefox browser enables you to receive any trace statements that are executed within the application. If you like, you can also log the results of the trace to a file.

You can download Xray from http://osflash.org/xray#downloads and FlashTrace from http://www.sephiroth.it/firefox

Section 21.2: Use the Component Compiler

Problem

You want to compile a Flex component into a SWC file that can be used as a runtime shared library (RSL).

Solution

Use the Component compiler (compc) and either pass command-line arguments to the compiler or pass a configuration XML file as the load-config argument.

Discussion

To invoke the Component compiler, compc, use this syntax:

compc -source-path . -include-classes oreilly.cookbook.foo -output example.swc

Some of the most important options for the compc are as follows:

-benchmark

Indicates that the compiler should benchmark the amount of time needed to compile the SWC.

-compiler.debug

Indicates whether the generated SWC should have debugging information and functionality included with it.

-compiler.external-library-path [path-element] [...]

Indicates SWC files or directories to compile against but to omit from linking.

-compiler.include-libraries [library] [...]

Indicates libraries (SWCs) to completely include in the SWF.

-compiler.library-path [path-element] [...]

Indicates SWC files or directories that contain SWC files that should be used in compiling.

-compiler.locale [locale-element] [...]

Specifies the locale for internationalization.

-compiler.optimize

Enables postlink SWF optimization.

-compiler.services <filename>

Specifies the path to the Flex Data Services configuration file.

-compiler.theme [filename] [...]

Lists all CSS or SWC files to apply as themes within the application.

-compiler.use-resource-bundle-metadata

Determines whether resources bundles are included in the application.

-include-classes [class] [...]

Indicates all the classes that should be included in the RSL; can be repeated multiple times or have a wildcard path listed.

-include-file <name><path>

Indicates all the files that should be included in the RSL; can be repeated multiple times or have a wildcard path listed.

-include-resource-bundles [bundle] [...]

Sets whether a localization resource bundle should be included.

-load-config <filename>

Loads a file containing configuration options.

-output <filename>

Determines the name and location of the file that is generated by compc.

-runtime-shared-libraries [url] [...]

Indicates any external RSLs that should be bundled into the RSL generated by compc in this compilation.

-runtime-shared-library-path [path-element] [rsl-url] [policy-file-url] [rsl-url] [policy-file-url]

Sets the location and other information about an RSL that the application will use.

-use-network

Toggles whether the SWC is flagged for access to network resources.

Compiling many classes into a runtime shared library can result in a very long command. To simplify this, you can use either configuration files or manifest files.

As with the MXML compiler (mxmlc), you can use configuration files with compc by specifying a load-config option. Also like mxmlc, compc automatically loads a default configuration file called flex-config.xml. Unless you want to duplicate the entire contents of flex-config.xml (much of which is required), specify a configuration file in addition to the default by using the += operator:

compc -load-config+=configuration.xml

Any flags passed to the compiler can be described in XML and passed to compc in the –load-config option:

<include-sources>src/.</include-sources>

Section 21.3: Install the Flex Ant Tasks

Problem

You want to use the Flex Ant tasks included with the Flex 3 SDK.

Solution

Copy the flex_ant/lib/flexTasks.jar file to Ant’s lib directory ({ANT_root}/lib).

Discussion

To ensure that Ant always has access to all tasks included in the Flex Ant tasks library provided with the Flex 3 SDK, you must copy the tasks into the lib directory of the Ant installation. 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 XML file.

Section 21.4: Use the compc and mxmlc Tasks in the Flex Ant Tasks

Problem

You want to use the mxmlc or compc tasks that are included with the Flex Ant tasks to simplify compiling Flex applications and working with Ant.

Solution

Install the Flex Ant tasks into your Ant libraries and then use either the <mxmlc> or <compc> tags, with the compile options passed to the tags as XML arguments.

Discussion

The Flex Ant tasks greatly simplify working with Ant for compiling Flex applications by providing prebuilt common tasks for developers to use. All the options you can set for the command-line use of mxmlc or compc can be passed to the Flex Ant task. For example, after you declare the mxmlc task, you can declare the file output options as shown:

<mxmlc file="C:/Flex/projects/app/App.mxml" output="C:/Flex/projects/bin/App.swf">

Instead of needing to specify the location of mxmlc and set all the options as arguments to the executable, the mxmlc Ant task can be used, saving configuration time and making your build files far easier to read. Further options can be set as shown here:

    <!-- 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>
</mxmlc>

The <compc> task for the Flex Ant tasks works similarly; all of the options for compc are passed through to the <compc> task:

<compc output="${output}/mylib.swc" locale="en_US">

Section 21.5: Compile and Deploy Flex Applications That Use RSLs

Problem

You need to deploy a Flex application that uses one or more runtime shared libraries (RSLs).

Solution

Use the external-library-path compiler option to indicate the location of the RSL or RSLs after the application is compiled.

Discussion

When it initializes, a Flex application needs to know the location of any necessary runtime shared libraries. The external-library-path compiler option contains this information; passing it to the compiler enables the Flash Player to begin loading the bytes for the RSL right away, without needing to load a separate SWF file before instantiating components or classes.

In order to use an RSL file, you need to first create an RSL. RSLs are stored within SWC files that are then accessed by the application at runtime. The SWC RSL file is compiled by using compc, and the application SWF file is compiled by using the mxmlc compiler. In order for the application to use the RSL, a reference to the location of the RSL must be passed to mxmlc by using the runtime-shared-libraries option. In this example, Ant is used to compile both the SWC file and the application that will access it, meaning that we’ll need to use both compc and mxmlc. In the build.xml file that Ant will use, both of the compilers will need to be declared as variables:

<property name="mxmlc" value="C:\FlexSDK\bin\mxmlc.exe"/>
<property name="compc" value="C:\FlexSDK\bin\compc.exe"/>

Next, use compc to compile the RSL that the application will access and use the move task to place it in the application/rsl directory:

<target name="compileRSL">
    <exec executable="${compc}">
      <arg line="-load-config+=rsl/configuration.xml" />
    </exec>
    <mkdir dir="application/rsl" />
    <move file="example.swc" todir="application/rsl" />
    <unzip src="application/rsl/example.swc" dest="application/rsl/" />
  </target>

Then compile the application SWF by using mxmlc. Note that we’re passing an XML file called configuration.xml to the compiler by using -load-config. This file will contain all the information about how we want our application compiled, including, in this case, the location of the RSL:

<target name="compileApplication">
    <exec executable="${mxmlc}">
      <arg line="-load-config+=application/configuration.xml" />
    </exec>
  </target>

  <target name="compileAll" depends="compileRSL,compileApplication">
  </target>

Pages: 1, 2, 3, 4

Next Page