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     + CMakeLists.txt
  36     + adm_local
  37       + CMakeLists.txt
  38       + cmake_files
  39         + CMakeLists.txt
  40         + FindSalomePYHELLO.cmake
  41     + bin
  42       + CMakeLists.txt
  43       + VERSION.in
  44       + runAppli.in
  45       + myrunSalome.py
  46     + idl
  47       + CMakeLists.txt
  48       + PYHELLO_Gen.idl
  49     + src
  50       + CMakeLists.txt
  51       + PYHELLO
  52         + CMakeLists.txt
  53         + PYHELLO.py
  54     + doc
  55
  56 The module name is PYHELLO, the component name is PYHELLO and all the files will be put in a directory named PYHELLO1_SRC.
  57 All files are essential except for VERSION.in, runAppli.in and runSalome.py.
  58 VERSION.in is used to document the module, it must give its version and its compatibilities or
  59 incompatibilities with other modules.  Therefore, it is strongly recommended but is not essential for operation.
  60 The runAppli.in and runSalome.py files are not essential but make the example easier to use.
  61
  62 .. warning::
  63
  64    the files of the basic platform (KERNEL) must not be copied to initialise a module tree structure.
  65    It is usually preferable to copy files from another module such as GEOM or MED.
  66
  67 Implementation of CMake
  68 --------------------------------------
  69 The  CMakeLists.txt files are used to describe the build procedure,
  70 in particular:
  71 - Test platform;
  72 - Test system configuration;
  73 - Detect pre-requisites;
  74 - Generate build rules (for example, standard UNIX makefiles on Linux, MSVC solutions, etc).
  75
  76 Project's root directory provides main CMake configuration that allows build all targets into one
  77 set of binaries and libraries. Each sub-directory also includes CMake configuration file (CMakeLists.txt)
  78 that specifies targets being build.
  79
  80 The file CMakeLists.txt in root directory of the PYHELLO module provides basic build rules to be used
  81 in other CMakeLists.txt files.
  82 It sets main properties of project: name, version, pre-requisites, installation paths, programming languages
  83 being used by the project, tree of sub-directories, etc.
  84
  85 A lot of files used by the build procedure of HELLO module are located in SALOME KERNEL module
  86 (that is referenced by the KERNEL_ROOT_DIR environment variable), namely in its salome_adm sub-folder.
  87 Similarly, the GUI_ROOT_DIR environment variable is used for the graphical user interface (GUI) module of SALOME;
  88 this module also provides a set of configuration utilities (*.cmake files) in its adm_local folder.
  89
  90 The idl directory
  91 --------------------------------------
  92 The idl directory requires a CMakeLists.txt 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.
  94 This is done by using OMNIORB_ADD_MODULE() CMake macro::
  95
  96    OMNIORB_ADD_MODULE(SalomeIDLPYHELLO PYHELLO_Gen.idl ${KERNEL_ROOT_DIR}/idl/salome ${KERNEL_SalomeIDLKernel})
  97    INSTALL(TARGETS SalomeIDLPYHELLO EXPORT ${PROJECT_NAME}TargetGroup DESTINATION ${SALOME_INSTALL_LIBS})
  98
  99 The idl file itself must define a CORBA module for which the name must be different from the module
 100 name to avoid name conflicts and define a CORBA interface that is derived at least from the EngineComponent interface of the Engines module.
 101 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
 104 --------------------------------------
 105 The src directory will contain all components and the GUI for the module. Each of these entities must have
 106 its own directory.
 107
 108 For the moment, the module will only contain a single directory for the engine of the PYHELLO component
 109 and its name will be PYHELLO.
 110
 111 The CMakeLists.txt file triggers the path of sub-directories described
 112 by the \a ADD_SUBDIRECTORY() command.
 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 CMakeLists.txt 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
 153 Go into ../PYHELLO1_BUILD and enter::
 154
 155      cmake -DCMAKE_BUILD_TYPE=<Mode> -DCMAKE_INSTALL_PREFIX=<PYHELLO1 installation path> ../PYHELLO1_SRC
 156      make
 157      make install
 158
 159 Where <Mode> is build mode (Release or Debug).
 160
 161 Running the platform
 162 -------------------------------
 163 Move into the <PYHELLO1 module installation path> and enter::
 164
 165     ./bin/salome/runAppli
 166
 167 This command runs SALOME configured for KERNEL and the PYHELLO1 module.  At the end of running,
 168 the user sees a Python interpreter configured for SALOME that provides access to SALOME CORBA objects.
 169
 170 runAppli is a shell that executes a Python script, by passing arguments to it in a command line::
 171
 172     python -i $PYHELLO_ROOT_DIR/bin/salome/myrunSalome.py --modules=PYHELLO --killall
 173
 174 These arguments state that the myrunSalome.py script located in the PYHELLO module will be used, that the PYHELLO
 175 component will be activated and all SALOME processes that existed before the run will be killed.
 176
 177 This command will not function unless the following environment variables have previously been set::
 178
 179    export KERNEL_ROOT_DIR=<KERNEL installation path>
 180    export PYHELLO_ROOT_DIR=<PYHELLO installation path>
 181
 182 .. warning::
 183
 184    it is possible that the SALOME run will not reach the end.  In some circumstances, the time to
 185    start CORBA servers may be long and could exceed the timeout.  If the reason for
 186    this is that the time to load dynamic libraries is long, it is possible that a second run immediately
 187    afterwards will be successful.
 188
 189 Loading the example component
 190 ------------------------------------
 191 The PYHELLO_ORB module has to be imported before making a request to load the component into the Python
 192 container, to obtain access to methods of the component.  This Python container was made accessible
 193 in the runSalome.py by means of the container variable::
 194
 195     import PYHELLO_ORB
 196     c=container.load_impl("PYHELLO","PYHELLO")
 197     c.makeBanner("Christian")
 198
 199 The last instruction must return ‘Hello Christian’.
 200
 201 Proceed as follows to see CORBA objects created by these actions::
 202
 203     clt.showNS()
 204
 205 Declared SALOME component
 206 ==============================
 207 For the moment, the PYHELLO component was loaded by making a direct request to the Python container.  This is
 208 not the standard method for loading a component.  The normal method uses the LifeCycle service that uses
 209 catalog services to identify the component and its properties and then calls the requested container to load the component.
 210
 211 Before this method can be used, the component must be declared in a catalog in the XML format, for which
 212 the name must be <Module>Catalog.xml.  In our case, it will be PYHELLOCatalog.xml.  This catalog will be stored in
 213 the resources directory.
 214
 215 Updated tree structure::
 216
 217   + PYHELLO1_SRC
 218     + CMakeLists.txt
 219     + adm_local
 220     + bin
 221     + idl
 222     + src
 223     + doc
 224     + resources
 225       + PYHELLOCatalog.xml
 226
 227 The remainder of the files are identical, apart from adding the resources directory and the PYHELLOCatalog.xml file.
 228 However, the CMakeLists.txt has to be modified so that the catalog is actually installed in the installation
 229 directory.
 230
 231 Construction, installation
 232 ---------------------------------
 233 There is no need to do another configure to take account of this modification.
 234 All that is necessary is to enter PYHELLO1_BUILD and then::
 235
 236     make
 237     make install
 238
 239 Starting the platform
 240 -------------------------------
 241 The platform is started in the same way as before.  Go into PYHELLO1_INSTALL and do::
 242
 243     ./bin/salome/runAppli
 244
 245 Loading the example component
 246 ------------------------------------
 247 The method of loading the component is not very different from that described above.  The services of the
 248 LifeCycle module are used in this case instead of calling the container directly.
 249 The call sequence is contained in the runSalome.Py test function. ::
 250
 251     c=test(clt)
 252     c.makeBanner("Christian")
 253
 254 The test function creates the LifeCycle.  It then asks for the PYHELLO component to be loaded in the FactoryServerPy container::
 255
 256   def test(clt):
 257        """
 258         Test function that creates an instance of PYHELLO component
 259         usage : pyhello=test(clt)
 260        """
 261        import LifeCycleCORBA
 262        lcc = LifeCycleCORBA.LifeCycleCORBA(clt.orb)
 263        import PYHELLO_ORB
 264        pyhello = lcc.FindOrLoadComponent("FactoryServerPy", "PYHELLO")
 265        return pyhello
 266
 267 Loading from the application interface (IAPP)
 268 ----------------------------------------------------------
 269 Before a component can be loaded dynamically using the IAPP components bar, the icon representing the
 270 component will have to be declared in the catalog.
 271 It is declared by simply adding a line for the icon to the component catalog::
 272
 273   <component-icon>PYHELLO.png</component-icon>
 274
 275 and putting the corresponding file in the module resources directory.
 276
 277 Adding a graphic GUI
 278 ===========================
 279 The next step to complete the module consists of adding a graphic interface to the PYHELLO component, that will
 280 be written in Python using the Qt widgets library.  This graphic interface must be integrated into the SALOME
 281 application interface (IAPP), and therefore must respect some constraints that we will see.
 282
 283 Firstly note the contour of the GUI of a component.  The behaviour of the GUI is given by a Python module
 284 that has a standard name <Module>GUI.py.  It must propose conventional entry points that the IAPP will use to
 285 activate this GUI or to inform it of specific events.  GUI commands are activated through a menu bar and a
 286 button bar that are integrated into the menu bar and into the IAPP button bar.
 287
 288 Python module implanting the behaviour of the GUI
 289 -----------------------------------------------------
 290 The behaviour of the PYHELLO component GUI is implanted in the Python PYHELLOGUI.py module in the
 291 PYHELLOGUI sub-directory.  The CMakeLists.txt located in the src directory must be updated to include
 292 the PYHELLOGUI subdirectory.  A CMakeLists.txt must be added into the PYHELLOGUI subdirectory.
 293
 294 Menu bar and button bar
 295 ----------------------------------
 296 The menu bar and button bar for the PYHELLO component are dynamically added when importing the PYHELLOGUI module.
 297 They are created by calling the Python functions createMenu, createAction and createTool from the sgPyQt SALOME
 298 interface object. Every action must have a unique id.
 299 Some icons are used. They must be installed in the resources directory.
 300