1029 lines
26 KiB
HTML
1029 lines
26 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<html>
|
|
<head>
|
|
<title>SWIG and Scilab</title>
|
|
<link rel="stylesheet" type="text/css" href="style.css">
|
|
</head>
|
|
|
|
|
|
<body bgcolor="#ffffff">
|
|
|
|
<H1><a name="Scilab"></a>37 SWIG and Scilab</H1>
|
|
<!-- INDEX -->
|
|
<div class="sectiontoc">
|
|
<ul>
|
|
<li><a href="#Scilab_preliminaries">Preliminaries</a>
|
|
<li><a href="#Scilab_running_swig">Running SWIG</a>
|
|
<ul>
|
|
<li><a href="#Scilab_running_swig_generating_module">Generating the module</a>
|
|
<li><a href="#Scilab_running_swig_building_module">Building the module</a>
|
|
<li><a href="#Scilab_running_swig_loading_module">Loading the module</a>
|
|
<li><a href="#Scilab_running_swig_using_module">Using the module</a>
|
|
<li><a href="#Scilab_running_swig_options">Additional command line options</a>
|
|
</ul>
|
|
<li><a href="#Scilab_wrapping">A basic tour of C/C++ wrapping</a>
|
|
<ul>
|
|
<li><a href="#Scilab_wrapping_overview">Overview</a>
|
|
<li><a href="#Scilab_wrapping_identifiers">Identifiers</a>
|
|
<li><a href="#Scilab_wrapping_modules">Modules</a>
|
|
<li><a href="#Scilab_wrapping_functions">Functions</a>
|
|
<li><a href="#Scilab_wrapping_type_mappings">Default primitive type mappings</a>
|
|
<li><a href="#Scilab_wrapping_global_variables">Global variables</a>
|
|
<li><a href="#Scilab_wrapping_constants">Constants</a>
|
|
<li><a href="#Scilab_wrapping_enums">Enums</a>
|
|
<li><a href="#Scilab_wrapping_pointers">Pointers</a>
|
|
<li><a href="#Scilab_wrapping_structs">Structs</a>
|
|
<li><a href="#Scilab_wrapping_arrays">Arrays</a>
|
|
<li><a href="#Scilab_wrapping_matrices">Matrices</a>
|
|
<li><a href="#Scilab_wrapping_classes">C++ classes</a>
|
|
<li><a href="#Scilab_wrapping_templates">C++ templates</a>
|
|
<li><a href="#Scilab_wrapping_stl">C++ STL</a>
|
|
</ul>
|
|
<li><a href="#Scilab_module">Module</a>
|
|
<ul>
|
|
<li><a href="#Scilab_module_structure">Structure</a>
|
|
<li><a href="#Scilab_module_interface_file">Interface file</a>
|
|
<li><a href="#Scilab_module_building">Building</a>
|
|
<li><a href="#Scilab_module_builder">Builder script</a>
|
|
<li><a href="#Scilab_module_loader">Loader script</a>
|
|
</ul>
|
|
<li><a href="#Scilab_other_resources">Other resources</a>
|
|
</ul>
|
|
</ul>
|
|
</div>
|
|
<!-- INDEX -->
|
|
|
|
|
|
|
|
<p>
|
|
Scilab is a scientific software package for numerical computations providing a powerful open computing environment for engineering and scientific applications that is mostly compatible with MATLAB. More information can be found at <a href="http://www.scilab.org">www.scilab.org</a>.
|
|
</p>
|
|
|
|
<p>
|
|
This chapter explains how to use SWIG for Scilab. After this introduction, you should be able to generate with SWIG a Scilab external module from a C/C++ library.
|
|
</p>
|
|
|
|
|
|
<H2><a name="Scilab_preliminaries"></a>37.1 Preliminaries</H2>
|
|
|
|
<p>
|
|
SWIG for Scilab supports Linux. Other operating sytems haven't been tested.
|
|
</p>
|
|
|
|
<p>
|
|
Scilab is supported from version 5.3.3.
|
|
</p>
|
|
|
|
<p>
|
|
SWIG for Scilab supports C language. C++ is partially supported. See <a href="#Scilab_wrapping">A basic tour of C/C++ wrapping</a> for further details.
|
|
</p>
|
|
|
|
|
|
<H2><a name="Scilab_running_swig"></a>37.2 Running SWIG</H2>
|
|
|
|
<p>
|
|
Let's show how to use SWIG for Scilab on a small example, inspired from the "simple" example (found in the <tt>Examples/scilab/simple</tt> directory).
|
|
<br>
|
|
We want to bind from C a function and a global variable into Scilab.
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<p>
|
|
The SWIG interface (in <tt>example.i</tt> file) is as following:
|
|
</p>
|
|
|
|
<div class="code"><pre>
|
|
%module Example
|
|
%{
|
|
double Foo = 3.0;
|
|
int gcd(int x, int y) {
|
|
int g;
|
|
g = y;
|
|
while (x > 0) {
|
|
g = x;
|
|
x = y % x;
|
|
y = g;
|
|
}
|
|
return g;
|
|
}
|
|
%}
|
|
|
|
/* A global variable */
|
|
double Foo;
|
|
|
|
/* Compute the greatest common divisor of positive integers */
|
|
int gcd(int x, int y);
|
|
</pre></div>
|
|
|
|
<p>
|
|
Note: this is not the usual approach to write an interface file, it was used only for tightness and simplicity. See <a href="#Scilab_module">Module</a> to see the usual way to write the interface file.
|
|
</p>
|
|
|
|
|
|
<H3><a name="Scilab_running_swig_generating_module"></a>37.2.1 Generating the module</H3>
|
|
|
|
<p>
|
|
The module must be first generated, using the program <tt>swig</tt> and its <tt>-scilab</tt> option.
|
|
</p>
|
|
|
|
<div class="shell"><pre>
|
|
$ swig -scilab example.i
|
|
</pre></div>
|
|
|
|
<p>
|
|
This command generates two files:
|
|
</p>
|
|
<ul>
|
|
<li>a C source file <tt>example_wrap.c</tt>: the generated C source file contains the wrapping code (and our in case, also the implementation of <tt>gcd</tt>).</li>
|
|
<li>a Scilab script <tt>builder.sce</tt>: used to build the shared library (and other files).</li>
|
|
</ul>
|
|
|
|
<p>
|
|
Note: if the following error is returned:
|
|
<p>
|
|
|
|
<div class="shell"><pre>
|
|
:1: Error: Unable to find 'swig.swg'
|
|
:3: Error: Unable to find 'scilab.swg'
|
|
</pre></div>
|
|
|
|
<p>
|
|
It may be because the SWIG library is not found. Check the SWIG_LIB environment variable or your SWIG installation.
|
|
</p>
|
|
|
|
<p>
|
|
The <tt>swig</tt> command line program has several other options you can use. See <a href="#Scilab_running_swig_options">Additional command line options</a> for further details.
|
|
</p>
|
|
|
|
|
|
<H3><a name="Scilab_running_swig_building_module"></a>37.2.2 Building the module</H3>
|
|
|
|
<p>
|
|
Scilab external modules are shared libraries (with the <tt>.so</tt> file extension).
|
|
Building such a file is usually done by running the <tt>builder.sce</tt> script in Scilab:
|
|
</p>
|
|
|
|
<div class="shell"><pre>
|
|
$ ./scilab-cli
|
|
--> exec builder.sce
|
|
</pre></div>
|
|
|
|
<p>
|
|
This command will produce two important files:
|
|
</p>
|
|
|
|
<ul>
|
|
<li>the shared library <tt>libexample.so</tt>: it has the name of the module in the interface file, and it is prefixed by <tt>lib</tt>.</li>
|
|
<li>the loader script <tt>loader.sce</tt>: this script is used to load the shared library in Scilab.</li>
|
|
</ul>
|
|
|
|
<p>
|
|
Note: two other files are generated:
|
|
</p>
|
|
|
|
<ul>
|
|
<li>the Scilab gateway source file <tt>libexample.c</tt>: it a file used during the build.</li>
|
|
<li>the cleaner script <tt>cleaner.sce</tt>: used to clean (delete) the shared library.</li>
|
|
</ul>
|
|
</p>
|
|
|
|
|
|
<H3><a name="Scilab_running_swig_loading_module"></a>37.2.3 Loading the module</H3>
|
|
|
|
<p>
|
|
This is done by running the following command in Scilab:
|
|
</p>
|
|
|
|
<div class="shell"><pre>
|
|
--> exec loader.sce
|
|
</pre></div>
|
|
|
|
<p>
|
|
Scilab should output the following messages:
|
|
</p>
|
|
|
|
<div class="shell"><pre>
|
|
Shared archive loaded.
|
|
Link done.
|
|
</pre></div>
|
|
|
|
<p>
|
|
Which means that Scilab has sucessfully loaded the shared library. Its functions and other symbols are now available in Scilab.
|
|
</p>
|
|
|
|
<H3><a name="Scilab_running_swig_using_module"></a>37.2.4 Using the module</H3>
|
|
|
|
<p>
|
|
In Scilab, the function <tt>gcd()</tt> can be used simply like that:
|
|
</p>
|
|
|
|
<div class="targetlang"><pre>
|
|
--> gcd(4,6)
|
|
ans = 2
|
|
</pre></div>
|
|
|
|
<p>For the <tt>Foo</tt> global variable, the accessors have to be used:
|
|
|
|
<div class="targetlang"><pre>
|
|
--> Foo_get
|
|
ans = 3
|
|
|
|
--> Foo_set(4);
|
|
|
|
--> Foo_get
|
|
ans = 4
|
|
</pre></div>
|
|
|
|
|
|
<H3><a name="Scilab_running_swig_options"></a>37.2.5 Additional command line options</H3>
|
|
|
|
<p>
|
|
The following table lists the specific options for Scilab (of <tt>swig</tt> program):
|
|
</p>
|
|
|
|
<table summary="Scilab specific options">
|
|
|
|
<tr>
|
|
<td>-addcflag <opt></td>
|
|
<td>Additional compiler options <opt> to include in build script</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>-addldflag <opt></td>
|
|
<td>Additional link options <opt> to include in build script</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>-addsrc <files></td>
|
|
<td>Additional comma separated source <files> to include in build script</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>-vbl <level></td>
|
|
<td>Sets the build verbose <level> (default 0)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>-buildflags <file></td>
|
|
<td>Uses a Scilab script in <file> to set build flags level</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>-nobuilder</td>
|
|
<td>Do not generate builder script</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<p>
|
|
These options can be displayed with:
|
|
</p>
|
|
|
|
<div class="code"><pre>
|
|
swig -scilab -help
|
|
</pre></div>
|
|
|
|
<p>
|
|
Some examples:
|
|
</p>
|
|
|
|
<div class="shell"><pre>
|
|
$ swig -scilab -addcflag -I/usr/includes example.i
|
|
$ swig -scilab -addldflag "-lm example.i"
|
|
$ swig -scilab -addsrc file1.cxx,file2.cxx,example.i
|
|
</pre></div>
|
|
</p>
|
|
|
|
<H2><a name="Scilab_wrapping"></a>37.3 A basic tour of C/C++ wrapping</H2>
|
|
|
|
<H3><a name="Scilab_wrapping_overview"></a>37.3.1 Overview</H3>
|
|
|
|
<p>
|
|
SWIG for Scilab provides only low-level C interface only for Scilab. This means that functions, structs, classes, variables, etc... are interfaced through C functions. These C functions are mapped as Scilab functions.
|
|
<p>
|
|
|
|
<H3><a name="Scilab_wrapping_identifiers"></a>37.3.2 Identifiers</H3>
|
|
|
|
<p>
|
|
In Scilab 5.x, identifier names can be composed of 24 chars maximum (this limitation disappears in future version of Scilab 6.0).
|
|
<br>So long function or variables names can be truncated. It can be cause of conflict.
|
|
</p>
|
|
<p>It happens especially when wrapping structs/classes, for which the wrapping functions name are composed of the struct/class name and field names. In that case, the SWIG <tt>rename</tt> instruction, to choose a different wrapping name, can be useful.
|
|
<p>
|
|
|
|
<H3><a name="Scilab_wrapping_functions"></a>37.3.3 Functions</H3>
|
|
|
|
|
|
<p>
|
|
Global functions are wrapped as new Scilab built-in functions. For example:
|
|
</p>
|
|
|
|
<div class="code"><pre>
|
|
%module example
|
|
int fact(int n);
|
|
</pre></div>
|
|
|
|
<p>
|
|
Creates a built-in function <tt>fact(n)</tt> that works exactly like you think it does:
|
|
</p>
|
|
|
|
<div class="targetlang"><pre>
|
|
--> fact(4)
|
|
ans=24
|
|
</pre></div>
|
|
|
|
<H3><a name="Scilab_wrapping_primitive_type_mappings"></a>37.3.4 Default primitive type mappings</H3>
|
|
|
|
<p>
|
|
The following table give for each C/C++ primitive type the equivalent Scilab type.
|
|
</p>
|
|
|
|
<div class="table">
|
|
<table border="1" sumary="Scilab default primitive type mappings">
|
|
<tr>
|
|
<td><b>C/C++ type</b></td>
|
|
<td><b>Scilab type</b></td>
|
|
</tr>
|
|
<tr><td>bool</td><td>boolean</td></tr>
|
|
<tr><td>char</td><td>string</td></tr>
|
|
<tr><td>signed char</td><td>double or int8</td></tr>
|
|
<tr><td>unsigned char</td><td>uint8</td></tr>
|
|
<tr><td>short</td><td>double or int16</td></tr>
|
|
<tr><td>unsigned short</td><td>uint16</td></tr>
|
|
<tr><td>int</td><td>double or int32</td></tr>
|
|
<tr><td>unsigned int</td><td>uint32</td></tr>
|
|
<tr><td>long</td><td>double or int32</td></tr>
|
|
<tr><td>unsigned long</td><td>uint32</td></tr>
|
|
<tr><td>signed long long</td><td>not supported with Scilab 5.x</td></tr>
|
|
<tr><td>unsigned long long</td><td>not supported with Scilab 5.x</td></tr>
|
|
<tr><td>float</td><td>double</td></tr>
|
|
<tr><td>double</td><td>double</td></tr>
|
|
<tr><td>char* or char[]</td><td>string</td></tr>
|
|
</table>
|
|
</div>
|
|
|
|
<p>
|
|
Notes:
|
|
<ul>
|
|
<li>Double type in Scilab is far more used than integer type.
|
|
That's why signed integer values (short, int, integer, long) are automatically converted to Scilab double values in output of a C function.
|
|
Also in input, double values are converted from doubles into the appropriate integer type.
|
|
Note that this conversion does not occur with unsigned integers.
|
|
</li>
|
|
<li>
|
|
In SWIG for Scilab 5.x long long type is not supported since Scilab 5.x does not have a 64-bit integer type.
|
|
In that case, SWIG displays an error when wrapping a function that has long long type arguments.
|
|
</li>
|
|
</ul>
|
|
</p>
|
|
|
|
<H3><a name="Scilab_wrapping_non-primitive_type_mappings"></a>37.3.5 Default type mappings for non-primitive types</H3>
|
|
|
|
<p>
|
|
The default mapped type for C/C++ non-primitive types is the Scilab pointer. That is the case for exemple for C structs, C++ classes, ...
|
|
But there are many type mappings for non-primitive types (such as enums, arrays, STL types, etc...). Each of them is described further in this document.
|
|
</p>
|
|
|
|
<H3><a name="Scilab_wrapping_global_variables"></a>37.3.6 Global variables</H3>
|
|
|
|
|
|
<p>
|
|
To expose variables, SWIG actually generates two functions, to get and set the value. In this case, Foo_set and Foo_get would be generated. SWIG then automatically calls these functions when you get and set the variable-- in the former case creating a local copy in the interpreter of the C variables, and in the latter case copying an interpreter variable value into the C variable.
|
|
</p>
|
|
|
|
<div class="targetlang"><pre>
|
|
--> exec loader.sce;
|
|
--> c=Foo_get();
|
|
|
|
--> Foo_set(4);
|
|
|
|
--> c
|
|
c = 3
|
|
|
|
--> Foo_get()
|
|
ans = 4
|
|
</pre></div>
|
|
|
|
<H3><a name="Scilab_wrapping_constants"></a>37.3.7 Constants</H3>
|
|
|
|
<p>
|
|
There is no constant in Scilab. By default, C/C++ constants are wrapped as getter functions. For example for the following constants:
|
|
</p>
|
|
|
|
<div class="code"><pre>
|
|
%module example
|
|
#define ICONST 42
|
|
#define FCONST 2.1828
|
|
#define CCONST 'x'
|
|
#define CCONST2 '\n'
|
|
#define SCONST "Hello World"
|
|
#define SCONST2 "\"Hello World\""
|
|
</pre></div>
|
|
|
|
<p>
|
|
The following getter functions are generated:
|
|
</p>
|
|
|
|
<div class="targetlang"><pre>
|
|
--> exec loader.sce;
|
|
--> ICONST_get();
|
|
ans= 42
|
|
--> FCONST_get();
|
|
ans= 2.1828
|
|
--> CCONST_get();
|
|
ans=x
|
|
--> CCONST2_get();
|
|
ans=
|
|
|
|
--> SCONST_get();
|
|
ans= Hello World
|
|
--> SCONST2_get();
|
|
ans= "Hello World"
|
|
--> EXPR_get();
|
|
ans= 48.5484
|
|
--> iconst_get();
|
|
ans= 37
|
|
--> fconst_get();
|
|
ans= 3.14
|
|
</pre></div>
|
|
|
|
<p>
|
|
There is another mode in which constants are wrapped as Scilab variables.
|
|
The variables are easier to use than functions, but the little drawback is that variables are not constant and so can be modified.
|
|
This mode can be enabled/disabled at any time in the interface file with the feature <tt>%scilabconst()</tt> (argument value "1" to enable, "0" to disable).
|
|
For example in this mode the previous constants:
|
|
</p>
|
|
|
|
<div class="code"><pre>
|
|
%module example
|
|
|
|
%scilabconst(1);
|
|
#define ICONST 42
|
|
#define FCONST 2.1828
|
|
#define CCONST 'x'
|
|
#define CCONST2 '\n'
|
|
#define SCONST "Hello World"
|
|
#define SCONST2 "\"Hello World\""
|
|
</pre></div>
|
|
|
|
<p>
|
|
Are mapped to Scilab variables, with the same name:
|
|
</p>
|
|
|
|
<div class="targetlang"><pre>
|
|
--> exec loader.sce;
|
|
--> ICONST;
|
|
ans= 42
|
|
--> FCONST;
|
|
ans= 2.1828
|
|
--> CCONST;
|
|
ans=x
|
|
--> CCONST2;
|
|
ans=
|
|
|
|
--> SCONST;
|
|
ans= Hello World
|
|
--> SCONST2;
|
|
ans= "Hello World"
|
|
--> EXPR;
|
|
ans= 48.5484
|
|
--> iconst;
|
|
ans= 37
|
|
--> fconst;
|
|
ans= 3.14
|
|
</pre></div>
|
|
|
|
<H3><a name="Scilab_wrapping_enums"></a>37.3.8 Enums</H3>
|
|
|
|
<p>
|
|
The wrapping of enums is quite the same as for constants.
|
|
In the default mode, the enums are wrapped as getter functions.
|
|
For example on the following enumeration:
|
|
</p>
|
|
|
|
<div class="code"><pre>%module example
|
|
typedef enum { RED, BLUE, GREEN } color;
|
|
</pre></div>
|
|
|
|
<p>
|
|
A getter function will be generated for each value of the enumeration:
|
|
</p>
|
|
|
|
<div class="targetlang"><pre>
|
|
--> exec loader.sce;
|
|
--> printf(" RED = %i\n", RED_get());
|
|
RED = 0.
|
|
--> printf(" BLUE = %i\n", BLUE_get());
|
|
BLUE = 1.
|
|
--> printf(" GREEN = %i\n", GREEN_get());
|
|
GREEN = 2.
|
|
</pre></div>
|
|
|
|
<p>
|
|
The feature <tt>%scilabconst()</tt> is also available for enumerations:
|
|
</p>
|
|
|
|
<div class="code"><pre>%module example
|
|
%scilabconst(1);
|
|
typedef enum { RED, BLUE, GREEN } color;
|
|
</pre></div>
|
|
|
|
<p>
|
|
<div class="targetlang"><pre>
|
|
--> exec loader.sce;
|
|
--> printf(" RED = %i\n", RED);
|
|
RED = 0.
|
|
--> printf(" BLUE = %i\n", BLUE);
|
|
BLUE = 1.
|
|
--> printf(" GREEN = %i\n", GREEN);
|
|
GREEN = 2.
|
|
</pre></div>
|
|
</p>
|
|
|
|
<H3><a name="Scilab_wrapping_pointers"></a>37.3.9 Pointers</H3>
|
|
|
|
|
|
<p>
|
|
Pointers are fully supported by SWIG. One way to deal with the pointers is using the INPUT and OUTPUT typemaps. For example, in order to call C functions as the following:
|
|
</p>
|
|
|
|
<div class="code"><pre>
|
|
void sub(int *x, int *y, int *result) {
|
|
*result = *x - *y;
|
|
}
|
|
int divide(int n, int d, int *r) {
|
|
int q;
|
|
q = n/d;
|
|
*r = n - q*d;
|
|
return q;
|
|
}
|
|
</pre></div>
|
|
|
|
<p> We could write an interface file:
|
|
</p>
|
|
|
|
<div class="code"><pre>%module example
|
|
%include typemaps.i
|
|
extern void sub(int *INPUT, int *INPUT, int *OUTPUT);
|
|
|
|
%apply int *OUTPUT { int *r };
|
|
extern int divide(int n, int d, int *r);
|
|
</pre></div>
|
|
|
|
<p>Then run it in Scilab:
|
|
</p>
|
|
|
|
<div class="targetlang"><pre>
|
|
--> r = sub(37,42);
|
|
--> printf(" 37 - 42 = %i\n",r);
|
|
37 - 42 = -5
|
|
|
|
--> [q,r] = divide(42,37);
|
|
--> printf(" 42/37 = %d remainder %d\n",q,r);
|
|
42/37 = 1 remainder 5
|
|
|
|
</pre></div>
|
|
|
|
<p> From the example above, it is clear that instead of passing a pointer to an object,
|
|
we only need a real value instead.
|
|
</p>
|
|
|
|
<H3><a name="Scilab_wrapping_structs"></a>37.3.10 Structs</H3>
|
|
|
|
|
|
<p>
|
|
SWIG creates a set of accessor functions when encountering a structure or union. For example:
|
|
</p>
|
|
|
|
<div class="code"><pre>%module example
|
|
%inline %{
|
|
typedef struct {
|
|
int x;
|
|
} Foo;
|
|
|
|
%}
|
|
</pre></div>
|
|
|
|
<p> When wrapped, it would generate two main function: Foo_x_set(), which set the data value of the structure and Foo_x_get() which could obtain the value of the structure. Run it in Scilab:
|
|
</p>
|
|
|
|
<div class="targetlang"><pre>
|
|
--> a=new_Foo();
|
|
--> Foo_x_set(a,100);
|
|
--> Foo_x_get(a)
|
|
ans =
|
|
|
|
100
|
|
</pre></div>
|
|
|
|
<H3><a name="Scilab_wrapping_arrays"></a>37.3.11 Arrays</H3>
|
|
|
|
|
|
<p>
|
|
Arrays are fully supported by SWIG and Scilab. In SWIG, they are handled as pointers.
|
|
It is easy to deal with arrays too. For example:
|
|
</p>
|
|
|
|
<div class="code"><pre>
|
|
%module example
|
|
|
|
%inline %{
|
|
int x[10];
|
|
double y[7];
|
|
void initArray()
|
|
{
|
|
int i, n;
|
|
|
|
n = sizeof(x)/sizeof(x[0]);
|
|
for(i = 0; i > n; i++)
|
|
x[i] = i;
|
|
|
|
n = sizeof(y)/sizeof(y[0]);
|
|
for(i = 0; i < n; i++)
|
|
y[i] = ((double) i)/ ((double) n);
|
|
return;
|
|
%}
|
|
</pre></div>
|
|
|
|
<p> When wrapped, the following functions are generated: x_set(), x_get(), y_set(), y_get(), and _wrap_initArray.
|
|
They can be used like this:
|
|
</p>
|
|
|
|
<div class="targetlang"><pre>
|
|
--> exec loader.sce
|
|
|
|
--> initArray();
|
|
--> x_get()
|
|
ans =
|
|
|
|
0 1 2 3 4 5 6 7 8 9
|
|
--> y_get()
|
|
ans =
|
|
|
|
0. 0.1428571 0.2857143 0.4285714 0.5714286 0.7142857 0.8571429
|
|
</pre></div>
|
|
|
|
<H3><a name="Scilab_wrapping_matrices"></a>37.3.12 Matrices</H3>
|
|
|
|
|
|
<p>
|
|
Scilab uses matrices a lot for numerical mathematics and scientific visualization. Supporting matrices makes Scilab more convenient. For example:
|
|
</p>
|
|
|
|
<div class="code"><pre>%module example
|
|
%inline %{
|
|
double **new_matrix() {
|
|
|
|
int i;
|
|
double **M;
|
|
|
|
M = (double **) malloc(4 * sizeof(double *));
|
|
M[0] = (double *) malloc(16 * sizeof(double));
|
|
|
|
for (i = 0; i < 4; i++) {
|
|
M[i] = M[0] + 4 * i;
|
|
}
|
|
return M;
|
|
}
|
|
|
|
void set_m(double **M, int i, int j, double val) {
|
|
M[i][j] = val;
|
|
}
|
|
|
|
double get_m(double **M, int i, int j) {
|
|
return M[i][j];
|
|
}
|
|
|
|
void print_matrix(double **M) {
|
|
|
|
int i,j;
|
|
|
|
for (i = 0; i < 4; i++) {
|
|
for (j = 0; j < 4; j++) {
|
|
printf("%10g ", M[i][j]);
|
|
}
|
|
printf("\n");
|
|
}
|
|
}
|
|
|
|
void mat_mult(double **m1, double **m2, double **m3) {
|
|
|
|
int i,j,k;
|
|
double temp[4][4];
|
|
|
|
for (i = 0; i < 4; i++)
|
|
for (j = 0; j < 4; j++) {
|
|
temp[i][j] = 0;
|
|
for (k = 0; k < 4; k++)
|
|
temp[i][j] += m1[i][k] * m2[k][j];
|
|
}
|
|
|
|
for (i = 0; i < 4; i++)
|
|
for (j = 0; j < 4; j++)
|
|
m3[i][j] = temp[i][j];
|
|
}
|
|
%}
|
|
</pre></div>
|
|
|
|
<p> When wrapped, it would generate the following function:
|
|
</p>
|
|
<p>_wrap_new_matrix(): generate a new matrix.
|
|
</p>
|
|
<p>_wrap_set_m(M, i, j, a): set M(i, j) to be value a.
|
|
</p>
|
|
<p>_wrap_get_m(M, i, j): get the value of M(i, j).
|
|
</p>
|
|
<p>_wrap_print_matrix(M): print the matrix M.
|
|
</p>
|
|
<p>_wrap_mat_mult(A, B, C): compute the A * B and the result is stored into C.
|
|
</p>
|
|
<p>It can be used like this:
|
|
</p>
|
|
|
|
<div class="targetlang"><pre>
|
|
--> exec loader.sce
|
|
|
|
--> x = new_matrix();
|
|
--> for i = 0 : 3;
|
|
--> for j = 0 : 3;
|
|
--> set_m(x, i, j, i + j);
|
|
--> end;
|
|
--> end;
|
|
|
|
--> print_matrix(y);
|
|
0 1 2 3
|
|
1 2 3 4
|
|
2 3 4 5
|
|
3 4 5 6
|
|
--> y = new_matrix();
|
|
--> for i = 0 : 3;
|
|
--> for j = 0 : 3;
|
|
--> set_m(y, i, j, i - j);
|
|
--> end;
|
|
--> end;
|
|
|
|
--> print_matrix(y);
|
|
0 -1 -2 -3
|
|
1 0 -1 -2
|
|
2 1 0 -1
|
|
3 2 1 0
|
|
--> z = new_matrix();
|
|
--> mat_mult(x, y, z);
|
|
--> print_matrix(z);
|
|
14 8 2 -4
|
|
20 10 0 -10
|
|
26 12 -2 -16
|
|
32 14 -4 -22
|
|
</pre></div>
|
|
|
|
|
|
<H3><a name="Scilab_wrapping_classes"></a>37.4.13 Classes</H3>
|
|
|
|
<p>
|
|
The classes are wrapped in the same manner as structs, through functions. For example, the following class:
|
|
</p>
|
|
|
|
<div class="targetlang"><pre>
|
|
class Point {
|
|
public:
|
|
int x,y;
|
|
Point(int _x,int _y) : x(_x),y(_y) {}
|
|
double distance(const Point& rhs) {
|
|
return sqrt(pow(x-rhs.x,2)+pow(y-rhs.y,2));
|
|
}
|
|
void set(int _x,int _y) {
|
|
x=_x; y=_y;
|
|
}
|
|
};
|
|
</pre></div>
|
|
|
|
<p>
|
|
can be used from Scilab like this:
|
|
</p>
|
|
|
|
<div class="targetlang"><pre>
|
|
--> p1 = Point_new(3, 5);
|
|
--> p2 = Point_new(1, 2);
|
|
--> p1.distance(p2)
|
|
ans =
|
|
3.6056
|
|
</pre></div>
|
|
|
|
|
|
|
|
<H3><a name="Scilab_wrapping_templates"></a>37.4.14 Templates</H3>
|
|
|
|
<p>
|
|
Templates are supported. See the SWIG general documentation on how templates are interfaced in SWIG.<br>
|
|
An example of templates can be found in <tt>Examples/scilab/templates</tt>.
|
|
</p>
|
|
|
|
<H3><a name="Scilab_wrapping_stl"></a>37.4.15 STL</H3>
|
|
|
|
<p>
|
|
Standard Template Library (STL) is partially supported.
|
|
</p>
|
|
|
|
<p>
|
|
The following containers are usable:
|
|
<p>
|
|
|
|
<ul>
|
|
<li><tt>std::vector</tt></li>
|
|
<li><tt>std::list</tt></li>
|
|
<li><tt>std::set</tt></li>
|
|
</ul>
|
|
|
|
<p>
|
|
Each of these containers supports the following types:
|
|
</p>
|
|
|
|
<ul>
|
|
<li><tt>double</tt></li>
|
|
<li><tt>int</tt></li>
|
|
<li><tt>string</tt></li>
|
|
<li><tt>bool</tt></li>
|
|
<li><tt>pointer</tt></li>
|
|
</ul>
|
|
|
|
<p>
|
|
Some typemaps between Scilab and STL are available.
|
|
<p>
|
|
|
|
<ul>
|
|
<li>
|
|
|
|
<p>
|
|
A STL vector or list is mapped from/to a Scilab matrix or list, depending on type.
|
|
<p>
|
|
|
|
<table summary="Typemaps vector-list", border="1">
|
|
<tr>
|
|
<th>STL type</th>
|
|
<th>Header 2</th>
|
|
<tr><td>vector/list of int</td><td>int matrix</td></tr>
|
|
<tr><td>vector/list of double</td><td>double matrix</td></tr>
|
|
<tr><td>vector/list of string</td><td>string matrix</td></tr>
|
|
<tr><td>vector/list of bool</td><td>bool matrix</td></tr>
|
|
<tr><td>vector/list of pointer</td><td>pointer list</td></tr>
|
|
</table>
|
|
|
|
</li>
|
|
|
|
<li>A STL set is mapped from/to a Scilab list.</li>
|
|
</ul>
|
|
|
|
<p>
|
|
In the SWIG interface file, the STL support can be enabled with:
|
|
</p>
|
|
|
|
<div class="code"><pre>
|
|
%include stl.i
|
|
</pre/></div>
|
|
|
|
<p>As templates, for each specific type used, the STL container has the to be instantied:
|
|
<div class="code"><pre>
|
|
namespace std {
|
|
%template(IntVector) vector<int>;
|
|
%template(DoubleVector) vector<double>;
|
|
</pre></div>
|
|
|
|
<p>
|
|
At last, a command has to be run in Scilab, so that all that types are known by Scilab.
|
|
|
|
<div class="targetlang"><pre>
|
|
SWIG_Init();
|
|
</pre></div>
|
|
|
|
|
|
<H2><a name="Scilab_module"></a>37.5 Module</H2>
|
|
|
|
<p>
|
|
In this part we describe how may be structured a module, how to build it, and give some details about the generated scripts.
|
|
</p>
|
|
|
|
<H3><a name="Scilab_module_structure"></a>37.5.1 Structure</H3>
|
|
|
|
<p>
|
|
Usually, one module is created to bind one library. Each library to be wrapped comes with the following files:
|
|
</p>
|
|
|
|
<ul>
|
|
<li>header files (<tt>.h</tt>, <tt>.hpp</tt>,...) of the module, or of a third party library.</tt></li>
|
|
<li>source files (<tt>.c</tt>, <tt>.cpp</tt>,...).</tt></li>
|
|
<li>some third party libraries (<tt>.so</tt>) to link with.</tt></li>
|
|
</ul>
|
|
|
|
|
|
<H3><a name="Scilab_module_interface_file"></a>37.5.2 Interface file</H3>
|
|
|
|
<p>
|
|
To one module corresponds one interface file. Multi modules in an interface file are not supported.
|
|
</p>
|
|
|
|
<p>
|
|
Usually the interface file will look like as following:
|
|
</p>
|
|
|
|
<div class="code"><pre>
|
|
%module [module_name]
|
|
%{
|
|
#include [header]
|
|
....
|
|
%}
|
|
|
|
#include [header]
|
|
....
|
|
</pre></div>
|
|
|
|
<H3><a name="Scilab_module_building"></a>37.5.3 Building</H3>
|
|
|
|
<p>
|
|
SWIG for Scilab builds dynamic modules. This means shared libaries are built (.so), which are dynamically linked by Scilab.
|
|
</p>
|
|
|
|
<p>
|
|
To generate the code and the builder script, the following options may be used with <tt>swig</tt>:
|
|
</p>
|
|
|
|
<ul>
|
|
<li><tt><b>addsrc</b></tt>: to add in the compilation source files</li>
|
|
<li><tt><b>addcflag</b></tt>: to set the header include paths</li>
|
|
<li><tt><b>addldflag</b></tt>: to set the third party library paths and names</li>
|
|
</ul>
|
|
|
|
<p>
|
|
The <tt>swig</tt> command to use may be something like this:
|
|
</p>
|
|
|
|
<div class="shell"><pre>
|
|
swig -scilab -addcflag "-I[inc_path]..." -addsrc [source],... -addldflag "-L[lib_path] -l[lib_name]" [module_name].i
|
|
</pre></div>
|
|
|
|
<H3><a name="Scilab_module_builder"></a>37.5.4 Builder script</H3>
|
|
|
|
<p>
|
|
<tt>builder.sce</tt> is the script file generated by SWIG. It contains the following code:
|
|
</p>
|
|
<div class="code"><pre>
|
|
|
|
ilib_name = "examplelib";
|
|
files = ["example_wrap.c"];
|
|
libs = [];
|
|
table = ["gcd","_wrap_gcd";"Foo_set","_wrap_Foo_set";"Foo_get","_wrap_Foo_get";];
|
|
ilib_build(ilib_name,table,files,libs);
|
|
</pre></div>
|
|
|
|
<p>
|
|
<tt>ilib_build(lib_name,table,files,libs)</tt> is used to create shared libraries and to generate a loader file which can be used to dynamically load the shared library into Scilab with <tt>addinter</tt>.
|
|
</p>
|
|
|
|
<ul>
|
|
<li><tt><b>ilib_name</b></tt>: a character string, the generic name of the library without path and extension.</li>
|
|
<li><tt><b>files</b></tt>: string matrix giving objects files needed for shared library creation.</li>
|
|
<li><tt><b>libs</b></tt>: string matrix giving extra libraries needed for shred library creation.</li>
|
|
<li><tt><b>table</b></tt>: two column string matrix giving the table of pairs 'scilab-name', 'interface name'.</li>
|
|
</ul>
|
|
|
|
<H3><a name="Scilab_module_loader"></a>37.5.5 Loader script</H3>
|
|
|
|
<p>
|
|
The loader script <tt>loader.sce</tt> script looks as following:
|
|
</p>
|
|
|
|
<div class="code"><pre>
|
|
// ------------------------------------------------------
|
|
// generated by builder.sce: Please do not edit this file
|
|
// ------------------------------------------------------
|
|
|
|
libexamplelib_path = get_file_path('loader.sce');
|
|
list_functions = [ 'gcd';
|
|
'Foo_set';
|
|
'Foo_get';
|
|
];
|
|
addinter(libexamplelib_path+'/libexamplelib.so','libexamplelib',list_functions);
|
|
// remove temp. variables on stack
|
|
clear libexamplelib_path;
|
|
clear list_functions;
|
|
clear get_file_path;
|
|
// ------------------------------------------------------
|
|
</pre></div>
|
|
|
|
<p>
|
|
<tt>addinter(files,spname,fcts)</tt> performs dynamic linking of a compiled C new Scilab interface routine.
|
|
</p>
|
|
<ul>
|
|
<li><tt><b>files</b></tt>: a character string or a vector of character string contain object files used to define the new Scilab interface routine (interface code, user routines or libraries, system libraries).</li>
|
|
<li><tt><b>spname</b></tt>: a character string. Name of interface routine entry point.</li>
|
|
<li><tt><b>fcts</b></tt>: vector of character strings. The name of new Scilab function implemented in the new interface.</li>
|
|
</ul>
|
|
|
|
<H2><a name="Scilab_other_resources"></a>37.6 Other resources</H2>
|
|
|
|
<ul>
|
|
<li>Examples can be found in the <tt>Examples/scilab directory</tt>, and they cover the different cases of wrapping.</li>
|
|
<li>The test suite in the <tt>Examples/test-suite/scilab</tt> can be another source of wrapping use cases.</li>
|
|
</ul>
|
|
|