Plateforme Eclipse
Installation et mise à jour

Date de révision : 14/06/01 10:45 - Version : 0.12

 
Remarque : Le gestionnaire de mise à jour est toujours en cours de développement et il faut s'attendre à ce qu'il soit modifié d'ici son achèvement. Il est diffusé à ce stade pour solliciter les commentaires des premiers utilisateurs, tout en signalant que les détails de la structure d'installation peuvent considérablement changer d'ici là.

Introduction
Scénarios
Conventions de mise en forme
       Concepts
       Archive de composant
       Archive de configuration
       Traduction des informations de mise en forme
       Considérations relatives à la sécurité
       Mise en forme NL
       Mise en forme de support propre à la cible
      Remises de support de mise en forme
Structure d'installation
       Installation complète et installation de référence
       Mappage de système de fichiers : Installation complète
       Fichiers de l'espace de travail
       Mappage de système de fichiers : Installation de référence
Lancement d'Eclipse
Considérations relatives à la mise à jour
       Mise à jour de composants ne faisant pas partie de la plateforme
       Mise à jour de la plateforme
       Mise à jour de l'environnement JRE
       Mise à jour des fichiers produit
       Mise à jour du support de lancement
       Reprise suite aux défaillances de mise à jour
       Reprise suite à des mises à jour erronées
       Nettoyage de l'installation
       Fonction non gérée d'Eclipse
Considérations relatives à l'installation
       Nouvelle installation
       Installation fusionnée
       Enregistrement spécifique à la plateforme
Considérations relatives au développement
       Indépendance de l'emplacement d'installation
       Exécutables natifs
       Support de versions de plug-in concurrentes
       Migration de version

Introduction

Le présent document décrit le support de gestion de livraison des fonctions dans la plateforme Eclipse.

Scénarios

La plateforme Eclipse comporte un gestionnaire de mise à jour intégré, utilisé comme élément de l'installation d'une fonction basée sur Eclipse, et pour fournir des mises à jour de services et des mises à niveau de fonctions. Les scénarios suivants sont supportés dans la version initiale d'Eclipse :

Conventions de mise en forme

Concepts

