Compiling and Debugging: Chapter 21 - Flex 3 Cookbook
Pages: 1, 2

Alternatively, you can use the Java version by writing a task such as this one:

<!-- COMPILE MAIN -->
<target name="compileMain" description="Compiles the main application files.">
    <echo>Compiling '${bin.dir}/main.swf'...</echo>
    <java jar="${FLEX_HOME}/lib/mxmlc.jar" fork="true" failonerror="true">
        <arg value="+flexlib=${FLEX_HOME}/frameworks" />
        <arg value="-file-specs='${src.dir}/main.mxml'" />
        <arg value="-output='${bin.dir}/main.swf'" />
    </java>
</target>

The final (and perhaps best) approach is to use the optional mxmlc tasks that are included with the Flex 3 SDK. Installing these is described in . To access them in your build file, first you will need to add a task definition:

<!-- TASK DEFINITIONS -->
<taskdef resource="flexTasks.tasks" classpath="${FLEX_HOME}/ant/lib/flexTasks.jar" />

By importing the optional Flex tasks, you can now compile by using an even more intuitive syntax, plus leverage error detection in a tool such as Eclipse as you write out the task. For example:

<!-- COMPILE MAIN -->
<target name="compileMain" description="Compiles the main application files.">
    <echo>Compiling '${bin.dir}/main.swf'...</echo>
    <mxmlc file="${src.dir}/main.mxml" output="${bin.dir}/main.swf">
            <source-path path-element="${src.dir}" />
    </mxmlc>
</target>

In all of these examples, the same basic rules apply. You need to define properties that point toward your project’s src and bin directories, as well as the Flex 3 SDK. All of the properties in the examples use suggested names, except for FLEX_HOME, which is a mandatory name. The FLEX_HOME property must be set to the root of the Flex 3 SDK before using the mxmlc task. If you’re using the EXE or JAR versions of mxmlc, you can use a property name other than FLEX_HOME.

The true power of compiling your project via Ant lies in the ability to chain targets together. For instance, you could create a compileAll target that calls each individual compile target one by one:

<!-- COMPILE ALL -->
<target name="compileAll" description="Compiles all application files." 
depends="compileMain, compileNavigation, compileGallery, compileLibrary">
    <echo>Finishing compile process...</echo>
</target>

All of this may seem a little intimidating at first; however, after you spend a little bit of time using Ant and configuration files, you will find that they can greatly improve your workflow. By letting a third-party tool such as Ant automate your compile process, you are no longer tied to using one particular development tool. You will easily be able to call on Ant to build your project from the development tool of your choice, that is, Flex Builder, FDT, TextMate, or FlashDevelop.

See Also

Recipe 21.3

Section 21.10: Generate Documentation by Using ASDoc and Ant

Contributed by Ryan Taylor

Problem

You want to easily generate documentation for your application.

Solution

Add an executable task to your Ant build file that uses ASDoc (included with the Flex 3 SDK) to generate the documentation for you.

Discussion

ASDoc is a free command-line utility that is included with the Flex 3 SDK. If you have ever used Adobe’s LiveDocs, you are already familiar with the style of documentation that ASDoc produces. Though opening up the command prompt or terminal and using it isn’t terribly difficult, a better solution is to add a target to your Ant build file for automating the process even further.

Before creating a target for generating your documentation, it is a good idea to create an additional target that cleans out your docs directory. When you define the docs.dir property, simply point it toward your project’s docs directory:

<!-- CLEAN DOCS -->
<target name="cleanDocs" description="Cleans out the documentation directory.">
    <echo>Cleaning '${docs.dir}'...</echo>
    <delete includeemptydirs="true">
        <fileset dir="${docs.dir}" includes="**/*" />
    </delete>
</target>

With the target for cleaning out the docs directory in place, you are ready to create the target that actually generates the documentation. Notice in the sample code that the depends attribute mandates that the cleanDocs target is executed before the instructions for generating the documentation:

<!-- GENERATE DOCUMENTATION -->
<target name="generateDocs" description="Generates application documentation using 
ASDoc." depends="cleanDocs">
    <echo>Generating documentation...</echo>
    <exec executable="${FLEX_HOME}/bin/asdoc.exe" failOnError="true">
        <arg line="-source-path ${src.dir}" />
        <arg line="-doc-sources ${src.dir}" />
        <arg line="-main-title ${docs.title}" />
        <arg line="-window-title ${docs.title}" />
        <arg line="-footer ${docs.footer}" />
        <arg line="-output ${docs.dir}" />
    </exec>
</target>

The FLEX_HOME property needs to point toward the root directory of the Flex 3 SDK on your machine. The src.dir and docs.dir properties represent your project’s src and docs directories, respectively. Last but not least are the docs.title and docs.footer properties, which set the title and footer text that appears in the documentation. A common convention for the documentation title is Your Project Reference, where Your Project is the name of the project you are working on. The footer is a good place to put a copyright and URL.

