1. Architecture of a Scilab Module (Scilab 5.x and 6.X)
This information may not be up-to-date. Please check howto/Create a toolbox for more up-to-date information
A module can be Scilab macros, java,Tcl/Tk, C, C++ and/or Fortran code. A module can (and should) contains other things like demos, help, unitary tests... This applies to Scilab 5.X. Scilab 4.X is completely different.
1.1. Description
A Scilab module should be composed like this:
Scilab module description |
||
demos |
Demos of the module which show features of the module |
|
etc |
Configuration of the module (initialization and configuration) |
|
examples |
examples (readme.txt) |
|
help |
Help of the module (Scilab help description) |
|
includes |
Header files which can be used externaly (other Scilab modules or third party programs) |
|
locales |
localization |
|
macros |
Scilab macros of the module |
|
sci_gateway |
Sources to plug the module into Scilab. |
Sources should be splited into subdirs (src/c/ src/fortran/...). |
src |
Core sources of the module. |
Sources should be splited into subdirs (src/c/ src/fortran/...). Local header (.h) should be put here |
tests/unit_tests |
Unitary tests which will be launched in order to test this module |
|
tests/nonreg_tests |
Non regression tests which will be launched in order to test this module |
|
tests/benchmarks |
Benchmarks which will be launched in order to test this module |
|
Mandatory files:
- changelog.txt
- licence.txt
- Makefile.am
- Makefile.in (generated from Makefile.am by automake)
- xxxx.vcproj
- version.xml
- readme.txt
etc/<module>.start
etc/<module>.quit
includes/gw_<module>.h
sci_gateway/xxx/gw_<module>.c
sci_gateway/<module>_gateway.xml
Optional files:
locales/en_US/<module>.po (this file is usually generated by SCI/tools/localization/updateLocalizationModule.sh)
1.2. Conception
The name of the module itself is quite important. It is must be composed only by letters, numbers and a just two special characters (_ or -). In the examples below, the module will be called <my_module_name>.
1.3. Guidelines
Function profiles should be declared in a .h in src/<language/ if they are local to the module. If the function can be used from an other modules, the header file should be put into includes/
- extern should be avoid. Prefer header file instead (.h)
- When a C function is created and can be called by fortran, don't forget to add the macros C2F around the name of the function.
- No warning in debug mode (-Wall) should be reached.
1.3.1. Rules for function profile & header declarations
- if the function is only used in the current file, put the declaration only in the C file
if the function is used in the module only, create an header file (.h) with the same name as the C/C++ file into the <module>/src/c/ directory
if the function is used (or will be) elsewhere in Scilab, create an header file (.h) with the same name as the C/C++ file into the <module>/includes/ directory
1.4. How to develop a new internal module Step by Step
Create directory SCI/modules/<my_module_name>
Create directory SCI/modules/<my_module_name>/etc : It will contain starting and stoping files
Create a <my_module_name>.start file
Create a <my_module_name>.quit file
Create a VERSION file
Create a readme.txt file
Create a license.txt file
Create a changelog.txt file
edit SCI/etc/modules.xml and add a new line with the information of your module in the list.
Create the Makefile.am file (you can copy it from an other module)
Edit the SCI/configure.ac file, look for AC_CONFIG_FILES and add modules/<my_module_name>/Makefile into the list
Edit the SCI/modules/Makefile.am and add to SUBDIRS <my_module_name>
Edit the SCI/modules/core/includes/callinterf.h and add #include "../../<my_module_name>/includes/gw_<my_module_name>.h" to the list
Edit the SCI/modules/core/src/c/callinterf.c and add {gw_<my_module_name>} to the list. Update INTERFACES_MAX++
In SCI, launch autoreconf (you will need at least the version 2.68 of autoconf and 1.11 of automake)
If you need your library to be added into Scilab dynamic library, into SCI/modules/Makefile.am, add \$(top_builddir)/modules/<my_module_name>/lib<my_module_name>.la to the variable libscilab_la_LIBADD
In SCI/modules/<my_module_name>/sci_gateway/c/, create a gw_<my_module_name>.c, this file should contain the match between the Scilab function and the C/C++/Fortran function. For example :
static OptimTable Tab[]= { {C2F(sci_optim),"optim"}, {C2F(sci_semidef),"semidef"}, {C2F(sci_fsolve),"fsolve"} };
In SCI/modules/<my_module_name>/includes/, create a gw_<my_module_name>.h, this file should contain the Scilab connector (copy/paste from an other) and also the list of all functions used in the Table defined in gw_<my_module_name>.c. '
Matching to the list of functions, create the file SCI/modules/<my_module_name>/sci_gateway/<my_module_name>_gateway.xml to list all the function which will be available in Scilab
- If the contains Java source files, then the file SCI/modules/prebuildjava/build.xml must be modified (target tag).
TODO : create a skeleton for this
Create directory SCI/modules/<my_module_name>/macros'
Create a directory SCI/modules/<my_module_name>/help/en_US' 1.4.1. Macro module
genlib(<21 characters of module's name> + 'lib','SCI/modules/elementaries_functions/macros');
example : elementaries_functions module
genlib('elementaries_functionlib','SCI/modules/elementaries_functions/macros');
1.4.2. Add a help chapter