Diff for /books/www/chapters/ch06.html between versions 1.1 and 1.2

version 1.1, 2002/09/17 21:10:35 version 1.2, 2002/09/23 15:23:31
Line 11 Line 11
 <I>Mozilla packaging components</I>  <I>Mozilla packaging components</I>
   
 <P>As you can see in <A HREF="#77002">Figure 6-1</A>, the  <!--INDEX XPI (Cross-Platform Installer);distribution:XPI --> 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.  <P>As you can see in <A HREF="#77002">Figure 6-1</A>, the  <!--INDEX XPI (Cross-Platform Installer);distribution:XPI --> 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.
<P>When a XPI contains a  <!--INDEX packages:installation script;XPI (Cross-Platform Installer):package installation script --> Mozilla-based package such as the xFly sample discussed in <A HREF="ch02.htm#77048">Chapter 2</A> and the following chapters, the installation script also takes care of the package registration process, described in the <A HREF="#77070">"Registering Packages</A>" section later in this chapter. <A HREF="#77020">Example 6-1</A> shows a simple installation script and the kind of information it contains. The <A HREF="#77085">"Installation Scripts</A>" section, also later in this chapter, discusses other scripts that may need to be used in the installation process, such as trigger scripts.<P>When a XPI contains a  <!--INDEX packages:installation script;XPI (Cross-Platform Installer):package installation script --> Mozilla-based 
 package such as the xFly sample discussed in <A HREF="ch02.html#77048">Chapter 2</A> and the following chapters, the installation script also takes care of the package registration process, described in the <A HREF="#77070">"Registering Packages</A>" section later in this chapter. <A HREF="#77020">Example 6-1</A> shows a simple installation script and the kind of information it contains. The <A HREF="#77085">"Installation Scripts</A>" section, also later in this chapter, discusses other scripts that may need to be used in the installation process, such as trigger scripts.
   
 <P><I>Example 6-1: <A NAME="77020"></A></I>  <P><I>Example 6-1: <A NAME="77020"></A></I>
 <I>Package installation script</I>  <I>Package installation script</I>
Line 36 Line 37
 <P>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  <!--INDEX registration:packages;packages:registration;installation:packages:registration --> are registered. At this point, the application is installed on a user's computer.  <P>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  <!--INDEX registration:packages;packages:registration;installation:packages:registration --> are registered. At this point, the application is installed on a user's computer.
 <P>When you install new packages or  <!--INDEX chrome:registry, package installation --> 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).  <P>When you install new packages or  <!--INDEX chrome:registry, package installation --> 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).
 <P>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.  <P>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.
<P>It is possible to use this  <!--INDEX bundling, packaging and;packages:bundling and --> 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  <!--INDEX XPI (Cross-Platform Installer):Mouse Gestures;Mouser Gestures --> as Mouse Gestures (<I><A HREF="http://optimoz.mozdev.org/gestures/">http://optimoz.mozdev.org/gestures/</A> </I>), which enables the execution of common browser commands with mouse movements. You can package new Mozilla development tools and libraries like JSLib (see <A HREF="ch05.htm#77037">Chapter 5</A>). You can also  <!--INDEX ENDRANGE--packaging:overview;installation:overview --> create installations for entirely new Mozilla applications.<P>It is possible to use this  <!--INDEX bundling, packaging and;packages:bundling and --> 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  <!--INDEX XPI (Cross-Platform Installer):Mouse Gestures;Mouser Gestures --> as Mouse Gestures (<I><A HREF="http://optimoz.mozdev.org/gestures/">http://optimoz.mozdev.org/gestures/</A> </I>), which enables the execution of common browser commands with mouse movements. You can package new Mozilla development tools and libraries like JSLib (see <A HREF="ch05.html#77037">Chapter 5</A>). You can also  <!--INDEX ENDRANGE--packaging:overview;installation:overview --> create installations for entirely new Mozilla applications.
 <H2><A NAME="77065"></A> Packaging Mozilla Applications</H2>  <H2><A NAME="77065"></A> Packaging Mozilla Applications</H2>
 <P><I>Packaging</I> simply  <!--INDEX packaging:Mozilla applications;applications:packaging --> 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.  <P><I>Packaging</I> simply  <!--INDEX packaging:Mozilla applications;applications:packaging --> 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.
<P>When you are done with this packaging section, package your Mozilla-based applications in the same way that we packaged the xFly example in <A HREF="ch02.htm#77048">Chapter 2</A>. 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.<P>When you are done with this packaging section, package your Mozilla-based applications in the same way that we packaged the xFly example in <A 
 HREF="ch02.html#77048">Chapter 2</A>. 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.
 <H3><A NAME="77066"></A> Package Manifests</H3>  <H3><A NAME="77066"></A> Package Manifests</H3>
 <P>All new packages  <!--INDEX packages:manifests;manifests: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.  <P>All new packages  <!--INDEX packages:manifests;manifests: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.
 <P>The installation script points out the manifest locations so the package can be registered properly. Note that  <!--INDEX JAR (Java Archive) files:manifests --> 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 <A HREF="#77081">"Installing Mozilla Applications</A>" section later in this chapter for more information about XPI install files).  <P>The installation script points out the manifest locations so the package can be registered properly. Note that  <!--INDEX JAR (Java Archive) files:manifests --> 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 <A HREF="#77081">"Installing Mozilla Applications</A>" section later in this chapter for more information about XPI install files).
