Install Manifests

  • Revision slug: Install_Manifests
  • Revision title: Install Manifests
  • Revision id: 8735
  • Created:
  • Creator: Nickolay
  • Is current revision? No
  • Comment /* targetApplication */ app.extensions.version

Revision Content

Introduction

An Install Manifest is the file an Addon Manager-enabled XUL application uses to determine information about an addon as it is being installed. It contains metadata identifying the addon, providing information about who created it, where more information can be found about it, which versions of what applications it is compatible with, how it should be updated, and so on.

The format of the Install Manifest is RDF/XML.

The file must be called <tt>install.rdf</tt> and live at the top level of an addon's XPI file.

Layout

The basic layout of an Install Manifest is like so:

<?xml version="1.0"?>

<RDF xmlns="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
     xmlns:em="http://www.mozilla.org/2004/em-rdf#">
  <Description about="urn:mozilla:install-manifest">
    <!-- properties -->
  </Description>
</RDF>

Some properties are required, some are optional. Some have simple string values, some are complex resources.

Required Property Reference

Your Install Manifest must specify these properties correctly otherwise your addon may not install.

id

The id of the extension, which is a:

  • GUID (generate using guidgen on Windows or uuidgen on Unix systems) (Firefox 1.0)
  • Firefox 1.5 and newer: A string formatted like so: <tt>extensionname@organization.tld</tt>

The latter format is significantly easier to generate and manipulate. Firefox 1.5 has checking to ensure that your id falls into one format or the other and will refuse to install addons that have malformed ids.

Examples

<em:id>myextension@mysite.com</em:id>

<em:id>{daf44bf7-a45e-4450-979c-91cf07434c3d}</em:id>

version

A version string identifying the version of the addon being supplied. The format must conform to the rules specified in {{mediawiki.external('this document')}}.

Examples

<em:version>2.0</em:version>

<em:version>1.0.2</em:version>

<em:version>0.4.1.2005090112</em:version>

Firefox 1.5 - addons that do not use a valid version format will not be installed.

For addons hosted on addons.mozilla.org - Mozilla's update website may repackage your addon and correct or reject malformed version strings.

type

An integer value representing the type of addon.

2Extensions
4Themes
8Locale
16Plugin

Examples

<em:type>2</em:type>

Firefox 1.5 This property was added for Firefox 1.5, and is only required for addon types other than Extensions and Themes.

targetApplication

An object specifying an application targeted by this addon. This means that the addon will work with the application identified by the id property (<tt><em:id></tt>) specified, from the min version (<tt><em:minVersion></tt>) up to and including the max version (<tt><em:maxVersion></tt>). These version strings are formatted in the same fashion as the <tt>version</tt> property and will be compared to the value of <tt>app.extensions.version</tt> preference which may be different from the displayed version of the application. For example, Firefox 1.0 - 1.0.6 has <tt>app.extensions.version</tt> = 1.0.

The Install Manifest must specify at least one of these objects, and may specify more if the addon targets multiple applications that support the Addon Manager (e.g. Firefox and Thunderbird)

Examples

<em:targetApplication>
 <Description>
  <em:id>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</em:id>
  <em:minVersion>1.0</em:minVersion>
  <em:maxVersion>1.5</em:maxVersion>
 </Description>
<em:targetApplication>

name

The name of the addon- intended for display in the UI.

Examples

<em:name>My Extension</em:name>

Optional Property Reference

You may need to supply these properties, depending on the capabilities of your addon.

description

A short description of the addon - intended for display in the user interface. This description should fit on one short line of text.

Examples

<em:description>Advanced foo tools.</em:description>

creator

The name of the creator/principal developer - intended for display in the user interface.

Examples

<em:creator>John Doe</em:creator>

contributor

The name(s) of additional contributors. You may specify more than one of this value to specify multiple contributors.

Examples

<em:contributor>John Doe</em:contributor>

<em:contributor>John Doe</em:contributor>
<em:contributor>Jane Doe</em:contributor>
<em:contributor>Elvis Presley</em:contributor>

homepageURL

A link to the addon's home page - intended for display in the user interface.

Examples

<em:homepageURL>http://www.foo.com/</em:homepageURL>

updateURL

A link to a custom Update Manifest file that specifies available updates to the addon. The format is described below. If enabled, the addon manager periodically checks with this Manifest file to determine if newer versions are available.

Your server must send this file as <tt>text/rdf</tt> or the update checker will not work.

