Laatst gewijzigd op vrijdag 18 juni 2004 om 15:20 uur
Op Eclipse gebaseerde producten moeten op de juiste wijze worden geïnstalleerd op de computer van de eindgebruiker. Speciale verpakkingstools, zoals InstallShield en RPM, worden vaak gebruikt om uitvoerbare installatieprogramma's te bouwen waarmee producten automatisch kunnen worden geïnstalleerd, bijgewerkt en verwijderd. In dit document wordt beschreven hoe u een installatieprogramma voor een op Eclipse gebaseerd product en voor afzonderlijk te installeren extensies voor op Eclipse gebaseerde producten schrijft.
Hierbij wordt aangenomen dat een productontwikkelteam verantwoordelijk is voor aanlevering van de basisonderdelen die, verpakt als uitvoerbaar installatieprogramma, op de computers van de eindgebruikers moeten worden gezet. Het maken van uitvoerbare installatieprogramma's moet verlopen volgens een bepaald script, evenals de installatieacties die nodig zijn om interactief met de eindgebruikers te werken en bestanden op hun computer te zetten. In dit document vindt u een gedetailleerde beschrijving van de vereiste werking van deze installatieprogramma's.
Dit document moet worden beschouwd als procedure voor de persoon die verantwoordelijk is voor het schrijven van een installatieprogramma voor een op Eclipse gebaseerd product. Er zijn twee goede redenen waarom iedere schrijver van een dergelijk installatieprogramma zich aan deze procedure moet houden:
Een productinstallatieprogramma moet een op zichzelf staand programma zijn, dat bijvoorbeeld kan worden gedistribueerd op een cd-rom en kan worden geïnstalleerd op elke computer met een geschikt besturingssysteem.
Voor Eclipse is een Java2-JRE (Java Runtime Environment, Java-runtimeomgeving) vereist om Java-code uit te voeren. Een JRE is gelicentieerde software, die kan worden verkregen van Java-leveranciers. Met een licentie om een JRE van een JRE-leverancier te herdistribueren, mag een bedrijf een JRE meeleveren bij haar product en deze JRE tegelijk met haar product installeren op de computer van de eindgebruiker. Als alternatief kunt u ook vereisen dat op de computer van de eindgebruiker al een bepaalde JRE is geïnstalleerd, en ervoor zorgen dat deze JRE tijdens het installatieproces aan het product wordt gekoppeld. In beide gevallen is voor het op Eclipse gebaseerde product een geschikte JRE vereist en moet het productinstallatieprogramma een rol spelen in ofwel het installeren van een JRE ofwel het opzoeken en koppelen van het product aan een bestaande JRE.
Ga ervan uit dat er bij het product een JRE moet worden geïnstalleerd. Een directory met de JRE is
een verplicht invoergegeven voor het script voor het maken van het installatieprogramma. Duid deze directory
aan met <JRE>. Deze directory moet een standaard-JRE-directorystructuur hebben, waarbij het
uitvoerbare Java-bestand zich bevindt in jre/bin/java.exe
en de klassenbibliotheek zich
bevindt in jre/lib/rt.jar
in de directory <JRE>.
Ter referentie, de raamstructuur van deze directory ziet er als volgt uit:
<JRE>/
jre/
bin/
java.exe
lib/
rt.jar
Er bevinden zich nog meer bestanden (en subdirectory's) in deze directory's. Hier is echter slechts een deel afgebeeld om u een idee te geven van de algemene structuur. Cursieve namen zijn productspecifiek.
Het tweede invoergegeven voor het installatieprogramma-aanmaakscript is een directory, <product
head
>, met het productspecifieke uitvoerbare startprogramma en alle bestanden die niet gerelateerd
zijn aan Eclipse. Ter referentie, de raamstructuur van deze directory ziet er als volgt uit
(cursieve bestandsnamen verschillen per product):
<product head>/
Het derde invoergegeven voor het installatieprogramma-aanmaakscript is een directory, <
acmeproduct.exe
product
body
>, met de ontwikkelde features en plugins voor het product. Ter referentie, de raamstructuur van deze directory ziet er als volgt uit:
<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
Het vierde invoergegeven voor het installatieprogramma-aanmaakscript is een directory, <platform
>,
met de features en plugins voor het Eclipse-platform zelf en alle tools van derden die worden meegeleverd.
Deze directory bevat ook het standaardopstartprogramma van Eclipse, het uitvoerbare bestand eclipse.exe
,
(eclipse
in een Unix-omgeving), het bijbehorende bestand startup.jar
en alle andere Eclipse-platformbestanden
die vereist zijn aan het begin van het installatieproces. Ter referentie, de raamstructuur van deze directory ziet er als volgt uit:
<platform>
De exacte inhoud van de invoerdirectory's <
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/
(overige plugindirectory's org.eclipse.*)
JRE
>, <product
head
>, <product body
>,
en <platform
> bepaalt welke bestanden uiteindelijk
op de computer van de eindgebruiker worden geïnstalleerd.
De laatste invoergegevens voor het installatieprogramma-aanmaakscript zijn de tekenreeksen met het ID en de versie
van de primaire feature van het product, bijvoorbeeld "com.example.acme.acmefeature"
en "1.0.0
", en de naam van het uitvoerbare bestand van het product, bijvoorbeeld
"acmeproduct
.exe
".
Voor producten waarvoor geen eigen uitvoerbaar bestand vereist is, wordt dit het pad van
het standaardopstartprogramma van Eclipse, het uitvoerbare bestand "eclipse/eclipse.exe
".
Deze tekenreeksen zijn van speciaal belang voor het installatieprogramma, omdat ze worden gebruikt in bestands- en directorynamen en in de inhoud van markeringsbestanden die tijdens de installatie worden gemaakt.
Het installatieproces moet verlopen volgens het volgende standaardgedrag (gedetailleerde uitleg volgt na de stappenlijst):
Als tijdens stap 5 de locatie <install
> is opgegeven, worden door het installatieprogramma
alle bestanden in de directory's <JRE
>, <platform>,
<product
> en
<product plug-ins>
naar <install
> gekopieerd.
Invoerbestand | Geïnstalleerd bestand |
<JRE>/* |
<install>/eclipse/* |
<product head>/* |
<install>/* |
<product body>/* |
<install>/* |
<platform>/* |
<install>/* |
Het markeringsbestand dat tijdens stap 8 wordt gemaakt, <install>/eclipse/.eclipseproduct
,
wordt gebruikt om aan te duiden dat in de desbetreffende directory een op Eclipse gebaseerd product is geïnstalleerd,
hoofdzakelijk zodat deze kan worden gevonden door extensie-installatieprogramma's. Dit markeringsbestand is een java.io.Properties-indelingsbestand
(ISO 8859-1 tekencodering met "\"-ontsnappingstekens) en bevat de volgende gegevens waarmee het product voor de gebruiker
kan worden geïdentificeerd en het ene op Eclipse gebaseerde product kan worden onderscheiden van het andere:
name=Acme Visual Tools Pro
id=com.example.acme.acmefeature
version=1.0.0
De waarden van de eigenschappen "id" en "version" zijn invoergegevens van het installatieprogramma-aanmaakscript. De naam van het product is waarschijnlijk bekend en zo gecodeerd dat deze niet kan worden gewijzigd (hard-coded). (Het markeringsbestand wordt gewoonlijk niet gebruikt door producten, maar alleen beschreven of gelezen door product- en extensie-installatieprogramma's.)
Bij stap 6 moet worden gecontroleerd of er al een bestand <install>/eclipse/.eclipseproduct
of <install>/eclipse/.eclipseextension
aanwezig is. Een product kan niet
worden geïnstalleerd op exact dezelfde locatie als een ander product of een andere extensie.
Nadat alle bestanden geïnstalleerd zijn, bevat de toplevel structuur van de installatiedirectory de volgende bestanden en subdirectory's (en mogelijk ook nog andere bestanden en subdirectory's):
<install>/
Als in een productinstallatieprogramma licentiegegevens moeten worden ingevoerd door de gebruiker, zoals
de naam van de geregisteerde eigenaar en de licentiecode, moeten deze gegevens worden opgenomen in het
"Info"-dialoogvenster van het product (stap 10).
acmeproduct.exe
eclipse/
.eclipseproduct
eclipse.exe
startup.jar
features/
plugins/
jre/
Dit wordt gedaan door de respons van de gebruiker vast te leggen in het bestand "about.mapping
"
in de plugin van de primaire feature, bijvoorbeeld <install>/plugins/com.example.acme.acmefeature_1.0.0/about.mapping
.
Het bestand "about.mapping
" kan vooraf gedefinieerd zijn in <product
head
> of moet tijdens de installatie door het installatieprogramma worden gemaakt.
De sleutels zijn getallen. De waarde van de sleutel "n" wordt gebruikt
voor de subtekenreeks "{n}
" in de eigenschap "aboutText
".
Als een licentiecode bijvoorbeeld veld nummer 0 is, wordt een bestand "about.mapping
"
met een regel in de vorm van "0=T42-24T-ME4U-U4ME
" gemaakt.
Opmerking: het bestand "about.mapping
" is een java.io.Properties-indelingsbestand
(ISO 8859-1 tekencodering met "\"-ontsnappingstekens).
Als de standaardtekencodering tijdens de installatie niet ISO 8859-1 is, moet het installatieprogramma ervoor
zorgen dat de standaardtekencodering wordt geconverteerd naar Unicode en dat er waar nodig
"\"-ontsnappingstekens worden toegevoegd. Dit is nodig wanneer de tekenreeksen speciale tekens
(zoals "\") of niet-Latin-tekens bevatten. Voorbeeld: veld nummer 1 met de eerste 3 letters van het Griekse
alfabet wordt geschreven als "1=\u03B1\u03B2\u03B3
".
Bij stap 12 wordt het startprogramma van het product, het uitvoerbare bestand <install>/acmeproduct.exe
,
uitgevoerd met de speciale optie -initialize [de precieze gegevens hierover volgen nog]. Dit heeft tot gevolg dat het platform alle tijdrovende eerste verwerkingen in stilte uitvoert en de resultaten in de cache opslaat, zodat wanneer de gebruiker het product opent, dit in de status Klaar voor gebruik wordt geopend.
Het programma voor het ongedaan maken van de installatie moet worden uitgevoerd volgens het volgende gedrag:
install
>, evenals
alle bestanden uit de directory's <install
>/eclipse/features
en <install
>/eclipse/plugins
, inclusief bestanden van andere programma's
dan dit installatieprogramma (bijvoorbeeld de updatemanager van Eclipse).Nadat de installatie van het product ongedaan gemaakt is, moeten de (tijdelijke) bestanden die voor het installatieproces
overgedragen zijn worden verwijderd, met inbegrip van bijgewerkte features en plugins die door de updatemanager van Eclipse
gemaakt zijn. Belangrijk: in de directory <install>
, met name in de subdirectory's <install>/eclipse/workspace/
,
<install>/eclipse/links/
en <install>/eclipse/configuration/
, kunnen zich andere directory's en bestanden bevinden
waarin belangrijke gegevens zijn opgeslagen die bewaard moeten blijven wanneer het product wordt verwijderd. De gebruiker moet een product kunnen verwijderen
en vervolgens opnieuw kunnen installeren op dezelfde locatie zonder dat daarbij belangrijke gegevens verloren gaan.
Als het product al op de computer van de gebruiker geïnstalleerd is, moet het installatieprogramma een service-update of versie-upgrade voor het geïnstalleerde product toestaan als deze beschikbaar is.
Het installatieprogramma moet worden geprogrammeerd volgens dit standaardgedrag:
Tijdens stap 2 kan een geïnstalleerd product worden herkend aan de aanwezigheid van de directory "eclipse
",
waarin een bestand met de naam ".eclipseproduct
" voorkomt.
Het bovenliggende item van de directory "eclipse
" is de installatiedirectory
van het desbetreffende product, bijvoorbeeld <install>/eclipse/.eclipseproduct
.
De informatie in dit markeringsbestand dient te worden afgebeeld voor de gebruiker zodat deze kan
bevestigen dat het juiste product wordt bijgewerkt (mogelijk zijn er meerdere op Eclipse gebaseerde
producten op de computer van de gebruiker geïnstalleerd).
De compatibiliteitscontroles die worden beschreven in stap 3 kunnen door het installatieprogramma worden uitgevoerd
door middel van een eenvoudige patroonvergelijking met subdirectory's in de directory <install>/eclipse/features
.
Door bijvoorbeeld te controleren of er een map is die overeenkomt met "com.example.acme.otherfeature_1.0.1
",
kan worden vastgesteld of een bepaalde service-update op het geïnstalleerde product is toegepast.
Voor stap 7 kan het installatieprogramma enkele of alle oorspronkelijke bestanden verwijderen of vervangen,
en aanvullende bestanden toevoegen. Belangrijk: in de installatiedirectory kunnen zich verschillende bestanden en (sub)directory's met belangrijke gegevensbestanden bevinden, zoals
<install>/eclipse/workspace/
en <install>/eclipse/configuration
, die niet mogen worden verwijderd wanneer het product wordt bijgewerkt.
In upgradesituaties is de kans groot dat de meeste bestanden in <install>/eclipse/plugins/
(en <install>/eclipse/features/
) hetzelfde zijn gebleven.
Er zijn goede mogelijkheden voor optimalisatie in <install>/eclipse/plugins/
omdat de naam van de subdirectory waarin het versienummer van de plugin (of het fragment) is
ingebed, alleen wordt gewijzigd als een van de onderliggende bestanden wordt gewijzigd. Met andere
woorden, de bestanden in <install>/eclipse/plugins/org.eclipse.ui_2.0.0/
hoeven niet te worden
gewijzigd als deze subdirectory ook na de upgrade nog aanwezig moet zijn. Als bijvoorbeeld een van de pluginbestanden wordt gewijzigd,
verandert ook het versienummer van de plugin, waardoor de bestanden voor de bijgewerkte plugin worden geïnstalleerd in de
parallelle directory <install>/eclipse/plugins/org.eclipse.ui_2.0.1/
.
De verwachte locatie van de JRE is <install>/eclipse/jre/bin/javaw.exe
.
Als de JRE zich op een andere locatie bevindt, moet u deze opgeven in de vorm van een absoluut pad met de opdrachtregeloptie -vm
,
bijvoorbeeld -vm C:\j2jre1.3.0\jre\bin\javaw.exe
.
In dat geval moet deze optie door het installatieprogramma worden toegevoegd aan de opdrachtregel van de snelkoppeling die op het bureaublad wordt geplaatst.
Een extensie is een afzonderlijk te installeren set features en bijbehorende plugins die kunnen worden gekoppeld aan en gebruikt door een of meer op Eclipse gebaseerde producten die zijn geïnstalleerd op een computer. In tegenstelling tot een product staat een extensie niet op zichzelf. Een extensie bevat geen uitvoerbaar productbestand, Eclipse-platform of JRE.
Voor het gemak kunt u ervan uitgaan dat een extensie bestaat uit één feature. Het eerste invoergegeven voor het installatieprogramma-aanmaakscript is een directory, <extension
>, met de bijbehorende feature en plugins. We nemen aan dat een extension geen bestanden heeft die aan Eclipse gerelateerd zijn, anders zouden deze thuishoren in <extension>/
, en niet in <extension>/eclipse/
. Ter referentie, de raamstructuur van deze directory ziet er als volgt uit:
<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/
De exacte inhoud van de invoerdirectory <extension
> bepaalt welke bestanden uiteindelijk op de computer van de eindgebruiker worden geïnstalleerd.
De laatste invoergegevens voor het installatieprogramma-aanmaakscript zijn de tekenreeksen met het ID en de versie van de extensiefeature, bijvoorbeeld "com.example.wiley.anvil
" en "1.0.0
". Deze tekenreeksen zijn van speciaal belang voor het installatieprogramma, omdat ze worden gebruikt in bestands- en directorynamen en in de inhoud van markeringsbestanden die tijdens de installatie worden gemaakt.
Een extensie-installatieprogramma werkt in veel opzichten hetzelfde als een productinstallatieprogramma. De verschillen worden hieronder weergegeven:
Het installatieprogramma wordt uitgevoerd volgens het standaardgedrag:
Als tijdens stap 5 de locatie <install
> is opgegeven, worden door het installatieprogramma alle bestanden in de directory <extension>
tijdens stap 11 naar <install
> gekopieerd.
Invoerbestand | Geïnstalleerd bestand |
<extension>/* |
<install>/* |
Voor stap 7 komt elk willekeurig Eclipse-product in aanmerking. Op Eclipse gebaseerde producten
zijn herkenbaar aan de aanwezigheid van een bestand <product install>/eclipse/.eclipseproduct
.
De gebruiker moet een beperkte zoekopdracht kunnen uitvoeren om de schijf te doorzoeken op geïnstalleerde
producten (met een knop "Geïnstalleerde producten zoeken") of kunnen navigeren naar een
directory met een product (met een knop "Bladeren").
De compatibiliteitscontroles die worden beschreven in stap 8 kunnen door het installatieprogramma worden uitgevoerd
door middel van een eenvoudige patroonvergelijking met subdirectory's in de directory <product install>/eclipse/features
.
Door bijvoorbeeld te controleren of er een map is die overeenkomt met "org.eclipse.jdt_2.*
"
kan worden vastgesteld of JDT is opgenomen in het geïnstalleerde product.
Het markeringsbestand dat tijdens stap 10 wordt gemaakt, <install>/eclipse/.eclipseextension
,
wordt gebruikt om aan te duiden dat in een bepaalde directory een op Eclipse gebaseerde extensie is geïnstalleerd,
hoofdzakelijk zodat deze kan worden gevonden door extension-installatieprogramma's (zoals bij het markeringsbestand .eclipseproduct
van een product). Dit
markeringsbestand is een java.io.Properties-indelingsbestand
(ISO 8859-1 tekencodering met "\"-ontsnappingstekens) en bevat de volgende gegevens waarmee de extensie voor de gebruiker
kan worden geïdentificeerd en de ene op Eclipse gebaseerde extensie kan worden onderscheiden van de andere:
name=Wiley Anvil Enterprise Edition
id=com.example.wiley.anvilfeature
version=1.0.0
De waarden van de eigenschappen "id" en "version" zijn invoergegevens van het installatieprogramma-aanmaakscript. De naam van de extensie is waarschijnlijk bekend en zo gecodeerd dat deze niet meer kan worden veranderd (hard-coded). (Het markeringsbestand wordt gewoonlijk niet gebruikt door producten, maar alleen beschreven of gelezen door product- en extensie-installatieprogramma's.)
Nadat alle bestanden geïnstalleerd zijn, bevat de toplevel structuur van de installatiedirectory de volgende bestanden en subdirectory's:
<install>/
eclipse/
.eclipseextension
features/
plugins/
Het enige grote verschil met een productinstallatieprogramma is dat een extensie-installatieprogramma ook linkbestanden maakt in andere op Eclipse gebaseerde producten die al op de computer van de gebruiker geïnstalleerd zijn. (Hierdoor hoeft de gebruiker de nieuwe extensie niet handmatig aan elk product te koppelen met de updatemanager van Eclipse.)
Het linkbestand dat tijdens stap 14 wordt gemaakt, is <product install>/eclipse/links/com.example.wiley.anvilfeature.link
.
Dit bestand heeft dezelfde naam als de featuredirectory van de extensie, maar dan zonder het versienummersuffix.
Een linkbestand is een java.io.Properties-indelingsbestand (ISO 8859-1 tekencodering met "\"-ontsnappingstekens).
De sleutel is "path" en de waarde is het absolute pad van de geïnstalleerde extensie, <install>
. Voorbeeld: "path=C:\\Program Files\\Wiley\\Anvil
".
Het installatieprogramma
moet ervoor zorgen dat de standaardtekencodering wordt geconverteerd naar Unicode en dat er waar nodig "\"-ontsnappingstekens worden toegevoegd. Dit is
gewoonlijk vereist omdat <install>
vaak speciale tekens (zoals "\")
en verwijzingen naar directorynamen met niet-Latin-tekens bevat. De linkbestanden worden bij het opstarten
van het product gelezen. Het installatieprogramma houdt een record van alle gemaakte linkbestanden bij, zodat deze kunnen worden teruggevonden wanneer de extensie wordt bijgewerkt of verwijderd.
Het verwijderprogramma moet worden geprogrammeerd volgens dit standaardgedrag:
install
>, evenals
alle bestanden uit de directory's <install
>/eclipse/features
en <install
>/eclipse/plugins
, inclusief bestanden van andere programma's
dan dit installatieprogramma (bijvoorbeeld de updatemanager van Eclipse).Bij het verwijderen van een extensie moeten alle plugin- en featurebestanden worden verwijderd: er zijn geen belangrijke gegevensbestanden in deze subdirectory's die bewaard moeten blijven. Hierdoor kan de gebruiker een extensie volledig verwijderen, inclusief alle updates die door de updatemanager van Eclipse zijn toegepast.
Als de extension al op de computer van de gebruiker geïnstalleerd is, moet het installatieprogramma een service-update of versie-upgrade voor de geïnstalleerde extensie toestaan als deze beschikbaar is.
Het installatieprogramma moet worden geprogrammeerd volgens dit standaardgedrag:
Tijdens stap 2 kan een geïnstalleerde extensie worden herkend aan de aanwezigheid van de directory "eclipse
",
waarin een bestand met de naam ".eclipseextension
" voorkomt.
Het bovenliggende item van de directory "eclipse
" is de installatiedirectory
van de desbetreffende extensie, bijvoorbeeld <install>/eclipse/.eclipseextension
.
De informatie in dit markeringsbestand dient te worden afgebeeld voor de gebruiker zodat deze kan
bevestigen dat de juiste extensie wordt bijgewerkt (mogelijk zijn er meerdere op Eclipse gebaseerde
extensies op de computer van de gebruiker geïnstalleerd).
Bij stap 7 mag het installatieprogramma geen oorspronkelijke installatiebestanden verwijderen of overschrijven.
Er mogen alleen bestanden worden toegevoegd of geschreven voor nieuwe versies van de features en de plugin of
eventuele wijzigingen van het markeringsbestand <install>/eclipse/.eclipseextension
. Door de oude versies te bewaren
heeft de gebruiker nog de mogelijkheid om de update terug te draaien. Zoals bij een upgrade van een productinstallatie, hoeven
de bestanden in <install>/eclipse/plugins/com.example.wiley.otherplugin_1.0.0/
niet te worden
gewijzigd als deze subdirectory ook na de upgrade nog aanwezig moet zijn. Als bijvoorbeeld een van de pluginbestanden
wordt gewijzigd, verandert ook het versienummer van de plugin, waardoor de bestanden voor de bijgewerkte plugin worden
geïnstalleerd in een de parallelle directory <install>/eclipse/plugins/com.example.wiley.otherplugin_1.0.1/
.