Install Manifests

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.

        安装显示清单是一个XUL应用插件管理工具,用以确定被安装插件的重要信息。例如:该插件识别号、创作者、从哪里可以找到有关该插件的更多资讯、该插件目前的版本号以及如何更新该插件等信息。

The format of the Install Manifest is RDF/XML.

安装显示清单的格式是RDF或者XML。

The file must be called install.rdf and live at the top level of an addon's XPI file.
译:清单文件必须要命名为install.rdf并且位于扩展的XPI文件中最顶级(XPI是ZIP格式的压缩文件, 这里的"最顶级"指的是在压缩文件内部清单文件应该位于根路径级别).

Layout (内容布局)

The basic layout of an Install Manifest is like so:
译:Install清单内容的基本布局如下:

<?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.
译:你的Install清单必须要正确的指定那些必要的属性, 否则你的addon可能不能够安装.

id

The id of the extension, which is a: (扩展的id属性是:)

  • GUID (generate using guidgen on Windows, uuidgen on Linux and makeuuid on Solaris) (Firefox 1.0) 译:GUID(GUID的生成, Windows上使用guidgen, Linux上使用uuidgen, Solaris上使用makeuuid)
  • A string formatted like so: extensionname@organization.tld 译:一个字符串格式, 如extensionname@organization.tld

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.
译:后一种格式是重要的用于更简单的生成和操作id. Firefox1.5将进行检查以确保你的id属于第一种格式或者是另一种, 并且将拒绝安装拥有不符合要求id的addon.

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.
译:版本字符串作为标识addon的版本被提供.

For Firefox/Thunderbird 1.0, the format must conform to the rules specified in Extension Versioning, Update and Compatibility. For Firefox/Thunderbird 1.5, see Toolkit version format.
译:对于Firefox/Thunderbird 1.0, 版本格式必须要符合指定的规则Extension Versioning, Update and Compatibility. 对于Firefox/Thunderbird 1.5参见Toolkit version format

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 / XULRunner 1.8 - addons that do not use a valid version format will not be installed. The version format is different from, although backwards-compatible with, 1.0's.
译:对于Firefox 1.5 / XULRunner 1.8, 没有使用有效格式版本信息的addon将不能够被安装. 尽管存在着向下兼容, 但与1.0的版本格式不相同addon仍然不能够被安装.

For addons hosted on addons.mozilla.org - Mozilla's update website may repackage your addon and correct or reject malformed version strings.
译:对于已经在addons.mozilla.org服务器上的addons, Mozilla的更新站点可能会重新包装你的addon或者调整不符合要求的版本字符串.

type (类型)

An integer value representing the type of addon.
译:一个表示addon类型的整型值.

2 Extensions
4 Themes
8 Locale
32 Multiple Item Package

Examples

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

This property was added for Firefox 1.5, and is only required for addon types other than Extensions and Themes.
译: 对于Firefox1.5这个属性已经被添加了, 并且仅对于addon来讲是必要的, 除了Extensions和Themes.

Firefox 2 and previous supported a value of 16 to represent plugins. In Firefox 3 this has been removed.
译: Firefox 2和它的前续版本已经支持值为16的整型值用以表示plugins. 在Firefox 3中这个属性已经被移除.

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 (<em:id>) specified (for a comprehensive list of application IDs see Valid application versions for add-on developers), from the minimum version (<em:minVersion>) up to and including the maximum version (<em:maxVersion>). These version strings are formatted in the same fashion as the version property and will be compared to the application version; this allows the extension author to specify which versions of Firefox an extension has been tested with.
译:一个object通过addon来指定一个应用程序目标. 意思是说将与应用程序一起工作的addon通过指定的id属性(<em:id>)被识别(for a comprehensive list of application IDs see Valid application versions for add-on developers), 识别过程从最小版本(<em:minVersion>)一直到最大版本(<em:maxVersion>). 这些版本字符串采用相同的方式定义version property并且将被与应用程序的版本进行比较; 这允许extension作者去指定哪个Firefox的版本是extension已经测试通过的.

