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 8 or greater (*1)            

Maven 3.3.9 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.11.0/commons-io-2.11.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>