doc/pysalome.rst

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