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