Apache Flex® - Component compilation

When you compile an application, you create a SWF file that a user can download and play. You can also compile any custom components that you create as part of the application.

When you create a component, you save it to a location that the Flex compiler can access. You can save your components as MXML and ActionScript files, as SWC files, or as Runtime Shared Libraries (RSLs). You have several options when you compile the components.

About compiling

You compile a custom component so that you can use it as part of your application. You can compile the component when you compile the entire application, or you can compile it separately so that you can link it into the application at a later time.

Flex component file types

When you create a Flex component, you can distribute it in one of several different file formats, as the following table shows:

File format	Extension	Description
MXML	.mxml	A component implemented as an MXML file.
ActionScript	.as	A component implemented as an ActionScript class.
SWC	.swc	A component implemented as an MXML or ActionScript file, and then packaged as a SWC file. A SWC file contains components that you package and reuse among multiple applications. The SWC file is then compiled into your application when you create the application's SWF file.
RSL	.swc	A component implemented as an MXML or ActionScript file, and then deployed as an RSL. An RSL is a stand‑alone file that is downloaded separately from your application's SWF file, and cached on the client computer for use with multiple application SWF files.

You must take into consideration the file format and file location when you compile an application that uses the component.

About compiling with Flex SDK

Flex includes two compilers: mxmlc and compc. You use the mxmlc compiler to compile MXML, ActionScript, SWC, and RSL files into a single SWF file. After your application is compiled and deployed on your web or application server, a user can make an HTTP request to download and play the SWF file on their computer.

You use the compc compiler to compile components, classes, and other files into SWC files or into RSLs.

You use the compc and mxmlc compilers from a command line. For more information on using the compilers, see Flex compilers.

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

 $ mxmlc c:/myfiles/app.mxml

The default option is the target file to compile into a SWF file, and it must 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, as in the following example:

 $ mxmlc -option arg1 arg2 arg3 -- target_file.mxml

About case sensitivity during a compilation

The Flex compilers use a case-sensitive file lookup on all file systems. On case-insensitive file systems, such as the Macintosh and Windows file systems, the Flex compiler generates a case-mismatch error when you use a component with the incorrect case. On case-sensitive file systems, such as the UNIX file system, the Flex compiler generates a component-not-found error when you use a component with the incorrect case.

About the ActionScript source path

Typically, you put component files in directories that are in the ActionScript source path. These include your application's root directory, its subdirectories, and any directory that you specify to the compiler. To specify a directory, you use the source-path option to the mxmlc compiler.

The following rules can help you organize your custom components:

An application can access MXML and ActionScript components in the same directory and in its subdirectories.
An ActionScript component in a subdirectory of the main application directory must define a fully qualified package name that is relative to the location of the application's root directory. For example, if you define a custom component in the dir1/dir2/myControls/PieChart.as file, its fully qualified package name must be dir1.dir2.myControls, assuming dir1 is an immediate subdirectory of the main application directory.
An MXML component does not include a package name definition. However, you must declare a namespace definition in the file that references the MXML component that corresponds to the directory location of the MXML component, either in a subdirectory of the application's root directory or in a subdirectory of the source path. For more information, see Simple MXML components.
An application can access MXML and ActionScript components in the directories included in the ActionScript source path. The component search order in the source path is based on the order of the directories listed in the source path.
An ActionScript component in a subdirectory of a directory included in the source path must define a fully qualified package name that is relative to the location of the source path directory. For example, if you define a custom component in the file dir1/dir2/myControls/PieChart.as, and dir1 is included in the ActionScript source path, its fully qualified package name must be dir1.dir2.myControls.
The <fx:Script> tag in the main MXML file, and in dependent MXML component files, can reference components located in the ActionScript source path.

Compiling components with Flex SDK

How you compile an application with the Flex SDK is based on how you distribute your custom components that are distributed as MXML, ActionScript, SWC, and RSL files.

Distributing components as MXML and ActionScript files

When you compile an application with Flex SDK, you define where the MXML and ActionScript files for your custom components exist in the directory structure of your application, or in the directory structure of components shared by multiple applications.

For example, you can create a component for use by a single application. In that case, you store it in the directory structure of the application, usually in a subdirectory under the directory that contains the main file of the application. The component is then compiled with the entire application into the resultant SWF file.

You can also create a component that is shared among multiple applications as an MXML or ActionScript file. In that case, store the component in a location that is included in the ActionScript source path of the application. When Flex compiles the application, it also compiles the components included in the application's ActionScript source path.

