Apache Flex (Flex)
==================

    Apache Flex is an application framework for easily building Flash-based applications 
    for mobile devices, the browser and desktop.

    Apache Flex 4.9 is a follow up release to Apache Flex 4.8 which was a parity release
    of Adobe Flex 4.6.  This version adds new features and implements bug fixes that were
    unavailable in previous versions.  It is compatible with most code written to target
    Adobe Flex 4.6.

    For detailed information about Apache Flex please visit 
    http://incubator.apache.org/flex/ 
    
    The Apache Flex project has just graduated to be a top level Apache project and the
    project's URL will be soon be changing to http://flex.apache.org/.

    Apache Flex is a large project with many pieces.  The framework is implemented
    in ActionScript and the compiler is implemented in Java.

    Currently supported platforms include:

        Microsoft Windows
        Mac OS X
        Apple iOS
        Google Android
        RIM BlackBerry

    Apache Flex is the software evolution of the popular Adobe Flex SDK project.
    
    The community surrounding Flex is vast, diverse, distributed globally, and with all 
    levels of proficiency in software development. It is estimated that there are between 
    350,000 and 500,000 Flex developers worldwide. 

Getting the latest sources via Subversion
=========================================

    This is the recommended way to get Apache Flex.  We offer an automated installer
    along with binary distributions on our website at http://incubator.apache.org/flex.

    You can always checkout the latest source via subversion using the following
    command:

    svn co https://svn.apache.org/repos/asf/incubator/flex/trunk flex

    For further information visit http://incubator.apache.org/flex/source.html


Getting the convenience packages for Apache Flex
================================================

    The Apache Flex SDK Installer is an application that simplifies the download and
    installation of the Apache Flex SDK and its (required) components. It is aimed at
    anyone who wants to use the latest release of the Apache Flex SDK, but who might not
    necessarily be familiar with the tools and procedures required to compile the Apache
    Flex SDK from source code. The application will grab the binary distribution of the
    SDK from apache.org or one of its mirrors, install it onto your computer and prepare
    it for use with your favorite IDE such as Adobe Flash Builder or JetBrains IntelliJ.

    You can get the SDK Installer from the Apache Flex website at

      http://incubator.apache.org/flex/installer.html

    You can also get just the binaries from our website as well.  These binaries do not
    include the dependencies, so additional software may need to be downloaded and installed.

      http://incubator.apache.org/flex/download.html

Building Apache Flex 4.9
========================

    Apache Flex is a large project. It requires some build tools which must be installed
    prior to building Flex and it depends on some external software which
    are downloaded as part of the build process.  Some of these have different licenses.
    See the Software Dependencies section for more information on the external software
    dependencies.
    
    From Apache's perspective, the Adobe Flash Player and Adobe AIR have excluded
    licenses so they can not be bundled with the Apache Flex binaries.  They must be
    installed prior to building Apache Flex.
    
