注: 更新マネージャーは現在開発中であり、安定版の完成までには変更が予想されます。 初期段階の採択者からは、現在、インストール構造の詳細が予期しない形で変更される可能性のあることを理解した上で、 フィードバックを受け付けています。 |
概要
手順
パッケージの規則
概念
コンポーネント・アーカイブ
構成アーカイブ
パッケージ情報の変換
セキュリティーに関する考慮事項
NL のパッケージ
ターゲット固有サポートのパッケージ
デリバリー可能なサポートのパッケージ
インストール構造
フルインストールと参照インストール
ファイル・システム・マッピング: フルインストール
ワークスペース・ファイル
ファイル・システム・マッピング: 参照インストール
Eclipse の起動
更新に関する考慮事項
非プラットフォーム・コンポーネントの更新
プラットフォームの更新
JRE の更新
製品ファイルの更新
起動サポートの更新
更新の障害からの回復
誤った更新からの回復
インストールのクリーンアップ
管理外の Eclipse 機能
インストールの注意点
新規インストール
マージ・インストール
プラットフォーム固有の登録
開発に関する考慮事項
インストール・ロケーションの独立性
ネイティブの実行可能ファイル
プラグイン・バージョンの並行サポート
バージョンの移行
プラグインの開発中 (つまり、頻繁に変更が行われている間) は、 内部ファイル構造は、開発者にとっての利便性を反映しています。 これは、通常、使用される特定の開発ツールに依存します。 ただし、開発者は、一般的に、.jar ファイルから実行するのではなく (.jar の作成には余分な手間がかかり、開発者がこれを避けることは明らかなので)、 公開される .class ファイルを含むディレクトリー・ツリーからプラグインを実行するようセットアップすることが多いでしょう。 また、この段階ではプラグインの変更が継続しているため、開発者はプラグインのバージョン情報には特に注意を払いません。
ただし、プラグインのパッケージ作成の準備ができると、パッケージおよびインストールに適した形に変換する必要があります。 これは、通常、ランタイム .jar を作成し、開発時のファイル (ソース、公開 .class ファイルなど) を削除する作業になります。 また、公式のプラグイン・バージョンにより plugin.xml マニフェストを更新して、 そのバージョンをプラグイン名のディレクトリー名に反映させます (『プラグイン・バージョンの並行サポート』を参照)。
プラグイン・フラグメント
プラグイン・フラグメント (または単にフラグメント) により、
基本となるプラグインの特定の性質を個別にパッケージすることができます。
これには、プラグイン用の変換済みリソース、OS 固有またはウィンドウ・システム固有のコード、
または代替ユーザーをターゲットとするプラグイン・コンテンツ (プラグインに提供される SDK 開発者情報など) が含まれます
(これに限定されるわけではありません)。
実行時、フラグメントは基本プラグインに論理的にマージされます。
パッケージの視点からは、これらは基本プラグインに物理的にパッケージするか、
パッケージとサービスを別個に行うことができます。
これにより、たとえば基本機能のディストリビューションから独立した「言語パック」や
特定の「OS パック」を作成することができます。
コンポーネント
コンポーネントは、通常、何らかのユーザー機能のデリバリーを行うプラグイン/プラグイン・フラグメントのグループです。
コンポーネントは、機能選択のユニットを表すことから、
パッケージおよびインストールのプロセスの一部としてユーザーに公開することができます。
また、コンポーネントはインストールのユニットを表します
(含まれるファイルはすべて 1 つのインストール・ツリーにインストールされる)。
コンポーネントは、バージョンの ID を含みます。
コンポーネントは、必要なプラグイン、プラグイン・フラグメント、 およびコンポーネントのインストール・マニフェスト (xml ファイル) を含む Java .jar ファイルとしてパッケージされます。 コンポーネントの .jar ファイルは、Eclipse 更新マネージャーによるダウンロードおよびインストール用に、 サーバー上に配置することや、あるいはいずれかの「従来形式」のインストーラー・テクノロジーにより、 正式なパッケージ・プロセスへの入力として使用することができます。 コンポーネント jar およびそのインストール・マニフェストのフォーマットについては、後述します。
構成
構成は、バージョン化されたコンポーネント・セットをバージョン管理してグループ化するためのメカニズムです。
たとえば、これを使用して、特定の製品バージョンとして作成およびテストされたコンポーネント構成を指定することができます。
構成は、構成のインストール・マニフェスト (xml ファイル) を含む Java .jar ファイルとしてパッケージされます。 マニフェストには、構成のコンポーネントへの参照、およびインストールとバージョン更新に関する制約が含まれます。 構成の .jar ファイルに実際にコンポーネントが含まれることはありません (参照のみ)。
構成の .jar ファイルは、Eclipse 更新マネージャーによるダウンロードおよびインストール用に、 サーバー上に配置することや、あるいはいずれかの「従来形式」のインストーラー・テクノロジーにより、 正式なパッケージ・プロセスへの入力として使用することができます。 構成 jar およびそのインストール・マニフェストのフォーマットについては、後述します。
現在の Eclipse インプリメンテーションでは、構成をネストすることはできません。
名前の形式
<componentId>_<version>
例
org.eclipse.platform_1.0.3.jar
com.ibm.tools.jspeditor_3.1.0\install.xml
コンポーネント jar の内部パス構造
install/
components/
<componentId>_<version>/
install.xml
(other optional files)see "Translating Packaging Information"
plugins/
<pluginId>_<pluginVersion>/
plugin.xml
(other plug-in files)
fragments/
<fragmentId>_<fragmentVersion>/
fragment.xml
(other fragment files, may also include plugin.xml)
.jar ファイルには、1 つの install.xml ファイルを含む install/components/ パスが 1 つ含まれます。 これには、その相対ディレクトリー (バージョン修飾子を持つ) 内に プラグイン / プラグイン・フラグメントが含まれます (ない場合もある)。 また、Java jar ユーティリティーにより作成される meta-inf/ ディレクトリーも含まれます。
コンポーネントの install.xml のフォーマットは、次の dtd により定義されます。
<?xml encoding="US-ASCII"?>
<!ELEMENT component (description?, url?, plugin*, fragment*)>
<!ATTLIST component
label CDATA #IMPLIED
id CDATA #REQUIRED
version CDATA #REQUIRED
provider-name CDATA #IMPLIED
>
<!ELEMENT description (#PCDATA)>
<!ELEMENT url (update*, discovery*)>
<!ELEMENT update EMPTY>
<!ATTLIST update
url CDATA #REQUIRED
label CDATA #IMPLIED
>
<!ELEMENT discovery EMPTY>
<!ATTLIST discovery
url CDATA #REQUIRED
label CDATA #IMPLIED
>
<!ELEMENT plugin EMPTY>
<!ATTLIST plugin
label CDATA #IMPLIED
id CDATA #REQUIRED
version CDATA #REQUIRED
>
<!ELEMENT fragment EMPTY>
<!ATTLIST fragment
label CDATA #IMPLIED
id CDATA #REQUIRED
version CDATA #REQUIRED
>
エレメントおよび属性の定義は次のとおりです。
名前の形式
<configurationId>_<version>
例
org.eclipse.sdk_1.1.5.jar
com.ibm.wsa_1.0.1\install.xml
構成 jar の内部パス構造
install/
configurations/
<configurationId>_<version>/
install.xml
(other optional files)see "Translating Packaging Information"
("product" files)see "Launching Eclipse"
.jar ファイルには、1 つの install.xml ファイルを含む install/configurations/ パスが 1 つ含まれます。 また、Java jar ユーティリティーにより作成される meta-inf/ ディレクトリーも含まれます。
構成の install.xml のフォーマットは、次の dtd により定義されます。
<?xml encoding="US-ASCII"?>
<!ELEMENT configuration (description?, url?, component*)>
<!ATTLIST configuration
label CDATA #IMPLIED
id CDATA #REQUIRED
version CDATA #REQUIRED
provider-name CDATA #IMPLIED
application CDATA #IMPLIED
>
<!ELEMENT description (#PCDATA)>
<!ELEMENT url (update*, discovery*)>
<!ELEMENT update EMPTY>
<!ATTLIST update
url CDATA #REQUIRED
label CDATA #IMPLIED
>
<!ELEMENT discovery EMPTY>
<!ATTLIST discovery
url CDATA #REQUIRED
label CDATA #IMPLIED
>
<!ELEMENT component EMPTY>
<!ATTLIST component
label CDATA #IMPLIED
id CDATA #REQUIRED
version CDATA #REQUIRED
allowUpgrade (true | false) "false"
optional (true | false) "false"
>
エレメントおよび属性の定義は次のとおりです。
label="%cfg Eclipse SDK for Linux"
これにより、キー "cfg" を使用して、適切なプロパティー・ファイル内でリソースが参照されます。 プロパティー・ファイルが提供されない、またはキーが見つからない場合は、 デフォルトのストリング値 (%key) が使用されます。
プロパティー・ファイルの名前は、Java リソース・バンドルの命名規則に従い、install_<locale>.properties となります。 これは、コンポーネントおよび構成 .jar 内で、対応する install.xml ファイルと同じディレクトリーに配置されます。
リソース・バンドルにアクセスする場合、 コードではマニフェストの適切な NL バリアントを選択して (参照アルゴリズムのインプリメントによる)、 次のものを使用してバンドルを作成することができます。
ResourceBundle b;
b = new PropertyResourceBundle(properties.openStream());
あるいは、ベースの Java サポートを使用して、マニフェストの適切な NL バリアントを探します。次のようにします。
ResourceBundle b;
ClassLoader l;
l = new URLClassLoader(new URL[] {<targetDirectoryURL>}, null);
b = ResourceBundle.getBundle("install",Locale.getDefault(),l);
作成されたリソース・バンドルは IPluginDescriptor.getResourceString(String,ResourceBundle) で使用して、 実際に、マニフェスト属性用の適切な変換済みストリングを戻すことができます。
NL ファイルをプラグイン・フラグメントとしてパッケージすることにより、インストール構造がやや複雑化します。 この主な利点は、NL コンテンツを事後にベースに追加することができる点です (同時にシップする必要がない)。 また、フラグメントの開発をベースとは分離して行うことができます (サービス・アップデートに関して)。
NL のパッケージ用の代替インストール構造を次に示します。
プラグインによる「インライン」への NL のパッケージ
install/
plugins/
<pluginId>_<version>/
("plug-in" files)
nl/
<locale>/
(NL files)
以下に例を示します。
install/
plugins/
my.funky.plugin_1.0.1/
plugin.xml
my.jar ... contains classes and default resources
nl/
de_DE/
my.jar ... contains the translated delta
プラグイン・フラグメントとしての NL のパッケージ
install/
fragments/
<fragmentId>_<version>/
fragment.xml
nl/
<locale>/
(NL files)
以下に例を示します。
install/
fragments/
my.funky.plugin_german_1.0.1/
fragment.xml
nl/
de_DE/
my.jar ... contains the translated delta
ロケール・ディレクトリー名は、標準の Java ロケール命名規則に従います。
通常、基本プラグイン・コンテンツには必ずデフォルトの NL リソースが含まれるようにし、 ロケール・ツリーが存在しない場合に、機能が適切に振る舞うようにする必要があります (UI では、リソース ID ではなくデフォルトのストリングを表示する方がよいでしょう)。
ランタイム・メカニズム、fragment.xml フォーマット、および NL ディレクトリーとフラグメントの管理用 API については、 Eclipse プラットフォーム・ドキュメンテーションの別の箇所で説明します。
ターゲット固有のファイルをプラグイン・フラグメントとしてパッケージすることにより、インストール構造がやや複雑化します。 この主な利点は、ターゲット固有のサポートを事後にベースに追加することができる点です (同時にシップする必要がない)。 また、フラグメントの開発をベースとは分離して行うことができます (サービス・アップデートに関して)。
ターゲット固有ファイルのパッケージ用の代替インストール構造を次に示します。
プラグインによる「インライン」へのターゲット固有サポートのパッケージ
install/
plugins/
<pluginId>_<version>/
("plug-in" files)
os/
<os-name>/
(OS-specific files)
ws/
<windowing-system-name>/
(WS-specific files)
以下に例を示します。
install/
plugins/
my.funky.plugin_1.0.1/
plugin.xml
my.jar
os/
solaris/
libfoo.so
ws/
motif/
my.jar
プラグイン・フラグメントとしてのターゲット固有サポートのパッケージ
install/
fragments/
<fragmentId>_<version>/
fragment.xml
os/
<os-name>/
(OS-specific files)
ws/
<windowing-system-name>/
(WS-specific files)
以下に例を示します。
install/
fragments/
my.funky.plugin_solaris_1.0.1/
fragment.xml
os/
solaris/
libfoo.so
ws/
motif/
my.jar
ディレクトリー名に使用されるターゲット ID は、Eclipse により定義されます (org.eclipse.core.boot.BootLoader の Javadoc を参照)。
ランタイム・メカニズム、fragment.xml フォーマット、 およびターゲット固有のディレクトリーとフラグメントの管理用 API については、 Eclipse プラットフォーム・ドキュメンテーションの別の箇所で説明します。
Eclipse のフルインストールのファイル構造は次のとおりです。
<installation root>/
install/
install.properties
components/
<componentId>_<version>/
install.xml
install_<locale>.properties (optional)
configurations/
<configurationId>_<version>/
install.xml
install_<locale>.properties (optional)
(other "product" files) (optional)
plugins/
<pluginId>_<version>/
plugin.xml
(other plug-in files)
fragments/
<fragmentId>_<fragmentVersion>/
fragment.xml
(other fragment files, may also include plugin.xml)
ディレクトリーおよびファイルの定義は、コンポーネントおよび構成の jar で指定したものと同じです。
ファイル install.properties には、構成可能な起動用のプロパティーが含まれます。 これには、現在のプラットフォームおよびインストール済みのアプリケーションの起動セットアップが反映されています。 この使用法については、『Eclipse の起動』で説明します。 このファイルは、最初に新規インストールの一部としてインストールされます。 その後は、Eclipse のインストールが更新されるごとに、更新マネージャーによって更新されます。 オリジナルのインストールと互換性のない方式でファイルが更新された場合、 最後に有効とされた状態が復元されます。
ファイルは Java プロパティー・ファイル形式であり、内容は次のとおりです。
application=<applicationId>
application.configuration=<configurationId>_<version>
runtime=<pluginId>_<version>
次に例を示します。
application=
application.configuration=com.ibm.wsa_1.0.3
runtime=org.eclipse.core.boot_1.1.4
プロパティー定義の内容は次のとおりです。
注: このセクションに記載されたように、 Eclipse ベースの製品の初期インストールでは、 初期の起動設定を正しく反映した install.properties ファイルのインストールも必要です。 これを怠った場合、製品を起動することができません。
<installation root>/
install/
components/
install.index (optional)
<componentId>_<version>/
install.xml
install_<locale>.properties (optional)
<componentId>_<version>.jar
configurations/
install.index (optional)
<configurationId>_<version>/
install.xml
install_<locale>.properties (optional)
<configurationId>_<version>.jar
参照インストールを作成するには、 コンポーネントまたは構成 jar からインストール・マニフェスト (およびインストール・リソース・バンドル) を解凍し、 jar 全体をディレクトリー構造 (install.xml と同じ) にインストールするだけです。 install.xml を公開することにより、更新マネージャーが所定のサイトで使用可能な内容を判別することが可能になります。 選択を行うと、対応する .jar がダウンロードされインストールされます。
直接のファイル入出力以外のプロトコルにより参照インストール・サイトにアクセスする場合、 サイトにはオプションの install.index を含む必要があります (components/ および configurations/ ディレクトリー内)。 このファイルは、ディレクトリーの「目次」となります。 これには、行ごとに実際のサブディレクトリー名が含まれます。
以下に例を示します。
<installation root>/
install/
components/
install.index
org.eclipse.platform_1.0.1/
org.eclipse.jdt_2.9.5/
org.eclipse.pde_1.0.4/
install.index が含むファイルは次のとおりです。
org.eclipse.platform_1.0.1
org.eclipse.jdt_2.9.5
org.eclipse.pde_1.0.4
直接のファイル入出力により「サイト」を参照する場合 (「ファイル」URL として)、install.index ファイルは必要ありません。 ただし、ファイルが存在する場合は、直接のファイル入出力アクセスの場合でもこのファイルが使用されます。 ファイルをこのようにサイト管理に使用して、実際に公開する構成およびコンポーネントをコントロールします。 これは、通常、構成に含まれるコンポーネントを別個にダウンロードしてインストールすることを意図していない (つまり、何らかの構成によってのみ管理を行う) 場合に役立ちます。 この場合、構成は直接公開されますが、コンポーネントは公開されません。 コンポーネントは、公開された構成によってのみ配置されます。
更新マネージャーが、既存のプラグイン・ディレクトリー構造を更新することはありません。 以前に存在していなかったプラグインのバージョンをインストールするだけです。 プラグインのディレクトリーが既に存在する場合 (他のバージョンのコンポーネントに含まれているなど)、 これは再度インストールされません。 更新マネージャーは、既存のディレクトリー内容がコンポーネント jar の内容と一致するかどうかは検査しません。 したがって、プラグインのディレクトリー名には、プラグインのバージョン ID が正しく反映されている必要があります。
たとえば、コンポーネント jar の内容は次のようになります。
install/
components/
com.xyx.etools_1.3.5/
install.xml
splash.bmp
readme.txt
license.txt
notes/
jspedit.txt
debug.txt
更新マネージャーがこの情報を更新して保存するごとに (保存はプラットフォームのシャットダウン時に行われる)、 状態に関する情報が複製され、以前の状態が日時順に保持されます。 更新マネージャーは、いくつかの世代の状態を維持します (以前の状態の数は、オプションとして設定可能)。 以前のバージョンの状態と、対応する構成およびコンポーネントは、 更新マネージャーのクリーンアップ・プロセスの一部として定期的に収集 (削除) されます。
状態のバックレベル・コピーを行うことで、更新を誤った場合に回復するためのメカニズムが提供されます。 この場合「誤った」とは、更新マネージャーが正常にダウンロードと変更の適用を行った場合でも、 変更により問題が生じることを指します。
インストーラーにより、次のことを行う必要があります。
更新マネージャーにより行われた変更を補うため、 「従来形式」のアンインストーラーは、次の Eclipse インストール・ディレクトリーの全ファイルを強制的に除去することができます。
インストーラーにより、次のことを行う必要があります。
アンインストール・プロセスにおいて上記のコントロール (インストール・ファイルの除去を抑止) がなされていない インストーラーを使用する場合には、注意してください。 Linux の RPM はその一例です。 このような場合、マージ・インストールについては特定のインストーラーを使用することは避けてください。 アンインストールを行った結果、実行が不可能になります。
「従来形式」のアンインストーラーにより、マージ・インストールの「ルート」ファイルを使用して、 インストールされた機能を安全に除去することができます。 これは、マージ・インストールの一部としてオプションでインストールされたファイルであり、 対応する構成およびコンポーネントへのアンカーとしての役割をします。 Eclipse プラットフォームは、起動時に「ルート」ファイルの除去を検出して、 リストされた構成およびコンポーネントを安全に除去します。
注: 構成やコンポーネントのファイルとは異なり、「ルート」ファイルは更新マネージャーにより変更されません。 したがって、「従来形式」のアンインストーラーは、これらファイルによりインストール後の位置を特定することができます。
「ルート」ファイルはインストール後、Eclipse インストール・ツリー内の install/info/ ディレクトリーに配置されます (install/configurations および install/components ディレクトリーと同じ)。 ファイルの命名規則は次のとおりです。
<merged-installation-identifier>.install
Eclipse プラットフォームは、ID のフォーマットを指定しません (解釈を行わない)。 名前が競合する可能性を最小限にするよう、 この ID は、プロバイダーのインターネット・ドメイン・ネーム (例、com.xyz.toolpack.install) に基づく 命名規則を使用することをお勧めします。
「ルート」ファイルのコンテンツは、Java プロパティー・ファイルのフォーマットを使用し、次のようになります。
configurations=[<configId>_<version> [, <configId>_<version>]*
]
components=[<compId>_<version> [,<compId>_<version>]*
]
ここで
[] はオプションのエレメント
* はグループを繰り返す
(つまり、両方のプロパティーは、対応するバージョンの接尾部を持つ ID をコンマで区切ったリスト)
Eclipse ベースの製品では、インストールされている Eclipse プラットフォームのすべての位置を追跡するために、 OS の登録メカニズムを使用するよう提唱されています。 これにより、新規プラットフォームのインストールを作成するか、 既存のインストールにコンポーネントをマージするかを決定する際に、 単純な参照を行うだけで済みます。 このような登録メカニズムのないプラットフォームでは、 ユーザーが Eclipse のインストール・ディレクトリーを明示的に示すよう指示されます。
通常、インストーラーが新規インストールの作成、または既存のインストールへのコンポーネントのマージを行います。 新規のインストールを作成することにより、登録構造も更新されます。
Windows では、Windows レジストリーを使用して登録が行われます。 Eclipse プラットフォームのインストール・ディレクトリーの識別に使用するレジストリー・キー構造を次に示します。
eclipse.org/
platforms/
<product name>
<product name> キーは、 新規の Eclipse プラットフォーム・インストールを作成したプロバイダーまたは主要アプリケーション (あるいはその両方) を識別します。 全キーは、次の属性にマップされます。
label = displayable label for the <product name>
key. Localized at time of creation.
directory = <absolute path>
OS 固有のネイティブ・コンポーネント (ActiveX など) は、Eclipse 更新マネージャーによる処理が行われない カスタム・インストールが必要です。 カスタム・インストーラーは、適切な OS サービスを使用してコンポーネントを登録し、 標準の検索パスを更新します。 Eclipse プラットフォームでは、必須のネイティブ・コンポーネントの自動チェックは行われません。 プラグイン・コードは、必要なチェック / 回復ロジックをインプリメントする必要があります。 カスタム・インストーラーの一部として「マーカー」プラグインを作成し、 ネイティブ・コンポーネントの存在を示し、他のプラグインにより依存関係を指定することができます。 ただし、この方法は絶対確実のものではなく、ネイティブの依存関係が絶対に保証されるものでもありません。
また、Eclipse プラットフォームでは、同じプラグインの複数のバージョンを同時に構成し実行することができます。 これは特に、共用ランタイム・ライブラリーを含むプラグインの場合に行われます。 共用ランタイムのあるユーザーが、特定バージョンのプラグインに依存関係を指定する場合があります。 このようなプラグインは、そのランタイム・ライブラリーを宣言するだけでよく (plugin.xml の <runtime> セクション)、 プラットフォームに対する contribution を宣言してはいけません (特に拡張ポイントの宣言または拡張機能の contribution (あるいはその両方))。
これをサポートするため、Eclipse プラットフォームでは、 プラグインの識別スキーム、ファイル・システム内のプラグイン・ディレクトリーの命名規則、 およびプラットフォーム起動時に検出されたプラグインの構成と実行の規則が定義されています。
プラグインは、Java パッケージ名に似た構造化ストリング、および複数桁のバージョン ID の組み合わせにより識別されます。 バージョン ID は、非互換の世代を示すメジャー・コンポーネントと、 プラグイン互換を示すマイナー・コンポーネントから構成されます。
プラグイン | バージョン | 推奨されるディレクトリー名 |
org.eclipse.ui | 1.3.17 | org.eclipse.ui_1.3.17 |
edu.xyz.tools | 1.0.1 | edu.xyz.tools_1.0.1 |
プラットフォームには、バージョン ID を扱うための API が提供されています。
プラットフォームに提供される基本機能をプラグインで使用することにより、 移行状況をそれぞれ取り扱うことができますが、これらを正しく使用することはプラグイン開発者の責任です。
プラグインは実行時、プラグイン固有の情報を複数の作業ロケーションに書き込むことができます。 作業ロケーションへの参照は、次の API 呼び出しにより取得されます。
後方移行は、プラグイン開発者の側で追加の作業が必要となります。 基本的に、バージョン n+1 のプラグインは、バージョン n がこの状況を検出できるような形でデータを書き込む必要があります。 プラグインがこの状況に対応できるようにするには、いくつかの方法があります。