Sist endret 15.20 fredag 18. juni, 2004
Eclipse-baserte produkter må være riktig installert på sluttbrukerens datamaskin. Spesielle pakkeverktøy, for eksempel InstallShield og RPM, blir ofte brukt for å bygge utførbare installeringsprogrammer som automatiserer installeringen, oppdateringen og avinstalleringen. Dette notatet beskriver hvordan du skriver et installeringsprogram for et Eclipse-basert produkt, og utvidelser til Eclipse-baserte produkter som kan installeres separat.
Vi antar at en produktutviklingsgruppe er ansvarlig for å skaffe de grunnleggende ingrediensene som trengs på sluttbrukernes datamaskiner, pakket som et utførbart installeringsprogram. Det blir brukt skript under opprettelsen av utførbare installeringsprogrammer, og også ved handlingene under installering som trengs for å kommunisere med sluttbrukeren og legge filer på datamaskinene deres. Dette notatet beskriver i detalj hva disse installeringsprogrammene må gjøre, og hvordan de skal virke.
Dette notatet skal ses på som en oppskrift for personen som er ansvarlig for å skrive et installeringsprogram for Eclipse-baserte produkter. Det er to gode grunner til at vi anbefaler at de som skriver installeringsprogrammer, følger oppskriften:
Et produktinstalleringsprogram skal være komplett, slik at det kan distribueres på en CD og installeres på en hvilken som helst maskin med et passende operativsystem.
Eclipse krever Java2 JRE (Java Runtime Environment) for å kjøre Java-kode. JREer er lisensiert programvare fra Java-leverandører. Hvis et firma har en lisens til å redistribuere en JRE fra en JRE-leverandør, kan det inkludere en JRE i produktet og installere det på sluttbrukerens datamaskin sammen med produktet. Alternativt kan det kreves at en JRE forhåndsinstalleres på sluttbrukerens datamaskin og knyttes til produktet under installering. Uansett krever et Eclipse-basert produkt en passende JRE, og produktinstalleringsprogrammet må spille en rolle enten under installering av en JRE eller til å finne og linke til en JRE som finnes fra før.
Anta at en JRE skal installeres sammen med produktet. En katalog som inneholder JREen, blir lagt inn i skriptet
for opprettelse av installeringsprogrammet. Gi katalogen betegnelsen <JRE>. Denne katalogen må ha en standard
JRE-katalogstruktur, der den utførbare Java-filen ligger i jre/bin/java.exe
og klassebiblioteket
ligger i jre/lib/rt.jar
under <JRE>-katalogen.
Som referanse ser skjelettstrukturen til
katalogen slik ut:
<JRE>/
jre/
bin/
java.exe
lib/
rt.jar
Det er andre filer (og underkataloger) i disse katalogene - vi har bare tatt med et eksempel som viser den generelle strukturen. Navn i kursiv er produktspesifikke.
Det andre som blir lagt inn i skriptet for opprettelse av installeringsprogrammet, er en katalog,
<product head
>,
som inneholder den produktspesifikke utførbare oppstarteren og eventuelle filer som ikke er knyttet til Eclipse. Som
referanse ser skjelettstrukturen til denne katalogen slik ut (kursiv indikerer filnavn som varierer fra produkt til
produkt):
<product head>/
Det tredje som blir lagt inn i skriptet for opprettelse av installeringsprogrammet, er en
katalog, <
acmeproduct.exe
product
body
>, som inneholder funksjonene og plugin-modulene som er utviklet for produktet. Som
referanse ser skjelettstrukturen til katalogen slik ut:
<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
Det fjerde som blir lagt inn i skriptet for opprettelse av installeringsprogrammet, er
<platform
>,
som inneholder funksjonene og plugin-modulene for selve Eclipse-plattformen og eventuelle
tredjepartsverktøy som skal inkluderes.
Denne katalogen inkluderer også den utførbare standard
Eclipse-oppstarteren, eclipse.exe
,
(kalt eclipse
i Unix-operativsystemet), den tilhørende startup.jar
og alle andre
Eclipse-plattformfiler som kreves i roten av installeringen. Som
referanse ser skjelettstrukturen til katalogen slik ut:
<platform>
Det nøyaktige innholdet i inndatakatalogene <
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/
(flere org.eclipse.*-plugin-kataloger)
JRE
>, <product
head
>, <product body
>
og <platform
> bestemmer hvilke filer som til slutt blir installert på sluttbrukerens
datamaskin.
Det siste som blir lagt inn i skriptet for opprettelse av installeringsprogrammet, er ID- og
versjonsstrengene
for produktets primære funksjon, for eksempel
"com.example.acme.acmefeature"
og "1.0.0
", og navnet på det utførbare produktet, for eksempel "acmeproduct
.exe
".
For produkter som ikke krever egne utførbare produkter, er dette banen til den utførbare standard
Eclipse-oppstarteren "eclipse/eclipse.exe
".
Disse strengene har spesiell betydning for installeringsprogrammet, og
blir vist i fil- og katalognavn og i innholdet til marker-filer som opprettes under installering.
Under installering skal installeringsprogrammet virke på en standardisert måte (du finner flere detaljer etter listen over trinn):
Hvis plasseringen oppgitt i trinn 5 er <install
>,
kopierer installeringsprogrammet alle filene i katalogene <JRE
>,
<platform>,
<product
>,
og <product plug-ins>
til <install
>.
Inndatafil | Installert fil |
<JRE>/* |
<install>/eclipse/* |
<product head>/* |
<install>/* |
<product body>/* |
<install>/* |
<platform>/* |
<install>/* |
Marker-filen opprettet i trinn 8, <install>/eclipse/.eclipseproduct
, blir brukt til å
merke en katalog som det er installert et Eclipse-basert produkt i, primært for at
utvidelsesinstalleringsprogrammer skal finne dem. Denne marker-filen er en
java.io.Properties-formatfil (ISO
8859-1-tegnkoding med escape-tegnet "\") og inneholder følgende informasjon som identifiserer
produktet for
brukeren, og skiller ett Eclipse-basert produkt fra et annet:
name=Acme Visual Tools Pro
id=com.example.acme.acmefeature
version=1.0.0
Verdiene for egenskapene "id" og "version" blir lagt inn i skriptet for opprettelse av installeringsprogrammet. Navnet på produktet antas å være kjent og hardkodet. (Produkter får vanligvis ikke tilgang til denne marker-filen. Det er bare installeringsprogrammer for produkter og utvidere som skriver og leser den.)
Trinn 6 krever at det kontrolleres om filen <install>/eclipse/.eclipseproduct
eller <install>/eclipse/.eclipseextension
finnes fra før. Et produkt kan ikke installeres
på nøyaktig samme sted som et annet produkt eller en annen utvidelse.
Når filene er installert, skal toppnivåstrukturen til den installerte katalogen inneholde følgende filer og underkataloger (og kanskje andre):
<install>/
Hvis installeringsprogrammet for et produkt ber om lisensinformasjon fra brukeren, for eksempel navnet på
den registrerte eieren og lisensnøkkelen, skal denne informasjonen legges i produktets "om"-dialogboks
(trinn 10).
acmeproduct.exe
eclipse/
.eclipseproduct
eclipse.exe
startup.jar
features/
plugins/
jre/
Dette gjøres ved å registrere brukerens svar i filen "about.mapping
" i den primære
funksjonens plugin-modul. For eksempel
<install>/plugins/com.example.acme.acmefeature_1.0.0/about.mapping
.
Filen "about.mapping
" kan finnes fra før i <product
head
>, eller den må kanskje opprettes av installeringsprogrammet under installering.
Nøklene er
numre. Verdien av nøkkelen "n" blir erstattet av delstrengen "{n}
"
i "aboutText
"-egenskapen.
Hvis for eksempel en lisensnøkkel var feltnummer 0, skal det
opprettes en "about.mapping
"-fil med en linje som
"0=T42-24T-ME4U-U4ME
".
NB
Filen "about.mapping
" er en
java.io.Properties-formatfil
(ISO 8859-1-tegnkoding med escape-tegnet "\").
Når den interne tegnkodingen under installeringen er noe annet enn ISO 8859-1, har installeringsprogrammet
ansvar for å konvertere den interne tegnkodingen til Unicode og legge til "\"-escape-tegn der det er
nødvendig. Escape-tegn er nødvendig når strenger inneholder spesialtegn (for eksempel "\") eller
ikke-latinske tegn. Hvis for eksempel felt nummer 1 inneholder de 3 første tegnene i det greske alfabetet, blir
det skrevet som "1=\u03B1\u03B2\u03B3
".
I trinn 12 starter produktinstalleringsprogrammet det utførbare produktet, <install>/acmeproduct.exe
,
med det spesielle alternativet -initialize. Eclipse-plattformen utfører da all tidkrevende førstegangsbehandling og bufrer
resultatene slik at når brukeren starter produktet, vises det med en gang i
aktivert tilstand.
Under avinstallering skal avinstalleringsprogrammet virke på en standardisert måte:
install
> og alle filer i
<install
>/eclipse/features
og
<install
>/eclipse/plugins
, inkludert de som er lagt der av andre parter enn
dette installeringsprogrammet (for eksempel Eclipse-oppdateringsstyreren)Når produktet blir avinstallert, skal filer som er lagt inn under installeringen, slettes, sammen med de oppdaterte
funksjonene og plugin-modulene som ble opprettet av Eclipse-oppdateringsstyreren. Viktig: Under
avinstalleringen kan det være andre kataloger og filer i katalogen <install>
,
særlig <install>/eclipse/workspace/
,
<install>/eclipse/links/
og <install>/eclipse/configuration/
,
som inneholder viktige data som må beholdes når produktet blir avinstallert. Brukeren må kunne avinstallere
produktet og installere det på nytt på samme plasseringen uten å miste viktige data.
Hvis produktet allerede er installert på brukerens datamaskin, skal installeringsprogrammet tillate at det blir tatt i bruk en tjenesteoppdatering eller en versjonsoppgradering for det installerte produktet.
Under installering skal installeringsprogrammet virke på en standardisert måte:
I trinn 2 kan det installerte produktet gjenkjennes ved at det er en "eclipse
"-katalog
som umiddelbart inneholder filen ".eclipseproduct
".
Den overordnede for "eclipse
"-katalogen er produktets installeringskatalog, det vil si
<install>/eclipse/.eclipseproduct
.
Informasjonen i denne marker-filen skal vises til brukeren, slik at brukeren kan bekrefte at det er riktig produkt
som oppdateres (det kan være flere Eclipse-baserte produkter på brukerens datamaskin).
Installeringsprogrammet skal utføre kompatibilitetskontroll i trinn 3 ved enkel mønstersammenlikning med
underkataloger i katalogen <install>/eclipse/features
. Hvis det for eksempel finnes en
mappe som samsvarer med "com.example.acme.otherfeature_1.0.1
", betyr det at en
bestemt tjenesteoppdatering er tatt i bruk på det installerte produktet.
I trinn 7 kan installeringsprogrammet slette eller erstatte hvilke som helst filer som det opprinnelig
installerte, og legge til flere filer. Viktig: Flere filer og kataloger, inkludert
<install>/eclipse/workspace/
og <install>/eclipse/configuration
,
kan ligge sammen med installeringsprogrammet og inneholde viktige datafiler som må beholdes når produktet blir
oppgradert.
I oppgraderingssituasjoner er det store muligheter for at de fleste filene under <install>/eclipse/plugins/
er de samme (som for <install>/eclipse/features/
).
Det er store muligheter for optimalisering i <install>/eclipse/plugins/
, ettersom navnet
på underkatalogen, som tar med plugin-versjonsnummeret (eller fragmentversjonsnummeret), endres hvis, og bare hvis,
noen av de underliggende filene endres. Det er med andre ord ikke nødvendig å røre noen filer i <install>/eclipse/plugins/org.eclipse.ui_2.0.0
/
hvis underkatalogen også skal finnes etter oppgraderingen. Hvis noen av plugin-modulens filer blir endret, blir
plugin-versjonsnummeret endret, noe som fører til at filene for den oppgraderte plugin-modulen blir installert
i en parallell katalog <install>/eclipse/plugins/org.eclipse.ui_2.0.1
/.
Det forventes at JREen ligger i <install>/eclipse/jre/bin/javaw.exe
.
Hvis den ligger et annet sted, skal den fullstendige banen oppgis med alternativet -vm
på
kommandolinjen, for eksempel -vm C:\j2jre1.3.0\jre\bin\javaw.exe
.
I dette tilfellet skal installeringsprogrammet legge til dette alternativet på kommandolinjen for
skrivebordssnarveien det oppretter.
Med utvidelse mener vi et eget sett med installerbare funksjoner og plugin-moduler som kan knyttes til, og brukes fra, ett eller flere Eclipse-baserte produkter som er installert på samme datamaskin. I motsetning til et produkt, er ikke en utvidelse komplett. En utvidelse inneholder ikke et utførbart produkt, Eclipse-plattformen, en JRE.
Anta at en utvidelse består av en enkelt funksjon. Det første som blir lagt inn i skriptet for opprettelse av
installeringsprogrammet, er en katalog, <extension
>, som inneholder tilhørende funksjon og
plugin-moduler. Vi antar at en utvidelse ikke har noen filer som er knyttet til Eclipse. Hvis den har det, legges
de i <extension>/
, og ikke i <extension>/eclipse/
. Som
referanse ser skjelettstrukturen til katalogen slik ut:
<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/
Det nøyaktige innholdet i inndatakatalogen <extension
> bestemmer hvilke filer som
til slutt blir installert på sluttbrukerens datamaskin.
Det siste som blir lagt inn i skriptet for opprettelse av installeringsprogrammet, er ID- og
versjonsstrengene for utvidelsens funksjon, for eksempel "com.example.wiley.anvil
"
og "1.0.0
". Disse strengene har spesiell betydning for installeringsprogrammet, og
blir vist i fil- og katalognavn og i innholdet til marker-filer som opprettes under installering.
Et utvidelsesinstalleringsprogram likner på mange måter et produktinstalleringsprogram. De områdene som skiller dem, er uthevet nedenfor:
Under installering virker installeringsprogrammet på en standardisert måte:
Hvis plasseringen oppgitt i trinn 5 er <install
>,
kopierer installeringsprogrammet alle filene i katalogen <extension>
til
<install
> i trinn 11.
Inndatafil | Installert fil |
<extension>/* |
<install>/* |
I trinn 7 kan et hvilket som helst Eclipse-produkt være en kandidat. Eclipse-baserte produkter kan gjenkjennes
ved at de har filen <product install>/eclipse/.eclipseproduct
, brukere skal kunne be om
et begrenset disksøk etter installerte produkter (en "søk etter installerte produkter"-knapp), eller de
kan navigere til en katalog som inneholder et produkt (for eksempel en "bla gjennom"-knapp).
Installeringsprogrammet skal utføre kompatibilitetskontroll i trinn 8 ved enkel mønstersammenlikning med
underkataloger i katalogen <product install>/eclipse/features
. Hvis det for eksempel
finnes en mappe som samsvarer med "org.eclipse.jdt_2.*
", betyr det at JDT er inkludert i det
installerte produktet.
Marker-filen opprettet i trinn 10, <install>/eclipse/.eclipseextension
, blir brukt til
å merke en katalog som det er installert en Eclipse-basert utvidelse i, primært for at
utvidelsesinstalleringsprogrammet skal finne dem (tilsvarer marker-filen .eclipseproduct
for et
produkt). Denne marker-filen er en
java.io.Properties-formatfil (ISO
8859-1-tegnkoding med escape-tegnet "\") og inneholder følgende informasjon som identifiserer
utvidelsen for brukeren, og skiller en Eclipse-basert utvidelse fra en annen:
name=Wiley Anvil Enterprise Edition
id=com.example.wiley.anvilfeature
version=1.0.0
Verdiene for egenskapene "id" og "version" blir lagt inn i skriptet for opprettelse av installeringsprogrammet. Navnet på utvidelsen antas å være kjent og hardkodet. (Produkter får vanligvis ikke tilgang til denne marker-filen. Det er bare installeringsprogrammer for produkter og utvidere som skriver og leser den.)
Når filene er installert, skal toppnivåstrukturen til den installerte katalogen inneholde følgende filer og underkataloger:
<install>/
eclipse/
.eclipseextension
features/
plugins/
Den eneste forskjellen av betydning fra et produktinstalleringsprogram er at et utvidelsesinstalleringsprogram også oppretter linkfiler i andre Eclipse-baserte produkter som allerede er installert på brukerens datamaskin. (Dermed slipper brukeren manuelt å tilknytte den nye utvidelsen fra hvert produkt med Eclipse-oppdateringsstyreren.)
Linkfilen opprettet i trinn 14 er <product
install>/eclipse/links/com.example.wiley.anvilfeature.link
. Linkfilen har altså samme navn som
utvidelsens funksjonskatalog, uten versjonssuffikset. En linkfil er en
java.io.Properties-formatfil
(ISO 8859-1-tegnkoding med escape-tegnet "\").
Nøkkelen er "path" og verdien er den fullstendige banen
til den installerte utvidelsen, <install>
. En oppføring kan for eksempel se ut som
"path=C:\\Program Files\\Wiley\\Anvil
".
Installeringsprogrammet har ansvar for
å konvertere den interne tegnkodingen til Unicode og legge til "\"-escape-tegn der det er nødvendig. Escape-tegn
kreves som regel, ettersom <install>
vanligvis inneholder spesialtegn (for eksempel
"\") og kan inneholde kataloger med ikke-latinske tegn i navnet. Produktet leser linkfilen når den
starter. Installeringsprogrammet registrerer alle linkfiler den oppretter, slik at det er mulig å finne dem når
utvidelsen blir oppdatert eller avinstallert.
Under avinstallering skal avinstalleringsprogrammet virke på en standardisert måte:
install
> og alle filer i
<install
>/eclipse/features
og
<install
>/eclipse/plugins
, inkludert de som er lagt der av andre parter enn
dette installeringsprogrammet (for eksempel Eclipse-oppdateringsstyreren)Når en utvidelse blir avinstallert, skal alle plugin- og funksjonsfiler slettes. Det er ingen viktige datafiler som skal beholdes i disse underkatalogene. Dette gjør at brukeren kan avinstallere en utvidelse fullstendig, inkludert eventuelle oppdateringer som er tatt i bruk av Eclipse-oppdateringsstyreren.
Hvis utvidelsen allerede er installert på brukerens datamaskin, skal installeringsprogrammet tillate at det blir tatt i bruk en tjenesteoppdatering eller en versjonsoppgradering på den installerte utvidelsen.
Under installering skal installeringsprogrammet virke på en standardisert måte:
I trinn 2 kan den installerte utvidelsen gjenkjennes ved at det er en
"eclipse
"-katalog
som umiddelbart inneholder filen ".eclipseextension
".
Den overordnede for "eclipse
"-katalogen er utvidelsens installeringskatalog, det vil
si <install>/eclipse/.eclipseextension
.
Informasjonen i denne marker-filen skal vises til brukeren, slik at brukeren kan bekrefte at det er riktig
utvidelse som oppdateres (det kan være flere Eclipse-baserte utvidelser på brukerens datamaskin).
I trinn 7 skal ikke installeringsprogrammet slette eller overskrive noen av de filene som opprinnelig ble
installert. Det skal i stedet bare legge til filene for nye versjoner av funksjoner og plugin-moduler, og
kanskje skrive om marker-filen <install>/eclipse/.eclipseextension
. Hvis den gamle
versjonen blir liggende, gir det brukeren muligheten til ikke å bruke oppdateringen. Som med oppgradering av
produktinstalleringen er det ikke nødvendig å røre noen filer i <install>/eclipse/plugins/com.example.wiley.otherplugin_1.0.0
/
hvis denne underkatalogen også skal finnes etter oppgraderingen. Hvis noen av plugin-filene blir endret, blir
plugin-versjonsnummeret endret, noe som fører til at filene for den oppgraderte plugin-modulen blir installert i en
parallell katalog <install>/eclipse/plugins/com.example.wiley.otherplugin_1.0.1
/.