Note: Firefox 1.0-1.0.6 all have an application version of 1.0. Security and stability updates of Firefox 1.5 have application version 1.5.0.1, 1.5.0.2, etc. Extensions compatible with Firefox or Thunderbird 1.5 should specify a maxVersion of 1.5.0.*, so that they are automatically compatible with security and stability updates.
译:注意:Firefox 1.0-1.0.6有着相同的一个应用程序版本号1.0. Firefox 1.5的安全更新与稳定性更新分别对应的应用程序版本号为1.5.0.1和1.5.0.2等. Extensios要与Firefox 1.5或者Thunderbird 1.5相兼容, 那么需要指定maxVersion属性为1.5.0.*, 那么这样做extensions将自动与安全更新与稳定性更新相兼容.

Extensions compatible with Firefox 2 should specify a maxVersion of 2.0.0.*
Extensions如想与Firefox 2相兼容, 那么应该指定maxVersion为2.0.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)
译:Install清单文件至少要指定这些版本中的一个, 更可能需要指定更多如果addon目标是与多个支持Addon Manager(Addon管理器)的应用程序(比如, Firefox和Thunderbird)相兼容.

Examples

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

Gecko 1.9 based applications allow you to use the special targetApplication id toolkit@mozilla.org to say that the add-on is compatible with any toolkit app with a toolkit version matching the minVersion and maxVersion.
译:基于Gecko 1.9的应用程序允许你使用特殊的targetApplication(目标应用程序) id toolkit@mozilla.org以要求add-on与任何版本在mi...之间toolkit应用相兼容.

name

The name of the addon- intended for display in the UI.
译:addon的name用来在UI中显示.

Examples

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

Optional Property Reference (可选的属性)

You may need to supply these properties, depending on the capabilities of your add-on. 译:你可能需要提供些可选属性, 这要视你的add-on的实现功能而定.

localized (本地化)

Allows you to localize the add-on's name, description, contributors and other metadata. The localized description must specify at least one em:locale which indicates which locales to use this information for.
译: 允许你本地化add-on的名称, 描述, 贡献者(不能肯定这么翻译)和其它的元数据. 本地化描述必须要指定至少一个em:locale用以指出要使用哪个本地化信息.

Examples

This declares a set of add-on metadata to be displayed when the application is running in the de-DE locale.
译:当应用程序运行于de-DE区域中时, 以下则是用于被显示的add-on元数据的一组定义.

<em:localized>
  <Description>
    <em:locale>de-DE</em:locale>
    <em:name>Tab Sidebar</em:name>
    <em:description>Zeigt in einer Sidebar Vorschaubilder der Inhalte aller offenen Tabs an.</em:description>
  </Description>
</em:localized>

The following properties which are described elsewhere in this page can be included in the localized property:
译:以下属性是在本页的其它位置所描述的并可以被包含在本地化属性中的.

  • name
  • description
  • creator
  • homepageURL
  • developer
  • translator
  • contributor

More documentation can be found at Localizing extension descriptions. 译:更多的文档可以在这里找到Localizing extension descriptions.

description (描述)

A short description of the add-on - intended for display in the user interface. This description should fit on one short line of text.
译:一个简短的打算被显示在用户界面上的add-on描述. 这个描述应该简短到一行文本.

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>

or

<em:creator>CoolExtension Team</em:creator>

developer (开发人员)

The name(s) of co-developers. You may specify more than one of this value to specify multiple developers.
译:联合开发人员的名称. 你可能要指定一人以上的这个值以指定多开发人员.

Examples

<em:developer>Jane Doe</em:developer>
<em:developer>Koos van der Merwe</em:developer>

translator (翻译人员)

The name(s) of translators. You may specify more than one of this value to specify multiple translators.
译:翻译人员的名称. 你可能要指定一个以上的这个值以指定多个翻译人员.

Examples

<em:translator>Janez Novak</em:translator>
<em:translator>Kari Nordmann</em:translator>

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 (主页URL)

A link to the addon's home page - intended for display in the user interface.
译:打算显示在用户界面里的addon的主页连接.

Examples

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

