Packager votre propre module

Une fois que vous avez finalisé le code de votre projet SKUAD vous pouvez réaliser quelques réglages afin de faciliter les manipulations à effectuer pour son déploiement. Ces réglages relèvent ce qu’on appel le packaging, et dans ce tutoriel nous allons examiner ce qu’il est possible de faire à ce niveau.

1 - Un simple fichier jar

Le packaging le plus simple à réaliser est de produire une archive jar contenant l’ensemble du code compilé de votre projet. C’est la forme la plus couramment utilisé pour déployer des programmes et des librairies écrites en Java. C’est donc aussi sous cette forme que le packaging de module SKUAD doit être réalisé. Nous allons voir ici comment réaliser une telle archive, et dans la suite nous examinerons les ajustements complémentaires qui permettrons d’optimiser encore plus l’opération de déploiement.

Si vous utilisez l’éditeur Eclipse cette opération peut être réalisée comme ceci :

  • Nous allons commencer par créer le dossier dans lequel l’archive sera créée : dans le volet d’exploration, cliquez avec le bouton droit de la souris sur l’item de votre projet puis choisissez l’item « New » puis « Folder ».
  • Entrez le nom « dist » dans le champ « Folder name », puis cliquez sur « Finish ».
  • Maintenant, cliquez à nouveau avec le bouton droit de la souris sur l’item de votre projet dans le volet d’exploration, puis choisissez cette fois l’entrée « Export… » du menu qui va apparaître.
  • Dans la boite qui s’affiche, déployez le menu « Java », sélectionnez l’item « JAR file » puis cliquez sur le bouton « Next »

  • Utilisez le bouton « Browse… » pour naviguer jusqu’au dossier « dist » que l’on a créée dans le répertoire de votre projet et entrez le nom de l’archive, par exemple « monprojet.jar » pour pouvoir valider cette boite de navigation. Cela va remplir le champ « JAR file » avec une chaine de la forme : « MonProjet/dist/monprojet.jar » .

  • Il nous vous reste plus qu’a finaliser l’opération en cliquant sur le bouton « Finish ». Eclipse va générer le fichier jar et le placer dans votre dossier « dist ». Vous pouvez constater cela dans l’explorateur de projet :

Voila, le pack de votre module est terminé. Pour le déployer dans une installation il vous suffit simplement de copier cette archive dans le dossier « lib » d’un dossier SKUAD. Puis d’utiliser le lanceur en mentionnant le nom de votre programme. Par exemple, si le programme de votre projet est monprojet.MonProg vous devez taper la commande :

  > java   start   monprojet.MonProg  

 
2 - Le fichier de configuration d'un module SKUAD

L’archive jar que nous avons produite dans la section précédente est fonctionnelle, mais elle ne comporte aucun renseignement sur votre module. De ce fait le lanceur SKUAD n’est pas en mesure d’identifier votre module et de gérer les éventuelles dépendances qui pourrait le concerner. Pour le constater ouvrez une console et placez vous dans le dossier SKUAD ou vous avez déployé votre archive. Tapez ensuite la commande qui permet de lister les modules présents :

  > java   start   -m  

Dans cette liste votre module n’apparait pas.

Pour remédier à cette lacune il vous faut spécifier les informations de configuration de votre projet. Cela se fait simplement en ajoutant un fichier de nom config.ini dans votre dossier « src » : sous Eclipse, cliquez droit sur votre projet dans le volet d’exploration, item « New » puis « File » et entrez le nom « config.ini ».

Dans ce fichier de configuration vous pouvez spécifier les informations suivantes (une par ligne) :

  • @module=NOM_DU_MODULE : pour indiquer le nom de votre module.
  • @version=VERSION : pour indiquer la version de votre module.
  • @depends=DEPENDANCES : pour indiquer les dépendances de votre module, c’est à dire la liste des autres modules nécessaires à son fonctionnement. Cette valeur doit être une liste de nom de module séparés par des virgules. Vous avez aussi la possibilité de faire suivre un nom par un numéro de version pour préciser la version minimale de ce module.

