////

  Licensed to the Apache Software Foundation (ASF) under one or more
  contributor license agreements.  See the NOTICE file distributed with
  this work for additional information regarding copyright ownership.
  The ASF licenses this file to You under the Apache License, Version 2.0
  (the "License"); you may not use this file except in compliance with
  the License.  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.

////

= Building Royale from source

This document will guide you through the process of building Royale from source.

== Prerequisites

In order to build Royale you require the following software installed on your machine:

- A Java JDK 1.6 or higher (a simple Java runtime is not enough) (http://www.oracle.com/technetwork/java/javase/downloads/index.html)
- Apache Maven 3.3.1 or higher (http://maven.apache.org)
- The Flash Player projector content debugger (https://www.adobe.com/support/flashplayer/debug_downloads.html)

Make sure the following environment variable is set to the exact location of the Flash Player projector content debugger:

----
FLASHPLAYER_DEBUGGER={Absolute path to the executable}
----

On a Mac you have to point to the executable itself, not the app-directory

----
FLASHPLAYER_DEBUGGER="{Absolute path the the App directory}/Flash Player.app/Contents/MacOS/Flash Player Debugger"
----

If you are using the commandline you need to make sure the following environment variables are set:

----
JAVA_HOME={Absolute path to the JDK installation directory}
MAVEN_HOME={Absolute path to the Maven installation directory}
----

The following elements have to be added to your systems PATH variable:

----
{JAVA_HOME}/bin
{MAVEN_HOME}/bin
----

The following setup has proven to be usefull:

=== Windows

----
JAVA_HOME={Absolute path to the JDK installation directory}
MAVEN_HOME={Absolute path to the Maven installation directory}
FLASHPLAYER_DEBUGGER={Absolute path to the executable}
PATH=%PATH%;%JAVA_HOME%\bin;%MAVEN_HOME%\bin
----

=== Linux / Mac

----
JAVA_HOME={Absolute path to the JDK installation directory}
MAVEN_HOME={Absolute path to the Maven installation directory}
FLASHPLAYER_DEBUGGER={Absolute path to the executable}
PATH=${PATH}:${JAVA_HOME}/bin;${MAVEN_HOME}/bin
----

== Building Royale

Currently you need to checkout and run builds in 3 different repositories.
This is due to the fact that every part of the Royale SDK (Compiler,
typedefs and framework) should be released separately. Also there is a
technical reason for this, as the compiler part contains a plugin which
is used by the typedefs and the framework. As Maven resolves all the plugins
before starting to build we would have a hen-eg-problem. This is particularly
hard to handle during Maven releases.

In order to build, the compiler and the typedefs need a set of plugins which
are not available as standard maven plugins. Therefore the compiler build
contains a compiler-build-tools project which is a Maven plugin that provides
all the additional logic needed to build all parts of Royale. This needs
to be built and released only once. As soon as that's done we will continue
to reference the released version in the rest of the build. This module
only needs to be built if there are changes to the tools.

Another thing the user should keep in mind, that an important part of the
build is the `flex-sdk-converter-maven-extension`. This takes care of
automatically providing the Maven artifacts for the old FDK, Air and Flash
resources. Unfortunately this has not been released yet and therefore is
only available in the Apache Snapshot Repo. Maven doesn't know about that
therefore we have to tell it to. The best way would be to add the apache-
snapshot-repo to your `~/.m2/settings.xml`

----
    <!-- Profile that adds the apache snapshot repo to maven -->
    <profiles>
        <profile>
            <id>apache-snapshots-enabled</id>
            <!--Enable snapshots for the built in central repo and plugin repo -->
            <repositories>
                <repository>
                    <id>apache-snapshots</id>
                    <url>http://repository.apache.org/snapshots/</url>
                    <releases>
                        <enabled>false</enabled>
                    </releases>
                    <snapshots>
                        <enabled>true</enabled>
                    </snapshots>
                </repository>
            </repositories>
            <pluginRepositories>
                <pluginRepository>
                    <id>apache-snapshots</id>
                    <url>http://repository.apache.org/snapshots/</url>
                    <releases>
                        <enabled>false</enabled>
                    </releases>
                    <snapshots>
                        <enabled>true</enabled>
                    </snapshots>
                </pluginRepository>
            </pluginRepositories>
        </profile>
    </profiles>

    <!-- Activate the apache-snapshots-enabled profile -->
    <activeProfiles>
        <activeProfile>apache-snapshots-enabled</activeProfile>
    </activeProfiles>
----

For your convenience, we added a file called "settings-template.xml" to each of
the three repositories. You could simply copy one to your `~/.m2` directory and
name it `settings.xml` or you tell maven to use the template, by using the `-s`
parameter instead:

----
mvn -s settings-template.xml
----

So for the rest of this documentation we will be assuming you have
defined the Apache Snapshot Repository in the default Maven settings.xml.
In all other cases you simply have to add `-s settings-template.xml` to
every Maven call.

=== Building the Compiler

The compiler block is the main part of the build. You can easily build
it using the following command:
(run it in the royale-compiler repo)

----
mvn clean install
----

This contains a large set of unit- and integrationtests. If you just want
to build the compiler, the following command will take care of this without
running the unit- and integrationtests:
(run it in the royale-compiler repo)

----
mvn clean install -DskipTests
----

If you want to run the unittests, but skip the integrationtests:
(run it in the royale-compiler repo)

----
mvn clean install -DskipITs
----

Maven also takes care of building the project website and documentation.
This is handled as part of the Maven `site` lifecycle. If you want to build
the documentation for the compiler, the following command will take care of
this:
(run it in the royale-compiler repo)

----
mvn site
----

This will create the documentation for each module inside the corresponding
modules `target/site` directory. However if you open the `index.html` of the
root project, the links to the sub-modules will not work as the local directory
structure differs from the structure the deployed documentation would have.
In order to locally read and test the documentation, the following command will
wrap all parts into the `target/staging` directory of the project root.
(run it in the royale-compiler repo)

----
mvn site:stage
----

You can of course wrap all together into one big build:
(run it in the royale-compiler repo)

----
mvn clean install site site:stage
----

=== Building the typedefs

The second block of the Royale SDK are the typedefs (aka externs). These
are located in a separate repo (royale-typedefs).

Building the typedefs is quite straight-forward. All you need to do, is run the
following command:
(run it in the royale-typedefs repo)

----
mvn clean install
----

=== Building the framework

The framework is the last building block and is located in the `royale-asjs` repo.
This contains all the modules that make up the framework of Royale. It also
contains a set of examples as well as the Maven assembly to build a local Royale
SDK distribution, which can be configured in any IDE to build Royale applications.

Building the framework is quite straight-forward. All you need to do, is run the
following command:
(run it in the royale-asjs repo)

----
mvn clean install
----

As compiling the examples takes quite a while, you have to enable the building
of examples by activating the `build-examples` profile:
(run it in the royale-asjs repo)

----
mvn clean install -P build-examples
----

Building the distribution also takes a little while, so it is also not built in
the default profile. In order to build the distribution, run the following build:
(run it in the royale-asjs repo)

----
mvn clean install -P build-distribution
----

However this doesn't automatically build the directory distribution. It builds
a zip and a tar.gz version of the Royale SDK, without any of the Adobe dependencies.
This is the part that produces package usable by IDEs.

If you want to have a Royale SDK (including Air, Flash, Fontkit, etc.) you need to
tell the build where to put it by providing a property to the build:
(run it in the royale-asjs repo)

----
mvn clean install -P build-distribution -DdistributionTargetFolder={some directory}
----

If you want to build everything:
(run it in the royale-asjs repo)

----
mvn clean install -P build-examples,build-distribution -DdistributionTargetFolder={some directory}
----