The application compilers create SWF files that are run in an Adobe™ Flash^® Player client or in an Adobe AIR™ application. The client can be a stand-alone Flash Player or a Flash Player in a browser, which takes the form of an ActiveX control for Microsoft Internet Explorer or a plug-in for Netscape-based browsers.

The mxmlc command-line compiler

You open the mxmlc compiler from the command line to create a SWF file that you then deploy to a website. Typically, you pass the name of the application's root MXML file to the compiler. The output is a SWF file. For more information, see Using the mxmlc application compiler.

The mxmlc compiler options are described in About the application compiler options.

You can compile applications that are written entirely in ActionScript and contain no MXML using the mxmlc compiler.

You use the component compiler to generate a SWC file from component source files and other asset files such as images and style sheets. A SWC file is an archive of components and other assets. For more information about SWC files, see About SWC files.

In some ways, the component compiler is similar to the application compiler. The application compiler produces a SWF file from one or more MXML and ActionScript files; the component compiler produces a SWC file from its input files. SWC files are compressed files that contain a SWF file (library.swf), asset files, and a catalog.xml file.

You use the component compiler to create the following kinds of assets:

Component libraries

Component libraries are SWC files that contain one or more components that are used by applications. SWC files also contain the namespace information that describe the contents of the SWC file. For more information about component libraries, see About SWC files.

Runtime shared libraries (RSLs)

RSLs are external shared assets that can be separately downloaded and cached on the client. These shared assets are loaded by any number of applications at run time. For more information on RSLs, see Runtime Shared Libraries.

Themes

Themes are a combination of skins and Cascading Style Sheets (CSS). You use themes to define the look and feel of an application built with Flex. For more information on themes, see Styles and themes.

You use the component compiler in the following ways:

The compc command-line compiler

You open the compc compiler from the command line to create a SWC file. For more information, see Using the compc component compiler.

The component compiler has many of the same options as the application compilers, as described in About the application compiler options. The component compiler has additional options as described in About the component compiler options.

Like the application compiler, you can use the load-config option to point the component compiler to a configuration file, rather than specify command-line options or set the options in the Flex Compiler dialog box.

When you compile a SWC file, store the new file in a location that is not the same as the source files. If both sets of files are accessible by Flex when you compile your application, unexpected behavior can occur.

The SWC files that are produced by the component compilers do not require an HTML wrapper because they are used as themes, RSLs, or component libraries that are input to other compilers to create applications. You never deploy a SWC file that users can request directly.

The mxmlc and compc compilers take many options. The options are listed in the help which you can view with the help option, as the following example shows:

 mxmlc -help

This displays a menu of choices for getting help. The most common choice is to list the basic configuration options:

 mxmlc -help list

To see advanced options, use the list advanced option, as the following example shows:

 mxmlc -help list advanced

To see a list of entries whose names or descriptions include a particular String, use the following syntax:

 mxmlc -help pattern 

The following example returns descriptions for the external-library-path, library-path, and runtime-shared-libraries options:

 mxmlc -help list library

For a complete description of mxmlc options, see About the application compiler options. For a complete description of compc options, see About the component compiler options.

Many command-line options, such as show-actionscript-warnings and accessible, have true and false values. You specify these values by using the following syntax:

 mxmlc -accessible=true -show-actionscript-warnings=true

Some options, such as source-path, take a list of one or more options. You can see which options take a list by examining the help output. Square brackets ([ ]) that surround options indicate that the option can take a list of one or more parameters.

You can separate each entry in a list with a space or a comma. The syntax is as follows:

 -var val1 val2

or

 -var=val1, val2

If you do not use commas to separate entries, you terminate a list by using a double hyphen, as the following example shows:

 -var val1 val2 -- -next_option 

If you use commas to separate entries, you terminate a list by not using a comma after the last entry, as the following example shows:

 -var=val1, val2 -next_option 

You can append values to an option using the += operator. This adds the new entry to the end of the list of existing entries rather than replacing the existing entries. The following example adds the c:/myfiles directory to the library-path option:

 mxmlc -library-path+=c:/myfiles

In some cases, the command-line help shows an option with dot-notation syntax; for example, source-path is shown as compiler.source-path. This notation indicates how you would set this option in a configuration file. On the command line, you can specify the option with only the final node, source-path, as long as that node is unique, as the following example shows:

 mxmlc -source-path . c:/myclasses/ -- foo.mxml