updateURL (更新URL)

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.
译:一个到自定义的更新清单文件的连接, 它指定了该附件(addon)可用的更新. 该URL格式在下边描述. 如果更新URL是允许的, 那么addon管理器会周期性的检查更新清单以确定是否有新的版本可用.

Note: It is strongly recommended that the updateURL be an HTTPS (secure) link. Non-secure update URLs can be hijacked by a malicious update.rdf file, enabling malware to infiltrate the user's computer. Alternatively, you could host your extension on AMO and leave out the updateURL completely. This provides secure updates automatically.

译:注意:强烈建议updateURL是一个HTTPS(安全的)连接. 非安全的更新URL能被恶意的update.rdf文件所拦截, 然后允许恶意的入侵用户计算机. 另一个解决办法就是, 将你的extension放在AMO上并且完全省去updateURL. 这样将自动能够提供安装的更新.

For security reasons, Gecko 1.9 applications require that if you specify an updateURL, it must be an https URL, or you must include an updateKey.
译:为了安全的原因, Gecko 1.9应用程序要求如果你指定了一个updateURL, 那么就必须是一个https URL, 或者你必须要包含一个updateKey.

If your plugin or extension that contains install.rdf file is intended to users of Firefox 2 version (Not for FireFox 3, just FireFox 2), you can just skip HTTPS or updateKey stuffs!</br>

译:如果你的plugin或者extension包含install.rdf文件, 并打算在Firefox 2版本上使用(仅针对Firefox 2, 而不是Firefox 3), 你可以跳过HTTPS或者updateKey stuffs!

Your server must send this file as text/rdf or the update checker will not work. text/xml also seems to work (projects on mozdev.org)

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:

%REQ_VERSION% The version of the request. Currently 1
%ITEM_ID% The id of the addon being updated
%ITEM_VERSION% The version of the addon being updated
%ITEM_MAXAPPVERSION% The maxVersion of the targetApplication object corresponding to the current application for the addon being updated.
%ITEM_STATUS% Comma separated list of the add-ons operating status in the application. Contains at the least either userEnabled or userDisabled plus any number of incompatible, blockslisted or needsDependencies.
%APP_ID% The id of the current application
%APP_VERSION% The version of the current application
%APP_OS% The value of OS_TARGET from the Firefox build system, identifying the operating system being used.
%APP_ABI% The value of the TARGET_XPCOM_ABI value from the Firefox build system, identifying the compiler/architecture combination used to compile the current application.
%APP_LOCALE% The current application's locale.

Examples

<em:updateURL>http://www.foo.com/update.cgi?id=%ITEM_ID%&amp;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 addons.mozilla.org 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. For examples of an update manifest, see Extension Versioning, Update and Compatibility and Enabling Extension Updates (external).

updateKey

To ensure the security of update rdf data that is retrieved over plain http you must use a digital signature to verify the contents of the data. In order to do so you must include the public part of the cryptographic key in an updateKey entry in the install.rdf of the add-on. This can be generated using the McCoy tool. Any line breaks and whitespace as part of this entry are ignored.

Examples

<em:updateKey>MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDK426erD/H3XtsjvaB5+PJqbhj
              Zc9EDI5OCJS8R3FIObJ9ZHJK1TXeaE7JWqt9WUmBWTEFvwS+FI9vWu8058N9CHhD
              NyeP6i4LuUYjTURnn7Yw/IgzyIJ2oKsYa32RuxAyteqAWqPT/J63wBixIeCxmysf
              awB/zH4KaPiY3vnrzQIDAQAB</em:updateKey>

optionsURL

The chrome:// 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 chrome:// 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 chrome:// 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>

Note: For the above example to work you will also have to add a skin package line to your chrome.manifest file. See Chrome Registration#skin. Alternatively you can place your icon in the directory specified in your content package line.

hidden

A boolean value that when true makes the add-on not show up in the add-ons list, provided the add-on is installed in a restricted access area (so it does not work for add-ons installed in the profile). 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>

targetPlatform

