mozilla

Compare Revisions

Creating XPI Installer Modules

Change Revisions

Revision 78093:

Revision 78093 by Jorend on

Revision 78094:

Revision 78094 by Enn on

Title:
Creating XPI Installer Modules
Creating XPI Installer Modules
Slug:
Creating_XPI_Installer_Modules
Creating_XPI_Installer_Modules
Tags:
XPInstall
XPInstall
Content:

Revision 78093
Revision 78094
nn7    <p>
8      &nbsp;
9    </p>
7    <h2 name="Introduction">10    <h2 id="Introduction" name="Introduction">
n12        This article is rather old and only applies to Mozilla Sun15        This article is rather old and only applies to Mozilla Su
>ite and SeaMonkey (until it gets converted to Toolkit). Addons fo>ite and SeaMonkey (until it gets converted to Toolkit). Addons fo
>r various Toolkit applications, such as Firefox or Thundebird, sh>r various Toolkit applications, such as Firefox or Thundebird, sh
>ould be packaged <a href="en/Toolkit_API#Official_References">in >ould be packaged <a href="/en/Toolkit_API#Official_References" ti
>a different way</a>.>tle="en/Toolkit_API#Official_References">in a different way</a>.
n16      Mozilla has introduced major changes to the way that themesn19      Mozilla has introduced major changes to the way that themes
> and all the other parts of the UI are packaged. This new packagi> and all the other parts of the UI are packaged. This new packagi
>ng scheme is called <a href="en/XPI">XPI</a> (pronounced "zippy")>ng scheme is called <a href="/en/XPI" title="en/XPI">XPI</a> (pro
>, and interacts with <a href="en/XPInstall">XPInstall</a>. A XPI >nounced "zippy"), and interacts with <a href="/en/XPInstall" titl
>file typically contains the resources to be installed (in this ca>e="en/XPInstall">XPInstall</a>. A XPI file typically contains the
>se the <i>barley.jar</i> we want to have installed in the <tt>Moz> resources to be installed (in this case the <em>barley.jar</em> 
>illa/bin/chrome/</tt> directory) and an install script that guide>we want to have installed in the <code>Mozilla/bin/chrome/</code>
>s the installation process.> directory) and an install script that guides the installation pr
 >ocess.
17    </p>
18    <p>20    </p>
21    <p>
19      Under the <tt>chrome/</tt> directory, you'll notice that in22      Under the <code>chrome/</code> directory, you'll notice tha
> addition to the package subdirectories, there are now also a han>t in addition to the package subdirectories, there are now also a
>dful of <a class="external" href="http://java.sun.com/j2se/1.5.0/> handful of <a class="external" href="http://java.sun.com/j2se/1.
>docs/guide/jar/jar.html">JAR files</a>, or Java archives (see fig>5.0/docs/guide/jar/jar.html">JAR files</a>, or Java archives (see
>ure below). JAR is a file format based on the ZIP file format and> figure below). JAR is a file format based on the ZIP file format
> is used for aggregating multiple files into a single file. These> and is used for aggregating multiple files into a single file. T
> archives are redundant with the subdirectories: Mozilla now inst>hese archives are redundant with the subdirectories: Mozilla now 
>alls both the compressed and uncompressed versions of the UI, tho>installs both the compressed and uncompressed versions of the UI,
>ugh you can change this when you build Mozilla yourself.> though you can change this when you build Mozilla yourself.
n55      In addition to these JAR files, there are also several new n58      In addition to these JAR files, there are also several new 
><a href="en/RDF">RDF</a> files. These new files represent a redes><a href="/en/RDF" title="en/RDF">RDF</a> files. These new files r
>ign of the way that the Mozilla UI is packaged and installed. Tho>epresent a redesign of the way that the Mozilla UI is packaged an
>ugh the chrome directory still includes subdirectories of uncompr>d installed. Though the chrome directory still includes subdirect
>essed files by default, a new way to aggregate and distribute the>ories of uncompressed files by default, a new way to aggregate an
> files has improved performance, made the UI components more port>d distribute the files has improved performance, made the UI comp
>able and easier to install, and made the installation process a m>onents more portable and easier to install, and made the installa
>uch easier one.>tion process a much easier one.
56    </p>
57    <p>59    </p>
60    <p>
58      However, this new arrangement does not make things much eas61      However, this new arrangement does not make things much eas
>ier for the web or user interface developer. The relatively simpl>ier for the web or user interface developer. The relatively simpl
>e process of finding the appropriate resources (i.e. <a href="en/>e process of finding the appropriate resources (i.e. <a href="/en
>XUL">XUL</a>, <a href="en/JavaScript">JavaScript</a>, or <a href=>/XUL" title="en/XUL">XUL</a>, <a href="/en/JavaScript" title="en/
>"en/CSS">CSS</a> files) in the chrome subdirectories and editing >JavaScript">JavaScript</a>, or <a href="/en/CSS" title="en/CSS">C
>them with a text editor has been replaced by something a lot of d>SS</a> files) in the chrome subdirectories and editing them with 
>evelopers find more confusing and esoteric. This article describe>a text editor has been replaced by something a lot of developers 
>s the new packaging scheme of Mozilla and offers a tutorial for c>find more confusing and esoteric. This article describes the new 
>reating a new package that can then be redistributed, installed, >packaging scheme of Mozilla and offers a tutorial for creating a 
>and made available to users.>new package that can then be redistributed, installed, and made a
 >vailable to users.
