doc/dev_guide.txt

   1 ================================================================
   2 Guide pour le développement d'un module SALOME 2 en Python
   3 ================================================================
   4
   5 :Auteur: Caremoli C.
   6
   7 .. contents::
   8 .. sectnum::
   9
  10 Présentation
  11 =========================
  12 Ce document a pour objectif de décrire les différentes étapes
  13 du développement d'un module SALOME 2 en Python.
  14 Il commence par un bref rappel des principes de SALOME 2. Puis, il décrit
  15 les étapes successives qui seront suivies pour arriver à une configuration
  16 de module complète.
  17
  18 Rappels sur les modules et composants SALOME 2
  19 ==================================================
  20 Dans son principe, la plate-forme SALOME 2 est décomposée en une plate-forme
  21 de base nommée module KERNEL et une collection de modules divers.
  22
  23 Un module est un produit compilable et installable qui se concrétise par une arborescence source qui doit
  24 respecter les règles générales SALOME2 et qui comprend une procédure de construction, installation qui
  25 respecte également les règles SALOME2.
  26 Chaque module est géré en configuration dans un module CVS
  27 indépendant. Chaque module peut livrer des versions à son rythme dans le respect des règles de
  28 cohérence de SALOME2. A chaque module est associée une base de tests de non régression.
  29
  30 Un module a des dépendances avec les autres modules (utilise, est utilisé).
  31 Le module KERNEL constitue la base de la plate-forme SALOME2.
  32 Tous les autres modules dépendent du module KERNEL.
  33
  34 ===================================== ========= ============= ==================================
  35 Sous projets                           Modules    Utilise          Est utilisé par
  36 ===================================== ========= ============= ==================================
  37 SP1 - Environnement de production
  38 SP2 - Architecture                     KERNEL                  MED, GEOM, SMESH, VISU,SUPERV
  39 SP2 - Architecture                     MED       KERNEL         SMESH, VISU
  40 SP3 - Géométrie                        GEOM      KERNEL         SMESH
  41 SP5 - Maillage                         SMESH     KERNEL, MED
  42 SP6 - Superviseur                      SUPERV    KERNEL
  43 SP7 - Visualisation                    VISU      KERNEL, MED
  44 ===================================== ========= ============= ==================================
  45
  46 Un module contient un ou plusieurs composants SALOME. Un composant SALOME est un objet CORBA qui
  47 respecte les règles SALOME et qui est déclaré à SALOME au moyen d'un catalogue. Un composant SALOME
  48 peut être doté d'une interface utilisateur graphique (GUI) qui doit elle-même respecter les règles
  49 SALOME.
  50
  51 Les étapes de construction du module exemple
  52 ====================================================
  53 Le module exemple choisi pour illustrer le processus de construction d'un
  54 module est extrèmement simple. Il contiendra un seul composant et ce composant
  55 aura un seul service nommé getBanner qui acceptera une chaine de caractères
  56 comme unique argument et qui retournera une chaine de caractères obtenue
  57 par concaténation de "Hello " et de la chaine d'entrée. Ce composant sera
  58 complété par un GUI graphique écrit en PyQt.
  59
  60 Les différentes étapes du développement seront les suivantes :
  61
  62   - créer une arborescence de module
  63   - créer un composant SALOME 2 chargeable par un container Python
  64   - configurer le module pour que le composant soit connu de SALOME
  65   - ajouter un GUI graphique
  66   - rendre le composant utilisable dans le superviseur
  67
  68 Création de l'arborescence du module
  69 =======================================
  70 Dans un premier temps, on se contentera de mettre dans le module exemple un composant
  71 SALOME écrit en Python qui sera chargeable par un container Python.
  72 Il suffit donc d'une interface idl et d'une implantation Python du composant.
  73 Pour mettre en oeuvre ceci dans un module SALOME 2, il faut l'arborescence de
  74 fichier suivante::
  75
  76   + PYHELLO1_SRC
  77     + build_configure
  78     + configure.in.base
  79     + Makefile.in
  80     + adm_local
  81       + unix
  82         + make_commence.in
  83         + make_omniorb.in
  84         + config_files
  85     + bin
  86       + VERSION
  87       + runAppli.in
  88       + runSalome.py
  89     + idl
  90       + Makefile.in
  91       + PYHELLO_Gen.idl
  92     + src
  93       + Makefile.in
  94       + PYHELLO
  95         + Makefile.in
  96         + PYHELLO.py
  97     + doc
  98
  99 Le module a pour nom PYHELLO1_SRC et le composant PYHELLO.
 100 Tous les fichiers sont indispensables à l'exception de VERSION, runAppli et runSalome.py.
 101 VERSION sert pour documenter le module, il doit donner sa version et ses compatibilités ou
 102 incompatibilités avec les autres modules. Il est donc fortement recommandé mais pas indispensable
 103 au fonctionnement.
 104 Les fichiers runAppli et runSalome.py ne sont pas indispensables mais facilitent la mise en
 105 oeuvre de l'exemple.
 106
 107 Mise en garde : il ne faut pas copier les fichiers de la plate-forme de base (KERNEL) pour
 108 initialiser une arborescence de module. Il est, en général, préférable de copier les fichiers
 109 d'un autre module comme GEOM ou MED.
 110
 111 Mise en oeuvre d'autoconf, configure
 112 --------------------------------------
 113 SALOME utilise autoconf pour construire le script configure qui sert à l'installation pour
 114 tester la configuration du système et pour préconfigurer les fichiers Makefile de contruction
 115 du module.
 116 Le fichier build_configure contient une procédure qui à partir de configure.in.base et au moyen
 117 d'autoconf construit le script configure.
 118 Tous les fichiers dont l'extension est in sont des squelettes qui seront transformés par le
 119 processus de configure.
 120
 121 Presque tous les fichiers utilisés pour ce processus sont localisés dans la plate-forme de
 122 base qui est référencée par la variable d'environnement KERNEL_ROOT_DIR. Cependant quelques
 123 fichiers doivent être modifiés en fonction du module cible. C'est le cas bien sur de build_configure
 124 et de configure.in.base qui doivent en général adaptés.
 125
 126 Les fichiers de base pour le configure du module KERNEL et des autres modules sont rassemblés
 127 dans le répertoire salome_adm du module KERNEL. Il faut cependant, pour pouvoir utiliser les objets
 128 CORBA du module KERNEL surcharger les fichiers make_commence.in et make_omniorb.in du répertoire
 129 salome_adm. Cette surcharge est réalisée en mettant les fichiers make_commence.in et make_omniorb.in
 130 modifiés dans le répertoire adm_local du module exemple.
 131
 132 config_files est un répertoire dans lequel on peut mettre les fichiers m4 qui servent à tester
 133 la configuration du système dans le processus de configure. Si les fichiers de salome_adm ne sont pas
 134 suffisants, on peut en ajouter dans adm_local.
 135
 136 Répertoire idl
 137 ------------------
 138 Dans le répertoire idl, il faut un Makefile qui doit mettre en oeuvre la compilation
 139 du fichier idl PYHELLO_Gen.idl et installer tous ces fichiers dans les bons répertoires
 140 de l'installation du module. Il suffit de modifier la cible IDL_FILES pour obtenir
 141 un fichier adapté.
 142
 143 Concernant le fichier idl lui-même, il doit définir un module CORBA dont le nom
 144 doit être différent du nom du module pour éviter les conflits de nom et définir une
 145 interface CORBA qui dérive à minima de l'interface Component du module Engines.
 146 Le nom du module CORBA sera PYHELLO_ORB et le nom de l'interface PYHELLO_Gen.
 147
 148 Répertoire src
 149 ------------------
 150 Le répertoire src contiendra tous les composants et GUI graphiques du module. Chacune
 151 de ces entités doit avoir son propre répertoire.
 152
 153 Le module ne contiendra pour le moment qu'un seul répertoire pour le moteur du
 154 composant PYHELLO et son nom sera PYHELLO.
 155
 156 Le Makefile se contente de déclencher le parcours des sous répertoires qui sont
 157 décrits par la cible SUBDIRS.
 158
 159 Répertoire PYHELLO
 160 '''''''''''''''''''''''
 161 Le répertoire contient le module Python qui représente le composant et donc contient la classe PYHELLO
 162 et un fichier Makefile dont le rôle est simplement d'exporter le module PYHELLO.py
 163 dans le répertoire d'installation du module SALOME.
 164
 165 Le module PYHELLO.py contient la classe PYHELLO qui dérive de l'interface PYHELLO_Gen du
 166 module CORBA PYHELLO_ORB__POA et de la classe SALOME_ComponentPy_i du module SALOME_ComponentPy.
 167
 168 Répertoire doc
 169 ------------------
 170 Il ne contient rien pour le moment. Il pourrait contenir ce document.
 171
 172 Répertoire bin
 173 ------------------
 174 VERSION sert pour documenter le module, il doit donner sa version et ses compatibilités ou
 175 incompatibilités avec les autres modules. Il est donc fortement recommandé mais pas indispensable
 176 au fonctionnement.
 177
 178 Le fichier runAppli.in est l'équivalent du runSalome du module KERNEL configuré pour mettre
 179 en oeuvre le module KERNEL et ce module PYHELLO.
 180
 181 Le fichier runSalome.py est le fichier du module KERNEL avec une correction de bug pour
 182 tourner seulement avec un container Python, une modification de la fonction test qui crée
 183 le composant PYHELLO au lieu d'un composant MED et un développement pour disposer de
 184 la complétion automatique en Python.
 185
 186 Création d'un composant chargeable par un container
 187 ======================================================
 188 Les fichiers présentés ci-dessus suffisent pour construire et installer le module PYHELLO1_SRC,
 189 lancer la plate-forme SALOME constituée  des modules KERNEL et PYHELLO1 et demander au container
 190 Python le chargement d'un composant PYHELLO.
 191
 192 Toutes les étapes suivantes supposent que les logiciels prérequis de SALOME sont accessibles dans l'environnement
 193 du développeur de modules.
 194
 195 Construction, installation
 196 ---------------------------------
 197 Dans PYHELLO1_SRC, faire::
 198
 199      export KERNEL_ROOT_DIR=<chemin d'installation du module KERNEL>
 200      ./build_configure
 201
 202 Aller dans ../PYHELLO1_BUILD et faire::
 203
 204      ../PYHELLO1_SRC/configure --prefix=<chemin d'installation du module PYHELLO1>
 205      make
 206      make install
 207
 208 Lancement de la plate-forme
 209 -------------------------------
 210 Aller dans <chemin d'installation du module PYHELLO1> et faire::
 211
 212     ./bin/salome/runAppli
 213
 214 Cette commande lance SALOME configurée pour KERNEL et le module PYHELLO1. A la fin de ce
 215 lancement l'utilisateur est devant un interpréteur Python configuré pour SALOME et qui
 216 donne accès aux objets CORBA de SALOME.
 217
 218 runAppli est un shell qui exécute un script Python en lui passant des arguments en ligne de
 219 commande::
 220
 221     python -i $PYHELLO_ROOT_DIR/bin/salome/runSalome.py --modules=PYHELLO --xterm --containers=cpp,python --killall
 222
 223 Ces arguments indiquent que l'on prendra le script runSalome.py situé dans le module PYHELLO, que l'on
 224 activera le composant PYHELLO, les impressions seront redirigées dans une fenêtre xterm, on lancera un
 225 container Python et tous les processus SALOME existant avant le lancement seront tués.
 226
 227 Pour que cette commande fonctionne, il faut préalablement avoir positionné les variables d'environnement
 228 suivantes::
 229
 230    export KERNEL_ROOT_DIR=<chemin d'installation du module KERNEL>
 231    export PYHELLO_ROOT_DIR=<chemin d'installation du module PYHELLO>
 232
 233 Cette méthode d'activation des modules et composants de SALOME 2 tend à confondre module et composant.
 234 Dans ce cas (1 composant par module), il n'y a pas de difficulté à paramétrer le lancement. Il suffit d'indiquer derrière
 235 l'option --modules la liste des composants demandés (KERNEL est inutile) et de fournir autant de variables
 236 d'environnement qu'il y a de composants. Le nom de ces variables doit être <Composant>_ROOT_DIR et doit donner le chemin
 237 du module contenant le composant. Dans le cas où on a plusieurs composants par module, c'est un peu plus
 238 compliqué. Ce sera présenté ultérieurement.
 239
 240 Mise en garde: il est possible que le lancement de SALOME 2 n'aille pas jusqu'au bout. En effet
 241 dans certaines circonstances, le temps de lancement des serveurs CORBA peut être long et dépasser
 242 le timeout fixé à 21 secondes. Si la raison en est le temps de chargement important des
 243 bibliothèques dynamiques, il est possible qu'un deuxième lancement dans la foulée aille
 244 jusqu'au bout.
 245
 246 Chargement du composant exemple
 247 ------------------------------------
 248 Pour avoir accès aux méthodes du composant, il faut importer le module PYHELLO_ORB avant
 249 de demander le chargement du composant au container Python. Ce container Python
 250 a été rendu accessible dans runSalome.py au moyen de la variable container::
 251
 252     import PYHELLO_ORB
 253     c=container.load_impl("PYHELLO","PYHELLO")
 254     c.makeBanner("Christian")
 255
 256 La dernière instruction doit retourner 'Hello Christian'.
 257 Pour voir les objets CORBA créés par ces actions, faire::
 258
 259     clt.showNS()
 260
 261 On peut voir que le composant a été créé et enregistré dans un contexte de nommage qui peut
 262 être incorrect en raison d'un bug identifié dans la version 1.2.1 du module KERNEL.
 263
 264
 265 Composant SALOME déclaré
 266 ==============================
 267 Pour le moment, le composant PYHELLO a été chargé en faisant une requête directe au container
 268 Python. Ce n'est pas la méthode standard pour charger un composant. La voie normale passe
 269 par le service LifeCycle qui utilise les services du catalogue pour identifier le composant
 270 et ses propriétés puis appelle le container demandé pour charger le composant.
 271
 272 Pour pouvoir utiliser cette méthode, il faut déclarer le composant dans un catalogue au format XML dont le
 273 nom doit  être <Composant>Catalog.xml. Dans notre cas ce sera PYHELLOCatalog.xml. Ce catalogue sera rangé
 274 dans le répertoire resources. Arborescence actualisée::
 275
 276   + PYHELLO1_SRC
 277     + build_configure
 278     + configure.in.base
 279     + Makefile.in
 280     + adm_local
 281     + bin
 282     + idl
 283     + src
 284     + doc
 285     + resources
 286       + PYHELLOCatalog.xml
 287
 288 En dehors de l'ajout du répertoire resources et du fichier PYHELLOCatalog.xml, le reste des fichiers
 289 est identique. Il faut cependant modifier le Makefile.in de tête pour que le catalogue soit bien installé
 290 dans le répertoire d'installation. Il suffit de le spécifier dans la cible RESOURCES_FILES.
 291
 292 Construction, installation
 293 ---------------------------------
 294 Il n'est pas nécessaire de refaire un configure pour prendre en compte cette modification. Il
 295 suffit d'aller dans PYHELLO1_BUILD et de faire::
 296
 297     ./config.status
 298     make
 299     make install
 300
 301 Lancement de la plate-forme
 302 -------------------------------
 303 Le lancement de la plate-forme se passe de la même manière que précédemment. Aller dans PYHELLO1_INSTALL et faire::
 304
 305     ./bin/salome/runAppli
 306
 307 Chargement du composant exemple
 308 ------------------------------------
 309 La méthode de chargement du composant n'est pas très différente de la fois précédente. On
 310 utiilise maintenant les services du module LifeCycle au lieu d'appeler directement le container.
 311 La séquence d'appel est contenue dans la fonction test de runSalome.Py. ::
 312
 313     c=test(clt)
 314     c.makeBanner("Christian")
 315
 316 La fonction test crée le LifeCycle. Puis elle demande le chargement du composant PYHELLO
 317 dans le container FactoryServerPy::
 318
 319   def test(clt):
 320        """
 321         Test function that creates an instance of PYHELLO component
 322         usage : pyhello=test(clt)
 323        """
 324        import LifeCycleCORBA
 325        lcc = LifeCycleCORBA.LifeCycleCORBA(clt.orb)
 326        import PYHELLO_ORB
 327        pyhello = lcc.FindOrLoadComponent("FactoryServerPy", "PYHELLO")
 328        return pyhello
 329
 330 Chargement depuis l'interface applicative (IAPP)
 331 ----------------------------------------------------------
 332 Pour pouvoir charger dynamiquement un composant en utilisant la barre à composants
 333 de l'IAPP, il faut déclarer l'icone représentative du composant dans le catalogue.
 334 Pour la déclarer il suffit d'ajouter une ligne pour l'icone au catalogue du composant::
 335
 336       <component-icone>PYHELLO.png</component-icone>
 337
 338 et de mettre le fichier correspondant dans le répertoire resources du module.
 339
 340 Pour tester la bonne configuration de la barre à composants, lancer SALOME 2 comme
 341 précédemment puis à partir de l'interpréteur Python lancer l'IAPP par::
 342
 343       startGUI()
 344
 345 et charger le composant en cliquant sur l'icone de PYHELLO après avoir ouvert une étude. L'IAPP doit
 346 signaler que le GUI du composant n'est pas correctement configuré mais le composant sera quand
 347 même créé après un temps d'attente. On peut le constater en tapant::
 348
 349      clt.showNS()
 350
 351 Ajout d'un GUI graphique
 352 ===========================
 353 L'étape suivante pour compléter le module consiste à ajouter au composant PYHELLO
 354 une interface graphique qui sera écrite en Python en utilisant la bibliothèque de
 355 widgets Qt. Cette interface graphique doit s'intégrer dans l'interface applicative
 356 de SALOME (IAPP) et doit donc respecter certaines contraintes que nous allons voir.
 357
 358 Tout d'abord, précisons le contour du GUI d'un composant.
 359 Le comportement du GUI est
 360 donné par un module Python dont le nom est normalisé <Composant>GUI.py. Il doit
 361 proposer des points d'entrée conventionnels qui seront utilisés par l'IAPP pour activer
 362 ce GUI ou l'informer de certains évènements.
 363 L'activation des commandes du GUI est réalisée au moyen d'une barre de menu et d'une barre
 364 à boutons qui s'intègrent dans la barre à menus et dans la barre à boutons de l'IAPP.
 365
 366
 367 Module Python implantant le comportement du GUI
 368 -----------------------------------------------------
 369 Le comportement du GUI du composant PYHELLO est implanté dans le module Python PYHELLOGUI.py
 370 du sous-répertoire PYHELLOGUI.
 371 Le Makefile.in localisé dans le répertoire src doit être actualisé pour parcourir le sous-répertoire PYHELLOGUI.
 372 Un Makefile.in doit être ajouté dans le sous-répertoire PYHELLOGUI. Les cibles
 373 importantes sont PO_FILES et EXPORT_PYSCRIPTS.
 374
 375 La cible EXPORT_PYSCRIPTS doit être mise à jour avec le nom des modules Python à rendre visible
 376 dans Salome, c'est à dire principalement pour qu'ils soient importables (commande import de Python).
 377
 378 La cible PO_FILES doit être mise à jour avec les noms des fichiers qui sont utilisés pour le multi-linguisme.
 379 Pour le moment le fichier PYHELLO_msg_en.po (traduction pour langue anglaise) est vide car le multi-linguisme
 380 n'est pas mis en oeuvre dans cet exemple.
 381
 382 Barre à menus et barre à boutons
 383 ----------------------------------
 384 Les barres à menus et à boutons du composant PYHELLO sont décrites dans un fichier au format XML
 385 pour permettre leur chargement dynamique dans l'IAPP. Ce fichier est localisé dans le répertoire resources
 386 du module et a un nom standardisé <Composant>_en.xml pour la langue anglaise. Pour la langue française, il
 387 faut également un fichier de nom <Composant>_fr.xml.
 388 Pour le composant PYHELLO, le fichier PYHELLO_en.xml contient un menu avec un item et un bouton.
 389 L'icone du bouton est fournie par le fichier ExecPYHELLO.png localisé dans le répertoire resources du module.
 390
 391 Etapes ultérieures restant à décrire
 392 ==========================================
 393
 394      - lien avec l'étude
 395      - lien avec la sélection
 396      - ajout d'un popup contextuel
 397      - comment rendre le composant supervisable
 398      - ajout de la persistance
 399      - avoir plusieurs composants dans le même module
 400
 401 Rapides rappels sur l'architecture SALOME 2
 402 ==================================================
 403 Les containers
 404 --------------------
 405 Dans SALOME, les composants sont dynamiquement chargeables. Cette propriété est obtenu
 406 en utilisant un mécanisme de container.
 407
 408 Dans ses grandes lignes, un container est un serveur CORBA dont l'interface dispose
 409 des méthodes nécessaires pour effectuer le chargement déchargement de l'implantation
 410 d'un composant SALOME. Pour effectuer le chargement d'un composant, on appellera la méthode
 411 load_impl du container.
 412
 413 La mécanique de base du chargement d'un composant est dépendante du langage d'implantation choisi.
 414
 415 En C++, la plate-forme utilise le chargement dynamique de bibliothèque (dlopen) et un mécanisme de fonction
 416 factory dont le nom doit être <Module>Engine_factory (par exemple GEOMEngine_factory, pour GEOM).
 417 Cette fonction doit retourner l'objet CORBA effectif qui est le composant SALOME.
 418
 419 En Python, la plate-forme utilise le mécanisme d'import de Python (import <Module>) et instancie
 420 le composant SALOME Python en utilisant une classe (ou une factory) de même nom (<Module>) pour
 421 ce faire.
 422
 423 Le multi-linguisme
 424 -----------------------
 425 A compléter
 426
 427 Les logiciels prérequis
 428 ---------------------------
 429 A compléter
 430
 431
 432