6 ================================================================
7 Guide for the development of a SALOME module in Python
8 ================================================================
10 The purpose of this document is to describe briefly the different steps in the development of a SALOME module
13 Steps in construction of the example module
14 ====================================================
15 The example module chosen to illustrate the process to construct a module is extremely simple.
16 It will contain a single component and this component will have a single service called getBanner that
17 will accept a character string as the sole argument and that will return a character string obtained by
18 concatenation of “Hello” and the input chain. This component will be completed by a graphic GUI written in PyQt.
20 The different steps in the development will be as follows:
22 - create a module tree structure
23 - create a SALOME component that can be loaded by a Python container
24 - configure the module so that the component is known to SALOME
27 Create the module tree structure
28 =======================================
29 Firstly, we will simply put a SALOME component written in Python and that can be loaded by a Python
30 container, into the example module. An idl interface and a Python implementation of the component will be
31 all that are necessary.
32 The following file structure is necessary so that this can be implemented in a SALOME module::
42 + make_common_starter.am
61 The module name is PYHELLO, the component name is PYHELLO and all the files will be put in a directory named PYHELLO1_SRC.
62 All files are essential except for VERSION.in, runAppli.in and runSalome.py.
63 VERSION.in is used to document the module, it must give its version and its compatibilities or
64 incompatibilities with other modules. Therefore, it is strongly recommended but is not essential for operation.
65 The runAppli.in and runSalome.py files are not essential but make the example easier to use.
69 the files of the basic platform (KERNEL) must not be copied to initialise a module tree structure.
70 It is usually preferable to copy files from another module such as GEOM or MED.
72 Implementation of automake, configure
73 --------------------------------------
74 SALOME uses autoconf and automake to build the configure script that is used for the installation to test
75 the system configuration and to preconfigure the module construction Makefile files.
76 The build_configure file contains a procedure that starts from configure.ac and uses automake to build
78 automake starts from Makefile.am files to build Makefile.in files.
79 All files with an "in" extension are skeletons that will be transformed by the configure process.
81 Almost all files used for this process are located in the basic platform that is referenced by the
82 KERNEL_ROOT_DIR environment variable as well as GUI_ROOT_DIR for the graphical user interface (GUI).
83 However, some files must be modified as a function of the target
84 module. This is the case for build_configure and configure.ac files that usually need to be adapted.
86 The basic files for configuration of the KERNEL module and other modules are collected in the salome_adm
87 directory of the KERNEL module. However, in order to be able to use the CORBA objects of the KERNEL module,
88 the files in the salome_adm directory have to be overwritten, using the make_common_starter.am file in
89 the adm_local directory of the example module.
91 config_files is a directory in which the m4 files that are used to test the configuration of the system in the
92 configure process can be placed. If the salome_adm files are not sufficient, others can be added in adm_local.
95 --------------------------------------
96 The idl directory requires a Makefile.am that must make the compilation of the idl PYHELLO_Gen.idl file
97 and install all the generated files in the right module installation directories. The BASE_IDL_FILES target has
98 to be modified to reach this goal.
100 The idl file itself must define a CORBA module for which the name must be different from the module
101 name to avoid name conflicts and define a CORBA interface that is derived at least from the EngineComponent interface of the Engines module.
102 The name of the CORBA module will be PYHELLO_ORB and the name of the interface will be PYHELLO_Gen.
105 --------------------------------------
106 The src directory will contain all components and the GUI for the module. Each of these entities must have
109 For the moment, the module will only contain a single directory for the engine of the PYHELLO component
110 and its name will be PYHELLO.
112 The Makefile.am will simply trigger the path of sub-directories described by the SUBDIRS target.
114 The PYHELLO directory
115 '''''''''''''''''''''''
116 This directory contains the Python module that represents the component and therefore contains the PYHELLO class
117 and a Makefile.am file that simply exports the PYHELLO.py module into the installation directory of the SALOME module.
119 The PYHELLO.py module contains the PYHELLO class that is derived from the PYHELLO_Gen interface of the CORBA
120 PYHELLO_ORB_POA module and the SALOME_ComponentPy_i class of the SALOME_ComponentPy module.
123 --------------------------------------
124 This contains nothing for the moment. It could contain this document.
127 --------------------------------------
128 VERSION.in is used to document the module, it must define its version and its compatibilities
129 or incompatibilities with other modules. Therefore, it is strongly recommended but is not essential for operation.
131 The runAppli.in file is the equivalent of the runSalome in the KERNEL module configured to implement the KERNEL
132 module and this PYHELLO module.
134 The myrunSalome.py file is the file of the KERNEL module modified to run only with a Python container,
135 with the test function that creates the PYHELLO component instead of a MED component,
136 and automatic completion in Python.
138 Creating a component that can be loaded by a container
139 ======================================================
140 The files presented above are sufficient to build and install the PYHELLO1_SRC module, to start
141 the SALOME platform composed of the KERNEL and PYHELLO1 modules, and to request the Python container
142 to load a PYHELLO component.
144 All the following steps are only possible if the SALOME prerequisite software is accessible in the module
145 developer environment.
147 Construction, installation
148 ---------------------------------
149 In PYHELLO1_SRC, enter::
151 export KERNEL_ROOT_DIR=<KERNEL installation path>
154 Go into ../PYHELLO1_BUILD and enter::
156 ../PYHELLO1_SRC/configure --prefix=<PYHELLO1 installation path>
161 -------------------------------
162 Move into the <PYHELLO1 module installation path> and enter::
164 ./bin/salome/runAppli
166 This command runs SALOME configured for KERNEL and the PYHELLO1 module. At the end of running,
167 the user sees a Python interpreter configured for SALOME that provides access to SALOME CORBA objects.
169 runAppli is a shell that executes a Python script, by passing arguments to it in a command line::
171 python -i $PYHELLO_ROOT_DIR/bin/salome/myrunSalome.py --modules=PYHELLO --killall
173 These arguments state that the myrunSalome.py script located in the PYHELLO module will be used, that the PYHELLO
174 component will be activated and all SALOME processes that existed before the run will be killed.
176 This command will not function unless the following environment variables have previously been set::
178 export KERNEL_ROOT_DIR=<KERNEL installation path>
179 export PYHELLO_ROOT_DIR=<PYHELLO installation path>
183 it is possible that the SALOME run will not reach the end. In some circumstances, the time to
184 start CORBA servers may be long and could exceed the timeout. If the reason for
185 this is that the time to load dynamic libraries is long, it is possible that a second run immediately
186 afterwards will be successful.
188 Loading the example component
189 ------------------------------------
190 The PYHELLO_ORB module has to be imported before making a request to load the component into the Python
191 container, to obtain access to methods of the component. This Python container was made accessible
192 in the runSalome.py by means of the container variable::
195 c=container.load_impl("PYHELLO","PYHELLO")
196 c.makeBanner("Christian")
198 The last instruction must return ‘Hello Christian’.
200 Proceed as follows to see CORBA objects created by these actions::
204 Declared SALOME component
205 ==============================
206 For the moment, the PYHELLO component was loaded by making a direct request to the Python container. This is
207 not the standard method for loading a component. The normal method uses the LifeCycle service that uses
208 catalog services to identify the component and its properties and then calls the requested container to load the component.
210 Before this method can be used, the component must be declared in a catalog in the XML format, for which
211 the name must be <Module>Catalog.xml. In our case, it will be PYHELLOCatalog.xml. This catalog will be stored in
212 the resources directory.
214 Updated tree structure::
228 The remainder of the files are identical, apart from adding the resources directory and the PYHELLOCatalog.xml file.
229 However, the Makefile.am has to be modified so that the catalog is actually installed in the installation
230 directory. It simply needs to be specified in the salomeres_SCRIPTS target.
232 Construction, installation
233 ---------------------------------
234 There is no need to do another configure to take account of this modification.
235 All that is necessary is to enter PYHELLO1_BUILD and then::
241 Starting the platform
242 -------------------------------
243 The platform is started in the same way as before. Go into PYHELLO1_INSTALL and do::
245 ./bin/salome/runAppli
247 Loading the example component
248 ------------------------------------
249 The method of loading the component is not very different from that described above. The services of the
250 LifeCycle module are used in this case instead of calling the container directly.
251 The call sequence is contained in the runSalome.Py test function. ::
254 c.makeBanner("Christian")
256 The test function creates the LifeCycle. It then asks for the PYHELLO component to be loaded in the FactoryServerPy container::
260 Test function that creates an instance of PYHELLO component
261 usage : pyhello=test(clt)
263 import LifeCycleCORBA
264 lcc = LifeCycleCORBA.LifeCycleCORBA(clt.orb)
266 pyhello = lcc.FindOrLoadComponent("FactoryServerPy", "PYHELLO")
269 Loading from the application interface (IAPP)
270 ----------------------------------------------------------
271 Before a component can be loaded dynamically using the IAPP components bar, the icon representing the
272 component will have to be declared in the catalog.
273 It is declared by simply adding a line for the icon to the component catalog::
275 <component-icon>PYHELLO.png</component-icon>
277 and putting the corresponding file in the module resources directory.
280 ===========================
281 The next step to complete the module consists of adding a graphic interface to the PYHELLO component, that will
282 be written in Python using the Qt widgets library. This graphic interface must be integrated into the SALOME
283 application interface (IAPP), and therefore must respect some constraints that we will see.
285 Firstly note the contour of the GUI of a component. The behaviour of the GUI is given by a Python module
286 that has a standard name <Module>GUI.py. It must propose conventional entry points that the IAPP will use to
287 activate this GUI or to inform it of specific events. GUI commands are activated through a menu bar and a
288 button bar that are integrated into the menu bar and into the IAPP button bar.
290 Python module implanting the behaviour of the GUI
291 -----------------------------------------------------
292 The behaviour of the PYHELLO component GUI is implanted in the Python PYHELLOGUI.py module in the
293 PYHELLOGUI sub-directory. The Makefile.am located in the src directory must be updated to include
294 the PYHELLOGUI subdirectory. A Makefile.am must be added into the PYHELLOGUI subdirectory.
295 Important targets are salomescript_SCRIPTS and salomeres_DATA.
297 The salomescript_SCRIPTS target must be updated with the name of the Python modules to be made visible in Salome, in other
298 words mainly so that they are importable (Python import command).
300 The salomeres_DATA target must be updated with the names of files that are used for multi-linguism.
302 Menu bar and button bar
303 ----------------------------------
304 The menu bar and button bar for the PYHELLO component are dynamically added when importing the PYHELLOGUI module.
305 They are created by calling the Python functions createMenu, createAction and createTool from the sgPyQt SALOME
306 interface object. Every action must have a unique id.
307 Some icons are used. They must be installed in the resources directory.