n60    <h2 name="The_XPI_Packaging_Scheme">n63    <h2 id="The_XPI_Packaging_Scheme" name="The_XPI_Packaging_Sch
 >eme">
n64      A complete description of the new packaging scheme is beyonn67      A complete description of the new packaging scheme is beyon
>d the scope of this article. The reader is referred to <a class=">d the scope of this article. The reader is referred to <a class="
>external" href="http://www.mozilla.org/build/jar-packaging.html">>external" href="http://www.mozilla.org/build/jar-packaging.html">
>JAR Packaging</a>, which describes the design, goals, and options>JAR Packaging</a>, which describes the design, goals, and options
> available for JAR packaging in some depth. What follows is a <i>> available for JAR packaging in some depth. What follows is a <em
>very</i> brief overview of the design and a description of what M>>very</em> brief overview of the design and a description of what
>ozilla expects in installable packages.> Mozilla expects in installable packages.
65    </p>
66    <p>68    </p>
69    <p>
67      Resources are collected in JAR archives whose contents are 70      Resources are collected in JAR archives whose contents are 
>specified in <i>contents.rdf</i> files at their own top level. Th>specified in <em>contents.rdf</em> files at their own top level. 
>e <i>contents.rdf</i> file explains the structure and contents of>The <em>contents.rdf</em> file explains the structure and content
> the archive to Mozilla's chrome registry; as long as the explana>s of the archive to Mozilla's chrome registry; as long as the exp
>tion is accurate, the contents can be arranged in almost any way >lanation is accurate, the contents can be arranged in almost any 
>you want. In the package you create in this tutorial, for example>way you want. In the package you create in this tutorial, for exa
>, all of the resources are located under the <tt>content/</tt> su>mple, all of the resources are located under the <code>content/</
>bdirectory, but they could just as easily have been archived dire>code> subdirectory, but they could just as easily have been archi
>ctly at the top--along with skin and locale resources, if you wan>ved directly at the top--along with skin and locale resources, if
>ted.> you wanted.
68    </p>
69    <p>71    </p>
70      Where before a single <i>manifest.rdf</i> file described th
>e resources in an entire package directory or archive, now <i>con 
>tents.rdf</i> files can be used for as large or as small a part o 
>f your package description as you want; you can use several <i>co 
>ntents.rdf</i> files in your package to describe the various part 
>s (e.g., one for the skin of your package, another for the conten 
>t, and so on), or you can use a single one, as was common before. 
71    </p>72    <p>
73      Where before a single <em>manifest.rdf</em> file described 
 >the resources in an entire package directory or archive, now <em>
 >contents.rdf</em> files can be used for as large or as small a pa
 >rt of your package description as you want; you can use several <
 >em>contents.rdf</em> files in your package to describe the variou
 >s parts (e.g., one for the skin of your package, another for the 
 >content, and so on), or you can use a single one, as was common b
 >efore.
