Understanding library linking can help you understand how RSLs work and how you can most benefit from their use. The Flex compilers support static linking and dynamic linking for class libraries (including RSLs). Static linking is the most common type of linking when compiling an application. However, dynamic linking lets you take advantage of RSLs to achieve a reduction of the final SWF file size and, therefore, a reduction in the application download time.

When you use static linking, the compiler includes all referenced classes and their dependencies in the application SWF file. The end result is a larger file that takes longer to download than a dynamically-linked application, but loads and runs quickly because all the code is in the SWF file.

To statically link a library's definitions into your application, you use the library-path and include-libraries compiler options to specify locations of SWC files.

When you use the library-path option, the compiler includes only those classes required at compile time in the SWF file, so the entire contents of a library are not necessarily compiled into the SWF file. The include-libraries option includes the entire contents of the library, regardless of which classes are required. You can also use the source-path and includes options to embed individual classes in your SWF file.

If you statically link any part of a library into your application, you cannot use that library as an RSL.

Dynamic linking is when some classes used by an application are left in an external file that is loaded at run time. The result is a smaller SWF file size for the main application, but the application relies on external files that are loaded at run time. Dynamic linking is used by modules, runtime stylesheets, and RSLs.

When you want to use a dynamically-linked library, you instruct the compiler to exclude that library's contents from the application SWF file when you compile the application. You must provide link-checking at compile time even though the classes are not going to be included in the final SWF file. At run time, the application loads the entire library into the application SWF file, which can result in slower startup times and greater memory usage.

You can use the runtime-shared-library-path (Flex 4 and later) and runtime-shared-libraries (Flex 3) options to specify the location of dynamically-linked libraries.

You can also use the external-library-path, externs, or load-externs compiler options to specify the files to dynamically link into an application. These options instruct the compiler to exclude classes and libraries from the application, but to check links against them and prepare to load them at run time. The external-library-path option specifies SWC files or directories for dynamic linking. The externs option specifies individual classes or symbols for dynamic linking. The load-externs option specifies an XML file that describes what classes to use for dynamic linking. These options are most often used when externalizing assets from modules so that the module and the application do not contain overlapping class definitions. The runtime-shared-library-path option provides all the arguments to use external libraries as RSLs.

You can view the linking information for your application by using the link-report compiler option. This generates a report that has the same syntax as the file that you load with the load-externs option, so you can use it as an argument to that option without changing it. For more information about this report, see Examining linker dependencies.

For more general information about the command-line compiler options, see Flex compilers.

The following example shows the possible benefit of separating shared components into an RSL. In this example, the library's size is 150 KB (kilobytes) and the compiled application's size is 100 KB. Without RSLs, you merge the library into both applications for an aggregate download size of 500 KB. If you add a third or fourth application, the aggregate download size increases by 250 KB for each additional application.

With RSLs, the RSL needs to be downloaded once only. For two applications that use the same RSL, the result is an aggregate download size of 350 KB, or a 30% reduction. If you add a third or fourth application, the aggregate download size increases by 100 KB instead of 250KB for each additional application. In this example, the benefits of using an RSL increase with each new application.

In this example, the applications with statically-linked libraries run only after Adobe^® Flash^® Player loads the 250 KB for each application. With dynamically linked RSLs, however, only the first application must load the entire 250 KB (the combined size of the application and the RSL). The second application runs when just 100 KB loads because the RSL is cached.

The illustrated scenario shows one possible outcome. If your applications do not use all of the components in the RSL, the size difference (and, as a result, the savings in download time) might not be as great. Suppose that each application only uses half of the components in the RSL. If you statically link the library, only those classes that are used are included; the output, as a result, is 100 KB + 75 KB for the first application and the library and 100 KB + 75 KB for the second application and the library, or an aggregate download size of 350 KB. When you use a library as an RSL, its entire SWF file must be transferred across the network and loaded by the application at run time, regardless of how much of that library is actually used. In this second case, the combined download size when using RSLs and when not using RSLs is the same.