Voici un exemple de spécification pour un module de nom MonProjet, qui nécessite la présence du module ModGIS et la librairie SKUAD dans une version supérieure ou égale à 0.1_b12 :

@module=MonProjet
@version=0.1
@depends=ModGIS, SKUAD 0.1_b12

En plus de ces informations, dans ce fichier de configuration vous pouvez aussi créer des alias de lancement pour le ou les programmes que contient votre projet. Un alias de lancement est un nom court qui va désigner un programme. Par exemple, si vous avez un programme de nom complet monprojet.MonProg vous pouvez créer un alias court sous le nom MonProg. Cet alias pourra alors être utilisé en argument du lanceur SKUAD afin d’avoir moins de chose à écrire pour lancer votre programme.

L’autre avantage des alias est qu’on peut prendre connaissance de leur exitence avec la commande :

  > java   start   -l  

En effet, cette commande affiche la liste des alias disponible dans une installation SKUAD. En plus du nom de l’alias on peut avoir un texte exprimant son utilité et la mention d’une catégorie afin de regrouper les alias par thème.

Voici la syntaxe à utiliser pour créer un alias dans votre fichier config.ini :

  • NOM_ALIAS=NOM_COMPLET_DU_PROGRAMME
  • NOM_ALIAS@label=DESCRIPTION_DU_PROGRAMME
  • NOM_ALIAS@cat=CATEGORIE

Par exemple, pour le programme monprojet.MonProg on écrira :

MonProg=monprojet.MonProg
MonProg@label=un super programme qui va changer le cours de l'histoire
MonProg@cat=Test MonProjet

Astuces complémentaires :

Il faut faire attention aux caractères accentués dans ce fichier config.ini car ils ne sont pas correctement interprétés durant l’analyse de la configuration. Pour éviter les problèmes il faut les encoder en les remplaçant par un code de la forme \XXXX spécifique à chaque caractère. Voici la liste des codes à utiliser pour les caractères accentués les plus courants :

  • é : \u00e9
  • è : \u00e8
  • à : \u00e0

Notez aussi que les lignes qui commencent par le symbole # seront ignorées. Vous pouvez donc ajouter des commentaires dans votre fichier config.ini en les plaçant sur des lignes qui commencent par ce symbole.

Une fois que vous avez terminé l’édition du fichier config.ini vous devez regénérer votre archive jar tel qu’on la fait dans la section 1, puis la déployer dans le répertoire « lib » d’un dossier SKUAD. Essayez ensuite les commandes ci-dessous pour constater les changements :

  > java   start   -m  

  > java   start   -l  

  > java   start   MonProg  

 
3 - Un pack d'installation

Si vous avez essayé des modules additionnels SKUAD, tel que ModGIS ou Mod2D, vous avez du constater qu’ils disposent d’un pack d’installation sous la forme d’un fichier .zip. Ces packs rendent plus facile la mise en place de l’archive du module car il suffit simplement de les décompresser dans un dossier SKUAD et le tour est joué. Pour les environnements ou l’application de décompression n’est pas présente on peut même utiliser la commande suivante du lanceur SKUAD pour réaliser l’installation directement depuis le pack .zip :

  > java   start   -i   FICHIER_PACK.ZIP

Vous pouvez vous aussi produire de tel pack d’installation pour vos modules. Il suffit pour cela de créer un fichier compressé .zip qui contient un dossier « lib » dans lequel vous aurez placé l’archive .jar de votre projet. C’est aussi simple que ça.

Vous pouvez également donner un minimum d’information sur votre module en ajoutant dans la racine de votre fichier .zip un fichier qui commence par « readme » et dont l’extension est « .txt » (par exemple : readme_monprojet.txt). Ce fichier peut contenir le texte d’explication que vous souhaitez, mais notez que s’il est présent la première ligne qu’il contient sera affichée à la fin de l’installation réalisée par la commande « java start -i …« . Aussi, l’usage est que la première ligne de ce fichier readme doit comporter le nom et le numéro de version de votre module.

 
4 - Un script Ant pour tout générer en seul click

