Chapter 6. Packaging and Installing Applications-P1
The previous chapters covered the basic parts of building an application.
Now that you've seen how to create an application with XUL, CSS, and
JavaScript that can be used on your local computer, we will show you how
to turn your program into something that can be installed by other users.
This chapter discusses the technologies Mozilla provides for packaging and
installing applications.
Until your project is packaged for distribution, it can't be fully considered a
finished application (unless it was designed to work only on the computer
where it was created). Making your application distributable, installable, and
registrable allows others to use what you have created.
This chapter is divided into four main sections. It starts with a quick
overview of the basics of packaging and installing applications. The second
section provides details about how to get your application packaged and
described so that Mozilla recognizes what it is. The next section specifies
how to put your package into a cross-platform installation file that can be
installed over the Web onto other machines. The last section provides tips
for customizing how your application will look once it is installed.
6.1. Packaging and Installing Overview
Several different pieces comprise Mozilla's distribution technology. In fact,
Mozilla may have a few more moving parts than other packaging systems
because it needs a way to package and install new software uniformly across
several different platforms. Figure 6-1 shows the major components of
Mozilla's packaging system outlined in black.
Figure 6-1. Mozilla packaging components

As you can see in Figure 6-1, the Cross-Platform Installer (XPI), pronounced
zippy or X-P-I, is the archive format used to distribute Mozilla applications.
The XPI file contains a script that downloads and installs the application.
The package inside the XPI has a manifest that is used to register the new
Mozilla-based software with the Mozilla chrome registry.
When a XPI contains a Mozilla-based package such as the xFly sample
discussed in Chapter 2 and the following chapters, the installation script also
takes care of the package registration process, described in the Section 6.2.2
section later in this chapter. Example 6-1 shows a simple installation script
and the kind of information it contains. The Section 6.3.2 section, also later
in this chapter, discusses other scripts that may need to be used in the
installation process, such as trigger scripts.
Example 6-1. Package installation script

