ed84d6b162
git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/branches/gsoc2009-sploving@11288 626c5289-ae23-0410-ae9c-e8d60b6d4f22
300 lines
9.1 KiB
HTML
300 lines
9.1 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>36 SWIG and Scilab</H1>
|
|
<!-- INDEX -->
|
|
<div class="sectiontoc">
|
|
<ul>
|
|
<li><a href="#Scilab_nn2">Preliminaries</a>
|
|
<li><a href="#Scilab_nn3">Running SWIG</a>
|
|
<ul>
|
|
<li><a href="#Scilab_nn5">Compiling a dynamic module</a>
|
|
<li><a href="#Scilab_nn6">Using your module</a>
|
|
</ul>
|
|
<li><a href="#Scilab_nn7">A tour of basic C/C++ wrapping</a>
|
|
<ul>
|
|
<li><a href="#Scilab_nn8">Modules</a>
|
|
<li><a href="#Scilab_nn9">Functions</a>
|
|
<li><a href="#scilab_nn10">Global variables</a>
|
|
<li><a href="#Scilab_nn11">Constants</a>
|
|
<li><a href="#Scilab_nn12">Enums</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 is intended to give an introduction to using the module. You should also read the SWIG documentation that is not specific to Scilab.Also, there are a dozen or so examples in the Examples/Scilab directory.
|
|
</p>
|
|
|
|
<H2><a name="Scilab_nn2"></a>36.1 Preliminaries</H2>
|
|
|
|
|
|
<p>
|
|
The current SWIG implemention is based on Scilab 5.1.1. Support for other higher versions has not been tested, nor has support for any OS other than Linux.
|
|
</p>
|
|
|
|
<H2><a name="Scilab_nn3"></a>36.2 Running SWIG</H2>
|
|
|
|
|
|
<p>
|
|
Let's start with a very simple SWIG interface file:
|
|
</p>
|
|
|
|
<div class="code"><pre>%module example
|
|
%{
|
|
#include "example.h"
|
|
%}
|
|
int gcd(int x, int y);
|
|
extern double Foo; </pre></div>
|
|
|
|
<p>
|
|
To build an Scilab module, run SWIG using the <tt>-scilab</tt> option.
|
|
</p>
|
|
|
|
<div class="shell"><pre>$ swig -scilab example.i </pre></div>
|
|
|
|
<p>
|
|
This creates a C source file <tt>example_wrap.c</tt> and a interface file <tt>builder.sce</tt>. The generated C source file contains the low-level wrappers that need to be compiled and linked with the rest of your C application (in this case, the gcd implementation) to create an extension module. And the builder.sce is used to generate the *.so file.
|
|
</p>
|
|
|
|
<p>
|
|
The swig command line has a number of options you can use, like to redirect it's output. Use <tt>swig --help</tt> to learn about these.
|
|
</p>
|
|
|
|
<H3><a name="Scilab_nn5"></a>36.2.1 Compiling a dynamic module</H3>
|
|
|
|
|
|
<p>
|
|
Scilab modules are shared objects having the ".so" suffix.
|
|
Building such a file is usually done with the "exec" command (within Scilab itself) For example,
|
|
</p>
|
|
|
|
<div class="shell"><pre>
|
|
$ ./scilab
|
|
--> exec builder.sce
|
|
</pre></div>
|
|
|
|
<p>
|
|
where builder.sce is the interface file generated by the swig. It looks like the following:
|
|
</p>
|
|
<div class="code"><pre>
|
|
ilib_name = "examplelib";
|
|
files = ["example_wrap.c","example.o"];
|
|
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>ilib_build(lib_name,table,files,libs) 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 addinter.
|
|
</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>
|
|
|
|
<p>
|
|
"exec builder.sce" will produce *.so,and a file called "loader.sce" which contains how to load the module. Loading it into Scilab is then a matter of invoking
|
|
</p>
|
|
|
|
<div class="shell"><pre>Scilab:1> exec loader.sce</pre></div>
|
|
|
|
<H3><a name="Scilab_nn6"></a>36.2.2 Using your module</H3>
|
|
|
|
|
|
<p>
|
|
Assuming all goes well, you will be able to do this:
|
|
<br>
|
|
</p>
|
|
|
|
<div class="targetlang"><pre>
|
|
Scilab:2>gcd(4,6)
|
|
ans = 2
|
|
|
|
Scilab:3>Foo_get
|
|
ans = 3
|
|
|
|
Scilab:4>Foo_set(4);
|
|
|
|
Scilab:5>Foo_get
|
|
ans = 4 </pre></div>
|
|
|
|
<H2><a name="Scilab_nn7"></a>36.3 A tour of basic C wrapping</H2>
|
|
|
|
|
|
<H3><a name="Scilab_nn8"></a>36.3.1 Modules</H3>
|
|
|
|
|
|
<p>
|
|
The SWIG module directive specifies the name of the Scilab module. If you want to load the module, you'll need a file called "loader.sce" which is usually generated by the command "exec builder.sce". The loader.sce 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>addinter (files,spname,fcts) performs incremental 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>
|
|
|
|
|
|
<p>
|
|
After you run the command "exec loader.sce", you could use the module.
|
|
</pre>
|
|
|
|
<H3><a name="Scilab_nn9"></a>36.3.2 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>Scilab:1>fact(4)
|
|
ant=24 </pre></div>
|
|
<H3><a name="scilab_nn10"></a>27.3.3 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 variables onto the C variable.
|
|
</p>
|
|
|
|
<div class="targetlang"><pre>scilab:1> exec loader.sce;
|
|
scilab:2> c=Foo_get();
|
|
|
|
scilab:3> Foo_set(4);
|
|
|
|
scilab:4> c
|
|
c = 3
|
|
|
|
scilab:5> Foo_get()
|
|
ans = 4</pre></div>
|
|
<H3><a name="Scilab_nn11"></a>27.3.4 Constants</H3>
|
|
|
|
|
|
<p>
|
|
C constants are not really constant in Scilab. They are actually just a copy of the value into the Scilab interpreter. Therefore they can be changed just as any other value. For example given some 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>
|
|
A file called example.sce will be created, which could be interpreted by the scilab. The code in the file is as following:
|
|
</p>
|
|
|
|
<div class="code"><pre>....
|
|
example.ICONST = 42
|
|
example.FCONST = 2.1828
|
|
example.CCONST = ascii(120)
|
|
example.CCONST2 = ascii(10)
|
|
example.SCONST = "Hello World"
|
|
example.SCONST2 = """Hello World"""
|
|
example.EXPR = 42+3*(2.1828)
|
|
example.iconst = 37
|
|
example.fconst = 3.14
|
|
.... </pre></div>
|
|
<p>It is easy to use the C constants after run the command "exec example.sce":</p>
|
|
|
|
<div class="targetlang"><pre>
|
|
scilab:1> exec example.sce;
|
|
scilab:2> example.ICONST
|
|
ans= 42
|
|
scilab:3> example.FCONST
|
|
ans= 2.1828
|
|
scilab:4> example.CCONST
|
|
ans=x
|
|
scilab:5> example.CCONST2
|
|
ans=
|
|
|
|
scilab:6> example.SCONST
|
|
ans= Hello World
|
|
scilab:7> example.SCONST2
|
|
ans= "Hello World"
|
|
scilab:8> example.EXPR
|
|
ans= 48.5484
|
|
scilab:9> example.iconst
|
|
ans= 37
|
|
scilab:10> example.fconst
|
|
ans= 3.14
|
|
</pre></div>
|
|
|
|
<H3><a name="Scilab_nn12"></a>27.3.5 Enums</H3>
|
|
|
|
<p> The way that deals with the enums is similar to the constants. For example:
|
|
</p>
|
|
|
|
<div class="code"><pre>%module example
|
|
typedef enum { RED, BLUE, GREEN } color;
|
|
</pre></div>
|
|
|
|
<p>
|
|
A file called example.sce will be created, which could be interpreted by the scilab. The code in the file is as following:
|
|
</p>
|
|
|
|
<div class="code"><pre>....
|
|
color.RED=0;
|
|
color.BLUE=color.RED + 1;
|
|
color.GREEN=color.BLUE + 1;
|
|
.... </pre></div>
|
|
<p>It is easy to use the enums after run the command "exec example.sce":</p>
|
|
|
|
<div class="targetlang"><pre>
|
|
scilab:1> exec example.sce;
|
|
scilab:2> printf(" RED = %i\n", color.RED);
|
|
RED = 0
|
|
|
|
scilab:3> printf(" BLUE = %i\n", color.BLUE);
|
|
BLUE = 1
|
|
|
|
scilab:4> printf(" GREEN = %i\n", color.GREEN);
|
|
GREEN = 2
|
|
</pre></div>
|
|
|
|
|
|
|