For more information about using configuration files to store command-line options, see About configuration files.

Some compiler options have aliases. Aliases provide shortened variations of the option name to make command lines more readable and less verbose. For example, the alias for the output option is o. You can view a list of options by their aliases by using the following command:

 mxmlc -help list aliases

or

 mxmlc -help list advanced aliases

You can also see the aliases in the verbose help output by using the following command:

 mxmlc -help list details

Flex provides a simple interface to the command-line compilers. For UNIX users, there is a shell script. For Windows users, there is an executable file. These files are located in the bin directory. You can also invoke the compilers using Java. This lets you integrate the compilers into Java-based projects (such as Ant) or other utilities.

The shell scripts and executable files for the command-line compilers wrap calls to the mxmlc.jar and compc.jar JAR files. To invoke the compilers from Java, you call the JAR files directly. For Flex SDK, the JAR files are located in the flex_install_dir/lib directory.

To invoke a command in a JAR file, use the java command from the command line and specify the JAR file you want to execute with the jar option. You must also specify the value of the +flexlib option. This advanced option lets you set the root directory that is used by the compiler to locate the flex-config.xml file, among other files. You typically point it to your frameworks directory. From there, the compiler can detect the location of other configuration files.

The following example compiles MyApp.mxml into a SWF file using the JAR file to invoke the mxmlc compiler:

 java -jar ../lib/mxmlc.jar +flexlib c:/flex_4_sdk/frameworks c:/flex/MyApp.mxml

You pass all other options as you would when you open the command-line compilers. The following example sets the locale and source path when compiling MyApp:

 java -jar ../lib/mxmlc.jar +flexlib c:/flex_4_sdk/frameworks -locale en_US -source-path locale/{locale} c:/flex/MyApp.mxml

You can specify the location of a configuration file by using the load-config option. The target configuration file can be the default flex-config.xml file, or it can be a custom configuration file. The following example loads a custom configuration file:

 compc -load-config=myconfig.xml

If you specify the filename with the += operator, your loaded configuration file is used in addition to and not instead of the flex-config.xml file:

 compc -load-config+=myconfig.xml

With the mxmlc compiler, you can also use a local configuration file. A local configuration file does not require you to point to it on the command line. Rather, Flex examines the same directory as the target MXML file for a configuration file with the same name (one that matches the filename-config.xml filename). If it finds a file, it uses it in conjunction with the flex-config.xml file. You can also specify a configuration file by using the load-config option with the += operator.

For example, if your application's top-level file is called MyApp.mxml, the compiler first checks for a MyApp-config.xml file for configuration settings. With this feature, you can easily compile multiple applications using different configuration options without changing your command-line options or your flex-config.xml file.

Options in the local configuration file take precedence over options set in the flex-config.xml file. Options set in a configuration file that the load-config option specify take precedence over the local configuration file. Command-line settings take precedence over all configuration file settings. For more information on the precedence of compiler options, see About option precedence.

You store values in a configuration file in XML blocks, which follow a specific syntax. In general, the tags you use match the command-line options.

The following table describes the application compiler options. You invoke the application compiler with the mxmlc command-line utility.

accessible=true|false

actionscript-file-encoding string

advanced

mxmlc -help advanced

allow-source-path-overlap=true|false

as3=true|false

benchmark=true|false

context-root context-path

contributor name

creator name

date text

debug=true|false

debug-password string

default-frame-rate int

default-script-limits max-recursion-depth max-execution-time

default-size width height 

defaults-css-files filename [, ...]

defaults-css-url string

define=NAMESPACE::variable,value

-define=CONFIG::debugging,true

