前次修改日期:15:20 Friday June 18, 2004
以 Eclipse 為基礎的產品必需正確的安裝到一般使用者的電腦上。 特殊目的之套裝工具,如 InstallShield 和 RPM,經常用來建置自動安裝、更新和解除安裝的可執行安裝程式。 這個附註說明了如何撰寫以 Eclipse 為基礎的產品的安裝程式,和可分別安裝至以 Eclipse 為基礎的產品上的延伸。
我們假設產品開發團隊負責提供程式資料組成物,必須找到在一般使用者電腦上包裝為 可執行套件的安裝程式。執行檔安裝程式的建立是有底稿的,為安裝時間動作所需的與一般使用者交談,並儲存檔案至他們的電腦。這個附註詳細說明了這些安裝程式需要做些什麼以及如何做。
負責為以Eclipse 為基礎的產品撰寫安裝程式的人,可以將此附註視為秘訣。 我們建議所有安裝程式撰寫者遵循我們的秘訣,有兩個原因:
產品安裝程式應是自行包含的 - 可在 CD 中分送的方式,並安裝在有適當作業系統的機器上。
Eclipse 要求 Java2 Java Runtime Environment (JRE) 來執行 Java 程式碼。JRE 是授權的軟體,由 Java 供應商處取得。 在有從 JRE 供應商取得重新分送 JRE 的授權時,公司可以併入 JRE 到它的產品中,並在安裝產品時同時安裝至一般使用者的電腦上。 替代方案是要求一般使用者在電腦中預先安裝 JRE,與產品安裝時間相關聯。 不論使用那一個方式,以 Eclipse 為基礎的產品要求合適的 JRE,而產品安裝程式 必須扮演安裝 JRE 或尋找鏈結至先前已安裝的 JRE 角色。
假設 JRE 與產品一起安裝。包含 JRE 的目錄是安裝程式建立 Script 的一項輸入。
表示這個目錄為 <JRE>。這個目錄必須有標準 JRE 目錄結構, Java 執行檔位在 jre/bin/java.exe
目錄下,而類別庫位於
<JRE> 目錄的 jre/lib/rt.jar
路徑中。
供參考,這個目錄的結構看起來像:
<JRE>/
jre/
bin/
java.exe
lib/
rt.jar
這些目錄中有其他的檔案(和子目錄);我們只顯示範例來給予一般結構。 名稱使用斜體字為特定的產品。
安裝程式建立 Script 的第二個輸入為目錄,<product head
>,包含產品特定可執行啟動程式和任何與 Eclipse 不相關的檔案。
供參考,這個目錄的結構看起來像(斜體表示檔案名稱根據產品不同而改變):
<product head>/
安裝程式建立 Script 的第三個輸入為目錄,<
acmeproduct.exe
product body
>,包含產品所開發的特性和外掛程式。
供參考,這個目錄的結構看起來像:
<product body>/
eclipse/
features/
com.example.acme.acmefeature_1.0.0/
feature.xml
com.example.acme.otherfeature_1.0.0/
feature.xml
plugins/
com.example.acme.acmefeature_1.0.0/
plugin.xml
about.ini
about.properties
about.mappings
plugin_customization.ini
splash.bmp
com.example.acme.otherfeature_1.0.0/
plugin.xml
about.ini
about.properties
about.mappings
com.example.acme.myplugin_1.0.0/
plugin.xml
myplugin.jar
com.example.acme.otherplugin_1.0.0/
plugin.xml
otherplugin.jar
安裝程式建立 Script 的第四個輸入為目錄,<platform
>,包含 Eclipse 平台本身的特性和外掛程式,而且併入協力廠商工具。
這個目錄也併入標準 Eclipse 可執行啟動程式,eclipse.exe
,(
在 UNIX 作業環境上稱為 eclipse
),它的夥伴 startup.jar
,以及其他 Eclipse 平台檔案必須安裝在根目錄中。
供參考,這個目錄的結構看起來像:
<platform>
<
eclipse/
eclipse.exe
startup.jar
features/
org.eclipse.platform_2.0.0/
org.eclipse.platform.win32_2.0.0/
org.eclipse.jdt_2.0.0/
org.eclipse.pde_2.0.0/
plugins/
org.eclipse.platform_2.0.0/
org.eclipse.core.runtime_2.0.0/
org.eclipse.core.boot_2.0.0/
org.eclipse.core.resources_2.0.0/
org.eclipse.ui_2.0.0/
org.eclipse.jdt_2.0.0/
org.eclipse.jdt.core_2.0.0/
org.eclipse.jdt.ui_2.0.0/
org.eclipse.pde_2.0.0/
org.eclipse.pde.core_2.0.0/
org.eclipse.pde.ui_2.0.0/
(more org.eclipse.* plug-in directories)
JRE
>,<product head
>,<product body
>,和 <platform
> 的輸入目錄的確切內容判斷安裝哪些檔案到一般使用者的電腦上。
安裝程式建立 Script 的最終輸入為產品主要特性 ID 和版本字串;例如,"com.example.acme.acmefeature"
和 "1.0.0
";以及產品執行檔的名稱;例如,"acmeproduct
.exe
"。
對不需要產品本身執行檔的產品來說,這將是標準 Eclipse 執行檔啟動程式
"eclipse/eclipse.exe
" 的路徑。
這些字串對安裝程式來說有特殊有效位數,出現在欄位和目錄名稱,以及安裝時所建立的標記檔案內容。
在安裝時,安裝程式行為應該為標準方式(下列步驟為更詳細的資料):
如果步驟 5 所指定的位置是 <install
>,安裝程式複製 <JRE
>、<platform>、
<product
>、
和 <product plug-ins>
目錄中的所有檔案至 <install
> 目錄中。
輸入檔案 | 安裝檔案 |
<JRE>/* |
<install>/eclipse/* |
<product head>/* |
<install>/* |
<product body>/* |
<install>/* |
<platform>/* |
<install>/* |
步驟 8 中所建立的標記檔案為 <install>/eclipse/.eclipseproduct
,
用來標記安裝以 Eclipse 為基礎的產品所在的目錄,主要是供延伸安裝程式尋找目錄。
標記檔案是 java.io.Properties
格式的檔案(ISO 8859-1 字元編碼和使用 "\" 跳出),並包含下列資訊,供使用者識別產品以及區分
以 Eclipse 為基礎的產品:
name=Acme Visual Tools Pro
id=com.example.acme.acmefeature
version=1.0.0
"id" 和 "version" 內容的值為安裝程式建立 script; 的輸入,大概知道產品的名稱和實接線。(產品不是原來就存取這個標記檔案;只有產品和延伸安裝程式寫入或讀取它。)
步驟 6 要求檢查現有的 <install>/eclipse/.eclipseproduct
或 <install>/eclipse/.eclipseextension
檔案。產品無法安裝在已安裝
其他產品或延伸的相同地方。
安裝所有檔案之後,安裝目錄最上層結構包含下列檔案和子目錄(或許還有其他):
<install>/
如果產品安裝程式要求使用者授權資訊,如已登錄的擁有者名稱和授權碼,這個資訊應該併入至產品「關於」對話框中(步驟 10)。
acmeproduct.exe
eclipse/
.eclipseproduct
eclipse.exe
startup.jar
features/
plugins/
jre/
這可以利用主要特性外掛程式中的 "about.mapping
" 檔案紀錄使用者回應來完成。
例如,<install>/plugins/com.example.acme.acmefeature_1.0.0/about.mapping
。
"about.mapping
" 檔案可能預先存在於 <product head
>
輸入中,或需要利用安裝程式在安裝時建立。
這些鍵都是號碼;"n" 鍵的值被 "aboutText
" 內容中的 "{n}
" 所替代。
比方說,如果授權碼是欄位號碼為 0,應該建立包含像 "0=T42-24T-ME4U-U4ME
" 行
的 "about.mapping
" 檔案。
N.B.
"about.mapping
" 檔案是 java.io.Properties
格式的檔案(ISO 8859-1 字元編碼,使用 "\" 跳出)。
安裝時當原生的字元編碼與 ISO 8859-1 不同時,安裝程式負責轉換原生的字元編碼為 Unicode,並且在需要的地方新增 "\" 跳出字元。
當字串包含特殊字元(如 "\")或非拉丁字元時,跳出字元是必要的。
例如,欄位號碼 1 包含希臘英文字母的前三個字母,應為 "1=\u03B1\u03B2\u03B3
"。
在步驟 12,產品安裝程式啟動產品執行檔, <install>/acmeproduct.exe
,使用特殊 -initialize 選項 [詳細資料 TBD]。
這個造成了 Eclipse 平台安靜的執行所有費時的第一次處理程序和快取結果,所以當
使用者啟動產品時,提示為 open-for-business 狀態。
解除安裝時,解除安裝程式行為的標準方式:
install
> 目錄移除全部已安裝檔案, <install
>/eclipse/features
和
<install
>/eclipse/plugins
目錄中的所有檔案,包括其他安裝程式(例如,Eclipse 更新管理程式)所放置的檔案。已解除安裝產品後,安裝時所儲存的檔案應被刪除,以及 Eclipse 更新管理程式所建立的
更新特性和外掛程式也應刪除。
重要事項:在解除安裝期間,可能有其他目錄和檔案在 <install>
目錄中,特別注意 <install>/eclipse/workspace/
,<install>/eclipse/links/
,和 <install>/eclipse/configuration/
,解除安裝後這些目錄都含有必須保留的重要資料。使用者必須能夠解除安裝和重新安裝產品到
同一個位置,而且沒有遺失重要資料。
當產品已安裝在使用者的電腦上時,安裝程式應容許套用服務程式更新或版本的升級至已安裝的產品上。
在安裝期間,安裝程式行為應該為標準方式:
在步驟 2 中,已安裝的產品可依 "eclipse
" 目錄
是否包含 ".eclipseproduct
" 檔案來立即辨識。
"eclipse
" 目錄的母項是產品的安裝目錄;
例如,<install>/eclipse/.eclipseproduct
。
包含在此標記檔案中的資訊應該顯示給使用者,以確認正確的產品己經更新(在使用者的電腦中可能有一些以 Eclipse 為基礎的產品)。
安裝程式應該在步驟 3,藉著簡易的型樣與 <install>/eclipse/features
目錄中的型樣是否相符來執行相容性檢查。
比方說,如果有與 "com.example.acme.otherfeature_1.0.1
" 相符的資料夾出現,就可確定某些更新的服務程式已套用至已安裝的產品中。
步驟 7,安裝程式可能刪除或取代原來安裝的檔案,並新增更多檔案。
重要事項:一些檔案和目錄,包括 <install>/eclipse/workspace/
,<install>/eclipse/configuration
,可能同時位在
安裝目錄中,並且包含一些產品升級時需要保留的重要資料檔案。
在升級狀況中,有一個好的機會就是 <install>/eclipse/plugins/
下
大部分檔案都是相同的(類似 <install>/eclipse/features/
)。
有一個重要的機會在 <install>/eclipse/plugins/
進行最佳化,因為
內含外掛程式(或片段)版本號碼的子目錄名稱,只在下列任何檔案有所變更時才會變更。
換句話說,如果這個子目錄在升級後依然存在則不需要碰觸 <install>/eclipse/plugins/org.eclipse.ui_2.0.0
/
中的任何檔案,如果有任何外掛程式要變更,就會修訂外掛程式的版本號碼,造成已升級的外掛程式檔案安裝在並行的目錄 <install>/eclipse/plugins/org.eclipse.ui_2.0.1
/ 中。
預期 JRE 位在 <install>/eclipse/jre/bin/javaw.exe
。
如果位在其他位置,絕對路徑應該在指令行使用 -vm
選項來指定;
例如, -vm C:\j2jre1.3.0\jre\bin\javaw.exe
。
在此情形中,安裝程式新增這個選項至它所建立的桌面捷徑的指令行。
所謂延伸是指一組獨立安裝的特性集及其外掛程式,它可與安裝在同部電腦中一或多個以 Eclipse 為基礎的產品搭配使用。 與產品相反的是,延伸不是自行包含的;延伸不包括產品執行檔 Eclipse 平台 JRE。
沒有流失一般性,假設延伸由單一特性所組成。
安裝程式建立 Script 的第一個輸入為目錄,<extension
>,包含特性和外掛程式。我們假設延伸沒有與 Eclipse 相關的檔案;如果有,它們會在 <extension>/
中,而不是 <extension>/eclipse/
中。 供參考,這個目錄的結構看起來像:
<extension>/
eclipse/
features/
com.example.wiley.anvilfeature_1.0.0/
feature.xml
plugins/
com.example.wiley.anvilfeature_1.0.0/
plugin.xml
about.ini
about.properties
about.mappings
com.example.wiley.mainplugin_1.0.0/
com.example.wiley.otherplugin_1.0.0/
<extension
> 輸入目錄的確切內容判斷安裝哪些檔案到一般使用者的電腦上。
安裝程式建立 Script 的最終輸入為產品主要特性 ID 和版本字串;例如,"com.example.wiley.anvil
"
和 "1.0.0
"。 這些字串對安裝程式來說有特殊有效位數,出現在欄位和目錄名稱,以及安裝時所建立的標記檔案內容。
延伸安裝程式與產品安裝程式絕大部分相似。 不同的範圍強調顯示如下:
在安裝期間,安裝程式行為應該為標準方式:
如果步驟 5 所指定的位置是 <install
>,安裝程式複製 <extension>
目錄中的所有檔案
至步驟 11 中的 <install
> 目錄下。
輸入檔案 | 安裝檔案 |
<extension>/* |
<install>/* |
步驟 7,任何 Eclipse 產品都可能是候選的產品。以 Eclipse 為基礎的產品可利用
<product install>/eclipse/.eclipseproduct
檔案的存在來辨識;
使用者應該能夠要求在限制的磁碟中搜尋已安裝的產品(「搜尋已安裝的產品」按鈕),或者導覽含有產品的目錄(例如,「瀏覽」按鈕)。
安裝程式應該在步驟 8,藉著簡易的型樣與 <product install>/eclipse/features
目錄中的子目錄是否相符來執行相容性檢查。例如,資料夾與 "org.eclipse.jdt_2.*
" 相符的出現,表示 JDT 已併入在已安裝的產品中。
步驟 10 中所建立的標記檔案為 <install>/
.eclipseproduct
,用來標記安裝以 Eclipse 為基礎的延伸所在的目錄,主要供延伸安裝程式尋找
(與產品的 .eclipseproduct
標記檔案類似)。
標記檔案是 java.io.Properties
格式的檔案(ISO 8859-1 字元編碼和使用 "\" 跳出),並包含下列資訊,供使用者識別延伸以及區分
以 Eclipse 為基礎延伸:
name=Wiley Anvil Enterprise Edition
id=com.example.wiley.anvilfeature
version=1.0.0
"id" 和 "version" 值的內容為安裝程式建立 script 的輸入;大概知道延伸的名稱和實接線。(產品不是原來就存取這個標記檔案;只有產品和延伸安裝程式寫入或讀取它。)
安裝所有檔案之後,安裝目錄最上層結構包含下列檔案和子目錄:
<install>/
eclipse/
.eclipseextension
features/
plugins/
與產品安裝程式唯一的重要差異是,延伸安裝程式也在其他已安裝在使用者電腦中以 Eclipse 為基礎的產品上建立鏈結檔案。(這使得使用者不需要使用 Eclipse 更新管理程式 以手動方式建立新建延伸與每一個產品之間的關聯性。)
步驟 14 所建立的鏈結檔案是 <product install>/eclipse/links/com.example.wiley.anvilfeature.link
;
也就是,檔案與延伸特性目錄為相同的名稱,較少的版本號碼字尾。
鏈結檔案是 java.io.Properties
格式的檔案(ISO 8859-1 字元編碼,使用 "\" 跳出)。
鍵為 "path" 而值是已安裝的延伸的絕對路徑,<install>
;
例如,項目可能看起來像 "path=C:\\Program Files\\Wiley\\Anvil
"。
安裝程式負責轉換原生的字元編碼為 Unicode,並且在需要的地方新增 "\" 跳出字元。
跳出通常是必要的,因為 <install>
一般含有
特殊字元(如 "\"),而且可能在目錄中已非非拉丁字元作為名稱。
啟動時,產品讀取鏈結檔案。安裝程式保存所建立的鏈結檔記錄,所以可以在更新延伸
或解除安裝時找到這些記錄。
解除安裝期間,解除安裝程式行為的標準方式:
install
> 目錄移除全部已安裝檔案, <install
>/eclipse/features
和
<install
>/eclipse/plugins
目錄中的所有檔案,包括其他安裝程式(例如,Eclipse 更新管理程式)所放置的檔案。解除安裝延伸時,應刪除所有外掛程式和特性檔;在這些子目錄中沒有需要保存的重要資料。 這讓使用者完全的解除安裝延伸,包括 Eclipse 更新管理程式所套用的更新。
當延伸已安裝在使用者的電腦上時,安裝程式應容許服務程式更新或版本的升級套用至已安裝的延伸上。
在安裝期間,安裝程式行為應該為標準方式:
在步驟 2 中,已安裝的延伸可依 "eclipse
" 目錄
是否包含 ".eclipseextension
" 檔案來立即辨識。
"eclipse
" 目錄的母項是延伸的安裝目錄;
例如,<install>/eclipse/.eclipseextension
。
包含在標記檔案中的資訊應該顯示給使用者,以確認正確的延伸已經更新(可能有一些以 Eclipse 為基礎延伸在使用者的電腦中)。
步驟 7,安裝程式應該不會刪除或改寫程式安裝的任何檔案;而是只新增特性和外掛程式
新版本的檔案,而且可能重新撰寫標記檔案 <install>/eclipse/.eclipseextension
以保留舊版本,給與使用者可回到舊版本的選項而言。其升級產品安裝時,如果這個子目錄在升級後依然存在則不需要碰觸 <install>/eclipse/plugins/com.example.wiley.otherplugin_1.0.0
/
中的任何檔案,如果變更了外掛程式的任何檔案,修訂外掛程式的版本號碼,
則會造成已升級的外掛程式檔案會安裝在 <install>/eclipse/plugins/com.example.wiley.otherplugin_1.0.1
/ 並行的目錄中。