flex-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From cd...@apache.org
Subject git commit: [flex-falcon] [refs/heads/develop] - - Updated the documentation for the maven build
Date Tue, 26 Jul 2016 07:10:59 GMT
Repository: flex-falcon
Updated Branches:
  refs/heads/develop b4a73e9fc -> 773dc1118


- Updated the documentation for the maven build


Project: http://git-wip-us.apache.org/repos/asf/flex-falcon/repo
Commit: http://git-wip-us.apache.org/repos/asf/flex-falcon/commit/773dc111
Tree: http://git-wip-us.apache.org/repos/asf/flex-falcon/tree/773dc111
Diff: http://git-wip-us.apache.org/repos/asf/flex-falcon/diff/773dc111

Branch: refs/heads/develop
Commit: 773dc11180c46eca6d3373f34c1440256b70db92
Parents: b4a73e9
Author: Christofer Dutz <christofer.dutz@codecentric.de>
Authored: Tue Jul 26 09:10:52 2016 +0200
Committer: Christofer Dutz <christofer.dutz@codecentric.de>
Committed: Tue Jul 26 09:10:52 2016 +0200

----------------------------------------------------------------------
 README_MAVEN.txt             |   7 +-
 src/site/asciidoc/build.adoc | 192 +++++++++++++++++++++++++++++++++-----
 2 files changed, 169 insertions(+), 30 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/flex-falcon/blob/773dc111/README_MAVEN.txt
----------------------------------------------------------------------
diff --git a/README_MAVEN.txt b/README_MAVEN.txt
index 8443655..3db5bc9 100644
--- a/README_MAVEN.txt
+++ b/README_MAVEN.txt
@@ -1,13 +1,10 @@
 In order to build falcon with Maven you need to perform the following steps:
 
-0. Get Maven (http://maven.apache.org) and unpack it somewhere.
+1. Get Maven (http://maven.apache.org) and unpack it somewhere.
     This directory is now "MAVEN_HOME". Now make sure MAVEN_HOME/bin
     is on your systems path.
 
-1. Make sure you have the following environment variables set:
-
-2. Run the migrate-to-maven.sh (This converts the projects directory structure to a typical
maven structure)
-    NOTE FOR WINDOWS USERS: tun the script using gitbash
+2. Make sure you have the following environment variables set:
 
 3. Build the parts needed by the build
     mvn install -P utils

http://git-wip-us.apache.org/repos/asf/flex-falcon/blob/773dc111/src/site/asciidoc/build.adoc
----------------------------------------------------------------------
diff --git a/src/site/asciidoc/build.adoc b/src/site/asciidoc/build.adoc
index 194c3ac..594f6c4 100644
--- a/src/site/asciidoc/build.adoc
+++ b/src/site/asciidoc/build.adoc
@@ -35,10 +35,17 @@ Make sure the following environment variable is set to the exact location
of the
 FLASHPLAYER_DEBUGGER={Absolute path to the executable}
 ----
 
-If you are using the commandline you need to make sure the following environment variables
is set:
+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:
@@ -70,48 +77,126 @@ PATH=${PATH}:${JAVA_HOME}/bin;${MAVEN_HOME}/bin
 
 == Building FlexJS
 
-Currently you need to run 3 build in order to build all the parts
-of FlexJS. This is due to the fact that in order to build the
-Compiler and the other parts, we need some tools prior to building
-those parts. After having released these parts for the first time,
-we will no longer require this first build step. The second build
-builds the compiler. The third build is currently needed as we are
-having some classloading issues, that prevent us from using the compiler
-we built as part of the build process, I am expecting this to become
-obsolete soon.
+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 Build-Tools
 
 The following command will take care of building the prerequisites:
+(run it in the flex-falcon repo)
 
 ----
-mvn clean install -P minimal
+mvn clean install -P utils
 ----
 
 === Building the Compiler
 
-The compiler block is the main part of the build. It 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:
+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 -P compiler -DskipTests
+mvn clean install -DskipTests
 ----
 
-If you want to build and run the tests, just omit the `-DskipTests`:
+If you want to run the unittests, but skip the integrationtests:
+(run it in the flex-falcon repo)
 
 ----
-mvn clean install -P compiler
+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 -P compiler
+mvn site
 ----
 
 This will create the documentation for each module inside the corresponding
@@ -120,22 +205,79 @@ root project, the links to the sub-modules will not work as the local
directory
 structure differs from the strucure the deployed deocumentation 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 -P compiler
+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 -P compiler
+mvn clean install site site:stage
 ----
 
-=== Building the externs
+=== 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}
+----
 
-Building the externs is quite straight-forward. All you need to do, is run the
-folloging command:
+If you want to build everything:
+(run it in the flex-asjs repo)
 
 ----
-mvn clean install -P externs
+mvn clean install -P build-examples,build-distribution -DdistributionTargetFolder={some directory}
 ----


Mime
View raw message