In general, the more applications that use a common RSL, the greater the benefit.

RSLs are not necessarily beneficial for all applications. You should try to test both the download time and startup time of your application with and without RSLs.

Standard RSLs can not be shared across domains. If a client runs an application in domain1.com and uses an RSL, and then launches an application in domain2.com that uses the same RSL, the client downloads the RSL twice even though the RSL is the same. You can overcome this limitation of standard RSLs by using cross-domain RSLs.

Cross-domain RSLs can be loaded by any application, even if that application is not in the same domain. They do, however, require that you create and check a digest when the RSL is loaded. This can increase startup time of the application by a small amount.

Framework RSLs can also be loaded by any application. To take advantage of the fact that framework RSLs can be cached in the Player cache, the client must be running a recent version of Flash Player. Not all clients necessarily have the latest Player, so loading a framework RSL might fail. In these cases, you can specify a failover RSL.

An RSL usually increases the startup time of an application. This is because the entire library is loaded into an application regardless of how much of the RSL is actually used. For this reason, make your RSLs as small as possible. This contrasts with how statically-linked libraries are used. When you compile an application, the compiler extracts just the components it needs from those component libraries.

If you have several applications that share several libraries, it might be tempting to merge the libraries into a single library that you use as an RSL. However, if the individual applications generally do not use more than one or two libraries each, the penalty for having to load a single, large RSL might be higher than it would be to have the applications load multiple smaller RSLs.

In this case, test your application with both a single large RSL and multiple smaller RSLs, because the gains are largely application specific. It might be better to build one RSL that has some extra classes than to build two RSLs, if most users will load both of them anyway.

If you have overlapping classes in multiple RSLs, be sure to synchronize the versions so that the wrong class is never loaded.

You cannot use RSLs in ActionScript-only projects if the base class is Sprite or MovieClip. RSLs require that the application's base class, such as Application or SimpleApplication, understand RSL loading.

In general, you should disable RSLs when compiling modules, CSS SWF files, and applications that will be loaded as child SWFs in a parent application. The parent application will likely use RSLs and dynamically link the required classes.

RSLs are cached when they are first used. When they are needed by another application, they can be loaded from the cache rather than across the network. Caching is one of the benefits of RSLs, because disk access is much faster than network access.

The type of caching used by an RSL is based on the type of RSL. Standard or cross-domain RSLs are stored in the browser's cache. If the user clears their cache, the RSLs are removed and must be downloaded again the next time they are needed. Unsigned framework RSLs are also stored in the browser's cache.

Signed framework RSLs are stored in the Player cache. This is a special cache that is maintained by Flash Player. To clear this cache, clients must invoke the Settings Manager. RSLs stored in this cache are signed and therefore can be used by any application without the need for a cross-domain policy file.

For more information about the framework cache, see About the Player cache.

The techniques in this section apply to framework and custom RSLs.

The Player cache stores signed RSLs, such as the framework RSLs. You can manage the settings of the Player cache with the Settings Manager. The use of the RSLs in the Player cache is secure; no third party can inject code that will be executed. Only Adobe can sign RSLs; therefore, only Adobe RSLs can be stored in the Player cache.

The default size of the framework cache is 20MB. When the aggregate size of the cached RSLs in this directory meets or exceeds 20MB, Flash Player purges the cache. Files are purged on a least-recently-used basis. Less-used files are purged before files that have been used more recently. Purging continues until the cache size is below 60% of the maximum size. By default, this is 12MB.

The Global Storage Settings panel in the Settings Manager lets the user turn off the caching feature and increase or decrease its size. The Settings Manager is a special control panel that runs on your local computer but is displayed within and accessed from the Adobe website. If the user disables the Player cache, then Flash Player will not load SWZ files. Flash Player will load failover RSLs instead.

The following table shows the locations of the Player cache on various platforms:

Framework RSLs are enabled by default for the command-line compiler. You can use the information in this section if you want to specify that only some of them are used, reorder the failover options, or customize some other aspect of the framework RSLs.

