AS3 | Flex | Tools | Tutorial

Curious about Adobe Open Source? Get started with the Flex SDK on Mac OS X

How about creating a SWF that runs in the Adobe Flash Player without building it in the Flash or Flex Builder authoring environment, using tools that are free and open source? Ever since Adobe made the move from ActionScript 2.0 to 3.0 there has been a gem of a toolkit available that allows precisely that. The Flex SDK (Software Development Kit) allows developers to create SWFs from ActionScript and MXML source code, and with the right setup is not difficult to configure and use.

Housed at Adobe Open Source, the Flex SDK is available in two incarnations through the site:

  • The Open Source Flex SDK containing everything needed to create a functional application using ActionScript and/or MXML and the Flex framework.
  • The Free Adobe Flex 3 SDK containing everything in the Open Source Flex SDK plus additional components such as advanced font encoders, tools for packaging Adobe AIR applications, and the Adobe Flash Player.
  • How to use the Flex SDK

    I have developed an Apache Ant build script that makes—after some configuration—the Flex SDK quite easy to use on Mac OS X. Here’s how to configure it:

    1. Download the latest Flex SDK from Adobe Open Source. Rename the SDK folder flex_sdk_3 and place it in /Applications/ on your hard drive.
    2. Locate Apache Ant on your system. Ant will already be installed if you have installed the Mac OS X Developer Tools (which are an optional install included with every version of OS X) or are running Leopard.

      Open Terminal and type:

      whereis ant

      It should say something like

      /usr/bin/ant

      If Ant is not installed, no path will be shown in Terminal. To install Ant I recommend using MacPorts, an excellent open source utility for managing unix tools on Mac OS X (follow these well written directions for installation). If you are not comfortable using the Terminal, there is a GUI available for MacPorts called Porticus.

    3. Copy the Flex Ant tasks to your Ant installation’s library. These will allow Ant to communicate with the major Flex SDK tools. To copy the tasks, first locate the Ant lib directory, which will be in Ant’s main installation folder. For example on Mac OS X 10.5 it appears at usr/share/ant/lib. Copy /Applications/flex_sdk_3/ant/lib/flexTasks.jar into this directory.
    4. If you are an advanced user and would like to utilize Unit Testing using FlexUnit, Download the FlexUnit Ant Tasks. Place these in the Ant installation’s library folder as well.

      (Note: The project template you will download from my site in the next step includes two SWCs for use with unit testing. For those that may be curious where these came from, here are the links to the original locations: FlexUnit SWC library and FlexUnit Optional SWC library)

    5. Download the Flex SDK example application template from my site. Unzip the archive and place the FlexSDKProjectTemplate folder on your desktop. Open the folder.
    6. Make a copy of build.properties.template and rename it build.properties.
    7. Open the build.properties file you just created and edit the REQUIRED TOOL LOCATIONS section to reflect the path to the Flex SDK, your preferred web browser, and the location of the Flash Player (which you will need to download if you have not already done so).
    8. Using Terminal navigate to the example application template. For example:
      cd Desktop/FlexSDKProjectTemplate/

      And then type the following:

      ant run

      The sample application will launch, typing ant usage will show you what other options are available, such as creating documentation, SWCs, or launching the application in a web browser.

    9. Lastly, to enable the trace() method so that it will work from your code when using the Flash debug player, create a textfile called mm.cfg and fill it with the following:

      TraceOutPutFileName=flashlog.txt
      ErrorReportingEnable=1
      TraceOutputFileEnable=1
      MaxWarnings=0

      Place this file at
      /Library/Application Support/Macromedia/mm.cfg
      . Whenever you have a trace("some text"); statement in your code, it will be written to:

      /Users/[your username]/Library/Preferences/Macromedia/Flash Player/Logs/flashlog.txt

    Please leave comments with any suggestions, problems, questions, etc. Enjoy!

    Troubleshooting

    Problem: Running ASDoc produces: Execute failed: java.io.IOException: /Applications/flex_sdk_3/bin/asdoc: cannot execute

    Solution: This mostly likely means the ASDoc script Ant uses is not set to be executable. Type the following in Terminal:

    cd /Applications/flex_sdk_3/bin/
    chmod +x asdoc

    The first line changes the directory to the one ASDoc resides in. The second line makes ASDoc executable.

    Problem: Running ASDoc produces: exec returned: 255

    Solution: This mostly likely means the ASDoc script (which is just a text file) contains Window-style line endings. These will need to be converted to linux.

    Install dos2unix using MacPorts and type the following in Terminal:

    cd /Applications/flex_sdk_3/bin/
    dos2unix asdoc

    This will turn off the executable bit in the permission tables, so you will have to re-enable that using the instructions in the first solution above.

    Problem: Running ASDoc produces: Could not create toplevel.xml: /Applications/flex_sdk_3/asdoc/templates/asDocHelper: cannot execute

    Solution: This mostly likely means that a helper script used by ASDoc is not set to be executable. Type the following in Terminal:

    cd /Applications/flex_sdk_3/asdoc/templates/
    chmod +x asDocHelper