Library projects

You use SWC libraries in your projects in the following ways:

Merged into the application

When you add a SWC file to the project’s library path, the components contained in the library are available to use in your application. When you build the application, only the library components you actually used are compiled into the application SWF file. In other words, all of your application code is merged into a single SWF file. This is the most common and straightforward way of using library components.

External to the application

You can keep library components separate from the compiled SWF file, so they are not merged into the file. The compiler resolves all code contained in the library that is used by the application, but does not merge the code into the application SWF file. The advantage of this approach is that you make the application SWF file smaller. The components contained in the SWC file are retrieved and loaded into memory as needed, at run time.

Runtime Shared Library

In Flex projects only, you can also use SWC files as a Runtime Shared Library (RSL), which is similar to a dynamically linked library on other platforms. Use SWC files as an RSL when you have a collection of components that are used by more than one application.

There are several advantages to sharing components between applications by using an RSL. First, the library is loaded into memory once, cached, and then available to all the applications that use those components. Second, the components contained within the library are only loaded when they are needed, which reduces the application’s start-up time because the size of each application is smaller. The potential problem to this approach is that the entire RSL is loaded into memory, rather than the individual components that the applications use. For more information about when to use SWC files as an RSL, see Using Runtime Shared Libraries.

When you create a library project, the New Flex Library Project wizard guides you through the steps, prompting you for the project name, location, and build path information. After you create the Library project, you add components, specify the library project elements to include in the SWC file, and then build the project to generate the SWC file. The first step in creating a SWC file in Flash Builder is to create a Flex Library project.

1. Select File > New > Flex Library Project.

2. Enter a Project name, and then specify the following:

   Project Location

   The default location is the current workspace. On Windows platforms, the default workspace location is C:\Documents and Settings\Flex Developer\Adobe Flash Builder\. On the Macintosh, the default workspace location is /Users/Flex Developer/Adobe Flash Builder/. You can choose a different project location by deselecting the Use Default Location option.

   Flex SDK Version

   Choose default or specific. You can also click the Configure SDKs link to add, edit, or remove SDKs on the main Preferences page.

   Include Adobe AIR libraries

   Select this option if your library must use AIR features, such as access to the AIR APIs. Flash Builder then changes the library path of this new Flex Library project so that it includes airglobal.swc and airframework.swc. Web-based Flex projects cannot use this library.

   Do not select this option if you are writing a generic library intended to be used only in a web-based Flex application, or in either a web-based or AIR-based application.

3. Click Next.

4. (Optional) Set the build path information. For example, you can add folders to the project’s source path that contains the components to include in the SWC file. You can also add other projects, folder, or library SWC files to include in your library project. See Using SWC files in your projects.

5. When you finish entering the project settings, click Finish.

You add components to the library project in the following ways:

• Add new or existing custom components, ActionScript classes, and other assets to the project.

• Link to existing components in other projects in the workspace. (See Linking to resources outside the project workspace.)

• Add a linked folder that contains components to the library project’s source path. (See Adding resource folders to the project source path.)

The next step in creating a library SWC file is to select the elements (components and resources) to include in the SWC file when it is built by the compiler.

1. Select Project > Properties > Flex Library Build Path.

   The components that you added to the project (either directly or by linking to them) appear in the Classes tab.

2. Select the component classes to include in the SWC file.

3. (Optional) Select the Resources tab and then select the resources to include in the SWC file.

4. After you make your selections, click OK.

After you select elements to include in the SWC file, and if you selected the Build Automatically option, the SWC file is immediately compiled and generated into the project’s output folder. If you build your projects manually, you can build the library project when you want by selecting Project > Build Project or Build All.

Building your library project generates a SWC file, which you can share with other applications or users.

A SWC file is an archive file. You can open the SWC file in any archive utility, such as WinZip. Inside the SWC file are the library.swf and catalog.xml files. There also are properties files and other embedded assets.

You can export the library as an open directory rather than as a SWC file. You typically export a library as an open directory when you plan on using the library.swf file inside the SWC file as an RSL.

You do this by setting the directory and output compiler options. You set the output option to the name of a directory to create, and set the directory option to true to indicate that you want an open directory and not a SWC file when you build the library. To edit the compiler options, select Project > Properties > Flex Library Compiler, and add the options to the “Additional compiler arguments” field; for example:

-directory=true -output=myOpenDir 

Flash Builder creates a directory in the project named myOpenDir and stores the contents of the SWC file in that directory.

To use SWC files in your Flex projects, you add them to the project’s library path. The SWC files can be located in the project, in a Flex library project, in a shared folder within the workspace, or any other location that has been linked to the project (using a shared folder that was added to the project’s source path, for example).

When you use SWC files in applications, there are configuration options that determine whether they are statically or dynamically linked to the application, merged into the application SWF file, or external to it and accessed separately at run time.