Install Manifests
出典: MDC
目次 |
[編集] はじめに
インストールマニフェスト(Install Manifest)はアドオンの使えるXULアプリケーションで、アドオンがアプリケーションにインストールされる必要な情報を持っています。例えば、アドオンを特定するためのIDや、作成者名などの情報、適合バージョン、アドオン自身のバージョンなどを含んでいます。
インストールマニフェストの形式は RDF/XML です。
ファイル名は必ず install.rdf とし、XPIファイル(パッケージ)の最上位(直下)におきます。
[編集] レイアウト
基本的なインストールマニフェストは下記のようになってます:
<?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>
プロパティには必須項目とオプション項目があります。また、プロパティに設定する値には単純に文字列を配置するものと、決められたものを設定するものがあります。
[編集] 必須のプロパティ リファレンス
インストールマニフェストには以下の必ず設定しなくてはならないプロパティがあります。以下の項目を正しく設定しないと、アドオンがインストールされないので注意が必要です。
[編集] id
アドオンの id :
- Firefox 1.0: GUID (Windowsは guidgen で生成/ Unixは uuidgen で生成)
- Firefox 1.5 以降: extensionname@organization.tld のようなフォーマット
後者のidは作りやすく、扱いやすいです。Firefox 1.5はidが正しいかを判定し、不正なid(フォーマットに合致しないid)の場合はインストールを行いません。
例
<em:id>myextension@mysite.com</em:id>
<em:id>{daf44bf7-a45e-4450-979c-91cf07434c3d}</em:id>
[編集] version
アドオンのバージョン情報を記述します。
例
<em:version>2.0</em:version> <em:version>1.0.2</em:version> <em:version>0.4.1.2005090112</em:version>
Firefox/Thundebird 1.0 - Extension Versioning, Update and Compatibility で決められた形式に従わなくてはなりません。 Firefox/Thundebird 1.5 / XULRunner 1.8 - Toolkit version format に沿うようにしてください。正しいバージョン名を記述しない場合はインストールされません。また、Firefox 1.0などで用いた記述方式はサポートされていません。 addons.mozilla.org - Mozillaのアップデートサイトではアドオンを再パッケージするため、バージョン情報を校正したり、不正なバージョン情報を拒否したりするかもしれません。
[編集] type
追加機能の種類を下記の数値で表します。
| 2 | 拡張機能 |
| 4 | テーマ |
| 8 | ロケール |
| 32 | Multiple Item Package |
例(拡張機能の場合)
<em:type>2</em:type>
Firefox 1.5 の新機能このプロパティは Firefox 1.5 で追加されました。なお、拡張機能/テーマ以外の場合は必ず記述しなくてはなりません。
Firefox 3 の新機能 Firefox 2およびそれ以前のバージョンは、「プラグイン」を示すために16という値をサポートしていました。Firefox 3ではこの機能は取り除かれました。
[編集] targetApplication
拡張の対象となる(拡張も含む)アプリケーションを指定します。 アドオンが動くアプリケーション(ターゲットアプリケーション)を下記のプロパティにより限定します。
- ターゲットアプリケーションのidプロパティ(<em:id>)
- 包括的なアプリケーションIDのリストは Mozilla Addons FAQ の "Valid App Versions for Addon Developers" に記述されています。
- 特定のバージョン以降を指定するminVersionプロパティ (<em:minVersion>)
- 特定のバージョン以前を指定するmaxVersionプロパティ (<em:maxVersion>)
- minVersion および maxVersion の値はversion プロパティと同じフォーマットで記述します。アプリケーションはこれらの値を元にインストールできるかを判断されます。これにより、配布者はこのプロパティによりテストに適合したものを提供することができます。
ノート: Firefox 1.0-1.0.6 では共通のバージョンが 1.0 となります。 Firefox 1.5 でのセキュリティアップデートや安定性向上のためのアップデートでのバージョンは 1.5.0.1, 1.5.0.2, などとなります。 アドオンの対応バージョンをFirefox/Thunderbird 1.5とする場合は maxVersion を 1.5.0.* とします。
インストールマニフェストは上記のプロパティの最低1つを指定しなくてはなりません。(特にアドオンマネージャを搭載する Firefox/Thunderbirdについて)アドオンの対応するアプリケーションが複数ある場合はさらに指定しなくてはなりません。
例
<em:targetApplication>
<Description>
<em:id>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</em:id>
<em:minVersion>1.0</em:minVersion>
<em:maxVersion>1.5.0.*</em:maxVersion>
</Description>
</em:targetApplication>
Firefox 3 の新機能 Gecko 1.9ベースのアプリケーションでは、ツールキットのバージョンが指定されたminVersionとmaxVersionにマッチしているすべてのツールキット アプリケーションに対して互換性があることを示すための特殊なtargetApplicationのidとして、toolkit@mozilla.orgが利用できます。
[編集] name
UI(アドオン一覧)に表示される名前。
例
<em:name>My Extension</em:name>
[編集] オプション プロパティ リファレンス
必要であれば、下記のプロパティを記述します。
[編集] localized
Firefox 3 の新機能 アドオンの名前、説明文、貢献者名、その他のメタデータをローカライズすることができます。ローカライズされた説明文は、どの言語においてその情報を使うのかを示す最低一つのem:localeを含んでいなければなりません。
例
この例は、アプリケーションがde-DEのロケール設定で起動している際に表示されるアドオンのメタデータのセットを示すものです。
<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>
このページもしくは他の箇所で説明されている、以下のプロパティを、localizedプロパティの中に含めることができます。
- name
- description
- creator
- homepageURL
- developer
- translator
- contributor
より詳しい情報については拡張機能のローカライズを参照してください。
[編集] description
UI(アドオン一覧)に表示される説明。持っている機能を説明するのに用いられます。表示領域が狭いため、短く記述したほうが良いでしょう。
例
<em:description>Advanced foo tools.</em:description>
[編集] creator
作成者/メインプログラマの名前。アドオンの情報に表示されます。
例
<em:creator>John Doe</em:creator>
もしくは
<em:creator>CoolExtension Team</em:creator>
[編集] developer
開発者の名前。複数の名前を記述することができます。 Firefox 2.0での新機能です。
例
<em:developer>Jane Doe</em:developer> <em:developer>Koos van der Merwe</em:developer>
[編集] translator
翻訳者(ロケール作成者)の名前。複数の名前を記述することができます。 Firefox 2.0での新機能です。
例
<em:translator>Janez Novak</em:translator> <em:translator>Kari Nordmann</em:translator>
[編集] contributor
寄付者/貢献者の名前。複数の名前を記述することができます。
例
<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
アドオンのホームページアドレス。アドオンの情報からアクセスできます。
例
<em:homepageURL>http://www.foo.com/</em:homepageURL>
[編集] updateURL
拡張を更新するためのアップデートマニフェストファイルへのリンク(URL)。このプロパティを定義した場合、拡張マネージャが定期的に更新がないかを自動的にチェックします。
updateURL は HTTPS (安全な) リンクであることが強く推奨されます。安全ではない更新 URL は悪意のある update.rdf によって乗っ取られる (hijacked) 可能性があります。これは悪意のあるソフトウェア (malware) がユーザのコンピュータへ侵入することを可能にします。代わりにあなたの拡張を AMO でホストし、updateURL を完全に取り除くことができます。これは自動的に安全な更新を提供します。Firefox 3 の新機能 Gecko 1.9ベースのアプリケーションではセキュリティ上の理由から、updateURLにhttpsのURLを指定するか、もしくはupdateKeyを含める必要があります。
更新を提供するサーバは必ずtext/rdf形式で送信を行うようにしてください。text/xml形式でも可能のようです(mozdev.org プロジェクトはそのように設定されている)
アドオンマネージャは以下に示す部分に値を入れて、PHPやCGIでRDFを動的に生成する手助けをします。
| %REQ_VERSION% | リクエストのバージョン。通常は 1 |
| %ITEM_ID% | アドオンのid |
| %ITEM_VERSION% | 現在のアドオンのversion |
| %ITEM_MAXAPPVERSION% | 現在のアドオンのサポートする targetApplication の maxVersion |
| %APP_ID% | 現在のアプリケーションのid |
| %APP_VERSION% | 現在のアプリケーションのversion |
| %APP_OS% | 現在のアプリケーションのOS_TARGETの値。現在のOSのことを指す。Firefox 1.5からの新機能 |
| %APP_ABI% | 現在のアプリケーションがビルドされた環境(コンパイラおよびアーキテクチャ)を示す TARGET_XPCOM_ABI の値。 Firefox 1.5からの新機能 |
例
<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>
addons.mozilla.org: Mozillaのアップデートサイトを利用する場合は updateURL プロパティを指定しなくてもいいでしょう。 アドオンマネージャを使っているFirefoxやThunderbirdなどのMozillaアプリケーションはデフォルトでaddons.mozilla.orgに更新がないかを問い合わせます。新しいバージョンのアドオンをアップデートサイトにアップロードするたびに自動的にこのプロパティを更新/追加を行います。
アップデートマニフェストのフォーマット: アップデートマニフェストUpdate Manifest は RDF/XML 形式です。詳細は右のリンクを辿ってってください。アップデートマニフェストのサンプルは Extension Versioning, Update and Compatibility / Enabling Extension Updates (external) を参照してください。
[編集] updateKey
Gecko 1.9 で導入
この記事は Firefox 3 の新機能について述べています
通常のhttp通信を通じて取得された更新情報のRDFデータのセキュリティを保証するために、あなたはデータの内容を検証するための電子署名を使わなくてはなりません。そのため、あなたは暗号鍵の公開鍵をアドオンのinstall.rdfのupdateKeyエントリに含める必要があります。これはMcCoyというツールを使うことで生成できます。このエントリ中の改行や空白文字はすべて無視されます。
例
<em:updateKey>MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDK426erD/H3XtsjvaB5+PJqbhj
Zc9EDI5OCJS8R3FIObJ9ZHJK1TXeaE7JWqt9WUmBWTEFvwS+FI9vWu8058N9CHhD
NyeP6i4LuUYjTURnn7Yw/IgzyIJ2oKsYa32RuxAyteqAWqPT/J63wBixIeCxmysf
awB/zH4KaPiY3vnrzQIDAQAB</em:updateKey>
[編集] optionsURL
オプションダイアログの chrome:// URL を指定してください。このオプションは拡張機能のインストールマニフェストでしか有効になりません。このプロパティが設定されていると、拡張機能一覧のコンテキストメニュー(右クリックメニュー)から設定(オプション)ダイアログを開くことができるようになります。
例
<em:optionsURL>chrome://myext/content/options.xul</em:optionsURL>
[編集] aboutURL
説明ダイアログの chrome:// URL を指定してください。このオプションは拡張機能のインストールマニフェストでしか有効になりません。このプロパティが設定されていると、拡張機能一覧のコンテキストメニュー(右クリックメニュー)から説明ダイアログを開くことができるようになります。指定しない場合は、デフォルトのダイアログが表示されます。
例
<em:aboutURL>chrome://myext/content/about.xul</em:aboutURL>
[編集] iconURL
アドオン一覧に表示するアイコン(32x32)の chrome:// URL を指定します。指定しない場合はアプリケーションのデフォルトのアイコンが使われます。
例
<em:iconURL>chrome://myext/skin/icon.png</em:iconURL>
[編集] hidden
アドオン一覧に表示するかどうかを真偽値で設定します。値にはtrue/falseを設定します。trueが設定されている場合はアドオン一覧に表示されません。アドオンがアクセスが制限された領域にインストールされる場合に設定します。（よって、プロファイルにインストールされるアドオンに対しては効果がありません。）これは、アドオンが一覧に表示されては困る大きなアプリケーションのフックの統合のためにあります。指定しない場合はfalseが設定されます。
例
<em:hidden>true</em:hidden>
[編集] targetPlatform
アドオンが対応するOS(プラットフォーム)を指定します。OS_TARGET の値のみ もしくは OS_TARGET の値 と TARGET_XPCOM_ABI の値を _ (アンダーコア)で繋げた文字列を指定します。
OS_TARGET の値は 普通コマンドライン上で 'uname -s' と入力し、帰ってきた値を記述します。例えば、以下のようになります:
-
WINNTWindows NT, 2000, XP 以降 -
Linuxすべての Linux -
Darwinすべての MacOS X
個々のマニフェストファイルにより複数の targetPlatform プロパティを指定することができます。複数のうちどれかの値が条件を満たす場合はアドオンがインストールされます。逆に、どれも条件を満たさない場合はインストールされません。インストールされない場合はその旨の警告が表示されます。
例
<em:targetPlatform>WINNT_x86-msvc</em:targetPlatform> <em:targetPlatform>Linux</em:targetPlatform> <em:targetPlatform>Darwin_ppc-gcc3</em:targetPlatform>
普通は、特定のOSにのみ対応しているテーマや拡張のためにこの属性のみを使うでしょう。(コンパイルされた)バイナリデータを含む拡張のために、この属性のみならず、コンパイルした ABI (s) も含んでください。複数のバージョンのバイナリを同封したい場合は Platform-specific Subdirectories も利用してください。
ノート
- 同じマニフェストファイルで、ABIを含む値と含まない値を一緒に使うことができるかもしれません。あるアプリケーションのOSに対する値が特定のABIを含んだものにヒットした場合、ABIはOSとABIの組み合わせが一致しないときにアドオンをインストールしないことを重要だと判断します。 なぜ一致しないケースを優先するのかというと、上記の例を1つのマニフェストに記述した場合、ABIを判断せずに Windows Cygwin用ではなくLinux用のパッケージをインストールしてしまいます。
- ABIがわからない Firefox / Thunderbird が存在することがあります。(希少なプラットフォームや正規版でないもの) そのような環境で、アドオンがプラットフォームについて詳細なABIを要求するときはインストールされません。
Firefox 1.5 このプロパティは Firefox/Thunderbird 1.5 で追加されました。以前のバージョンではこれらの制限を無視し、どのOSに対してもインストールを行ってしまいます。
[編集] requires
Firefox 2 の新機能 このタグは<em:targetApplication>と似た文法を持っています。もし<em:id>タグによって示されたアドオンがインストールされていないか、もしくは非対応のバージョンである場合、拡張機能マネージャはあなたの拡張機能を無効にし、「追加の項目が必要です」というメッセージを表示するでしょう。あなたは複数の<em:requires>タグを好きなだけ追加することができます。指定された条件が一つでも満たされていなければ、あなたの拡張機能は無効化されます。
例
<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>
註
- 現在は、
<em:requires>タグの中では<em:id>,<em:minVersion>,<em:maxVersion>だけが解釈されます。 - 今の所、
<em:targetApplication>によって依存関係を表現することはできません。詳しい情報については拡張機能の依存関係を参照してください。
このプロパティはFirefox/Thunderbird 2のために追加されました。これらのアプリケーションの以前のバージョンは、制限事項を無視して、指定された条件とは無関係にアドオンをインストールするでしょう。
[編集] 廃止されたプロパティ リファレンス
以下のリファレンスはアドオンマネージャの古いバージョンで必須とされていたプロパティです。最新環境ではこれらのプロパティは一新されさらに良い構成となっています。
[編集] 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).
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.
例
<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.
[編集] 用語集
[編集] アクセスが制限された領域
アクセスが制限された領域とは、アクセスが制限されたアカウントにおいて、現在のユーザの特権（nsIInstallLocation::restricted を参照）によって制限されているかどうかにかかわらずその場所へアクセスできないかもしれないインストール場所のことです。
現在の所、($APPDIR)/extensionsフォルダと、HKEY_LOCAL_MACHINE以下に登録されたインストール場所（詳細はWindowsのレジストリを使って拡張機能を追加するを参照してください）が制限されます。
他方で、($PROFILE)/extensionsとHKEY_CURRENT_USERに登録されたインストール場所については制限されません。
[編集] 追加情報
- install.rdf page on the MozillaZine KB を参照するとさらなる情報や、サンプルを入手することができます