ASDoc will successfully generate documentation from your code even if you haven’t written a single comment. It is, of course, highly recommended that you thoroughly document your code by using Javadoc commenting. Not only will this produce much more in-depth documentation, but programmers unfamiliar with your code can also follow along inside the code itself

Section 21.11: Compile Flex Applications by Using Rake

Problem

You want to compile Flex applications by using Rake, the Ruby make tool.

Solution

Download and install Ruby 1.9 if you have not already, and then download and install Rake.

Discussion

Although written completely in Ruby, Rake functions very similarly to the classic make utility used by C++ and C programmers. After you’ve downloaded and installed both Ruby and Rake, you can write a simple Rake file like so:

task :default do
  DEV_ROOT = "/Users/base/flex_development"
  PUBLIC = "#{DEV_ROOT}/bin"
  FLEX_ROOT = "#{DEV_ROOT}/src"
  system "/Developer/SDKs/Flex/bin/mxmlc --show-actionscript-warnings=true --
strict=true -file-specs #{FLEX_ROOT}/App.mxml"
  system "cp #{FLEX_ROOT}/App.swf #{PUBLIC}/App.swf"
end

All tasks in Rake are similar to targets in Ant, that is, they define an action to be done. The default action is always performed, and any extra actions can be optionally called within a different task. Within the task itself, variables can be declared, and system arguments can be called, as shown here:

system "/Developer/SDKs/Flex/bin/mxmlc --show-actionscript-warnings=true --strict=true
-file-specs #{FLEX_ROOT}/App.mxml"

This is the actual call to the MXML compiler that will generate the SWF file. Because an item in the Rake task won’t be run until the previous task returns, the next line can assume that the SWF has been generated and can be copied to a new location:

system "cp #{FLEX_ROOT}/App.swf #{PUBLIC}/App.swf"

The rest of the Rake file declares variables that will be used to place files in the appropriate folders. The file can now be saved with any name and run at the command line by using the rake command. If you save the file as Rakefile, you can now run it by entering the following:

rake Rakefile

Section 21.12: Use ExpressInstall for Your Application

Problem

You want to ensure that if a user does not have the correct version of Flash Player installed to view a Flex application, the correct version can be installed.

Solution

Use the ExpressInstall option when compiling to let the SWF file redirect the user to the Adobe website where the most current version of Flash Player can be installed.

Discussion

To use the Express Install, you can set the Use Express Install option in Flex Builder, in the application options (Figure 21-5)

If you are not using Flex Builder for development, then simply set the pluginspage variable in the Object tag on the embed tag of the HTML page that the SWF file is embedded within the ExpressInstall:

pluginspage="http://www.adobe.com/go/getflashplayer"

A sample <embed> statement for a Netscape-based browser such as Firefox is shown here:

<embed src="CookbookChapter26.swf" id="CookbookChapter26" quality="high" bgcolor=
"#869ca7" name="CookbookChapter26" allowscriptaccess="sameDomain" pluginspage="http:
//www.adobe.com/go/getflashplayer" type="application/x-shockwave-flash" align="middle"
height="100%" width="100%">

Section 21.13: Use Memory Profiling with Flex Builder 3 to View Memory Snapshots

Problem

You want to view all the objects allocated in the Flash Player’s memory at runtime.

Solution

Use the Memory Profiler view in Flex Builder 3 to run your application and observe the objects being created and destroyed.

Discussion

The Flex Profiler is a new addition to Flex Builder 3 and is a powerful tool that enables you to watch an application as it allocates and clears memory and objects. It connects to your application with a local socket connection. You might have to disable antivirus software to use it, however, if your antivirus software prevents socket communication.

As the Profiler runs, it takes a snapshot of data every few milliseconds and records the state of the Flash Player at that snapshot, a process referred to as sampling. By parsing the data from sampling, the Profiler can show every operation in your application. The Profiler records the execution time of those operations, as well as the total memory usage of objects in the Flash Player at the time of the snapshot. When an application is run in the Profiler, you’ll see the Connection Established dialog box (). Here you can enable memory profiling to help identify areas of an application where memory allocation problems are occurring, as well as enable performance profiling to help improve the performance of an application.

If you turn on the Watch Live Memory Data check box, the Profiling view displays live graphs of the objects allocated in the Flash Player ()

The Profiler provides memory snapshots that can be taken at any time and provide in-depth data about the number of instances of any object and the amount of memory that they require (Figure 21-8).

Finally, you can compare any two memory snapshots from different times in the application to find loitering objects, that is, objects that were created after the first memory snapshot and exist in the second. Information about the class name, memory size, and number of instances are all included in the Loitering Objects view ()