| //// |
| |
| 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} |
| ---- |