Macromedia Flex - 4.0 User Guide

Using

ADOBE® FLEX® 4

COMPILER API

Last updated 3/19/2010

Copyright

© 2010 Adobe Systems Incorporated. All rights reserved.
Adobe® Flex® 4 Compiler API.

This guide is protected under copyright law, furnished for informational use only, is subject to change without notice, and should not be construed as a
commitment by Adobe Systems Incorporated. Adobe Systems Incorporated assumes no responsibility or liability for any errors or inaccuracies that may appear
in the informational content contained in this guide.

This guide is licensed for use under the terms of the Creative Commons Attribution Non-Commercial 3.0 License. This License allows users to copy, distribute,
and transmit the guide for noncommercial purposes only so long as (1) proper attribution to Adobe is given as the owner of the guide; and (2) any reuse or
distribution of the guide contains a notice that use of the guide is governed by these terms. The best way to provide notice is to include the following link. To
view a copy of this license, visit

Adobe, the Adobe logo, Flex, and Flash Builder are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States and/or other
countries.

ActiveX and Windows are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries. Java is a trademark
or registered trademark of Sun Microsystems, Inc. in the United States and other countries. All other trademarks are the property of their respective owners.

Updated Information/Additional Third Party Code Information available at http://www.adobe.com/go/thirdparty

Portions include software under the following terms:

This product contains either BISAFE and/or TIPEM software by RSA Data Security, Inc.

Adobe Systems Incorporated, 345 Park Avenue, San Jose, CA 95110-2704, USA.

Notice to U.S. government end users. The software and documentation are “Commercial Items,” as that term is defined at 48 C.F.R. §2.101, consisting of
“Commercial Computer Software” and “Commercial Computer Software Documentation,” as such terms are used in 48 C.F.R. §12.212 or 48 C.F.R. §227.7202,
as applicable. Consistent with 48 C.F.R. §12.212 or 48 C.F.R. §§227.7202-1 through 227.7202-4, as applicable, the Commercial Computer Software and
Commercial Computer Software Documentation are being licensed to U.S. Government end users (a) only as Commercial items and (b) with only those rights
as are granted to all other end users pursuant to the terms and conditions herein. Unpublished-rights reserved under the copyright laws of the United States. For
U.S. Government End Users, Adobe agrees to comply with all applicable equal opportunity laws including, if appropriate, the provisions of Executive Order
11246, as amended, Section 402 of the Vietnam Era Veterans Readjustment Assistance Act of 1974 (38 USC 4212), and Section 503 of the Rehabilitation Act of
1973, as amended, and the regulations at 41 CFR Parts 60-1 through 60-60, 60-250 ,and 60-741. The affirmative action clause and regulations contained in the
preceding sentence shall be incorporated by reference.

http://creativecommons.org/licenses/by-nc-sa/3.0/

Last updated 3/19/2010

Contents

Chapter 1: Introduction

About the Flex compiler API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Quick Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Configuring the compiler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

Adding assets to applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Chapter 2: Logging and Reports

Using custom logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Creating reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Watching progress . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Chapter 3: Libraries and Projects

Creating libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Creating projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Chapter 4: Creating Dynamic Applications

About the creation of dynamic applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Using custom components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Using incremental compilation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

iii

Last updated 3/19/2010

Chapter 1: Introduction

The Quick Start section contains a full example to get you started using the Adobe® Flex® compiler API.

About the Flex compiler API

The Flex compiler API lets you compile Flex applications from Java applications. You can also create Flex applications
in memory and compile them to SWF files without ever having an MXML file on disk. In addition, the compiler API
lets you output linkage reports and other details about your applications.

You can also create project files and libraries with the compiler API. Libraries are SWC files that define a set of
components for use in your application, theme files, or Runtime Shared Libraries (RSLs). Projects combine Flex
applications and libraries. They let you enforce dependencies between a Flex application and its assets in the
compilation process.

Requirements of the compiler API

The Flex compiler API has the following requirements:

1

Java JDK The compiler API requires that you have the Java interpreter and the javac compiler from JDK version 1.4.2

or later.

Flex SDK The compiler API is not a stand-alone product. It requires the Flex SDK or the SDK included with Flash

Builder.

What’s included

The Flex compiler API includes the following resources:

flex-compiler-oem.jar The flex2.tools.oem.* package used by the compiler API. This JAR file is in the SDK’s lib

directory. For Flash Builder, this JAR file is in the sdks/4.0.0/lib directory.

JavaDocs The API documentation for the public classes and interfaces in the flex2.tools.oem.* package. You can

download the JavaDoc for the compiler API from the

flex_compiler_api_guide.pdf The Flex 4 Compiler API User Guide is a PDF that provides usage documentation for