A string specifying a platform that the addon supports. It contains either the value of OS_TARGET alone or combined with TARGET_XPCOM_ABI, separated by an underscore (_).

OS_TARGET is typically the output of the 'uname -s' command on the target platform, e.g.:

  • WINNT for Windows NT, 2000, XP and later
  • Linux for all Linux versions
  • Darwin for all MacOS X versions
  • SunOS for all Solaris versions

You can specify multiple targetPlatform properties per manifest. If any value matches the application's build parameters, it will be installed; if not, the user will get an appropriate error message.

Examples

<em:targetPlatform>WINNT_x86-msvc</em:targetPlatform>

<em:targetPlatform>Linux</em:targetPlatform>

<em:targetPlatform>Darwin_ppc-gcc3</em:targetPlatform>

<em:targetPlatform>SunOS_sparc-sunc</em:targetPlatform>

Usually, you would use only the OS part for themes or for extensions that are not fully cross-platform. For extensions including binary (compiled) components, you should never use the OS alone, but include the ABI (s) that you compiled the components with. If you want to include multiple versions of the components, you should also use Platform-specific Subdirectories.

Notes

  • In the same manifest file, you could even mix values with and without ABI. If a value for the application's OS is encountered that requires any specific ABI, the ABI is considered important for that OS and the application will refuse to install the addon if it does not find a matching OS/ABI combination. This means that if all of the above examples would occur in one manifest, the addon will install on any Linux build of the application, regardless of its ABI, but not on a Windows Cygwin build.
  • There may be builds of Firefox and Thunderbird which do not "know" their ABI (most likely ports to rare platforms, or non-official builds). These builds will refuse to install any addon that requires a specific ABI for their platform.

This property was added for Firefox/Thunderbird 1.5. Previous versions of these applications will ignore the restrictions and install the addon regardless of the platform.

requires

This tag has a similar syntax to the <em:targetApplication> tag. If the addon specified by the <em:id> tag is not installed or has an incompatible version, the extension manager will disable your extension and show the message "Requires additional items". You can add as many <em:requires> tags as you like. Your extension will be disabled if any of the specified requirements fail.

Example

<em:requires>
   <Description>
     <!-- Lightning -->
     <em:id>{e2fda1a4-762b-4020-b5ad-a41df1933103}</em:id>
     <em:minVersion>0.5pre</em:minVersion>
     <em:maxVersion>0.5pre</em:maxVersion>
   </Description>
 </em:requires>

Notes

  • Currently, only <em:id>, <em:minVersion>, <em:maxVersion> are parsed inside the <em:requires> tag.
    (译:目前只有<em:id>, <em:minVersion>, <em:maxVersion>能够写在<em:requires>标签里)
  • It is not currently possible to add dependencies that are specific to a <em:targetApplication>. See wikimo:Extension Manager:Extension Dependencies for more details.

This property was added for Firefox/Thunderbird 2. Previous versions of these applications will ignore the restrictions and install the addon regardless of the requirements.

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 .jar file that contains chrome packages that require registration with the Chrome Registry.

The <em:file> property has a complex object value. The uri of the value is urn:mozilla:extension:file:jarFile.jar where jarFile.jar 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. urn:mozilla:extension:file:directory). In either case, the referenced chrome package file(s) must be placed in the chrome subdirectory of the XPI's top level.

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

In extensions for Firefox 1.5, this property is no longer necessary: the chrome.manifest 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 file properties, one for each jar file or subdirectory that contains chrome to register.

Glossary

restricted access area

A restricted access area is an install location that could be restricted on a restricted-access account, regardless of whether or not the location is restricted with the current user privileges (see nsIInstallLocation::restricted). Currently, the ($APPDIR)/extensions folder and the registry install location under HKEY_LOCAL_MACHINE (see Adding Extensions using the Windows Registry for details) are restricted.

The ($PROFILE)/extensions and HKEY_CURRENT_USER install locations, on the other hand, are not restricted.

Document Tags and Contributors

Contributors to this page: vika0322, Xoosye, Duwei, fscholz, ethertank, Efree, whongfei, Mgjbot, Dehuai
最后编辑者: ethertank,