The addon manager will substitute the following values into this URL in case you wish to generate the response RDF dynamically, such as using PHP or CGI:

<tt>%REQ_VERSION%</tt>The version of the request. Currently 1
<tt>%ITEM_ID%</tt>The <tt>id</tt> of the addon being updated
<tt>%ITEM_VERSION%</tt>The <tt>version</tt> of the addon being updated
<tt>%ITEM_MAXAPPVERSION%</tt>The <tt>maxVersion</tt> of the <tt>targetApplication</tt> object corresponding to the current application for the addon being updated.
<tt>%APP_ID%</tt>The <tt>id</tt> of the current application
<tt>%APP_VERSION%</tt>The <tt>version</tt> of the current application
<tt>%APP_OS%</tt>The value of <tt>OS_TARGET</tt> from the Firefox build system, identifying the operating system being used. New in Firefox 1.5
<tt>%APP_ABI%</tt>The value of the <tt>TARGET_XPCOM_ABI</tt> value from the Firefox build system, identifying the compiler/architecture combination used to compile the current application. New in Firefox 1.5

Examples

<em:updateURL>http://www.foo.com/update.cgi?id=%ITEM_ID%&version=%ITEM_VERSION%</em:updateURL>

<em:updateURL>http://www.foo.com/extension/windows.rdf</em:updateURL>

For addons hosted on addons.mozilla.org: You may not specify an updateURL property. By default, Mozilla applications using the Addon Manager (such as Firefox and Thunderbird) will send update requests to <tt>addons.mozilla.org</tt> using the default web service. Every time you upload a new version of your addon or change its compatibility parameters through the author interface, your update manifest will be generated automatically.

Format of the Update Manifest: The Update Manifest is a RDF/XML datasource and its format is described here: Update Manifest

optionsURL

The <tt>chrome://</tt> URL of the extension's options dialog box. This is only useful to extensions. If this property is specified, when the extension is selected in the Extensions list, the Options button is enabled and will show this.

Examples

<em:optionsURL>chrome://myext/content/options.xul</em:optionsURL>

aboutURL

The <tt>chrome://</tt> URL of the extension's about dialog box. This is only useful to extensions. If this property is specified, when the extension is selected in the Extensions list, the About... link in the extension's context menu will show this dialog, rather than the default.

Examples

<em:aboutURL>chrome://myext/content/about.xul</em:aboutURL>

iconURL

A <tt>chrome://</tt> URL to a 32x32 icon to display in the addons list. If this property is not specified, a default icon is used.

<em:iconURL>chrome://myext/skin/icon.png</em:iconURL>

hidden

A boolean value that when true makes the addon not show up in the addons list, provided the addon is installed in a restricted access area (i.e. not from the web). This is for bundling integration hooks to larger applications where having an entry in the Extensions list does not make sense.

Examples

<em:hidden>true</em:hidden>

Obsolete Property Reference

These properties were required in older versions of the Addon Manager, but have been replaced with newer and better mechanisms.

file

Firefox 1.0 This property pointed to a chrome <tt>.jar</tt> file that contains chrome packages that require registration with the Chrome Registry.

The <tt><em:file></tt> property has a complex object value. The uri of the value is <tt>urn:mozilla:extension:file:jarFile.jar</tt> where <tt>jarFile.jar</tt> is the name of the jar file that contains the chrome package's files. This could also be the name of a directory that contains the chrome package's files, un-jarred (e.g. <tt>urn:mozilla:extension:file:directory</tt>).

This object has a <tt>package</tt> property (with a path within the jar file or directory that leads to the location where the <tt>contents.rdf</tt> file responsible for registering that package is located), a <tt>locale</tt> property (ditto, but to register the locale) and a <tt>skin</tt> property (ditto, but to register the theme material).

In extensions for Firefox 1.5, this property is no longer necessary: the <tt>chrome.manifest</tt> at the top level of the XPI is used to locate chrome to register. If there is no chrome.manifest, this property is still read by the Addon Manager and a chrome.manifest is generated from old-style contents.rdf.

Examples

<em:file>
 <Description about="urn:mozilla:extension:file:myext.jar">
  <em:package>content/myext/</em:package>
  <em:locale>locale/en-US/myext/</em:locale>
  <em:skin>skin/classic/myext/<em:skin>
 </Description>
</em:file>

An Install Manifest may specify multiple <tt>file</tt> properties, one for each jar file or subdirectory that contains chrome to register.

More Information

{{ wiki.languages( { "pl": "pl/Manifesty_Instalacji" } ) }}