Plug-in
Les développeurs d'Eclipse génèrent des plug-ins. Ceux-ci constituent les unités d'exécution de base reconnues par l'environnement d'exécution d'Eclipse. En règle générale, les plug-ins ne sont pas exposés aux utilisateurs qui sélectionnent la fonction pendant l'installation ou la mise à jour. Les raisons à cela sont que les limites du plug-in sont établies par les développeurs à des fins de développement (réutilisation d'une fonction, par exemple) et présentent un niveau de granularité erroné en termes de ce que l'utilisateur voit de l'unité de fonction.

Lorsque les plug-ins sont développés (c'est-à-dire fréquemment modifiés), leur structure de fichier interne reflète ce qui arrange le développeur. Ceci dépend généralement de l'outil de développement utilisé. Cependant, en général, le développeur configure le plug-in pour qu'il s'exécute à partir d'une arborescence de répertoires contenant les fichiers .class exposés, plutôt qu'à partir d'un fichier .jar (une étape supplémentaire est requise pour créer le fichier .jar et nous savons tous que les développeurs détestent les étapes supplémentaires). A ce stade, le développeur accorde également une attention toute particulière aux informations relatives à la vérification des versions du plug-in, car il change constamment.

Toutefois, lorsque le plug-in est prêt à être mis en forme, il doit être converti dans un format approprié à la mise en forme et à l'installation. Cela signifie généralement la création du ou des fichier(s) .jar d'exécution et la suppression des fichiers propres au développement (fichiers source, fichiers .class exposés, etc). Cela signifie également la mise à jour du manifeste plugin.xml avec la version formelle du plug-in et le reflet de la version dans le nom du répertoire du plug-in (pour plus de détails, reportez-vous à la section "Support de version de plug-in concurrente").

Fragment de plug-in
Les fragments de plug-in (ou simplement fragments) permettent une mise en forme indépendante de certains aspects du plug-in de base. Ceci inclut (mais ne s'y limite pas) des ressources traduites pour le plug-in, du code propre à l'environnement d'exploitation ou au système de fenêtrage ou encore le contenu d'un plug-in destiné à d'autres utilisateurs (c'est-à-dire, des informations d'un programme de développement SDK fournies dans un plug-in). Au moment de l'exécution, les fragments sont logiquement fusionnés dans le plug-in de base. Du point de vue de la mise en forme, ils peuvent être mis en forme physiquement avec le plug-in de base ou mis en forme et traités séparément. Ceci permet, par exemple, la création d'un "pack de langue" ou d'un "pack de système d'exploitation" spécifique indépendant de la distribution de la fonction de base.

Composant
Un composant est généralement un groupe de plug-ins et/ou de fragments de plug-in qui fournit des fonctions utilisateur. Les composants peuvent être exposés aux utilisateurs en tant qu'élément du processus de mise en forme et d'installation du fait qu'ils représentent une unité de la sélection de fonction. Ils représentent également une unité d'installation (tous les fichiers contenus sont installés ensemble dans une arborescence d'installation) et portent un identificateur de version.

Les composants sont mis en forme en tant que fichier .jar Java, contenant les plug-ins requis, les fragments de plug-in et un manifeste d'installation de composant (un fichier xml). Les fichiers .jar de composant peuvent être placés sur un serveur de mise à jour à des fins de téléchargement et d'installation par le gestionnaire de mise à jour Eclipse ou être utilisés comme sortie dans un processus de mise en forme formel utilisant l'une des technologies d'installation classiques. Le format du fichier jar et de son manifeste d'installation sont décrits ultérieurement.

Configuration
Une configuration est un mécanisme de regroupement versionné pour un jeu de composants versionnés. Il peut, par exemple, être utilisé pour spécifier la configuration de composants, générée et testée comme version spécifique d'un produit.

Les configurations sont mises en forme en tant que fichier .jar Java, contenant le manifeste d'installation de la configuration (un fichier xml). Le manifeste contient les références aux composants qui constituent la configuration, avec les contraintes d'installation et de mise à jour de version. Notez que le fichier .jar de configuration ne contient pas réellement les fichiers composants (mais uniquement des références).

Les fichiers .jar de configuration peuvent être placés sur un serveur de mise à jour à des fins de téléchargement et d'installation par le gestionnaire de mise à jour Eclipse ou être utilisés comme sortie dans un processus de mise en forme formel utilisant l'une des technologies d'installation classiques. Le format du fichier jar de configuration et de son manifeste d'installation sont décrits ultérieurement.

L'implémentation courante d'Eclipse ne permet pas aux configurations d'être imbriquées.

Archive de composant (.jar)

Par convention, les composants sont identifiés à l'aide d'un identificateur structuré, fondé sur le nom du domaine Internet du fournisseur. Par exemple, l'organisation eclipse.org peut produire le composant org.eclipse.platform. L'identificateur de composant est utilisé comme partie du nom du fichier .jar, ainsi que comme nom du répertoire de composants dans la structure .jar (et de ce fait l'arborescence d'installation). Comme plusieurs versions d'un composant donné peuvent être installées simultanément, le nom du fichier .jar, ainsi que le nom de son répertoire encodent également l'identificateur de version. Ce dernier respecte le format défini par Eclipse pour les identificateurs de version de plug-in (reportez-vous au Javadoc pour la classe PluginVersionIdentifier). Il s'agit d'un identificateur numérique en trois parties, constitué de composants majeur, mineur et de service (par exemple,2.4.11).

Le nom est de la forme suivante :
<componentId>_<version>

Par exemple,
org.eclipse.platform_1.0.3.jar
com.ibm.tools.jspeditor_3.1.0\install.xml

La structure du chemin d'accès interne du jar est la suivante :

install/
    components/
        <componentId>_<version>/
            install.xml
            (other optional files)see "Translating Packaging Information"
    plugins/
        <pluginId>_<pluginVersion>/
            plugin.xml
            (other plug-in files)
    fragments/
        <fragmentId>_<fragmentVersion>/
            fragment.xml
            (other fragment files, may also include plugin.xml)

Le fichier .jar contient exactement un chemin d'accès install/components/ avec exactement un fichier install.xml. Il contient aucun ou plusieurs plug-ins dans leurs répertoires relatifs (avec un qualifiant de version). Il contient aucun ou plusieurs fragments de plug-in dans leurs répertoires relatifs (avec un qualifiant de version). Il contient également le répertoire meta-inf/ produit par les utilitaires jar Java.

Le format du composant install.xml est défini par la DTD suivante :

<?xml encoding="US-ASCII"?>

<!ELEMENT component (description?, url?, plugin*, fragment*)>
<!ATTLIST component
    label CDATA #IMPLIED
    id CDATA #REQUIRED
    version CDATA #REQUIRED
    provider-name CDATA #IMPLIED
>

<!ELEMENT description (#PCDATA)>

<!ELEMENT url (update*, discovery*)>

<!ELEMENT update EMPTY>
<!ATTLIST update
    url CDATA #REQUIRED
    label CDATA #IMPLIED
>

<!ELEMENT discovery EMPTY>
<!ATTLIST discovery
    url CDATA #REQUIRED
    label CDATA #IMPLIED
>

<!ELEMENT plugin EMPTY>
<!ATTLIST plugin
    label CDATA #IMPLIED
    id CDATA #REQUIRED
    version CDATA #REQUIRED
>

<!ELEMENT fragment EMPTY>
<!ATTLIST fragment
    label CDATA #IMPLIED
    id CDATA #REQUIRED
    version CDATA #REQUIRED
>

Les définitions d'élément et d'attribut sont les suivantes :

Archive de configuration (.jar)

Par convention, les configurations sont identifiées à l'aide d'un identificateur structuré, fondé sur le nom du domaine Internet du fournisseur. Par exemple, l'organisation eclipse.org peut produire la configuration org.eclipse.sdk. L'identificateur de configuration est utilisé comme partie du nom du fichier de configuration .jar, ainsi que comme nom du répertoire de la configuration dans la structure .jar (et de ce fait l'arborescence d'installation). Comme plusieurs versions d'une configuration donnée peuvent être installées simultanément, le nom du fichier de configuration .jar, ainsi que le nom de son répertoire encodent également l'identificateur de version. Ce dernier respecte le format défini par Eclipse pour les identificateurs de version de plug-in (reportez-vous au Javadoc pour la classe PluginVersionIdentifier). Il s'agit d'un identificateur numérique en trois parties, constitué de composants majeur, mineur et de service (par exemple,2.4.11).

Le nom est de la forme suivante :
<configurationId>_<version>

Par exemple,
org.eclipse.sdk_1.1.5.jar
com.ibm.wsa_1.0.1\install.xml

La structure du chemin d'accès interne du jar de configuration est la suivante :

install/
    configurations/
        <configurationId>_<version>/
            install.xml
            (other optional files)see "Translating Packaging Information"
            ("product" files)see "Launching Eclipse"

Le fichier .jar contient exactement un chemin d'accès install/configurations/ avec exactement un fichier install.xml. Il contient également le répertoire meta-inf/ produit par les utilitaires jar Java.

Le format de configuration install.xml est défini par la DTD suivante :

<?xml encoding="US-ASCII"?>

<!ELEMENT configuration (description?, url?, component*)>
<!ATTLIST configuration
    label CDATA #IMPLIED
    id CDATA #REQUIRED
    version CDATA #REQUIRED
    provider-name CDATA #IMPLIED
    application CDATA #IMPLIED
>

<!ELEMENT description (#PCDATA)>

<!ELEMENT url (update*, discovery*)>

<!ELEMENT update EMPTY>
<!ATTLIST update
    url CDATA #REQUIRED
    label CDATA #IMPLIED
>

<!ELEMENT discovery EMPTY>
<!ATTLIST discovery
    url CDATA #REQUIRED
    label CDATA #IMPLIED
>

<!ELEMENT component EMPTY>
<!ATTLIST component
    label CDATA #IMPLIED
    id CDATA #REQUIRED
    version CDATA #REQUIRED
    allowUpgrade (true | false) "false"
    optional (true | false) "false"
>

Les définitions d'élément et d'attribut sont les suivantes :

L'implémentation courante d'Eclipse ne permet pas aux configurations d'être imbriquées ou à des règles de composant plus complexes d'être spécifiées.

Traduction des informations de mise en forme

Plusieurs des attributs contenus dans les manifestes d'installation sont des chaînes destinées à l'affichage via des interfaces utilisateur. Pour faciliter la traduction, ces valeurs d'attribut utilisent la convention définie pour les attributs traduisibles du fichier plugin.xml. Les chaînes commençant par % jusqu'au premier espace sont considérées comme des clés d'identificateur de ressource (sans le caractère %) et recherchées dans un fichier de propriétés. Par exemple

label="%cfg Eclipse SDK for Linux"

résulte en une recherche de ressource dans le fichier de propriétés approprié avec la clé "cfg". Si aucun fichier de propriétés n'est fourni ou si la clé n'est pas trouvée, la valeur de la chaîne par défaut (suivant la clé %) est utilisée.

Les fichiers de propriétés sont nommés install_<locale>.properties, suivant les conventions de dénomination du fichier de regroupement de ressources Java. Dans le jar de composant et de configuration, ces fichiers sont placés dans le même répertoire que leur fichier install.xml correspondant.

Lors de l'accès aux regroupements de ressources, le code peut sélectionner la variante NL appropriée du manifeste (en implémentant un algorithme de recherche), puis créer un regroupement à l'aide de

ResourceBundle b;
b = new PropertyResourceBundle(properties.openStream());

Ou bien, le code peut utiliser le support de base Java pour localiser la variante NL appropriée du manifeste comme suit :

ResourceBundle b;
ClassLoader l;
l = new URLClassLoader(new URL[] {<targetDirectoryURL>}, null);
b = ResourceBundle.getBundle("install",Locale.getDefault(),l);

Le regroupement de ressources résultant peut être utilisé dans IPluginDescriptor.getResourceString(String,ResourceBundle) pour retourner réellement la chaîne correcte traduite pour l'attribut du manifeste.

Considérations relatives à la sécurité

Les fichiers .jar de composant et de configuration peuvent être signés à l'aide des utilitaires de sécurité Java standard (jarsigner, par exemple). Au moment de l'exécution, le gestionnaire de mise à jour vérifie pour voir si le jar demandé est fourni par un fournisseur digne de confiance, et si le contenu du jar n'a pas été modifié depuis qu'il a été signé. L'utilisateur a l'option d'accepter les jar non sécurisés. Les jar modifiés après avoir été signés sont rejetés par l'environnement d'exécution Eclipse.

Mise en forme NL

Les fichiers NL sont mis en forme dans des sous-répertoires distincts pour chaque environnement supporté. Les sous-répertoires peuvent être définis dans le répertoire de plug-in réel (c'est-à-dire, défini "en ligne" avec le plug-in) ou ils peuvent être mis en forme dans des fragments de plug-in distincts. Dans l'un ou l'autre cas, l'environnement d'exécution d'Eclipse fournit des services permettant d'associer le répertoire de plug-in de base et les fichiers locaux appropriés en une seule structure d'accès logique (cependant, ils peuvent être physiquement mis en forme).

La mise en forme des fichiers NL en tant que fragments de plug-in résulte en une structure d'installation légèrement plus complexe. Le principal avantage est le fait que le contenu NL puisse être ajouté à la base ultérieurement (autrement dit, qu'il n'a pas à être fourni en même temps). Cela permet également aux fragments d'évoluer indépendamment de la base (par rapport aux mises à jour de service).

Le code ci-dessous correspond aux autres structures d'installation résultantes pour la mise en forme NL.

Mise en forme NL "en ligne" avec plug-in

install/
    plugins/
        <pluginId>_<version>/
            ("plug-in" files)
            nl/
                <locale>/
                    (NL files)

Par exemple :

install/
    plugins/
        my.funky.plugin_1.0.1/
            plugin.xml
            my.jar ... contains classes and default resources
            nl/
                fr_FR/
                    my.jar ... contains the translated delta

Mise en forme NL en tant que fragment de plug-in

install/
    fragments/
        <fragmentId>_<version>/
            fragment.xml
            nl/
                <locale>/
                    (NL files)

Par exemple :

install/
    fragments/
        my.funky.plugin_french_1.0.1/
            fragment.xml
                nl/
                    fr_FR/
                        my.jar ... contains the translated delta

Les noms du répertoire de l'environnement local suivent les conventions de dénomination des paramètres régionaux Java standard.

Notez qu'en général, le contenu du plug-in de base doit toujours inclure les ressources NL par défaut de sorte que la fonction se comporte de manière raisonnable en l'absence de l'arborescence de l'environnement local approprié. Ainsi, il est préférable de montrer une chaîne par défaut que des ID ressource dans une interface utilisateur.

Les mécanismes d'exécution, format de fragment.xml et API de gestion des répertoires et des fragments, sont décrits dans une autre partie de la documentation de la plateforme Eclipse.

Mise en forme de support propre à la cible

Les fichiers dus système d'exploitation et spécifiques au système de fenêtrage sont mis en forme dans des sous-répertoires distincts pour chaque environnement supporté. Les sous-répertoires peuvent être définis dans le répertoire de plug-in réel (c'est-à-dire, défini "en ligne" avec le plug-in) ou ils peuvent être mis en forme dans des fragments de plug-in distincts. Dans l'un ou l'autre cas, l'environnement d'exécution d'Eclipse fournit des services permettant d'associer le répertoire de plug-in de base et les fichiers appropriés propres à la cible en une seule structure d'accès logique (cependant, ils peuvent être physiquement mis en forme).

La mise en forme des fichiers propres à la cible en tant que fragments de plug-in résulte en une structure d'installation légèrement plus complexe. Le principal avantage est le fait que le support propre à la cible puisse être ajouté à la base ultérieurement(autrement dit, qu'il n'a pas à être fourni en même temps). Cela permet également aux fragments d'évoluer indépendamment de la base (par rapport aux mises à jour de service).

Le code ci-dessous correspond aux autres structures d'installation résultantes pour la mise en forme des fichiers propres à la cible.

Mise en forme "en ligne" avec plug-in du support propre à la cible

install/
    plugins/
        <pluginId>_<version>/
            ("plug-in" files)
            os/
                <os-name>/
                    (OS-specific files)
            ws/
                <windowing-system-name>/
                    (WS-specific files)

Par exemple :

install/
    plugins/
        my.funky.plugin_1.0.1/
            plugin.xml
            my.jar
            os/
                solaris/
                    libfoo.so
            ws/
                motif/
                    my.jar

Mise en forme du support propre à la cible en tant que fragment de plug-in

install/
    fragments/
        <fragmentId>_<version>/
            fragment.xml
            os/
                <os-name>/
                    (OS-specific files)
            ws/
                <windowing-system-name>/
                    (WS-specific files)

Par exemple :

install/
    fragments/
        my.funky.plugin_solaris_1.0.1/
            fragment.xml
            os/
                solaris/
                    libfoo.so
            ws/
                motif/
                    my.jar

Les identificateurs cibles utilisés pour les noms de répertoire sont définis par Eclipse (reportez-vous au Javadoc pour org.eclipse.core.boot.BootLoader).

Les mécanismes d'exécution, format de fragment.xml et API de gestion des répertoires propres à la cible et des fragments, sont décrits dans une autre partie de la documentation de la plateforme Eclipse.

Remises de support de mise en forme

Des fichiers de support supplémentaires peuvent être mis en forme directement dans les répertoires de plug-in ou comme fragments. Il peut s'agir de modèles, d'exemples, de documentation de référence, de scénarios de test ou d'autres informations qui ne fournissent pas directement la fonction utilisateur de base. En général, la plateforme ne spécifie pas l'emplacement et l'utilisation de ces fichiers. Cependant, une fois mis en forme en tant que fragments, la plateforme fournit le support pour accéder à l'espace combiné plug-in/fragment en tant qu'arborescence logique unique. Ce permet au plug-in de base de contenir uniquement le support utilisateur principal et de fournir les informations supplémentaires uniquement lorsque les fragments nécessaires sont également présents.

Structure d'installation

Installation complète et installation de référence

Eclipse supporte deux types d'installation :
  1. Installation complète. Il s'agit de la structure du système de fichiers résultant, une fois la procédure d'installation exécutée. Les fichiers figurent dans le système de fichiers conformément à la manière requise par la plateforme Eclipse pour une exécution directe. La fonction Eclipse ne peut être exécutée directement qu'à partir d'une installation complète.
  2. Installation de référence. Il s'agit de la structure de fichiers qui existe dans un emplacement de mise à jour Eclipse, utilisé pour sélectionner des composants et des configurations installables.

Mappage de système de fichiers : Installation complète

Une installation complète est définie comme la sortie du processus d'installation, qu'il soit le résultat d'une installation classique ou celui d'une action du gestionnaire de mise à jour. La plateforme Eclipse peut s'exécuter directement à partir d'une installation complète.

Une installation complète d'Eclipse comporte la structure de fichiers suivante :

<installation root>/
    install/
        install.properties
        components/
            <componentId>_<version>/
                install.xml
                install_<locale>.properties (optional)
        configurations/
            <configurationId>_<version>/
                install.xml
                install_<locale>.properties (optional)
                (other "product" files) (optional)

    plugins/
        <pluginId>_<version>/
            plugin.xml
            (other plug-in files)
    fragments/
        <fragmentId>_<fragmentVersion>/
            fragment.xml
            (other fragment files, may also include plugin.xml)

La définition des répertoires et des fichiers est conforme à ce qui a été spécifié précédemment pour les jars de composant et de configuration.

Le fichier install.properties contient des propriétés de lancement configurables. Il est le reflet de la configuration de lancement courante de la plateforme et de l'application installée. Son utilisation exacte est décrite à la section "Lancement d'Eclipse". Ce fichier est initialement installé comme élément de la nouvelle installation. Il est de ce fait mis à jour uniquement par le gestionnaire de mise à jour, chaque fois que l'installation d'Eclipse est modifiée. Si le fichier est mis à jour par un tout autre moyen, de manière incompatible avec l'installation d'origine, le dernier état valide est restauré.

Le fichier est de la forme d'un fichier de propriétés Java et contient les éléments suivants :

application=<applicationId>
application.configuration=<configurationId>_<version>
runtime=<pluginId>_<version>

Par exemple

application=
application.configuration=com.ibm.wsa_1.0.3
runtime=org.eclipse.core.boot_1.1.4

Les définitions de propriété sont les suivantes :

Le fichier installation.properties est créé par le programme d'installation initial. Une fois installé, les propriétés d'application et d'exécution peuvent être mises à jour. Seul le suffixe de version de application.configuration peut être mis à jour (mais pas l'identificateur de configuration "dominant").

Remarque : Comme spécifié dans cette section, l'installation initiale d'un produit basé sur Eclipse doit également installer le fichier install.properties qui reflète les paramètres de démarrage initiaux corrects. Si ce fichier n'est pas installé, il en résulte une incapacité à lancer le produit.

*Fichiers de l'espace de travail

Dans une configuration mono-utilisateur classique, la <racine d'installation> contient également les fichiers de l'espace de travail utilisateur. Ils sont créés une fois la plateforme démarrée. Dans une configuration à plusieurs espaces de travail, la plateforme est démarrée en spécifiant un répertoire d'espace de travail explicite. Tous les fichiers créés en tant qu'élément d'exécution de la plateforme sont écrits dans les répertoires de l'espace de travail. Notez que dans le scénario à plusieurs espaces de travail, l'utilisateur doit s'assurer qu'une seule instance du gestionnaire de mise à jour s'exécute à un moment donné. Si en fait la configuration à plusieurs espaces de travail représente une installation partagée par plusieurs utilisateurs, l'"administrateur" de l'installation partagée doit s'assurer que les utilisateurs individuels ne peuvent accéder à la racine de l'installation qu'en lecture seulement.

Mappage de système de fichiers : Installation de référence

La structure du fichier d'installation de référence est similaire à l'installation complète. Elle contient les éléments suivants :

<installation root>/
    install/
        components/
            install.index (optional)
            <componentId>_<version>/
                install.xml
                install_<locale>.properties (optional)
                <componentId>_<version>.jar
        configurations/
            install.index (optional)
            <configurationId>_<version>/
                install.xml
                install_<locale>.properties (optional)
                <configurationId>_<version>.jar

L'installation de référence peut être créée simplement par une décompression partielle du manifeste d'installation (et de tous les regroupements de ressources d'installation) à partir du jar de composant ou de configuration, suivie de la copie du jar complet dans la structure de répertoires résultante (en tant qu'homologue du fichier install.xml). L'exposition du fichier install.xml permet au gestionnaire de mise à jour de déterminer ce qui est disponible sur un site donné. Une fois sélectionné, le fichier .jar correspondant est téléchargé et installé.

Lorsque le site d'installation de référence est accédé par un protocole différent de l'entrée-sortie directe du fichier, le site doit également contenir le fichier optionnel install.index (dans les répertoires components/ et configurations/). Ce fichier est une simple "table des matières" des répertoires. Il contient les noms réels des sous-répertoires sur des lignes distinctes.

Par exemple :

<installation root>/
    install/
        components/
            install.index
            org.eclipse.platform_1.0.1/
            org.eclipse.jdt_2.9.5/
            org.eclipse.pde_1.0.4/

Le fichier install.index contiendrait :

org.eclipse.platform_1.0.1
org.eclipse.jdt_2.9.5
org.eclipse.pde_1.0.4

Le fichier install.index n'est pas requis lorsqu'il est fait référence au "site" via une entrée-sortie de fichier directe (une URL de fichier, par exemple). Notez, cependant, que si le fichier est présent, il est utilisé même dans le cas d'accès entrée-sortie directe de fichier. De cette façon, le fichier peut être utilisé par l'administration du site pour contrôler les configurations et les composants réellement exposés. En règle générale, ceci est utile lorsque les composants contenus dans des configurations ne sont pas destinés à être téléchargés et installés en tant qu'éléments distincts (c'est-à-dire, gérés uniquement via une configuration). Dans ce cas, les configurations sont directement exposées, mais pas les composants. Les composants sont localisés uniquement via les configurations exposées.

Lancement d'Eclipse

Avant d'observer certaines considérations propres à la mise à jour, il est important de comprendre comment la plateforme Eclipse est démarrée. Ceci implique les points suivants :
  1. le répertoire racine d'installation contient la commande de lancement du "produit". Il peut s'agir d'une simple commande "script" (.bat, par exemple) ou bien la fonction de ce script peut être effectuée par un simple lanceur d'exécutable (.exe, par exemple). Dans l'un ou l'autre cas, la commande de lancement effectue trois choses :
  2. La classe Main reçoit l'emplacement des exécutables de la plateforme Eclipse (propriété d'exécution) et l'identificateur d'une application que la plateforme doit exécuter (propriété d'application, le plan de travail est l'application par défaut fournie par Eclipse). La classe Main localise le fichier boot.jar de la plateforme et charge le chargeur initial de la plateforme à partir de celui-ci. Il donne le contrôle au chargeur initial qui transmet l'identificateur de l'application en tant qu'argument (plus tous les autres arguments de démarrage).
  3. Le chargeur initial entraîne le démarrage de l'environnement d'exécution de l'API principale de la plateforme. Ceci implique également le chargement et la résolution du registre du plug-in (configurant les plug-ins dont l'exécution sera possible).
  4. Le chargeur initial recherche le nom de l'application (transmis sous forme d'argument) dans le registre du plug-in, et s'il le trouve, active le plug-in de l'application et lui donne le contrôle.
  5. L'application démarrée (c'est-à-dire le plan de travail) active et appelle d'autres plug-ins si nécessaire.