Line 197  locale,install,url,resource:/chrome/xfly Line 200  locale,install,url,resource:/chrome/xfly
 skin,install,url,jar:resource:/chrome/xfly.jar!/skin/  skin,install,url,jar:resource:/chrome/xfly.jar!/skin/
 locale,install,url,jar:resource:/chrome/xfly.jar!/locale/en-US/</PRE>  locale,install,url,jar:resource:/chrome/xfly.jar!/locale/en-US/</PRE>
 <P>This code tells the chrome registry to look in the <I>content</I>, <I>skin</I>, and <I>locale/en-US</I> directories in the JAR file to locate the manifests.  <P>This code tells the chrome registry to look in the <I>content</I>, <I>skin</I>, and <I>locale/en-US</I> directories in the JAR file to locate the manifests.
<P>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 <A HREF="ch04.htm#77088">"Skin inheritance and skin modularization</A>" in <A HREF="ch04.htm#77060">Chapter 4</A> for a discussion of skin inheritance and tips on how to make sure your skin is structured to best take advantage of it.<P>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 <A HREF="ch04.html#77088">"Skin inheritance and skin modularization</A>" in <A HREF="ch04.html#77060">Chapter 4</A> for a discussion of skin inheritance and tips on how to make sure your skin is structured to best take advantage of it.
 <P>When you make these additions to the <I>installed-chrome.txt</I> file and restart Mozilla, the chrome registry looks for manifests in the directories you specify and registers the packages described there. The <I>installed-chrome.txt</I> 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 <I>installed-chrome.txt</I> file separate form the main one. See the section <A HREF="#77078">"The Chrome Registry</A>" for more information about this process.  <P>When you make these additions to the <I>installed-chrome.txt</I> file and restart Mozilla, the chrome registry looks for manifests in the directories you specify and registers the packages described there. The <I>installed-chrome.txt</I> 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 <I>installed-chrome.txt</I> file separate form the main one. See the section <A HREF="#77078">"The Chrome Registry</A>" for more information about this process.
 <H3><A NAME="77073"></A> Creating a Package</H3>  <H3><A NAME="77073"></A> Creating a Package</H3>
<P>The xFly sample package  <!--INDEX packages:xFly;xFly 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 <A HREF="ch02.htm#77048">Chapter 2</A>, but this section will discuss the process in detail.<P>The xFly sample package  <!--INDEX packages:xFly;xFly 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 <A HREF="ch02.html#77048">Chapter 2</A>, but this section will discuss the process in detail.
 <H4><A NAME="77074"></A> Setting up xFly</H4>  <H4><A NAME="77074"></A> Setting up xFly</H4>
 <P>To start working immediately  <!--INDEX xFly package:setup;packages:xFly:setup --> 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.  <P>To start working immediately  <!--INDEX xFly package:setup;packages:xFly:setup --> 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.
 <P>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:  <P>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:
Line 217  chrome/en-US.jar!/locale/en-US/communica Line 223  chrome/en-US.jar!/locale/en-US/communica
 <P>When you develop your application, it's typical to work within a regular directory. As you finish the application and make it available for distribution and installation, however, you may want to use one of the installation archive formats to package your work, such as a JAR file. See the section <A HREF="#77082">"The XPI File Format</A>" later in this chapter for more details.<P></BLOCKQUOTE>  <P>When you develop your application, it's typical to work within a regular directory. As you finish the application and make it available for distribution and installation, however, you may want to use one of the installation archive formats to package your work, such as a JAR file. See the section <A HREF="#77082">"The XPI File Format</A>" later in this chapter for more details.<P></BLOCKQUOTE>
 <P>When your application is large and distributed in this way, the RDF-based manifests "compose" all of the metadata and treat all files as a single component.  <P>When your application is large and distributed in this way, the RDF-based manifests "compose" all of the metadata and treat all files as a single component.
 <H4><A NAME="77075"></A> Hacking the installed-chrome.txt file</H4>  <H4><A NAME="77075"></A> Hacking the installed-chrome.txt file</H4>
<P>The entries you made  <!--INDEX installed-chrome.txt file:xFly and;xFly:installed-chrome.txt file --> to the <I>installed-chrome.txt</I> in <A HREF="ch02.htm#77048">Chapter 2</A> tell the chrome registry that a new package must be registered:<P>The entries you made  <!--INDEX installed-chrome.txt file:xFly and;xFly:installed-chrome.txt file --> to the <I>installed-chrome.txt</I> in <A 
 HREF="ch02.html#77048">Chapter 2</A> tell the chrome registry that a new package must be registered:
 <PRE>content,install,url,resource:/chrome/xfly/content/  <PRE>content,install,url,resource:/chrome/xfly/content/
 skin,install,url,resource:/chrome/xfly/skin/  skin,install,url,resource:/chrome/xfly/skin/
 locale,install,url,resource:/chrome/xfly/locale/en-US/</PRE>  locale,install,url,resource:/chrome/xfly/locale/en-US/</PRE>
Line 320  performInstall( );</PRE> Line 327  performInstall( );</PRE>
 <P>This example uses XPInstall technology to install something that may or may not be a Mozilla application. The <I>install.js</I> script in <A HREF="#77034">Example 6-8</A> would look like this. In Mozilla application development, however, XPIs often contain JAR files that are installed as new packages in the Mozilla distribution. To make a XPI for your package, use any zip software (applications or extensions that will be part of the main Mozilla distribution are required to use the free <I>zip</I> utility from InfoTools so that they can be run as part of the build process) to archive your files.  <P>This example uses XPInstall technology to install something that may or may not be a Mozilla application. The <I>install.js</I> script in <A HREF="#77034">Example 6-8</A> would look like this. In Mozilla application development, however, XPIs often contain JAR files that are installed as new packages in the Mozilla distribution. To make a XPI for your package, use any zip software (applications or extensions that will be part of the main Mozilla distribution are required to use the free <I>zip</I> utility from InfoTools so that they can be run as part of the build process) to archive your files.
 <H4><A NAME="77084"></A> JARs versus XPIs</H4>  <H4><A NAME="77084"></A> JARs versus XPIs</H4>
 <P>Technically, only the internal  <!--INDEX JAR (Java Archive) files:XPIs and;XPIs, JARs and --> installation script distinguishes JARs and XPIs. However, Mozilla treats them differently. Since JARs do not include this installation script, they cannot install full content or applications by themselves. In this case, "content" means XUL, XBL, or JavaScript files that have script access to XPCOM. Files of this kind that are in JARs are denied access to XPConnect and are not registered as content in the chrome registry. JARs are used primarily to install locales, or language packs, and skins.  <P>Technically, only the internal  <!--INDEX JAR (Java Archive) files:XPIs and;XPIs, JARs and --> installation script distinguishes JARs and XPIs. However, Mozilla treats them differently. Since JARs do not include this installation script, they cannot install full content or applications by themselves. In this case, "content" means XUL, XBL, or JavaScript files that have script access to XPCOM. Files of this kind that are in JARs are denied access to XPConnect and are not registered as content in the chrome registry. JARs are used primarily to install locales, or language packs, and skins.