Revision Source

<h3 name="Introduction"> Introduction </h3>
<p>An Install Manifest is the file an Addon Manager-enabled XUL application uses to determine information about an addon as it is being installed. It contains metadata identifying the addon, providing information about who created it, where more information can be found about it, which versions of what applications it is compatible with, how it should be updated, and so on.
</p><p>The format of the Install Manifest is RDF/XML.
</p><p>The file must be called <tt>install.rdf</tt> and live at the top level of an addon's XPI file.
</p>
<h3 name="Layout"> Layout </h3>
<p>The basic layout of an Install Manifest is like so:
</p>
<pre class="eval">&lt;?xml version="1.0"?&gt;

&lt;RDF xmlns="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
     xmlns:em="http://www.mozilla.org/2004/em-rdf#"&gt;
  &lt;Description about="urn:mozilla:install-manifest"&gt;
    &lt;!-- properties --&gt;
  &lt;/Description&gt;
&lt;/RDF&gt;
</pre>
<p>Some properties are required, some are optional. Some have simple string values, some are complex resources.
</p>
<h3 name="Required_Property_Reference"> Required Property Reference </h3>
<p>Your Install Manifest must specify these properties correctly otherwise your addon may not install. 
</p>
<h4 name="id"> id </h4>
<p>The id of the extension, which is a:
</p>
<ul><li> GUID (generate using guidgen on Windows or uuidgen on Unix systems) (Firefox 1.0)
</li><li> <b>Firefox 1.5 and newer:</b> A string formatted like so: <tt>extensionname@organization.tld</tt>
</li></ul>
<p>The latter format is significantly easier to generate and manipulate. Firefox 1.5 has checking to ensure that your id falls into one format or the other and will refuse to install addons that have malformed ids. 
</p><p><b>Examples</b>
</p>
<pre class="eval">&lt;em:id&gt;myextension@mysite.com&lt;/em:id&gt;

&lt;em:id&gt;{daf44bf7-a45e-4450-979c-91cf07434c3d}&lt;/em:id&gt;
</pre>
<h4 name="version"> version </h4>
<p>A version string identifying the version of the addon being supplied. The format must conform to the rules specified in {{mediawiki.external('this document')}}.
</p><p><b>Examples</b>
</p>
<pre class="eval">&lt;em:version&gt;2.0&lt;/em:version&gt;

&lt;em:version&gt;1.0.2&lt;/em:version&gt;

&lt;em:version&gt;0.4.1.2005090112&lt;/em:version&gt;

</pre>
<p><b>Firefox 1.5</b> - addons that do not use a valid version format will not be installed.
</p><p><b>For addons hosted on addons.mozilla.org</b> - Mozilla's update website may repackage your addon and correct or reject malformed version strings.
</p>
<h4 name="type"> type </h4>
<p>An integer value representing the type of addon. 
</p>
<table>
 <tbody><tr><td>2</td><td>Extensions</td></tr>
 <tr><td>4</td><td>Themes</td></tr>
 <tr><td>8</td><td>Locale</td></tr>
 <tr><td>16</td><td>Plugin</td></tr>
</tbody></table>
<p><b>Examples</b>
</p>
<pre class="eval">&lt;em:type&gt;2&lt;/em:type&gt;
</pre>
<p><b>Firefox 1.5</b> This property was added for Firefox 1.5, and is only required for addon types other than Extensions and Themes. 
</p>
<h4 name="targetApplication"> targetApplication </h4>
<p>An object specifying an application targeted by this addon. This means that the addon will work with the application identified by the id property (<tt>&lt;em:id&gt;</tt>) specified, from the min version (<tt>&lt;em:minVersion&gt;</tt>) up to and including the max version (<tt>&lt;em:maxVersion&gt;</tt>). These version strings are formatted in the same fashion as the <tt>version</tt> property and will be compared to the value of <tt>app.extensions.version</tt> preference which may be different from the displayed version of the application. For example, Firefox 1.0 - 1.0.6 has <tt>app.extensions.version</tt> = 1.0.
</p><p>The Install Manifest must specify at least one of these objects, and may specify more if the addon targets multiple applications that support the Addon Manager (e.g. Firefox and Thunderbird)
</p><p><b>Examples</b>
</p>
<pre class="eval">&lt;em:targetApplication&gt;
 &lt;Description&gt;
  &lt;em:id&gt;{ec8030f7-c20a-464f-9b0e-13a3a9e97384}&lt;/em:id&gt;
  &lt;em:minVersion&gt;1.0&lt;/em:minVersion&gt;
  &lt;em:maxVersion&gt;1.5&lt;/em:maxVersion&gt;
 &lt;/Description&gt;