the compiler API.

Flex doc blog site.

Quick Start

The following example describes how to create a simple Java application that compiles a Flex application.

Create and compile a new application with the compiler API

1 Create a Java application; for example, MyAppCompiler.java:

Last updated 3/19/2010

// java/MyAppCompiler.java
import flex2.tools.oem.Application;
import java.io.*;

public class MyAppCompiler {
public static void main(String[] args) {
try {
Application application = new Application(new File("../apps/TestApp.mxml"));
application.setOutput(new File("../apps/TestApp.swf"));
long result = application.build(true);
if (result > 0) {
System.out.println("COMPILE OK");
} else {
System.out.println("COMPILE FAILED");
}
} catch (Exception ex) {
ex.printStackTrace();
}
}
}

FLEX 4 COMPILER API

Introduction

In this file, ensure that you do the following:

2

a Create an Application object.

b Specify an output file for the new Application object.

c Call the Application.build() method.

d Check for a value greater than 0 returned by the build() method.

2 Compile the class with your Java compiler; for example:

C:\myapps\src>javac -classpath c:\flex\lib\flex-compiler-oem.jar MyAppCompiler.java

Ensure that you add the flex-compiler-oem.jar to your Java classpath.

3 Create an MXML file and store it in the location you specified with the File constructor in your Java application;

for example, create a file named TestApp.mxml in the myapps\apps directory:

<?xml version="1.0"?>
<!-- oem_kit\apps\TestApp.mxml -->
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx">
<s:Label text="Hello World"/>
</s:Application>

4 Run the new application compiler with your Java interpreter; for example:

C:\myapps\src>java -classpath c:\flex\lib\flex-compiler-oem.jar;. MyAppCompiler

Ensure that you add the flex-compiler-oem.jar, and the current directory, to your Java classpath.

You can set configuration options in your Java application by using the Configuration class’s methods. The following
example enables the ActionScript optimizer and disables compiler warnings:

Last updated 3/19/2010

// java/MyConfiguringCompiler.java
import flex2.tools.oem.Application;
import flex2.tools.oem.Configuration;
import java.io.*;

public class MyConfiguringCompiler {
public static void main(String[] args) {
String outputRoot = "../apps/";

try {
Application application = new Application(new
File(outputRoot, "ErrorTestApp.mxml"));
application.setOutput(new File(outputRoot, "ErrorTestApp.swf"));

Configuration config = application.getDefaultConfiguration();

// Enable ActionScript optimizer.
config.optimize(true);

// Disable warnings.
config.showActionScriptWarnings(false);
config.showBindingWarnings(false);
config.showUnusedTypeSelectorWarnings(false);

// Apply the new configuration to the Application.
application.setConfiguration(config);

long result = application.build(true);
if (result > 0) {
System.out.println("COMPILE OK");
} else {
System.out.println("COMPILE FAILED");
}
} catch (Exception ex) {
ex.printStackTrace();
}
}
}

FLEX 4 COMPILER API

Introduction

3

To compile applications with some advanced features, you must pass a valid Flash Builder Premier license key to your
application. You can do this with the Configuration class’s

setLicense() method. The following example sets the

license key prior to launching the compiler:

Last updated 3/19/2010

// java/MyDataVisAppCompiler.java
import flex2.tools.oem.Application;
import flex2.tools.oem.Configuration;
import java.io.*;

public class MyDataVisAppCompiler {
public static void main(String[] args) {
try {
Application application = new Application(new
File("../apps/DataVisTestApp.mxml"));
application.setOutput(new File("../apps/DataVisTestApp.swf"));

// Get an instance of the default configuration class.
Configuration config = application.getDefaultConfiguration();

// Replace this with a valid license key.
config.setLicense("flashbuilder4", "0000-0000-0000-0000-0000-0000");

// Apply the new configuration to the Application.
application.setConfiguration(config);

long result = application.build(true);

if (result > 0) {
System.out.println("COMPILE OK");
} else {
System.out.println("COMPILE FAILED");
}
} catch (Exception ex) {
ex.printStackTrace();
}
}
}

FLEX 4 COMPILER API

4

Introduction

Configuring the compiler

You can pass configuration options to the compiler when using the compiler API. To do this, you get an instance of
the Configuration class using the Application or Library classes’s
options on that instance, and then assign that object to the Application or Library by using the
method.

For most compiler options, there is a 1:1 mapping between the flex2.tools.oem.Configuration API methods and the
compiler options. For example, to set the value of the

true to the Configuration class’s keepCompilerGeneratedActionScript() method:

pass

config.keepCompilerGeneratedActionScript(true);

keep-generated-actionscript compiler option to true, you

