src/site/asciidoc/build.adoc - royale-compiler - Git at Google

 ////

   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 FlexJS from source

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

 == Prerequisites

 In order to build FlexJS 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 FlexJS

 Currently you need to checkout and run builds in 3 different repositories.
 This is due to the fact that every part of the FlexJS 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 FlexJS. 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 flex-falcon 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 flex-falcon repo)

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

 If you want to run the unittests, but skip the integrationtests:
 (run it in the flex-falcon 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 flex-falcon 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 flex-falcon repo)

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

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

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

 === Building the typedefs

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

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

 ----
 mvn clean install
 ----

 === Building the framework

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

 Building the framework is quite straight-forward. All you need to do, is run the
 following command:
 (run it in the flex-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 flex-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 flex-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 FlexJS SDK, without any of the Adobe dependencies.
 This is the part that is for example used by the Flex Installer to install a
 local FDK.

 If you want to have a FlexJS 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 flex-asjs repo)

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

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

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

	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 FlexJS from source

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

	== Prerequisites

	In order to build FlexJS 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 FlexJS

	Currently you need to checkout and run builds in 3 different repositories.
	This is due to the fact that every part of the FlexJS 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 FlexJS. 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 flex-falcon 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 flex-falcon repo)

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

	If you want to run the unittests, but skip the integrationtests:
	(run it in the flex-falcon 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 flex-falcon 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 flex-falcon repo)

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

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

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

	=== Building the typedefs

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

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

	----
	mvn clean install
	----

	=== Building the framework

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

	Building the framework is quite straight-forward. All you need to do, is run the
	following command:
	(run it in the flex-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 flex-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 flex-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 FlexJS SDK, without any of the Adobe dependencies.
	This is the part that is for example used by the Flex Installer to install a
	local FDK.

	If you want to have a FlexJS 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 flex-asjs repo)

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

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

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