Dernière modification : Vendredi 18 juin 2004 à 15h20
Les produits basés sur Eclipse doivent être correctement installés sur l'ordinateur de l'utilisateur final. Des outils spécialisés d'intégration, tels que InstallShield et RPM, sont souvent utilisés pour générer des exécutables qui automatisent l'installation, la mise à jour et la désinstallation. Cette note explique comment écrire un programme d'installation pour un produit basé sur Eclipse et pour des extensions installables séparément de produits basés sur Eclipse.
Nous partons du principe qu'une équipe de développement produit fournit les éléments bruts qui permettront l'intégration d'ordinateurs d'utilisateurs en tant que programme d'installation exécutable. La création de programmes d'installation exécutables est convertie en scripts, à l'instar des opérations exécutées lors de l'installation, qui permettent de communiquer avec l'utilisateur final et de déposer des fichiers sur son ordinateur. Cette note explique en détails les tâches que doivent effectuer ces programmes d'installation et comment ils doivent fonctionner.
Elle fait office de recette à l'intention de la personne chargée d'écrire un programme d'installation pour un produit basé sur Eclipse. Nous vous recommandons de la respecter pour l'écriture de tous vos programmes d'installation, et ce pour deux bonnes raisons :
Un programme d'installation de produit doit être autonome (distribuable sur CD-ROM et installable sur toute machine dotée du système d'exploitation adéquat.
Eclipse nécessite un environnement d'exécution Java (JRE) Java2 pour exécuter du code Java. Les JRE sont des logiciels sous licence, disponibles auprès des distributeurs Java. Avec une licence de redistribution d'un JRE obtenue auprès d'un revendeur de JRE, une compagnie peut associer à son produit un JRE qu'elle installe sur l'ordinateur de l'utilisateur final en même temps que le produit. L'installation d'un JRE sur l'ordinateur de l'utilisateur final peut aussi être demandée en tant que prérequis au moment de l'installation du produit. Quelle que soit la méthode retenue, un produit basé sur Eclipse nécessite un JRE approprié et le programme d'installation du produit doit assurer l'installation d'un JRE ou déterminer l'emplacement d'un JRE existant.
Partons du principe qu'un JRE est installé avec le produit. L'une des entrée du script de création du programme
d'installation désigne le répertoire contenant le JRE. Nommez ce répertoire <JRE>. Il doit avoir une
structure de répertoire JRE standard, avec l'exécutable Java dans jre/bin/java.exe
et la bibliothèque de
classes dans jre/lib/rt.jar
sous le répertoire <JRE>.
A titre indicatif, la structure de ce répertoire se présente comme suit :
<JRE>/
jre/
bin/
java.exe
lib/
rt.jar
Ces répertoires contiennent d'autres fichiers (et sous-répertoires) ; nous ne présentons ici que la structure de base. Les noms en italiques désignent des éléments propres à des produits.
La seconde entrée du script de création du programme d'installation est un répertoire, <en-tête de
produit
>, qui contient le programme de lancement de l'exécutable propre au produit ainsi que tous les
fichiers non liés à Eclipse. A titre indicatif, la structure de ce répertoire se présente comme suit (les noms en italiques variant
selon les produits) :
<en-tête de produit>/
La troisième entrée du script de création du programme d'installation est un répertoire, <
acmeproduct.exe
corps du
produit
>, qui contient les fonctions et plug-ins développées pour le produit. A titre
indicatif, la structure de ce répertoire se présente comme suit :
<corps du produit>/
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
La quatrième entrée du script de création du programme d'installation est un répertoire,
<plate-forme
>, qui contient les fonctions et plug-ins de la plate-forme Eclipse ainsi que tous
les outils de société tierce inclus dans le produit.
Ce répertoire contient également le programme standard de lancement de l'exécutable Eclipse, eclipse.exe
,
(nommé eclipse
en environnement Unix), son compagnon startup.jar
ainsi que tous les autres
fichiers de plate-forme Eclipse à placer à la racine de l'installation. A titre
indicatif, la structure de ce répertoire se présente comme suit :
<plateforme>
Le contenu exact des répertoires d'entrée <
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/
(autres répertoires de plug-in org.eclipse.*)
JRE
>, <en-tête
produit
>, <corps produit
> et <plateforme
> détermine les
fichiers éventuellement installés sur l'ordinateur de l'utilisateur final.
Les dernières entrées du script de création du programme d'installation sont les chaînes d'ID et de version de la
fonction de base du produit (par exemple, "com.example.acme.acmefeature"
et
"1.0.0
") ainsi que le nom de l'exécutable du produit (par exemple,
"acmeproduct
.exe
").
Pour les produits qui n'ont pas besoin de leur propre exécutable, i peut s'agir du chemin d'accès du programme standard
de lancement de l'exécutable Eclipse "eclipse/eclipse.exe
".
Ces chaînes, qui ont une signification particulière pour le programme d'installation, apparaissent dans les noms de
fichiers et de répertoires et dans les fichiers de marqueurs créés au moment de l'installation.
Au moment de l'installation, le programme d'installation doit se comporter de la manière standard (plus de détails en fin de liste des étapes), à savoir :
Si l'emplacement indiqué à l'étape 5 est <install
>, le programme d'installation copie
tous les fichiers des répertoires <JRE
>, <plateforme>,
<produit
>, et <plug-ins du produit>
dans
<install
>.
Fichier d'entrée | Fichier installé |
<JRE>/* |
<install>/eclipse/* |
<en-tête produit>/* |
<install>/* |
<corps du produit>/* |
<install>/* |
<plateforme>/* |
<install>/* |
Le fichier de marqueurs créé à l'étape 8 se nomme
<install>/eclipse/.eclipseproduct
;
il est utilisé pour marquer un répertoire dans lequel un produit basé sur Eclipse a été installé, de sorte
que les programmes d'installation d'extension puissent le localiser facilement. Ce fichier de marqueurs au format
java.io.Properties (codage ISO 8859-1 avec
"\" comme caractère d'échappement) contient les informations suivantes qui permettent d'identifier le produit
auprès de l'utilisateur et de différencier un produit Eclipse d'un autre :
name=Acme Visual Tools Pro
id=com.example.acme.acmefeature
version=1.0.0
Les valeurs des propriétés "id" et "version" sont des entrées du script de création du programme d'installation ; le nom du produit est présumé connu et imposé. (En général, les produits n'accèdent pas à ce fichier de marqueurs, seuls les programmes d'installation de produit et d'extension y écrivent ou le lisent.)
L'étape 6 requiert de vérifier la présence d'un fichier
<install>/eclipse/.eclipseproduct
ou
<install>/eclipse/.eclipseextension
. Un produit ne peut pas être installé exactement au même
endroit qu'un autre produit ou extension.
Une fois tous les fichiers installés, la structure de niveau supérieur du répertoire d'installation doit contenir les fichiers et sous-répertoires suivants (et éventuellement d'autres) :
<install>/
Si un programme d'installation de produit demande à l'utilisateur de fournir des informations sur la licence,
telles que le nom du propriétaire enregistré ou la clé de licence, ces informations doivent figurer dans la boîte de
dialogue "a propos de" du produit (étape 10).
acmeproduct.exe
eclipse/
.eclipseproduct
eclipse.exe
startup.jar
features/
plugins/
jre/
Pour ce faire, il faut enregistrer les réponses de l'utilisateur dans le fichier
"about.mapping
" du plug-in de la fonction principale. Par exemple, dans
<install>/plugins/com.example.acme.acmefeature_1.0.0/about.mapping
.
La fichier "about.mapping
" doit déjà figurer dans l'entrée <en-tête
produit
> ou être créé par le programme d'installation au moment de l'installation.
Les clés sont des numéros, la valeur de la clé "n" remplaçant la sous-chaîne
"{n}
" dans la propriété "aboutText
".
Par exemple, si une clé de licence figure dans la zone numéro 0, un fichier "about.mapping
"
contenant une ligne du type "0=T42-24T-ME4U-U4ME
" doit être créé.
REMARQUE :
Le fichier "about.mapping
" est au format
java.io.Properties (codage ISO 8859-1 avec
"\" comme caractère d'échappement).
Au moment de l'installation, si le codage natif n'est pas ISO 8859-1, le programme d'installation est chargé de
convertir le codage natif en format Unicode et d'ajouter les caractères d'échappement "\" requis. Un caractère
d'échappement est nécessaire lorsque les chaînes contiennent des caractères spéciaux (tels que "\") ou des
caractères n'appartenant pas à l'alphabet latin. Ainsi la zone numéro 1, qui contient les trois premières lettres de
l'alphabet grec, doit s'écrire "1=\u03B1\u03B2\u03B3
".
A l'étape 12, le programme d'installation du produit lance l'exécutable du
produit, <install>/acmeproduct.exe
, avec l'option spéciale -initialize [détails
exacts à définir]. La plate-forme Eclipse effectue alors en silence tous les traitements longs et place les résultats
dans le cache ; ainsi, à son démarrage, le produit apparaît rapidement et est immédiatement opérationnel.
Au moment de la désinstallation, le programme de désinstallation doit se comporter de manière standard, à savoir :
install
>, ainsi que tous les fichiers des répertoires <install
>/eclipse/features
et <install
>/eclipse/plugins
, y compris ceux placés dans ces répertoires par
d'autres instances que ce programme d'installation (par ex., le gestionnaire des mises à jour Eclipse)Lorsque le produit est désinstallé, tous les fichiers déposés lors de l'installation doivent être supprimés, de même
que les mises à jour de fonctions et de plug-ins initiées par le gestionnaires des mises à jour Eclipse. Important : Au moment de la désinstallation, il est possible que le répertoire
<install>
contienne d'autres répertoires et fichiers, notamment
<install>/eclipse/workspace/
, <install>/eclipse/links/
et
<install>/eclipse/configuration/
, qui contiennent des données importantes devant être conservées
à la désinstallation du produit. L'utilisateur doit pouvoir désinstaller et réinstaller un produit au même endroit sans
perdre de données importantes.
Lorsque le produit est déjà installé sur l'ordinateur de l'utilisateur, le programme d'installation doit offrir une possibilité de mise à jour ou de passage à une version plus récente du produit.
Au moment de l'installation, le programme d'installation doit se comporter de la manière standard, à savoir :
A l'étape 2, un produit installé est décelable par la présence d'un répertoire "eclipse
"
contenant un fichier ".eclipseproduct
".
Le parent du répertoire "eclipse
" est un répertoire d'installation de produit, tel que
<install>/eclipse/.eclipseproduct
.
Les informations de ce fichier de marqueurs doivent être présentées à l'utilisateur pour qu'il confirme que la mise à
jour s'applique bien au produit approprié (l'ordinateur de l'utilisateur peut effet abriter plusieurs produits Eclipse).
Le programme d'installation doit effectuer des vérifications de compatibilité à l'étape 3 par mise en
correspondance de modèle avec des sous-répertoires du répertoire <install>/eclipse/features
. Ainsi la présence d'un dossier correspondant à
"com.example.acme.otherfeature_1.0.1
" prouve que le produit installé a fait l'objet
d'une mise à jour.
Pour l'étape 7, le programme d'installation doit supprimer ou remplacer tous les fichiers installés à l'origine, et en ajouter d'autres. Important
: Plusieurs fichiers et répertoires, y compris
<install>/eclipse/workspace/
, <install>/eclipse/configuration
,
peuvent être installés au même endroit et contiennent des fichiers de données importantes qui doivent être conservés
lors de la mise à niveau du produit.
En cas de mise à niveau, il est fort probable que la plupart des fichiers enregistrés sous
<install>/eclipse/plugins/
soient les mêmes (de même que pour
<install>/eclipse/features/
).
<install>/eclipse/plugins/
offre une grande opportunité d'optimisation
car le nom du sous-répertoire, dans lequel est incorporé le numéro de version du plug-in (ou fragment),
change si et seulement si l'un des fichiers qu'il contient change. En d'autres termes, il n'est pas
nécessaire de modifier des fichiers du sous-répertoire<install>/eclipse/plugins/org.eclipse.ui_2.0.0
/ si ce sous-répertoire doit être conservé à l'issue de la mise à niveau. Si l'un des fichiers de plug-in est modifié, le numéro de version du
plug-in est révisé, de sorte que les fichiers du plug-in mis à niveau soient installé dans un répertoire parallèle
<install>/eclipse/plugins/org.eclipse.ui_2.0.1
/.
Le JRE doit normalement se trouver dans <install>/eclipse/jre/bin/javaw.exe
.
S'il se trouve ailleurs, son chemin absolu doit être indiqué à l'aide de l'option -vm
entrée sur la ligne de commande. Par exemple, -vm C:\j2jre1.3.0\jre\bin\javaw.exe
.
Auquel cas, le programme d'installation doit ajouter cette option dans la ligne de commande du raccourci bureau qu'il
crée.
Le terme "extension" désigne une série de dispositifs installables séparément ainsi que leurs plug-ins pouvant être associés à, et utilisés depuis, un ou plusieurs produits basés sur Eclipse installés sur le même ordinateur. Contrairement à un produit, une extension n'est pas une entité indépendante ; elle ne contient pas d'exécutable de produit, la plate-forme Eclipse, un JRE.
Disons pour simplifier qu'une extension se compose d'un seul dispositif. La première entrée du script de création du
programme d'installation est le répertoire <extension
>, qui contient les fonctions et plug-ins
de l'extension. Nous partons du principe qu'une extension n'a aucun fichiers liés à Eclipse. Dans le cas contraire, ils
vont dans <extension>/
, et non dans <extension>/eclipse/
. A titre
indicatif, la structure de ce répertoire se présente comme suit :
<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/
Le contenu exact du répertoire d'entrée <extension
> détermine les fichiers éventuellement
installés sur l'ordinateur de l'utilisateur final.
Les dernières entrées du script de création du programme d'installation sont les chaînes d'ID et de version du
dispositif de l'extension (par exemple, "com.example.wiley.anvil
" et
"1.0.0
"). Ces chaînes, qui ont une signification particulière pour le programme d'installation, apparaissent dans les noms de
fichiers et de répertoires et dans les fichiers de marqueurs créés au moment de l'installation.
Un programme d'installation d'extension et un programme d'installation de produit ont de nombreux points communs. Les points divergents sont signalés ci-dessous :
Au moment de l'installation, le programme d'installation comporte de la manière standard, à savoir :
Si l'emplacement indiqué à l'étape 5 est <install
>, le programme d'installation copie
tous les fichiers du répertoire <extension>
dans <install
> à
l'étape 11.
Fichier d'entrée | Fichier installé |
<extension>/* |
<install>/* |
Pour l'étape 7, tout produit Eclipse convient. Un produit Eclipse se distingue par la présence d'un fichier
<product install>/eclipse/.eclipseproduct
. L'utilisateur doit pouvoir demander une recherche
limitée sur disque des produits installés (avec un bouton de "recherche des produits installés"), ou naviguer
jusqu'à un répertoire contenant un produit (par ex., avec un bouton "parcourir").
Le programme d'installation doit effectuer des vérifications de compatibilité à l'étape 8 par mise en
correspondance de modèle avec des sous-répertoires du répertoire <product
install>/eclipse/features
. Ainsi la présence d'un dossier correspondant à
"org.eclipse.jdt_2.*
" signifie que le JDT est inclus dans le produit installé.
Le fichier de marqueurs créé à l'étape 10 se nomme
<install>/eclipse/.eclipseextension
;
il est utilisé pour marquer un répertoire dans lequel une extension basée sur Eclipse a été installée, de sorte que les
programmes d'installation d'extension puisse le localise facilement (semblable au fichier de marqueurs
.eclipseproduct
d'un produit). Ce fichier de marqueurs au format
java.io.Properties (codage ISO 8859-1 avec
"\" comme caractère d'échappement) contient les informations suivantes qui permettent d'identifier l'extension
auprès de l'utilisateur et de différencier une extension Eclipse d'une autre :
name=Wiley Anvil Enterprise Edition
id=com.example.wiley.anvilfeature
version=1.0.0
Les valeurs des propriétés "id" et "version" sont des entrées du script de création du programme d'installation ; le nom de l'extension est présumé connu et imposé. (En général, les produits n'accèdent pas à ce fichier de marqueurs, seuls les programmes d'installation de produit et d'extension y écrivent ou le lisent.)
Une fois tous les fichiers installés, la structure de niveau supérieur du répertoire d'installation doit contenir les fichiers et sous-répertoires suivants :
<install>/
eclipse/
.eclipseextension
features/
plugins/
La seule différence notoire par rapport à un programme d'installation de produit tient au fait qu'un programme d'installation d'extension crée aussi des fichiers de liens dans d'autres produits Eclipse déjà installés sur l'ordinateur de l'utilisateur. (Ainsi, l'utilisateur n'a pas à associer manuellement la nouvelle extension à partir de chaque produit à l'aide du gestionnaire de mises à jour Eclipse.)
Le fichier de liens créé à l'étape 14 est <product
install>/eclipse/links/com.example.wiley.anvilfeature.link
; il porte donc le même nom que le
répertoire du dispositif de l'extension moins le suffixe correspondant au numéro de version. Un fichier de liens est au
format java.io.Properties (codage ISO
8859-1 avec "\" comme caractère d'échappement).
La clé est "path" et la valeur le chemin absolu de l'extension installée, <install>
.
Une entrée peut, par exemple, se présenter ainsi : "path=C:\\Program
Files\\Wiley\\Anvil
".
Le programme d'installation est chargé de convertir le codage natif en
format Unicode et d'ajouter les caractères d'échappement "\" requis. Les caractère d'échappement sont
généralement requis car <install>
contient souvent des caractères spéciaux (tels que
"\") et peut désigner des répertoires dont le nom contient des caractères non latins. Le produit lit les
fichiers de liens lorsqu'il démarre. Le programme d'installation conserve un enregistrement de tous les fichiers de
liens qu'il crée de façon à pouvoir les localiser lors de la mise à jour ou de la désinstallation de l'extension.
Au moment de la désinstallation, le programme de désinstallation doit se comporter de la manière standard, à savoir :
install
>, ainsi que tous les fichiers des répertoires <install
>/eclipse/features
et <install
>/eclipse/plugins
, y compris ceux placés dans ces répertoires par
d'autres instances que ce programme d'installation (par ex., le gestionnaire des mises à jour Eclipse)A la désinstallation d'une extension, tous les fichiers de plug-in et de dispositif doivent être supprimés ; ils ne contiennent aucune données importantes à conserver. L'utilisateur peut ainsi désinstaller totalement une extension, y compris les mises à jour effectuées par le gestionnaire de mises à jour Eclipse.
Lorsque l'extension est déjà installée sur l'ordinateur de l'utilisateur, le programme d'installation doit offrir une possibilité de mise à jour ou de passage à une version plus récente de l'extension.
Au moment de l'installation, le programme d'installation doit se comporter de la manière standard, à savoir :
A l'étape 2, une extension installée est décelable par la présence d'un répertoire
"eclipse
" contenant un fichier ".eclipseextension
".
Le parent du répertoire "eclipse
" est un répertoire d'installation d'extension, tel que
<install>/eclipse/.eclipseextension
.
Les informations de ce fichier de marqueurs doivent être présentées à l'utilisateur pour qu'il confirme que la mise à
jour s'applique bien à l'extension appropriée (l'ordinateur de l'utilisateur peut effet abriter plusieurs extensions
Eclipse).
A l'étape 7, le programme d'installation ne doit supprimer ni écraser aucun des fichiers installés à
l'origine ; il doit uniquement ajouter les fichiers des nouvelles versions des dispositifs et de plug-in, et si
possible réécrire le fichier de marqueurs <install>/eclipse/.eclipseextension
. Conserver les
anciennes versions offre à l'utilisateur la possibilité d'annuler la mise à jour. Comme pour la mise à niveau d'une
installation de produit, il n'est pas nécessaire de modifier des fichiers du sous-répertoire
<install>/eclipse/plugins/com.example.wiley.otherplugin_1.0.0
/ si ce
sous-répertoire doit être conservé à l'issue de la mise à niveau. Si l'un des fichiers de plug-in est modifié, le numéro
de version du plug-in est révisé, de sorte que les fichiers du plug-in mis à niveau soient installé dans un répertoire
parallèle <install>/eclipse/plugins/com.example.wiley.otherplugin_1.0.1
/.