Add in Octave and R sections
git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk@10292 626c5289-ae23-0410-ae9c-e8d60b6d4f22
This commit is contained in:
William S Fulton
parent
2ded60495f
commit
f74c2b9ede
36 changed files with 1628 additions and 1585 deletions
|
|
@ -8,14 +8,13 @@
|
|||
|
||||
<body bgcolor="#ffffff">
|
||||
|
||||
<H1><a name="Octave_nn1"></a>22 SWIG and Octave</H1>
|
||||
<H1><a name="Octave"></a>18 SWIG and Octave</H1>
|
||||
<!-- INDEX -->
|
||||
<div class="sectiontoc">
|
||||
<ul>
|
||||
<li><a href="#Octave_nn2">Preliminaries</a>
|
||||
<li><a href="#Octave_nn3">Running SWIG</a>
|
||||
<ul>
|
||||
<li><a href="#Octave_nn4">Compiling and Linking and Interpreter</a>
|
||||
<li><a href="#Octave_nn5">Compiling a dynamic module</a>
|
||||
<li><a href="#Octave_nn6">Using your module</a>
|
||||
</ul>
|
||||
|
|
@ -35,20 +34,18 @@
|
|||
<li><a href="#Octave_nn19">Class extension with %extend</a>
|
||||
<li><a href="#Octave_nn20">C++ templates</a>
|
||||
<li><a href="#Octave_nn21">C++ Smart Pointers</a>
|
||||
</ul>
|
||||
<li><a href="#Octave_nn22">Details...</a>
|
||||
<ul>
|
||||
<li><a href="#Octave_nn22">Directors (calling Octave from C++ code)</a>
|
||||
<li><a href="#Octave_nn23">Threads</a>
|
||||
<li><a href="#Octave_nn24">Memory management</a>
|
||||
<li><a href="#Octave_nn25">STL support</a>
|
||||
<li><a href="#Octave_nn26">Matrix typemaps</a>
|
||||
</ul>
|
||||
<ul>
|
||||
</ul>
|
||||
</ul>
|
||||
</div>
|
||||
<!-- INDEX -->
|
||||
|
||||
|
||||
|
||||
<p>
|
||||
Octave is a high-level language intended for numerical programming that is mostly compatible with MATLAB.
|
||||
More information can be found at <a href="http://www.octave.org">octave.org</a>.
|
||||
|
|
@ -66,13 +63,16 @@ For now, the best way to find information about how to use the Octave module is
|
|||
The bulk of the Octave-specific wrapper generator code is in Source/Modules/octave.cxx. The runtime components are in Lib/octave, and in particular Lib/octave/octrun.swg.
|
||||
</p>
|
||||
|
||||
<H2><a name="Octave_nn2"></a>22.1 Preliminaries</H2>
|
||||
<H2><a name="Octave_nn2"></a>18.1 Preliminaries</H2>
|
||||
|
||||
|
||||
<p>
|
||||
The current SWIG implemention is based on Octave 2.9.12. Support for other versions (in particular the recent 3.0) has not been tested, nor has support for any OS other than Linux.
|
||||
</p>
|
||||
|
||||
<H2><a name="Octave_nn3"></a>22.2 Running SWIG</H2>
|
||||
<H2><a name="Octave_nn3"></a>18.2 Running SWIG</H2>
|
||||
|
||||
|
||||
<p>
|
||||
Let's start with a very simple SWIG interface file:
|
||||
</p>
|
||||
|
|
@ -102,7 +102,8 @@ This creates a C/C++ source file <tt>example_wrap.cxx</tt>. The generated C++ so
|
|||
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="Octave_nn5"></a>22.2.2 Compiling a dynamic module</H3>
|
||||
<H3><a name="Octave_nn5"></a>18.2.1 Compiling a dynamic module</H3>
|
||||
|
||||
|
||||
<p>
|
||||
Octave modules are DLLs/shared objects having the ".oct" suffix.
|
||||
|
|
@ -133,7 +134,9 @@ $ mkoctfile example_wrap.cxx example.c
|
|||
</p>
|
||||
|
||||
<p>
|
||||
<H3><a name="Octave_nn6"></a>22.2.3 Using your module</H3>
|
||||
<H3><a name="Octave_nn6"></a>18.2.2 Using your module</H3>
|
||||
|
||||
|
||||
</p>
|
||||
|
||||
<p>
|
||||
|
|
@ -153,9 +156,11 @@ octave:5> example.cvar.Foo
|
|||
ans = 4 </pre></div>
|
||||
</p>
|
||||
|
||||
<H2><a name="Octave_nn7"></a>22.3 A tour of basic C/C++ wrapping</H2>
|
||||
<H2><a name="Octave_nn7"></a>18.3 A tour of basic C/C++ wrapping</H2>
|
||||
|
||||
|
||||
<H3><a name="Octave_nn8"></a>18.3.1 Modules</H3>
|
||||
|
||||
<H3><a name="Octave_nn8"></a>22.3.1 Modules</H3>
|
||||
|
||||
<p>
|
||||
The SWIG module directive specifies the name of the Octave module. If you specify `module example', then in Octave everything in the module will be accessible under "example", as in the above example. When choosing a module name, make sure you don't use the same name as a built-in Octave command or standard module name.
|
||||
|
|
@ -202,7 +207,9 @@ octave:1> some_vars = cvar;
|
|||
</div></pre>
|
||||
</p>
|
||||
|
||||
<H3><a name="Octave_nn9"></a>22.3.2 Functions</H3>
|
||||
<H3><a name="Octave_nn9"></a>18.3.2 Functions</H3>
|
||||
|
||||
|
||||
<p>
|
||||
Global functions are wrapped as new Octave built-in functions. For example,
|
||||
</p>
|
||||
|
|
@ -222,7 +229,9 @@ int fact(int n); </pre></div>
|
|||
</p>
|
||||
|
||||
<p>
|
||||
If there are name collisions (especially if using the "global" option), the last-loaded functions (in this case those from the SWIG module) will override the previously defined ones. <H3><a name="Octave_nn10"></a>22.3.3 Global variables</H3>
|
||||
<H3><a name="Octave_nn10"></a>18.3.3 Global variables</H3>
|
||||
|
||||
|
||||
<p>
|
||||
Global variables are a little special in Octave. Given a global variable:
|
||||
</p>
|
||||
|
|
@ -283,7 +292,9 @@ octave:3> example.PI
|
|||
ans = 3.1420 </pre></div>
|
||||
</p>
|
||||
|
||||
<H3><a name="Octave_nn11"></a>22.3.4 Constants and enums</H3>
|
||||
<H3><a name="Octave_nn11"></a>18.3.4 Constants and enums</H3>
|
||||
|
||||
|
||||
<p>
|
||||
Because Octave doesn't really have the concept of constants, C/C++ constants are not really constant in Octave. They are actually just a copy of the value into the Octave interpreter. Therefore they can be changed just as any other value. For example given some constants:
|
||||
</p>
|
||||
|
|
@ -308,7 +319,9 @@ example.SUNDAY=0
|
|||
</p>
|
||||
|
||||
<p>
|
||||
Constants are not guaranteed to remain constant in Octave. The name of the constant could be accidentally reassigned to refer to some other object. Unfortunately, there is no easy way for SWIG to generate code that prevents this. You will just have to be careful. <H3><a name="Octave_nn12"></a>22.3.5 Pointers</H3>
|
||||
<H3><a name="Octave_nn12"></a>18.3.5 Pointers</H3>
|
||||
|
||||
|
||||
</p>
|
||||
|
||||
<p>
|
||||
|
|
@ -363,7 +376,9 @@ error: value on right hand side of assignment is undefined
|
|||
error: evaluating assignment expression near line 2, column 2 </pre></div>
|
||||
</p>
|
||||
|
||||
<H3><a name="Octave_nn13"></a>22.3.6 Structures</H3>
|
||||
<H3><a name="Octave_nn13"></a>18.3.6 Structures</H3>
|
||||
|
||||
|
||||
<p>
|
||||
SWIG wraps C structures and C++ classes by creating type objects. When invoked as a function, they create a new object of their type. The structures/classes themselves are mapped to a native Octave type. This provides a very natural interface. For example,
|
||||
</p>
|
||||
|
|
@ -391,17 +406,23 @@ ans = 5
|
|||
</pre></div>
|
||||
</p>
|
||||
|
||||
<H3><a name="Octave_nn14"></a>22.3.7 C++ classes</H3>
|
||||
<H3><a name="Octave_nn14"></a>18.3.7 C++ classes</H3>
|
||||
|
||||
|
||||
<p>
|
||||
C++ classes are handled in a way identical to other modules.
|
||||
</p>
|
||||
|
||||
<H3><a name="Octave_nn15"></a>22.3.8 C++ inheritance</H3>
|
||||
<H3><a name="Octave_nn15"></a>18.3.8 C++ inheritance</H3>
|
||||
|
||||
|
||||
<p>
|
||||
Inheritance is handled in a way identical to other modules.
|
||||
</p>
|
||||
|
||||
<H3><a name="Octave_nn16"></a>22.3.9 Pointers, references, values, and arrays</H3>
|
||||
<H3><a name="Octave_nn16"></a>18.3.9 Pointers, references, values, and arrays</H3>
|
||||
|
||||
|
||||
<p>
|
||||
Pointers, references, values, and arrays are handled in the same way as other modules.
|
||||
</p>
|
||||
|
|
@ -409,12 +430,16 @@ Pointers, references, values, and arrays are handled in the same way as other mo
|
|||
There are still some failing tests relating to global arrays.
|
||||
</p>
|
||||
|
||||
<H3><a name="Octave_nn17"></a>22.3.10 C++ overloaded functions</H3>
|
||||
<H3><a name="Octave_nn17"></a>18.3.10 C++ overloaded functions</H3>
|
||||
|
||||
|
||||
<p>
|
||||
Overloaded functions are supported, and handled as in other modules.
|
||||
</p>
|
||||
|
||||
<H3><a name="Octave_nn18"></a>22.3.11 C++ operators</H3>
|
||||
<H3><a name="Octave_nn18"></a>18.3.11 C++ operators</H3>
|
||||
|
||||
|
||||
<p>
|
||||
C++ operator overloading is supported, in a way similar to other modules.
|
||||
</p>
|
||||
|
|
@ -522,7 +547,9 @@ On the C++ side, the default mappings are as follows:
|
|||
%rename(__brace) *::operator[];
|
||||
</pre></div>
|
||||
|
||||
<H3><a name="Octave_nn19"></a>22.3.12 Class extension with %extend</H3>
|
||||
<H3><a name="Octave_nn19"></a>18.3.12 Class extension with %extend</H3>
|
||||
|
||||
|
||||
<p>
|
||||
The %extend directive works the same as in other modules.
|
||||
</p>
|
||||
|
|
@ -554,17 +581,23 @@ octave:4> a.__str()
|
|||
4
|
||||
</pre></div>
|
||||
</p>
|
||||
<H3><a name="Octave_nn20"></a>22.3.13 C++ templates</H3>
|
||||
<H3><a name="Octave_nn20"></a>18.3.13 C++ templates</H3>
|
||||
|
||||
|
||||
<p>
|
||||
C++ templates are fully supported, as in other modules.
|
||||
</p>
|
||||
|
||||
<H3><a name="Octave_nn21"></a>22.3.14 C++ Smart Pointers</H3>
|
||||
<H3><a name="Octave_nn21"></a>18.3.14 C++ Smart Pointers</H3>
|
||||
|
||||
|
||||
<p>
|
||||
C++ smart pointers are fully supported, as in other modules.
|
||||
</p>
|
||||
|
||||
<H3><a name="Octave_nn22"></a>22.4.1 Directors (calling Octave from C++ code)</H3>
|
||||
<H3><a name="Octave_nn22"></a>18.3.15 Directors (calling Octave from C++ code)</H3>
|
||||
|
||||
|
||||
<p>
|
||||
There is full support for SWIG Directors, which permits Octave code to subclass C++ classes, and implement their virtual methods.
|
||||
</p>
|
||||
|
|
@ -654,12 +687,16 @@ octave-side routine called
|
|||
</pre></div>
|
||||
</p>
|
||||
|
||||
<H3><a name="Octave_nn23"></a>22.4.1 Threads</H3>
|
||||
<H3><a name="Octave_nn23"></a>18.3.16 Threads</H3>
|
||||
|
||||
|
||||
<p>
|
||||
The use of threads in wrapped Director code is not supported; i.e., an Octave-side implementation of a C++ class must be called from the Octave interpreter's thread. Anything fancier (apartment/queue model, whatever) is left to the user. Without anything fancier, this amounts to the limitation that Octave must drive the module... like, for example, an optimization package that calls Octave to evaluate an objective function.
|
||||
</p>
|
||||
|
||||
<H3><a name="Octave_nn24"></a>22.4.3 Memory management</H3>
|
||||
<H3><a name="Octave_nn24"></a>18.3.17 Memory management</H3>
|
||||
|
||||
|
||||
<p>
|
||||
All Octave objects are referenced counted internally. SWIG-wrapped objects are no different. This means that destructors get called when the Octave object's reference count goes to zero.
|
||||
</p>
|
||||
|
|
@ -692,12 +729,16 @@ A destructing
|
|||
In the case where one wishes for the C++ side to own an object that was created in Octave (especially a Director object), one can use the __disown() method to invert this logic. Then letting the Octave reference count go to zero will not destroy the object, but destroying the object will invalidate the Octave-side object if it still exists (and call destructors of other C++ bases in the case of multiple inheritance/<tt>subclass()</tt>'ing).
|
||||
</p>
|
||||
|
||||
<H3><a name="Octave_nn25"></a>22.4.3 STL support</H3>
|
||||
<H3><a name="Octave_nn25"></a>18.3.18 STL support</H3>
|
||||
|
||||
|
||||
<p>
|
||||
This is some skeleton support for various STL containers, but this work is not finished.
|
||||
</p>
|
||||
|
||||
<H3><a name="Octave_nn26"></a>22.4.3 Matrix typemaps</H3>
|
||||
<H3><a name="Octave_nn26"></a>18.3.19 Matrix typemaps</H3>
|
||||
|
||||
|
||||
<p>
|
||||
Octave provides a rich set of classes for dealing with matrices etc. Currently there are no typemaps to deal with those, though such support will be added soon. However, these are relatively straight forward for users to add themselves (see the docs on typemaps). Without much work (a single typemap decl-- say, 5 lines of code in the interface file), it would be possible to have a function
|
||||
</p>
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue