Programming Flex 3: Chapter 20, Embedding Flex Applications in a Browser
Pages: 1, 2, 3, 4, 5, 6, 7, 8, 9

Creating Runtime Shared Libraries with the Command-Line Compilers

When you want to create a runtime shared library with the command-line compilers, you need to use both the mxmlc application compiler and the compc component compiler. First you must use the compc compiler to compile all the common elements into an .swc file. An .swc is an archive format, and in the case of a runtime shared library it contains two files: library.swf and catalog.xml. The .swf file contained within the .swc is the runtime shared library file. You then use the mxmlc compiler to compile the application as usual, but this time you notify the compiler to dynamically link to the runtime shared libraries.

Note: Creating runtime shared libraries is an advanced feature. You may want to return to this section only after you're comfortable creating Flex applications and you want to optimize an application or applications that would benefit from runtime shared libraries.

Using compc

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 .

This excerpt is from Programming Flex 3. If you want to try your hand at developing rich Internet applications with Adobe's Flex 3, and already have experience with frameworks such as .NET or Java, this is the ideal book to get you started. Programming Flex 3 gives you a solid understanding of Flex 3's core concepts, and valuable insight into how, why, and when to use specific Flex features. Learn to get the most from this amazing and sophisticated technology.

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.