Install Prerequisites
---------------------

    Before building Flex you must install the following software and set the
    corresponding environment variables using absolute file paths.  Relative file paths
    will result in build errors.
    
    The environment variables PLAYERGLOBAL_HOME, AIR_HOME, FLASHPLAYER_DEBUGGER,
    PIXELBENDER_HOME and ADOBE_EXTENSION_MANAGER can also be set in the property file 
    called env.properties. See the env-template.properties file for instructions.
    
    The Adobe Flash Player playerglobal.swc is needed to compile all the components
    with the exception of the airframework and airspark components which require
    airglobal.swc from the AIR Integration Kit.  The AIR Integration kit is also needed
    to build and debug mobile applications.  The Adobe Flash Player content debugger is
    used by checkintests and other pieces of the test subsystem to run compiled
    applications.  The Adobe Pixel Bender Toolkit is needed to build some
    files needed for effects.
    
    ==================================================================================
    SOFTWARE                                    ENVIRONMENT VARIABLE (absolute paths)
    ==================================================================================
    
    Java SDK 1.6 or greater (*1)                JAVA_HOME
        (for Java 1.7 see note at (*2))
        
    Ant 1.7.1 or greater (*1)                   ANT_HOME
        (for Java 1.7 see note at (*2))
        
    Cygwin, git bash 
    or other unix-like shell
    (if Windows)
    
    Adobe AIR Integration Kit (*3)              AIR_HOME 
    
    Adobe Flash Player Content Debugger (*4)    FLASHPLAYER_DEBUGGER
        
    Adobe Pixel Bender Toolkit (*5)             PIXELBENDER_HOME
    
    Adobe Flash Player (*6)                     PLAYERGLOBAL_HOME

    Adobe Extension Manager CS5 (*7)            ADOBE_EXTENSION_MANAGER

    ==================================================================================
        
    *1) The bin directories for ANT_HOME and JAVA_HOME should be added to your PATH.
        
        On Windows, set PATH to
            
            PATH=%PATH%;%ANT_HOME%\bin;%JAVA_HOME%\bin
            
        On the Mac (bash), set PATH to
            
            export PATH="$PATH:$ANT_HOME/bin:$JAVA_HOME/bin"

    *2)  If you are using Java SDK 1.7 or greater on a Mac you must use Ant 1.8 or 
         greater. If you use Java 1.7 with Ant 1.7, ant reports the java version as 1.6 
         so the JVM args for the data model (-d32/-d64) will not be set correctly and you
         will get compile errors.
        
    *3) The Adobe AIR integration kit for Windows can be downloaded from:
                http://airdownload.adobe.com/air/win/download/3.4/AdobeAIRSDK.zip
        
         The Adobe AIR integration kit for Mac can be downloaded from:
            http://airdownload.adobe.com/air/mac/download/3.4/AdobeAIRSDK.tbz2

        This version of Apache Flex was certified for use with AIR 3.4, and should
        be compatible with other versions of AIR newer than 3.1. However it hasn't
        been tested on AIR 3.2, 3.3 or 3.5.

        Download the AIR SDK for your platform and unzip it.  Set AIR_HOME to the absolute 
        path of the AIR SDK directory.
               
    *4) The Adobe Flash Player content debuggers can be found here:
            http://www.adobe.com/support/flashplayer/downloads.html

        This version of Apache Flex was certified for use with Adobe Flash Player 11.1, and
        is compatible with versions 10.2 through 11.5. It has been tested with versions 11.1
        and 11.5 on Windows and Mac. It has been compiled against other Adobe Flash Player
        versions but has not been fully tested.
            
        On Windows, set FLASHPLAYER_DEBUGGER to the absolute path of FlashPlayerDebugger.exe
        
        On the Mac, set FLASHPLAYER_DEBUGGER to the absolute path of 
        Flash Player Debugger.app/Contents/MacOS/Flash Player Debugger
        
        On Linux, set FLASHPLAYER_DEBUGGER to the absolute path of flashplayerdebugger
            
    *5) The Adobe Pixel Bender Toolkit for Windows can be downloaded from:
            http://www.adobe.com/go/pixelbender_toolkit_zip/
        
         The Adobe Pixel Bender Toolkit for Mac can be downloaded from:
            http://www.adobe.com/go/pixelbender_toolkit_dmg/
        
        Download the Pixel Bender Toolkit for your platform and install or unzip it.
        Set PIXELBENDER_HOME to the absolute path of the Pixel Bender Toolkit directory.

    *6) The Adobe Flash Player playerglobal.swc for 11.1 can be downloaded from:
            http://fpdownload.macromedia.com/get/flashplayer/updaters/11/playerglobal11_1.swc 
        
        Use URL above to download playerglobal11_1.swc. Create the directory, player/11.1
        and copy playerglobal11_1.swc to player/11.1/playerglobal.swc.
        
        Set PLAYERGLOBAL_HOME to the absolute path of the player directory (not including
        the version subdirectory). The target-player option controls which 
        PLAYERGLOBAL_HOME subdirectory is used.

        Other more recent versions of Adode Flash Player playergloal.swc can be downloaded from:
            http://fpdownload.macromedia.com/get/flashplayer/updaters/11/playerglobal11_2.swc
            http://fpdownload.macromedia.com/get/flashplayer/updaters/11/playerglobal11_3.swc
            http://fpdownload.macromedia.com/get/flashplayer/updaters/11/playerglobal11_4.swc
            http://fpdownload.macromedia.com/get/flashplayer/updaters/11/playerglobal11_5.swc
            
        These can be used with Apache Flex but have not been fully tested.
        
    *7) The Adobe Extension Manager is only required for those creating releases or testing
            changes to the flash-integration swc.  Not that if you change APIs on classes
            that flash-integration depends on, you may need to update flash-integration.

        The Adobe Extension Manager for Windows can be downloaded from:
            http://download.macromedia.com/pub/dw_exchange/extension_manager/win/AdobeExtensionManager5All.zip
        
         The Adobe Extension Manager for Mac can be downloaded from:
            http://download.macromedia.com/pub/dw_exchange/extension_manager/mac/AdobeExtensionManager5All.dmg

        On Windows, set ADOBE_EXTENSION_MANAGER to the absolute path of "Adobe Extension Manager CS5.exe"
        
        On the Mac, set ADOBE_EXTENSION_MANAGER to the absolute path of "Adobe Extension Manager CS5.app"

