Like the mxmlc compiler, the compc compiler has options that you can use to determine what gets compiled and how. The first option you’ll need to specify is source-path, which tells the compiler where to look for the files you want to compile. If you are compiling classes in packages, the source-path should be the root directory of the packages. If you want to use the current directory you must still specify a value, using a dot. If you want to use more than one directory, you can list the directories delimited by spaces.

You must compile one or more classes into a runtime shared library. You have to list each class using the include-classes option. There is no option to simply include all the classes in a directory. You must list each class individually. You must list each class using the fully qualified class name, and you can list multiple classes by separating them with spaces.

You must also specify an output file when calling compc. Use the output option, and specify the path to an .swc file that you want to export. The following example compiles the class com.oreilly.programmingflex.A into an .swc file called example.swc:

compc -source-path . -include-classes com.oreilly.programmingflex.A
-output example.swc

Compiling many classes into a runtime shared library can result in a very long command. To simplify this you can use either configuration files or manifest files.

Like mxmlc, you can use configuration files with compc by specifying a load-config option. Also like mxmlc, the compc compiler automatically loads a default configuration file called flex-config.xml, and unless you want to duplicate all the contents of flex-config.xml (much of which is required), it generally is better to specify a configuration file in addition to the default by using the += operator, as in the following example:

compc -load-config+=configuration.xml

The following example configuration file is the equivalent of the earlier command, which specified the source path and output, and included classes from the command line:

<flex-config>
  <compiler>
    <source-path>
      <path-element>.</path-element>
    </source-path>
  </compiler>
  <output>example.swc</output>
  <include-classes>
    <class>com.oreilly.programmingflex.A</class>
  </include-classes>
</flex-config>

If you want to include many classes, you can simply add more <class> nodes, as in the following example:

<flex-config>
  <compiler>
    <source-path>
      <path-element>.</path-element>
    </source-path>
  </compiler>
  <output>example.swc</output>
  <include-classes>
    <class>com.oreilly.programmingflex.A</class>
    <class>com.oreilly.programmingflex.B</class>
    <class>com.oreilly.programmingflex.C</class>
    <class>com.oreilly.programmingflex.D</class>
  </include-classes>
</flex-config>

You can use manifest files to achieve the same result of simplifying the compiler command. However, manifest files also have an added benefit in that they allow you to create a namespace for components that you compile into the runtime shared library. This is more useful when the runtime shared library contains user interface components that you want to be able to add to an application using MXML tags. However, using a manifest file is not hurtful in any case, because it lets you simplify the compiler command.

A manifest file is an XML file in the following format:

<?xml version="1.0"?>
<componentPackage>
    <component id="Identifier" class="ClassName"/>
</componentPackage>

The following example will tell the compiler to add classes A, B, C, and D to the library:

<?xml version="1.0"?>
<componentPackage>
    <component id="A" class="com.oreilly.programmingflex.A"/>
    <component id="B" class="com.oreilly.programmingflex.B"/>
    <component id="C" class="com.oreilly.programmingflex.C"/>
    <component id="D" class="com.oreilly.programmingflex.D"/>
</componentPackage>

Once you’ve defined a manifest file, you need to tell the compiler to use the file. You can achieve that with the namespace and include-namespaces options. A namespace is an identifier that you can use within your MXML documents that will map to the manifest file contents. The namespace option requires that you specify two values: first the namespace identifier and then the manifest file to which the identifier corresponds. The include-namespaces option requires that you list all the identifiers for which you want to compile the contents into the .swc file. The following example compiles the classes specified in manifest.xml into the .swc:

compc -namespace http://oreilly.com/programmingflex manifest.xml
-include-namespaces http://oreilly.com/programmingflex -output example.swc

You can also combine the use of a manifest file with a configuration file. The following configuration file uses the manifest file:

<flex-config xmlns="http://www.adobe.com/2006/flex-config">
  <compiler>
    <source-path>
      <path-element>.</path-element>
    </source-path>
    <namespaces>
      <namespace>
        <uri>http://oreilly.com/programmingflex</uri>
        <manifest>manifest.xml</manifest>
      </namespace>
    </namespaces>
  </compiler>
  <output>example.swc</output>
  <include-namespaces>
    <uri>http://oreilly.com/programmingflex</uri>
  </include-namespaces>
