installer/README

<!--

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.

-->

==========================================================================================
Overview:
=========

- The Apache Flex SDK Installer AIR application provides an easy, installation of the 
  Apache Flex SDK and all its dependencies.  This will make it suitable for working with 
  IDEs such as Adobe Flash Builder, FDT, IntelliJ IDEA, FlashDevelop, etc.  
  The application downloads the following dependencies:
    - The AIR sdk (Windows vs. Mac) based on the current platform
    - Adobe Flash Player playerglobal.swc
    - SwfObject
    - Open Source Media Framework (OSMF)
	 
  Optionally, the application will download these files if the user explicitly agrees to 
  the licensing terms:
    - Adobe BlazeDS
     - Adobe embedded font support
 
    All the file names and urls of the downloaded files are available in 
    installer/src/installer/sdk-installer-config-3.0.xml. 
    When the dependencies file names or urls change in future, update the 
    sdk-installer-config-3.0.xml to ensure that the application works correctly.
    
- The application uses http://flex.apache.org/single-mirror-url.cgi to determine
  the preferred mirror url to download the Apache Flex SDK binary from.
  
- Once the Apache Flex SDK binary file is downloaded, a MD5 hash is generated for it.  
  This hash is compared with the hash from the Apache Flex SDK release site.  
  If they match, we verify that the downloaded binary file is a valid Apache release and 
  proceed to unzip the file.  
	
- The Adobe AIR SDK will be downloaded and the relevant files are copied to the required 
  locations.
  
- The Adobe Flash Player playerglobal.swc file and the config files are placed in the 
  required locations.
  
- Then the rest of the external dependencies and the optional files (if selected by user) 
  are downloaded and copied into the appropriate locations.  

- From the 2.6 version, you can select the version of Adobe Flash Player and Adobe AIR SDK
  the installer downloads.

- From the 2.5 version, by default, Apache Flex SDK Installer 2.5 downloads Adobe Flash 
  Player 11.1 and Adobe AIR SDK 3.4. 
  If you want to change it to any other supported combination, you save a copy of the 
  config file found at: http://flex.apache.org/installer/sdk-installer-config-3.0.xml, 
  modify the download urls to point to the required versions.  Then run the app from 
  command line mode with the optional command line parameter: -config=<path to config file>

- If building the app for Linux, open InstallApacheFlex-app.xml and change the Adobe AIR 
  namespace from http://ns.adobe.com/air/application/3.4 to 
  http://ns.adobe.com/air/application/2.6  This is because AIR 2.6 is the latest available 
  version on Linux.  
	
==========================================================================================
How to build the installer using ANT (no Flash Builder or any other IDE required):
==========================================================================================

1.  Unzip the source distribution.  You should see the 'installer' directory and the 
    'common' directory in the root.
            
2.  In the installer directory, run:
        ant build [-DFLEX_HOME=/path/to/apache/flex/sdk] [-DAIR_HOME=/path/to/air/sdk]
        
    FLEX_HOME is the absolute path to the Apache Flex SDK
        If you omit this argument, and the system environment variable, FLEX_HOME exists,
        it is used.  Otherwise, the FLEX_HOME_MAC or FLEX_HOME_WIN property in 
        installer/build.properties is used.
        
    AIR_HOME is the absolute path to the Adobe AIR SDK
        If you omit this argument, and the system environment variable, AIR_HOME exists,
        it is used.  Otherwise, the AIR_HOME_MAC or AIR_HOME_WIN property in 
        installer/build.properties is used.
          	
2.  The installer executable file created in the installer/release directory.  If you are 
    on Windows, you will see an .exe file; if you are on Mac OS, you will see a .dmg file.  
	A temporary digital signing certificate - temp.p12 will be created in the installer 
	directory as well.  The password for this file is available in the build.properties 
	file (var: TEMP_PASS_CHANGE_THIS)

==========================================================================================
How to set up the project for working with Adobe Flash Builder (or any other IDE):
==========================================================================================

1.  Unzip the source distribution.  You should see the 'installer' directory and the 
    'common' directory in the root.

2.  In the installer directory run: 
        ant get-as3commons.swc
    This step downloads the required as3commons library and saves it in the libs 
    directory.

3.  If using Adobe Flash Builder, add a linked resource called: 
        APACHE_FLEX_UTILITIES_ROOT 
    and point it to the directory path where the 'installer' and 'common' directories are 
    located.

4.  In the installer project, add ${APACHE_FLEX_UTILITIES_ROOT}/common/src as a source path.