Apache Royale
=============

Apache Royale is the next generation of the Apache Flex SDK. Royale lets you develop applications in MXML and ActionScript and compile them to run not only on the Flash/AIR runtimes, but also in modern browsers without Flash, on mobile devices as a PhoneGap/Cordova application, and in embedded JavaScript environments such as Chromium Embedded Framework. 

For detailed information about using Royale, visit:

<https://apache.github.io/royale-docs/>

For more information about the Apache Royale project, visit:

<http://royale.apache.org>

This README file applies to the top-level source and binary packages.  The 
individual folders (royale-compiler, royale-typedefs, royale-asjs) each have their own
README file specific to the contents of those folders.

Getting Royale
==============

Official Apache Royale releases are in the form of a source package, which needs to
be built by Apache Ant or Apache Maven before it can be used to build applications
that produce JS or SWF output. Royale also provides pre-built packages (often referred
to as "binary convenience packages") for users who choose not to compile Royale from sourc.

Royale compiled binaries are available as Maven artifacts and through Node Package Manager (NPM).  If you want to use NPM, see "Getting Royale with NPM" below.

This document is the README for the source and binary convenience packages.

This package contains sources from three Git repositories. Royale source code is organized into these repos as follows:

   royale-compiler:  Java source code for the Royale compiler that converts ActionScript and MXML to JS or SWF output.

   royale-typedefs:  JavaScript (and some ActionScript) definitions for common JavaScript libraries.

   royale-asjs:      ActionScript source code for a framework for the user interface and other components.

Each folder has its own README, RELEASE_NOTES, LICENSE and NOTICE with information specific to the sources contained within that folder.

Building Royale
===============

Royale requires Java SDK 1.7 or greater to be installed on your computer. For more information on installing the Java SDK, see:

    <http://www.oracle.com/technetwork/java/javase/downloads/index.html>

Set the JAVA_HOME environment variable to the Java SDK installation path.

Add the bin directory of **JAVA_HOME** to the PATH.

On Windows, set PATH to
  PATH=%PATH%;%JAVA_HOME%\bin

On a Mac, set PATH to
  export PATH="$PATH:$JAVA_HOME/bin"

Once Java is installed and setup, follow the instructions for "Building Royale With 
Apache Maven" or "Building Royale With Apache Ant".  If you want SWF output, see the
section on "Additional Prerequisites for SWF Output" before building Royale.


Building Royale With Apache Maven
=================================

Royale requires Maven 3.3.9 or greater to be installed on your computer.

To build Royale with Apache Maven, run Maven in the 3 folders as follows:

royale-compiler:  mvn clean install -P -main,utils
royale-compiler:  mvn clean install
royale-typedefs:  mvn clean install
royale-asjs:      mvn clean install

When complete, you should be able to use the Maven archetypes in royale-asjs/archetypes
to build Royale applications.


Building Royale With Apache Ant
===============================

Royale requires Ant 1.7.1 or greater to be installed on your computer.

Note: 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 you will get compile errors.

For more information on installing Ant, see:

   <http://ant.apache.org/>

Set the **ANT_HOME** environment variable to the Ant installation path.

Add the bin directory of **ANT_HOME** to the PATH.

On Windows, set PATH to
  PATH=%PATH%;%ANT_HOME%\bin

On a Mac, set PATH to
  export PATH="$PATH:$ANT_HOME/bin"

Then, run:
  cd royale-asjs
  ant all

This will build all of Royale and when finished the royale-asjs folder will be the
equivalent of a "binary convenience package".  For instructions on how to use
the results of the build, see the next section.

Using the Binary Convenience Package
====================================

There are two packages containing compiled binaries for each release. The package ending with -bin-js only supports JavaScript output. The package ending with bin-js-swf supports both JavaScript and SWF output.

These packages can be used in IDEs that support Royale. The bin-js package can be uncompressed and used directly. The bin-js-swf package requires downloading of SWF-related libraries from Adobe Systems Inc. There is an Ant script called InstallAdobeSDKs.xml that you can run via:

  ant -f InstallAdobeSDKs.xml

IDEs should recognize the royale-asjs folder as a valid Royale SDK.

You can also compile applications from the command line by running MXMLC to compile ActionScript and MXML into JS (and SWF) applications.

On Windows, run:
  royale-asjs\js\bin\mxmlc.bat

On Mac, run: 
  royale-asjs/js/bin/mxmlc

See documentation for details on how to use mxmlc. 


Additional Prerequisites For SWF Output
=======================================

playerglobal.swc
----------------

The Adobe Flash Player playerglobal.swc (version 11.1) can be downloaded from:

<http://fpdownload.macromedia.com/get/flashplayer/installers/archive/playerglobal/playerglobal11_1.swc>

First, create the following directory structure:

  [some folder]/player/11.1/*

Next, rename the downloaded SWC to 'playerglobal.swc' and place it in the above directory.

Then set the PLAYERGLOBAL_HOME environment variable to the absolute path of the player directory, not including the version subdirectory (i.e. '[some folder]/player').

Other, more recent versions of Adobe Flash Player 'playerglobal.swc' can be downloaded from 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>). These versions can be used with Royale, but not all have been fully tested.


Flash Player Content Debugger
-----------------------------

The Flash Player Content Debugger can be found here:

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

This version of Royale was certified for use with Flash Player 11.1, and is compatible with version 10.2 and up. It has been tested with version 16.0 on Windows and Mac. It has been compiled, but not fully tested, with other Flash Player versions. It has not been fully tested on Linux.

On Windows, set the FLASHPLAYER_DEBUGGER environment variable to the absolute path including the filename of the Flash Player Projector Content Debugger executable (e.g. 'FlashPlayerDebugger.exe'). Note: the filename of Flash Player Content Debugger can differ slightly between versions. Adjust your path accordingly.

On the Mac, set the FLASHPLAYER_DEBUGGER environment variable to the absolute path of 'Flash Player.app/Contents/MacOS/Flash Player Debugger'

On Linux, set the FLASHPLAYER_DEBUGGER environment variable to the absolute path of 'flashplayerdebugger'.

Adobe AIR Integration Kit
-------------------------

This version of Apache Royale was certified for use with Adobe AIR 16 and is compatible with version 3.1 and up. The Adobe AIR integration kit can be downloaded from:

Windows: <http://airdownload.adobe.com/air/win/download/16.0/AdobeAIRSDK.zip>

Mac: <http://airdownload.adobe.com/air/mac/download/16.0/AdobeAIRSDK.tbz2>

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

After you download the AIR SDK, unzip it and place it in a directory of your choice.

Set the AIR_HOME environment variable to the absolute path of the AIR SDK directory.


Getting Royale with NPM
=======================

You can use NPM to get a pre-built package.  To do so run:

On Mac:

  sudo npm install @apache-royale/royale-js -g

or for both JS and SWF output:

  sudo npm install @apache-royale/royale-js-swf -g

On Windows:

  npm install @apache-royale/royale-js -g

or for both JS and SWF output:

  npm install @apache-royale/royale-js-swf -g


Using Royale
============

To get started using Royale, follow along with the Quick Start Guide at https://github.com/apache/royale-asjs/wiki/Quick-Start, and the tutorials at the <a href="https://royale.codeoscopic.com/" target="_blank">Royale website</a>.

Thanks for using Apache Royale.  Enjoy!


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