Create an application with a single Button control. After you create the application, determine the size of the application's compiled SWF file before you use the framework RSL. This will give you an idea of how much memory you are saving by using the framework RSL.

Compile the application as you normally would, with one exception. Add the static-link-runtime-shared-libraries=true option; this ensures that you are not using the framework RSL when compiling the application, regardless of the settings in your configuration files. Instead, you are compiling the framework classes into your application's SWF file.

With the mxmlc command-line compiler, use the following command to compile the application:

 mxmlc -static-link-runtime-shared-libraries=true bin/SimpleApp.mxml

Examine the output size of the SWF file. Even though the application contains only a Button control, the size of the SWF file should be over 100KB. That is because it not only includes component and application framework classes, but it also includes all classes that those classes inherit from plus other framework dependencies. For visual controls such as a Button, the list of dependencies can be lengthy. If you added several more controls to the application, you will notice that the application does not get much larger. That is because there is a great deal of overlap among all the visual controls.

Run the application in a browser either from the file system or from a server. You can also run the application in the standalone player.

Next, compile the application again, but this time add the signed framework RSL as an RSL and the unsigned framework RSL as a failover RSL. For example:

 mxmlc -runtime-shared-library-path=c:/p4/flex/flex/sdk/frameworks/libs/framework.swc, 
 	framework_4.0.0.5902.swz,,framework_4.0.0.5902.swf rsls/SimpleApp.mxml

The result is a SWF file that should be smaller than the previous SWF file.

This command includes a blank entry for the policy file URL. In this example, the crossdomain.xml file is not needed because you will deploy the RSLs and the application to the same domain, into the same directory.

In addition, the runtime-shared-library-path option includes an unsigned failover RSL as its final parameter. This is a standard framework RSL SWF file that is provided to support older versions of Flash Player that do not support signed RSLs. It is not cross domain, and if used by the client, it is stored in the browser's cache, not the framework cache.

Deploy the application and the framework RSLs to a server. You cannot request the SimpleApp.swf file from the file system because it loads network resources (the framework RSLs). This causes a security sandbox violation unless the application is loaded from a server. Deploy the SimpleApp.swf, framework_4.0.0.5902.swz, and framework_4.0.0.5902.swf files to the same directory on your web server.

Request the application in the browser or create a wrapper for the application and request that file.

To verify that the signed framework RSL was loaded by your application, you can look for an SWZ file in your framework cache. For more information, see About the Player cache.

After the client downloads the signed framework RSL, they will not have to download that RSL again for any application that uses signed framework RSLs, unless a new version of the framework is released or the RSL's SWZ file is purged from the Player cache.

Standard RSLs can only be used by applications that are in the same domain as the RSL. You can benefit from using standard RSLs if you meet all of the following conditions:

• You host multiple applications in the same domain.

• You have custom component libraries.

• More than one application uses those custom component libraries.

Not all applications can benefit from standard RSLs. Applications that are in different domains or that do not use component libraries will not benefit from standard RSLs.

Standard RSLs can benefit from digests. While they do not require digests, you can use them to ensure that your application loads the latest RSL. For more information, see About RSL digests.

The following is a list of typical applications that can benefit from standard RSLs:

• Large applications that load multiple smaller applications that use a common component library. The top-level application and all the subordinate applications can share components that are stored in a common RSL.

• A family of applications on a server built with a common component library. When the user accesses the first application, they download an application SWF file and the RSL. When they access the second application, they download only the application SWF file (the client has already downloaded the RSL, and the components in the RSL are used by the two applications).

• A single monolithic application that changes frequently, but has a large set of components that rarely change. In this case, the components are downloaded once, while the application itself might be downloaded many times. This might be the case with charting components, where you might have an application that uses you change frequently, but the charting components themselves remain fairly static.

