doc/pysalome.rst

   1
   2 :tocdepth: 3
   3
   4 .. _pysalome:
   5
   6 ================================================================
   7 Guide for the development of a SALOME module in Python
   8 ================================================================
   9
  10 The purpose of this document is to describe briefly the different steps in the development of a SALOME module
  11 in Python.
  12
  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.
  19
  20 The different steps in the development will be as follows:
  21
  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
  25  - add a graphic GUI
  26
  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::
  33
  34   + PYHELLO1_SRC
  35     + build_configure
  36     + configure.ac
  37     + Makefile.am
  38     + adm_local
  39       + Makefile.am
  40       + unix
  41         + Makefile.am
  42         + make_common_starter.am
  43         + config_files
  44           + Makefile.am
  45           + check_PYHELLO.m4
  46     + bin
  47       + Makefile.am
  48       + VERSION.in
  49       + runAppli.in
  50       + myrunSalome.py
  51     + idl
  52       + Makefile.am
  53       + PYHELLO_Gen.idl
  54     + src
  55       + Makefile.am
  56       + PYHELLO
  57         + Makefile.am
  58         + PYHELLO.py
  59     + doc
  60
  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.
  66
  67 .. warning::
  68
  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.
  71
  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
  77 the configure script.
  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.
  80
  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.
  85
  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.
  90
  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.
  93
  94 The idl directory
  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.
  99
 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.
 103
 104 The src directory
 105 --------------------------------------
 106 The src directory will contain all components and the GUI for the module. Each of these entities must have
 107 its own directory.
 108
 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.
 111
 112 The Makefile.am will simply trigger the path of sub-directories described by the SUBDIRS target.
 113
 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.
 118
 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.
 121
 122 The doc directory
 123 --------------------------------------
 124 This contains nothing for the moment. It could contain this document.
 125
 126 The bin directory
 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.
 130
 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.
 133
 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.
 137
 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.
 143
 144 All the following steps are only possible if the SALOME prerequisite software is accessible in the module
 145 developer environment.
 146
 147 Construction, installation
 148 ---------------------------------
 149 In PYHELLO1_SRC, enter::
 150
 151      export KERNEL_ROOT_DIR=<KERNEL installation path>
 152      ./build_configure
 153
 154 Go into ../PYHELLO1_BUILD and enter::
 155
 156      ../PYHELLO1_SRC/configure --prefix=<PYHELLO1 installation path>
 157      make
 158      make install
 159
 160 Running the platform
 161 -------------------------------
 162 Move into the <PYHELLO1 module installation path> and enter::
 163
 164     ./bin/salome/runAppli
 165
 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.
 168
 169 runAppli is a shell that executes a Python script, by passing arguments to it in a command line::
 170
 171     python -i $PYHELLO_ROOT_DIR/bin/salome/myrunSalome.py --modules=PYHELLO --killall
 172
 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.
 175
 176 This command will not function unless the following environment variables have previously been set::
 177
 178    export KERNEL_ROOT_DIR=<KERNEL installation path>
 179    export PYHELLO_ROOT_DIR=<PYHELLO installation path>
 180
 181 .. warning::
 182
 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.
 187
 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::
 193
 194     import PYHELLO_ORB
 195     c=container.load_impl("PYHELLO","PYHELLO")
 196     c.makeBanner("Christian")
 197
 198 The last instruction must return ‘Hello Christian’.
 199
 200 Proceed as follows to see CORBA objects created by these actions::
 201
 202     clt.showNS()
 203
 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.
 209
 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.
 213
 214 Updated tree structure::
 215
 216   + PYHELLO1_SRC
 217     + build_configure
 218     + configure.ac
 219     + Makefile.am
 220     + adm_local
 221     + bin
 222     + idl
 223     + src
 224     + doc
 225     + resources
 226       + PYHELLOCatalog.xml
 227
 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.
 231
 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::
 236
 237     ./config.status
 238     make
 239     make install
 240
 241 Starting the platform
 242 -------------------------------
 243 The platform is started in the same way as before.  Go into PYHELLO1_INSTALL and do::
 244
 245     ./bin/salome/runAppli
 246
 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. ::
 252
 253     c=test(clt)
 254     c.makeBanner("Christian")
 255
 256 The test function creates the LifeCycle.  It then asks for the PYHELLO component to be loaded in the FactoryServerPy container::
 257
 258   def test(clt):
 259        """
 260         Test function that creates an instance of PYHELLO component
 261         usage : pyhello=test(clt)
 262        """
 263        import LifeCycleCORBA
 264        lcc = LifeCycleCORBA.LifeCycleCORBA(clt.orb)
 265        import PYHELLO_ORB
 266        pyhello = lcc.FindOrLoadComponent("FactoryServerPy", "PYHELLO")
 267        return pyhello
 268
 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::
 274
 275   <component-icon>PYHELLO.png</component-icon>
 276
 277 and putting the corresponding file in the module resources directory.
 278
 279 Adding a graphic GUI
 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.
 284
 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.
 289
 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.
 296
 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).
 299
 300 The salomeres_DATA target must be updated with the names of files that are used for multi-linguism.
 301
 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.
 308