You specify the directory location of the shared components by using the following method:

mxmlc compiler: Use the source-path option to the mxmlc compiler to specify the directory location of your shared MXML and ActionScript files.

Distributing components as SWC files

A SWC file is an archive file of Flex components. SWC files make it easy to exchange components among Flex developers. You need to exchange only a single file, rather than the MXML or ActionScript files, images, and other resource files. In addition, the SWF file inside a SWC file is compiled, which means that the code is hidden from casual view. Finally, compiling a component as a SWC file can make namespace allocation an easier process.

SWC files can contain one or more components and are packaged and expanded with the PKZIP archive format. You can open and examine a SWC file by using WinZip, JAR, or another archiving tool. However, do not manually change the contents of a SWC file, and do not try to run the SWF file that is in a SWC file outside of the SWC file.

When you compile your application, you specify the directory location of the SWC files by using the following method:

mxmlc compiler

Set the library-classpath option to the mxmlc compiler to specify the directory location of your SWC files.

One of the advantages of distributing components as SWC files is that you can define a global style sheet, named defaults.css, in the SWC file. The defaults.css file defines the default style settings for all of the components defined in the SWC file. For more information, see Applying styles from a defaults.css file.

For more information about SWC files, see Flex compilers.

Distributing components as RSLs

One way to reduce the size of your application's SWF file is by externalizing shared assets into stand-alone files that can be separately downloaded and cached on the client. These shared assets are loaded by any number of applications at run time, but must be transferred to the client only once. These shared files are known as Runtime Shared Libraries (RSLs).

If you have multiple applications but those applications share a core set of components or classes, your users download those assets only once as an RSL. The applications that share the assets in the RSL use the same cached RSL as the source for the libraries as long as they are in the same domain. By using an RSL, you can reduce the resulting file size for your applications. The benefits increase as the number of applications that use the RSL increases. If you only have one application, putting components into RSLs does not reduce the aggregate download size, and may increase it.

When you compile your application, you specify the directory location of an RSL file by using the following method:

mxmlc compiler

Set the external-library-path option to the mxmlc compiler to specify the location of the RSL file at compile time. Set the runtime-shared-libraries option to the mxmlc compiler to specify the relative location of the RSL file when the application is deployed.

For more information, including information on how to create an RSL file, see Runtime Shared Libraries.

Example: Compiling a custom formatter component

The example in this section uses a custom formatter component that is defined as an ActionScript file. The name of the formatter is MySimpleFormatter, and it is defined in the file MySimpleFormatter.as. For more information on creating customer formatter components, see Custom formatters.

The process for compiling an MXML file is the same as for an ActionScript file. For an example of deploying an MXML file, see Simple MXML components.

Distributing a component as an ActionScript file

When you distribute a component defined as an ActionScript file, you can store it within the same directory structure as your application files or in a directory specified in the ActionScript source path.

The MXML tag name for a custom component consists of two parts: the namespace prefix and the tag name. The namespace prefix tells Flex where to look for the file that implements the custom component. The tag name corresponds to the filename of the component, in this case MySimpleFormatter.as. Therefore, the file MySimpleFormatter.as defines a component with the tag name of < namespace :MySimpleFormatter>.

The main application MXML file defines the namespace prefix used to reference the component in the <s:Application> tag. When you deploy your formatter as an ActionScript file, you refer to it in one of the following ways:

If you store the formatter component in the same directory as the application file, or in a directory that the ActionScript source path (not a subdirectory) specifies, you define the formatter by using an empty package statement, as the following example shows:
```
 package 
 { 
 	//Import base Formatter class. 
 	import mx.formatters.Formatter 
  
 	public class MySimpleFormatter extends Formatter { 
 		... 
 	} 
 }
```
You can refer to it as the following example shows. In the following code, the local namespace (*) is mapped to the prefix MyComp.
```
 <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:MyComp="*"> 
  
 	<MyComp:MySimpleFormatter/> 
  
 </s:Application>
```
If the same file exists in the ActionScript source path directory and the application directory, Flex uses the file in the application directory.
If you store the formatter component in a subdirectory of the directory that contains the application file, you specify that directory as part of the package statement, as the following example shows:
```
 package myComponents.formatters 
 { 
 	//Import base Formatter class 
 	import mx.formatters.Formatter 
  
 	public class MySimpleFormatter extends Formatter { 
 		... 
 	} 
 }
```
In this example, the MySimpleFormatter.as file is located in the myComponents/formatter subdirectory of the main application directory. You map the myComponents.formatters namespace to the MyComp prefix, 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:MyComp="myComponents.formatters.*"> 
  
 	<MyComp:MySimpleFormatter/> 
  
 </s:Application>
