doc/dev_guide.txt

   1
   2 .. _pysalome:
   3
   4 ================================================================
   5 Guide for the development of a SALOME module in Python
   6 ================================================================
   7
   8 The purpose of this document is to describe briefly the different steps in the development of a SALOME module
   9 in Python.
  10
  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.
  17
  18 The different steps in the development will be as follows:
  19
  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
  23  - add a graphic GUI
  24
  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::
  31
  32   + PYHELLO1_SRC
  33     + build_configure
  34     + configure.ac
  35     + Makefile.am
  36     + adm_local
  37       + Makefile.am
  38       + unix
  39         + Makefile.am
  40         + make_common_starter.am
  41         + config_files
  42           + Makefile.am
  43           + check_PYHELLO.m4
  44     + bin
  45       + Makefile.am
  46       + VERSION.in
  47       + runAppli.in
  48       + myrunSalome.py
  49     + idl
  50       + Makefile.am
  51       + PYHELLO_Gen.idl
  52     + src
  53       + Makefile.am
  54       + PYHELLO
  55         + Makefile.am
  56         + PYHELLO.py
  57     + doc
  58
  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.
  64
  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.
  67
  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
  73 the configure script.
  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.
  76
  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.
  81
  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.
  86
  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.
  89
  90 The idl directory
  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.
  95
  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.
 100
 101 The src directory
 102 --------------------------------------
 103 The src directory will contain all components and the GUI for the module. Each of these entities must have
 104 its own directory.
 105
 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.
 108
 109 The Makefile.am will simply trigger the path of sub-directories described by the SUBDIRS target.
 110
 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.
 115
 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.
 118
 119 The doc directory
 120 --------------------------------------
 121 This contains nothing for the moment. It could contain this document.
 122
 123 The bin directory
 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.
 127
 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.
 130
 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.
 134
 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.
 140
 141 All the following steps are only possible if the SALOME prerequisite software is accessible in the module
 142 developer environment.
 143
 144 Construction, installation
 145 ---------------------------------
 146 In PYHELLO1_SRC, enter::
 147
 148      export KERNEL_ROOT_DIR=<KERNEL installation path>
 149      ./build_configure
 150
 151 Go into ../PYHELLO1_BUILD and enter::
 152
 153      ../PYHELLO1_SRC/configure --prefix=<PYHELLO1 installation path>
 154      make
 155      make install
 156
 157 Running the platform
 158 -------------------------------
 159 Move into the <PYHELLO1 module installation path> and enter::
 160
 161     ./bin/salome/runAppli
 162
 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.
 165
 166 runAppli is a shell that executes a Python script, by passing arguments to it in a command line::
 167
 168     python -i $PYHELLO_ROOT_DIR/bin/salome/myrunSalome.py --modules=PYHELLO --killall
 169
 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.
 172
 173 This command will not function unless the following environment variables have previously been set::
 174
 175    export KERNEL_ROOT_DIR=<KERNEL installation path>
 176    export PYHELLO_ROOT_DIR=<PYHELLO installation path>
 177
 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.
 182
 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::
 188
 189     import PYHELLO_ORB
 190     c=container.load_impl("PYHELLO","PYHELLO")
 191     c.makeBanner("Christian")
 192
 193 The last instruction must return ‘Hello Christian’.
 194
 195 Proceed as follows to see CORBA objects created by these actions::
 196
 197     clt.showNS()
 198
 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.
 204
 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.
 208
 209 Updated tree structure::
 210
 211   + PYHELLO1_SRC
 212     + build_configure
 213     + configure.ac
 214     + Makefile.am
 215     + adm_local
 216     + bin
 217     + idl
 218     + src
 219     + doc
 220     + resources
 221       + PYHELLOCatalog.xml
 222
 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.
 226
 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::
 231
 232     ./config.status
 233     make
 234     make install
 235
 236 Starting the platform
 237 -------------------------------
 238 The platform is started in the same way as before.  Go into PYHELLO1_INSTALL and do::
 239
 240     ./bin/salome/runAppli
 241
 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. ::
 247
 248     c=test(clt)
 249     c.makeBanner("Christian")
 250
 251 The test function creates the LifeCycle.  It then asks for the PYHELLO component to be loaded in the FactoryServerPy container::
 252
 253   def test(clt):
 254        """
 255         Test function that creates an instance of PYHELLO component
 256         usage : pyhello=test(clt)
 257        """
 258        import LifeCycleCORBA
 259        lcc = LifeCycleCORBA.LifeCycleCORBA(clt.orb)
 260        import PYHELLO_ORB
 261        pyhello = lcc.FindOrLoadComponent("FactoryServerPy", "PYHELLO")
 262        return pyhello
 263
 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::
 269
 270   <component-icon>PYHELLO.png</component-icon>
 271
 272 and putting the corresponding file in the module resources directory.
 273
 274 Adding a graphic GUI
 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.
 279
 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.
 284
 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.
 291
 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).
 294
 295 The salomeres_DATA target must be updated with the names of files that are used for multi-linguism.
 296
 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.
 303