FlashPlayer Configuration
-------------------------

    For testing, the Adobe Flash Player's mm.cfg file must have the following entries
    
        ErrorReportingEnable=1
        TraceOutputFileEnable=1
    
    and a FlashPlayerTrust file must allow local SWFs to access local files.
    
Other Locale Support
--------------------

    The Apache Flex SDK defaults to using the en_US locale and SDK error messages are by default
    displayed in American English.
    
    To compile the SDK for another locale either:

    Change the locale in the build.properties file to have a value other than "en_US". For this new
    locale to take effect the SDK needs to be recompiled. For example, to use the Australian English
    locale change locale to have a value of "en_AU" like so:
     
        locale = en_AU
        
    OR
    
    Compile the SDK with a -Dlocale=<locale> option, where <locale> is the new locale to compile the
    SDK against.

    The list of supported locales include:
        da_DK    el_GR    en_GB    fi_FI    ja_JP    nl_NL    ru_RU    zh_TW
        de_CH    en_AU    en_US    fr_FR    ko_KR    pt_BR    sv_SE
        de_DE    en_CA    es_ES    it_IT    nb_NO    pt_PT    zh_CN

    The Apache Flex SDK has only been tested for the en_US locale, however there is unlikely to be any
    issues with a SDK compiled for another locales.
    
