5.8. Create the module tree structure

The first step in the development process is the creation of the module tree file structure. The typical SALOME module usually includes some set of the configuration files (used in the build procedure of a module), Makefiles, IDL file that provides a definition of a CORBA services implemented in a module and a set of source Python files which implement the module CORBA engine and (optionally) its GUI.

The following file structure is typical for the SALOME module:

+ SMITER1_SRC
   + SalomeSMITERConfig.cmake.in
   + CMake
   + CMakeLists.txt
   + adm_local
     + CMakeLists.txt
     + unix
       + CMakeLists.txt
       + make_common_starter.am
       + config_files
         + CMakeLists.txt
         + check_SMITER.m4
   + bin
     + CMakeLists.txt
     + VERSION.in
     + runAppli.in
     + myrunSalome.py
   + idl
     + CMakeLists.txt
     + SMITER_Gen.idl
   + src
     + CMakeLists.txt
     + SMITER
       + CMakeLists.txt
       + SMITER.py
       + SMITER_utils.py
     + SMITERGUI
       + CMakeLists.txt
       + SMITERGUI.py
       + SMITER_msg_en.ts
       + SMITER_icons.ts
   + resources
     + CMakeLists.txt
     + SMITER.png
     + SMITER_small.png
     + ExecSMITER.png
     + handshake.png
     + stop.png
     + SMITERCatalog.xml.in
     + SalomeApp.xml
   + doc
     + CMakeLists.txt
     + doxyfile.in
     + index.doc

Note that other files can be optionally present. For example, in some SALOME modules sources tree you can find such files as AUTHORS, INSTALL, ChangeLog, COPYING, NEWS, README, etc. Some files are specific only for this SMITER module, for example PNG images in the resources directory which are used in the GUI dialog boxes etc.

The usual way of the sources directory tree structure initial creation is to copy it from the existing SALOME module.

The files of the platform base module (KERNEL) must not be copied to initialise a module tree structure. It is usually preferable to copy files from another module such as GEOM or MED.

The module name is SMITER, the component name is SMITER and all the files are put in a directory named SMITER1_SRC. Below is a short description of these files. Note, that files with .in suffix are the autoconf templates from which the actual files are generated during the build procedure.

  • SalomeSMITERConfig.cmake.in, CMake, CMakeLists.txt, make_common_starter.am

These files are a part of the build system based on GNU automake/autoconf auto-tools. These files define the build procedure, namely, compilation and installation rules like compiler and linker options, installation destination folder, package version etc.

  • adm_local/unix/config_files/check_SMITER.m4

The files in this directory are also a part of the GNU auto-tools -based build procedure. The scripts written in m4 language are usually used to test an availability of some 3rd-party pre-requisite product, compiler feature, different configuration options.

  • bin/VERSION.in

This file is used to document the module, it must give its version (at least) and (optionally) compatibilities or incompatibilities with other modules. This file is strongly recommended but is not essential for operation of the module.

  • bin/runAppli.in
  • bin/runSalome.py

These files are not essential but make the example easier to use. These are scripts that can be used to run SALOME session with SMITER module.

  • idl/SMITER_Gen.idl

This is the CORBA IDL definition of the services implemented by SALOME SMITER module.

  • src/SMITER/SMITER.py
  • src/SMITER/SMITER_utils.py

These files provide the implementation of a CORBA engine of the SMITER module. In particular, this is an implementation of the services defined in the SMITER_Gen.idl file.

  • src/SMITERGUI/SMITERGUI.py

The src/SMITERGUI is an optional directory that provides an implementation of SMITER module’s GUI. Strictly speaking, the GUI is optional for each SALOME module. In some cases it is enough to implement CORBA engine only. Then, the services of the module will be avaiable in a CORBA environment. The module can be loaded to the SALOME container and its services can be used in the Supervisor computation schemas, in Python scripts or/and refer to it in other modules. A GUI is necessary in the cases if it is planned to access to the module functionality from the SALOME GUI session via menu actions, dialog boxes and so on.

  • src/SMITERGUI/SMITER_msg_en.ts
  • src/SMITERGUI/SMITER_icons.ts

These files provide a description (internationalization) of GUI resources of the SMITER module. SMITER_msg_en.ts provides an English translation of the string resources used in a module. SMITER_icons.ts defines images and icons resources used within the GUI of the SMITER module. Please refer to Qt linguist documentation for more details.

  • resources/SMITER.png
  • resources/SMITER_small.png
  • resources/ExecSMITER.png
  • resources/handshake.png
  • resources/stop.png

The resources folder usually includes different resource files used within the SALOME module. For example, SMITER.png file provides an icon of SMITER module to be shown in the SALOME GUI desktop. ExecSMITER.png is an icon for the makeBanner() function used in the menu and toolbar. The icons handshake.png and stop.png are used in the dialog boxes and SMITER_small.png icon is used to display in the Object browser for root SMITER entity.

  • resources/SMITERCatalog.xml.in

The XML description of the CORBA services provided by the SMITER module. This file is parsed by Supervisor and YACS module to generate the list of service nodes to be used in the calculation schemas. The simplest way to create this file is to use Catalog Generator utility provided by the SALOME KERNEL module, that can automatically generate XML description file from the IDL file.

  • resources/SalomeApp.xml

This file is essential for the module. It provides some parameters of the module which define module behavior in SALOME. In particular it should provide a section with the name corresponding to the name of a module (“SMITER” in this case) with the following parameters:

<section name= "SMITER" >
  <parameter name= "name" value= "SMITER" />
  <parameter name= "icon" value= "SMITER.png" />
  <parameter name= "library" value= "SalomePyQtGUI" />
</section>

The “name” parameter defines GUI name of a module. The “icon” parameter defines a GUI icon of a module. The parameter “library” specifies the name of the C++ library representing the front-end of the module in the SALOME GUI desktop. The Python modules which do not implement its own C++ front-end GUI library should specify “SalomePyQtGUI” value in this parameter.

The section “resources” also specifies the directory that contains resources of a module (icons, translation files, etc).

<section name= "resources" >
  <parameter name= "SMITER" value= "${SMITER_ROOT_DIR}/share/salome/resources/SMITER" />
</section>
  • doc/doxyfile.in

The Sphinx configuration file. The Sphinx is used to build this documentation. The file doxyfile.in provides a rules for the generation of module documentation.

  • doc/index.doc

An input file for the Sphinx, which provides a source of this documentation.