</flex-config>

When you use a runtime shared library, you’ll need two files: the .swc and the library .swf file contained within the .swc file. You need the .swc file because the mxmlc compiler uses the .swc file to determine which classes to dynamically link. You need the .swf file because it’s the file you deploy with the application and from which the application loads the libraries. The SWC format is an archive format—essentially a ZIP format. You can use any standard unzip utility to extract the .swf file from the .swc. The .swc always contains a file called library.swf that you should extract and place in the deploy directory for the application. If you plan to use several runtime shared libraries with an application, you need to either place the library.swf files in different subdirectories or rename the files.

Once you’ve compiled an .swc file containing a runtime shared library and extracted the .swf file, you next need to compile the application that uses the library. To accomplish that you’ll use mxmlc in much the same way as you’d compile an application that uses only static linking. However, when you use a runtime shared library, you need to dynamically link the relevant classes in the main application and tell the application where to find the runtime shared library .swf file at runtime. The external-library-path option specifies the .swc file or files that tell the compiler which classes to dynamically link. Use the runtime-shared-libraries option to tell the compiler where it can find the runtime shared library file(s) at runtime. The following tells the compiler to compile the application using example.swc for dynamic linking and example.swf as the URL for the shared library:

mxmlc -external-library-path=example.swc
-runtime-shared-libraries=example.swf Example.mxml

You can use configuration files for these purposes as well. The following configuration file achieves the same result as the preceding command:

<flex-config>
  <compiler>
    <external-library-path>
      <path-element>example.swc</path-element>
    </external-library-path>
  </compiler>
  <file-specs>
    <path-element>RSLClientTest.mxml</path-element>
  </file-specs>
  <runtime-shared-libraries>
    <url>example.swf</url>
  </runtime-shared-libraries>
</flex-config>

When you deploy the application, you must also deploy the runtime shared library .swf file. You do not need to deploy the .swc file along with the rest of your application.

As you’ve seen, building an application that uses a runtime shared library requires quite a few steps. To summarize:

Using Ant can simplify things because you can write just one script that will run all the tasks. The following is an example of such a script:

<?xml version="1.0"?>
<project name="RSLExample" basedir="./">

  <property name="mxmlc" value="C:FlexSDKinmxmlc.exe"/>
  <property name="compc" value="C:FlexSDKincompc.exe"/>

  <target name="compileRSL">
    <exec executable="${compc}">
      <arg line="-load-config+=rsl/configuration.xml" />
    </exec>
    <mkdir dir="application/rsl" />
    <move file="example.swc" todir="application/rsl" />
    <unzip src="application/rsl/example.swc" dest="application/rsl/" />
  </target>

  <target name="compileApplication">
    <exec executable="${mxmlc}">
      <arg line="-load-config+=application/configuration.xml" />
    </exec>
  </target>

  <target name="compileAll" depends="compileRSL,compileApplication">
  </target>

</project>

The first step in creating a Flex Library Project is to create the project by selecting File→New→Flex Library Project. Every Flex Library Project needs to have at least one element—generally a class. You can add classes to the project as you would any standard Flex project. Once you’ve defined all the files for the project, you’ll next need to tell Flex Builder which of those classes to compile into the .swc file. You can do that by way of the project properties. You can access the properties by selecting Project→Properties. Then select the Flex Library Build Path option from the menu on the left of the dialog. In the Classes tab you should select every class that you want to compile into the library. This is all that is necessary to create a Flex Library Project.

When you want to use a library from a Flex application, you need to tell Flex Builder to link to the corresponding Flex Library Project. You can accomplish this by selecting Project→Properties for the Flex project. Then select the Flex Build Path option from the menu in the dialog, and select the “Library path” tab. Within the “Library path” tab you click the Add Project button. This opens a new dialog that prompts you to select the Flex Library Project you want to link to your application. When you select the library project and click OK, the project will show up in the “Library path” tab list. By default, libraries are statically linked rather than dynamically linked. You must tell Flex Builder to dynamically link the library by expanding the library project icon in the list, selecting the Link Type option and then selecting the Runtime Shared Library (RSL) option from the menu.

When you add a library project to the library path for a Flex project, the application can use any of the classes defined in the library project.