Adobe Flash Player Version Support
----------------------------------

    The Apache Flex SDK defaults to using the Adobe Flash Player 11.1. The SDK can be
    compiled for Flash Player versions 10.2, 10.3, 11.0, 11.0, 11.1, 11.2, 11.3, 11.4 and 11.5.

    To compile the SDK for another version of the Adobe Flash Player either:

    Change the playerglobal.version in the build.properties file to have a value other than "11.1".
    For this change to take effect the SDK needs to be recompiled. For example to compile against the
    lastest version of the Adobe Flash Player set the value of playerglobal.version to be "11.5" like so:
     
        playerglobal.version = 11.5
        
    OR
    
    Compile the SDK with a -Dplayerglobal.version=<version> option, where <version> is the 
    Adobe Flash Player version to compile the SDK against.
    
    
    Different versions of the Adobe Flash Player require different versions of playerglobal.swc.
    
    These can be found at:
    
    http://fpdownload.macromedia.com/get/flashplayer/installers/archive/playerglobal/playerglobal10_2.swc
    http://fpdownload.macromedia.com/get/flashplayer/installers/archive/playerglobal/playerglobal10_3.swc
    http://fpdownload.macromedia.com/get/flashplayer/updaters/11/playerglobal11_0.swc 
    http://fpdownload.macromedia.com/get/flashplayer/updaters/11/playerglobal11_1.swc
    http://fpdownload.macromedia.com/get/flashplayer/updaters/11/playerglobal11_2.swc
    http://fpdownload.macromedia.com/get/flashplayer/updaters/11/playerglobal11_3.swc
    http://fpdownload.macromedia.com/get/flashplayer/updaters/11/playerglobal11_4.swc
    http://fpdownload.macromedia.com/get/flashplayer/updaters/11/playerglobal11_5.swc
    
    Copy the target playerglobal.swc to the directory:
    
        frameworks/libs/player/<version>/playerglobal.swf
    
    Where <version> is the major and minor version numbers of the Adobe Flash Player 
    separated by a period or full stop.
    
    If all of the playerglobal swcs where installed the frameworks/libs/player directory
    structure would look like this.
    
        /frameworks
            /libs
                /player
                    /10.2
                         /playerglobal.swc
                    /10.3
                         /playerglobal.swc
                    /11.0
                         /playerglobal.swc
                    /11.2
                         /playerglobal.swc
                    /11.2
                         /playerglobal.swc
                    /11.3
                         /playerglobal.swc
                    /11.4
                         /playerglobal.swc
                    /11.5
                         /playerglobal.swc     
                                                                                                                                
    Apache Flex has been tested with Adobe Flash Player 11.1 and 11.5 on Windows and Mac.
    
    It compiles against other Adobe Flash Player versions and is expected to work but they 
    may be some issues, particularly with the earlier 10.2 and 10.3 versions of the 
    Adobe Flash Player.

Software Dependencies
---------------------

    Apache Flex uses third-party code that will be downloaded as part of the Apache
    Flex build.  In addition, there is some optional third-party code that you can choose
    to download if you would like to take advantage of the features offered and you agree
    to the license terms.  
    
    The Apache Version 2.0 license is in the LICENSE file.  
    
    The following dependencies have licenses which are, or are compatible with, the Apache 
    Version 2.0 license.  You will not be prompted to acknowledge the download.  Most
    of the jars are installed in lib/external.
    
        batik - http://archive.apache.org/dist/xmlgraphics/batik/batik-1.6.zip
        commons-collections - http://archive.apache.org/dist/commons/collections/binaries/commons-collections-3.0.tar.gz
        commons-discovery - http://archive.apache.org/dist/commons/discovery/binaries/commons-discovery-0.2.tar.gz
        commons-logging - http://archive.apache.org/dist/commons/logging/binaries/commons-logging-1.0.4.tar.gz
        javacc - http://java.net/projects/javacc/downloads/download/javacc-5.0.tar.gz
        saxon9 - http://sourceforge.net/projects/saxon/files/Saxon-B/9.1.0.8/saxonb9-1-0-8j.zip/download
        velocity - http://archive.apache.org/dist/velocity/engine/1.4/velocity-1.4.tar.gz
        xalan - http://archive.apache.org/dist/xml/xalan-j/binaries/xalan-j_2_6_0-bin.tar.gz
        xerces - http://archive.apache.org/dist/xerces/j/Xerces-J-bin.2.9.1.zip
 
    The following dependencies have licenses which Apache considers to be reciprocal
    licenses so you will be prompted to acknowledge the license before the software is
    downloaded to your system. These files are installed in frameworks/libs.
        
        osmf.swc            

            Open Source Media Framework v1.0 used for video components
        
            This file is extracted from:
            http://sourceforge.net/projects/osmf.adobe/files/OSMF%201.0%20%28final%20source%2C%20ASDocs%2C%20PDF%20guides%2C%20and%20release%20notes%29/OSMF_1.0.zip/download
            
            This software is released under the Mozilla Public License Version 1.1:
            <http://www.mozilla.org/MPL/>
                    
    The following dependencies have licenses which Apache considers to be not compatible 
    with the Apache License Version 2.0. You will be prompted to read and agree to the 
    license terms of the dependency before the software can be downloaded to your system.  
    These are optional components which enable additional features.  They are installed in 
    libs/external/optional.

    flex-messaging-common.jar
        Provides integration with Adobe BlazeDs.
               
        This files are extracted from: 
        http://fpdownload.adobe.com/pub/flex/sdk/builds/flex4.6/flex_sdk_4.6.0.23201B.zip
       
        This software is released under an Adobe license:
        <http://www.adobe.com/products/eulas/pdfs/adobe_flex_software_development_kit-combined-20110916_0930.pdf>
        
    flex-fontkit.jar
    afe.jar, adt.jar
    aglj40.jar
    rideau.jar
        Adobe proprietary software which provides embedded font support.
       
        These jars are extracted from:
        http://fpdownload.adobe.com/pub/flex/sdk/builds/flex4.6/flex_sdk_4.6.0.23201B.zip
       
        This software is released under an Adobe license:
        <http://www.adobe.com/products/eulas/pdfs/adobe_flex_software_development_kit-combined-20110916_0930.pdf>
        
