Ostatnia modyfikacja: 18 czerwca 2004 godzina 15:20
Produkty oparte na platformie Eclipse wymagają poprawnej instalacji na komputerze użytkownika końcowego. Dlatego często stosuje się wyspecjalizowane narzędzia (takie jak InstallShield i RPM), które pozwalają tworzyć wykonywalne instalatory automatyzujące procedurę instalacji, aktualizacji i deinstalacji. W tym dokumencie opisano, jak samodzielnie utworzyć instalator produktu opartego na platformie Eclipse lub oddzielnie instalowanych rozszerzeń takiego produktu.
Założono, że zespół programistyczny produktu jest odpowiedzialny za dostarczenie składników, które po uwzględnieniu w wykonywalnym instalatorze będą musiały znaleźć się na komputerze użytkownika końcowego. Proces tworzenia wykonywalnych instalatorów jest oparty na skrypcie. Podobnie jest z akcjami wykonywanymi podczas instalacji, które umożliwiają komunikowanie się z użytkownikiem i umieszczanie plików na jego komputerze. W tym dokumencie szczegółowo opisano, jakie akcje powinny być wykonywane przez instalator i jak powinien on działać.
Niniejszy dokument należy traktować jak szczegółową instrukcję przeznaczoną dla osoby odpowiedzialnej za tworzenie instalatora produktu opartego na platformie Eclipse. Zalecane jest, aby twórcy instalatorów postępowali według podanej instrukcji, z dwóch głównych powodów:
Instalator produktu powinien stanowić autonomiczną całość. Musi być możliwe jego rozpowszechnianie na dyskach CD i instalowanie na dowolnym komputerze z odpowiednim systemem operacyjnym.
Platforma Eclipse wymaga obecności środowiska wykonawczego Java2 (Java2 Java Runtime Environment - JRE), aby możliwe było wykonywanie kodu Java. Środowiska JRE to licencjonowane oprogramowanie oferowane przez różnych dostawców. Po zaopatrzeniu się w licencję, która zezwala na dystrybucję środowiska JRE wybranego dostawcy, firma może włączyć to środowisko do własnego produktu i umożliwić jego zainstalowanie na komputerze użytkownika końcowego razem z własnym produktem. Alternatywne podejście polega na sformułowaniu wymogu, aby środowisko JRE było już wcześniej zainstalowane na komputerze użytkownika końcowego, i powiązanie tego środowiska z produktem podczas jego instalacji. Bez względu na wybrany sposób postępowania, produkt oparty na platformie Eclipse wymaga odpowiedniego środowiska JRE, a instalator produktu musi zainstalować to środowisko lub znaleźć wcześniej zainstalowane środowisko JRE i powiązać je z produktem.
Można założyć, że środowisko JRE ma być instalowane razem z produktem. Katalog zawierający środowisko JRE będzie jednym z parametrów wejściowych skryptu tworzenia instalatora. Katalog ten zostanie oznaczony jako <JRE>. Dany katalog musi mieć standardową strukturę katalogów środowiska JRE, w której plik wykonywalny Java znajduje się w podkatalogu jre/bin/java.exe
, a biblioteka klas - w podkatalogu jre/lib/rt.jar
(poniżej katalogu <JRE>).
Struktura tego katalogu powinna wyglądać następująco:
<JRE>/
jre/
bin/
java.exe
lib/
rt.jar
W tych katalogach znajdują się także inne pliki i podkatalogi. Tutaj przedstawiono tylko przykład przedstawiający strukturę ogólną. Nazwy wyróżnione kursywą są specyficzne dla produktu.
Drugim parametrem wejściowym skryptu tworzenia instalatora jest katalog <product
head
> zawierający wykonywalny program uruchamiający (specyficzny dla produktu) i wszystkie pliki niezwiązane z platformą Eclipse. Struktura tego katalogu będzie wyglądać następująco (nazwy plików wyróżnione kursywą są specyficzne dla produktu):
<product head>/
Trzecim parametrem wejściowym skryptu tworzenia instalatora jest katalog <
acmeproduct.exe
treść
produktu
> zawierający składniki i moduły dodatkowe składające się na dany produkt. Struktura tego katalogu będzie wyglądać następująco:
<treść produktu>/
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
Czwartym parametrem wejściowym skryptu tworzenia instalatora jest katalog <platform
> zawierający składniki i moduły dodatkowe na potrzeby platformy Eclipse, a także włączone do niej narzędzia innych firm.
W tym katalogu znajduje się także standardowy wykonywalny program uruchamiający platformy Eclipse eclipse.exe
(w systemie operacyjnym Unix ma on nazwę eclipse
), jego plik towarzyszący startup.jar
oraz inne pliki platformy Eclipse wymagane w katalogu głównym instalacji. Struktura tego katalogu będzie wyglądać następująco:
<platform>
Wartości parametrów wejściowych <
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/
(inne katalogi modułów dodatkowych org.eclipse.*)
JRE
>, <product head
>, <product body
> i <platform
> decydują o tym, jakie pliki zostaną ostatecznie zainstalowane na komputerze użytkownika końcowego.
Ostatnie parametry wejściowe skryptu tworzenia instalatora to identyfikator i numer wersji składnika podstawowego produktu (np. "com.example.acme.acmefeature"
i "1.0.0
") oraz nazwa pliku wykonywalnego produktu (np. "acmeproduct
.exe
").
W przypadku produktów nie wymagających własnego pliku wykonywalnego będzie to ścieżka do standardowego wykonywalnego programu uruchamiającego Eclipse ("eclipse/eclipse.exe
").
Te parametry mają dla instalatora szczególne znaczenie, ponieważ występują później w nazwach plików i katalogów, a także w treści plików znaczników tworzonych podczas instalacji.
Podczas instalacji instalator powinien działać w standardowy sposób (dalsze informacje podano po procedurze):
Jeśli miejsce określone w kroku 5 to katalog <install
>,
instalator kopiuje wszystkie pliki z katalogów <JRE
>, <platform>,
<product
>, i <product plug-ins>
do katalogu <install
>.
Plik wejściowy | Plik instalowany |
<JRE>/* |
<install>/eclipse/* |
<product head>/* |
<install>/* |
<product body>/* |
<install>/* |
<platforma>/* |
<install>/* |
Plik znacznika utworzony w kroku 8 (<install>/eclipse/.eclipseproduct
) jest używany do oznaczania katalogu, w którym zainstalowano produkt oparty na platformie Eclipse. Pozwala to instalatorom rozszerzeń znaleźć ten katalog. Plik znacznika jest plikiem w formacie java.io.Properties (kodowanie znaków ISO 8859-1, znak zmiany znaczenia: "\"). Zawiera on poniższe informacje pozwalające zidentyfikować produkt i odróżnić go od innych produktów opartych na platformie Eclipse:
name=Acme Visual Tools Pro
id=com.example.acme.acmefeature
version=1.0.0
Wartościami właściwości "id" (identyfikator) i "version" (wersja) są parametry wejściowe skryptu tworzenia instalatora. Nazwa produktu jest prawdopodobnie znana i zapisana na stałe. Produkt jako taki zazwyczaj nie odwołuje się do pliku znacznika - jest on odczytywany i zapisywany wyłącznie przez instalatory produktów i rozszerzeń.
Krok 6 wymaga sprawdzenia, czy istnieje już plik <install>/eclipse/.eclipseproduct
lub <install>/eclipse/.eclipseextension
. Nie jest możliwa instalacja produktu w miejscu, w którym już jest zainstalowany inny produkt lub rozszerzenie.
Po zainstalowaniu wszystkich plików struktura najwyższego poziomu w katalogu instalacyjnym zawierać będzie (między innymi) następujące pliki i podkatalogi:
<install>/
Jeśli instalator produktu wymaga od użytkownika podania informacji licencyjnych (np. nazwiska zarejestrowanego właściciela i klucza licencyjnego), informacje te powinny znaleźć się w oknie dialogowym "Informacje o" (krok 10).
acmeproduct.exe
eclipse/
.eclipseproduct
eclipse.exe
startup.jar
features/
plugins/
jre/
W tym celu odpowiedzi użytkownika są rejestrowane w pliku "about.mapping
" w module dodatkowym składnika podstawowego (np. w pliku <install>/plugins/com.example.acme.acmefeature_1.0.0/about.mapping
).
Plik "about.mapping
" może już wcześniej istnieć w katalogu <product head
>. Jeśli nie istnieje, musi on zostać utworzony przez instalator podczas instalacji.
Klucze są liczbami. Wartość klucza "n" jest podstawiana w miejsce podłańcucha "{n}
" w ustawieniu właściwości "aboutText
".
Jeśli na przykład klucz licencyjny znajdował się w polu o numerze 0, należy utworzyć plik "about.mapping
" zawierający wiersz "0=T42-24T-ME4U-U4ME
".
Plik "about.mapping
" jest plikiem w formacie java.io.Properties
(kodowanie znaków ISO 8859-1, znak zmiany znaczenia: \).
Jeśli kodowanie znaków w środowisku, w którym produkt jest instalowany, różni się od standardu ISO 8859-1, instalator jest odpowiedzialny za przekształcenie kodowania znaków w format Unicode i za dodanie znaku zmiany znaczenia "\" w miejscach, w których jest to wymagane. Znak zmiany znaczenia jest konieczny, gdy łańcuch zawiera znaki specjalne (np. "\") oraz znaki spoza alfabetu łacińskiego. Na przykład w polu o numerze 1, zawierającym pierwsze 3 znaki alfabetu greckiego, zostanie zapisany łańcuch "1=\u03B1\u03B2\u03B3
".
W kroku 12 instalator produktu uruchamia plik wykonywalny produktu (<install>/acmeproduct.exe
) z użyciem specjalnej opcji -initialize. Powoduje to, że platforma Eclipse automatycznie wykona wszystkie czasochłonne operacje wymagane przy pierwszym uruchomieniu programu i zapisze ich wyniki w pamięci podręcznej. Dzięki temu, gdy użytkownik ponownie uruchomi produkt, zostanie on szybko uruchomiony i będzie gotowy do działania.
Podczas deinstalacji deinstalator powinien działać w standardowy sposób:
install
> oraz wszystkich plików z katalogów <install
>/eclipse/features
i <install
>/eclipse/plugins
, w tym plików umieszczonych tam przez programy inne niż dany instalator (np. przez menedżera aktualizacji platformy Eclipse).Zdeinstalowanie produktu powinno spowodować usunięcie plików zapisanych podczas jego instalacji, łącznie ze zaktualizowanymi składnikami i modułami dodatkowymi, które utworzył menedżer aktualizacji platformy Eclipse. Ważne: W momencie deinstalacji katalog <install>
może zawierać także inne katalogi i pliki (np. <install>/eclipse/workspace/
, <install>/eclipse/links/
i <install>/eclipse/configuration/
) z ważnymi danymi, które powinny być zachowane po deinstalacji produktu. Użytkownik musi mieć możliwość instalowania i deinstalowania produktu w tym samym miejscu bez utraty ważnych danych.
Jeśli produkt jest już zainstalowany na komputerze użytkownika, instalator powinien umożliwić jego uzupełnienie o poprawki serwisowe lub zaktualizowanie do nowszej wersji.
Podczas instalacji instalator powinien działać w standardowy sposób:
W kroku 2 zainstalowany produkt można rozpoznać dzięki obecności katalogu "eclipse
", w którym znajduje się plik o nazwie ".eclipseproduct
".
Katalog nadrzędny katalogu "eclipse
" jest katalogiem instalacyjnym produktu (tj. <install>/eclipse/.eclipseproduct
).
Informacje zawarte w tym pliku znacznika powinny zostać wyświetlone użytkownikowi w celu potwierdzenia, że aktualizowany jest właściwy produkt (na komputerze użytkownika może znajdować się więcej niż jeden produkt oparty na platformie Eclipse).
W kroku 3 instalator powinien przeprowadzić test zgodności polegający po prostu na porównaniu wzorca i nazw podkatalogów z katalogu <install>/eclipse/features
. Na przykład obecność folderu pasującego do wzorca "com.example.acme.otherfeature_1.0.1
" świadczyłaby o tym, że pewne poprawki serwisowe produktu już zostały zainstalowane.
W kroku 7 instalator może usunąć lub zastąpić wszystkie pierwotnie zainstalowane pliki, a także dodać nowe pliki. Ważne: Niektóre pliki i katalogi (w tym katalogi <install>/eclipse/workspace/
i <install>/eclipse/configuration
) znajdujące się w katalogu instalacyjnym mogą zawierać ważne dane, które powinny zostać zachowane przy aktualizacji produktu.
W przypadku aktualizacji jest bardzo prawdopodobne, że większość plików w katalogu <install>/eclipse/plugins/
nie uległa zmianie (podobnie jak w katalogu <install>/eclipse/features/
).
Dzięki temu istnieje możliwość optymalizacji procesu aktualizacji katalogu <install>/eclipse/plugins/
, ponieważ nazwa podkatalogu zawierająca numer wersji modułu dodatkowego (lub fragmentu) zmienia się tylko wtedy, gdy zostanie zmieniony dowolny ze znajdujących się w niej plików. Innymi słowy, nie jest konieczne modyfikowanie plików w katalogu <install>/eclipse/plugins/org.eclipse.ui_2.0.0
/, jeśli ten podkatalog ma istnieć także po aktualizacji. Jeśli jeden z plików modułu dodatkowego miałby ulec zmianie, numer wersji modułu dodatkowego także jest zmieniany, a pliki aktualizowanego modułu dodatkowego są instalowane w równoległym katalogu <install>/eclipse/plugins/org.eclipse.ui_2.0.1
/.
Środowisko JRE domyślnie powinno znajdować się w katalogu <install>/eclipse/jre/bin/javaw.exe
.
Jeśli znajduje się w innym miejscu, należy w wierszu komend podać jego ścieżkę bezwzględną przy użyciu opcji -vm
(np. -vm C:\j2jre1.3.0\jre\bin\javaw.exe
).
W takiej sytuacji instalator powinien dodać tę opcję do wiersza komend skrótu tworzonego na pulpicie.
Rozszerzenie jest to oddzielnie instalowany zestaw składników i ich modułów dodatkowych, które można powiązać i używać wraz z jednym lub wieloma produktami opartymi na platformie Eclipse zainstalowanymi na tym samym komputerze. W przeciwieństwie do produktu rozszerzenie nie jest autonomiczną całością. Rozszerzenie nie zawiera pliku wykonywalnego produktu, platformy Eclipse ani środowiska JRE.
Na potrzeby ogólnych rozważań można założyć, że rozszerzenie składa się z pojedynczego składnika. Pierwszym parametrem wejściowym skryptu tworzenia instalatora jest katalog <extension
> zawierający składniki i moduły dodatkowe. Należy założyć, że w rozszerzeniu nie ma plików związanych z platformą Eclipse. Gdyby takie pliki istniały, zostałyby umieszczone w katalogu <extension>/
, a nie <extension>/eclipse/
. Struktura tego katalogu będzie wyglądać następująco:
<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/
Wartość parametru wejściowego <extension
> decyduje o tym, jakie pliki zostaną ostatecznie zainstalowane na komputerze użytkownika końcowego.
Ostatnie parametry wejściowe skryptu tworzenia instalatora to identyfikator (id) i numer wersji (version) składnika rozszerzenia (np. "com.example.wiley.anvil
" i "1.0.0
"). Te parametry mają dla instalatora szczególne znaczenie, ponieważ występują później w nazwach plików i katalogów, a także w treści plików znaczników tworzonych podczas instalacji.
Instalator rozszerzenia pod wieloma względami przypomina instalator produktu. Istniejące różnice wyróżniono poniżej:
Podczas instalacji instalator działa w standardowy sposób:
Jeśli miejsce określone w kroku 5 to katalog <install
>, to w kroku 11 instalator skopiuje wszystkie pliki z katalogu <extension>
do katalogu <install
>.
Plik wejściowy | Plik instalowany |
<extension>/* |
<install>/* |
W kroku 7 można wybrać dowolny produkt oparty na platformie Eclipse. Produkt oparty na platformie Eclipse można rozpoznać dzięki obecności pliku <product install>/eclipse/.eclipseproduct
. Użytkownik powinien mieć możliwość wyszukania na dysku zainstalowanych produktów (przycisk "Szukaj zainstalowanych produktów") lub samodzielnego wskazania katalogu zawierającego produkt (przycisk "Przeglądaj").
W kroku 8 instalator powinien przeprowadzić test zgodności polegający po prostu na porównaniu wzorca i nazw podkatalogów z katalogu <product install>/eclipse/features
. Na przykład obecność folderu pasującego do wzorca "org.eclipse.jdt_2.*
" oznacza, że instalowany produkt zawiera pakiet JDT.
Plik znacznika utworzony w kroku 10 <install>/eclipse/.eclipseextension
jest używany do oznaczania katalogu, w którym zainstalowano rozszerzenie oparte na platformie Eclipse. Pozwala to instalatorom rozszerzeń znaleźć ten katalog (podobnie jak w przypadku pliku znacznika .eclipseproduct
produktu). Plik znacznika jest plikiem w formacie java.io.Properties (kodowanie znaków ISO 8859-1, znak zmiany znaczenia: "\"). Zawiera on poniższe informacje pozwalające zidentyfikować rozszerzenie i odróżnić je od innych rozszerzeń opartych na platformie Eclipse:
name=Wiley Anvil Enterprise Edition
id=com.example.wiley.anvilfeature
version=1.0.0
Wartościami właściwości "id" (identyfikator) i "version" (wersja) są parametry wejściowe skryptu tworzenia instalatora. Nazwa rozszerzenia jest prawdopodobnie znana i zapisana na stałe. Produkt jako taki zazwyczaj nie odwołuje się do pliku znacznika - jest on odczytywany i zapisywany wyłącznie przez instalatory produktów i rozszerzeń.
Po zainstalowaniu wszystkich plików struktura najwyższego poziomu w katalogu instalacyjnym zawierać będzie następujące pliki i podkatalogi:
<install>/
eclipse/
.eclipseextension
features/
plugins/
Jedyna istotna różnica w odniesieniu do instalatora produktu polega na tym, że instalator rozszerzeń tworzy także pliki konsolidacji w katalogach innych produktów opartych na platformie Eclipse, które są już zainstalowane na komputerze użytkownika. Dzięki temu użytkownik nie musi ręcznie tworzyć powiązania między nowym rozszerzeniem a poszczególnymi produktami przy użyciu menedżera aktualizacji platformy Eclipse.
Plik konsolidacji utworzony w kroku 14 to plik <instalacja produktu>/eclipse/links/com.example.wiley.anvilfeature.link
. Oznacza to, że plik ma taką samą nazwę, jak katalog składnika rozszerzenia (bez przyrostka z numerem wersji). Plik konsolidacji jest plikiem w formacie java.io.Properties
(kodowanie znaków ISO 8859-1, znak zmiany znaczenia: \).
Kluczem jest słowo "path", a jego wartością - ścieżka bezwzględna do zainstalowanego rozszerzenia (<install>
). Wpis może na przykład wyglądać następująco "path=C:\\Program
Files\\Wiley\\Anvil
".
Instalator jest odpowiedzialny za przekształcenie oryginalnego kodowania znaków w kodowanie Unicode oraz za dodanie znaku zmiany znaczenia "\" w miejscach, w których jest to wymagane. Stosowanie znaku zmiany znaczenia jest konieczne, ponieważ katalog <install>
zawiera zwykle znaki specjalne (np. "\") oraz znaki spoza alfabetu łacińskiego. Produkt odczytuje pliki konsolidacji podczas uruchamiania. Instalator rejestruje każdy tworzony plik konsolidacji, aby łatwo go znaleźć w przypadku aktualizacji lub deinstalacji rozszerzenia.
Podczas deinstalacji deinstalator powinien działać w standardowy sposób:
install
> oraz wszystkich plików z katalogów <install
>/eclipse/features
i <install
>/eclipse/plugins
, w tym plików umieszczonych tam przez programy inne niż dany instalator (np. przez menedżera aktualizacji platformy Eclipse).Deinstalacja rozszerzenia powinna spowodować usunięcie wszystkich plików modułów dodatkowych i składników, ponieważ ich podkatalogi nie zawierają żadnych plików z ważnymi danymi. Pozwala to użytkownikowi na całkowite zdeinstalowanie rozszerzenia (łącznie z aktualizacjami dodanymi przez menedżera aktualizacji platformy Eclipse).
Jeśli rozszerzenie jest już zainstalowane na komputerze użytkownika, instalator powinien umożliwić jego uzupełnienie o poprawki serwisowe lub zaktualizowanie do nowszej wersji.
Podczas instalacji instalator powinien działać w standardowy sposób:
W kroku 2 zainstalowane rozszerzenie można rozpoznać dzięki obecności katalogu "eclipse
", w którym znajduje się plik o nazwie ".eclipseextension
".
Katalog nadrzędny katalogu "eclipse
" jest katalogiem instalacyjnym rozszerzenia (tj. <install>/eclipse/.eclipseextension
).
Informacje zawarte w tym pliku znacznika powinny zostać wyświetlone użytkownikowi w celu potwierdzenia, że aktualizowane jest właściwe rozszerzenie (na komputerze użytkownika może znajdować się więcej niż jedno rozszerzenie oparte na platformie Eclipse).
W kroku 7 instalator nie powinien usuwać ani zastępować żadnych plików, które zostały zainstalowane pierwotnie. Powinien tylko dodawać pliki dla nowszych wersji składników i modułów dodatkowych oraz ewentualnie utworzyć nowy plik znacznika (<install>/eclipse/.eclipseextension
). Pozostawienie poprzednich wersji na dysku umożliwia użytkownikowi późniejsze wycofanie aktualizacji. Podobnie jak w przypadku aktualizacji instalacji produktu, nie jest konieczne modyfikowanie plików w podkatalogu <install>/eclipse/plugins/com.example.wiley.otherplugin_1.0.0
/, jeśli powinien on istnieć także po aktualizacji. Jeśli dowolny z plików modułu dodatkowego ulegnie zmianie, zmieni się także numer wersji modułu dodatkowego, a pliki zaktualizowanego modułu zostaną zainstalowane w równoległym podkatalogu <install>/eclipse/plugins/com.example.wiley.otherplugin_1.0.1
/.