wiki:documentation
Last modified 3 years ago

Comprendre le wspDeriver

  1. Le Deriver en quelques mots
  2. Quand utiliser le deriver ?
    1. Exemples
  3. Deriver et SVN
    1. ordre des actions pour les commits et updates du projet
    2. rôle de chaque script
  4. Exemple complet pour un deriver opale
    1. Preparer SCENARIBuilder à pouvoir modifier le modèle Opale
    2. Mettre en place le deriver
    3. Mettre à jour le modèle original
  5. Changement d'url dans le conf.xml
  6. commandes à effectuer sur linux
  7. Changer l'attribut "Name"
    1. Changer le name de la composition
  8. JRE de Sun

Attention !

Le deriver a changé de structure, de manière à pouvoir commiter un dossier model. Cette fonctionnalité est très utile pour dériver un modèle issu lui-même d'une dérivation. Exemple de Swad qui dérive DokielGuide qui lui même dérive Dokiel. La documentation ci-dessous a été mise à jour en conséquence.

Le Deriver en quelques mots

Le deriver est une application extérieure à SCENARIbuilder.

Elle ne s'installe pas, mais est composée de 3 scripts (bat pour windows, sh pour linux): originalUpdate, createWsp et autoDiff.

  • Pour créer un projet de dérivation il faut tout d'abord poser une certaine organisation de dossiers (simplement créer les dossier à la main de manière classique) où on veut sur son disque dur (mieux vaut le faire dans l'espace où on rassemble les projets svn, comme le workspace d'eclipse si on l'utilise par exemple) qui sont "deriver", "original", "model", et "apps". Par exemple MaDerivation contient ces 4 dossiers : deriver, original, model, apps.
  • toujours dans le dossier deriver, vous devez placer un fichier conf.xml qui doit avoir un contenu de ce type : 
 <wspTransformer name="monProjet" version="1.x">
	<wspOut dir="../model" />
	<originalFolders>
		<folder from="../original/rep1" target="sources/rep1"/>
		<folder from="../original/rep2" target="sources/rep2"/>
		<svnSynchro>
			<credential username="anonymous" password="anonymous"/>
			<item from="http://.../sources/rep1" to="../original/rep1"/>
			<item from="http://.../sources/rep2" to="../original/rep2"/>
		</svnSynchro>
	</originalFolders>

	<overwrite from="../overwrite"/>
	
	<!-- # xsl globales -->
	<xsl path="res/toto.xsl" dir="sources/rep1" includes="**/*.transf"/>
	<xsl path="res/toto.xsl" dir="sources/rep2" includes="**/*.transf"/>
		
</wspTransformer>

Quand utiliser le deriver ?

Le deriver sert à produire un modèle documentaire à partir d'un modèle d'origine en automatisant les modifications à faire (ajout d'un objet métier, modification du stylage des générateurs, ajout d'un nouveau générateur etc).

Ceci n'a de sens que si le modèle d'origine et le modèle dérivé sont dans la même version de SCENARIbuilder. Entre deux versions de SCENARIbuilder, les sources des modèles sont amenés à être sensiblement modifiés, il en résulte un modèle sensiblement différent de la source.

Exemples

L'utilisation du deriver n'est pas pertinente pour :

  • Dériver un modele 3.n pour le passer en 3.n+1, car il y a une migration des sources entre ces deux versions, on se retrouve avec un différentiel de 100% entre l'orignial et le modèle dérivé. En effet, entre la 3.4 et 3.5 par exemple, TOUT les transformers Web, la plupart des .model sont touchés par la migration.

Cependant, le deriver a toute sa pertinence pour :

  • un passage de la 3.5.0 à la 3.5.1,
  • un passage de la version d'un modèle (ex: Opale) à un autre si les modifications du modèles se sont réalisées avec la même version de builder.
  • L'utilisation du deriver est surtout pertinente pour changer un peu la chaîne (ajouter une intro, changer le générateur, les styles etc), en gardant un lien avec celle d'origine.

Exemple

Dans sa dérivation de DokielGuide, Swad ajoute des balises dans le texte, ajoute un nouveau générateur web aux styles et comportements dédiés à l'utilisation de Swad (documenter Scenari), et pour finir ajout de nouveaux .model et leurs générateurs associés pour créer encore plus de documents.

Deriver et SVN

Deriver a besoin de la structure suivante dans votre projet:

  • deriver
    • overwrite
    • conf.xml
  • apps : en external
  • original : les dossiers du projet original en svn:ignore car updatés par la fonction 2 du dériver (originalUpdate)
  • model : en svn:ignore sauf si l'on souhaite permettre une dérivation de cette dérivation (cf plus haut).

Les dossiers et fichiers à commiter absolument sont tous contenus dans le répertoire deriver. Voilà pourquoi il est essentiel d'effectuer régulièrement l'action 1_autoDiff, pour enregistrer le différentiel dans le dossier deriver/overwrite.

ordre des actions pour les commits et updates du projet

Pour un update/checkout du projet

  • update svn
  • apps/2_OriginalUpdate
  • apps/3_CreateWsp

