README

The Apache Flex SDK
===================

The Apache Flex SDK is the evolution of the popular Adobe Flex SDK. The Apache
Flex SDK is an application development framework for easily building Flash
based applications for mobile devices, web browsers, and desktops. Currently
supported platforms include:

    Microsoft Windows
    Mac OS X
    Apple iOS
    Google Android
    RIM BlackBerry
    (Linux)

Linux support is currently experimental and you may run into issues. The Apache
Flex project would like to see a fully supported Linux release, but we need
help from the community in order to do that. Please help out if you can.

For more information about the Apache Flex project, please visit:

    http://flex.apache.org/

The Apache Flex SDK 4.14.0 is a follow up release to version 4.13.0. It is
compatible with most code written for the original Adobe Flex 4.6 SDK.



Installing the Apache Flex SDK
==============================

The Apache Flex SDK Installer is an AIR 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 favourite IDE
such as Adobe Flash Builder or JetBrains IntelliJ IDEA.

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

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

Starting with the Apache Flex SDK 4.12, Linux users can install the binary
distribution using ANT. More information about installing the binary package
with ANT can be found on our wiki at:

    https://cwiki.apache.org/confluence/display/FLEX/Installation+help#Installationhelp-Antinstaller



Building the Apache Flex SDK from source
========================================

The Apache Flex SDK is a large project. It requires build tools which must be
installed on your system and it depends on some external software. The external
software is downloaded as part of the build process.

The following steps are all you need for a fully functional SDK:
- Prepare your system
    - install external software
    - set environment variables
- Get the source code
    - flex-sdk
    - flex-tlf
- Build the SDK
- Prepare the SDK for use with an IDE
- Optional steps:
  - Flash Player configuration
  - Other locale support


Prepare your system
-------------------

Before building the Apache Flex SDK you must install the following software and
set the corresponding environment variables. Make sure to use absolute paths,
relative paths will result in build errors.

The environment variables PLAYERGLOBAL_HOME, AIR_HOME, FLASHPLAYER_DEBUGGER,
TLF_HOME, and ADOBE_EXTENSION_MANAGER can also be set in a property file
called env.properties. See the env-template.properties file for instructions.

The Adobe Flash Player and Adobe AIR have excluded licenses so they can not be
bundled with the Apache Flex SDK, i.e. they need to be installed separately.

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 the ant ‘checkintests’
target and other pieces of the test subsystem to run compiled applications.


---------------------------------------------------------------------
SOFTWARE                                      ENVIRONMENT VARIABLE
---------------------------------------------------------------------

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

Adobe AIR Integration Kit (* 3)               AIR_HOME

Adobe Flash Player Content Debugger (* 4)     FLASHPLAYER_DEBUGGER

Adobe Flash Player playerglobal swcs (* 5)    PLAYERGLOBAL_HOME

Optional: Text Layout Framework (* 6)         TLF_HOME

Optional: 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'

On Linux make sure your path includes ANT_HOME and JAVA_HOME.

* 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/15.0/AdobeAIRSDK.zip

The Adobe AIR integration kit for Mac can be downloaded from:

    http://airdownload.adobe.com/air/mac/download/15.0/AdobeAIRSDK.tbz2

The Adobe AIR integration kit for Linux can be downloaded from:

    http://airdownload.adobe.com/air/lin/download/2.6/AdobeAIRSDK.tbz2

Download the AIR SDK for your platform and unzip it. Set AIR_HOME to the
absolute path of the AIR SDK directory.

This version of the Apache Flex SDK was certified for use with Adobe AIR 3.7
and is compatible with version 3.1 and up. It has been fully tested on AIR 3.7,
4 and 15.

* 4)
The Adobe Flash Player content debuggers can be found here:

    http://www.adobe.com/support/flashplayer/downloads.html

This version of the Apache Flex SDK was certified for use with Adobe Flash
Player 11.1, and is compatible with version 10.2 and up. It has been tested
with versions 11.1, 11.7, 13.0 and 15.0 on Windows and Mac. It has been
compiled against other Adobe Flash Player versions but has not been fully
tested. It has not been fully tested on Linux.

On Windows, set FLASHPLAYER_DEBUGGER to the absolute path including the
filename of the FlashPlayerDebugger.exe. Note the filename of flash player
debugger maybe different, e.g. C:\MyPath\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 Flash Player playerglobal.swc for 11.1 can be downloaded from:

    http://download.macromedia.com/get/flashplayer/updaters/11/playerglobal11_1.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.

Additional information about downloading and setting up this and/or other
versions of the Adobe Flash Player can be found in the section
'Adobe Flash Player Version Support' below.

* 6)
The build scripts assume that the source code folder containing the Apache Flex
Text Layout Framework root folder ('flex-tlf') is at the same level as the SDK
root folder ('flex-sdk'). See 'Getting the source code', below. If this is not
the case on your system, then you must set the TLF_HOME environment variable to
point to your TLF root folder.

* 7)
The Adobe Extension Manager is only required for those creating releases or
testing changes to the flash-integration SWC. Note that if you change APIs on
classes that flash-integration depends on, you may need to update
flash-integration.

On Windows, download the Adobe Extension Manager from:

    http://download.macromedia.com/pub/dw_exchange/extension_manager/win/AdobeExtensionManager5All.zip