&lt;em:targetApplication&gt;
</pre>
<h4 name="name"> name </h4>
<p>The name of the addon- intended for display in the UI.
</p><p><b> Examples </b>
</p>
<pre class="eval">&lt;em:name&gt;My Extension&lt;/em:name&gt;
</pre>
<h3 name="Optional_Property_Reference"> Optional Property Reference </h3>
<p>You may need to supply these properties, depending on the capabilities of your addon. 
</p>
<h4 name="description"> description </h4>
<p>A short description of the addon - intended for display in the user interface. This description should fit on one short line of text.
</p><p><b>Examples</b>
</p>
<pre class="eval">&lt;em:description&gt;Advanced foo tools.&lt;/em:description&gt;
</pre>
<h4 name="creator"> creator </h4>
<p>The name of the creator/principal developer - intended for display in the user interface.
</p><p><b>Examples</b>
</p>
<pre class="eval">&lt;em:creator&gt;John Doe&lt;/em:creator&gt;
</pre>
<h4 name="contributor"> contributor </h4>
<p>The name(s) of additional contributors. You may specify more than one of this value to specify multiple contributors. 
</p><p><b>Examples</b>
</p>
<pre class="eval">&lt;em:contributor&gt;John Doe&lt;/em:contributor&gt;

&lt;em:contributor&gt;John Doe&lt;/em:contributor&gt;
&lt;em:contributor&gt;Jane Doe&lt;/em:contributor&gt;
&lt;em:contributor&gt;Elvis Presley&lt;/em:contributor&gt;
</pre>
<h4 name="homepageURL"> homepageURL </h4>
<p>A link to the addon's home page - intended for display in the user interface.
</p><p><b>Examples</b>
</p>
<pre class="eval">&lt;em:homepageURL&gt;http://www.foo.com/&lt;/em:homepageURL&gt;
</pre>
<h4 name="updateURL"> updateURL </h4>
<p>A link to a custom Update Manifest file that specifies available updates to the addon. The format is described below. If enabled, the addon manager periodically checks with this Manifest file to determine if newer versions are available. 
</p><p>Your server must send this file as <tt>text/rdf</tt> or the update checker will not work. 
</p><p>The addon manager will substitute the following values into this URL in case you wish to generate the response RDF dynamically, such as using PHP or CGI:
</p>
<table border="1" cellpadding="3" cellspacing="2">
 <tbody><tr><td><tt>%REQ_VERSION%</tt></td><td>The version of the request. Currently 1</td></tr>
 <tr><td><tt>%ITEM_ID%</tt></td><td>The <tt>id</tt> of the addon being updated</td></tr>
 <tr><td><tt>%ITEM_VERSION%</tt></td><td>The <tt>version</tt> of the addon being updated</td></tr>
 <tr><td><tt>%ITEM_MAXAPPVERSION%</tt></td><td>The <tt>maxVersion</tt> of the <tt>targetApplication</tt> object corresponding to the current application for the addon being updated.</td></tr>
 <tr><td><tt>%APP_ID%</tt></td><td>The <tt>id</tt> of the current application</td></tr>
 <tr><td><tt>%APP_VERSION%</tt></td><td>The <tt>version</tt> of the current application</td></tr>
 <tr><td><tt>%APP_OS%</tt></td><td>The value of <tt>OS_TARGET</tt> from the Firefox build system, identifying the operating system being used. <b>New in Firefox 1.5</b></td></tr>
 <tr><td><tt>%APP_ABI%</tt></td><td>The value of the <tt>TARGET_XPCOM_ABI</tt> value from the Firefox build system, identifying the compiler/architecture combination used to compile the current application. <b>New in Firefox 1.5</b></td></tr>
</tbody></table>
<p><b>Examples</b>
</p>
<pre class="eval">&lt;em:updateURL&gt;http://www.foo.com/update.cgi?id=%ITEM_ID%&amp;version=%ITEM_VERSION%&lt;/em:updateURL&gt;

