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