Apache Royale Compiler
====================

    The Apache Royale Compiler compiles ActionScript 3.0 and MXML code to SWF
    or JavaScript.
    
    The Apache Royale Compiler was formerly known as the 'Falcon' compiler.  It was 
    originally destined to be the next-generation replacement to the MXMLC compiler
    that is currently bundled with the Apache Flex SDK.  This compiler is based on the 
    Adobe 'ASC 2.0' code base donated to Apache by Adobe Systems Inc.

    The compiler has been modified and extended to transpile MXML and ActionScript
    to JavaScript, and potentially other output definitions, and it is
    now being used as the compiler for the Apache Royale SDK.  Royale is a
    next-generation SDK that allows the developer to leverage MXML and ActionScript
    to build applications that not only run as a SWF, but can also be cross-compiled
    to JavaScript and run natively in a browser — or anywhere that JavaScript runs.

Getting the latest sources via git
==================================

    Getting the source code is the recommended way to get the Apache Royale Compiler.  
    The compiler can also be installed by installing an Apache Royale SDK via NPM
    or by unpacking Apache Royale binary distributions available from link on our 
    website at https://royale.apache.org/.

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

	 git clone https://github.com/apache/royale-compiler.git royale-compiler
	 cd royale-compiler
	 git checkout develop

Building the Apache Royale Compiler
=================================

    The Apache Royale Compiler is a large project. It requires some build tools 
    which must be installed prior to building the compiler 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.

    Linux support is currently experimental has not been fully tested so you 
    may run into issues.

    You can build the Apache Royale Compiler with Apache Maven or Apache Ant.

Building the Apache Royale Compiler with Apache Maven
-----------------------------------------------------

    Before building the Apache Royale Compiler with Apache Maven you must install 
    the following software.

    ==================================================================================
    SOFTWARE                                
    ==================================================================================

    Java SDK 11 or greater (*1)            

    Maven 3.8.1 or greater (*1)              

    ==================================================================================

    *1) The bin directories for Maven and Java should be added to your
        PATH.

    Then run

        mvn clean install

Building the Apache Royale Compiler with Ant
----------------------------------------------

    Before building the Apache Royale Compiler with Apache Ant you must install 
    the following software and set the corresponding environment variables using 
    absolute file paths.  Relative file paths will result in build errors.

    ==================================================================================
    SOFTWARE                                     ENVIRONMENT VARIABLE (absolute paths)
    ==================================================================================

    Java JDK 11 or greater (*1)                            JAVA_HOME

    Ant 1.8 or greater (*1)                                ANT_HOME

    ==================================================================================
    
    *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 you path include ANT_HOME and JAVA_HOME.

    Once you've done that, use

        ant main        (or just ant since the default target is main)

    to download the third-party dependencies and build the source and run
    some tests.  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 wipe-all (which is just thirdparty-clean followed by clean)

    To get a brief listing of all the targets type

        ant -projecthelp