72    <p>74    </p>
75    <p>
73      Mozilla is alerted to these content specifications and the 76      Mozilla is alerted to these content specifications and the 
>resources they manage either through registration as part of an i>resources they manage either through registration as part of an i
>nstallation process (as described in this tutorial) or by way of >nstallation process (as described in this tutorial) or by way of 
>a shortcut file called <tt>installed-chrome.txt</tt>, in which de>a shortcut file called <code>installed-chrome.txt</code>, in whic
>velopers can point at their new contents.rdf files and have them >h developers can point at their new contents.rdf files and have t
>registered as they develop (a process we do not describe here). O>hem registered as they develop (a process we do not describe here
>ne way of another, the chrome registry is shown the contents.rdf >). One way of another, the chrome registry is shown the contents.
>files; the contents.rdf files in turn point to new resources, and>rdf files; the contents.rdf files in turn point to new resources,
> the resources are then registered with Mozilla and accessible to> and the resources are then registered with Mozilla and accessibl
> the user.>e to the user.
n75    <h2 name="Creating_a_New_Package">n78    <h2 id="Creating_a_New_Package" name="Creating_a_New_Package"
 >>
n81    <h3 name="The_Barley_Package">n84    <h3 id="The_Barley_Package" name="The_Barley_Package">
n85      <img align="right" alt="The Barley window" fileid="40" src=n88      <img align="right" alt="The Barley window" class=" internal
>"File:en/Media_Gallery/Barley_Window.png">The barley package is a>" src="/@api/deki/files/40/=Barley_Window.png">The barley package
> simple <a href="en/XUL">XUL</a> window with a couple of buttons > is a simple <a href="/en/XUL" title="en/XUL">XUL</a> window with
>and an image element. One of the buttons, labeled "show aphids", > a couple of buttons and an image element. One of the buttons, la
>displays an alert dialog by calling a function defined in the Jav>beled "show aphids", displays an alert dialog by calling a functi
>aScript file <i>barley.js</i>.>on defined in the JavaScript file <em>barley.js</em>.
n94      This option tells Mozilla to load a chrome other than the dn97      This option tells Mozilla to load a chrome other than the d
>efault, which is the main browser window. For this option to work>efault, which is the main browser window. For this option to work
>, the designated chrome must have been installed and registered p>, the designated chrome must have been installed and registered p
>roperly with Mozilla. The <tt><a class=" external" href="chrome:/>roperly with Mozilla. The <code>chrome://</code> url pointer corr
>/" rel="freelink">chrome://</a></tt> url pointer corresponds to t>esponds to the directory <code>Mozilla/bin/chrome/barley/content<
>he directory <tt>Mozilla/bin/chrome/barley/content</tt>, where th>/code>, where the main XUL file and the other resources live once
>e main XUL file and the other resources live once they are instal> they are installed.
>led. 
n96    <h3 name="Package_Creation_Overview">n99    <h3 id="Package_Creation_Overview" name="Package_Creation_Ove
 >rview">
n125    <h3 name="Developing_the_Resources">n128    <h3 id="Developing_the_Resources" name="Developing_the_Resour
 >ces">
n147      &lt;button label="show aphids" onclick="bar();" /&gt;n150      &lt;button label="show aphids" oncommand="bar();" /&gt;
n152      The other files that the window imports are defined in <fonn155      The other files that the window imports are defined in <fon
>t color="darkblue">dark blue</font>. Note that the stylesheet pro>t color="darkblue">dark blue</font>. Note that the stylesheet pro
>cessing instruction at the top of the XUL file does not refer to >cessing instruction at the top of the XUL file does not refer to 
>any new skin, but imports <tt>communicator.css</tt> to make use o>any new skin, but imports <code>communicator.css</code> to make u
>f that skin's basic widget styles.>se of that skin's basic widget styles.
153    </p>
154    <p>156    </p>
157    <p>
155      The JavaScript file <i>barley.js</i> contains a single func158      The JavaScript file <em>barley.js</em> contains a single fu
>tion, <code>bar()</code>, defined as follows:>nction, <code>bar()</code>, defined as follows:
n166      While you are developing these resources and before you havn169      While you are developing these resources and before you hav
>e made them a package of their own, you can test the basic layout>e made them a package of their own, you can test the basic layout
> and functionality by opening <i>barley.xul</i> from within Mozil> and functionality by opening <em>barley.xul</em> from within Moz
>la by using File -&gt; Open. Though Mozilla will not display the >illa by using File -&gt; Open. Though Mozilla will not display th
>file as a separate window (much less interpret it as a separate p>e file as a separate window (much less interpret it as a separate
>ackage), you ought to be able to see the image and the JavaScript> package), you ought to be able to see the image and the JavaScri
> function working as defined in <i>barley.js</i> (provided that b>pt function working as defined in <em>barley.js</em> (provided th
>oth all three files are in the same working directory).>at both all three files are in the same working directory).
n168    <h3 name="Organizing_the_Resources">n171    <h3 id="Organizing_the_Resources" name="Organizing_the_Resour
 >ces">