Some compiler options, such as source-path and library-path, can use the += operator to append entries to the
source path and library path. For these compiler options, you can replace the entire path using the

setLibraryPath() methods, or you can append new entries to the list with the addSourcePath() and

and

addLibraryPath() methods.

getDefaultConfiguration() method, set the

setConfiguration()

setSourcePath()

Last updated 3/19/2010

FLEX 4 COMPILER API

Introduction

In some cases, the Configuration class does not have a method that maps to a compiler option. You might call a
method of a different class, or call multiple methods. For example, there is no method in the compiler API that enables
and disables all warnings as per the

showBindingWarnings(), showShadowedDeviceFontWarnings(), and showUnusedTypeSelectorWarnings()

warnings compiler option. Instead, you call the showActionScriptWarnings(),

methods.

The following table lists the compiler options that have alternative methods for setting their values:

Compiler option Equivalent compiler API method or methods

5

dump-config

include-classes

include-file

include-namespaces

include-sources

library-path

link-report

output

resource-bundle-list

source-path

version

warnings

Call the Configuration.keepConfigurationReport(true) method and then the

Report.writeConfigurationReport() method.

Call the Library.addComponent(java.lang.String) method.

Call the Library.addArchiveFile() method.

Call the Library.addComponent(java.net.URI) method.

Call the Library.addComponent(VirtualLocalFile) or

Library.addComponent(java.io.File) method.

Call the Configuration.setLibraryPath() method to replace the value of the default source
path. Call the
source path.

Call the Configuration.keepLinkReport(true) method, then the

Report.writeLinkReport() method.

Call the Application.setOutput() and Library.setOutput()/setDirectory() methods.

Call the Report.getResourceBundleNames() method.

Call the Configuration.setSourcePath() method to replace the value of the default source
path. Call the
source path.

Call the Report.getCompilerVersion() method.

Call the showActionScriptWarnings(), showBindingWarnings(),

showShadowedDeviceFontWarnings(), and showUnusedTypeSelectorWarnings()

methods.

Configuration.addLibraryPath() method to append new values to the default

Configuration.addSourcePath() method to append new values to the default

About option and property precedence

Similar to mxmlc and compc, the default configuration that the compiler API uses is the flex-config.xml file. For
compiling applications, the compiler API also uses local configuration files. The compiler API then applies the
configuration options in flex2.tools.oem.Configuration to create the final set of compiler configuration options.

By default, the compiler invoked by the compiler API populates the default Configuration object with options in the
flex-config.xml file. This file’s location is relative to the location of the mxmlc.jar file. In most cases, this file is in the
SDK’s lib directory, which is the same directory that contains the flex-compiler-oem.jar file. The compiler also uses
local configuration files (such as app_name-config.xml), or you can point to the location of another configuration file
using the Configuration class’s

Configuration options that you set with the compiler API have the same precedence as a command-line compiler
option. This means that they take precedence over all other options (flex-config.xml, alternative configuration file, and
local configuration file).

For more information about using configuration files, see Using Adobe Flex 4.

addConfiguration() method.

Last updated 3/19/2010

FLEX 4 COMPILER API

Introduction

Clearing configurations

You can clear a configuration by calling the Application.setConguration(null) method.

Adding assets to applications

You can add assets to the application by using methods of the Configuration class, such as addExterns(),

addIncludes(), and setTheme(). Using these methods, you can add external themes, libraries, classes, RSLs, and

other types of assets.

The following example uses the Configuration class’s setTheme() method to add several themes to the resulting
application:

// java/MyThemeCompiler.java
import flex2.tools.oem.Application;
import flex2.tools.oem.Configuration;
import java.io.*;

public class MyThemeCompiler {
public static void main(String[] args) {
String assetRoot = "../assets/";
String outputRoot = "../apps/";
String frameworksRoot = "c:/p4/flex/flex/sdk/frameworks";

try {
File[] fileArray = new File[3];
fileArray[0] = new File(frameworksRoot, "libs/spark.swc");
fileArray[1] = new File(assetRoot, "myTheme.css");
fileArray[2] = new File(assetRoot, "myTheme2.css");

Application application = new Application(new File(outputRoot,
"TestAppWithAssets.mxml"));
application.setOutput(new File(outputRoot, "TestAppWithAssets.swf"));

Configuration config = application.getDefaultConfiguration();
config.setTheme(fileArray);
application.setConfiguration(config);

long result = application.build(true);
if (result > 0) {
System.out.println("COMPILE OK");
} else {
System.out.println("COMPILE FAILED");
}
} catch (Exception ex) {
ex.printStackTrace();
}
}
}

6

To add a SWC file that contains components, use the addLibraryPath() method. In the following example, the assets
directory contains the MyComponents.swc file: