Compiling and Debugging: Chapter 21 - Flex 3 Cookbook

by Joshua Noble and Todd Anderson

This excerpt is from Flex 3 Cookbook. This highly practical book contains more than 300 proven recipes for developing interactive Rich Internet Applications and Web 2.0 sites. You'll find everything from Flex basics and working with menus and controls, to methods for compiling, deploying, and configuring Flex applications. Each recipe features a discussion of how and why it works, and many of them offer sample code that you can put to use immediately.

buy button

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)

Example
Figure 21-1: Viewing output with Xray

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>

Note that both actual command-line calls to the compilers use a configuration.xml file containing information about the location of the runtime shared libraries that will be passed to mxmlc:

<flex-config>
  <compiler>
    <external-library-path>
      <path-element>example.swc</path-element>
    </external-library-path>
  </compiler>
  <file-specs>
    <path-element>RSLClientTest.mxml</path-element>
  </file-specs>
  <runtime-shared-libraries>
    <url>example.swf</url>
  </runtime-shared-libraries>
</flex-config>

In place of adding the external-library-path flag to the command-line invocation of mxmlc as shown here

mxmlc -external-library-path=example.swc

the configuration.xml file is passed as the load-config flag in the call to the compiler, and each option is read from the XML file.

A similar file can be passed to compc:

<flex-config>
  <compiler>
    <source-path>
      <path-element>.</path-element>
    </source-path>
  </compiler>
  <output>example.swc</output>
  <include-classes>
    <class>oreilly.cookbook.shared.*</class>
  </include-classes>
</flex-config>

The complete Ant file for this recipe is shown here:

<?xml version="1.0"?>
<project name="useRSL" basedir="./">

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

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

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

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

</project>

Section 21.6: Create and Monitor Expressions in Flex Builder Debugging

Problem

You want to track the changes to a value in your Flex application as the application executes.

Solution

Use the Flex Builder Debugger to run your application and set a breakpoint where the variable that you would like to inspect is within scope. In the Expressions window of the Flex Builder Debugger, create a new expression.

Discussion

The use of expressions is a powerful debugging tool that lets you see the value of any variable within scope. Any object within the scope where the breakpoint is set can be evaluated by creating an expression, as shown in Figure 21-2.

Example
Figure 21-2: Creating an expression

For example, if you place a breakpoint at the line where the array is instantiated, marked here with breakpoint here

<mx:Canvas xmlns:mx="http://www.adobe.com/2006/mxml" width="400" height="300" 
creationComplete="init()">
    <mx:Script>
        <![CDATA[
            import mx.collections.ArrayCollection;

            private var arr:ArrayCollection;

            private function init():void {
                arr = new ArrayCollection([1, 2, 3, 4, 5]);//breakpoint here
            }

            private function newFunc():void {
                var newArr:ArrayCollection = new ArrayCollection([3, 4, 5, 6]);
            }

        ]]>
    </mx:Script>
</mx:Canvas>

the expression arr will evaluate to null. When you advance the application by pressing the F6 key, the expression will evaluate to an ArrayCollection wrapping an Array of five integers (Figure 21-3).

Example
Figure 21-3: The expression showing the variable evaluated

The expression newArr evaluates to null, however, because the variable newArr will not be in scope (Figure 21-4).

Example
Figure 21-4: Only variables in scope can be evaluated.

If you instead place a breakpoint at line 17, the expressions newArr and arr both evaluate to ArrayCollections, because both variables will be in the current scope

Section 21.7: Install the Ant View in the Stand-Alone Version of Flex Builder

Contributed by Ryan Taylor

Problem

You can’t find the Ant view in the stand-alone version of Flex Builder.

Solution

Install the Eclipse Java Development Tools.

Discussion

To access Ant in Flex Builder’s stand-alone version, you must install the Eclipse Java Development Tools. To do so:

  1. In the Flex Builder menu bar, choose Help → Software Updates → Find and Install.
  2. Select the Search for New Features to Install option and then click Next.
  3. Choose The Eclipse Project Updates in the dialog box and then click Finish.
  4. A menu appears, asking you to select a location from which to download the files. Select any location, preferably one that is geographically near you for faster download times, and then click OK.
  5. Browse the various SDK versions in the Eclipse Project Updates tree until you find Eclipse Java Development Tools. Select the check box next to it and then click Next.
  6. After the Update Manager finishes downloading the necessary files, you will be prompted with a feature verification dialog box. Click Install All.
  7. After installation is completed, restart Flex Builder.

You can now find the Ant view in Flex Builder by browsing to Window → Other Views → Ant

Section 21.8: Create an Ant Build File for Automating Common Tasks

Contributed by Ryan Taylor

Problem

You want to leverage the capabilities of Ant to help automate common tasks such as compiling and generating documentation.

Solution

Create an Ant build file in which tasks can be added for automating your processes.

Discussion

Creating an Ant build file is easy and the first step toward using Ant to automate common tasks. Simply create a new XML document named build.xml and save it in a directory named build in the root of your project directory. Saving the file in this directory is not mandatory, but a common convention.

The root node in your build file should look something like this:

<project name="MyAntTasks" basedir="..">
</project>

You will want to set the name attribute to something unique for your project. This is the name that will show up inside the Ant view in Eclipse. For the basedir attribute, make sure it is set to the root of your project directory. You will use the basedir property frequently when defining other properties that point toward files and directories inside your project folder.

Next, you will likely want to create some additional properties for use throughout the various tasks that you may add later. For instance, to create a property that points toward your project’s source folder, you could do something like this:

<project name="MyAntTasks" basedir="..">
    <property name="src" value="${basedir}/src" />
</project>

The preceding example also demonstrates how to use a property after it has been defined, with the syntax ${property}.

If you find that you are defining a lot of properties and you would like to keep your build file as clean as possible, you can declare properties in a separate file instead. To do this, create a new text file named build.properties and save it in the same directory as your build.xml file. Inside this file, declaring properties is as simple as this:

src="${basedir}/src"

That’s all there is to it. Some examples of useful properties to define are paths to your source folder(s), your bin folder, and the Flex 3 SDK directory. You’ll catch on pretty quickly to what you need. From here, you are ready to start adding tasks to your build file.

See Also

Recipe 21.3

Section 21.9: Compile a Flex Application by Using mxmlc and Ant

Contributed by Ryan Taylor

Problem

You want to add tasks to your Ant build file for compiling your application.

Solution

Add executable tasks to your Ant build file that use the MXML compiler to compile your files.

Discussion

Compiling targets are by far the most common and useful types of targets you will add to your Ant build files. Flex applications are compiled by using mxmlc, which is the free command-line compiler included with the Flex 3 SDK. By adding targets for compiling to your build file, you can automate the build process: Ant will compile all your files without you ever having to open up the command prompt or terminal.

The MXML compiler (mxmlc) included in multiple formats. You can use the executable version of it by creating a target similar to this:

<!-- COMPILE MAIN -->
<target name="compileMain" description="Compiles the main application files.">
    <echo>Compiling '${bin.dir}/main.swf'...</echo>
    <exec executable="${FLEX_HOME}/bin/mxmlc.exe" spawn="false">
        <arg line="-source-path '${src.dir}'" />
        <arg line="-library-path '${FLEX_HOME}/frameworks'" />
        <arg line="'${src.dir}/main.mxml'" />
        <arg line="-output '${bin.dir}/main.swf'" />
    </exec>
</target>

Pages: 1, 2

Next Pagearrow