install.rdf

개요

Install Manifest 파일은 설치된 부가기능에 대한 정보를 확인하기 위해 부가기능 관리자가 사용하는 파일입니다. 이 파일에는 부가기능을 확인하기 위한 메타데이터를 포함하며, 누가 만들었는지, 어디서 더 자세한 정보를 얻을 수 있는지, 어떤 응용 프로그램의 버전과 호환되는지, 어떻게 업데이트하는지 등에 대한 정보를 제공합니다.

Install Manifest 파일은 RDF/XML 포맷입니다.

파일 이름은 install.rdf이어야 하며 부가기능의 XPI 파일 내 최상위 경로에 위치해야 합니다.

구조

Install Manifest의 기존 구조는 다음과 같습니다.

<?xml version="1.0"?>

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

어떤 속성들은 필수이고 어떤 것들은 선택사항 입니다. 또, 어떤 값은 단순 문자열이고 어떤 것들은 복합 리소스(complex resources)입니다.

필수 속성 참조(reference)

Install Manifest에는 다음 속성들이 정확하게 명시되어야 하며, 그렇지 않을 경우 설치되지 않습니다.

id

확장기능의 id로 다음과 같습니다.

• GUID(Windows에서는 guidgen으로, Linux에서는 uuidgen, Solaris에서는 makeuuid로 생성합니다) (Firefox 1.0)
• 다음과 같은 형식의 문자열: [email protected]

후자 포맷이 전자에 비해 더 쉽게 만들고 관리할 수 있습니다. Firefox 1.5는 id가 어떤 포맷에 해당하는지 확인하고 잘못된 포맷일 경우 설치되지 않습니다.

예제

<em:id>[email protected]</em:id>

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

version

제공되는 부가기능의 버전을 나타내는 문자열입니다.

Firefox/Thunderbird 1.0에서는 Extension Versioning, Update and Compatibility에서 설명하는 규칙을 만족해야 합니다. Firefox/Thunderbird 1.5에서는 Toolkit version format을 참조하세요.

예제

<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 - 유효하지 않은 버전 포맷을 사용한 부가기능은 설치되지 않습니다. 버전 포맷은 1.0 버전대와 하위 호환성이 존재하지만 서로 다른 포맷입니다.

addons.mozilla.org에서 호스팅되는 부가기능 - Mozilla의 업데이트 웹사이트에서는 여러분이 업로드한 부가기능의 버전 문자열을 확인하여 잘못된 경우 수정여 다시 패키징하거나 반송할 수 있습니다.

type

부가기능의 유형을 나타내는 정수값입니다.

예제

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

이 속성은 Firefox 1.5에서부터 추가되었고, 확장기능이나 테마가 아닌 다른 유형일 경우에만 필수 항목입니다.

Firefox 2 및 이전 버전에서는 16은 플러그인을 나타내는 값으로 사용되었습니다. 이 값은 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.

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.

Extensions compatible with Firefox 2 should specify a maxVersion of 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)

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 [email protected] to say that the add-on is compatible with any toolkit app with a toolkit version matching the minVersion and maxVersion.

name

UI에 출력되기 위해 사용하는 부가 기능의 이름입니다.

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

예제

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

Optional Property Reference

You may need to supply these properties, depending on the capabilities of your 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.

Examples

This declares a set of add-on metadata to be displayed when the application is running in the de-DE locale.

<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.

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.

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

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

Examples

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

updateURL

부가기능에 대한 업데이트 정보를 제공하는 Update Manifest 파일에 대한 링크입니다. 포맷은 아래에 설명되어 있습니다. 부가기능이 사용 가능한 상태인 경우, 부가기능 관리자는 주기적으로 해당 Manifest 파일을 검사하고 새로운 버전이 있는지 확인합니다.

보안상 이유로, Gecko 1.9 응용 프로그램에서는 반드시 updateURL가 https url이어야 하며, 그렇지 않을 경우 updateKey를 포함해야 합니다.

서버는 이 파일을 text/rdf로 전송해야 하고, 그렇지 않으면 업데이트 검사가 동작하지 않습니다. mozdev.org에 있는 프로젝트에서는 text/xml도 동작하는거 같습니다.

응답 RDF를 PHP나 CGI를 사용하여 동적으로 생성하고자 할 경우 다음의 치환자를 사용할 수 있으며, 부가기능 관리자가 자동으로 변환해서 요청합니다.

예제

<em:updateURL>https://www.foo.com/update.cgi?id=%ITEM_ID%&amp;version=%ITEM_VERSION%</em:updateURL>
<em:updateURL>https://www.foo.com/extension/windows.rdf</em:updateURL>

addons.mozilla.org에서 호스팅되는 부가기능의 경우: 이 경우 updateURL 속성을 명시하지 않아도 됩니다. 기본적으로 부가기능 관리자를 사용하는 Mozilla 응용프로그램(Firefox, Thunderbird)은 기본 웹 서비스를 사용하여 addons.mozilla.org에 업데이트 요청을 보냅니다. 새로운 버전의 부가기능을 업로드하거나, AMO에서 제공하는 인터페이를 통하여 호환성 인자를 변경할 경우 해당 업데이트 선언이 자동으로 갱신됩니다.

업데이트 선언의 포맷: 업데이트 선언은 RDF/XML 데이터원본입니다. Extension Versioning, Update and Compatibility 과 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.
• 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.