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

Apache Royale is a next-generation of the Apache Flex&trade; SDK: . Royale has the goal of allowing applications developed in MXML and ActionScript to not only run in the Flash/AIR runtimes, but also to run natively in the browser without Flash, on mobile devices as a PhoneGap/Cordova application, and in embedded JS environments such as Chromium Embedded Framework. Royale has the potential to allow your MXML and ActionScript code to run in even more places than Flash currently does.

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 is used for 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 that find it inconvenient to build
Royale from sources before using.

In addition to that, Royale compiled source is 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 3 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 of UI 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.  The packages ending with -bin-js only supports JavaScript output.  The packages 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 the 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.  In order to get started using Royale, you are invited to follow along with the Quick Start Guide at https://github.com/apache/royale-asjs/wiki/Quick-Start.


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

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

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

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

On Windows:

  npm install royale -g


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

In order to get started using Royale, you are invited to follow along with the Quick Start Guide at https://github.com/apache/royale-asjs/wiki/Quick-Start.

Thanks for using Apache Royale.  Enjoy!


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