Pour un commit du projet

  • apps/1_AutoDiff
  • commit svn

Si vous travaillez à plusieurs, faites régulièrement des updates et commit pour ne pas vous "marcher" dessus.

rôle de chaque script

Voici à quoi servent les 3 scripts :

  • Le script « 2_originalUpdate » lit ton fichier conf.xml pour retrouver l’emplacement du source svn que tu veux dériver. Puis il effectue un svn checkout dans un dossier « original » de votre dérivation. Au final vous avez en local la copie synchronisée SVN du modèle que vous dérivez.
  • Le script « 3_createWsp » lit également le conf.xml pour savoir où placer votre copie de travail de ce même modèle. Il effectue une copie synchrone avec la précédente dans le dossier « model » de votre espace de dérivation. Mais cette fois-ci la copie est dépouillée de tout ce qui concerne subversion. C’est sur cette copie que ton travail de dérivation se fera. La première servant d’original de référence.
  • Le script « 1_autoDiff » se base également sur le conf.xml pour savoir où est votre dossier de travail (« model ») et où est le répertoire de sauvegarde de tes modifs (« overwrite »). Le script met de coté les fichiers qui proviennent du modèle d’origine mais que tu as modifié dans ton espace de travail « model ». Les dossiers que tu aura ajouté pour compléter ton modèle seront ignorés par le mécanisme dériver cas il ne risquent pas d’être écrasés.

Exemple complet pour un deriver opale

Preparer SCENARIBuilder à pouvoir modifier le modèle Opale

  1. Télécharger Extension Assmnt (exercices)

http://scenari-platform.org/projects/scenari/files/SCENARIbuilder/extensions/modelingAssmnt/latestStable/

  1. Installer Extension Assmnt (exercices)

SCBuilder > Ateliers > Ajouter une extension => Sélectionner le paquet téléchargé.

Remarque : l'extension Scenari modelling sound n'est pas nécessaire pour opale (seulement pour webradio).

Mettre en place le deriver

  • Créer un dossier "monprojetdederivation" dans le dossier SCbuilder3.4
  • A l'intérieur du dossier "monprojetdederivation", créer les 4 dossiers "deriver", "original", "model", et "apps".
  • Dans monprojetdederivation/deriver , créer le dossier overwrite.
  • Aller sur http://scenari-platform.org/svn/wspderiver/trunk/ (si on utilise konqueror ou dolphin, écrire  svn+http://scenari-platform.org/svn/wspderiver/trunk/ ) puis copier coller les scripts et les dossiers ; les mettre dans le dossier apps .
  • Copier le fichier conf.sample.xml qui est situé dans apps/sample ; et le coller dans deriver.
  • Renommer le fichier conf.sample.xml en conf.xml
  • Dans ce fichier, changer les url par celles de la version en cours que l'on souhaite deriver (3.0.6 à la date du 23/04/2008), soit par exemple :

remplacer 

http://scenari-platform.org/svn/opale/branches/v3/model/sources/academic

par 

http://scenari-platform.org/svn/opale/tags/3.0.6/model/sources/academic

Faire de même pour les url contenant les dossiers math et binaries

  • Dans monprojetdederivation/apps/ , rendre executable 2_originalUpdate.sh (sur linux)
  • Pour rapatrier le modèle original opale :

Lancer 2_originalUpdate (commande une fois dans le répertoire : ./2_originalUpdate.sh ). Cela permet de télécharger certains fichiers d'opale et de les mettre dans le dossier monprojetdederivation/original/.

Remarque : Le script « 2_originalUpdate » lit ton fichier conf.xml pour retrouver l’emplacement du source svn que l'on souhaite dériver. Puis il effectue un svn checkout dans un dossier « original » de la dérivation. Au final on a en local la copie synchronisée SVN du modèle dérivé.

Conseil

Si vous utilisez un proxy, il est possible que le script "2_orignalUpdate" reste bloqué à l'étape "checkout". Editez le fichier de configuration, cherchez la ligne "credential" et rajoutez les paramètres proxy et proxyport, par passez de : 

<credential username="anonymous" password="anonymous"/>

à 

<credential username="anonymous" password="anonymous" proxy="proxyweb.utc.fr" proxyport="3128"/>

  • Rendre exécutable 3_createWsp.sh (sur linux)
  • Pour créer le dossier « model » de travail (sur lequel on travaillera avec SCbuilder)

Lancer 3_createWsp.

