Set up your development environment

Before you can build the Flex SDK from source code and then test it, you'll need to do some one-time setup. In addition to the source code, which you check out from the repository with a Subversion client, you'll need to

• have an appropriate command-line shell
• have a Java Development Kit (JDK)
• have Apache Ant
• set certain environment variables
• configure the Flash Player

You can build and test the Flex SDK on Windows, Macintosh, or Linux. You should be aware, however, that the official builds of the Flex SDK are done on a Windows machine using specific versions of the Java Development Kit and Apache Ant as described below. In the future, these versions will vary from branch to branch, so you should be prepared to have multiple versions of the JDK and Ant.

The following sections discuss these requirements in general terms. Links to pages with detailed steps for each OS may be found at the end.

Command-line shell

The Flex SDK is built using command-line tools such as ant and javac, and the tools that get built -- such as mxmlc -- are command-line tools. We're working to provide robust Eclipse and Flex Builder projects for SDK developers to use for debugging the author-time tools and the runtime framework. (Take a look at the projects in /flex/sdk/trunk/development.) However, official builds and tests are always done on the command line.

On Windows you'll need to use Cygwin, which provides a Unix-like command-line environment vastly richer than Command Prompt. Installing Cygwin is required because some of our build scripts use Cygwin tools. The ones we need are part of the default Cygwin installation.

On Macintosh, you'll use the Terminal application that is part of OS X.

Java Development Kit

A JDK contains a Java compiler and a Java runtime environment. Since the Flex SDK's author-time command-line tools are written using Java 5, you need a JDK 1.5 or later to compile and run them. (Note that you may need a different version of the JDK than the latest available; more information on getting an appropriate version can be found in the "Detailed steps" section below.)

On Windows, the command line executables (e.g. mxmlc.exe, compc.exe) are 32-bit processes, so a 32-bit version of Java must also be used to run them.

Apache Ant

We use Apache Ant, an open-source Java-based build system, to build the Flex SDK. Various directories inside the Flex SDK have build.xml files, which are Ant scripts written in XML format.

Environment variables

There are three environment variables -- JAVA_HOME, ANT_HOME, and PATH -- which must be properly set before the Flex SDK can be built, tested, and used. (Note that the setup.sh shell script discussed in a later section will set these up for you; they are documented here mainly for completeness and informational purposes.)

JAVA_HOME

This must point to the JDK directory, which should contain bin and lib directories.

ANT_HOME

This must point to the Ant directory, which should contain bin and lib directories.

PATH

The following three directories should be at the beginning of the PATH:

• the bin directory of the Flex SDK branch that you're using
• Ant's bin directory, $ANT_HOME/bin
• Java's bin directory, $JAVA_HOME/bin

This will allow command-line tools such as mxmlc, ant, and java to be found no matter what your current directory is.

Branch-setup scripts

If you build multiple branches of the Flex SDK, you want to be sure that the right version of mxmlc and other SDK tools are found on your PATH. Otherwise, you might accidentally compile with the Flex 3 compiler at branches/3.x/bin/mxmlc instead of the Flex 4 compiler at trunk/bin/mxmlc, for example.

Furthermore, in the near future we'll start using updated versions of Java and Ant on the trunk, so that Flex 4 is built with a current toolset (probably Java 5 and Ant 1.7).

Therefore the best strategy for ensuring that these three environment variables are properly set is to use the shell script setup.sh that we provide in the root of each branch. This script sets the environment variables JAVA_HOME, ANT_HOME, and PATH appropriately for building, testing, and developing with that particular branch. It ensures that the right version of Java and Ant are used and that when you invoke a Flex SDK tool such as mxmlc, the right copy of that tool is executed.

To use these scripts, do (for example)

cd flex/sdk/trunk
source setup.sh

Note: You must run this script with the source command (or with the shorthand "dot" syntax, i.e., ". setup.sh"); simply executing the script file instead will not work because the state of certain variables set in the shell script will not persist when the script is finished running.

Each setup.sh script assume that Java and Ant are installed at standard locations in your system. If you've placed them elsewhere, edit the paths.

If you're a shell hacker, you can set up simple shell aliases such as ft (for "Flex trunk") that cd to a directory and source its setup.sh script.

Note: The 3.0.0.477 release was tagged as tags/3.0.0.477 before the branch-setup scripts were added to trunk and branches/3.x. If you want to build this tag, copy branches/3.x/setup.sh to tags/3.0.0.477/setup.sh first.

Flash Player

Testing the Flex SDK involves running test applications in the standalone Flash Player. Development use of the Flash Player you to configure the mm.cfg file and the FlashPlayerTrust directory. See the "Detailed steps" section below for more information.

mm.cfg

This file lets you configure the debugging capabilities of the Flash Player. To test the SDK, you must specify

TraceOutputFileEnable=1

in the mm.cfg file so that trace() output is directed to the flashlog.txt file. You should also specify

ErrorReportingEnable=1

so that runtime errors are logged. See the detailed steps for information about where the mm.cfg file is located.

FlashPlayerTrust

This directory lets you configure aspects of Flash Player security. By default, an executing SWF can't access local files such as the images in the test apps. To allow this, you must create a "trust file" that grants this privilege to SWFs. See the detailed steps for more information.

Detailed steps

Please refer to the platform-specific steps documented below for setup on each OS; they detail the information you will need to get everything set up:

• Setup on Windows
• Setup on Macintosh
• Setup on Linux