<P>Skins that contain scripts  <!--INDEX skins:scripts and;skins:bindings and;bindings:skins;scripts:skins --> and bindings (see the section <A HREF="ch04.htm#77103">"Theme Security Restrictions</A>" and the <A HREF="ch04.htm#62192">"Evil Skins</A>" sidebar, both in <A HREF="ch04.htm#77060">Chapter 4</A>) are seen more as chrome content and must be installed in XPIs if they are to be fully functional. Like executables that are fetched from the Web, XPIs can cause trouble when downloaded by unprepared users since the software in XPIs are given the same privileges on the Mozilla platform that the browser chrome itself has.<P>Skins that contain scripts  <!--INDEX skins:scripts and;skins:bindings and;bindings:skins;scripts:skins --> and bindings (see the section <A 
 HREF="ch04.html#77103">"Theme Security Restrictions</A>" and the <A HREF="ch04.html#62192">"Evil Skins</A>" sidebar, both in <A 
 HREF="ch04.html#77060">Chapter 4</A>) are seen more as chrome content and must be installed in XPIs if they are to be fully functional. Like 
 executables that are fetched from the Web, XPIs can cause trouble when downloaded by unprepared users since the software in XPIs are given the same privileges on the Mozilla platform that the browser chrome itself has.
 <P>The characteristics and usage  <!--INDEX XPI files:characteristics;JAR (Java Archive) files:characteristics --> of an XPI are:  <P>The characteristics and usage  <!--INDEX XPI files:characteristics;JAR (Java Archive) files:characteristics --> of an XPI are:
 <UL><P><LI>Has an <I>install.js</I> file<P>  <UL><P><LI>Has an <I>install.js</I> file<P>
 <P><LI>Can install anything via XPInstall API<P>  <P><LI>Can install anything via XPInstall API<P>
Line 683  Example 6-21<A NAME="77060"></A> Line 693  Example 6-21<A NAME="77060"></A>
 <BLOCKQUOTE><CENTER><B>NOTE</B></CENTER>  <BLOCKQUOTE><CENTER><B>NOTE</B></CENTER>
 <P>You don't need to have an install page to install a XPI in Mozilla. If, instead of a web page, you provide a URL that points directly to a XPI, Mozilla displays a dialog that asks the user whether they want to initiate the installation of that XPI. As with any new software installation, however, a page that describes the package and what it does can help allay fears and promote use.<P></BLOCKQUOTE>  <P>You don't need to have an install page to install a XPI in Mozilla. If, instead of a web page, you provide a URL that points directly to a XPI, Mozilla displays a dialog that asks the user whether they want to initiate the installation of that XPI. As with any new software installation, however, a page that describes the package and what it does can help allay fears and promote use.<P></BLOCKQUOTE>
 <H2><A NAME="77100"></A> Extra Tricks for Customizing an Application</H2>  <H2><A NAME="77100"></A> Extra Tricks for Customizing an Application</H2>
<P>If the Mozilla application  <!--INDEX applications:customizing;customizing applications --> you are working on is more autonomous than a package that sits up on a Mozilla installation, you may want to add extra customization. Here are two common features: the program icon and the splash screen. Some features require that you build the source code yourself, even just a particular module instead of the whole tree. Refer to <A HREF="appa.htm#90096">Appendix A</A> for more details on obtaining and building the source code.<P>If the Mozilla application  <!--INDEX applications:customizing;customizing applications --> you are working on is more autonomous than a 
 package that sits up on a Mozilla installation, you may want to add extra customization. Here are two common features: the program icon and the splash screen. Some features require that you build the source code yourself, even just a particular module instead of the whole tree. Refer to <A HREF="appa.html#90096">Appendix A</A> for more details on obtaining and building the source code.
 <H3><A NAME="77101"></A> Icons</H3>  <H3><A NAME="77101"></A> Icons</H3>
 <P>Program icons are important  <!--INDEX icons, application customization;applications:customizing:icons --> for several reasons. Primarily, however, they are a visual representation of your application on the system that it runs on, whether it runs in a file explorer, a taskbar, or an application selector. This section tells you where to locate the current icons in the Mozilla application and what files or resources need to be changed to make your icon the default for Mozilla.  <P>Program icons are important  <!--INDEX icons, application customization;applications:customizing:icons --> for several reasons. Primarily, however, they are a visual representation of your application on the system that it runs on, whether it runs in a file explorer, a taskbar, or an application selector. This section tells you where to locate the current icons in the Mozilla application and what files or resources need to be changed to make your icon the default for Mozilla.
 <H4><A NAME="77102"></A> Windows</H4>  <H4><A NAME="77102"></A> Windows</H4>

Removed from v.1.1  
changed lines
  Added in v.1.2


FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>