Remarque : En fait, le lanceur par défaut fourni avec la version actuelle de la plateforme Eclipse ne traite pas le fichier install.properties (comme décrit aux étapes 1 et 2 ci-dessus). Il localise simplement l'écran d'accueil par défaut et l'environnement d'exécution de la plateforme par rapport à lui-même.

Considérations relatives à la mise à jour

Mise à jour de composants ne faisant pas partie de la plateforme

Les composants ne faisant pas partie de la plateforme fournissent des plug-ins qui s'exécutent "au-dessus" de la plateforme. Le gestionnaire de mise à jour installe simplement les fichiers et les répertoires de plug-ins requis. Ceux-ci sont détectés et traités lors du prochain démarrage de la plateforme.

Le gestionnaire de mise à jour ne met jamais à jour une structure de répertoires de plug-in existante. Il installe uniquement une version d'un plug-in qui n'existait pas précédemment. Si le répertoire de plug-in existe déjà (c'est-à-dire inclus dans un autre composant, ou une autre version de ce dernier), il n'est pas installé à nouveau. Le gestionnaire de mise à jour ne vérifie pas si le contenu du répertoire existant correspond à celui du JAR de composant. De ce fait, l'identificateur de version du plug-in doit être correctement indiqué dans le nom du répertoire du plug-in.

Mise à jour de la plateforme

La version courante de la plateforme Eclipse ne permet pas à la plateforme d'être mise à jour à l'aide du gestionnaire de mise à jour. Les mises à jour de la plateforme doivent être traitées via les mécanismes d'installation traditionnels.

Mise à jour de l'environnement JRE

La version courante de la plateforme Eclipse ne permet pas au JRE d'être mis à jour à l'aide du gestionnaire de mise à jour. Les mises à jour de JRE doivent être traitées via les mécanismes d'installation traditionnels.

Mise à jour des fichiers produit

Une installation sous forme de package inclut généralement un certain nombre de fichiers divers qui finissent par être placés dans le répertoire de lancement du produit. Ceci inclut divers fichiers readme, des images d'accueil, des copies des contrats de licence, des notes d'édition, etc. Ces fichiers devraient être regroupés comme élément des JAR de composant et de configuration (en tant que fichiers supplémentaires arbitraires dans la configuration spécifique ou le répertoire de composants (en tant qu'homologue du fichier install.xml)). Des fichiers individuels et des sous-répertoires sont permis. De cette façon, ces fichiers sont regroupés, fournis et installés en tant qu'élément du JAR de composant ou de configuration versionné.

Par exemple, le JAR de composant peut contenir :

install/
    components/
        com.xyx.etools_1.3.5/
            install.xml
            splash.bmp
            readme.txt
            license.txt
            notes/
                jspedit.txt
                debug.txt

Mise à jour du support de lancement

La version courante de la plateforme Eclipse ne permet pas au lanceur (.exe, startup.jar )d'être mis à jour à l'aide du gestionnaire de mise à jour. Les mises à jour du lanceur doivent être traitées via les mécanismes d'installation traditionnels.

Reprise suite aux défaillances de mise à jour

Deux scénarios sont à envisager.
  1. incidents contrôlés : il s'agit de diverses défaillances d'accès, de téléchargement, de décompression, etc. détectées par le gestionnaire de mise à jour. Ce gestionnaire contient la logique permettant une reprise suite à ces incidents.
  2. incidents "non contrôlés" : il s'agit de défaillances subites (coupure d'alimentation, par exemple) au milieu du traitement de la mise à jour avant que le gestionnaire de mise à jour puisse compléter l'opération. Ces défaillances sont détectées au démarrage de la plateforme. L'arborescence d'installation est vérifiée par rapport au dernier état connu et toutes les modifications partielles en sont supprimées.

Reprise suite à des mises à jour erronées

Le gestionnaire de mise à jour conserve une description de l'état de configuration courant de l'installation. Ceci inclut la liste des configurations et composants "actifs" (l'arborescence de l'installation réelle peut contenir des versions de configuration et de composant supplémentaires qui sont effectivement masquées du fait de mises à jour ultérieures).

Chaque fois que le gestionnaire de mise à jour met à jour et sauvegarde ces informations (une sauvegarde est effectué lors de l'arrêt de la plateforme), les informations d'état sont clonées et l'état précédent est conservé dans une séquence chronologique des mises à jour. Le gestionnaire de mise à jour gère plusieurs générations d'état (le nombre d'états conservés est une option paramétrable). Des versions antérieures de l'état et les configurations et composants correspondants sont régulièrement collectés (supprimés) lors du processus de nettoyage du gestionnaire de mise à jour.

Les copies de bas niveau de l'état fournissent un mécanisme de reprise suite à des mises à jour erronées. Dans ce scénario, "erroné" signifie que le gestionnaire de mise à jour est parvenu à télécharger et à appliquer un changement, mais que celui-ci est cause de problèmes.

Nettoyage de l'installation

Le gestionnaire de mise à jour étête périodiquement le contenu de l'arborescence d'installation. Seules les références de composants et de configurations contenues dans plusieurs des générations les plus récentes de l'état de mise à jour sont conservées (le nombre d'états retenus est une option paramétrable). Le nettoyage est effectué en tant qu'opération du gestionnaire de mise à jour et doit être explicitement déclenché.

Fonction non gérée d'Eclipse

En plus des configurations et composants installés "formellement", la plateforme Eclipse tolère également les plug-ins et les fragments de plug-in qui sont directement placés dans l'arborescence d'installation, sans manifeste d'installation correspondant les décrivant. Ces plug-ins et ces fragments sont reconnus lors de l'exécution, mais ne peuvent pas être mis à jour ou supprimés à l'aide des fonctions du gestionnaire de mise à jour (ils ne sont pas gérés). Ce support est spécifiquement lié aux scénarios de développement de plug-in dans une tentative d'élimination de la surcharge d'installation et de développement de mise en forme. Les programmes d'installation classiques ne doivent pas installer de plug-ins et de fragments non gérés.

Considérations relatives à l'installation

Du point de vue de l'installation, Eclipse fait une distinction entre une installation qui établit une nouvelle base de plateforme Eclipse (JRE, plateforme et l'application "dominante") et une autre qui ajoute simplement (fait fusionner) de nouveaux composants à une base existante.

Nouvelle installation

A présent, l'installation d'une nouvelle plateforme doit être réalisée à l'aide d'une technologie d'installation classique, telle que le programme d'installation Windows MSI, RPM, InstallShield ou un simple mécanisme d'archivage (un fichier .zip, par exemple). Le programme d'installation est responsable et doit garantir que la structure de fichier résultante (une fois l'installation terminée) respecte les spécifications du présent document.

Le programme d'installation doit effectuer les opérations suivantes :

Un programme de désinstallation "classique" correspondant doit être fourni pour supprimer l'application "dominante" et son arborescence de plateforme Eclipse. En général, le programme de désinstallation est responsable de l'inversion des actions de son programme d'installation. Notez, cependant, que le contenu de l'arborescence d'installation d'Eclipse peut changer du fait du fonctionnement normal de l'utilisation du gestionnaire de mise à jour d'Eclipse et que de ce fait, le programme de désinstallation "classique" peut ne pas trouver les fichiers installés à l'origine. Certains de ces fichiers peuvent ne plus exister (supprimés par le gestionnaire de mise à jour) et l'arborescence d'installation peut à présent contenir des fichiers supplémentaires qui n'ont pas été installés à l'origine (appliqués par des mises à jour). Il en résulte généralement qu'un programme de désinstallation "classique" reposant uniquement sur le fichier journal d'installation ne sera pas en mesure de supprimer totalement l'installation de l'application.

Pour compenser les changements effectués par le gestionnaire de mise à jour, le programme de désinstallation "classique" peut forcer la suppression de tous les fichiers contenus dans les répertoires d'installation d'Eclipse suivants :

D'autres répertoires se trouvant dans l'arborescence de l'installation peuvent contenir des données utilisateur et ne doivent pas être supprimés.

Installation fusionnée

Une fois l'installation d'une plateforme Eclipse établie (voir la section précédente), des composants et des configurations supplémentaires peuvent être ajoutés à la plateforme à l'aide du gestionnaire de mise à jour d'Eclipse ou d'un programme d'installation classique. Dans le dernier cas, le programme d'installation est responsable et doit garantir que la structure de fichier résultante (une fois l'installation terminée) respecte les spécifications du présent document.

Le programme d'installation doit effectuer les opérations suivantes :

L'utilisation d'un programme de désinstallation classique, dit "traditionnel" pour une installation fusionnée nécessite une attention toute particulière. En général, les programmes de désinstallation ne devraient jamais tenter de supprimer les fichiers programme réellement installés. La raison en est que les fichiers installés à l'origine risquent de ne plus exister ou que certains des fichiers installés ont été mis à jour au cours d'une opération normale d'Eclipse. Il en résulte que la tentative visant à supprimer directement les fichiers installés d'origine peut, au mieux, fonctionner correctement ou ne pas avoir d'effet du tout, et au pire, aboutir à la suppression d'une portion arbitraire du support installé (engendrant des défaillances imprévisibles lors du prochain lancement de l'application). Ceci est davantage aggravé lorsque les composants ou les plug-ins sont partagés. Les fichiers ne peuvent être supprimés directement uniquement dans le cas où une configuration ou un composant serait garanti ne pas avoir été mis à jour et ne pas être partagé.

Des précautions doivent être prises lors de l'utilisation des technologies de programme d'installation qui ne permettent pas le contrôle énoncé précédemment sur le processus de désinstallation (c'est-à-dire, la suppression des fichiers installés). RPM sous Linux est l'un de ces exemples. Dans ce cas, la technologie du programme d'installation spécifique doit être évitée pour les installations fusionnées, ou la désinstallation ne doit jamais être exécutée.

Un programme de désinstallation classique peut supporter une suppression sans risque de la fonction installée à l'aide des fichiers "racine" de l'installation fusionnée. Ceux-ci sont installés en option au cours de l'installation fusionnée et agissent comme point d'ancrage pour les configurations et les composants correspondants. La plateforme Eclipse détecte la suppression des fichiers "racine" au cours du démarrage et supprime sans risque les configurations et les composants indiqués.

Remarque : Contrairement aux fichiers de configuration et composant, les fichiers "racine" ne sont pas sujets à des modifications par le gestionnaire de mise à jour. De ce fait, un programme de désinstallation classique peut se fier à eux pour rester en place une fois installé.

Une fois installés, les fichiers "racine" sont placés dans le répertoire install/info/ dans l'arborescence de l'installation d'Eclipse (homologue des répertoires install/configurations et install/components). Les fichiers utilisent la convention de dénomination suivante :

<merged-installation-identifier>.install

La plateforme Eclipse ne spécifie pas le format de l'identificateur (n'est interprété en aucune façon). Pour réduire au maximum les possibilités de conflits de nom, il est fortement recommandé que l'identificateur utilise une convention de dénomination basée sur le nom du domaine Internet du fournisseur (par exemple, com.xyz.toolpack.install).

Le contenu du fichier "racine" utilise le format de fichier de propriétés Java, contenant les éléments suivants :

configurations=[<configId>_<version> [, <configId>_<version>]* ]
components=[<compId>_<version> [,<compId>_<version>]* ]


[]optional element
* repeating group

(en texte clair, les deux propriétés sont composées d'une liste d'identificateurs dont le suffixe est la version correspondante, séparés par une virgule.

Enregistrement spécifique à la plateforme

Remarque : Cette section décrit la "meilleure procédure" suggérée. Cependant, elle n'est pas requise pour une exécution correcte de la plateforme Eclipse.

Il est suggéré que les produits basés sur Eclipse utilisent un mécanisme d'enregistrement du système d'exploitation pour effectuer le suivi de tous les emplacements de plateformes Eclipse installées. Ceci permet une recherche simple lorsqu'il est décidé de créer l'installation d'une nouvelle plateforme ou de fusionner des composants dans un composant existant. Sur les plateformes pour lesquelles un tel mécanisme d'enregistrement n'est pas fourni, l'utilisateur sera invité à identifier de manière explicite les répertoires d'installation d'Eclipse.

Le programme d'installation propose généralement de créer une installation ou de fusionner les composants dans une installation existante. La création d'une installation doit également mettre à jour les structures d'enregistrement.

Sous Windows, le Registre Windows est utilisé dans ce but. Ci-dessous figure la structure suggérée de clés du registre permettant l'identification des répertoires d'installation de la plateforme Eclipse :

eclipse.org/
    platforms/
        <product name>

La clé <product name> identifie le fournisseur et/ou l'application dominante ayant créé l'installation de la nouvelle plateforme Eclipse. La clé complète mappe les attributs suivants :

label est le libellé affichable de la clé <product name>. Localisé au moment de la création.
directory est le chemin d'accès absolu (<absolute path>).

Considérations relatives au développement

Indépendance de l'emplacement d'installation

L'API Eclipse permet à un plug-in d'exécution d'obtenir une référence à son répertoire d'installation. Ceci est réalisé en appelant IPluginDescriptor.getInstallURL(). L'appel renvoie java.net.URL. Les plug-ins d'exécution accèdent à toutes les ressources requises relatives à cette URL. Le support du protocole d'URL traite la redirection requise au répertoire du plug-in local, à la cache du plug-in, au CD (installation minimale) ou au serveur. Un plug-in accède généralement à ses ressources en ouvrant un flux d'entrée sur l'URL et en lisant le contenu de la ressource. Comme l'emplacement de l'installation est présumé ne pouvoir être accédé qu'en lecture uniquement, le plug-in d'exécution ne devrait jamais tenter d'écrire à l'aide de l'URL renvoyée.

Exécutables natifs

Les bibliothèques Java natives utilisées par les plug-ins Eclipse ne requièrent pas de traitement spécial. Elles sont installées dans la structure des répertoires de plug-in et chargées par le chargeur de classe de la plateforme (jdk 1.2+).

Les composants natifs propres au système d'exploitation (tel qu'ActiveX) nécessitent une installation personnalisé, non traitée par le gestionnaire de mise à jour d'Eclipse. Le programme d'installation personnalisé enregistre les composants avec les services du système d'exploitation approprié et met à jour les chemins de recherche standard. La plateforme Eclipse ne fournit pas de vérification automatique des composants natifs requis. Le code du plug-in est requis pour implémenter la logique de vérification/reprise nécessaire. Il est possible de créer un plug-in "marqueur" comme élément du programme d'installation personnalisée afin d'indiquer la présence de certains composants natifs et de permettre à d'autres plug-ins de spécifier la dépendance. Cependant, cette approche n'est pas sans risque et ne peut pas être utilisée comme garantie absolue d'une dépendance native satisfaite.

Support de versions de plug-in concurrentes

La plateforme Eclipse permet à plusieurs versions d'un plug-in d'être installées simultanément. Ceci couvre des scénarios dans lesquels un utilisateur installe deux produits basés sur Eclipse, contenant des versions différentes du même plug-in. Les deux versions peuvent être installées dans la racine du programme commun. Selon les règles de configuration (abordées ultérieurement), normalement la plateforme utilise uniquement la version la plus récente du plug-in pendant l'exécution. Cependant, si l'utilisateur désinstalle ensuite l'un des produits, la structure d'installation des autres produits reste inchangée (en d'autres termes, elle contient la version correcte du plug-in, installé avec le produit).

La plateforme Eclipse permet également à plusieurs versions du même plug-in d'être configurées et exécutées simultanément. Ceci est particulièrement lié aux plug-ins contenant des bibliothèques d'exécution partagées. Un utilisateur donné de l'environnement d'exécution partagé peut spécifier une dépendance à une version spécifique du plug-in. Un tel plug-in doit déclarer uniquement ses bibliothèques d'exécution (à la section <runtime> du fichier plugin.xml) et ne doit pas déclarer d'autres contributions à la plateforme (et tout particulièrement ne pas déclarer de point d'extension et/ou ne pas ajouter d'extensions).

Pour pouvoir supporter cela, la plateforme Eclipse définit un schéma pour l'identification des plug-ins, une convention pour la dénomination des répertoires du plug-in dans le système de fichiers et un jeu de règles pour la configuration et l'exécution des plug-ins localisés au démarrage de la plateforme.

Les plug-ins sont identifiés par une combinaison de chaînes structurées, constituées d'un nom de package Java et d'un identificateur de version à plusieurs décimales. L'identificateur de version est constitué d'un composant majeur indiquant une génération incompatible et un composant mineur indiquant une évolution compatible du plug-in.

Du fait que plusieurs versions du même plug-in peuvent être physiquement installées dans la même arborescence de fichiers, les répertoires de plug-in individuels doivent être identifiés de manière unique pour empêcher plusieurs versions du même plug-in d'être écrasées par erreur. Le nom de répertoire de plug-in recommandé est la combinaison de l'identificateur unique du plug-in et de l'identificateur de version. Le caractère "_" (trait de soulignement) est utilisé pour séparer la chaîne de la version de la chaîne du nom. Les exemples ci-dessous illustrent les noms de répertoire pour les plug-ins correspondants.
 
Plug-in Version Nom de répertoire recommandé
org.eclipse.ui 1.3.17 org.eclipse.ui_1.3.17
edu.xyz.tools 1.0.1 edu.xyz.tools_1.0.1

La plateforme fournit une API pour le traitement des identificateurs de version :

Il existe une autre considération pour les plug-ins qui permet l'exécution concurrente et également l'écriture de l'état du plug-in ou des données de fonctionnement (voir Plugin.getPluginStateLocation() et IProject.getPluginWorkingLocation(IPluginDescriptor)). Au-delà des questions de migration de version (voir la section suivante), les plug-ins sont également responsables de la gestion de l'accès concurrent à partir de plusieurs versions d'exécution du même plug-in aux ressources de plug-in partagées. Les plug-ins doivent utiliser les fonctions des API d'accès au fichier sélectionné pour coordonner l'accès concurrent.

Migration de version

Du fait de la nature dynamique de la configuration de la plateforme, les implémentations de plug-in doivent être au fait des problèmes de migration qui peuvent survenir pendant l'exécution. Contrairement aux produits traditionnels, les solutions basées sur Eclipse ne se rassemblent pas tant que la plateforme n'est pas démarrée par l'utilisateur.

La plateforme fournit des fonctions de base qui peuvent être utilisées par le plug-in pour traiter chacune des situations de migration. Cependant, la responsabilité incombe au développeur de plug-in de les utiliser correctement.

Lorsque les plug-ins s'exécutent, ils peuvent écrire les informations qui leur sont spécifiques dans plusieurs emplacements d'exécution. Les références aux emplacements d'exécution sont obtenus à l'aide des appels d'API suivants :

Chaque plug-in est responsable du traitement de la migration de ses données de travail. Deux scénarios de base sont à envisager pour les plug-ins :
  1. migration avant : une nouvelle version d'un plug-in a été configurée et elle doit faire migrer les données écrites par la version précédente. Ceci se base sur la présomption que la version n+1 d'un plug-in peut lire les données écrites par la version n du même plug-in.
  2. migration arrière : une version d'un plug-in configurée dans un appel précédent de la plateforme est supprimée et une version antérieure du même plug-in est alors configurée (la version la plus récente masquait la version antérieure). C'est un scénario plus curieux car on ne présume généralement pas qu'une version n d'un plug-in puisse lire les données écrites par la version n+1 du même plug-in.
Le scénario de migration avant nécessite que la nouvelle version du plug-in détecte les données écrites par la version antérieure et lise, convertisse et réécrive les données. Ceci peut être effectué la première fois que la nouvelle version du plug-in est activée (Plugin.startup()) ou pendant l'accès aux zones d'exécution. En général, la première approche est plus adaptée à la migration des données d'état du plug-in et la seconde à la migration des données du projet.

La migration arrière nécessite un travail supplémentaire de la part du développeur de plug-in. En fait, la version n+1 du plug-in doit écrire les données de telle sorte que la version n puisse au moins détecter cette situation. Il existe plusieurs techniques que les plug-ins peuvent utiliser pour traiter ce scénario :

Le développeur de plug-in est responsable du choix de la stratégie d'implémentation appropriée. La plateforme ne fournit pas d'API spécifique pour la gestion automatique de la migration des données du plug-in.