Install.rdf: Difference between revisions

From MozillaZine Knowledge Base
Jump to navigationJump to search
m (tidying)
(→‎Items' IDs: updated second web guid generator)
 
(27 intermediate revisions by 11 users not shown)
Line 1: Line 1:
{{extdev}}
{{extdev}}
: ''Most of information here applies to install.rdf used in themes too. See [[#install.rdf for themes|below]] for detailed information.''


Firefox 0.9, Thunderbird 0.7 and all subsequent versions of these products use the Extension Manager. In order to be supported by it you have to package your extensions as described in [http://www.mozilla.org/projects/firefox/extensions/packaging/extensions.html this mozilla.org document]. This includes providing a valid "install.rdf" file.
Firefox 0.9, Thunderbird 0.7, Nvu 0.? and all subsequent versions of these products use the Extension Manager (''"the EM"'') for managing extensions and themes. In order to have your extension supported by it you have to package your extensions as described in "[http://www.mozilla.org/projects/firefox/extensions/packaging/extensions.html Packaging Firefox/Thunderbird Extensions]" document at mozilla.org (see also documentation at [http://developer.mozilla.org/en/docs/Install_Manifests Devmo]). This includes providing a valid '''install.rdf''' file.


Note that the Mozilla Suite currently makes no use of (and ignores) the "install.rdf" file. If you wish to support the Mozilla Suite, you must instead (or in addition) include an [[install.js]] file. Moreover, if you wish to submit your extension to [http://update.mozilla.org/ update.mozilla.org] then you should include the correct targetApplication item for the Mozilla Suite in a valid "install.rdf" file anyway (see [http://forums.mozillazine.org/viewtopic.php?t=99246 this thread]).
== Creating install.rdf using tools ==
 
==Creating "install.rdf" for your extension using tools==
You can use any of these tools:
You can use any of these tools:
*[http://ted.mielczarek.org/code/mozilla/extensiondev/ Extension developer's extension] has Extension Builder functionality.
* [http://ted.mielczarek.org/code/mozilla/extensiondev/ Extension developer's extension] has Extension Builder functionality.
*Ted Mielczarek's [http://ted.mielczarek.org/code/mozilla/ffinstall/ webapp for install.rdf creation].
* Ted Mielczarek's [http://ted.mielczarek.org/code/mozilla/ffinstall/ webapp for install.rdf creation].
*[http://willbert.unserious.com/?go=extenzilla Extenzilla] - Windows-only install.rdf and XPI generator by Will Ryan ([http://forums.mozillazine.org/viewtopic.php?t=96578 disscussion thread at MZ forums]).
* Ted Mielczarek's [http://ted.mielczarek.org/code/mozilla/extensionwiz/ Extension Wizard] for Firefox/Thunderbird version 1.5 and above ([http://forums.mozillazine.org/viewtopic.php?t=381720 discussion thread at MZ forums]).
*[http://physnet.uni-oldenburg.de/~schlenk/tcl/firefox/extensionmaker.kit Extensionmaker] - A Tcl Starkit for windows, that generates an install.rdf. You need a tclkit runtime for windows to start it (see [http://www.equi4.com/tclkit.html]). Its currently beta.
* [http://www.extensionsmirror.nl/index.php?showtopic=1379 xpiZilla] - Windows-only install.rdf and XPI generator by Will Ryan ([http://forums.mozillazine.org/viewtopic.php?t=96578 disscussion thread at MZ forums]).
* [http://physnet.uni-oldenburg.de/~schlenk/tcl/firefox/extensionmaker.kit Extensionmaker] - A Tcl Starkit for Windows that generates an install.rdf. You need a tclkit runtime for Windows to start it (see [http://www.equi4.com/tclkit.html]). It's currently beta.


==A template "install.rdf" file==
== Template ==
If you choose to manually create an "install.rdf" file, you can use the template below as a guide.
If you choose to manually create an "install.rdf" file, you can use the template below as a guide.


Line 35: Line 35:
<em:iconURL>chrome://sampleext/skin/mainicon.png</em:iconURL>
<em:iconURL>chrome://sampleext/skin/mainicon.png</em:iconURL>
<em:updateURL>http://sampleextension.mozdev.org/update.rdf</em:updateURL>
<em:updateURL>http://sampleextension.mozdev.org/update.rdf</em:updateURL>
<em:type>2</em:type> <!-- type=extension -->


<em:targetApplication> <!-- Firefox -->
                <!-- Firefox -->
<em:targetApplication>
<Description>
<Description>
<em:id>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</em:id>
<em:id>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</em:id>
<em:minVersion>0.9</em:minVersion>
<em:minVersion>0.9</em:minVersion>
<em:maxVersion>1.0</em:maxVersion>
<em:maxVersion>1.0</em:maxVersion>
</Description>
</em:targetApplication>
<em:targetApplication> <!-- Thunderbird -->
<Description>
<em:id>{3550f703-e582-4d05-9a08-453d09bdfdc6}</em:id>
<em:minVersion>0.7</em:minVersion>
<em:maxVersion>1.0</em:maxVersion>
</Description>
</em:targetApplication>
<em:targetApplication> <!-- Mozilla Suite -->
<Description>
<em:id>{86c18b42-e466-45a9-ae7a-9b95ba6f5640}</em:id>
<em:minVersion>1.7</em:minVersion>
<em:maxVersion>1.8</em:maxVersion>
</Description>
</Description>
</em:targetApplication>
</em:targetApplication>


                 <!-- This is not needed for Firefox 1.1 and later. Only include this  
                 <!-- This is not needed for Firefox 1.1 and later. Only include this  
                     if you want to be compatible with older versions -->
                     if you want to make your extension compatible with older versions -->
<em:file>
<em:file>
<Description about="urn:mozilla:extension:file:sampleext.jar">
<Description about="urn:mozilla:extension:file:sampleext.jar">
Line 74: Line 62:
</pre>
</pre>


==Generating a GUID==
== Target applications' GUIDs ==
You&rsquo;ll have to generate a GUID for each extension you create and put it inside the &lt;em:id&gt; tag. You can either download [http://www.microsoft.com/downloads/details.aspx?FamilyId=94551F58-484F-4A8C-BB39-ADB270833AFC&displaylang=en MS guidgen] (a GUID generator for Windows NT-based systems), use uuidgen (for *nix), use a web-based generator such as [http://kruithof.xs4all.nl/uuid/uuidgen this] and [http://www.hoskinson.net/webservices/guidgeneratorclient.aspx this], or open your [[IRC]] client, go to ''irc://irc.mozilla.org/#botbot'' and say 'botbot uuid'.
{|
|-
| Firefox
| <tt>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</tt>
|-
| Thunderbird
| <tt>{3550f703-e582-4d05-9a08-453d09bdfdc6}</tt>
|-
| Nvu
| <tt>{136c295a-4a5a-41cf-bf24-5cee526720d5}</tt>
|-
| Mozilla Suite
| <tt>{86c18b42-e466-45a9-ae7a-9b95ba6f5640}</tt>
|-
| SeaMonkey
| <tt>{92650c4d-4b8e-4d2a-b7eb-24ecf4f6b63a}</tt>
|-
| Sunbird
| <tt>{718e30fb-e89b-41dd-9da7-e25a45638b28}</tt>
|-
| Netscape Browser
| <tt>{3db10fab-e461-4c80-8b97-957ad5f8ea47}</tt>
|-
| Flock Browser
| <tt>{a463f10c-3994-11da-9945-000d60ca027b}</tt>
|}
 
 
=== Notes ===
* '''Mozilla Suite''' ignores ''install.rdf'', but you ought to include corresponding <tt>targetApplication</tt> item in ''install.rdf'' if you support the Suite and are going to submit your extension to [http://update.mozilla.org/ update.mozilla.org], see [http://forums.mozillazine.org/viewtopic.php?t=99246 this thread]. '''You still must include an [[install.js]] file if you support Mozilla Suite.'''
* '''"[http://wiki.mozilla.org/SeaMonkey:Home_Page SeaMonkey]"''' is now the name of the community project, that continues working on the Mozilla Suite codebase, after Mozilla Foundation has [http://www.mozilla.org/seamonkey-transition.html announced] it will not actively develop the Mozilla Suite any further. At the moment it doesn't read install.rdf, just as the Mozilla Suite, but it's planned to implement this in future.
* The <tt>em:type</tt> arc was introduced in '''Toolkit 1.1a''' applications. It's used to specify the type of an item. Use the value of 2 for extensions, 4 for themes.
 
== Items' IDs ==
Each extension must have a unique ID (the value of em:id arc).
 
Initially, it was recommended to use GUIDs for extensions IDs. To generate a GUID, you can use [http://www.microsoft.com/downloads/details.aspx?FamilyId=94551F58-484F-4A8C-BB39-ADB270833AFC&displaylang=en MS guidgen] (a GUID generator for Windows NT-based systems), uuidgen (for *nix, also comes with MSVS), a web-based generator such as [http://www.famkruithof.net/uuid/uuidgen this] and [http://www.hoskinson.net/GuidGenerator/ this], or open your [[IRC]] client, go to ''irc://irc.mozilla.org/botbot'' and say 'botbot uuid'.
 
Extension Manager in Toolkit 1.5-based applications '''will not install''' extensions using arbitrary strings as their IDs. Only GUIDs and IDs of ''extension@domain'' form are now accepted. For example, the DOM Inspector has ''inspector@mozilla.org'' ID.


As Firefox/Thunderbird install each extension in a folder with name taken from &lt;em:id&gt; in install.rdf, some people (e.g. clav) are using human-readable strings as ID for their extensions. However, extensions with such IDs are reported to be rejected by update.mozilla.org, so you need to use a 'real' GUID for your extension if you're going to submit it to u.m.o. ([http://forums.mozillazine.org/viewtopic.php?t=157579 discussion thread])
== Versioning ==
See [http://developer.mozilla.org/en/docs/Toolkit_version_format Toolkit version format] document for details about version's format used.


==Extension versioning==
== install.rdf for themes ==
As stated in the [http://www.mozilla.org/projects/firefox/extensions/update.html official documentation] on  mozilla.org, extension versions must be of form '''major.minor.release.build[+]'''. Old-style versions like 0.5pre are now invalid.
'''TBD.''' See [http://developer.mozilla.org/en/docs/Theme_Packaging#install.rdf]. The main difference is the additional "em:internalName" arc in theme's manifest.


[[Category:Development]]
[[Category:Development]]

Latest revision as of 04:05, 30 November 2008

This page is part of the extension development documentation project.

Ask your questions in MozillaZine Forums. Also try browsing example code.

Note: development documentation is in process of being moved to Mozilla Development Center (MDC).

Most of information here applies to install.rdf used in themes too. See below for detailed information.

Firefox 0.9, Thunderbird 0.7, Nvu 0.? and all subsequent versions of these products use the Extension Manager ("the EM") for managing extensions and themes. In order to have your extension supported by it you have to package your extensions as described in "Packaging Firefox/Thunderbird Extensions" document at mozilla.org (see also documentation at Devmo). This includes providing a valid install.rdf file.

Creating install.rdf using tools

You can use any of these tools:

Template

If you choose to manually create an "install.rdf" file, you can use the template below as a guide.

<?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">
	
		<em:id>{XXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}</em:id>
		<em:name>Sample Extension</em:name>
		<em:version>1.0</em:version>
		<em:description>A sample extension with advanced features</em:description>
		<em:creator>Your Name Here</em:creator>
		<!-- optional items -->
		<em:contributor>A person who helped you</em:contributor>
		<em:contributor>Another one</em:contributor>
		<em:homepageURL>http://sampleextension.mozdev.org/</em:homepageURL>
		<em:optionsURL>chrome://sampleext/content/settings.xul</em:optionsURL>
		<em:aboutURL>chrome://sampleext/content/about.xul</em:aboutURL>
		<em:iconURL>chrome://sampleext/skin/mainicon.png</em:iconURL>
		<em:updateURL>http://sampleextension.mozdev.org/update.rdf</em:updateURL>
		<em:type>2</em:type> <!-- type=extension --> 

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

                <!-- This is not needed for Firefox 1.1 and later. Only include this 
                     if you want to make your extension compatible with older versions -->
		<em:file>
			<Description about="urn:mozilla:extension:file:sampleext.jar">
				<em:package>content/</em:package>
				<!-- optional items -->
				<em:skin>skin/classic/</em:skin>
				<em:locale>locale/en-US/</em:locale>
				<em:locale>locale/ru-RU/</em:locale>
			</Description>
		</em:file>
	</Description>

</RDF>

Target applications' GUIDs

Firefox {ec8030f7-c20a-464f-9b0e-13a3a9e97384}
Thunderbird {3550f703-e582-4d05-9a08-453d09bdfdc6}
Nvu {136c295a-4a5a-41cf-bf24-5cee526720d5}
Mozilla Suite {86c18b42-e466-45a9-ae7a-9b95ba6f5640}
SeaMonkey {92650c4d-4b8e-4d2a-b7eb-24ecf4f6b63a}
Sunbird {718e30fb-e89b-41dd-9da7-e25a45638b28}
Netscape Browser {3db10fab-e461-4c80-8b97-957ad5f8ea47}
Flock Browser {a463f10c-3994-11da-9945-000d60ca027b}


Notes

  • Mozilla Suite ignores install.rdf, but you ought to include corresponding targetApplication item in install.rdf if you support the Suite and are going to submit your extension to update.mozilla.org, see this thread. You still must include an install.js file if you support Mozilla Suite.
  • "SeaMonkey" is now the name of the community project, that continues working on the Mozilla Suite codebase, after Mozilla Foundation has announced it will not actively develop the Mozilla Suite any further. At the moment it doesn't read install.rdf, just as the Mozilla Suite, but it's planned to implement this in future.
  • The em:type arc was introduced in Toolkit 1.1a applications. It's used to specify the type of an item. Use the value of 2 for extensions, 4 for themes.

Items' IDs

Each extension must have a unique ID (the value of em:id arc).

Initially, it was recommended to use GUIDs for extensions IDs. To generate a GUID, you can use MS guidgen (a GUID generator for Windows NT-based systems), uuidgen (for *nix, also comes with MSVS), a web-based generator such as this and this, or open your IRC client, go to irc://irc.mozilla.org/botbot and say 'botbot uuid'.

Extension Manager in Toolkit 1.5-based applications will not install extensions using arbitrary strings as their IDs. Only GUIDs and IDs of extension@domain form are now accepted. For example, the DOM Inspector has inspector@mozilla.org ID.

Versioning

See Toolkit version format document for details about version's format used.

install.rdf for themes

TBD. See [2]. The main difference is the additional "em:internalName" arc in theme's manifest.