Remarque : Le script « 3_createWsp » lit également le conf.xml pour savoir où placer la copie de travail de ce même modèle. Il effectue une copie synchrone avec la précédente dans le dossier « model » de l'espace de dérivation. Mais cette fois-ci la copie est dépouillée de tout ce qui concerne subversion. C’est sur cette copie que le travail de dérivation se fera. La première servant d’original de référence.

  • Créer l'atelier avec Builder
    • Cliquer sur Atelier > Ajouter un atelier
    • Dans stockage de l'atelier, sélectionner le dossier créé lors de l'étape 1 (dans cet exemple monprojetdederivation). Lui mettre le code que l'on veut.
    • Aller dans l'onglet "Avancée" puis pour stockage des items, sélectionner SCbuilder3.4/monprojetdederivation/model/sources; pour stockage des générations, sélectionner SCbuilder3.4/Monprojetdederivation01/model/~gen
    • Dans la partie "Définition du modèle", sélectionner les extensions "Modèles d'évaluation" et "Modèles de gestion du son" (s'ils ne sont pas disponibles, les installer, sinon on rencontre des dépendances insatisfaites par la suite (croix rouges)).
    • Cliquer sur créer
  • Effectuer ses modifications.

Mettre à jour le modèle original

  • Lancer le script 1 (1_autoDiff.sh) pour sauver ses propres modifications avant mise à jour de l’original.
  • Mettre à jour le conf.xml en remplaçant les url appropriées

Ex: Remplacer http://scenari-platform.org/svn/opale/tags/3.0.6/model/sources/academic par http://scenari-platform.org/svn/opale/tags/X.X.X/model/sources/academic (X étant à adapter à la dernière version stable)

  • Lancer le script 2 pour rapatrier l’original,
  • Le script 3 pour créer ton dossier « model » de travail
  • Faire vos premières modifications
  • Lancer un script 1 pour sauver vos modifications avant mise à jour de l’original
  • Relancer le script 2 ou faire un svn checkout sur votre original pour profiter des mises à jour du modèle d’origine
  • Relancer le script 3 qui va remplacer les dossiers indiqués dans le conf.xml de « original « vers « model » puis merger par xsl vos modifications personnelles sauvées par le script 1 dans le dossier « overwrite » avec le contenu des fichiers de « model »
  • Et vous bouclez ainsi sur modifications, 1, 2, 3...

(source: d'après des postes forum de Franck.Rouze et pepe, http://scenari-platform.org/forum/viewtopic.php?p=3492#3492)

Changement d'url dans le conf.xml

Attention !

Si l'on change les url dans le conf.xml, il faut soit faire un switch des dossiers contenus dans original, soit les supprimer et lancer la fonction originalUpdate.

Pour effectuer un switch dans le même repo Svn (le début de l'url est équivalent), sous linux : juw@xxx:~/eclipse/Mod_DokielGuide/original/sources/binaries$ svn sw http://scenari-platform.org/svn/dokiel/trunk/model/sources/binaries .

Pour effectuer un switch d'un repo Svn à un autre, quand le projet initial a changé d'hébergement. Exemple : le projet est passé du serveur de Kelis data.dokiel.fr au serveur Scenari-platform.org : {{{juw@xxx:~/eclipse/Mod_DokielGuide/original/sources/binaries$ svn sw --relocate  http://data.dokiel.fr/svn/Mod_DokielTemp http://scenari-platform.org/svn/dokiel }}}

commandes à effectuer sur linux

  • juw@juw:~/eclipse/maDerivation$ svn pe svn:ignore .

Entrez alors {{{ original model }}} séparés par un retour à la ligne. La ligne "model" est facultative.

  • juw@juw:~/eclipse/maDerivation$ svn pe svn:externals .

Entrez alors sur une seule ligne apps http://scenari-platform.org/svn/wspderiver/trunk. Cela permet d'avoir la dernière version du deriver à chaque update du repo.

Pour que cela fonctionne il faut que le dossier initial soit commité (ie le dossier au-dessus de deriver, original, apps et model), sinon svn ne peut pas éditer les propriétés ignore et externals, que ce soit sur linux ou windows.

Changer l'attribut "Name"

Décliner une chaîne éditoriale peut vouloir aussi signifier personnaliser l'interface auteur, et en particulier les noms affichés dans SCENARIchain. Ce sont les noms qui s'affichent dans la fenêtre de création d'item, dans la barre d'information supérieure (au dessus de l'éditeur), au survol d'un item, dans l'éditeur etc.

Il y a deux types de modifications à effectuer : changer le name de la composition, et changer le name des sm:part où cette composition est appelée (si nécessaire).

Exemple

Je veux changer le name de mes sections dans rapport, par "partie": je changerai le name de section.model, et dans les deux modèles qui l'appellent: chapter.model et report.model, je changerai le name de la part "sect".

Changer le name de la composition

Le code de section.model.exec.xsl contiendrait alors: 

<xsl:template match="sm:compositionPrim">
	<sm:compositionPrim xmlns:sc="http://www.utc.fr/ics/scenari/v3/core" xmlns:sm="http://www.utc.fr/ics/scenari/v3/modeling" name="Partie" category="Contenu">
	<xsl:apply-templates select="@*[name()!='name']|node()"/>
	</sm:compositionPrim>

</xsl:template>

JRE de Sun

Sous linux, on peut vous demander de spécifier explicitement la jre à utiliser : (exemple pour ubuntu) 

export JAVA_HOME=/usr/lib/jvm/java-6-sun-1.6.0.10/

ou, pour modifier de façon permanente, il faut utiliser la fonction : 

sudo update-alternatives --config java

et choisir la configuration java de sun