Library projects

Library projects let you build custom code libraries that you can share between your applications or distribute to other developers. A library project generates a SWC file, which is an archive file for Flex components and other resources. For example, the Flex framework is contained in SWC files. When you create a Flex project, the Flex framework SWC files are added to the project’s library path. You can view and edit the library path by accessing the project’s build path properties page (for Flex projects, select Project > Properties > Flex Build Path).

Archived into a SWC file is a SWF file that contains components and resources and a catalog.xml file that is the manifest of the elements contained within the SWF file. Typically, the SWF file contains one or more components and any other required resources. Adding the library to a project lets you use those components in your application and also enables code hinting for those components.

In addition to providing a convenient way to package and distribute components, SWC libraries are used as themes, the visual appearance of Flex applications. A SWC theme file contains a CSS file and all the related graphic assets. For more information about creating and using themes, see About themes.

Libraries are useful if you create components entirely in ActionScript and use them in Design mode in Flash Builder. ActionScript components are not visually rendered in Design mode until they are compiled into a SWF file. By adding ActionScript components to a library project, you create a SWF file that is contained in a SWC file. You can add the library to a project’s library path, and the ActionScript components visually render in Design mode when you add them to the application.

Configuring libraries for your applications

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.

Creating Flex library projects

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.

Adding components to the library project

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

Note: All the components you include in the library project must be associated with the library project (directly or as linked resources).

Selecting library project elements to include in the SWC file

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.

Building library projects

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.

Using SWC files in your projects

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.

Add an SWC file to the library path

  1. With a project selected in the Package Explorer, select Project > Properties > Flex Build Path.

  2. Click on the Library Path tab.

  3. Select any of these options to add SWC files:

    Add Project
    Adds a Flex library project.

    Add SWC Folder
    Lets you add a folder that contain SWC files.

    Add SWC
    Adds a compiled SWC file.

    Add Flex SDK
    Lets you add other Flex SDKs. If your project already has a Flex SDK in its library path, this button is disabled. If you remove the existing Flex SDK from your library path, the button is enabled. When you click this button, a Flex SDK node is added, but you are not prompted which one is added. To control which Flex SDK to use, select Project > Properties > Flex Compiler.

  4. Enter or browse to and select the location of the SWC file, project, or folder. Click OK.

    The SWC file, library project, or folder is added to the library path.

Merge the SWC file into the application SWF file when compiled

  1. With a project selected in the Package Explorer, select Project > Properties > Flex Build Path.

  2. Click on the Library Path tab, and then select and expand the SWC file entry to display the SWC options.

  3. Double-click the Link Type option. The Library Path Items Options dialog box appears.

  4. Select the Merged into Code option, and click OK.

This procedure is the equivalent of using the library-path compiler option.

Set the SWC file as an external library file

  1. With a project selected in the Package Explorer, select Project > Properties > Flex Build Path.

  2. Select the Library Path tab, and then select and expand the SWC file entry to display the SWC options.

  3. Double-click the Link Type option. The Library Path Items Options dialog box appears.

  4. Select the External option, and click OK.

This procedure is the equivalent of using the external-library-path compiler option.

Use the SWC file as an RSL

  1. With a project selected in the Package Explorer, select Project > Properties > Flex Build Path.

  2. Select the Library Path tab, and then select and expand the SWC file entry to display the SWC options.

  3. Double-click the Link Type option. The Library Path Items Options dialog box appears.

  4. Select the Run-time Shared Library (RSL) option.

  5. Enter the URL where the SWC library will reside when the application is deployed.

  6. (Optional) To extract the SWF file in the SWC file when it is placed in the deploy location, select the Automatically Extract SWF to Deployment Path option.

  7. Click OK.

Using the SWC files as an RSL simplifies the process for using RSLs manually. To do this, you extract the SWF file from the SWC file and set the values of the runtime-shared-library-path compiler option.

For more information about using SWC files as an RSL, see Using Runtime Shared Libraries in Building and Deploying Adobe Flex3 Applications.