```
If multiple files with the same name exist under an ActionScript source path subdirectory and the application subdirectory, Flex uses the file under the application subdirectory.

If you store the formatter component in a subdirectory of the ActionScript source path directory, you specify that subdirectory as part of the package statement, as the following example shows:

 package flexSharedRoot.custom.components 
 { 
 	//Import base Formatter class. 
 	import mx.formatters.Formatter 
  
 	public class MySimpleFormatter extends Formatter { 
 		... 
 	} 
 }

You then use a namespace that specifies the subdirectory. The following code declares a component that is in the flexSharedRoot/custom/components directory:

 <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:MyComp="flexSharedRoot.custom.components.*"/> 
  
 	<MyComp:MySimpleFormatter/> 
  
 </s:Application>

If the same file exists in the ActionScript source path directory and the application directory, Flex uses the file in the application file directory.

Distributing a component as a SWC file

To create a SWC file, use the compc compiler in the flex_install_dir/bin directory. The compc compiler generates a SWC file from MXML component source files and/or ActionScript component source files.

In this example, you create a SWC file for a custom formatter component that you defined by using the following package and class definition:

 package myComponents.formatters 
 { 
 	//Import base Formatter class. 
 	import mx.formatters.Formatter 
  
 	public class MySimpleFormatter extends Formatter { 
 		... 
 	} 
 }

In this example, the MySimpleFormatter.as file is in the directory c:\flex\myComponentsForSWCs\myComponents\formatters.

You use the following compc command from the flex_install_dir/bin directory to create the SWC file for this component:

 .\compc -source-path c:\flex\myComponentsForSWCs\ 
 	-include-classes myComponents.formatters.MySimpleFormatter 
 	-o c:\flex\mainApp\MyFormatterSWC.swc

In this example, you use the following options of the compc compiler:

Option name	Description
`-source-path`	Specifies the base directory location of the MySimpleFormatter.as file. It does not include the directories that the component's package statement defines.
`-include-classes`	Specifies classes to include in the SWC file. You provide the class name (MyComponents.formatters.MySimpleFormatter) not the filename of the source code. All classes specified with this option must be in the compiler's source path, which is specified in the `source-path` compiler option. You can use packaged and unpackaged classes. To use components in namespaces, use the `include-namespaces` option. If the components are in packages, use dot (.) notation rather than slashes to separate package levels.
`-o`	Specifies the name and directory location of the output SWC file. In this example, the directory is c:\flex\mainApp, the directory that contains your main application.

Option name

Description

-source-path

Specifies the base directory location of the MySimpleFormatter.as file. It does not include the directories that the component's package statement defines.

-include-classes

Specifies classes to include in the SWC file. You provide the class name (MyComponents.formatters.MySimpleFormatter) not the filename of the source code. All classes specified with this option must be in the compiler's source path, which is specified in the source-path compiler option.

You can use packaged and unpackaged classes. To use components in namespaces, use the include-namespaces option.

If the components are in packages, use dot (.) notation rather than slashes to separate package levels.

-o

Specifies the name and directory location of the output SWC file. In this example, the directory is c:\flex\mainApp, the directory that contains your main application.

In your main application file, you specify the component's namespace, 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:MyComp="myComponents.formatters.*"> 
  
 	<MyComp:MyFormatter/> 
  
 </s:Application>

When you distribute SWC files, ensure that the corresponding ActionScript file is not in the directory structure of the application or in the ActionScript source path. Otherwise, Flex might use the ActionScript file, rather than the SWC file.

When you use mxmlc to compile the main application, ensure that the c:\flex\mainApp directory is included in the library path; otherwise, mxmlc cannot locate the SWC file.

For more information about SWC files, see Flex compilers.

Distributing a component as an RSL file

You create an RSL by using the compc tool, and then pass the library's location to the compiler when you compile your application. For more information, including an example, see Runtime Shared Libraries.

Navigation

Using Flex » Custom components

Adobe and Adobe Flash Platform are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States and/or other countries and are used by permission from Adobe. No other license to the Adobe trademarks are granted.

Component compilation