Sous Eclipse vous pouvez automatiser la génération d’un packd d’installation afin de le produire en même temps que votre archive .jar, et le tout en seul click ! Ceci grâce à un script Ant.

Pour produire un tel script il vous siffit de créer un fichier de nom build.xml dans le répertoire de votre projet (en racine, donc au même niveau que les dossiers « src » et « dist ») :

Dans ce fichier devez adapter le code suivant en remplaçant les valeurs de NOM_PROJET et VERSION : sur les lignes 1 (à deux endroits), 2, 3 et 11, par celles correspondantes à votre projet :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
<project name="NOM_PROJET" default="dist NOM_PROJET" basedir=".">
    <property name="base_name"  value="NOM_PROJET"/>
    <property name="lib_version"    value="VERSION"/>
   
    <!-- propriété -->
    <property name="build" location="bin"/>
    <property name="dist"  location="dist"/>
    <property name="ress"  location="ressource"/>
    <property name="name_lib" value="${base_name}_v${lib_version}"/>
   
    <target name="dist NOM_PROJET"
        description="genere le pack d'installation de ${base_name}" >
       
        <mkdir dir="${dist}/${name_lib}"/>
        <mkdir dir="${dist}/${name_lib}/lib"/>     
        <copy   file="${ress}/readme.txt"
            tofile="${dist}/${name_lib}/readme_${base_name}.txt"
            overwrite="true"/>
       
        <jar jarfile="${dist}/${name_lib}/lib/${name_lib}.jar" >
                <fileset dir="${build}" />
        </jar>
       
        <zip destfile="${dist}/${name_lib}.zip" basedir="${dist}/${name_lib}" />
    </target>
</project>

Notez que ce script gère la mise en place du fichier « readme_XXX.txt » décrit à la fin de la section 3. Aussi, pour qu’il fonctionne correctement vous devez créer un dossier de nom « ressource » en racine de votre projet, et vous devez placer dans ce dossier un fichier de nom « readme.txt ». Comme cela est expliqué à la fin de la section 3, vous êtes libre de mettre le contenu que vous souhaitez dans ce fichier, mais l’usage veut que la première ligne contient le nom de votre module et son numéro de version

Si tout est bien en place votre projet devrait ressembler à ceci:

Il nous reste maintenant à câbler le fichier build.xml avec l’interface d’Eclipse. Pour cela cliquez sur le menu principal « Window » (tout en haut) puis « Show View », et cliquez sur « Ant ».

Cela va ouvrir le volet Ant sur la gauche de votre interface. Dans ce volet cliquez sur l’icône qui représente un + avec une fourmi (« Add Buildfiles »).

Et dans la boite qui s’ouvre sélectionnez le fichier build.xml de votre projet, puis validez avec le bouton « OK » :

Le script va apparaître dans le fenêtre de Ant. Et si vous cliquez sur la flèche qui se trouve à la gauche de son nom vous allez voir l’item de la commande que contient ce script : « > dist NOM_PROJET« .

Voila, le script de déploiement est en place. Maintenant à chaque fois que vous aurez besoin de générer le pack d’installation de votre projet il vous suffira :

  • de mettre à jour le numéro de version dans le fichier ressourse/readme.txt, et sur la ligne 3 du fichier build.xml
  • puis de double cliquer sur la commande « > dist NOM_PROJET«  du volet Ant

Au bout de quelques secondes vous verrez la confirmation de la fin de la génération du pack dans le volet « console » d’Eclipse, et en cliquant avec le bouton droit sur le dossier « dist » dans le volet d’exploration, choisissez l’item « refresh » pour voir le pack d’installation .zip apparaître dans ce dossier.