6 ================================================================
7 Guide pour le développement d'un module SALOME en Python
8 ================================================================
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
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.
25 Les différentes étapes du développement seront les suivantes :
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
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
49 + make_common_starter.am
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
73 Les fichiers runAppli.in et runSalome.py ne sont pas indispensables mais facilitent la mise en
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.
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
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.
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.
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.
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.
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
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.
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.
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.
125 Le Makefile se contente de déclencher le parcours des sous répertoires qui sont
126 décrits par la cible SUBDIRS.
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.
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.
139 Il ne contient rien pour le moment. Il pourrait contenir ce document.
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
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.
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.
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.
161 Toutes les étapes suivantes supposent que les logiciels prérequis de SALOME sont accessibles dans l'environnement
162 du développeur de modules.
164 Construction, installation
165 ---------------------------------
166 Dans PYHELLO1_SRC, faire::
168 export KERNEL_ROOT_DIR=<chemin d'installation du module KERNEL>
171 Aller dans ../PYHELLO1_BUILD et faire::
173 ../PYHELLO1_SRC/configure --prefix=<chemin d'installation du module PYHELLO1>
177 Lancement de la plate-forme
178 -------------------------------
179 Aller dans <chemin d'installation du module PYHELLO1> et faire::
181 ./bin/salome/runAppli
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.
187 runAppli est un shell qui exécute un script Python en lui passant des arguments en ligne de
190 python -i $PYHELLO_ROOT_DIR/bin/salome/runSalome.py --modules=PYHELLO --xterm --containers=cpp,python --killall
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.
196 Pour que cette commande fonctionne, il faut préalablement avoir positionné les variables d'environnement
199 export KERNEL_ROOT_DIR=<chemin d'installation du module KERNEL>
200 export PYHELLO_ROOT_DIR=<chemin d'installation du module PYHELLO>
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.
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
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::
222 c=container.load_impl("PYHELLO","PYHELLO")
223 c.makeBanner("Christian")
225 La dernière instruction doit retourner 'Hello Christian'.
226 Pour voir les objets CORBA créés par ces actions, faire::
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.
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::
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.
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::
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::
270 ./bin/salome/runAppli
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. ::
279 c.makeBanner("Christian")
281 La fonction test crée le LifeCycle. Puis elle demande le chargement du composant PYHELLO
282 dans le container FactoryServerPy::
286 Test function that creates an instance of PYHELLO component
287 usage : pyhello=test(clt)
289 import LifeCycleCORBA
290 lcc = LifeCycleCORBA.LifeCycleCORBA(clt.orb)
292 pyhello = lcc.FindOrLoadComponent("FactoryServerPy", "PYHELLO")
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::
301 <component-icone>PYHELLO.png</component-icone>
303 et de mettre le fichier correspondant dans le répertoire resources du module.
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::
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::
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.
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.
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.
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).
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.
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.