1 ================================================================
2 Guide pour le développement d'un module SALOME 2 en Python
3 ================================================================
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
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.
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.
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.
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 ===================================== ========= ============= ==================================
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
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.
60 Les différentes étapes du développement seront les suivantes :
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
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
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
104 Les fichiers runAppli et runSalome.py ne sont pas indispensables mais facilitent la mise en
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.
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
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.
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.
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.
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.
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
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.
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.
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.
156 Le Makefile se contente de déclencher le parcours des sous répertoires qui sont
157 décrits par la cible SUBDIRS.
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.
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.
170 Il ne contient rien pour le moment. Il pourrait contenir ce document.
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
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.
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.
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.
192 Toutes les étapes suivantes supposent que les logiciels prérequis de SALOME sont accessibles dans l'environnement
193 du développeur de modules.
195 Construction, installation
196 ---------------------------------
197 Dans PYHELLO1_SRC, faire::
199 export KERNEL_ROOT_DIR=<chemin d'installation du module KERNEL>
202 Aller dans ../PYHELLO1_BUILD et faire::
204 ../PYHELLO1_SRC/configure --prefix=<chemin d'installation du module PYHELLO1>
208 Lancement de la plate-forme
209 -------------------------------
210 Aller dans <chemin d'installation du module PYHELLO1> et faire::
212 ./bin/salome/runAppli
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.
218 runAppli est un shell qui exécute un script Python en lui passant des arguments en ligne de
221 python -i $PYHELLO_ROOT_DIR/bin/salome/runSalome.py --modules=PYHELLO --xterm --containers=cpp,python --killall
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.
227 Pour que cette commande fonctionne, il faut préalablement avoir positionné les variables d'environnement
230 export KERNEL_ROOT_DIR=<chemin d'installation du module KERNEL>
231 export PYHELLO_ROOT_DIR=<chemin d'installation du module PYHELLO>
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.
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
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::
253 c=container.load_impl("PYHELLO","PYHELLO")
254 c.makeBanner("Christian")
256 La dernière instruction doit retourner 'Hello Christian'.
257 Pour voir les objets CORBA créés par ces actions, faire::
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.
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.
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::
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.
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::
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::
305 ./bin/salome/runAppli
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. ::
314 c.makeBanner("Christian")
316 La fonction test crée le LifeCycle. Puis elle demande le chargement du composant PYHELLO
317 dans le container FactoryServerPy::
321 Test function that creates an instance of PYHELLO component
322 usage : pyhello=test(clt)
324 import LifeCycleCORBA
325 lcc = LifeCycleCORBA.LifeCycleCORBA(clt.orb)
327 pyhello = lcc.FindOrLoadComponent("FactoryServerPy", "PYHELLO")
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::
336 <component-icone>PYHELLO.png</component-icone>
338 et de mettre le fichier correspondant dans le répertoire resources du module.
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::
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::
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.
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.
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.
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).
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.
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.
391 Etapes ultérieures restant à décrire
392 ==========================================
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
401 Rapides rappels sur l'architecture SALOME 2
402 ==================================================
405 Dans SALOME, les composants sont dynamiquement chargeables. Cette propriété est obtenu
406 en utilisant un mécanisme de container.
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.
413 La mécanique de base du chargement d'un composant est dépendante du langage d'implantation choisi.
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.
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
424 -----------------------
427 Les logiciels prérequis
428 ---------------------------