Architecture of a Scilab Module (Scilab 5.x)

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.

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)

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>.

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.

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

How to develop a new 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/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
In SCI, launch autoreconf (you will need the version 2.60 of autoconf and 1.9 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

TODO : create a skeleton for this

Macro module

Create directory SCI/modules/<my_module_name>/macros'
edit buildmacros.sce and change genlib arguments

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');