Running Integration Tests
-------------------------

    The build process will run some tests.  By default, the build will not
    run feature or integration tests.  Before running some of the feature or 
    integration tests you will need to set the environment variables described
    below, or set up a env.properties file with those settings.

    A template is found here: env-template.properties. 

    Some tests of SWF output may use the Adobe Flash Player or Adobe AIR to
    run a SWF.  If you plan to run those tests, ensure that the folder 
    containing the source code is in your Flash Player Trust files.

    ==================================================================================
    SOFTWARE                                     ENVIRONMENT VARIABLE (absolute paths)
    ==================================================================================

    Apache Royale SDK or repository (*3)         ASJS_HOME

    Adobe AIR Integration Kit (*4)               AIR_HOME

    Adobe Flash Player Content Debugger (*5)     FLASHPLAYER_DEBUGGER

    Adobe Flash Player playerglobal swcs (*6)    PLAYERGLOBAL_HOME

    Adobe Flash Player playerglobal swcs (*6)    PLAYERGLOBAL_VERSION

    Apache Flex SDK or repository (*7)           FLEX_HOME

    Apache Flex TLF source (*8)                  TLF_HOME

    ==================================================================================

    *3) This option is only required to run additional tests to verify that the compiler
        can output Royale applications that use Royale framework SWCs.
        
        Set the ASJS_HOME variable to the root of the Apache Royale SDK or 
        royale-asjs repository.

    *4) This option is only required to run additional tests to verify that the compiler
        can output SWFs.
        
        The Adobe AIR integration kit for Windows can be downloaded from:
            https://airdownload.adobe.com/air/win/download/32.0/AdobeAIRSDK.zip

         The Adobe AIR integration kit for Mac can be downloaded from:
            https://airdownload.adobe.com/air/mac/download/32.0/AdobeAIRSDK.dmg

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

    *5) This option is only required to run additional tests to verify that the compiler
        can output SWFs.
        
        The Adobe Flash Player content debugger for Windows can be downloaded from:
            https://fpdownload.macromedia.com/pub/flashplayer/updaters/32/flashplayer_32_sa_debug.exe

        The Adobe Flash Player content debugger for Mac can be downloaded from:
            https://fpdownload.macromedia.com/pub/flashplayer/updaters/32/flashplayer_32_sa_debug.dmg

        The Adobe Flash Player content debugger for Linux can be downloaded from:
            https://fpdownload.macromedia.com/pub/flashplayer/updaters/32/flash_player_sa_linux_debug.x86_64.tar.gz

        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

    *6) This option is only required to run additional tests to verify that the compiler
        can output SWFs.
        
        The Adobe Flash Player playerglobal.swc for 32.0 can be downloaded from:
            https://fpdownload.macromedia.com/get/flashplayer/updaters/32/playerglobal32_0.swc

        Use URL above to download playerglobal32_0.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.

        Copy the target playerglobal.swc to the directory:

           frameworks/libs/player/<version.major>.<version.minor>/playerglobal.swc
    
        These can be used with the Apache Royale Compiler but not all have not been fully
        tested.

        Set PLAYERGLOBAL_VERSION to the version you chose.  The default is 11.1.

    *7) This option is only required to run additional tests to verify that the compiler
        can output SWFs.
        
        The FLEX_HOME variable should point to a folder of the flex-sdk sources.
        If you don’t provide this variable (and TLF_HOME and BLAZEDS_HOME), 
        you may not be able to run all of the tests in the compiler 
        and compiler-jx folders.

    *8) This option is only required to run additional tests to verify that the compiler
        can output SWFs.
        
        The TLF_HOME variable should point to a folder containing a folder
        named textLayout that contains a src folder of the TLF sources.
        This should be the root of the flex-tlf repository, or can be
        the frameworks/projects folder of an IDE compatible Royale SDK.

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

    The Apache Royale Compiler uses third-party code that will be downloaded as 
    part of the build.

    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 when installed
    into an Apache Royale SDK and the lib folder in the repository working copy.

        antlr - https://repo1.maven.org/maven2/org/antlr/antlr-complete/3.5.2/antlr-3.5.2-complete.jar
        args4j - https://repo1.maven.org/maven2/args4j/args4j/2.0.28/args4j-2.0.28.jar
        commons-cli - https://repo1.maven.org/maven2/commons-cli/commons-cli/1.2/commons-cli-1.2.jar
        commons-io - https://repo1.maven.org/maven2/commons-io/commons-io/2.14.0/commons-io-2.14.0.jar
        commons-lang - https://repo1.maven.org/maven2/commons-lang/commons-lang/2.6/commons-lang-2.6.jar
        commons-lang3 - https://repo1.maven.org/maven2/org/apache/commons/commons-lang3/3.4/commons-lang3-3.4.jar
        commons-compress - https://repo1.maven.org/maven2/org/apache/commons/commons-compress/1.26.0/commons-compress-1.26.0.jar
        guava - https://repo1.maven.org/maven2/com/google/guava/guava/32.0.0-jre/guava-32.0.0-jre.jar
        failureaccess - https://repo1.maven.org/maven2/com/google/guava/failureaccess/1.0.2/failureaccess-1.0.2.jar
        jburg - https://repo1.maven.org/maven2/net/sourceforge/jburg/jburg/1.10.2/jburg-1.10.2.jar
        jflex - https://jflex.de/jflex-1.6.0.tar.gz
        lzma - http://www.java2s.com/Code/JarDownload/lzma/lzma-9.20.jar.zip
        Google Closure Compiler - https://github.com/google/closure-compiler/archive/v20181210.zip

    The Google Closure Compiler includes files originally from Rhino under MPL 1.1.  For
    details see:
       https://github.com/google/closure-compiler/blob/master/README.md.  
    Rhino is available at:
       https://github.com/mozilla/rhino

Using the Binary Distribution
-----------------------------

    The binary artifacts produced by the Maven build are then used by Maven projects
    to build Apache Royale applications.  See the archetypes in the royale-asjs repo
    or the examples in the royale-asjs repo.

    The binaries produced by the Apache Ant build are intended to be packaged into an
    Apache Royale SDK to create Apache Royale applications via IDEs, Ant build
    scripts, or by running the compiler executables directly from the command line.

    To temporarily use a set of binary artifacts when building Apache Royale
    applications with Apache Ant, set the ROYALE_COMPILER_HOME property to the 
    compiler-jx folder in the binary distribution and set ROYALE_SWF_COMPILER_HOME
    to the compiler folder in the binary distribution either via an 
    environment variable or property when running Ant to build the Apache Royale
    application.

    To replace the current Royale Compiler binaries in a Apache Royale SDK, 
    run the copy-compiler target from the Ant script in the Apache Royale SDK and
    set ROYALE_COMPILER_REPO to the root of the binary distribution when running 
    that target.

       ant -DROYALE_COMPILER_REPO=<path to binary distribution> copy-compiler

Thanks for using Apache Royale. Enjoy!

                                          The Apache Royale Project
                                          <https://royale.apache.org>