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

If you have multiple applications but those applications share a core set of components or classes, clients can download those assets only once as an RSL rather than once for each application. The RSLs are persisted on the client disk so that they do not need to be transferred across the network a second time. The resulting file size for the applications can be reduced. The benefits increase as the number of applications that use the RSL increases.

Flex applications support the following types of RSLs:

• Standard RSLs -- A library of custom classes created by you to use across applications that are in the same domain. Standard RSLs are stored in the browser's cache. For more information, see About standard RSLs.
• Cross-domain RSLs -- A library of custom classes, like standard RSLs, with the difference being that they can be loaded by applications in different domains and sub-domains. Cross-domain RSLs are stored in the browser's cache. For more information, see About cross-domain RSLs.
• Framework RSLs -- Precompiled libraries of Flex components and framework classes that all applications can share. Framework RSLs are precompiled for you. For more information, see Using the framework RSLs.

You can create your own RSLs from custom libraries. You do this by using either the Adobe® Flex® Builder's™ Build Project option for your Flex Library Project or the compc command-line compiler.

About linking

Understanding 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. Static linking is the most common type of linking when compiling a Flex 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.

In Flex Builder, you use the Project > Properties > Flex Builder Path > Library Path dialog to add libraries to your project. To statically link a library at compile time, you select Merged Into Code for the library's Link Type. This includes only those classes that are used in the application, so it is the equivalent of the library-path compiler option.

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 and runtime-shared-libraries 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. Theruntime-shared-library-path option provides all the arguments to use external libraries as RSLs.

In Flex Builder, to use dynamically-linked libraries, you specify either RSL or External as the Link Type in the Library Path dialog for the library.

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 Using the Flex Compilers.

RSL benefits

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 Flex applications that use a common RSL, the greater the benefit.

RSL considerations

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 a Flex 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 a Flex 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.

About caching

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 Flex application without the need for a cross-domain policy file.