Cross-domain RSLs can be used by applications in any domain or sub-domain. The benefits of cross-domain RSLs are the same as standard RSLs, but they are not restricted to being in the same domain as the application that loads them. This lets you use the same RSL in multiple applications that are in different domains.

To use a cross-domain RSL that is located on a remote server, the remote server must have a crossdomain.xml file that allows access from the application's domain. The easiest way to do this is to add a crossdomain.xml file to the server's root. To ensure that applications from any domain can access the RSL SWF file, you can use an open crossdomain.xml file such as the following:

 <cross-domain-policy> 
 	<site-control permitted-cross-domain-policies="all"/> 
 	<allow-access-from domain="*" to-ports="*"/> 
 </cross-domain-policy>

This is not a best practice, however, because it allows requests from any domain to load the RSL, and other assets, from your server. You should instead restrict requests to only those domains that you trust by narrowing the entries in the domain attribute. You should also consider using a more restrictive meta-policy with the permitted-cross-domain-policies attribute. For more information, see Using cross-domain policy files.

You can store the crossdomain.xml file anywhere on the target server. When you compile a cross-domain RSL, you can specify the location of the crossdomain.xml file, and the application will look to that location to get permission to load the RSL. If you do not specify the location of the crossdomain.xml file when you compile your application, the application looks in the server's root directory by default.

Cross-domain RSLs can fail to load into an application under the following conditions:

• The server on which the RSL is located fails

• The network fails, so remote files cannot be loaded

• The digest of the RSL when the application was compiled does not match the digest of the RSL when it is loaded

• The policy file is absent from the RSL's server, or that server has a restrictive meta-policy

Cross-domain RSLs support a backup mechanism where a failover RSL can be loaded in the case of a server failure. If the server on which the main RSL fails, Flash Player will try to load a failover RSL whose location you specify when you compile the application.

To compile your application with standard or cross-domain RSLs you must extract the RSL SWF file from the SWC file yourself prior to deployment. In either case, when you deploy the RSL SWF file, you should optimize it as described in Optimizing RSL SWF files.

The default SWF file in your SWC files includes debugging code and metadata that increase the file size. The debugging code is necessary for the compiler to run, but is not necessary at run time unless you want to debug the RSL. You can remove the debug code and unnecessary metadata by using the optimizer tool. This should result in a smaller RSL.

If you use the optimizer tool, you must keep track of two separate library files: one for compiling (the larger, pre-optimized one) and one for deploying (the smaller, optimized one). You compile your main application against the non-optimized library but then deploy the optimized library so that it can be loaded at run time.

The optimizer tool is in the bin directory. For Unix and Mac OS, it is a shell script called optimizer. For Windows, it is optimizer.exe. You invoke it only from the command line. The Java settings are managed by the jvm.config file in the bin directory.

The syntax for the optimizer tool is as follows:

 optimizer -keep-as3-metadata Bindable Managed ChangeEvent  NonCommittingChangeEvent Transient -input input_swf -output output_swf

You must specify the keep-as3-metadata option and pass it the required metadata. At a minimum, you should specify the Bindable, Managed, ChangeEvent, NonCommittingChangeEvent, and Transient metadata names. You can also specify custom metadata that you want to remain in the optimized SWF file.

You can specify the configuration file that the optimizer tool uses by using the load-config option.

To get help while using the optimizer tool, enter the -help list advanced option:

optimizer -help list advanced

By default, the optimizer tool saves an optimized version of the SWF file in the current directory, with the name output.swf. This file should be smaller than the library.swf because it does not contain the debugging code.

This example walks you through the process of creating a library and then using that library as a standard and a cross-domain RSL with an application. It first shows you how to use a standard RSL, and then how to use that same RSL as a cross-domain RSL.

Keep in mind that a SWC file is a library that contains a SWF file that contains run-time definitions and additional metadata that is used by the compiler for dependency tracking, among other things. You can open SWC files with any archive tool, such as WinZip, and examine the contents.

Before you use an RSL, first learn how to statically link a SWC file. To do this, you build a SWC file and then set up your application to use that SWC file.