&lt;em:updateURL&gt;http://www.foo.com/extension/windows.rdf&lt;/em:updateURL&gt;
</pre>
<p><b>For addons hosted on addons.mozilla.org:</b> You may not specify an updateURL property. By default, Mozilla applications using the Addon Manager (such as Firefox and Thunderbird) will send update requests to <tt>addons.mozilla.org</tt> using the default web service. Every time you upload a new version of your addon or change its compatibility parameters through the author interface, your update manifest will be generated automatically.
</p><p><b>Format of the Update Manifest:</b> The Update Manifest is a RDF/XML datasource and its format is described here: <a href="en/Update_Manifest">Update Manifest</a>
</p>
<h4 name="optionsURL"> optionsURL </h4>
<p>The <tt>chrome://</tt> URL of the extension's options dialog box. This is only useful to extensions. If this property is specified, when the extension is selected in the Extensions list, the Options button is enabled and will show this.
</p><p><b>Examples</b>
</p>
<pre class="eval">&lt;em:optionsURL&gt;chrome://myext/content/options.xul&lt;/em:optionsURL&gt;
</pre>
<h4 name="aboutURL"> aboutURL </h4>
<p>The <tt>chrome://</tt> URL of the extension's about dialog box. This is only useful to extensions. If this property is specified, when the extension is selected in the Extensions list, the About... link in the extension's context menu will show this dialog, rather than the default.
</p><p><b>Examples</b>
</p>
<pre class="eval">&lt;em:aboutURL&gt;chrome://myext/content/about.xul&lt;/em:aboutURL&gt;
</pre>
<h4 name="iconURL"> iconURL </h4>
<p>A <tt>chrome://</tt> URL to a 32x32 icon to display in the addons list. If this property is not specified, a default icon is used. 
</p>
<pre class="eval">&lt;em:iconURL&gt;chrome://myext/skin/icon.png&lt;/em:iconURL&gt;
</pre>
<h4 name="hidden"> hidden </h4>
<p>A boolean value that when true makes the addon not show up in the addons list, provided the addon is installed in a restricted access area (i.e. not from the web). This is for bundling integration hooks to larger applications where having an entry in the Extensions list does not make sense.
</p><p><b>Examples</b>
</p>
<pre class="eval">&lt;em:hidden&gt;true&lt;/em:hidden&gt;
</pre>
<h3 name="Obsolete_Property_Reference"> Obsolete Property Reference </h3>
<p>These properties were required in older versions of the Addon Manager, but have been replaced with newer and better mechanisms.
</p>
<h4 name="file"> file </h4>
<p><b>Firefox 1.0</b> This property pointed to a chrome <tt>.jar</tt> file that contains chrome packages that require registration with the Chrome Registry. 
</p><p>The <tt>&lt;em:file&gt;</tt> property has a complex object value. The uri of the value is <tt>urn:mozilla:extension:file:jarFile.jar</tt> where <tt>jarFile.jar</tt> is the name of the jar file that contains the chrome package's files. This could also be the name of a directory that contains the chrome package's files, un-jarred (e.g. <tt>urn:mozilla:extension:file:directory</tt>).
</p><p>This object has a <tt>package</tt> property (with a path within the jar file or directory that leads to the location where the <tt>contents.rdf</tt> file responsible for registering that package is located), a <tt>locale</tt> property (ditto, but to register the locale) and a <tt>skin</tt> property (ditto, but to register the theme material).
</p><p>In extensions for Firefox 1.5, this property is no longer necessary: the <tt><a href="en/Chrome_Registration">chrome.manifest</a></tt> at the top level of the XPI is used to locate chrome to register. If there is no chrome.manifest, this property is still read by the Addon Manager and a chrome.manifest is generated from old-style contents.rdf.
</p><p><b>Examples</b>
</p>
<pre class="eval">&lt;em:file&gt;
 &lt;Description about="urn:mozilla:extension:file:myext.jar"&gt;
  &lt;em:package&gt;content/myext/&lt;/em:package&gt;
  &lt;em:locale&gt;locale/en-US/myext/&lt;/em:locale&gt;
  &lt;em:skin&gt;skin/classic/myext/&lt;em:skin&gt;
 &lt;/Description&gt;
&lt;/em:file&gt;
</pre>
<p>An Install Manifest may specify multiple <tt>file</tt> properties, one for each jar file or subdirectory that contains chrome to register.
</p>
<h3 name="More_Information"> More Information </h3>
<ul><li> See <a class="external" href="http://kb.mozillazine.org/Install.rdf">install.rdf page on the MozillaZine KB</a> for examples and more information
</li></ul>
{{ wiki.languages( { "pl": "pl/Manifesty_Instalacji" } ) }}
Revert to this revision