and set ADOBE_EXTENSION_MANAGER to the absolute path of
'Adobe Extension Manager CS5.exe'

On Mac, download the Adobe Extension Manager from:

    http://download.macromedia.com/pub/dw_exchange/extension_manager/mac/AdobeExtensionManager5All.dmg

and set ADOBE_EXTENSION_MANAGER to the absolute path of
'Adobe Extension Manager CS5.app/Contents/MacOS/Adobe Extension Manager CS5'

On Linux, no Adobe Extension Manager exists.


Get the source code
-------------------

The Apache Flex SDK source code uses git for SCM.

You can get the latest source ('develop' branch) using the following commands:

    git clone https://git-wip-us.apache.org/repos/asf/flex-sdk.git flex-sdk
    cd flex-sdk
    git checkout develop

The Apache Flex SDK requires source code from the Apache Flex Text Layout
Framework (TLF). To get the latest source for TLF ('develop' branch), use the
following commands:

    git clone https://git-wip-us.apache.org/repos/asf/flex-tlf.git flex-tlf
    cd flex-tlf
    git checkout develop

For further information visit:

    http://flex.apache.org/download-source.html


Build the SDK
-------------

When you have all the prerequisites in place and the environment variables set,
use these commands:

    cd <flex-sdk>
    ant main

to download the third party dependencies and build the source. You will 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

To generate a source distribution package and a binary distribution package,
use:

    ant -Dbuild.number=<YYYYMMDD> -Dbuild.noprompt= release

The packages can be found in the 'out' subdirectory.

To build the ASDoc package, use:

    ant asdoc-package

To get a brief listing of all the targets type, use:

    ant -projecthelp


Prepare the SDK for use with an IDE
-----------------------------------

If you want to use the SDK you built from source in Adobe Flash Builder, you
need to run these commands and scripts:

    cd <flex.dir>
    ant frameworks-rsls
    ./ide/constructFlexForIDE.[sh/bat]
    (Mac only: ./ide/addAIRtoSDK.sh)

This builds the RSLS for the SDK and copy some IDE related files from the Adobe
Flex SDK 4.6. On a Mac you will need to run the 'addAIRtoSDK.sh' script to
complete the installation.

To create an SDK for another IDE, or if you want to use a different version of
Adobe AIR (Adobe Flex 4.6 uses Adobe AIR 3.1), run:

    /ide/flashbuilder/makeApacheFlexForIDE.bat (on Windows)
    /ide/flashbuilder/makeApacheFlexForIDE.sh (on Mac and Linux)



Using the Binary Distribution
=============================

In order to use the binary distribution of the SDK, you must first download the
third-party dependencies. First, make sure your system is good to go: see
'Prepare your system' above. Note: you cannot use the env.properties file to
set the environment variables when you use the Binany Distribution. Now, use:

    cd <flex-sdk>/frameworks
    ant thirdparty-downloads

To complete the setup of the SDK, follow the instructions in the
'Prepare the SDK for use with an IDE' section above.



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.

More information about these settings can be found here:

    http://help.adobe.com/en_US/ActionScript/3.0_ProgrammingAS3/WS5b3ccc516d4fbf351e63e3d118a9b90204-7c95.html



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.

To compile all supported locales, which may take some time, use

    ant other.locales

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

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 used with Flash Player versions 10.2 and up.

It is recommended that you update to the latest version of Adobe Flash Player.
Newer versions of the Adobe Flash player address security vulnerabilities, fix
bugs/issues, increase stability, and implement new features.

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

Change the flex-config.xml configuration file to specify another version of the
Adobe Flash Player.

OR

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 latest version of the Adobe
Flash Player set the value of playerglobal.version to be '14.0' like so:

    playerglobal.version = 14.0

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://download.macromedia.com/get/flashplayer/installers/archive/playerglobal/playerglobal10_2.swc
    http://download.macromedia.com/get/flashplayer/installers/archive/playerglobal/playerglobal10_3.swc

and

   http://download.macromedia.com/get/flashplayer/updaters/<version.major>/playerglobal<version.major>_<version.minor>.swc

(e.g. http://download.macromedia.com/get/flashplayer/updaters/11/playerglobal11_1.swc)

Copy the target playerglobal.swc to the directory:

    frameworks/libs/player/<version>/playerglobal.swc

Where <version> is the major and minor version numbers of the Adobe Flash
Player separated by a period or full stop.


Software Dependencies
=====================

The Apache Flex SDK uses third-party code that will be downloaded as part of
the 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

    and 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 file is extracted from:

        http://fpdownload.adobe.com/pub/flex/sdk/builds/flex4.6/flex_sdk_4.6.0.23201B.zip

    and is released under an Adobe license:

        http://www.adobe.com/products/eulas/pdfs/adobe_flex_software_development_kit-combined-20110916_0930.pdf

    adt.jar, afe.jar, aglj40.jar, flex-fontkit.jar and rideau.jar (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

    and are released under an Adobe license:

        http://www.adobe.com/products/eulas/pdfs/adobe_flex_software_development_kit-combined-20110916_0930.pdf



Thanks for using the Apache Flex SDK. Enjoy!

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