CONFIG::debugging {// Execute debugging code here.}

description text

dump-config filename

mxmlc -dump-config myapp-config.xml

es=true|false

externs class_name [...]

external-library-path path-element [...]

fonts.advanced-anti-aliasing=true|false

fonts.languages.language-range lang range 

fonts.local-fonts-snapshot path_to_file

fonts.managers manager-class [...] 

fonts.max-cached-fonts string

fonts.max-glyphs-per-face string

frames.frame=label,class_name[,...]

-frame=MyLabel,Class1,Class2

generate-frame-loader=true|false

headless-server=true|false

System.setProperty("java.awt.headless", "true")

help [-list [advanced]]

help -list advanced

compc -include-classes mx.collections.ListCollectionView 
-include-inheritance-dependencies-only=true 
-source-path . -output lcv2 -directory

include-libraries library [...]

include-resource-bundles bundle [...]

includes class [...]

incremental=true|false

keep-as3-metadata=class_name [...]

keep-generated-actionscript=true|false

language code

library-path path-element [...]

license product_name  license_key

link-report filename

load-config filename

load-externs filename [...]

locale locale[,...]

localized-description text lang

localized-title text lang

mxml.compatibility-version=version

-compatibility-version=3.0.0

namespaces.namespace uri manifest

optimize=true|false

output filename

publisher name

raw-metadata XML_string

resource-bundle-list filename

runtime-shared-libraries rsl-url [...]

runtime-shared-library-path=path-element,rsl-url[,policy-file-url,failover-url,...]

mxmlc -o=../lib/app.swf -runtime-shared-library-path=../lib/mylib.swc,../bin/myrsl.swf Main.mxml

services filename

show-actionscript-warnings=true|false

show-binding-warnings=true|false

show-shadowed-device-font-warnings=true|false

show-unused-type-selector-warnings=true|false

mxmlc -size-report=myreport.xml MyApp.mxml

source-path path-element [...]

static-link-runtime-shared-libraries=true|false

strict=true|false

target-player=major_version[.minor_version.revision]

major_version.minor_version.revision

theme filename [...]

title text

use-network=true|false

use-resource-bundle-metadata=true|false

verbose-stacktraces=true|false

verify-digests=true|false

version

warn-warning_type=true|false

warnings=true|false

The following sections provide examples of using the mxmlc application compiler options on the command line.

The most basic example is one in which the MXML file has no external dependencies (such as components in a SWC file or ActionScript classes) and no special options. In this case, you invoke the mxmlc compiler and point it to your MXML file as the following example shows:

 mxmlc c:/myfiles/app.mxml

The default option is the target file to compile into a SWF file, and it is required to have a value. If you use a space-separated list as part of the options, you can terminate the list with a double hyphen before adding the target file; for example:

 mxmlc -option arg1 arg2 arg3 -- target_file.mxml

The application compilers support adding metadata to SWF files. This metadata can be used by search engines and other utilities to gather information about the SWF file. This metadata represents a subset of the Dublin Core schema.

You can set the following values:

• contributor

• creator

• date

• description

• language

• localized-description

• localized-title

• publisher

• title

For the mxmlc command-line compiler, the default metadata settings in the flex-config.xml file are as follows:

 <metadata> 
 	<title>Flex 4 Application</title> 
 	<description>http://www.adobe.com/products/flex</description> 
 	<publisher>unknown</publisher> 
 	<creator>unknown</creator> 
 	<language>EN</language> 
 </metadata>

You can also set the metadata values as command-line options. The following example sets some of the metadata values:

 mxmlc -language+=klingon -title "checkintest!" 
	-localized-description "it r0x0rs" en-us 
	-localized-description "c'est magnifique!" fr-fr 
	-creator "Flexy Frank" -publisher "Franks Beans" flexstore.mxml

In this example, the following values are compiled into the resulting SWF file:

 <rdf:RDF xmlns:rdf='http://www.w3.org/1999/02/22-rdf-syntax-ns#'> 
 	<rdf:Description rdf:about='' xmlns:dc='http://purl.org/dc/elements/1.1'> 
 		<dc:format>application/x-shockwave-flash</dc:format> 
 		<dc:title>checkintest!</dc:title> 
 		<dc:description> 
 			<rdf:Alt> 
 				<rdf:li xml:lang='fr-fr'>c'est magnifique!</rdf:li> 
 				<rdf:li xml:lang='x-default'>http://www.adobe.com/products/flex</rdf:li> 
 				<rdf:li xml:lang='en-us'>it r0x0rs</rdf:li> 
 			</rdf:Alt> 
 		</dc:description> 
 		<dc:publisher>Franks Beans</dc:publisher> 
 		<dc:creator>Flexy Frank</dc:creator> 
 		<dc:language>EN</dc:language> 
 		<dc:language>klingon</dc:language> 
 		<dc:date>Mar 16, 2010</dc:date> 
 	</rdf:Description> 
 </rdf:RDF>

You use the actionscript-file-encoding option to set the file encoding so that the application compiler correctly interprets ActionScript files. This tag does not affect MXML files because they are XML files that contain an encoding specification in the xml tag.

You use the actionscript-file-encoding option when your ActionScript files do not contain a Byte Order Mark (BOM), and the files use an encoding that is different from the default encoding of your computer. If your ActionScript files contain a BOM, the compiler uses the information in the BOM to determine the file encoding.

For example, if your ActionScript files use Shift_JIS encoding, have no BOM, and your computer uses ISO-8859-1 as the default encoding, you use the actionscript-file-encoding option, as the following example shows:

 actionscript-file-encoding=Shift_JIS

The mxmlc compiler includes options to set the application's frame rate, size, and script limits. By setting them when you compile your application, you do not need to edit the HTML wrapper or the application's MXML file. You can override these settings by using properties of the <s:Application> tag or properties of the <object> and <embed> tags in the HTML wrapper.

The following command-line example sets default application properties:

 mxmlc -default-size 240 240 -default-frame-rate=24 -default-script-limits 5000 10 -- c:/myfiles/flex/misc/MainApp.mxml

For more information about the Application class, see Application containers.

For more information about the HTML wrapper, see Creating a wrapper.

Often, you use SWC files when compiling MXML files. SWC files can provide themes, components, or other helper files. You typically specify SWC files used by the application by using the library-path option.

The following example compiles the RotationApplication.mxml file into the RotationApplication.swf file:

 mxmlc -library-path+=c:/mylibraries/MyButtonSwc.swc c:/myfiles/comptest/testRotation.mxml

In a configuration file, this appears as follows:

 <compiler> 
 	<library-path> 
		<path-element>libs</path-element> 
		<path-element>libs/player</path-element> 
		<path-element>libs/player/{targetPlayerMajorVersion}.{targetPlayerMinorVersion}</path-element> 
		<path-element>locale/{locale}</path-element> 
 		<path-element>c:/mylibraries/MyButtonSwc.swc</path-element> 
 	</library-path> 
 </compiler>

You can use incremental compilation to decrease the time it takes to compile an application or component library with the application compilers. When incremental compilation is enabled, the compiler inspects changes to the bytecode between revisions and only recompiles the section of bytecode that has changed. These sections of bytecode are also referred to as compilation units.

You enable incremental compilation by setting the incremental option to true, as the following example shows:

 mxmlc -incremental=true MyApp.mxml

Incremental compilation means that the compiler inspects your code, determines which parts of the application are affected by your changes, and only recompiles the newer classes and assets. The Flex compilers generate many compilation units that do not change between compilation cycles. It is possible that when you change one part of your application, the change might not have any effect on the bytecode of another.

As part of the incremental compilation process, the compiler generates a cache file that lists the compilation units of your application and information on your application's structure. This file is located in the same directory as the file that you are compiling. For example, if my application is called MyApp.mxml, the cache file is called MyApp.mxml.cache. This file helps the compiler determine which parts of your application must be recompiled. One way to force a complete recompile is to delete the cache file from the directory.

Incremental compilation can help reduce compile time on small applications, but you achieve the biggest gains on larger applications.

For the mxmlc command-line compiler, the default is false.

To include or exclude blocks of code for certain builds, you can use conditional compilation. The mxmlc compiler lets you pass the values of constants to the application at compile time. Commonly, you pass a Boolean that is used to include or exclude a block of code such as debugging or instrumentation code. The following example conditionalizes a block of code by using an inline constant Boolean:

 CONFIG::debugging { 
 	// Execute debugging code here. 
 }

To pass constants, you use the compiler.define compiler option. The constant can be a Boolean, String, or Number, or an expression that can be evaluated in ActionScript at compile time. This constant is then accessible within the application source code as a global constant.

To use the define option, you define a configuration namespace for the constant, a variable name, and a value using the following syntax:

 -define=namespace::variable_name,value

The configuration namespace can be anything you want. The following example defines the constant debugging with a value of true in the CONFIG namespace:

 -define=CONFIG::debugging,true

You use the += operator rather than the = operator to append definitions on the command line to the definitions set in the configuration file. Use the = operator to replace the definitions in the configuration file with the definitions on the command line.

To set the values of multiple constants on the command-line, use the define option more than once; for example:

 mxmlc -define+=CONFIG::debugging,true -define+=CONFIG::release,false MyApp.mxml

To set the value of these constants in the flex-config.xml file, rather than on the command line, you write this as the following example shows:

 <compiler> 
 	<define append="true"> 
 		<name>CONFIG::debugging</name> 
 		<value>true</value> 
 	</define> 
 	<define append="true"> 
 		<name>CONFIG::release</name> 
 		<value>false</value> 
 	</define> 
 </compiler>

If you set the same definition in a configuration file and on the command line, the value on the command line takes precedence.

In a Flex Ant task, you can set constants with a define element, as the following example shows:

 <mxmlc ... > 
 	<define name="CONFIG::debugging" value="true"/> 
 	<define name="CONFIG::release" value="false"/> 
 </mxmlc>

The component compiler options let you define settings such as the classes, resources, and namespaces to include in the resulting SWC file.

The component compiler can take most of the application compiler options, and the options described in this section. For a description of the application compiler options, see About the application compiler options. Application compiler options that do not apply to the component compiler include the metadata options (such as contributor, title, and date), default application options (such as default-frame-rate), locale, debug-password, and theme.

The component compiler has compiler options that the application compilers do not have. The following table describes the component compiler options that are not used by the application compilers:

compute-digest=true|false

directory=false|true

compc -directory=true -output=destination_directory

include-classes class [...]

include-file name path [...]

include-lookup-only=false|true

include-namespaces uri [...]

include-sources path-element

include-stylesheet name path [...]

On the command line, you cannot point the compc utility to a single directory and have it compile all components and source files in that directory. You must specify each source file to compile.

If you have a large set of components in a namespace to include in a SWC file, you can use a manifest file to avoid having to type an unwieldy compc command. For information on creating manifest files, see About manifest files.

The following sections describe common scenarios where you could use the compc command-line compiler.

In many cases, you have one or more components that you use in your applications, but you do not have them in a package structure. You want to be able to use them in the generic namespace ("*") inside your applications. In these cases, you use the include-classes option to add the components to your SWC file.

The following command-line example compiles two MXML components, Rotation.as and RotationInstance.as, into a single SWC file:

 compc -source-path .  
 	-output c:/jrun4/servers/flex/WEB-INF/flex/user_classes/RotationClasses.swc  
 	-include-classes rotationClasses.Rotation rotationClasses.RotationInstance

The rotationClasses directory is a subdirectory of the current directory, which is in the source path. The SWC file is output to the user_classes directory, so the new components require no additional configuration to be used in a server environment.

You use the include-classes option to add components to the SWC file. You use just the class name of the component and not the full filename (for example, MyComponent rather than MyComponent.as). Use dot-notation to specify the location of the component in the package structure.

You also set the source-path to the current directory or a directory from which the component directory can be determined.

You can also add the framework.swc and framework_rb.swc files to the library-path option. This addition is not always required if the compiler can determine the location of these SWC files on its own. However, if you move the compiler utility out of the default location relative to the frameworks files, you must add it to the library path.

The previous command-line example appears in a configuration file as follows:

 <compiler> 
 	<source-path> 
 		<path-element>.</path-element> 
 	</source-path> 
 	<output> 
 		c:/jrun4/servers/flex/WEB-INF/flex/user_classes/RotationClasses.swc 
 	</output> 
 </compiler> 
 <include-classes> 
 	<class>rotationClasses.Rotation</class> 
 	<class>rotationClasses.RotationInstance</class> 
 </include-classes>

To use components that are not in a package in an application, you must declare a namespace that includes the directory structure of the components. The following example declares a namespace for the components compiled in the previous example:

 <?xml version="1.0"?> 
 <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" 
	xmln:local="rotationclasses.*"> 
 	... 
 	<local:Rotation id="Rotate75" angleFrom="0" angleTo="75" duration="100"/> 
 	... 
 </s:Application>

To use the generic namespace of "*" rather than a namespace that includes a component's directory structure, you can include the directory in the source-path as the following command-line example shows:

 compc -source-path . c:/flexdeploy/comps/rotationClasses 
 	-output c:/jrun4/servers/flex/WEB-INF/flex/user_classes/RotationComps.swc  
 	-include-classes Rotation RotationInstance

Then, you can specify the namespace in your application as:

 <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" 
	xmln:local="*">

You are not required to use the directory name in the include-classes option if you add the directory to the source path.

These options appear in a configuration file, as the following example shows:

 <compiler> 
 	<source-path> 
 		<path-element>.</path-element> 
 		<path-element>c:/flexdeploy/comps/rotationClasses</path-element> 
 	</source-path> 
 	<output>c:/jrun4/servers/flex/WEB-INF/flex/user_classes/RotationComps.swc</output> 
 </compiler> 
 <include-classes> 
 	<class>Rotation</class> 
 	<class>RotationInstance</class> 
 <include-classes>

This example assumes that the components are not in a named package. For information about compiling packaged components, see Compiling components in packages.

Some components are created inside packages or directory structures so that they can be logically grouped and separated from application code. As a result, packaged components can have a namespace declaration that includes the package name or a unique namespace identifier that references their location within a package.

You compile packaged components similarly to how you compile components that are not in packages. The only difference is that you must use the package name in the namespace declaration, regardless of how you compiled the SWC file, and that package name uses dot-notation instead of slashes. You must be sure to specify the location of the classes in the source-path.

In the following command-line example, the MyButton component is in the mypackage package:

 compc -source-path . c:/flexdeploy/comps/mypackage/  
 	-output c:/jrun4/servers/flex/WEB-INF/flex/user_classes/MyButtonComp.swc  
 	-include-classes mypackage.MyButton

These options appear in a configuration file, as the following example shows:

 <compiler> 
 	<source-path> 
 		<path-element>.</path-element> 
 		<path-element>c:/flexdeploy/comps/mypackage/</path-element> 
 	</source-path> 
 	<output> 
 		c:/jrun4/servers/flex/WEB-INF/flex/user_classes/MyButtonComp.swc 
 	</output> 
 </compiler> 
 <include-classes> 
 	<class>mypackage.MyButton</class> 
 <include-classes>

To access the MyButton class in your application, you must declare a namespace that includes its package; for example:

<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" 
	xmlns:mine="mypackage.*">

You can use the compc compiler to compile components from multiple packages into a single SWC file. In the following command-line example, the MyButton control is in the mypackage package, and the CustomComboBox control is in the acme package:

 compc -source-path .  
 	-output c:/jrun4/servers/flex/WEB-INF/flex/user_classes/CustomComps.swc  
 	-include-classes mypackage.MyButton  
 	acme.CustomComboBox

You then define each package as a separate namespace in your MXML application:

 <?xml version="1.0"?> 
 <s:Application <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" 
	xmlns:mine="mypackage.*" 
	xmlns:acme="acme.*"> 
 	<mine:MyButton/> 
 	<acme:CustomComboBox/> 
 </s:Application>

When you have many components in one or more packages that you want to add to a SWC file and want to reference from an MXML file through a custom namespace, you can list them in a manifest file, then reference that manifest file on the command line. Also, you can specify a namespace for that component or define multiple manifest files and, therefore, specify multiple namespaces to compile into a single SWC file.

When you use manifest files to define the components in your SWC file, you specify the namespace that the components use in your applications. You can compile all the components from one or more packages into a single SWC file. If you have more than one package, you can set it up so that all packages use a single namespace or so that each package has an individual namespace.

You can add any classes that you want to use in your applications to a SWC file. These classes do not have to be components, but are often files that components use. They are classes that might be used at run time and, therefore, are not checked by the compiler. For example, your components might use a library of classes that perform mathematical functions, or use a custom logging utility. This documentation refers to these classes as utility classes. Utility classes are not exposed as MXML tags.

To add utility classes to a SWC file, you use the include-sources option. This option lets you specify a path to a class file rather than the class name, or specify an entire directory of classes.

The following command-line example adds the FV_calc.as and FV_format.as utility classes to the SWC file:

 compc -source-path .  
 	-output c:/jrun4/servers/flex/WEB-INF/flex/user_classes/MySwc.swc  
 	-include-sources FV_classes/FV_format.as FV_classes/FV_calc.as  
 	-include-classes asbutton.MyButton

In a configuration file, these options appear as the following example shows:

 <compiler> 
 	<source-path> 
 		<path-element>.</path-element> 
 	</source-path> 
 	<output>c:/jrun4/servers/flex/flex/WEB-INF/flex/user_classes/		MySwc.swc</output> 
 </compiler> 
 <include-classes> 
 	<class>asbutton.MyButton</class> 
 </include-classes> 
 <include-sources> 
 	<path-element>FV_classes/FV_format.as</path-element> 
 	<path-element>FV_classes/FV_calc.as</path-element> 
 <include-sources>

When specifying files with the include-sources option, you must give the full filename (for example, FV_calc.as instead of FV_calc) because the file is not a component. If you use this option to include MXML components that are in a non-default package, you must include the source folder in the source path.

You can also provide a directory name to the include-sources option. In this case, the compiler includes all files with an MXML or AS extension, and ignores all other files.

Classes that you add with the include-sources option can be accessed from the generic namespace in your applications. To use them, you need to add the following code in your application tag:

 xmlns:local="*"

You can then use them as tags; for example:

 <local:FV_calc id="calc" rate=".0125" nper="12" pmt="100" pv="0" type="1"/>

You often include noncompiled (or nonsource) files with your applications. A nonsource file is a class or resource (such as a style sheet or graphic) that is not compiled but is included in the SWC file for other classes to use. For example, a font file that you embed or a set of images that you use as graphical skins in a component's style sheet should not be compiled but should be included in the SWC file. These are classes that you typically do not use the [Embed] syntax to link in to your application.

Use the include-file option to define nonsource files in a SWC file.

The syntax for the include-file option is as follows:

 -include-file name path 

The name argument is the name used to reference the embedded file in your applications. The path argument is the current path to the file in the file system.

When you use the include-file option, you specify both a name and a filepath, as the following example shows:

 compc -include-file logo.gif c:/images/logo/logo1.gif ...

In a configuration file, these options appear as the following example shows:

 <compiler> 
 	<output>c:/jrun4/servers/flex/flex/WEB-INF/flex/user_classes/Combo.swc</output> 
 </compiler> 
 <include-file> 
 	<name>logo.gif</name> 
 	<path>c:/images/logo/logo1.gif</path> 
 </include-file> 
 <include-classes> 
 	<class>asbutton.MyButton</class> 
 <include-classes>

Each name that you assign to a resource must be unique because the name becomes a global variable.

You cannot specify a list of files with the include-file option. So, you must add a separate include-file option for each file that you include, as the following command-line example shows:

 compc -include-file file1.jpg ../images/file1.jpg -include-file file2.jpg ../images/file2.jpg -- -output MyFile.swc

If you want to add many resources to the SWC file, consider using a configuration file rather than listing all the resources on the command line. For an example of a configuration file that includes multiple resources in a SWC file, see Styles and themes.

In general, specify a file extension for files that you include with the include-file option. In some cases, omitting the file extension can lead to a loss of functionality. For example, if you include a CSS file in a theme SWC file, you must set the name to be *.css. When Flex examines the SWC file, it applies all CSS files in that SWC file to the application. CSS files without the CSS extension are ignored.

You can use the include-file and include-classes options to add skin files and style sheets to a SWC file. The SWC file can then be used as a theme. For more information about using themes in applications, see Styles and themes.

There are several options that let you customize the level of warnings and errors that are displayed by the Flex compilers, including the following:

• show-actionscript-warnings

• show-binding-warnings

• show-invalid-css-property-warnings

• show-shadowed-device-font-warnings

• show-unused-type-selector-warnings

• strict

• warnings

To disable all warnings, set the warnings option to false.

The show-actionscript-warnings option displays compiler warnings for the following situations:

1. Situations that are probably not what the developer intended, but are still legal; for example:

    if (a = 10) 							// Did you really want '==' instead of '='? 
    if (b == NaN) 							// Any comparison with NaN is always false. 
    var b;							// Missing type declaration.

2. Usage of deprecated or removed ActionScript 2.0 APIs.

3. Situations where APIs behave differently in ActionScript 2.0 than in ActionScript 3.0.

You can customize the types of warnings displayed by using options that begin with warn (for example, warn-constructor-return-values and warn-bad-type-cast). A complete list of warnings are available in the advanced command-line help or in the flex-config.xml file.

The strict option enforces typing and reports run-time verifier errors at compile time. This option assumes that definitions are not dynamically redefined at run time, so these checks can be made at compile time. It displays errors for conditions such as undefined references, const and private violations, argument mismatches, and type checking.

The show-binding-warnings option displays warnings when Flash Player cannot detect changes to bound properties.

In some cases, Flex functionality has been deprecated. Deprecated features and properties have the following characteristics:

• Generate compiler warnings.

• Continue to work in Flex 4.x.

• Will be removed from the product in a future major release.

The command-line compilers report deprecation warnings by default. You can suppress deprecation warnings by setting the show-deprecation-warnings option to false.

In some cases, deprecated functionality does not work as expected unless you instruct the compiler to use an earlier version of the compiler with the compatibility-version compiler argument. For example, to use functionality that was deprecated since Flex 3, you could use the following command-line compiler argument:

 -compatibility-version=3.0.0

Possible values for this compiler argument are defined as constants in the FlexVersion class. For more information on using this compiler argument, see Backward compatibility.

You can use the [Deprecated] metadata tag to deprecate your own classes and class elements. For more information, see Deprecated metadata tag.

Errors and warnings are reported differently, depending on which compiler you are using.

The mxmlc and compc command-line compilers send error and warning messages to the standard output. You can redirect this output by using the redirector (>).

After you generate a SWC file, you can use it in your applications.

You can also copy SWC files to a directory specified by the library-path compiler option. You must store SWC files at the top level of the user_classes directory or the directory specified by the library-path. You cannot store SWC files in subdirectories.

To use a SWC file when compiling components or applications from the command line, you specify the location of the SWC file with the library-path compiler option.

If a component in a SWC file does not have a namespace, you can add a generic namespace identifier in your <s:Application> tag to use the component, as the following example shows:

 <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" 
	xmlns:a="*">

If the component has a package name as part of its namespace, you must do one of the following:

1. Add the package name to the namespace declaration in the <s:Application> tag; for example:

    <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" 
   	xmlns:but="mycomponents.*">

2. Create a manifest file and recompile the SWC file. You pass the manifest file to the compc compiler by using the namespace option. In the <s:Application> tag, you specify only the unique namespace URI that you used with compc. For more information on specifying a namespace for the component, see Compiling components using namespaces.

You invoke fcsh from the command line. You can launch the utility either as an executable (Windows) or shell command (Unix/Linux/Mac).

1. Open a command prompt.

2. Navigate to the {SDK_root}/bin directory.

3. Enter fcsh at the command line. Your commands will now be executed within the fcsh environment. You will know this if your command prompt becomes (fcsh).

Typically, you compile a simple application when you first launch fcsh; for example:

 (fcsh) mxmlc c:/myfiles/MyApp.mxml

The fcsh utility returns a target id:

 fcsh: Assigned 1 as the compile target id.

You can then refer to the target ids when using subsequent commands inside the fcsh utility. For example, to compile the previous application with incremental compilation:

 (fcsh) compile 1

You can enter help in the fcsh shell to see a list of available options; for example:

 (fcsh) help

You can enter quit in the fcsh shell to exit fcsh and return to the command prompt; for example:

 (fcsh) quit

The following example shows that fcsh dramatically reduces compilation time when compiling the same application multiple times. The first compilation takes 8885 milliseconds. The second takes only 5140 milliseconds:

 (fcsh) mxmlc -benchmark=true flexstore.mxml 
 	Total time: 8885ms 
 	Peak memory usage: 84 MB (Heap: 58, Non-Heap: 26) 
 (fcsh) mxmlc -benchmark=true flexstore.mxml 
 	Total time: 5140ms 
 	Peak memory usage: 84 MB (Heap: 57, Non-Heap: 27)

In addition, subsequent full compilations of the same application are much faster, as the following example shows:

 > touch flexstore.mxml 
  
 (fcsh) compile 1 
 	Files changed: 1 Files affected: 0 
 	Total time: 933ms 
 	Peak memory usage: 88 MB (Heap: 62, Non-Heap: 26) 
 	flexstore.swf (522456 bytes) 
 	Total time: 1102ms 
 	Peak memory usage: 77 MB (Heap: 51, Non-Heap: 26) 
 (fcsh)

The following table describes the available fcsh commands:

clear [id]

compile id

compc arg1 [...]

info [id]

mxmlc arg1 [...]

quit