In this example you have an application named app.mxml that uses the ProductConfigurator.as and ProductView.as classes. The structure of this example includes the following files and directories:

 project/src/app.mxml 
 project/libsrc/ProductConfigurator.as 
 project/libsrc/ProductView.as  
 project/lib/ 
 project/bin/

To compile this application without using libraries, you can link the classes in the /libsrc directory using the source-path option, as the following example shows:

 cd project/src 
 mxmlc -o=../bin/app.swf -source-path+=../libsrc app.mxml

This command adds the ProductConfigurator and ProductView classes to the SWF file.

To use a library rather than standalone classes, you first create a library from the classes. You use the compc compiler to create a SWC file that contains the ProductConfigurator and ProductView classes, as the following command shows:

 cd project 
 compc -source-path+=libsrc -debug=false -o=lib/mylib.swc ProductConfigurator ProductView

This compiles the mylib.swc file in the lib directory. This SWC file contains the implementations of the ProductConfigurator and ProductView classes.

To recompile your application with the new library, you add the library with the library-path option, as the following example shows:

 cd project/src  
 mxmlc -o=../bin/app.swf -library-path+=../lib/mylib.swc app.mxml

This links the library at compile time, which does not result in any benefits of externalization. The library is not yet being used as an RSL. If you use the new library as an RSL, the resulting SWF file will be smaller, and the library can be shared across multiple applications.

Now you can recompile the application to use the library as an external RSL rather than as a library linked at compile time.

The first step is to compile your application with the runtime-shared-library-path option. This option instructs the compiler to specifically exclude the classes in your library from being compiled into your application, and provides a run time location of the RSL SWF file.

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

The next step is to prepare the RSL so that it can be found at run time. To do this, you extract the library.swf file from the SWC file with any archive tool, such as WinZip or jar.

The following example extracts the SWF file by using the unzip utility on the command line:

 cd project/lib 
 unzip mylib.swc library.swf 
 mv library.swf ../bin/myrsl.swf

This example renames the library.swf file to myrsl.swf and moves it to the same directory as the application SWF file.

The next step is to optimize the library.swf file so that it does not contain any debug code or unnecessary metadata. The following example optimizes the SWF file by using the optimizer tool:

 optimimzer -keep-as3-metadata Bindable Managed ChangeEvent NonCommittingChangeEvent Transient 
	-input bin/myrsl.swf -output bin/myrsl.swf

You now deploy the main application and the RSL. In this example, they must be in the same directory. If you want to deploy the myrsl.swf file to a different directory, you specify a different path in the runtime-shared-library-path option.

You can optionally run the optimizer tool on the myrsl.swf file to make it smaller before deploying it. For more information, see Optimizing RSL SWF files.

To use the RSL as a cross-domain RSL, you add a crossdomain.xml file, a failover RSL, and its crossdomain.xml file to the option, as the following example shows:

 cd project/src 
 	mxmlc -o=../bin/app.swf -runtime-shared-library-path=../lib/mylib.swc, 
 	http://www.my-remote-domain.com/rsls/myrsl.swf, 
 	http://www.my-remote-domain.com/rsls/crossdomain.xml, 
 	http://www.my-other-remote-domain.com/rsls/myrsl.swf, 
 	http://www.my-other-remote-domain.com/rsls/crossdomain.xml, 
 	Main.mxml

Next, you create a crossdomain.xml file. If the domain that are you running the application on is my-local-domain.com, then you can create a crossdomain.xml file that looks like the following:

 <cross-domain-policy> 
 	<site-control permitted-cross-domain-policies="all"/> 
 	<allow-access-from domain="*.my-local-domain.com" to-ports="*"/> 
 </cross-domain-policy>

You now deploy the main application and the RSL. This time, however, the RSL is deployed on a remote server in the /rsls directory. You must also ensure that the crossdomain.xml file is in that directory. Finally, you must ensure that the failover RSL and its crossdomain.xm l file are deployed to the other remote domain.