n172      Now that you have created the basic files to be included inn175      Now that you have created the basic files to be included in
> your package, you should put them all in a single directory so t> your package, you should put them all in a single directory so t
>hat they can be bundled up. When your package includes its own th>hat they can be bundled up. When your package includes its own th
>eme, localization packs, or other components it's convenient (but>eme, localization packs, or other components it's convenient (but
> not necessary to create a subdirectory structure that reflects t> not necessary to create a subdirectory structure that reflects t
>he role of the different parts. For the Barley package, you only >he role of the different parts. For the Barley package, you only 
>need to create a single subdirectory, <tt>content/</tt> (see figu>need to create a single subdirectory, <code>content/</code> (see 
>re below).>figure below).
n181    <h3 name="Creating_the_contents.rdf_File">n184    <h3 id="Creating_the_contents.rdf_File" name="Creating_the_co
 >ntents.rdf_File">
n185      One of the most important ingredients of the software packan188      One of the most important ingredients of the software packa
>ge is the <i>contents.rdf</i> file that describes the contents of>ge is the <em>contents.rdf</em> file that describes the contents 
> the package in terms that the chrome registry can make sense of.>of the package in terms that the chrome registry can make sense o
> For a package such as this one with its own content but no speci>f. For a package such as this one with its own content but no spe
>al localization or custom skin, the <i>contents.rdf</i> file desc>cial localization or custom skin, the <em>contents.rdf</em> file 
>ribes package in terms of its relation to the "root" package of M>describes package in terms of its relation to the "root" package 
>ozilla. In the following listing, the items in red are particular>of Mozilla. In the following listing, the items in red are partic
> to the barley package and can be edited for your own distributio>ular to the barley package and can be edited for your own distrib
>n:>ution:
n207      Create a contents.rdf file like the one in the listing abovn210      Create a contents.rdf file like the one in the listing abov
>e and put it in the <tt>content/</tt> subdirectory with the other>e and put it in the <code>content/</code> subdirectory with the o
> package resources.>ther package resources.
n218      These four files are all you need in your new package. The n221      These four files are all you need in your new package. The 
>next step is to zip up the contents of the working directory. Usi>next step is to zip up the contents of the working directory. Usi
>ng a ZIP archiver{{ Ref("zip") }}, create a new archive of the <t>ng a ZIP archiver{{ Ref("zip") }}, create a new archive of the <c
>t>content/</tt> subdirectory and name it <i>barley.jar</i>:>ode>content/</code> subdirectory and name it <em>barley.jar</em>:
219    </p>
220    <p>222    </p>
221      <img alt="Image:Barley_JAR.png" fileid="39" src="File:en/Me
>dia_Gallery/Barley_JAR.png"> 
222    </p>223    <p>
224      <img alt="Image:Barley_JAR.png" class=" internal" src="/@ap
 >i/deki/files/39/=Barley_JAR.png">
223    <p>225    </p>
226    <p>
224      Once this step is complete, the Barley package is in the sa227      Once this step is complete, the Barley package is in the sa
>me state as the JAR packages of the Mozilla UI. <i>comm.jar</i>, >me state as the JAR packages of the Mozilla UI. <em>comm.jar</em>
><i>en-US.jar</i>, and all of the other archived UI packages have >, <em>en-US.jar</em>, and all of the other archived UI packages h
>a similar--if slightly more complex--structure and content specif>ave a similar--if slightly more complex--structure and content sp
>ication as the <i>barley.jar</i>.>ecification as the <em>barley.jar</em>.
n226    <h3 name="Making_the_Barley_Install_Script">n229    <h3 id="Making_the_Barley_Install_Script" name="Making_the_Ba
 >rley_Install_Script">
n236<font color="green">// initInstall(<i>name + version</i>, <i>namen239<font color="green">// initInstall(<em>name + version</em>, <em>n
></i>, <i>version</i>); </font>>ame</em>, <em>version</em>); </font>
n245<font color="green">// registerChrome(<i>TYPE</i>, <i>location</in248<font color="green">// registerChrome(<em>TYPE</em>, <em>location
>>, <i>source</i>)</font>></em>, <em>source</em>)</font>
n254      Note that there is no version number on Barley, and so the n257      Note that there is no version number on Barley, and so the 
><i>name + version</i> parameter has a "v" and then nothing else. ><em>name + version</em> parameter has a "v" and then nothing else
>Note also the use of resource attributes specified in the <i>cont>. Note also the use of resource attributes specified in the <em>c
>ents.rdf</i> file in the JAR. It is the correspondence of this in>ontents.rdf</em> file in the JAR. It is the correspondence of thi
>stallation script, the resources themselves, and the contents.rdf>s installation script, the resources themselves, and the contents
> file that registers the package and makes it available.>.rdf file that registers the package and makes it available.
n256    <h3 name="Creating_a_XPI">n259    <h3 id="Creating_a_XPI" name="Creating_a_XPI">
n260      The final step in the tutorial is to create a XPI archive in263      The final step in the tutorial is to create a XPI archive i
>n which the <i>install.js</i> script and the <i>barley.jar</i> ca>n which the <em>install.js</em> script and the <em>barley.jar</em
>n be redistributed. The archiving of an archive may seem a little>> can be redistributed. The archiving of an archive may seem a li
> redundant--and if you want you can instead use the XPI to archiv>ttle redundant--and if you want you can instead use the XPI to ar
>e the install script and "flat", or uncompressed, versions of the>chive the install script and "flat", or uncompressed, versions of
> resources. But the XPI puts all of the resources of your package> the resources. But the XPI puts all of the resources of your pac
> together, including the instructions for installing it. Like the>kage together, including the instructions for installing it. Like
> JAR format that Mozilla uses to archive the UI packages, the XPI> the JAR format that Mozilla uses to archive the UI packages, the
> format is just a specially-ordered ZIP file. For a XPI file to b> XPI format is just a specially-ordered ZIP file. For a XPI file 
>e valid and installable, it must contain an installation script l>to be valid and installable, it must contain an installation scri
>ike the one above that tells Mozilla XPInstall where to put the n>pt like the one above that tells Mozilla XPInstall where to put t
>ew resources and how to register them.>he new resources and how to register them.
261    </p>
262    <p>264    </p>
265    <p>
263      To create a XPI, use your ZIP archiver{{ Ref("zip") }} agai266      To create a XPI, use your ZIP archiver{{ Ref("zip") }} agai
>n to archive the JAR file and the installation script <i>install.>n to archive the JAR file and the installation script <em>install
>js</i>. The archive, named <tt>barley.xpi</tt>, should contain th>.js</em>. The archive, named <code>barley.xpi</code>, should cont
>e following two files:>ain the following two files:
n273      <img alt="Image:Barley_dlog.png" fileid="41" src="File:en/Mn276      <img alt="Image:Barley_dlog.png" class=" internal" src="/@a
>edia_Gallery/Barley_dlog.png">>pi/deki/files/41/=Barley_dlog.png">
n282      and the new package displays. The resources are installed in285      and the new package displays. The resources are installed i
>n the <tt>mozilla/bin/chrome/</tt> directory, and the XPI itself >n the <code>mozilla/bin/chrome/</code> directory, and the XPI its
>can be redistributed for installation on other machines.>elf can be redistributed for installation on other machines.
n284    <h2 name="Notes">n287    <h2 id="Notes" name="Notes">
n288      <li>{{ Note("zip") }} There exist a lot of ZIP archivers/unn291      <li>{{ Note("zip") }} There exist a lot of ZIP archivers/un
>archivers. For Unix, you can either use the preinstalled <tt>zip<>archivers. For Unix, you can either use the preinstalled <code>zi
>/tt> tool, or e.g. <a class="external" href="http://www.7-zip.org>p</code> tool, or e.g. <a class="external" href="http://www.7-zip
>/">7-Zip</a> (free software). For Windows, you can e.g. use <a cl>.org/">7-Zip</a> (free software). For Windows, you can e.g. use <
>ass="external" href="http://www.7-zip.org/">7-Zip</a> (free softw>a class="external" href="http://www.7-zip.org/">7-Zip</a> (free s
>are), or <a class="external" href="http://www.winzip.com/">WinZip>oftware), or <a class="external" href="http://www.winzip.com/">Wi
></a> (commercial).>nZip</a> (commercial).
n291    <h2 name="See_Also">n294    <h2 id="See_Also" name="See_Also">
n303      <h2 name="Original_Document_Information">n306      <h2 id="Original_Document_Information" name="Original_Docum
 >ent_Information">
tt319    </div>
320    <p>
316    </div>{{ languages( { "ja": "ja/Creating_XPI_Installer_Module321      {{ languages( { "ja": "ja/Creating_XPI_Installer_Modules" }
>s" } ) }}> ) }}
322    </p>

Back to History