Creating libraries

To use standard or cross-domain RSLs, you must first create the library that will be used as an RSL. If you want to use framework RSLs, the libraries are already created for you. In that case, all you need to do is compile against them and then deploy the SWZ or SWF file with your application.

A standard or cross-domain RSL is a library of custom components, classes, and other assets that you create. You can create a library using either Flash Builder or the compc command-line compiler. A library is a SWC file or open directory that contains a library.swf file and a catalog.xml file, as well as properties files and other embedded assets. You can use any library as an RSL, but libraries do not need to be used as RSLs.

Creating libraries in Flash Builder

In Flash Builder, you create a new library by selecting File > New > Flex Library Project. You add resources to a library by using the Flex Library Build Path dialog box. When you select Build Library or Build All, Flash Builder creates a SWC file. This SWC file contains the library.swf file.

Creating libraries on the command line

On the command line, you create a library by using the compc compiler. You add files to a library by using the include-classes and include-namespaces options when you compile the SWC file.

The following example creates a library called CustomCellRenderer.swc with the compc compiler:

compc -source-path ../mycomponents/components/local  
    -include-classes CustomCellRendererComponent  
    -directory=true  
    -debug=false 
    -output ../libraries/CustomCellRenderer

The options on the command line can also be represented by settings in the flex-config.xml file, as the following example shows:

<?xml version="1.0"> 
<flex-config> 
    <compiler> 
        <source-path> 
            <path-element>../mycomponents/components/local</path-element> 
        </source-path> 
    </compiler> 
    <output>../libraries/CustomCellRenderer</output> 
    <directory>true</directory> 
    <debug>false</false> 
    <include-classes> 
        <class>CustomCellRendererComponent</class> 
    </include-classes> 
</flex-config>

All classes and components must be statically linked into the resulting library. When you use the compc compiler to create the library, do not use the include-file option to add files to the library, because this option does not statically link files into the library.

Optimizing libraries

Optimizing libraries means to remove debugging and other code from the library prior to deployment. For normal libraries that you are not using as RSLs, you do not need to optimize. This is because you will likely want to debug against the library during development, so you will need the debug code inside the library. And, when you compile the release version of your application, the compiler will exclude debug information as it links the classes from the library.

When you compile a library for production use as an RSL, however, you can set the debug compiler option to false. The default value is true for compc, which means that the compiler, by default, includes extra information in the SWC file to make it debuggable. You should avoid creating a debuggable library that you intend to use in production so that the RSL’s files are as small as possible. If you set the value of the debug option to false, however, you will not be able to debug against the RSL for testing.

If you do include debugging information, you can still optimize the RSL after compiling it, which removes the debugging information as well as unnecessary metadata. For more information, see Optimizing RSL SWF files.

Before you deploy an RSL, you extract the SWF file that is inside the library SWC file and optimize it. The default name of this SWF file is library.swf. After you extract it from the SWC file, you can rename it to anything you want. When you deploy the RSL, you deploy the SWF file so that the application can load it at run time.

On the command line, you typically specify that the output of compiling a library be an open directory rather than a SWC file by using the directory option and the output option. The output is an open directory that contains the following files:

  • catalog.xml

  • library.swf

In addition, the library contains properties files and any images or other embedded assets that are used by the library.

If you do not specify that the output be an open directory, you must manually extract the library.swf file from the SWC file with a compression utility, such as PKZip.

In Flash Builder, you can instruct the compiler to automatically extract the SWF file for you when you add the RSL SWC file to the project. Doing this does not optimize the SWF file, so the library will be bigger than if you extract it yourself and optimize it.

To manually extract an RSL SWF file from its SWC file in Flash Builder, add the output and directory options to the Additional Compiler Arguments field in the Flex Compiler dialog box. In both cases, you specify the deployment location of the SWF file when you add the SWC file to your project as an RSL.

When creating a library, you need to know if you will be using the library as a standard RSL or as a cross-domain RSL. If you are using it as a cross-domain RSL, you must include the digest information in the library. For more information, see About cross-domain RSLs.

After you create the library, you then compile your application against the SWC file and specify the library’s SWF file’s location for use at run time. For more information, see Compiling applications with standard and cross-domain RSLs.

For more information on using the compc compiler options, see Flex compilers.