Using the Binary Distribution
-----------------------------

    You must download the third-party dependencies.

    When you have all the prerequisites in place and the environment variables set, 
    (see Install Prerequisites above), use

        cd <flex.dir>/frameworks
        ant thirdparty-downloads
    
Building the Framework in a Binary Distribution
-----------------------------------------------

    The source for most of the framework is included in the binary distribution.  
    It can be useful if you wish to debug and/or extend components.

    When you have all the prerequisites in place and the environment variables set, 
    (see Install Prerequisites above), use

        cd <flex.dir>/frameworks
        ant main        (or just ant since the default target is main)
    
    to download the third-party dependencies and build the Flex framework.  You may be 
    prompted to acknowledge some of the downloads.  Since the third-party dependencies 
    take a little while to download and they don't change very often, they are not 
    cleaned with the regular clean target.
    
    To clean the build, of everything other than the downloaded third-party dependencies 
    use
    
        ant clean 
    
    To clean the build, of everything, including the downloaded third-party dependencies 
    use
        
        ant super-clean (which is just thirdparty-clean followed by clean)

Building the Source in the Source Distribution
----------------------------------------------

    The source for both the Flex compiler and the Flex framework is included in the
    source distribution.  The compiler is in the modules directory and the framework
    is in the frameworks directory.
    
    When you have all the prerequisites in place and the environment variables set
    (see Install Prerequisites above), use

        cd <flex.dir>
        ant main        (or just ant since the default target is main)
    
    to download the thirdparty dependencies and build the source.  You may be prompted
    to acknowledge and/or confirm some of the downloads.  Since the third-party 
    dependencies take a little while to download and they don't change very often, they 
    are not cleaned with the regular clean target.
    
    If you would like to build the RSLs, use
    
        ant frameworks-rsls
        
    To clean the build, of everything other than the downloaded third-party dependencies 
    use
    
        ant clean 
    
    To clean the build, of everything, including the downloaded third-party dependencies 
    use
        
        ant super-clean (which is just thirdparty-clean followed by clean)
        
    To generate a source distribution package and a binary distribution package use
        
        ant -Dbuild.number=<last svn rev> -Dbuild.noprompt=  release

    The packages can be found in the "out" subdirectory.
            
    To build the ASDoc package
        
        ant asdoc-package

    To get a brief listing of all the targets type
    
        ant -projecthelp


Thanks for using Apache Flex.

                                          The Apache Flex Project
                                          <http://incubator.apache.org/flex>