if (0 == getLastError( )) // if there have
been no errors:
performInstall( ); // install
"xfly.jar"
else // otherwise
cancelInstall( ); // cancel the
installation.
The installation process requires a few different steps. First an installation
must be initialized. Then the software to be installed is added to the
specified target directory. Finally, packages in the installation are registered.
At this point, the application is installed on a user's computer.
When you install new packages or Mozilla-based software, the chrome
registry on the Mozilla side brokers the deal -- reading the manifest,
executing the installation script(s), and updating the package information
that it maintains internally (storing this information using RDF).
The relationship of the packaging, installation, and registration -- and all
pieces involved -- may seem a little complex and idiosyncratic at first, but
bear with it. The upshot of this powerful but somewhat diffuse packaging
technology is that you can bundle your software, put it on a server, and have
users install it by simply clicking a link on a web page when using Mozilla.
It is possible to use this packaging system to bundle any sort of application
or extension to an existing Mozilla application. You can install a XPI that
adds functionality to the Mozilla browser, such as Mouse Gestures
(http://optimoz.mozdev.org/gestures/ ), which enables the execution of
common browser commands with mouse movements. You can package new

Mozilla development tools and libraries like JSLib (see Chapter 5). You can
also create installations for entirely new Mozilla applications.
6.2. Packaging Mozilla Applications
Packaging simply means organizing your files into a Mozilla application
structure. Packaging your application is required to make it installable and to
make it something that Mozilla recognizes as one of its own. Whether your
Mozilla-based becomes a part of an existing Mozilla application, like Mouse
Gestures, or will exist as a standalone application, like JabberZilla, you will
need to package it.
When you are done with this packaging section, package your Mozilla-based
applications in the same way that we packaged the xFly example in Chapter
2. This chapter describes the manifests and other necessary files. Then the
Installation section shows how you can put your package in a XPI file and
create installation script(s) so it can be distributed and installed.
6.2.1. Package Manifests
All new packages must have manifests describing their contents, skin
information, and locale information. These manifests are formatted in RDF,
which makes them easy to combine with the RDF data that makes up the
chrome registry and makes it easy to fit the package into the Mozilla
software. There is some flexibility about where in the package the manifest
must appear, but the registration process must find and read it regardless of
where it is.
The installation script points out the manifest locations so the package can
be registered properly. Note that manifests appear in JARs, but they do not

appear in XPIs, since the latter is a temporary file that gets deleted once the
files it contains, including JARs, are installed (see the Section 6.3 section
later in this chapter for more information about XPI install files).
6.2.1.1. Theme package manifests
Example 6-2 shows a manifest for a new theme to be installed in Mozilla. It
is simple because it describes only one type of package, the "fly skin," and
the existing component it interacts with, the communicator -- the default
Mozilla browser (the syntax and structure is the same for all manifests,
however). The manifest says, in effect, this is what I have here (the metadata
about the theme -- its name, a description, etc.), and this is what it affects
(the list of chrome:packages to which the theme should be applied).
Example 6-2. Simple theme package manifest

6.2.1.2. Language pack manifests
When you look at a package manifest that describes a new locale, as shown
in Example 6-3 (which is for a German language pack in Mozilla), you see a
similar structure. Again, the manifest describes the new package first and
then lists the existing components to which this new package applies.
Example 6-3. Locale package manifest

Note that in Example 6-3's package manifest, all major components are
affected by this new locale package. When the package is installed and the
manifest is read, the chrome registry is made aware of a German language
pack that it can use to display German in the interface of each Mozilla
component.
contents.rdf Type Manifests
Package manifests are an area where Mozilla browser itself may not be the
best model for learning about the best application development practice.
Mozilla is such a large and modular application that it uses several manifests
instead of one application-wide manifest.rdf file.
Although they have the same format, these distributed manifests are found in

several contents.rdf files. In a single theme (e.g., the modern.jar),
you can see as many as eight manifests (for major component to which the
theme applies).
These two types of manifests -- the contents.rdf file, which typically
describes a single package-component relationship; and the
manifest.rdf file, which describes the package's relationship to all
affected components -- are functionally equivalent. In both cases, the
chrome registry reads all RDF/XML data and registers the package.
Because the manifest data format is RDF/XML, you can use either type of
manifest in your own package development, although using a single
manifest.rdf is generally much easier, especially if you want to
change the list of affected components of any other metadata later.
The package manifests for content and new applications -- which may
include new content, skin, and locale information -- have an identical syntax
and a very similar structure, as you will see in the following sections. The
manifest for a full Mozilla-based application like xFly describes the content,
the skin, and the locale in a single file that sits at the top of that package.
6.2.1.3. Application manifests
When you create new applications on top of Mozilla, you will often create
new content, new skins, and your own localizable language elements, such
as DTDs. For applications, the manifest must describe these parts of your
application if Mozilla is to find and register them properly.

Example 6-4, the package manifest from the XMLTerm Mozilla extension,
describes the contents, skin, and locale in a single file, which is most
common for Mozilla-based applications.
Example 6-4. manifest.rdf describing the XMLTerm extension

The structure in Example 6-4 is exactly the same as that in more focused
manifests (Example 6-2 and Example 6-3), but all of the skin, content, and
locale structures sit together in a single manifest.rdf file. This manifest
follows the Mozilla convention of introducing the package contents at the
top and then expanding upon the basic listing of each separate sections,
providing the necessary metadata about the items in the middle, and then
listing the components that are affected by the items at the end. However,
the flexibility of the RDF format means you could just as easily order this
information differently -- which is why RDF is sometimes described as
creating a "soup" of statements about resources.
Note that the overlay section in the middle of the example is part of the
content description. It tells the chrome registry that the contents of the file
xmltermOverlay.xul should be overlaid into the
tasksOverlay.xul file in Mozilla, in which much of the Tools menu is
defined. The package manifest for the xFly sample application that we
discuss here, also a single file, is very similar to the manifest in Example 6-
4.
6.2.2. Registering Packages
Typically, registration occurs during installation, which is why the Section
6.3 section of this chapter goes into more detail about the specific methods
and objects available for package registration. The registration process deals

with packages and package manifests, however, so the following two
sections describe the two types of package registration that are possible in
Mozilla. The first provides an overview of how to register a package on
installation, as is typically done, and the second describes how to use a
special file to register your work with Mozilla as you develop it so that you
can view your work as it progresses.
6.2.2.1. Registering packages on installation
Generally, the registration process is a transaction that takes place between
your installation scripts, the chrome registry, and the manifests that describe
the package. Usually, registration happens upon installation. You can
approach this transaction in many ways, but the general relationship is
shown in Figure 6-2.
Figure 6-2. Package interaction overview

In this relationship, the install script is responsible for managing the transfer
of files to a specified location on the local disk and alerting the chrome
registry to the new files and their manifests. The chrome registry then finds
and reads those manifests. If the information there is formatted correctly,
then that information is added to the sum of package information that the
chrome registry manages -- a single, overarching datasource of all packages
in Mozilla, including skins, locales, overlays, and other software. In this
way, the package is added to Mozilla. The major players in this interaction
between the packages, the package descriptions, and the chrome registry are
shown in the following list.
• Manifests in the archives themselves
• XPInstall, the technology that performs the downloading and resource
installation
• The chrome registry, the database of packages, and user information
that is read and written to when new software is installed
6.2.2.2. Registering packages as you develop them (installed-
chrome.txt)
The file installed-chrome.txt is a convenience for developers who
want to create and test new packages without having to install them with
installation scripts and manifests. Some earlier xFly examples in this book
already used this method. The installed-chrome.txt file is a list of
entries that point to package manifests. Each line provides the chrome
registry with a pointer to a manifest in which new software is described: new
skin information, new packages, and new locales.

In the following snippet from the installed-chrome.txt file in the
Mozilla chrome directory, five entries point to contents.rdf type
manifests that describe the modern skin resources particular to the
application's major components. The first line in this list, for example, tells
the chrome registry to find a contents.rdf file in the subdirectory
skin/modern/communicator contained in the modern.jar file,
which describes the resources present there to skin the communicator
component. When the chrome registry reads this line, it uses those resources
to skin the communicator component, shown here:
skin,install,url,jar:resource:/chrome/modern.jar!/s
kin/modern/communicator/
skin,install,url,jar:resource:/chrome/modern.jar!/s
kin/modern/editor/
skin,install,url,jar:resource:/chrome/modern.jar!/s
kin/modern/global/
skin,install,url,jar:resource:/chrome/modern.jar!/s
kin/modern/messenger/
skin,install,url,jar:resource:/chrome/modern.jar!/s
kin/modern/navigator/
Instead of installing your package with installation scripts, you can add the
appropriate entries to this file, as seen in the following examples. Adding
these entries only registers local content on your machine. When you use the
installed-chrome.txt file, you neither install a new package nor
make that package installable by others. Editing the installed-
chrome.txt file directly is a shortcut for making Mozilla aware of

packages so that you can check your progress as you develop. You probably
need to create an installer for packages you want to distribute and install on
other systems.
To register a local copy of the xFly application with the Mozilla chrome
directory, you would add the following three entries, where the xFly
directory and the appropriate subdirectories sit directly under the chrome
directory:
content,install,url,resource:/chrome/xfly/content/
skin,install,url,resource:/chrome/xfly/skin/
locale,install,url,resource:/chrome/xfly/locale/en-
US/
The first line tells the chrome registry that the content is found in the
directory chrome/xfly/content. The next line points to the skin
resources at chrome/xfly/skin, and so on. Note that creating a single
entry for the xFly skin and locating its resources underneath the xFly
application directory (as opposed to a subdirectory in the modern and/or
classic JARs) means that the xFly skin will not change when the user
changes skins.
If we had the same structure archived in a JAR file called xfly.jar rather
than in a directory, the installed-chrome.txt entries would look like
this:
content,install,url,jar:resource:/chrome/xfly.jar!/
content/

skin,install,url,jar:resource:/chrome/xfly.jar!/ski
n/
locale,install,url,jar:resource:/chrome/xfly.jar!/l
ocale/en-US/
This code tells the chrome registry to look in the content, skin, and
locale/en-US directories in the JAR file to locate the manifests.
This skin entry seems to indicate that only one set of skin information is
available for the xFly sample, and that it always applies. If the xFly skin
inherits, as many skins do, from one or another of the preinstalled theme
(e.g., Modern), it may look very bad or even break when that theme is not
selected. See the section Section 4.3.1.1 in Chapter 4 for a discussion of skin
inheritance and tips on how to make sure your skin is structured to best take
advantage of it.
When you make these additions to the installed-chrome.txt file and
restart Mozilla, the chrome registry looks for manifests in the directories you
specify and registers the packages described there. The installed-
chrome.txt entries in this section do not necessarily need to be included
on your final XPI resource, but you will see them in some XPIs bundled in
their own installed-chrome.txt file separate form the main one. See
the section Section 6.2.4 for more information about this process.
6.2.3. Creating a Package
The xFly sample package is a relatively straightforward arrangement of
content, skin, and locale. You have already seen how to set up most
preliminaries you need to make it a package in Chapter 2, but this section
will discuss the process in detail.

6.2.3.1. Setting up xFly
To start working immediately with tools like XUL and CSS, you can move
some things around and hack one of the chrome registry files, as you have
already seen. This section reviews those important preliminary application
development steps in more detail.
Because it has its own interface and is not worried (for now) about being
made available in languages other than English, the only one for which it has
a language pack, the xFly package is self-contained:
chrome
xfly
content
skin
locale
All parts of the package can be held in a single JAR file or a single chrome
subdirectory. Contrast this with a large component-like communicator that,
when you include its content, skin, localized information, and the Mozilla
services it uses via XPConnect, is spread out into all of the main JAR files
that make up the distribution:
chrome/modern.jar!/skins/modern/communicator/
chrome/comm.jar!/content/communicator/
chrome/en-US.jar!/locale/en-US/communicator/
When you develop your application, it's typical to work within a regular
directory. As you finish the application and make it available for