jyapayne/swig
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Merge trunk rev 13025 (swig-2.0.6) into gsoc2008-maciekd

Browse source 
Conflicts:
	Doc/Manual/chapters
	Examples/Makefile.in
	Examples/test-suite/dynamic_cast.i
	Lib/exception.i
	Makefile.in
	Source/Include/swigwarn.h
	Source/Modules/swigmain.cxx
	Source/Swig/swig.h
	Tools/config/config.guess
	Tools/config/config.sub
	configure.in

From: William S Fulton <wsf@fultondesigns.co.uk>

git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/branches/gsoc2008-maciekd@13036 626c5289-ae23-0410-ae9c-e8d60b6d4f22
This commit is contained in:
William S Fulton 2012-05-07 16:59:38 +00:00
commit e0067ea998
2152 changed files with 99389 additions and 53536 deletions
Download patch file Download diff file Expand all files Collapse all files

2
Doc/Devel/cmdopt.html
View file

@ -36,7 +36,7 @@ functions to mark whether or not a particular command line option was used. Thi
<h2>Argument Marking</h2>
As command line options are are processed by language modules, the following functions are used
As command line options are processed by language modules, the following functions are used
to mark the arguments as used:
<p>

17
Doc/Devel/engineering.html
View file

@ -119,22 +119,25 @@ are case-insensitive on Windows so this convention will prevent you from inadver
creating two files that differ in case-only.
<p>
Each file should include a short abstract, author information, copyright information, and
Each file should include a short abstract, license information and
a SVN revision tag like this:
<blockquote>
<pre>
/* -----------------------------------------------------------------------------
* See the LICENSE file for information on copyright, usage and redistribution
* of SWIG, and the README file for authors - http://www.swig.org/release.html.
* This file is part of SWIG, which is licensed as a whole under version 3
* (or any later version) of the GNU General Public License. Some additional
* terms also apply to certain portions of SWIG. The full details of the SWIG
* license and copyrights can be found in the LICENSE and COPYRIGHT files
* included with the SWIG source code as distributed by the SWIG developers
* and at http://www.swig.org/legal.html.
*
* cwrap.c
* xxx.c
*
* This file defines a variety of wrapping rules for C/C++ handling including
* the naming of local variables, calling conventions, and so forth.
* This file defines ...
* ----------------------------------------------------------------------------- */
char cvsroot_cwrap_c[] = "$Id$";
static char cvs[] = "&#36Id&#36";
#include "swig.h"

1
Doc/Devel/index.html
View file

@ -21,6 +21,7 @@ The following documentation describe the internal APIs used by SWIG. These may
<li><a href="parm.html">Parameter and Parameter list handling functions</a>
<li><a href="scanner.html">Generic C/C++ Scanner interface</a>
<li><a href="wrapobj.html">Wrapper objects</a>.
<li><a href="runtime.txt">SWIG Runtime</a>.
</ul>
<hr>

254
Doc/Devel/internals.html
View file

@ -7,11 +7,6 @@
<center>
<h1>SWIG Internals Manual</h1>
<b>Thien-Thi Nguyen <br>
<p>
David M. Beazley <br>
</b>
</center>
@ -42,11 +37,12 @@ David M. Beazley <br>
</ul>
<li><a name="i3" href="#3">3. Types and Typemaps</a>
<li><a name="i4" href="#4">4. Parsing</a>
<li><a name="i5" href="#5">5. Difference Between SWIG 1.1 and SWIG 1.3</a>
<li><a name="i6" href="#6">6. Plans for SWIG 2.0</a>
<li><a name="i7" href="#7">7. C/C++ Wrapper Support Functions</a>
<li><a name="i8" href="#8">8. Symbol Naming Guidelines for Generated C/C++ Code</a>
<li><a name="i9" href="#9">9. Debugging SWIG</a>
<li><a name="i5" href="#5">5. C/C++ Wrapper Support Functions</a>
<li><a name="i6" href="#6">6. Symbol Naming Guidelines for Generated C/C++ Code</a>
<li><a name="i7" href="#7">7. Debugging SWIG</a>
<ul>
<li><a name="i7.1" href="#7.1">7.1 Debugging DOH Types The Hard Way</a>
</ul>
</ul>
<a name="1" href="#i1">
@ -76,9 +72,8 @@ to code).
<tr><td>Examples</td>
<td>This subdir tree contains examples of using SWIG w/ different
scripting languages, including makefiles. Typically, there are the
"simple" and "matrix" examples, w/ some languages offering additional
examples. The GIFPlot example has its own set of per-language
subdirectories. See the README more index.html file in each directory
"simple" and "class" examples, w/ some languages offering additional
examples. See the README more index.html file in each directory
for more info. [FIXME: Ref SWIG user manual.]</td>
</tr>
@ -97,55 +92,35 @@ info.</td>
</tr>
<tr><td>Source</td>
<td>SWIG source code is in this subdir tree. Directories marked w/ "(*)"
are used in building the <tt>swig</tt> executable.
<td>The C and C++ source code for the <tt>swig</tt> executable is in this
subdir tree.</td>
<table border=1>
<tr><td>DOH (*)</td>
<tr><td>DOH</td>
<td>C library providing memory allocation, file access and generic
containers. Result: libdoh.a</td>
containers.</td>
</tr>
<tr><td>Experiment</td>
<td>[TODO]</td>
</tr>
<tr><td>Include (*)</td>
<tr><td>Include</td>
<td>Configuration .h files</td>
</tr>
<tr><td>LParse</td>
<td>Parser (lex / yacc) files and support [why not (*)?!]</td>
<tr><td>CParse</td>
<td>Parser (lex / yacc) files and support</td>
</tr>
<tr><td>Modules</td>
<td>[TODO]</td>
</tr>
<tr><td>Modules1.1 (*)</td>
<td>Language-specific callbacks that does actual code generation (each
language has a .cxx and a .h file). Result: libmodules11.a</td>
language has a .cxx and a .h file).</td>
</tr>
<tr><td>Preprocessor (*)</td>
<td>SWIG-specialized C/C++ preprocessor. Result: libcpp.a</td>
<tr><td>Preprocessor</td>
<td>SWIG-specialized C/C++ preprocessor.</td>
</tr>
<tr><td>SWIG1.1 (*)</td>
<td>Parts of SWIG that are not language-specific, including option
processing and the type-mapping system. Result: libswig11.a.
Note: This directory is currently being phased out. </td>
</tr>
<tr><td>SWIG1.3</td>
<td>[TODO] [funny, nothing here is presently used for swig-1.3].
This directory might turn into a compatibility interface between
SWIG1.3 and the SWIG1.1 modules.</td>
</tr>
<tr><td>Swig (*)</td>
<td>This directory contains the new ANSI C core of the system
<tr><td>Swig</td>
<td>This directory contains the ANSI C core of the system
and contains generic functions related to types, file handling,
scanning, and so forth.</td>
</tr>
@ -154,7 +129,7 @@ are used in building the <tt>swig</tt> executable.
</tr>
<tr><td>Tools</td>
<td>Libtool support and the mkdist.py script.</td>
<td>The mkdist.py script and other tools.</td>
</tr>
<tr><td>Win</td>
@ -173,14 +148,14 @@ to look for code:
<ul>
<li> <tt>Modules1.1/swigmain.cxx:main()</tt> is the program entry
<li> <tt>Modules/swigmain.cxx:main()</tt> is the program entry
point. It parses the language-specifying command-line option (for
example, <tt>-java</tt>), creating a new language-specific wrapping
object (each language is a C++ class derived from base class
<tt>Language</tt>). This object and the command-line is passed to
<tt>SWIG_main()</tt>, whose return value is the program exit value.
<li> <tt>SWIG1.1/main.cxx:SWIG_main()</tt> is the "real" main. It
<li> <tt>Modules/main.cxx:SWIG_main()</tt> is the "real" main. It
initializes the preprocessor and typemap machinery, defines some
preprocessor symbols, locates the SWIG library, processes common
command-line options, and then calls the language-specific command-line
@ -203,7 +178,7 @@ included <tt>-freeze</tt>, go into an infinite loop; otherwise return the
error count.
<li> The language-specific <tt>parse()</tt> (and all other
language-specific code) lives in <tt>Modules1.1/foo.{h,cxx}</tt> for
language-specific code) lives in <tt>Modules/foo.{h,cxx}</tt> for
language Foo. Typically, <tt>FOO::parse()</tt> calls
<tt>FOO::headers()</tt> and then the global function <tt>yyparse()</tt>,
which uses the callbacks registered by <tt>SWIG_main()</tt> above.
@ -553,8 +528,7 @@ list item: listval5
The representation and manipulation of types is currently in the
process of being reorganized and (hopefully) simplified. The
following list describes the current set of functions that are used to
manipulate datatypes. These functions are different than in
SWIG1.1 and may change names in the final SWIG1.3 release.
manipulate datatypes.
<ul>
<li><tt>SwigType_str(SwigType *t, char *name)</tt>.<br>
@ -710,19 +684,7 @@ repeated calls without making any copies.
[TODO]
<a name="5" href="#i5">
<h2>5. Difference Between SWIG 1.1 and SWIG 1.3</h2>
</a>
[TODO]
<a name="6" href="#i6">
<h2>6. Plans for SWIG 2.0</h2>
</a>
[TODO]
<a name="7" href="#i7">
<h2>7. The C/C++ Wrapping Layer</h2>
<h2>5. The C/C++ Wrapping Layer</h2>
</a>
Added: Dave Beazley (July 22, 2000)
@ -1001,8 +963,8 @@ for specifying local variable declarations and argument conversions.
<a name="8" href="#i8">
<h2>8. Symbol Naming Guidelines for Generated C/C++ Code</h2>
<a name="6" href="#i6">
<h2>6. Symbol Naming Guidelines for Generated C/C++ Code</h2>
</a>
The C++ standard (ISO/IEC 14882:1998(E)) states:
<blockquote>
@ -1048,18 +1010,142 @@ For code compiled as C or C++ that attempts to mangle a wrapped symbol:
In the past SWIG has generated many symbols which flout the standard especially double underscores. In fact they may not all be rooted out yet, so please fix them when you see them.
<a name="9" href="#i9">
<h2>9. Debugging SWIG</h2>
<a name="7" href="#i7">
<h2>7. Debugging SWIG</h2>
</a>
Warning. Debugging SWIG is for the very patient.
<p>
The DOH types used in the SWIG source code are all typedefined to void.
Consequently, it is impossible for debuggers to automatically extract any information about DOH objects.
The easiest approach to debugging and viewing the contents of DOH objects is to make a call into one of the family of SWIG print functions from the debugger.
The "Debugging Functions" section in <a href="tree.html">SWIG Parse Tree Handling</a> lists them.
It is sometimes easier to debug by placing a few calls to these functions in code of interest and recompile, especially if your debugger cannot easily make calls into functions within a debugged binary.
</p>
<p>
The SWIG distribution comes with some additional support for the gdb debugger in the <tt>Tools/swig.gdb</tt> file.
Follow the instructions in this file for 'installing'.
This support file provides an easy way to call into some of the family of SWIG print functions via additional user-defined gdb commands.
Some usage of the <tt>swigprint</tt> and <tt>locswigprint</tt> user-defined commands are demonstrated below.
</p>
<p>
More often than not, a parse tree node needs to be examined.
The session below displays the node <tt>n</tt> in one of the Java language module wrapper functions.
The <tt>swigprint</tt> method is used to show the symbol name (<tt>symname</tt> - a DOH String type) and the node (<tt>n</tt> - a DOH Hash type).
</p>
<blockquote>
<pre>
Breakpoint 1, JAVA::functionWrapper (this=0x97ea5f0, n=0xb7d2afc8) at Modules/java.cxx:799
799 String *symname = Getattr(n, "sym:name");
(gdb) next
800 SwigType *t = Getattr(n, "type");
(gdb) swigprint symname
Shape_x_set
(gdb) swigprint n
Hash(0xb7d2afc8) {
'membervariableHandler:view' : variableHandler,
'feature:except' : 0,
'name' : x,
'ismember' : 1,
'sym:symtab' : Hash(0xb7d2aca8) {......},
'nodeType' : cdecl,
'nextSibling' : Hash(0xb7d2af98) {.............},
'kind' : variable,
'variableHandler:feature:immutable' : &lt;Object 'VoidObj' at 0xb7cfa008&gt;,
'sym:name' : Shape_x_set,
'view' : membervariableHandler,
'membervariableHandler:sym:name' : x,
'membervariableHandler:type' : double,
'membervariableHandler:parms' : &lt;Object 'VoidObj' at 0xb7cfa008&gt;,
'parentNode' : Hash(0xb7d2abc8) {..............................},
'feature:java:enum' : typesafe,
'access' : public,
'parms' : Hash(0xb7cb9408) {......},
'wrap:action' : if (arg1) (arg1)-&gt;x = arg2;,
'type' : void,
'memberset' : 1,
'sym:overname' : __SWIG_0,
'membervariableHandler:name' : x,
}
</pre>
</blockquote>
<p>
Note that all the attributes in the Hash are shown, including the 'sym:name' attribute which was assigned to the <tt>symname</tt> variable.
</p>
<p>
Hash types can be shown either expanded or collapsed.
When a Hash is shown expanded, all the attributes are displayed along with their values, otherwise a '.' replaces each attribute when collapsed.
Therefore a count of the dots provides the number of attributes within an unexpanded Hash.
Below shows the 'parms' Hash being displayed with the default Hash expansion of 1, then with 2 provided as the second argument to <tt>swigprint</tt> to expand to two Hash levels in order to view the contents of the collapsed 'nextSibling' Hash.
</p>
<blockquote>
<pre>
(gdb) swigprint 0xb7cb9408
Hash(0xb7cb9408) {
'name' : self,
'type' : p.Shape,
'self' : 1,
'nextSibling' : Hash(0xb7cb9498) {...},
'hidden' : 1,
'nodeType' : parm,
}
(gdb) swigprint 0xb7cb9408 2
Hash(0xb7cb9408) {
'name' : self,
'type' : p.Shape,
'self' : 1,
'nextSibling' : Hash(0xb7cb9498) {
'name' : x,
'type' : double,
'nodeType' : parm,
},
'hidden' : 1,
'nodeType' : parm,
}
</pre>
</blockquote>
<p>
The same Hash can also be displayed with file and line location information via the <tt>locswigprint</tt> command.
</p>
<blockquote>
<pre>
(gdb) locswigprint 0xb7cb9408
example.h:11: [Hash(0xb7cb9408) {
Hash(0xb7cb9408) {
'name' : self,
'type' : p.Shape,
'self' : 1,
'nextSibling' : Hash(0xb7cb9498) {...},
'hidden' : 1,
'nodeType' : parm,
}]
</pre>
</blockquote>
<p>
<b>Tip</b>: Commands in gdb can be shortened with whatever makes them unique and can be command completed with the tab key.
Thus <tt>swigprint</tt> can usually be shortened to <tt>sw</tt> and <tt>locswigprint</tt> to <tt>loc</tt>.
The help for each command can also be obtained within the debugging session, for example, 'help swigprint'.
</p>
<p>
The sub-section below gives pointers for debugging DOH objects using casts and provides an insight into why it can be hard to debug SWIG without the family of print functions.
<p>
The DOH types are all typedefined to void.
Consequently, it is impossible for debuggers to extract any information about DOH objects.
Most debuggers will be able to display useful variable information when an object is cast to the appropriate type.
Below are some tips for displaying some of the DOH objects.
Be sure to compile with compiler optimisations turned off before attempting the casts shown in a debugger window else they are unlikely to work.
Even displaying the underlying string in a String* doesn't work straight off in all debuggers due to the multiple definition of String as a struct and a void.
<a name="7.1" href="#i7.1">
<h3>7.1 Debugging DOH Types The Hard Way</h3>
</a>
The DOH types used in SWIG are all typedefined to void and hence the lack of type information for inspecting types within a debugger.
Most debuggers will however be able to display useful variable information when an object is cast to the appropriate type.
Getting at the underlying C string within DOH types is cumbersome, but possible with appropriate casts.
The casts below can be used in a debugger windows, but be sure to compile with compiler optimisations turned off before attempting the casts else they are unlikely to work.
Even displaying the underlying string in a String * doesn't work straight off in all debuggers due to the multiple definitions of String as a struct and a void.
<p>
Below are a list of common SWIG types.
@ -1069,34 +1155,32 @@ With each is the cast that can be used in the debugger to extract the underlying
<p>
<li>String *s;</li>
<br>
(String *)((DohBase *)s)-&gt;data
<tt>(struct String *)((DohBase *)s)-&gt;data</tt>
<br>
The underlying char * string can be displayed with
<br>
((String *)((DohBase *)s)-&gt;data)-&gt;str
<tt>(*(struct String *)(((DohBase *)s)-&gt;data)).str</tt>
<p>
<li>SwigType *t;</li>
<br>
(String *)((DohBase *)t)-&gt;data
<tt>(struct String *)((DohBase *)t)-&gt;data</tt>
<br>
The underlying char * string can be displayed with
<br>
((String *)((DohBase *)t)-&gt;data)-&gt;str
<tt>(*(struct String *)(((DohBase *)t)-&gt;data)).str</tt>
<p>
<li>String_or_char *sc;</li>
<li>const_String_or_char_ptr sc;</li>
Either <br>
((String *)((DohBase *)sc)-&gt;data)-&gt;str
<tt>(*(struct String *)(((DohBase *)sc)-&gt;data)).str</tt>
<br> or <br>
(char *)sc
<tt>(char *)sc</tt>
<br> will work depending on whether the underlying type is really a String * or char *.
</ul>
<hr>
Copyright (C) 1999-2004 SWIG Development Team.
Copyright (C) 1999-2010 SWIG Development Team.
</body>
</html>

9
Doc/Devel/scanner.html
View file

@ -77,7 +77,7 @@ string prior to using this function.
Pushes a token into the scanner. This exact token will be returned by the next call to <tt>Scanner_token()</tt>.
<tt>tokvalue</tt> is the integer token value to return and <tt>val</tt> is the token text to return. This
function is only used to handle very special parsing cases. For instance, if you need the scanner to
return a ficticious token into order to enter a special parsing case.
return a fictitious token into order to enter a special parsing case.
</blockquote>
<p>
@ -238,7 +238,7 @@ SWIG_TOKEN_PERIOD .
SWIG_TOKEN_AT @
SWIG_TOKEN_DOLLAR $
SWIG_TOKEN_ENDLINE Literal newline
SWIG_TOKEN_ID identifer
SWIG_TOKEN_ID identifier
SWIG_TOKEN_FLOAT Floating point with F suffix (e.g., 3.1415F)
SWIG_TOKEN_DOUBLE Floating point (e.g., 3.1415 )
SWIG_TOKEN_INT Integer (e.g., 314)
@ -281,8 +281,3 @@ using these functions to write a yacc-compatible lexer.
</body>
</html>

45
Doc/Devel/tree.html
View file

@ -6,13 +6,6 @@
<body>
<center>
<h1>SWIG Parse Tree Handling</h1>
<p>
David M. Beazley <br>
dave-swig@dabeaz.com<br>
December, 2006<br>
</b>
</center>
<h2>Introduction</h2>
@ -210,7 +203,33 @@ This function restores a node to the state it was in prior to the last <tt>Swig_
<h2>Debugging Functions</h2>
The following functions are used to help debug SWIG parse trees.
<p>
The following functions can be used to help debug any SWIG DOH object.
</p>
<b><tt>void Swig_print(DOH *object, int count = -1)</tt></b>
<blockquote>
Prints to stdout a string representation of any DOH type.
The number of nested Hash types to expand is set by count (default is 1 if count&lt;0). See Swig_set_max_hash_expand() to change default.
<pre>
</pre>
</blockquote>
<b><tt>void Swig_print_with_location(DOH *object, int count = -1)</tt></b>
<blockquote>
Prints to stdout a string representation of any DOH type, within [] brackets
for Hash and List types, prefixed by line and file information.
The number of nested Hash types to expand is set by count (default is 1 if count&lt;0). See Swig_set_max_hash_expand() to change default.
<pre>
</pre>
</blockquote>
<p>
The following functions can be used to help debug SWIG parse trees.
</p>
<p>
<b><tt>void Swig_print_tags(Node *node, String_or_char *prefix)</tt></b>
@ -218,10 +237,10 @@ The following functions are used to help debug SWIG parse trees.
<blockquote>
Prints the tag-structure of the parse tree to standard output. <tt>node</tt> is the top-level parse tree node. <tt>prefix</tt> is
a string prefix thats added to the start of each line. Normally, you would specify the empty string or NIL for <tt>prefix</tt>.
This function is called by the <tt>-dump_tags</tt> option to SWIG.
This function is called by the <tt>-debug-tags</tt> option to SWIG.
<pre>
% swig -dump_tags -python example.i
% swig -debug-tags -python example.i
. top (:1)
. top . include (/Users/beazley/Projects/share/swig/1.3.31/swig.swg:0)
. top . include . include (/Users/beazley/Projects/share/swig/1.3.31/swigwarnings.swg:0)
@ -243,7 +262,7 @@ Since many language modules include hundreds of typemaps and other information,
<blockquote>
Prints the contents of a parse tree node, including all children, to standard output. The output includes all attributes
and other details. The command line option <tt>-dump_tree</tt> produces output generated by this function.
and other details.
</blockquote>
<p>
@ -251,8 +270,8 @@ and other details. The command line option <tt>-dump_tree</tt> produces output
<blockquote>
Prints the same output as <tt>Swig_print_node()</tt> except that it also processes all of the siblings of <tt>node</tt>. This can
be used to dump the entire parse tree to standard output. Use the command line option <tt>-dump_tree</tt> to get
the output of this function for a SWIG input file.
be used to dump the entire parse tree to standard output. The command line options <tt>-debug-module</tt>
and <tt>-debug-top</tt> use this function to display the parse tree for a SWIG input file.
</blockquote>

116
Doc/Manual/Allegrocl.html Executable file → Normal file
View file

@ -8,13 +8,13 @@
<body bgcolor="#ffffff">
<H1><a name="Allegrocl_nn1"></a>16 SWIG and Allegro Common Lisp</H1>
<H1><a name="Allegrocl"></a>17 SWIG and Allegro Common Lisp</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="#Allegrocl_nn2">Basics</a>
<ul>
<li><a href="#Allegrocl_nn3">Running Swig</a>
<li><a href="#Allegrocl_nn3">Running SWIG</a>
<li><a href="#Allegrocl_nn4">Command Line Options</a>
<li><a href="#Allegrocl_nn5">Inserting user code into generated files</a>
</ul>
@ -135,10 +135,10 @@ be unhappy to see some enterprising folk use this work to add
to it.
</p>
<H2><a name="Allegrocl_nn2"></a>16.1 Basics</H2>
<H2><a name="Allegrocl_nn2"></a>17.1 Basics</H2>
<H3><a name="Allegrocl_nn3"></a>16.1.1 Running Swig</H3>
<H3><a name="Allegrocl_nn3"></a>17.1.1 Running SWIG</H3>
<p>
@ -360,7 +360,7 @@ need to link in the Allegro shared library. The library you create from
the C++ wrapper will be what you then load into Allegro CL.
</p>
<H3><a name="Allegrocl_nn4"></a>16.1.2 Command Line Options</H3>
<H3><a name="Allegrocl_nn4"></a>17.1.2 Command Line Options</H3>
<p>
@ -396,7 +396,7 @@ See <a href="#Allegrocl_nn47">Section 17.5 Identifier converter
functions</a> for more details.
</p>
<H3><a name="Allegrocl_nn5"></a>16.1.3 Inserting user code into generated files</H3>
<H3><a name="Allegrocl_nn5"></a>17.1.3 Inserting user code into generated files</H3>
<p>
@ -411,7 +411,7 @@ using the SWIG <tt>%insert(section) %{ ...code... %}</tt> directive:
<pre>
%module example
%insert("runtime") %{
%{
#include "header.h"
%}
@ -432,11 +432,11 @@ generated lisp interface file
</ul>
<p>
Note that the block <tt>%{ ... %}</tt> is effectively a shortcut for
<tt>%insert("runtime") %{ ... %}</tt>.
<tt>%insert("header") %{ ... %}</tt>.
</p>
<H2><a name="Allegrocl_nn6"></a>16.2 Wrapping Overview</H2>
<H2><a name="Allegrocl_nn6"></a>17.2 Wrapping Overview</H2>
<p>
@ -446,7 +446,7 @@ New users to SWIG are encouraged to read
interested in generating an interface to C++.
</p>
<H3><a name="Allegrocl_nn7"></a>16.2.1 Function Wrapping</H3>
<H3><a name="Allegrocl_nn7"></a>17.2.1 Function Wrapping</H3>
<p>
@ -499,7 +499,7 @@ interested in generating an interface to C++.
</pre>
</div>
<H3><a name="Allegrocl_nn8"></a>16.2.2 Foreign Wrappers</H3>
<H3><a name="Allegrocl_nn8"></a>17.2.2 Foreign Wrappers</H3>
<p>
@ -512,7 +512,7 @@ interested in generating an interface to C++.
typemap.
</p>
<H3><a name="Allegrocl_nn9"></a>16.2.3 FFI Wrappers</H3>
<H3><a name="Allegrocl_nn9"></a>17.2.3 FFI Wrappers</H3>
<p>
@ -593,7 +593,7 @@ char *xxx();
ff:def-foreign-call's.
</p>
<H3><a name="Allegrocl_nn10"></a>16.2.4 Non-overloaded Defuns</H3>
<H3><a name="Allegrocl_nn10"></a>17.2.4 Non-overloaded Defuns</H3>
<p>
@ -606,7 +606,7 @@ char *xxx();
this function can be manipulated via the <tt>lout</tt> typemap.
</p>
<H3><a name="Allegrocl_nn11"></a>16.2.5 Overloaded Defuns</H3>
<H3><a name="Allegrocl_nn11"></a>17.2.5 Overloaded Defuns</H3>
<p>
@ -622,7 +622,7 @@ char *xxx();
can be manipulated via the <tt>lout</tt> typemap.
</p>
<H3><a name="Allegrocl_nn12"></a>16.2.6 What about constant and variable access?</H3>
<H3><a name="Allegrocl_nn12"></a>17.2.6 What about constant and variable access?</H3>
<p>
@ -635,7 +635,7 @@ char *xxx();
into the foreign module.
</p>
<H3><a name="Allegrocl_nn13"></a>16.2.7 Object Wrapping</H3>
<H3><a name="Allegrocl_nn13"></a>17.2.7 Object Wrapping</H3>
<p>
@ -657,7 +657,7 @@ char *xxx();
foreign function interface.
</p>
<H2><a name="Allegrocl_nn14"></a>16.3 Wrapping Details</H2>
<H2><a name="Allegrocl_nn14"></a>17.3 Wrapping Details</H2>
<p>
@ -665,7 +665,7 @@ char *xxx();
translated into lisp.
</p>
<H3><a name="Allegrocl_nn15"></a>16.3.1 Namespaces</H3>
<H3><a name="Allegrocl_nn15"></a>17.3.1 Namespaces</H3>
<p>
@ -742,7 +742,7 @@ namespace car {
function such as <tt>(car '(1 2 3)</tt>.
</p>
<H3><a name="Allegrocl_nn16"></a>16.3.2 Constants</H3>
<H3><a name="Allegrocl_nn16"></a>17.3.2 Constants</H3>
@ -803,7 +803,7 @@ namespace car {
not use the <tt>-nocwrap</tt> command-line option.
</p>
<H3><a name="Allegrocl_nn17"></a>16.3.3 Variables</H3>
<H3><a name="Allegrocl_nn17"></a>17.3.3 Variables</H3>
<p>
@ -881,7 +881,7 @@ globalvar&gt; (globalvar.nnn::glob_float)
</pre>
</div>
<H3><a name="Allegrocl_nn18"></a>16.3.4 Enumerations</H3>
<H3><a name="Allegrocl_nn18"></a>17.3.4 Enumerations</H3>
<p>
@ -957,7 +957,7 @@ EXPORT const int ACL_ENUM___FOO3__SWIG_0 = FOO3;
</pre>
</div>
<H3><a name="Allegrocl_nn19"></a>16.3.5 Arrays</H3>
<H3><a name="Allegrocl_nn19"></a>17.3.5 Arrays</H3>
<p>
@ -1105,10 +1105,10 @@ namespace BAR {
</pre>
</div>
<H3><a name="Allegrocl_nn20"></a>16.3.6 Classes and Structs and Unions (oh my!)</H3>
<H3><a name="Allegrocl_nn20"></a>17.3.6 Classes and Structs and Unions (oh my!)</H3>
<H4><a name="Allegrocl_nn21"></a>16.3.6.1 CLOS wrapping of</H4>
<H4><a name="Allegrocl_nn21"></a>17.3.6.1 CLOS wrapping of</H4>
<p>
@ -1123,7 +1123,7 @@ namespace BAR {
integer values.
</p>
<H4><a name="Allegrocl_nn22"></a>16.3.6.2 CLOS Inheritance</H4>
<H4><a name="Allegrocl_nn22"></a>17.3.6.2 CLOS Inheritance</H4>
<p>
@ -1136,7 +1136,7 @@ namespace BAR {
parameter.
</p>
<H4><a name="Allegrocl_nn23"></a>16.3.6.3 Member fields and functions</H4>
<H4><a name="Allegrocl_nn23"></a>17.3.6.3 Member fields and functions</H4>
<p>
@ -1152,7 +1152,7 @@ namespace BAR {
the interface does nothing for <tt>friend</tt> directives,
</p>
<H4><a name="Allegrocl_nn24"></a>16.3.6.4 Why not directly access C++ classes using foreign types?</H4>
<H4><a name="Allegrocl_nn24"></a>17.3.6.4 Why not directly access C++ classes using foreign types?</H4>
<p>
@ -1170,11 +1170,11 @@ namespace BAR {
use the more robust wrapper functions.
</p>
<H3><a name="Allegrocl_nn25"></a>16.3.7 Templates</H3>
<H3><a name="Allegrocl_nn25"></a>17.3.7 Templates</H3>
<H4><a name="Allegrocl_nn26"></a>16.3.7.1 Generating wrapper code for templates</H4>
<H4><a name="Allegrocl_nn26"></a>17.3.7.1 Generating wrapper code for templates</H4>
<p>
@ -1187,7 +1187,7 @@ namespace BAR {
directive.
</p>
<H4><a name="Allegrocl_nn27"></a>16.3.7.2 Implicit Template instantiation</H4>
<H4><a name="Allegrocl_nn27"></a>17.3.7.2 Implicit Template instantiation</H4>
<p>
@ -1197,7 +1197,7 @@ namespace BAR {
class schema.
</p>
<H3><a name="Allegrocl_nn28"></a>16.3.8 Typedef, Templates, and Synonym Types</H3>
<H3><a name="Allegrocl_nn28"></a>17.3.8 Typedef, Templates, and Synonym Types</H3>
<p>
@ -1277,7 +1277,7 @@ synonym&gt;
</pre>
</div>
<H4><a name="Allegrocl_nn29"></a>16.3.8.1 Choosing a primary type</H4>
<H4><a name="Allegrocl_nn29"></a>17.3.8.1 Choosing a primary type</H4>
<p>
@ -1298,7 +1298,7 @@ synonym&gt;
</li>
</ul>
<H3><a name="Allegrocl_nn30"></a>16.3.9 Function overloading/Parameter defaulting</H3>
<H3><a name="Allegrocl_nn30"></a>17.3.9 Function overloading/Parameter defaulting</H3>
<p>
@ -1461,7 +1461,7 @@ overload&gt;
</pre>
</div>
<H3><a name="Allegrocl_nn31"></a>16.3.10 Operator wrapping and Operator overloading</H3>
<H3><a name="Allegrocl_nn31"></a>17.3.10 Operator wrapping and Operator overloading</H3>
<p>
@ -1607,7 +1607,7 @@ opoverload&gt;
</pre>
</div>
<H3><a name="Allegrocl_nn32"></a>16.3.11 Varargs</H3>
<H3><a name="Allegrocl_nn32"></a>17.3.11 Varargs</H3>
<p>
@ -1628,7 +1628,7 @@ opoverload&gt;
with other ways such functions can be wrapped.
</p>
<H3><a name="Allegrocl_nn33"></a>16.3.12 C++ Exceptions</H3>
<H3><a name="Allegrocl_nn33"></a>17.3.12 C++ Exceptions</H3>
<p>
@ -1640,7 +1640,7 @@ opoverload&gt;
implemented.
</p>
<H3><a name="Allegrocl_nn34"></a>16.3.13 Pass by value, pass by reference</H3>
<H3><a name="Allegrocl_nn34"></a>17.3.13 Pass by value, pass by reference</H3>
<p>
@ -1652,7 +1652,7 @@ opoverload&gt;
newly defined types.
</p>
<H2><a name="Allegrocl_nn35"></a>16.4 Typemaps</H2>
<H2><a name="Allegrocl_nn35"></a>17.4 Typemaps</H2>
<p>
@ -1663,7 +1663,7 @@ opoverload&gt;
on <a href="Typemaps.html#Typemaps">Typemaps</a> for more information.
</p>
<H3><a name="Allegrocl_nn36"></a>16.4.1 Code Generation in the C++ Wrapper</H3>
<H3><a name="Allegrocl_nn36"></a>17.4.1 Code Generation in the C++ Wrapper</H3>
@ -1693,7 +1693,7 @@ return-val wrapper-name(parm0, parm1, ..., parmN)
</pre>
</div>
<H4><a name="Allegrocl_nn37"></a>16.4.1.1 IN Typemap</H4>
<H4><a name="Allegrocl_nn37"></a>17.4.1.1 IN Typemap</H4>
<p>
@ -1728,7 +1728,7 @@ return-val wrapper-name(parm0, parm1, ..., parmN)
</pre>
</div>
<H4><a name="Allegrocl_nn38"></a>16.4.1.2 OUT Typemap</H4>
<H4><a name="Allegrocl_nn38"></a>17.4.1.2 OUT Typemap</H4>
<p>
@ -1752,7 +1752,7 @@ return-val wrapper-name(parm0, parm1, ..., parmN)
</pre>
</div>
<H4><a name="Allegrocl_nn39"></a>16.4.1.3 CTYPE Typemap</H4>
<H4><a name="Allegrocl_nn39"></a>17.4.1.3 CTYPE Typemap</H4>
<p>
@ -1777,14 +1777,14 @@ return-val wrapper-name(parm0, parm1, ..., parmN)
</div>
<p>
These three typemaps are specifically employed by the the
These three typemaps are specifically employed by the
Allegro CL interface generator. SWIG also implements a number of
other typemaps that can be used for generating code in the C/C++
wrappers. You can read about
these <a href="Typemaps.html#Typemaps_nn25">common typemaps</a> here.
</p>
<H3><a name="Allegrocl_nn40"></a>16.4.2 Code generation in Lisp wrappers</H3>
<H3><a name="Allegrocl_nn40"></a>17.4.2 Code generation in Lisp wrappers</H3>
<p>
@ -1803,7 +1803,7 @@ return-val wrapper-name(parm0, parm1, ..., parmN)
<a href="#Allegrocl_nn15">16.3.1 Namespaces</a> for details.
</p>
<H4><a name="Allegrocl_nn41"></a>16.4.2.1 LIN Typemap</H4>
<H4><a name="Allegrocl_nn41"></a>17.4.2.1 LIN Typemap</H4>
<p>
@ -1846,7 +1846,7 @@ return-val wrapper-name(parm0, parm1, ..., parmN)
</pre>
</div>
<H4><a name="Allegrocl_nn42"></a>16.4.2.2 LOUT Typemap</H4>
<H4><a name="Allegrocl_nn42"></a>17.4.2.2 LOUT Typemap</H4>
<p>
@ -1889,7 +1889,7 @@ return-val wrapper-name(parm0, parm1, ..., parmN)
</pre>
</div>
<H4><a name="Allegrocl_nn43"></a>16.4.2.3 FFITYPE Typemap</H4>
<H4><a name="Allegrocl_nn43"></a>17.4.2.3 FFITYPE Typemap</H4>
@ -1939,7 +1939,7 @@ return-val wrapper-name(parm0, parm1, ..., parmN)
</pre>
</div>
<H4><a name="Allegrocl_nn44"></a>16.4.2.4 LISPTYPE Typemap</H4>
<H4><a name="Allegrocl_nn44"></a>17.4.2.4 LISPTYPE Typemap</H4>
<p>
@ -1959,7 +1959,7 @@ return-val wrapper-name(parm0, parm1, ..., parmN)
</pre>
</div>
<H4><a name="Allegrocl_nn45"></a>16.4.2.5 LISPCLASS Typemap</H4>
<H4><a name="Allegrocl_nn45"></a>17.4.2.5 LISPCLASS Typemap</H4>
<p>
@ -1983,7 +1983,7 @@ return-val wrapper-name(parm0, parm1, ..., parmN)
</pre>
</div>
<H3><a name="Allegrocl_nn46"></a>16.4.3 Modifying SWIG behavior using typemaps</H3>
<H3><a name="Allegrocl_nn46"></a>17.4.3 Modifying SWIG behavior using typemaps</H3>
<p>
@ -2017,10 +2017,10 @@ return-val wrapper-name(parm0, parm1, ..., parmN)
</pre>
</div>
<H2><a name="Allegrocl_nn47"></a>16.5 Identifier Converter functions</H2>
<H2><a name="Allegrocl_nn47"></a>17.5 Identifier Converter functions</H2>
<H3><a name="Allegrocl_nn48"></a>16.5.1 Creating symbols in the lisp environment</H3>
<H3><a name="Allegrocl_nn48"></a>17.5.1 Creating symbols in the lisp environment</H3>
<p>
@ -2041,11 +2041,11 @@ return-val wrapper-name(parm0, parm1, ..., parmN)
of arguments.
</p>
<H3><a name="Allegrocl_nn49"></a>16.5.2 Existing identifier-converter functions</H3>
<H3><a name="Allegrocl_nn49"></a>17.5.2 Existing identifier-converter functions</H3>
<p>Two basic identifier routines have been defined.
<H4><a name="Allegrocl_nn50"></a>16.5.2.1 identifier-convert-null</H4>
<H4><a name="Allegrocl_nn50"></a>17.5.2.1 identifier-convert-null</H4>
<p>
@ -2054,7 +2054,7 @@ return-val wrapper-name(parm0, parm1, ..., parmN)
strings, from which a symbol will be created.
</p>
<H4><a name="Allegrocl_nn51"></a>16.5.2.2 identifier-convert-lispify</H4>
<H4><a name="Allegrocl_nn51"></a>17.5.2.2 identifier-convert-lispify</H4>
<p>
@ -2063,7 +2063,7 @@ return-val wrapper-name(parm0, parm1, ..., parmN)
same symbol transformations.
</p>
<H4><a name="Allegrocl_nn52"></a>16.5.2.3 Default identifier to symbol conversions</H4>
<H4><a name="Allegrocl_nn52"></a>17.5.2.3 Default identifier to symbol conversions</H4>
<p>
@ -2072,7 +2072,7 @@ return-val wrapper-name(parm0, parm1, ..., parmN)
default naming conventions.
</p>
<H3><a name="Allegrocl_nn53"></a>16.5.3 Defining your own identifier-converter</H3>
<H3><a name="Allegrocl_nn53"></a>17.5.3 Defining your own identifier-converter</H3>
<p>
@ -2128,7 +2128,7 @@ indicating the number of arguments passed to the routine indicated by
this identifier.
</p>
<H3><a name="Allegrocl_nn54"></a>16.5.4 Instructing SWIG to use a particular identifier-converter</H3>
<H3><a name="Allegrocl_nn54"></a>17.5.4 Instructing SWIG to use a particular identifier-converter</H3>
<p>

749
Doc/Manual/Android.html Normal file
View file

@ -0,0 +1,749 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>SWIG and Android</title>
<link rel="stylesheet" type="text/css" href="style.css">
</head>
<body bgcolor="#FFFFFF">
<H1><a name="Android"></a>18 SWIG and Android</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="#Android_overview">Overview</a>
<li><a href="#Android_examples">Android examples</a>
<ul>
<li><a href="#Android_examples_intro">Examples introduction</a>
<li><a href="#Android_example_simple">Simple C example</a>
<li><a href="#Android_example_class">C++ class example</a>
</ul>
</ul>
</div>
<!-- INDEX -->
<p>
This chapter describes SWIG's support of Android.
</p>
<H2><a name="Android_overview"></a>18.1 Overview</H2>
<p>
The Android chapter is fairly short as support for Android is the same as for Java, where the Java Native Interface (JNI) is
used to call from Android Java into C or C++ compiled code.
Everything in the <a href="Java.html">Java chapter</a> applies to generating code for access from Android Java code.
This chapter contains a few Android specific notes and examples.
</p>
<H2><a name="Android_examples"></a>18.2 Android examples</H2>
<H3><a name="Android_examples_intro"></a>18.2.1 Examples introduction</H3>
<p>
The examples require the the <a href="http://developer.android.com/sdk/index.html">Android SDK</a> and <a href="http://developer.android.com/sdk/ndk/index.html">Android NDK</a> which can be installed as per instructions in the links.
The Eclipse version is not required for these examples as just the command line tools are used (shown for Linux as the host, but Windows will be very similar, if not identical in most places).
Add the SDK tools and NDK tools to your path and create a directory somewhere for your Android projects (adjust PATH as necessary to where you installed the tools):
</p>
<div class="shell">
<pre>
$ export PATH=$HOME/android/android-sdk-linux_x86/tools:$HOME/android/android-sdk-linux_x86/platform-tools:$HOME/android/android-ndk-r6b:$PATH
$ mkdir AndroidApps
$ cd AnrdoidApps
</pre>
</div>
<p>
The examples use a target id of 1. This might need changing depending on your setup.
After installation of the Android SDK, the available target ids can be viewed by running the command below.
Please adjust the id to suit your target device.
</p>
<div class="shell">
<pre>
$ android list targets
</pre>
</div>
<p>
The following examples are shipped with SWIG under the Examples/android directory and include a Makefile to build and install each example.
</p>
<H3><a name="Android_example_simple"></a>18.2.2 Simple C example</H3>
<p>
This simple C example shows how to call a C function as well as read and modify a global variable.
First we'll create and build a pure Java Android app. Afterwards the JNI code will be generated by SWIG and built into the app.
First create and build an app called <tt>SwigSimple</tt> in a subdirectory called <tt>simple</tt> using the commands below.
Adjust the <tt>--target</tt> id as mentioned earlier in the <a href="Android.html#Android_examples_intro">Examples introduction</a>.
<a href="http://developer.android.com/guide/developing/projects/projects-cmdline.html">Managing Projects from the Command Line</a> on the Android developer's site is a useful reference for these steps.
</p>
<div class="shell">
<pre>
$ android create project --target 1 --name SwigSimple --path ./simple --activity SwigSimple --package org.swig.simple
$ cd simple
$ ant debug
</pre>
</div>
<p>
Modify <tt>src/org/swig/simple/SwigSimple.java</tt> from the default to:
</p>
<div class="code">
<pre>
package org.swig.simple;
import android.app.Activity;
import android.os.Bundle;
import android.view.View;
import android.widget.Button;
import android.widget.TextView;
import android.widget.ScrollView;
import android.text.method.ScrollingMovementMethod;
public class SwigSimple extends Activity
{
TextView outputText = null;
ScrollView scroller = null;
/** Called when the activity is first created. */
@Override
public void onCreate(Bundle savedInstanceState)
{
super.onCreate(savedInstanceState);
setContentView(R.layout.main);
outputText = (TextView)findViewById(R.id.OutputText);
outputText.setText("Press 'Run' to start...\n");
outputText.setMovementMethod(new ScrollingMovementMethod());
scroller = (ScrollView)findViewById(R.id.Scroller);
}
public void onRunButtonClick(View view)
{
outputText.append("Started...\n");
nativeCall();
outputText.append("Finished!\n");
// Ensure scroll to end of text
scroller.post(new Runnable() {
public void run() {
scroller.fullScroll(ScrollView.FOCUS_DOWN);
}
});
}
/** Calls into C/C++ code */
public void nativeCall()
{
// TODO
}
}
</pre>
</div>
<p>
The above simply adds a <i>Run</i> button and scrollable text view as the GUI aspects of the program.
The associated resources need to be created, modify <tt>res/layout/main.xml</tt> as follows:
</p>
<div class="code">
<pre>
&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
android:orientation="vertical"
android:layout_width="fill_parent"
android:layout_height="fill_parent"
&gt;
&lt;Button
android:id="@+id/RunButton"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:text="Run..."
android:onClick="onRunButtonClick"
/&gt;
&lt;ScrollView
android:id="@+id/Scroller"
android:layout_width="fill_parent"
android:layout_height="fill_parent"
&gt;
&lt;TextView
android:id="@+id/OutputText"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
/&gt;
&lt;/ScrollView&gt;
&lt;/LinearLayout&gt;
</pre>
</div>
<p>
Rebuild the project with your changes:
</p>
<div class="shell">
<pre>
$ ant debug
</pre>
</div>
<p>
Although there are no native function calls in the code, yet, you may want to check that this simple pure
Java app runs before adding in the native calls.
First, set up your Android device for hardware debugging, see <a href="http://developer.android.com/guide/developing/device.html">Using hardware devices</a> on the Android developer's site.
When complete your device should be listed in those attached, something like:
</p>
<div class="shell">
<pre>
$ adb devices
List of devices attached
A32-6DBE0001-9FF80000-015D62C3-02018028 device
</pre>
</div>
<p>
This means you are now ready to install the application...
</p>
<div class="shell">
<pre>
$ adb install bin/SwigSimple-debug.apk
95 KB/s (4834 bytes in 0.049s)
pkg: /data/local/tmp/SwigSimple-debug.apk
Success
</pre>
</div>
<p>
The newly installed 'SwigSimple' app will be amongst all your other applications on the home screen. Run the app and it will show a <i>Run</i> button text box below it.
Press the <i>Run</i> button to see the simple text output.
</p>
<p>
The application can be uninstalled like any other application and in fact must be uninstalled before installing an updated version. Uninstalling is quite easy too from your host computer:
</p>
<div class="shell">
<pre>
$ adb uninstall org.swig.simple
Success
</pre>
</div>
<p>
Now that you have a pure Java Android app working, let's add some JNI code generated from SWIG.
</p>
<p>
First create a <tt>jni</tt> subdirectory and then create some C source code in <tt>jni/example.c</tt>:
</p>
<div class="code">
<pre>
/* File : example.c */
/* A global variable */
double Foo = 3.0;
/* Compute the greatest common divisor of positive integers */
int gcd(int x, int y) {
int g;
g = y;
while (x &gt; 0) {
g = x;
x = y % x;
y = g;
}
return g;
}
</pre>
</div>
<p>
Create a SWIG interface file for this C code, <tt>jni/example.i</tt>:
</p>
<div class="code">
<pre>
/* File : example.i */
%module example
%inline %{
extern int gcd(int x, int y);
extern double Foo;
%}
</pre>
</div>
<p>
Invoke SWIG as follows:
</p>
<div class="shell">
<pre>
$ swig -java -package org.swig.simple -outdir src/org/swig/simple -o jni/example_wrap.c jni/example.i
</pre>
</div>
<p>
SWIG generates the following files:
</p>
<ul>
<li><tt>src/org/swig/simple/exampleJNI.java</tt></li>
<li><tt>src/org/swig/simple/example.java</tt></li>
<li><tt>jni/example_wrap.c</tt></li>
</ul>
<p>
Next we need to create a standard Android NDK build system file <tt>jni/Android.mk</tt>:
</p>
<div class="code">
<pre>
# File: Android.mk
LOCAL_PATH := $(call my-dir)
include $(CLEAR_VARS)
LOCAL_MODULE := example
LOCAL_SRC_FILES := example_wrap.c example.c
include $(BUILD_SHARED_LIBRARY)
</pre>
</div>
<p>
See the <a href="http://developer.android.com/sdk/ndk/index.html">Android NDK documentation</a> for more on the NDK build system and getting started with the NDK.
A simple invocation of ndk-build will compile the .c files and generate a shared object/system library. Output will be similar to:
</p>
<div class="shell">
<pre>
$ ndk-build
Compile thumb : example &lt;= example_wrap.c
Compile thumb : example &lt;= example.c
SharedLibrary : libexample.so
Install : libexample.so =&gt; libs/armeabi/libexample.so
</pre>
</div>
<p>
Now that the C JNI layer has been built, we can write Java code to call into the this layer.
Modify the <tt>nativeCall</tt> method in <tt>src/org/swig/simple/SwigSimple.java</tt> to call the JNI code as follows and add the static constructor to load the system library containing the compiled JNI C code:
</p>
<div class="code">
<pre>
/** Calls into C/C++ code */
public void nativeCall()
{
// Call our gcd() function
int x = 42;
int y = 105;
int g = example.gcd(x,y);
outputText.append("The greatest common divisor of " + x + " and " + y + " is " + g + "\n");
// Manipulate the Foo global variable
// Output its current value
double foo = example.getFoo();
outputText.append("Foo = " + foo + "\n");
// Change its value
example.setFoo(3.1415926);
// See if the change took effect
outputText.append("Foo = " + example.getFoo() + "\n");
// Restore value
example.setFoo(foo);
}
/** static constructor */
static {
System.loadLibrary("example");
}
</pre>
</div>
<p>
Compile the Java code as usual, uninstall the old version of the app if still installed and re-install the new app:
</p>
<div class="shell">
<pre>
$ ant debug
$ adb uninstall org.swig.simple
$ adb install bin/SwigSimple-debug.apk
</pre>
</div>
<p>
Run the app again and this time you will see the output pictured below, showing the result of calls into the C code:
</p>
<center><img src="android-simple.png" alt="Android screenshot of SwigSimple example"></center>
<H3><a name="Android_example_class"></a>18.2.3 C++ class example</H3>
<p>
The steps for calling C++ code are almost identical to those in the previous C code example.
All the steps required to compile and use a simple hierarchy of classes for shapes are shown in this example.
</p>
<p>
First create an Android project called <tt>SwigClass</tt> in a subdirectory called <tt>class</tt>.
The steps below create and build a the JNI C++ app.
Adjust the <tt>--target</tt> id as mentioned earlier in the <a href="Android.html#Android_examples_intro">Examples introduction</a>.
</p>
<div class="shell">
<pre>
$ android create project --target 1 --name SwigClass --path ./class --activity SwigClass --package org.swig.classexample
$ cd class
</pre>
</div>
<p>
Now create a <tt>jni</tt> subdirectory and then create a C++ header file <tt>jni/example.h</tt> which defines our
hierarchy of shape classes:
</p>
<div class="code">
<pre>
/* File : example.h */
class Shape {
public:
Shape() {
nshapes++;
}
virtual ~Shape() {
nshapes--;
};
double x, y;
void move(double dx, double dy);
virtual double area(void) = 0;
virtual double perimeter(void) = 0;
static int nshapes;
};
class Circle : public Shape {
private:
double radius;
public:
Circle(double r) : radius(r) { };
virtual double area(void);
virtual double perimeter(void);
};
class Square : public Shape {
private:
double width;
public:
Square(double w) : width(w) { };
virtual double area(void);
virtual double perimeter(void);
};
</pre>
</div>
<p>
and create the implementation in the <tt>jni/example.cpp</tt> file:
</p>
<div class="code">
<pre>
/* File : example.cpp */
#include "example.h"
#define M_PI 3.14159265358979323846
/* Move the shape to a new location */
void Shape::move(double dx, double dy) {
x += dx;
y += dy;
}
int Shape::nshapes = 0;
double Circle::area(void) {
return M_PI*radius*radius;
}
double Circle::perimeter(void) {
return 2*M_PI*radius;
}
double Square::area(void) {
return width*width;
}
double Square::perimeter(void) {
return 4*width;
}
</pre>
</div>
<p>
Create a SWIG interface file for this C++ code in <tt>jni/example.i</tt>:
</p>
<div class="code">
<pre>
/* File : example.i */
%module example
%{
#include "example.h"
%}
/* Let's just grab the original header file here */
%include "example.h"
</pre>
</div>
<p>
Invoke SWIG as follows, note that the -c++ option is required for C++ code:
</p>
<div class="shell">
<pre>
$ swig -c++ -java -package org.swig.classexample -outdir src/org/swig/classexample -o jni/example_wrap.cpp jni/example.i
</pre>
</div>
<p>
SWIG generates the following files:
</p>
<ul>
<li><tt>src/org/swig/classexample/Square.java</tt></li>
<li><tt>src/org/swig/classexample/exampleJNI.java</tt></li>
<li><tt>src/org/swig/classexample/example.java</tt></li>
<li><tt>src/org/swig/classexample/Circle.java</tt></li>
<li><tt>src/org/swig/classexample/Shape.java</tt></li>
<li><tt>jni/example_wrap.cpp</tt></li>
</ul>
<p>
Next we need to create an Android NDK build system file for compiling the C++ code <tt>jni/Android.mk</tt>.
The <tt>-frtti</tt> compiler flag isn't strictly needed for this example, but is needed for any code that uses C++ RTTI:
</p>
<div class="code">
<pre>
# File: Android.mk
LOCAL_PATH := $(call my-dir)
include $(CLEAR_VARS)
LOCAL_MODULE := example
LOCAL_SRC_FILES := example_wrap.cpp example.cpp
LOCAL_CFLAGS := -frtti
include $(BUILD_SHARED_LIBRARY)
</pre>
</div>
<p>
A simple invocation of ndk-build will compile the .cpp files and generate a shared object/system library. Output will be similar to:
</p>
<div class="shell">
<pre>
$ ndk-build
Compile++ thumb : example &lt;= example_wrap.cpp
Compile++ thumb : example &lt;= example.cpp
StaticLibrary : libstdc++.a
SharedLibrary : libexample.so
Install : libexample.so =&gt; libs/armeabi/libexample.so
</pre>
</div>
<p>
Now that the C JNI layer has been built, we can write Java code to call into this layer.
Modify <tt>src/org/swig/classexample/SwigClass.java</tt> from the default to:
</p>
<div class="code">
<pre>
package org.swig.classexample;
import android.app.Activity;
import android.os.Bundle;
import android.view.View;
import android.widget.Button;
import android.widget.TextView;
import android.widget.ScrollView;
import android.text.method.ScrollingMovementMethod;
public class SwigClass extends Activity
{
TextView outputText = null;
ScrollView scroller = null;
/** Called when the activity is first created. */
@Override
public void onCreate(Bundle savedInstanceState)
{
super.onCreate(savedInstanceState);
setContentView(R.layout.main);
outputText = (TextView)findViewById(R.id.OutputText);
outputText.setText("Press 'Run' to start...\n");
outputText.setMovementMethod(new ScrollingMovementMethod());
scroller = (ScrollView)findViewById(R.id.Scroller);
}
public void onRunButtonClick(View view)
{
outputText.append("Started...\n");
nativeCall();
outputText.append("Finished!\n");
// Ensure scroll to end of text
scroller.post(new Runnable() {
public void run() {
scroller.fullScroll(ScrollView.FOCUS_DOWN);
}
});
}
/** Calls into C/C++ code */
public void nativeCall()
{
// ----- Object creation -----
outputText.append( "Creating some objects:\n" );
Circle c = new Circle(10);
outputText.append( " Created circle " + c + "\n");
Square s = new Square(10);
outputText.append( " Created square " + s + "\n");
// ----- Access a static member -----
outputText.append( "\nA total of " + Shape.getNshapes() + " shapes were created\n" );
// ----- Member data access -----
// Notice how we can do this using functions specific to
// the 'Circle' class.
c.setX(20);
c.setY(30);
// Now use the same functions in the base class
Shape shape = s;
shape.setX(-10);
shape.setY(5);
outputText.append( "\nHere is their current position:\n" );
outputText.append( " Circle = (" + c.getX() + " " + c.getY() + ")\n" );
outputText.append( " Square = (" + s.getX() + " " + s.getY() + ")\n" );
// ----- Call some methods -----
outputText.append( "\nHere are some properties of the shapes:\n" );
Shape[] shapes = {c,s};
for (int i=0; i&lt;shapes.length; i++)
{
outputText.append( " " + shapes[i].toString() + "\n" );
outputText.append( " area = " + shapes[i].area() + "\n" );
outputText.append( " perimeter = " + shapes[i].perimeter() + "\n" );
}
// Notice how the area() and perimeter() functions really
// invoke the appropriate virtual method on each object.
// ----- Delete everything -----
outputText.append( "\nGuess I'll clean up now\n" );
// Note: this invokes the virtual destructor
// You could leave this to the garbage collector
c.delete();
s.delete();
outputText.append( Shape.getNshapes() + " shapes remain\n" );
outputText.append( "Goodbye\n" );
}
/** static constructor */
static {
System.loadLibrary("example");
}
}
</pre>
</div>
<p>
Note the static constructor and the interesting JNI code is in the <tt>nativeCall</tt> method.
The remaining code deals with the GUI aspects which are identical to the previous C simple example. Modify <tt>res/layout/main.xml</tt> to contain the xml for the 'Run' button and scrollable text view:
</p>
<div class="code">
<pre>
&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
android:orientation="vertical"
android:layout_width="fill_parent"
android:layout_height="fill_parent"
&gt;
&lt;Button
android:id="@+id/RunButton"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:text="Run..."
android:onClick="onRunButtonClick"
/&gt;
&lt;ScrollView
android:id="@+id/Scroller"
android:layout_width="fill_parent"
android:layout_height="fill_parent"
&gt;
&lt;TextView
android:id="@+id/OutputText"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
/&gt;
&lt;/ScrollView&gt;
&lt;/LinearLayout&gt;
</pre>
</div>
<p>
Compile the Java code as usual, uninstall the old version of the app if installed and re-install the new app:
</p>
<div class="shell">
<pre>
$ ant debug
$ adb uninstall org.swig.classexample
$ adb install bin/SwigClass-debug.apk
</pre>
</div>
<p>
Run the app to see the result of calling the C++ code from Java:
</p>
<center><img src="android-class.png" alt="Android screenshot of SwigClass example"></center>
</body>
</html>

6
Doc/Manual/Arguments.html
View file

@ -30,8 +30,6 @@
<b>Disclaimer: This chapter is under construction.</b>
<p>
In Chapter 3, SWIG's treatment of basic datatypes and pointers was
described. In particular, primitive types such as <tt>int</tt> and
@ -83,7 +81,7 @@ One way to deal with this is to use the
%include "typemaps.i"
%apply double *OUTPUT { double *result };
%inlne %{
%inline %{
extern void add(double a, double b, double *result);
%}
</pre></div>
@ -351,7 +349,7 @@ function like this in an interface file :</p>
<div class="code"><pre>
%module example
%include typemaps.i
%include "typemaps.i"
...
%{
extern void negate(double *);

596
Doc/Manual/CSharp.html
View file

@ -5,33 +5,42 @@
<link rel="stylesheet" type="text/css" href="style.css">
</head>
<body bgcolor="#FFFFFF">
<H1><a name="CSharp"></a>17 SWIG and C#</H1>
<H1><a name="CSharp"></a>19 SWIG and C#</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="#csharp_introduction">Introduction</a>
<li><a href="#csharp_differences_java">Differences to the Java module</a>
<li><a href="#csharp_exceptions">C# Exceptions</a>
<li><a href="#CSharp_introduction">Introduction</a>
<li><a href="#CSharp_differences_java">Differences to the Java module</a>
<li><a href="#CSharp_void_pointers">Void pointers</a>
<li><a href="#CSharp_arrays">C# Arrays</a>
<ul>
<li><a href="#csharp_exception_example_check_typemap">C# exception example using "check" typemap</a>
<li><a href="#csharp_exception_example_percent_exception">C# exception example using %exception</a>
<li><a href="#csharp_exception_example_exception_specifications">C# exception example using exception specifications</a>
<li><a href="#csharp_custom_application_exception">Custom C# ApplicationException example</a>
<li><a href="#CSharp_arrays_swig_library">The SWIG C arrays library</a>
<li><a href="#CSharp_arrays_pinvoke_default_array_marshalling">Managed arrays using P/Invoke default array marshalling</a>
<li><a href="#CSharp_arrays_pinning">Managed arrays using pinning</a>
</ul>
<li><a href="#csharp_directors">C# Directors</a>
<li><a href="#CSharp_exceptions">C# Exceptions</a>
<ul>
<li><a href="#csharp_directors_example">Directors example</a>
<li><a href="#csharp_directors_implementation">Directors implementation</a>
<li><a href="#csharp_director_caveats">Director caveats</a>
<li><a href="#CSharp_exception_example_check_typemap">C# exception example using "check" typemap</a>
<li><a href="#CSharp_exception_example_percent_exception">C# exception example using %exception</a>
<li><a href="#CSharp_exception_example_exception_specifications">C# exception example using exception specifications</a>
<li><a href="#CSharp_custom_application_exception">Custom C# ApplicationException example</a>
</ul>
<li><a href="#csharp_typemap_examples">C# Typemap examples</a>
<li><a href="#CSharp_directors">C# Directors</a>
<ul>
<li><a href="#csharp_memory_management_member_variables">Memory management when returning references to member variables</a>
<li><a href="#csharp_memory_management_objects">Memory management for objects passed to the C++ layer</a>
<li><a href="#csharp_date_marshalling">Date marshalling using the csin typemap and associated attributes</a>
<li><a href="#csharp_date_properties">A date example demonstrating marshalling of C# properties</a>
<li><a href="#csharp_partial_classes">Turning wrapped classes into partial classes</a>
<li><a href="#csharp_extending_proxy_class">Extending proxy classes with additional C# code</a>
<li><a href="#CSharp_directors_example">Directors example</a>
<li><a href="#CSharp_directors_implementation">Directors implementation</a>
<li><a href="#CSharp_director_caveats">Director caveats</a>
</ul>
<li><a href="#CSharp_multiple_modules">Multiples modules</a>
<li><a href="#CSharp_typemap_examples">C# Typemap examples</a>
<ul>
<li><a href="#CSharp_memory_management_member_variables">Memory management when returning references to member variables</a>
<li><a href="#CSharp_memory_management_objects">Memory management for objects passed to the C++ layer</a>
<li><a href="#CSharp_date_marshalling">Date marshalling using the csin typemap and associated attributes</a>
<li><a href="#CSharp_date_properties">A date example demonstrating marshalling of C# properties</a>
<li><a href="#CSharp_partial_classes">Turning wrapped classes into partial classes</a>
<li><a href="#CSharp_extending_proxy_class">Extending proxy classes with additional C# code</a>
<li><a href="#CSharp_enum_underlying_type">Underlying type for enums</a>
</ul>
</ul>
</div>
@ -39,7 +48,7 @@
<H2><a name="csharp_introduction"></a>17.1 Introduction</H2>
<H2><a name="CSharp_introduction"></a>19.1 Introduction</H2>
<p>
@ -48,9 +57,9 @@ The wrapper code implementation uses C# and the Platform Invoke (PInvoke) interf
The PInvoke interface has been chosen over Microsoft's Managed C++ interface as it is portable to both Microsoft Windows and non-Microsoft platforms.
PInvoke is part of the ECMA/ISO C# specification.
It is also better suited for robust production environments due to the Managed C++ flaw called the
<a href="http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dv_vstechart/html/vcconMixedDLLLoadingProblem.asp">Mixed DLL Loading Problem</a>.
Swig C# works equally well on non-Microsoft operating systems such as Linux, Solaris and Apple Mac using
<a href="http://www.mono-project.com/">Mono</a> and <a href="http://www.dotgnu.org/pnet.html">Portable.NET</a>.
<a href="http://msdn.microsoft.com/en-us/library/aa290048(VS.71).aspx">Mixed DLL Loading Problem</a>.
SWIG C# works equally well on non-Microsoft operating systems such as Linux, Solaris and Apple Mac using
<a href="http://www.mono-project.com/Main_Page">Mono</a> and <a href="http://www.dotgnu.org/pnet.html">Portable.NET</a>.
</p>
<p>
@ -59,7 +68,7 @@ The <a href="http://msdn.microsoft.com">Microsoft Developer Network (MSDN)</a> h
Monodoc, available from the Mono project, has a very useful section titled <a href="http://www.mono-project.com/Interop_with_Native_Libraries">Interop with native libraries</a>.
</p>
<H2><a name="csharp_differences_java"></a>17.2 Differences to the Java module</H2>
<H2><a name="CSharp_differences_java"></a>19.2 Differences to the Java module</H2>
<p>
@ -93,6 +102,12 @@ namespace com.bloggs.widget {
...
}
</pre></div>
Note that by default, the generated C# classes have no namespace and the module name is unrelated to namespaces. The module name is just like in Java and is merely used to name some of the generated classes.
</li>
<li>
The <a href="SWIGPlus.html#SWIGPlus_nspace">nspace feature</a> is also supported as described in this general section with a C# example.
Unlike Java which requires the use of the -package option when using the <tt>nspace</tt> feature, the -namespace option is not mandatory for C#.
</li>
<li>
@ -125,7 +140,7 @@ If it was used, it would generate an illegal runtime initialisation via a PInvok
C# doesn't support the notion of throws clauses.
Therefore there is no 'throws' typemap attribute support for adding exception classes to a throws clause.
Likewise there is no need for an equivalent to <tt>%javaexception</tt>.
In fact, throwing C# exceptions works quite differently, see <a href="CSharp.html#csharp_exceptions">C# Exceptions></a> below.
In fact, throwing C# exceptions works quite differently, see <a href="CSharp.html#CSharp_exceptions">C# Exceptions</a> below.
</li>
<li>
@ -156,6 +171,14 @@ javadestruct_derived -&gt; csdestruct_derived
</li>
<li>
<p>Typemap macros:</p>
<div class="code"><pre>
SWIG_JAVABODY_PROXY -&gt; SWIG_CSBODY_PROXY
SWIG_JAVABODY_TYPEWRAPPER -&gt; SWIG_CSBODY_TYPEWRAPPER
</pre></div>
</li>
<li>
<p>Additional typemaps:</p>
@ -194,6 +217,7 @@ jniclassinterfaces -&gt; imclassinterfaces
$javaclassname -&gt; $csclassname
$&amp;javaclassname -&gt; $&amp;csclassname
$*javaclassname -&gt; $*csclassname
$javaclazzname -&gt; $csclazzname
$javainput -&gt; $csinput
$jnicall -&gt; $imcall
</pre></div>
@ -201,7 +225,12 @@ $jnicall -&gt; $imcall
<li>
<p>
Unlike the "javain" typemap, the "csin" typemap does not support the 'pgcpp' attribute as the C# module does not have a premature garbage collection prevention parameter. The "csin" typemap supports an additional optional attribute called 'cshin'. It should contain the parameter type and name whenever a <a href="Java.html#java_constructor_helper_function">constructor helper function</a> is generated due to the 'pre' or 'post' attributes. Note that 'pre', 'post' and 'cshin' attributes are not used for marshalling the property set. Please see the <a href="#csharp_date_marshalling">Date marshalling example</a> and <a href="#CSharp.html#csharp_date_properties">Date marshalling of properties example</a> for further understanding.
Unlike the "javain" typemap, the "csin" typemap does not support the 'pgcpp' attribute as the C# module does not have a premature garbage collection prevention parameter.
The "csin" typemap supports additional optional attributes called 'cshin' and 'terminator'.
The 'cshin' attribute should contain the parameter type and name whenever a <a href="Java.html#Java_constructor_helper_function">constructor helper function</a> is generated due to the 'pre' or 'post' attributes.
The 'terminator' attribute normally just contains a closing brace for when the 'pre' attribute contains an opening brace, such as when a C# <tt>using</tt> or <tt>fixed</tt> block is started.
Note that 'pre', 'post', 'terminator' and 'cshin' attributes are not used for marshalling the property set.
Please see the <a href="#CSharp_date_marshalling">Date marshalling example</a> and <a href="#CSharp_date_properties">Date marshalling of properties example</a> for further understanding of these "csin" applicable attributes.
</p>
</li>
@ -237,7 +266,9 @@ public static extern IntPtr function(string jarg1);
<p>
Support for type attributes.
The 'imtype' and 'cstype' typemaps can have an optional <tt>inattributes</tt> and <tt>outattributes</tt> typemap attribute.
There are C# attributes and typemap attributes, don't get confused!!
The 'imtype' typemap can also have an optional <tt>directorinattributes</tt> and <tt>directoroutattributes</tt>
typemap attribute which attaches to director delegates, an implementation detail of directors, see <a href="#CSharp_directors_implementation">directors implementation</a>.
Note that there are C# attributes and typemap attributes, don't get confused between the two!!
The C# attributes specified in these typemap attributes are generated wherever the type is used in the C# wrappers.
These can be used to specify any C# attribute associated with a C/C++ type, but are more typically used for the C# <tt>MarshalAs</tt> attribute.
For example:
@ -281,12 +312,17 @@ These attributes are associated with the C/C++ parameter type or return type, wh
the attribute features and typemaps covered next.
Note that all these different C# attributes can be combined so that a method has more than one attribute.
</p>
<p>
The <tt>directorinattributes</tt> and <tt>directoroutattributes</tt> typemap attribute are attached to the delegates in the director class, for example, the SwigDelegateBase_0
</p>
</li>
<li>
<p>
Support for attaching C# attributes to wrapped methods and variables.
This is done using the <tt>%csattributes</tt> feature, see <a href="Customization.html#features">%feature directives</a>.
Support for attaching C# attributes to wrapped methods, variables and enum values.
This is done using the <tt>%csattributes</tt> feature, see <a href="Customization.html#Customization_features">%feature directives</a>.
Note that C# attributes are attached to proxy classes and enums using the <tt>csattributes</tt> typemap.
For example, imagine we have a custom attribute class, <tt>ThreadSafeAttribute</tt>, for labelling thread safety.
The following SWIG code shows how to attach this C# attribute to some methods and the class declaration itself:
@ -332,6 +368,38 @@ they can be added using the 'csvarin' and 'csvarout' typemaps respectively.
Note that the type used for the property is specified in the 'cstype' typemap.
If the 'out' attribute exists in this typemap, then the type used is from the 'out' attribute.
</p>
<p>
An example for attaching attributes to the enum and enum values is shown below.
</p>
<div class="code">
<pre>
%typemap(csattributes) Couleur "[System.ComponentModel.Description(\"Colours\")]"
%csattributes Rouge "[System.ComponentModel.Description(\"Red\")]"
%csattributes Vert "[System.ComponentModel.Description(\"Green\")]"
%inline %{
enum Couleur { Rouge, Orange, Vert };
%}
</pre>
</div>
<p>
which will result in the following C# enum:
</p>
<div class="code">
<pre>
[System.ComponentModel.Description("Colours")]
public enum Couleur {
[System.ComponentModel.Description("Red")]
Rouge,
Orange,
[System.ComponentModel.Description("Green")]
Vert
}
</pre>
</div>
</li>
<li>
@ -350,7 +418,7 @@ This feature is useful for some obscure cases where SWIG might get the <tt>virtu
</li>
<li>
<a name="csharp_module_directive"></a>
<a name="CSharp_module_directive"></a>
<p>
The name of the intermediary class can be changed from its default, that is, the module name with PINVOKE appended after it.
The module directive attribute <tt>imclassname</tt> is used to achieve this:
@ -385,7 +453,7 @@ if specified, otherwise it is equivalent to the <b>$module</b> special variable.
<p>
<b><tt>$imclassname</tt></b><br>
This special variable expands to the intermediary class name. For C# this is usually the same as '$modulePINVOKE' ('$moduleJNI' for Java),
unless the imclassname attribute is specified in the <a href="CSharp.html#csharp_module_directive">%module directive</a>.
unless the imclassname attribute is specified in the <a href="CSharp.html#CSharp_module_directive">%module directive</a>.
</p>
<p>
@ -397,7 +465,296 @@ Windows users can also get the examples working using a
<a href="http://www.cygwin.com">Cygwin</a> or <a href="http://www.mingw.org">MinGW</a> environment for automatic configuration of the example makefiles.
Any one of the three C# compilers (Portable.NET, Mono or Microsoft) can be detected from within a Cygwin or Mingw environment if installed in your path.
<H2><a name="csharp_exceptions"></a>17.3 C# Exceptions</H2>
<H2><a name="CSharp_void_pointers"></a>19.3 Void pointers</H2>
<p>
By default SWIG treats <tt>void *</tt> as any other pointer and hence marshalls it as a type wrapper class called <tt>SWIGTYPE_p_void</tt>.
If you want to marshall with the .NET <tt>System.IntPtr</tt> type instead, there is a simple set of named typemaps called
<tt>void *VOID_INT_PTR</tt> that can be used.
They can be applied like any other named typemaps:
</p>
<div class="code">
<pre>
%apply void *VOID_INT_PTR { void * }
void * f(void *v);
</pre>
</div>
<H2><a name="CSharp_arrays"></a>19.4 C# Arrays</H2>
<p>
There are various ways to pass arrays from C# to C/C++.
The default wrapping treats arrays as pointers and as such simple type wrapper classes are generated,
eg <tt>SWIGTYPE_p_int</tt> when wrapping the C type <tt>int []</tt> or <tt>int *</tt>.
This gives a rather restricted use of the underlying unmanaged code and the most practical way to use arrays is to enhance or customise
with one of the following three approaches; namely the SWIG C arrays library, P/Invoke default array marshalling or
pinned arrays.
</p>
<H3><a name="CSharp_arrays_swig_library"></a>19.4.1 The SWIG C arrays library</H3>
<p>
The C arrays library keeps all the array memory in the unmanaged layer.
The library is available to all language modules and is documented in the <a href="Library.html#Library_carrays">carrays.i library</a> section.
Please refer to this section for details, but for convenience, the C# usage for the two examples outlined there is shown below.
</p>
<p>
For the <tt>%array_functions</tt> example, the equivalent usage would be:
</p>
<div class="code">
<pre>
SWIGTYPE_p_double a = example.new_doubleArray(10); // Create an array
for (int i=0; i&lt;10; i++)
example.doubleArray_setitem(a,i,2*i); // Set a value
example.print_array(a); // Pass to C
example.delete_doubleArray(a); // Destroy array
</pre>
</div>
<p>
and for the <tt>%array_class</tt> example, the equivalent usage would be:
</p>
<div class="code">
<pre>
doubleArray c = new doubleArray(10); // Create double[10]
for (int i=0; i&lt;10; i++)
c.setitem(i, 2*i); // Assign values
example.print_array(c.cast()); // Pass to C
</pre>
</div>
<H3><a name="CSharp_arrays_pinvoke_default_array_marshalling"></a>19.4.2 Managed arrays using P/Invoke default array marshalling</H3>
<p>
In the P/Invoke default marshalling scheme, one needs to designate whether the invoked function will treat a managed
array parameter as input, output, or both. When the function is invoked, the CLR allocates a separate chunk of memory as big as the given managed array,
which is automatically released at the end of the function call. If the array parameter is marked as being input, the content of the managed array is copied
into this buffer when the call is made. Correspondingly, if the array parameter is marked as being output, the contents of the reserved buffer are copied
back into the managed array after the call returns. A pointer to this buffer
is passed to the native function.
</p>
<p>
The reason for allocating a separate buffer is to leave the CLR free to relocate the managed array object
during garbage collection. If the overhead caused by the copying is causing a significant performance penalty, consider pinning the managed array and
passing a direct reference as described in the next section.
</p>
<p>
For more information on the subject, see the
<a href="http://msdn.microsoft.com/en-us/library/z6cfh6e6(VS.80).aspx">Default Marshaling for Arrays</a> article
on MSDN.
</p>
<p>
The P/Invoke default marshalling is supported by the <tt>arrays_csharp.i</tt> library via the INPUT, OUTPUT and INOUT typemaps.
Let's look at some example usage. Consider the following C function:
</p>
<div class="code">
<pre>
void myArrayCopy(int *sourceArray, int *targetArray, int nitems);
</pre>
</div>
<p>
We can now instruct SWIG to use the default marshalling typemaps by
</p>
<div class="code">
<pre>
%include "arrays_csharp.i"
%apply int INPUT[] {int *sourceArray}
%apply int OUTPUT[] {int *targetArray}
</pre>
</div>
<p>
As a result, we get the following method in the module class:
</p>
<div class="code">
<pre>
public static void myArrayCopy(int[] sourceArray, int[] targetArray, int nitems) {
examplePINVOKE.myArrayCopy(sourceArray, targetArray, nitems);
}
</pre>
</div>
<p>
If we look beneath the surface at the corresponding intermediary class code, we see
that SWIG has generated code that uses attributes
(from the System.Runtime.InteropServices namespace) to tell the CLR to use default
marshalling for the arrays:
</p>
<div class="code">
<pre>
[DllImport("example", EntryPoint="CSharp_myArrayCopy")]
public static extern void myArrayCopy([In, MarshalAs(UnmanagedType.LPArray)]int[] jarg1,
[Out, MarshalAs(UnmanagedType.LPArray)]int[] jarg2,
int jarg3);
</pre>
</div>
<p>
As an example of passing an inout array (i.e. the target function will both read from and
write to the array), consider this C function that swaps a given number of elements
in the given arrays:
</p>
<div class="code">
<pre>
void myArraySwap(int *array1, int *array2, int nitems);
</pre>
</div>
<p>
Now, we can instruct SWIG to wrap this by
</p>
<div class="code">
<pre>
%include "arrays_csharp.i"
%apply int INOUT[] {int *array1}
%apply int INOUT[] {int *array2}
</pre>
</div>
<p>
This results in the module class method
</p>
<div class="code">
<pre>
public static void myArraySwap(int[] array1, int[] array2, int nitems) {
examplePINVOKE.myArraySwap(array1, array2, nitems);
}
</pre>
</div>
<p>
and intermediary class method
</p>
<div class="code">
<pre>
[DllImport("example", EntryPoint="CSharp_myArraySwap")]
public static extern void myArraySwap([In, Out, MarshalAs(UnmanagedType.LPArray)]int[] jarg1,
[In, Out, MarshalAs(UnmanagedType.LPArray)]int[] jarg2,
int jarg3);
</pre>
</div>
<H3><a name="CSharp_arrays_pinning"></a>19.4.3 Managed arrays using pinning</H3>
<p>
It is also possible to pin a given array in memory (i.e. fix its location in memory), obtain a
direct pointer to it, and then pass this pointer to the wrapped C/C++ function. This approach
involves no copying, but it makes the work of the garbage collector harder as
the managed array object can not be relocated before the fix on the array is released. You should avoid
fixing arrays in memory in cases where the control may re-enter the managed side via a callback and/or
another thread may produce enough garbage to trigger garbage collection.
</p>
<p>
For more information, see the <a href="http://msdn.microsoft.com/en-us/library/f58wzh21(VS.80).aspx">fixed statement</a> in the C# language reference.
</p>
<p>
Now let's look at an example using pinning, thus avoiding the CLR making copies
of the arrays passed as parameters. The <tt>arrays_csharp.i</tt> library file again provides the required support via the <tt>FIXED</tt> typemaps.
Let's use the same function from the previous section:
</p>
<div class="code">
<pre>
void myArrayCopy(int *sourceArray, int *targetArray, int nitems);
</pre>
</div>
<p>
We now need to declare the module class method unsafe, as we are using pointers:
</p>
<div class="code">
<pre>
%csmethodmodifiers myArrayCopy "public unsafe";
</pre>
</div>
<p>
Apply the appropriate typemaps to the array parameters:
</p>
<div class="code">
<pre>
%include "arrays_csharp.i"
%apply int FIXED[] {int *sourceArray}
%apply int FIXED[] {int *targetArray}
</pre>
</div>
<p>
Notice that there is no need for separate in, out or inout typemaps as is the
case when using P/Invoke default marshalling.
</p>
<p>
As a result, we get the following method in the module class:
</p>
<div class="code">
<pre>
public unsafe static void myArrayCopy(int[] sourceArray, int[] targetArray, int nitems) {
fixed ( int *swig_ptrTo_sourceArray = sourceArray ) {
fixed ( int *swig_ptrTo_targetArray = targetArray ) {
{
examplePINVOKE.myArrayCopy((IntPtr)swig_ptrTo_sourceArray, (IntPtr)swig_ptrTo_targetArray,
nitems);
}
}
}
}
</pre>
</div>
<p>
On the method signature level the only difference to the version using P/Invoke default
marshalling is the "unsafe" quantifier, which is required because we are handling pointers.
</p>
<p>
Also the intermediary class method looks a little different from the default marshalling
example - the method is expecting an IntPtr as the parameter type.
</p>
<div class="code">
<pre>
[DllImport("example", EntryPoint="CSharp_myArrayCopy")]
public static extern void myArrayCopy(IntPtr jarg1, IntPtr jarg2, int jarg3);
</pre>
</div>
<H2><a name="CSharp_exceptions"></a>19.5 C# Exceptions</H2>
<p>
@ -405,7 +762,7 @@ It is possible to throw a C# Exception from C/C++ code.
SWIG already provides the framework for throwing C# exceptions if it is able to detect that a C++ exception could be thrown.
Automatically detecting that a C++ exception could be thrown is only possible when a C++ exception specification is used,
see <a href="SWIGPlus.html#SWIGPlus_exception_specifications">Exception specifications</a>.
The <a href="Customization.html#exception">Exception handling with %exception</a> section details the <tt>%exception</tt> feature.
The <a href="Customization.html#Customization_exception">Exception handling with %exception</a> section details the <tt>%exception</tt> feature.
Customised code for handling exceptions with or without a C++ exception specification is possible and the details follow.
However anyone wishing to do this should be familiar with the contents of the sections referred to above.
</p>
@ -494,7 +851,7 @@ set so should only be used when a C# exception is not created.
</p>
<H3><a name="csharp_exception_example_check_typemap"></a>17.3.1 C# exception example using "check" typemap</H3>
<H3><a name="CSharp_exception_example_check_typemap"></a>19.5.1 C# exception example using "check" typemap</H3>
<p>
@ -668,7 +1025,7 @@ without setting the <tt>canthrow</tt> attribute you will get a warning message s
<div class="code">
<pre>
example.i:21: Warning(845): Unmanaged code contains a call to a SWIG_CSharpSetPendingException
example.i:21: Warning 845: Unmanaged code contains a call to a SWIG_CSharpSetPendingException
method and C# code does not handle pending exceptions via the canthrow attribute.
</pre>
</div>
@ -676,12 +1033,12 @@ method and C# code does not handle pending exceptions via the canthrow attribute
Actually it will issue this warning for any function beginning with <tt>SWIG_CSharpSetPendingException</tt>.
</P>
<H3><a name="csharp_exception_example_percent_exception"></a>17.3.2 C# exception example using %exception</H3>
<H3><a name="CSharp_exception_example_percent_exception"></a>19.5.2 C# exception example using %exception</H3>
<p>
Let's consider a similar, but more common example that throws a C++ exception from within a wrapped function.
We can use <tt>%exception</tt> as mentioned in <a href="Customization.html#exception">Exception handling with %exception</a>.
We can use <tt>%exception</tt> as mentioned in <a href="Customization.html#Customization_exception">Exception handling with %exception</a>.
</p>
<div class="code">
@ -741,7 +1098,7 @@ The managed code generated does check for the pending exception as mentioned ear
</pre>
</div>
<H3><a name="csharp_exception_example_exception_specifications"></a>17.3.3 C# exception example using exception specifications</H3>
<H3><a name="CSharp_exception_example_exception_specifications"></a>19.5.3 C# exception example using exception specifications</H3>
<p>
@ -798,7 +1155,7 @@ SWIGEXPORT void SWIGSTDCALL CSharp_evensonly(int jarg1) {
Multiple catch handlers are generated should there be more than one exception specifications declared.
</p>
<H3><a name="csharp_custom_application_exception"></a>17.3.4 Custom C# ApplicationException example</H3>
<H3><a name="CSharp_custom_application_exception"></a>19.5.4 Custom C# ApplicationException example</H3>
<p>
@ -932,7 +1289,7 @@ try {
</pre>
</div>
<H2><a name="csharp_directors"></a>17.4 C# Directors</H2>
<H2><a name="CSharp_directors"></a>19.6 C# Directors</H2>
<p>
@ -942,10 +1299,10 @@ Essentially, it enables unmanaged C++ code to call back into managed code for vi
<p>
The following sections provide information on the C# director implementation and contain most of the information required to use the C# directors.
However, the <a href="Java.html#java_directors">Java directors</a> section should also be read in order to gain more insight into directors.
However, the <a href="Java.html#Java_directors">Java directors</a> section should also be read in order to gain more insight into directors.
</p>
<H3><a name="csharp_directors_example"></a>17.4.1 Directors example</H3>
<H3><a name="CSharp_directors_example"></a>19.6.1 Directors example</H3>
<p>
@ -1066,7 +1423,7 @@ CSharpDerived - UIntMethod(123)
</pre>
</div>
<H3><a name="csharp_directors_implementation"></a>17.4.2 Directors implementation</H3>
<H3><a name="CSharp_directors_implementation"></a>19.6.2 Directors implementation</H3>
<p>
@ -1252,7 +1609,7 @@ void SwigDirector_Base::BaseBoolMethod(Base const &amp;b, bool flag) {
</pre>
</div>
<H3><a name="csharp_director_caveats"></a>17.4.3 Director caveats</H3>
<H3><a name="CSharp_director_caveats"></a>19.6.3 Director caveats</H3>
<p>
@ -1300,7 +1657,42 @@ However, a call from C# to <tt>CSharpDefaults.DefaultMethod()</tt> will of cours
should pass the call on to <tt>CSharpDefaults.DefaultMethod(int)</tt>using the C++ default value, as shown above.
</p>
<H2><a name="csharp_typemap_examples"></a>17.5 C# Typemap examples</H2>
<H2><a name="CSharp_multiple_modules"></a>19.7 Multiples modules</H2>
<p>
When using <a href="Modules.html">multiple modules</a> it is is possible to compile each SWIG generated wrapper
into a different assembly.
However, by default the generated code may not compile if
generated classes in one assembly use generated classes in another assembly.
The visibility of the
<tt>getCPtr()</tt> and pointer constructor generated from the <tt>csbody</tt> typemaps needs changing.
The default visibility is <tt>internal</tt> but it needs to be <tt>public</tt> for access from a different assembly.
Just changing 'internal' to 'public' in the typemap achieves this.
Two macros are available in <tt>csharp.swg</tt> to make this easier and using them is the preferred approach
over simply copying the typemaps and modifying as this is forward compatible with any changes in
the <tt>csbody</tt> typemap in future versions of SWIG.
The macros are for the proxy and typewrapper classes and can respectively be used to
to make the method and constructor public:
</p>
<div class="code">
<pre>
SWIG_CSBODY_PROXY(public, public, SWIGTYPE)
SWIG_CSBODY_TYPEWRAPPER(public, public, public, SWIGTYPE)
</pre>
</div>
<p>
Alternatively, instead of exposing these as public, consider
using the <tt>[assembly:InternalsVisibleTo("Name")]</tt> attribute available in the .NET framework when you
know which assemblies these can be exposed to.
Another approach would be to make these public, but also to hide them from intellisense by using
the <tt>[System.ComponentModel.EditorBrowsable(System.ComponentModel.EditorBrowsableState.Never)]</tt> attribute
if you don't want users to easily stumble upon these so called 'internal workings' of the wrappers.
</p>
<H2><a name="CSharp_typemap_examples"></a>19.8 C# Typemap examples</H2>
This section includes a few examples of typemaps. For more examples, you
@ -1308,12 +1700,12 @@ might look at the files "<tt>csharp.swg</tt>" and "<tt>typemaps.i</tt>" in
the SWIG library.
<H3><a name="csharp_memory_management_member_variables"></a>17.5.1 Memory management when returning references to member variables</H3>
<H3><a name="CSharp_memory_management_member_variables"></a>19.8.1 Memory management when returning references to member variables</H3>
<p>
This example shows how to prevent premature garbage collection of objects when the underlying C++ class returns a pointer or reference to a member variable.
The example is a direct equivalent to this <a href="Java.html#java_memory_management_objects">Java equivalent</a>.
The example is a direct equivalent to this <a href="Java.html#Java_memory_management_objects">Java equivalent</a>.
</p>
<p>
@ -1432,11 +1824,11 @@ public class Bike : IDisposable {
Note the <tt>addReference</tt> call.
</p>
<H3><a name="csharp_memory_management_objects"></a>17.5.2 Memory management for objects passed to the C++ layer</H3>
<H3><a name="CSharp_memory_management_objects"></a>19.8.2 Memory management for objects passed to the C++ layer</H3>
<p>
The example is a direct equivalent to this <a href="Java.html#java_memory_management_objects">Java equivalent</a>.
The example is a direct equivalent to this <a href="Java.html#Java_memory_management_objects">Java equivalent</a>.
Managing memory can be tricky when using C++ and C# proxy classes.
The previous example shows one such case and this example looks at memory management for a class passed to a C++ method which expects the object to remain in scope
after the function has returned. Consider the following two C++ classes:
@ -1551,14 +1943,14 @@ The 'cscode' typemap simply adds in the specified code into the C# proxy class.
</div>
<H3><a name="csharp_date_marshalling"></a>17.5.3 Date marshalling using the csin typemap and associated attributes</H3>
<H3><a name="CSharp_date_marshalling"></a>19.8.3 Date marshalling using the csin typemap and associated attributes</H3>
<p>
The <a href="Java.html#nan_exception_typemap">NaN Exception example</a> is a simple example of the "javain" typemap and its 'pre' attribute.
The <a href="Java.html#Java_nan_exception_typemap">NaN Exception example</a> is a simple example of the "javain" typemap and its 'pre' attribute.
This example demonstrates how a C++ date class, say <tt>CDate</tt>, can be mapped onto the standard .NET date class,
<tt>System.DateTime</tt> by using the 'pre', 'post' and 'pgcppname' attributes of the "csin" typemap (the C# equivalent to the "javain" typemap).
The example is an equivalent to the <a href="Java.html#java_date_marshalling">Java Date marshalling example</a>.
The example is an equivalent to the <a href="Java.html#Java_date_marshalling">Java Date marshalling example</a>.
The idea is that the <tt>System.DateTime</tt> is used wherever the C++ API uses a <tt>CDate</tt>.
Let's assume the code being wrapped is as follows:
</p>
@ -1567,6 +1959,7 @@ Let's assume the code being wrapped is as follows:
<pre>
class CDate {
public:
CDate();
CDate(int year, int month, int day);
int getYear();
int getMonth();
@ -1649,8 +2042,8 @@ The typemaps to achieve this are shown below.
<pre>
%typemap(cstype) const CDate&amp; "System.DateTime"
%typemap(csin,
pre=" CDate temp$csinput = new CDate($csinput.Year, $csinput.Month, $csinput.Day);")
const CDate &amp;
pre=" CDate temp$csinput = new CDate($csinput.Year, $csinput.Month, $csinput.Day);"
) const CDate &amp;
"$csclassname.getCPtr(temp$csinput)"
%typemap(cstype) CDate&amp; "out System.DateTime"
@ -1658,7 +2051,8 @@ The typemaps to achieve this are shown below.
pre=" CDate temp$csinput = new CDate();",
post=" $csinput = new System.DateTime(temp$csinput.getYear(),"
" temp$csinput.getMonth(), temp$csinput.getDay(), 0, 0, 0);",
cshin="out $csinput") CDate &amp;
cshin="out $csinput"
) CDate &amp;
"$csclassname.getCPtr(temp$csinput)"
</pre>
@ -1763,7 +2157,8 @@ will be possible with the following <tt>CDate *</tt> typemaps
pre=" CDate temp$csinput = new CDate($csinput.Year, $csinput.Month, $csinput.Day);",
post=" $csinput = new System.DateTime(temp$csinput.getYear(),"
" temp$csinput.getMonth(), temp$csinput.getDay(), 0, 0, 0);",
cshin="ref $csinput") CDate *
cshin="ref $csinput"
) CDate *
"$csclassname.getCPtr(temp$csinput)"
</pre>
</div>
@ -1780,7 +2175,8 @@ public class example {
try {
examplePINVOKE.addYears(CDate.getCPtr(temppDate), years);
} finally {
pDate = new System.DateTime(temppDate.getYear(), temppDate.getMonth(), temppDate.getDay(), 0, 0, 0);
pDate = new System.DateTime(temppDate.getYear(), temppDate.getMonth(), temppDate.getDay(),
0, 0, 0);
}
}
...
@ -1788,7 +2184,52 @@ public class example {
</pre>
</div>
<H3><a name="csharp_date_properties"></a>17.5.4 A date example demonstrating marshalling of C# properties</H3>
<p>
The following typemap is the same as the previous but demonstrates how a using block can be used for the temporary variable.
The only change to the previous typemap is the introduction of the 'terminator' attribute to terminate the <tt>using</tt> block.
The <tt>subtractYears</tt> method is nearly identical to the above <tt>addYears</tt> method.
</p>
<div class="code">
<pre>
%typemap(csin,
pre=" using (CDate temp$csinput = new CDate($csinput.Year, $csinput.Month, $csinput.Day)) {",
post=" $csinput = new System.DateTime(temp$csinput.getYear(),"
" temp$csinput.getMonth(), temp$csinput.getDay(), 0, 0, 0);",
terminator=" } // terminate temp$csinput using block",
cshin="ref $csinput"
) CDate *
"$csclassname.getCPtr(temp$csinput)"
void subtractYears(CDate *pDate, int years) {
*pDate = CDate(pDate-&gt;getYear() - years, pDate-&gt;getMonth(), pDate-&gt;getDay());
}
</pre>
</div>
<p>
The resulting generated code shows the termination of the <tt>using</tt> block:
</p>
<div class="code">
<pre>
public class example {
public static void subtractYears(ref System.DateTime pDate, int years) {
using (CDate temppDate = new CDate(pDate.Year, pDate.Month, pDate.Day)) {
try {
examplePINVOKE.subtractYears(CDate.getCPtr(temppDate), years);
} finally {
pDate = new System.DateTime(temppDate.getYear(), temppDate.getMonth(), temppDate.getDay(),
0, 0, 0);
}
} // terminate temppDate using block
}
...
}
</pre>
</div>
<H3><a name="CSharp_date_properties"></a>19.8.4 A date example demonstrating marshalling of C# properties</H3>
<p>
@ -1827,7 +2268,8 @@ The typemap type required is thus <tt>CDate *</tt>. Given that the previous sect
pre=" CDate temp$csinput = new CDate($csinput.Year, $csinput.Month, $csinput.Day);",
post=" $csinput = new System.DateTime(temp$csinput.getYear(),"
" temp$csinput.getMonth(), temp$csinput.getDay(), 0, 0, 0);",
cshin="ref $csinput") CDate *
cshin="ref $csinput"
) CDate *
"$csclassname.getCPtr(temp$csinput)"
%typemap(csvarin, excode=SWIGEXCODE2) CDate * %{
@ -1888,7 +2330,7 @@ Some points to note:
</ul>
<H3><a name="csharp_partial_classes"></a>17.5.5 Turning wrapped classes into partial classes</H3>
<H3><a name="CSharp_partial_classes"></a>19.8.5 Turning wrapped classes into partial classes</H3>
<p>
@ -1988,7 +2430,7 @@ demonstrating that the class contains methods calling both unmanaged code - <tt>
The following example is an alternative approach to adding managed code to the generated proxy class.
</p>
<H3><a name="csharp_extending_proxy_class"></a>17.5.6 Extending proxy classes with additional C# code</H3>
<H3><a name="CSharp_extending_proxy_class"></a>19.8.6 Extending proxy classes with additional C# code</H3>
<p>
@ -2027,6 +2469,38 @@ public class ExtendMe : IDisposable {
</pre>
</div>
<H3><a name="CSharp_enum_underlying_type"></a>19.8.7 Underlying type for enums</H3>
<P>
C# enums use int as the underlying type for each enum item.
If you wish to change the underlying type to something else, then use the <tt>csbase</tt> typemap.
For example when your C++ code uses a value larget than int, this is necessary as the C# compiler will not compile values which are too large to fit into an int.
Here is an example:
</p>
<div class="code">
<pre>
%typemap(csbase) BigNumbers "uint"
%inline %{
enum BigNumbers { big=0x80000000, bigger };
%}
</pre>
</div>
<p>
The generated enum will then use the given underlying type and compile correctly:
</p>
<div class="code">
<pre>
public enum BigNumbers : uint {
big = 0x80000000,
bigger
}
</pre>
</div>
</body>
</html>

61
Doc/Manual/Chicken.html
View file

@ -8,7 +8,7 @@
<body bgcolor="#ffffff">
<H1><a name="Chicken"></a>18 SWIG and Chicken</H1>
<H1><a name="Chicken"></a>20 SWIG and Chicken</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -35,7 +35,7 @@
<li><a href="#Chicken_nn16">Typemaps</a>
<li><a href="#Chicken_nn17">Pointers</a>
<ul>
<li><a href="#collection">Garbage collection</a>
<li><a href="#Chicken_collection">Garbage collection</a>
</ul>
<li><a href="#Chicken_nn18">Unsupported features and known problems</a>
<ul>
@ -72,7 +72,7 @@
</p>
<H2><a name="Chicken_nn2"></a>18.1 Preliminaries</H2>
<H2><a name="Chicken_nn2"></a>20.1 Preliminaries</H2>
<p>
@ -80,17 +80,16 @@
relies on some recent additions to CHICKEN, which are only
present in releases of CHICKEN with version number
<strong>greater than or equal to 1.89</strong>.
To use a chicken version between 1.40 and 1.89, see the <a href="#collection">Garbage collection</a>
To use a chicken version between 1.40 and 1.89, see the <a href="#Chicken_collection">Garbage collection</a>
section below.
</p>
<p>
You may want to look at any of the examples in Examples/chicken/
or Examples/GIFPlot/Chicken for the basic steps to run SWIG
CHICKEN.
directory for the basic steps to run SWIG CHICKEN.
</p>
<H3><a name="Chicken_nn3"></a>18.1.1 Running SWIG in C mode</H3>
<H3><a name="Chicken_nn3"></a>20.1.1 Running SWIG in C mode</H3>
<p>
@ -123,7 +122,7 @@
object files and linked into your project.
</p>
<H3><a name="Chicken_nn4"></a>18.1.2 Running SWIG in C++ mode</H3>
<H3><a name="Chicken_nn4"></a>20.1.2 Running SWIG in C++ mode</H3>
<p>
@ -152,10 +151,10 @@
object files and linked into your project.
</p>
<H2><a name="Chicken_nn5"></a>18.2 Code Generation</H2>
<H2><a name="Chicken_nn5"></a>20.2 Code Generation</H2>
<H3><a name="Chicken_nn6"></a>18.2.1 Naming Conventions</H3>
<H3><a name="Chicken_nn6"></a>20.2.1 Naming Conventions</H3>
<p>
@ -171,7 +170,7 @@
<tt>%rename</tt> SWIG directive in the SWIG interface file.
</p>
<H3><a name="Chicken_nn7"></a>18.2.2 Modules</H3>
<H3><a name="Chicken_nn7"></a>20.2.2 Modules</H3>
<p>
@ -193,7 +192,7 @@
(uses <i>modulename</i>))</code> CHICKEN Scheme form.
</p>
<H3><a name="Chicken_nn8"></a>18.2.3 Constants and Variables</H3>
<H3><a name="Chicken_nn8"></a>20.2.3 Constants and Variables</H3>
<p>
@ -226,11 +225,11 @@
a function that must be called, the constant will appear as a
scheme variable. This causes the generated .scm file to just contain the code
<tt>(set! MYCONSTANT1 (MYCONSTANT1))</tt>. See
<a href="Customization.html#features">Features and the %feature directive</a>
<a href="Customization.html#Customization_features">Features and the %feature directive</a>
for info on how to apply the %feature.
</p>
<H3><a name="Chicken_nn9"></a>18.2.4 Functions</H3>
<H3><a name="Chicken_nn9"></a>20.2.4 Functions</H3>
<p>
@ -249,12 +248,12 @@
parameters). The return values can then be accessed with <code>(call-with-values)</code>.
</p>
<H3><a name="Chicken_nn10"></a>18.2.5 Exceptions</H3>
<H3><a name="Chicken_nn10"></a>20.2.5 Exceptions</H3>
<p>The SWIG chicken module has support for exceptions thrown from
C or C++ code to be caught in scheme.
See <a href="Customization.html#exception">Exception handling with %exception</a>
See <a href="Customization.html#Customization_exception">Exception handling with %exception</a>
for more information about declaring exceptions in the interface file.
</p>
@ -263,7 +262,7 @@
inside the %exception blocks. <code>SWIG_exception</code> will throw a list consisting of the code
(as an integer) and the message. Both of these will throw an exception using <code>(abort)</code>,
which can be handled by <code>(handle-exceptions)</code>. See
<a href="http://www.call-with-current-continuation.org/manual/Exceptions.html#Exceptions">Chicken manual on Exceptions</a>
the Chicken manual on Exceptions
and <a href="http://srfi.schemers.org/srfi-12/srfi-12.html">SFRI-12</a>. Since the exception values are thrown
directly, if <code>(condition-case)</code> is used to catch an exception the exception will come through in the <code>val ()</code> case.
</p>
@ -291,7 +290,7 @@
</pre></div>
<H2><a name="Chicken_nn11"></a>18.3 TinyCLOS</H2>
<H2><a name="Chicken_nn11"></a>20.3 TinyCLOS</H2>
<p>
@ -334,7 +333,7 @@
</p>
<H2><a name="Chicken_nn12"></a>18.4 Linkage</H2>
<H2><a name="Chicken_nn12"></a>20.4 Linkage</H2>
<p>
@ -355,7 +354,7 @@
</p>
<H3><a name="Chicken_nn13"></a>18.4.1 Static binary or shared library linked at compile time</H3>
<H3><a name="Chicken_nn13"></a>20.4.1 Static binary or shared library linked at compile time</H3>
<p>We can easily use csc to build a static binary.</p>
@ -396,7 +395,7 @@ in which case the test script does not need to be linked with example.so. The t
be run with <tt>csi</tt>.
</p>
<H3><a name="Chicken_nn14"></a>18.4.2 Building chicken extension libraries</H3>
<H3><a name="Chicken_nn14"></a>20.4.2 Building chicken extension libraries</H3>
<p>Building a shared library like in the above section only works if the library
@ -417,8 +416,8 @@ $ csc -sv modname.scm modname_wrap.c modname_impl.c -o modname.so
</div>
<p>This library can then be loaded by scheme code with the <code>(require 'modname)</code> function.
See <a href="http://www.call-with-current-continuation.org/manual/Loading-extension-libraries.html">
Loading-extension-libraries</a> in the eval unit inside the CHICKEN manual for more information.</p>
See the
Loading-extension-libraries in the eval unit inside the CHICKEN manual for more information.</p>
<p>Another alternative is to run SWIG normally and create a scheme file that contains <code>(declare (uses <i>modname</i>))</code>
and then compile that file into the shared library as well. For example, inside the <tt>mod_load.scm</tt> file,</p>
@ -454,7 +453,7 @@ distributed and used by anyone, even if SWIG is not installed.</p>
<p>See the <tt>Examples/chicken/egg</tt> directory in the SWIG source for an example that builds
two eggs, one using the first method and one using the second method.</p>
<H3><a name="Chicken_nn15"></a>18.4.3 Linking multiple SWIG modules with TinyCLOS</H3>
<H3><a name="Chicken_nn15"></a>20.4.3 Linking multiple SWIG modules with TinyCLOS</H3>
<p>Linking together multiple modules that share type information using the <code>%import</code>
@ -478,7 +477,7 @@ with <code>(declare (uses ...))</code>.
To create an extension library or an egg, just create a <tt>module_load.scm</tt> file that <code>(declare (uses ...))</code>
all the modules.</p>
<H2><a name="Chicken_nn16"></a>18.5 Typemaps</H2>
<H2><a name="Chicken_nn16"></a>20.5 Typemaps</H2>
<p>
@ -487,7 +486,7 @@ all the modules.</p>
<code>Lib/chicken/chicken.swg</code>.
</p>
<H2><a name="Chicken_nn17"></a>18.6 Pointers</H2>
<H2><a name="Chicken_nn17"></a>20.6 Pointers</H2>
<p>
@ -520,7 +519,7 @@ all the modules.</p>
type. flags is either zero or SWIG_POINTER_DISOWN (see below).
</p>
<H3><a name="collection"></a>18.6.1 Garbage collection</H3>
<H3><a name="Chicken_collection"></a>20.6.1 Garbage collection</H3>
<p>If the owner flag passed to <code>SWIG_NewPointerObj</code> is 1, <code>NewPointerObj</code> will add a
@ -531,12 +530,12 @@ all the modules.</p>
be garbage collected, SWIG will automatically set the owner flag to 1. For other functions,
the <code>%newobject</code> directive must be specified for functions whose return values
should be garbage collected. See
<a href="Customization.html#ownership">Object ownership and %newobject</a> for more information.
<a href="Customization.html#Customization_ownership">Object ownership and %newobject</a> for more information.
</p>
<p>In situations where a C or C++ function will assume ownership of a pointer, and thus
chicken should no longer garbage collect it, SWIG provides the <code>DISOWN</code> input typemap.
After applying this typemap (see the <a href="Typemaps.html">Typemaps chapter</a> for more information on how to apply typemaps),
After applying this typemap (see the <a href="Typemaps.html#Typemaps">Typemaps chapter</a> for more information on how to apply typemaps),
any pointer that gets passed in will no longer be garbage collected.
An object is disowned by passing the <code>SWIG_POINTER_DISOWN</code> flag to <code>SWIG_ConvertPtr</code>.
<b>Warning:</b> Since the lifetime of the object is now controlled by the underlying code, the object might
@ -551,7 +550,7 @@ all the modules.</p>
must be called manually.
</p>
<H2><a name="Chicken_nn18"></a>18.7 Unsupported features and known problems</H2>
<H2><a name="Chicken_nn18"></a>20.7 Unsupported features and known problems</H2>
<ul>
@ -561,7 +560,7 @@ all the modules.</p>
<a href="SWIGPlus.html#SWIGPlus_default_args">%feature(compactdefaultargs)</a>.</li>
</ul>
<H3><a name="Chicken_nn19"></a>18.7.1 TinyCLOS problems with Chicken version &lt;= 1.92</H3>
<H3><a name="Chicken_nn19"></a>20.7.1 TinyCLOS problems with Chicken version &lt;= 1.92</H3>
<p>In Chicken versions equal to or below 1.92, TinyCLOS has a limitation such that generic methods do not properly work on methods

656
Doc/Manual/Contents.html
View file

File diff suppressed because it is too large Load diff

62
Doc/Manual/Customization.html
View file

@ -10,7 +10,7 @@
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="#exception">Exception handling with %exception</a>
<li><a href="#Customization_exception">Exception handling with %exception</a>
<ul>
<li><a href="#Customization_nn3">Handling exceptions in C code</a>
<li><a href="#Customization_nn4">Exception handling with longjmp()</a>
@ -20,14 +20,14 @@
<li><a href="#Customization_exception_special_variables">Special variables for %exception</a>
<li><a href="#Customization_nn7">Using The SWIG exception library</a>
</ul>
<li><a href="#ownership">Object ownership and %newobject</a>
<li><a href="#features">Features and the %feature directive</a>
<li><a href="#Customization_ownership">Object ownership and %newobject</a>
<li><a href="#Customization_features">Features and the %feature directive</a>
<ul>
<li><a href="#Customization_feature_attributes">Feature attributes</a>
<li><a href="#Customization_feature_flags">Feature flags</a>
<li><a href="#Customization_clearing_features">Clearing features</a>
<li><a href="#Customization_features_default_args">Features and default arguments</a>
<li><a href="#features_example">Feature example</a>
<li><a href="#Customization_features_example">Feature example</a>
</ul>
</ul>
</div>
@ -45,7 +45,7 @@ of exception handling is presented. Then, a more general-purpose
customization mechanism known as "features" is described.
</p>
<H2><a name="exception"></a>11.1 Exception handling with %exception</H2>
<H2><a name="Customization_exception"></a>11.1 Exception handling with %exception</H2>
<p>
@ -53,6 +53,21 @@ The <tt>%exception</tt> directive allows you to define a general purpose excepti
handler. For example, you can specify the following:
</p>
<div class="code"><pre>
%exception {
try {
$action
}
catch (RangeError) {
... handle error ...
}
}
</pre></div>
<p>
How the exception is handled depends on the target language, for example, Python:
</p>
<div class="code"><pre>
%exception {
try {
@ -60,7 +75,7 @@ handler. For example, you can specify the following:
}
catch (RangeError) {
PyErr_SetString(PyExc_IndexError,"index out-of-bounds");
return NULL;
SWIG_fail;
}
}
</pre></div>
@ -68,7 +83,7 @@ handler. For example, you can specify the following:
<p>
When defined, the code enclosed in braces is inserted directly into the low-level wrapper
functions. The special variable <tt>$action</tt> is one of a few
<a href="Customization.html#Customization_exception_special_variables">%exception special variable</a>
<a href="Customization.html#Customization_exception_special_variables">%exception special variables</a>
supported and gets replaced with the actual operation
to be performed (a function call, method invocation, attribute access, etc.). An exception handler
remains in effect until it is explicitly deleted. This is done by using either <tt>%exception</tt>
@ -336,7 +351,7 @@ In this case, the exception handler is only attached to declarations
named "allocate". This would include both global and member
functions. The names supplied to <tt>%exception</tt> follow the same
rules as for <tt>%rename</tt> described in the section on
<a href="SWIGPlus.html#ambiguity_resolution_renaming">Ambiguity resolution and renaming</a>.
<a href="SWIGPlus.html#SWIGPlus_ambiguity_resolution_renaming">Ambiguity resolution and renaming</a>.
For example, if you wanted to define
an exception handler for a specific class, you might write this:
</p>
@ -567,7 +582,7 @@ it can be used elsewhere in SWIG. This includes typemaps and helper
functions.
</p>
<H2><a name="ownership"></a>11.2 Object ownership and %newobject</H2>
<H2><a name="Customization_ownership"></a>11.2 Object ownership and %newobject</H2>
<p>
@ -689,6 +704,11 @@ depends on the target language on implementing the 'disown' mechanism
properly.
</p>
<p>
The use of <tt>%newobject</tt> is also integrated with reference counting and is covered in the
<a href="SWIGPlus.html#SWIGPlus_ref_unref">C++ reference counted objects</a> section.
</p>
<p>
<b>Compatibility note:</b> Previous versions of SWIG had a special <tt>%new</tt> directive. However, unlike <tt>%newobject</tt>,
it only applied to the next declaration. For example:
@ -719,7 +739,7 @@ char *strdup(const char *s);
The results might not be what you expect.
</p>
<H2><a name="features"></a>11.3 Features and the %feature directive</H2>
<H2><a name="Customization_features"></a>11.3 Features and the %feature directive</H2>
<p>
@ -758,9 +778,9 @@ involving <tt>%feature</tt>:
</div>
<p>
The name matching rules outlined in the <a href="SWIGPlus.html#ambiguity_resolution_renaming">Ambiguity resolution and renaming</a>
The name matching rules outlined in the <a href="SWIGPlus.html#SWIGPlus_ambiguity_resolution_renaming">Ambiguity resolution and renaming</a>
section applies to all <tt>%feature</tt> directives.
In fact the the <tt>%rename</tt> directive is just a special form of <tt>%feature</tt>.
In fact the <tt>%rename</tt> directive is just a special form of <tt>%feature</tt>.
The matching rules mean that features are very flexible and can be applied with
pinpoint accuracy to specific declarations if needed.
Additionally, if no declaration name is given, a global feature is said to be defined.
@ -839,7 +859,7 @@ In the following example, <tt>MyExceptionClass</tt> is the name of the Java clas
</div>
<p>
Further details can be obtained from the <a href="Java.html#exception_handling">Java exception handling</a> section.
Further details can be obtained from the <a href="Java.html#Java_exception_handling">Java exception handling</a> section.
</p>
<H3><a name="Customization_feature_flags"></a>11.3.2 Feature flags</H3>
@ -1019,6 +1039,20 @@ but this will:
</pre>
</div>
<p>
SWIG provides macros for disabling and clearing features. Many of these can be found in the <tt>swig.swg</tt> library file.
The typical pattern is to define three macros; one to define the feature itself, one to disable the feature and one to clear the feature.
The three macros below show this for the "except" feature:
</p>
<div class="code">
<pre>
#define %exception %feature("except")
#define %noexception %feature("except","0")
#define %clearexception %feature("except","")
</pre>
</div>
<H3><a name="Customization_features_default_args"></a>11.3.4 Features and default arguments</H3>
@ -1094,7 +1128,7 @@ specifying or not specifying default arguments in a feature is not applicable as
in SWIG-1.3.23 when the approach to wrapping methods with default arguments was changed.
</p>
<H3><a name="features_example"></a>11.3.5 Feature example</H3>
<H3><a name="Customization_features_example"></a>11.3.5 Feature example</H3>
<p>

454
Doc/Manual/D.html Normal file
View file

@ -0,0 +1,454 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>SWIG and D</title>
<link rel="stylesheet" type="text/css" href="style.css">
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
</head>
<body bgcolor="#FFFFFF">
<H1><a name="D"></a>21 SWIG and D</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="#D_introduction">Introduction</a>
<li><a href="#D_command_line_invocation">Command line invocation</a>
<li><a href="#D_typemaps">Typemaps</a>
<ul>
<li><a href="#D_typemap_name_comparison">C# &lt;-&gt; D name comparison</a>
<li><a href="#D_ctype_imtype_dtype">ctype, imtype, dtype</a>
<li><a href="#D_in_out_directorin_direcetorout">in, out, directorin, directorout</a>
<li><a href="#D_din_dout_ddirectorin_ddirectorout">din, dout, ddirectorin, ddirectorout</a>
<li><a href="#D_typecheck_typemaps">typecheck typemaps</a>
<li><a href="#D_code_injection_typemaps">Code injection typemaps</a>
<li><a href="#D_special_variables">Special variable macros</a>
</ul>
<li><a href="#D_features"><tt>%feature</tt>s</a>
<li><a href="#D_pragmas">Pragmas</a>
<li><a href="#D_exceptions">D Exceptions</a>
<li><a href="#D_directors">D Directors</a>
<li><a href="#D_other_features">Other features</a>
<ul>
<li><a href="#D_nspace">Extended namespace support (<tt>nspace</tt>)</a>
<li><a href="#D_native_pointer_support">Native pointer support</a>
<li><a href="#D_operator_overloading">Operator overloading</a>
<li><a href="#D_test_suite">Running the test-suite</a>
</ul>
<li><a href="#D_typemap_examples">D Typemap examples</a>
<li><a href="#D_planned_features">Work in progress and planned features</a>
</ul>
</div>
<!-- INDEX -->
<H2><a name="D_introduction"></a>21.1 Introduction</H2>
<p>From the <a href="http://www.digitalmars.com/d/">D Programming Language</a> web site: <em>D is a systems programming language. Its focus is on combining the power and high performance of C and C++ with the programmer productivity of modern languages like Ruby and Python. [...] The D language is statically typed and compiles directly to machine code.</em> As such, it is not very surprising that D is able to directly <a href="http://www.digitalmars.com/d/1.0/interfaceToC.html">interface with C libraries</a>. Why would a SWIG module for D be needed then in the first place?</p>
<p>Well, besides the obvious downside that the C header files have to be manually converted to D modules for this to work, there is one major inconvenience with this approach: D code usually is on a higher abstraction level than C, and many of the features that make D interesting are simply not available when dealing with C libraries, requiring you e.g. to manually convert strings between pointers to <tt>\0</tt>-terminated char arrays and D char arrays, making the algorithms from the D2 standard library unusable with C arrays and data structures, and so on.</p>
<p>While these issues can be worked around relatively easy by hand-coding a thin wrapper layer around the C library in question, there is another issue where writing wrapper code per hand is not feasible: C++ libraries. D did not support interfacing to C++ in version 1 at all, and even if <tt>extern(C++)</tt> has been added to D2, the support is still very limited, and a custom wrapper layer is still required in many cases. </p>
<p>To help addressing these issues, the SWIG C# module has been forked to support D. Is has evolved quite a lot since then, but there are still many similarities, so if you do not find what you are looking for on this page, it might be worth having a look at the chapter on <a href="CSharp.html">C#</a> (and also on <a href="Java.html">Java</a>, since the C# module was in turn forked from it).</p>
<H2><a name="D_command_line_invocation"></a>21.2 Command line invocation</H2>
<p>To activate the D module, pass the <tt>-d</tt> option to SWIG at the command line. The same standard command line switches as with any other language module are available, plus the following D specific ones:</p>
<dl>
<dt><tt>-d2</tt></dt>
<dd>
<p>By default, SWIG generates code for D1/Tango. Use the <tt>-d2</tt> flag to target D2/Phobos instead.</p>
</dd>
<dt id="D_splitproxy"><tt>-splitproxy</tt></dt>
<dd>
<p>By default, SWIG generates two D modules: the <em>proxy</em> module, named like the source module (either specified via the <tt>%module</tt> directive or via the <tt>module</tt> command line switch), which contains all the proxy classes, functions, enums, etc., and the <em>intermediary</em> module (named like the proxy module, but suffixed with <tt>_im</tt>), which contains all the <tt>extern(C)</tt> function declarations and other private parts only used internally by the proxy module.</p>
<p>If the split proxy mode is enabled by passing this switch at the command line, all proxy classes and enums are emitted to their own D module instead. The main proxy module only contains free functions and constants in this case.</p>
</dd>
<dt><tt>-package &lt;pkg&gt;</tt></dt>
<dd>
<p>By default, the proxy D modules and the intermediary D module are written to the root package. Using this option, you can specify another target package instead.</p>
</dd>
<dt><tt>-wrapperlibrary &lt;wl&gt;</tt></dt>
<dd>
<p>The code SWIG generates to dynamically load the C/C++ wrapper layer looks for a library called <tt>$module_wrap</tt> by default. With this switch, you can override the name of the file the wrapper code loads at runtime (the <tt>lib</tt> prefix and the suffix for shared libraries are appended automatically, depending on the OS).</p>
<p>This might especially be useful if you want to invoke SWIG several times on separate modules, but compile the resulting code into a single shared library.</p>
</dd>
</dl>
<H2><a name="D_typemaps"></a>21.3 Typemaps</H2>
<H3><a name="D_typemap_name_comparison"></a>21.3.1 C# &lt;-&gt; D name comparison</H3>
<p>If you already know the SWIG C# module, you might find the following name comparison table useful:</p>
<div class="diagram"><pre>
ctype &lt;-&gt; ctype
imtype &lt;-&gt; imtype
cstype &lt;-&gt; dtype
csin &lt;-&gt; din
csout &lt;-&gt; dout
csdirectorin &lt;-&gt; ddirectorin
csdirectorout &lt;-&gt; ddirectorout
csinterfaces &lt;-&gt; dinterfaces
csinterfaces_derived &lt;-&gt; dinterfaces_derived
csbase &lt;-&gt; dbase
csclassmodifiers &lt;-&gt; dclassmodifiers
cscode &lt;-&gt; dcode
csimports &lt;-&gt; dimports
csbody &lt;-&gt; dbody
csfinalize &lt;-&gt; ddestructor
csdestruct &lt;-&gt; ddispose
csdestruct_derived &lt;-&gt; ddispose_derived
</pre></div>
<H3><a name="D_ctype_imtype_dtype"></a>21.3.2 ctype, imtype, dtype</H3>
<p>Mapping of types between the C/C++ library, the C/C++ library wrapper exposing the C functions, the D wrapper module importing these functions and the D proxy code.</p>
<p>The <tt>ctype</tt> typemap is used to determine the types to use in the C wrapper functions. The types from the <tt>imtype</tt> typemap are used in the extern(C) declarations of these functions in the intermediary D module. The <tt>dtype</tt> typemap contains the D types used in the D proxy module/class.</p>
<H3><a name="D_in_out_directorin_direcetorout"></a>21.3.3 in, out, directorin, directorout</H3>
<p>Used for converting between the types for C/C++ and D when generating the code for the wrapper functions (on the C++ side).</p>
<p>The code from the <tt>in</tt> typemap is used to convert arguments to the C wrapper function to the type used in the wrapped code (<tt>ctype</tt>->original C++ type), the <tt>out</tt> typemap is utilized to convert values from the wrapped code to wrapper function return types (original C++ type-><tt>ctype</tt>).</p>
<p>The <tt>directorin</tt> typemap is used to convert parameters to the type used in the D director callback function, its return value is processed by <tt>directorout</tt> (see below).</p>
<H3><a name="D_din_dout_ddirectorin_ddirectorout"></a>21.3.4 din, dout, ddirectorin, ddirectorout</H3>
<p>Typemaps for code generation in D proxy and type wrapper classes.</p>
<p id="D_din">The <tt>din</tt> typemap is used for converting function parameter types from the type used in the proxy module or class to the type used in the intermediary D module (the <a href="D.html#D_dinput"><tt>$dinput</tt></a> macro is replaced). To inject further parameter processing code before or after the call to the intermediary layer, the <tt>pre</tt>, <tt>post</tt> and <tt>terminator</tt> attributes can be used (please refer to the <a href="CSharp.html#CSharp_date_marshalling">C# date marshalling example</a> for more information on these).</p>
<p id="D_dout">The <tt>dout</tt> typemap is used for converting function return values from the return type used in the intermediary D module to the type returned by the proxy function. The <tt>$excode</tt> special variable in <tt>dout</tt> typemaps is replaced by the <tt>excode</tt> typemap attribute code if the method can throw any exceptions from unmanaged code, otherwise by nothing (the <a href="D.html#D_imcall"><tt>$imcall</tt> and <tt>$owner</tt></a> macros are replaced).</p>
<p id="D_ddirectorinout">The code from the <tt>ddirectorin</tt> and <tt>ddirectorout</tt> typemaps is used for conversion in director callback functions. Arguments are converted to the type used in the proxy class method they are calling by using the code from <tt>ddirectorin</tt>, the proxy class method return value is converted to the type the C++ code expects via the <tt>ddirectorout</tt> typemap (the <a href="D.html#D_dpcall"><tt>$dcall</tt> and <tt>$winput</tt></a> macros are replaced).</p>
<p>The full chain of type conversions when a director callback is invoked looks like this:</p>
<div class="diagram"><pre>
type CPPClass::method(type a)
&uarr; &darr;
&lt;directorout&gt; &lt;directorin&gt;
&uarr; &darr;
ctype methodCallback(ctype a) C++
:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
imtype methodCallback(imtype a) D
&uarr; &darr;
&lt;ddirectorout&gt; &lt;ddirectorin&gt;
&uarr; &darr;
dtype DClass.method(dtype a)</pre></div>
<H3><a name="D_typecheck_typemaps"></a>21.3.5 typecheck typemaps</H3>
<p>Because, unlike many scripting languages supported by SWIG, D does not need any dynamic dispatch helper to access an overloaded function, the purpose of these is merely to issue a warning for overloaded C++ functions that cannot be overloaded in D (as more than one C++ type maps to a single D type).</p>
<H3><a name="D_code_injection_typemaps"></a>21.3.6 Code injection typemaps</H3>
<p>These typemaps are used for generating the skeleton of proxy classes for C++ types.</p>
<p>By overriding <tt>dbase</tt>, <tt>dinterfaces</tt> or <tt>dinterfaces_derived</tt>, the inheritance chain of the generated proxy class for a type can be modified. <tt>dclassmodifiers</tt> allows you to add any custom modifiers around the class keyword.</p>
<p>Using <tt>dcode</tt> and <tt>dimports</tt>, you can specify additional D code which will be emitted into the class body respectively the imports section of the D module the class is written to.</p>
<p id="D_class_code_typemaps"><tt>dconstructor</tt>, <tt>ddestructor</tt>, <tt>ddispose</tt> and <tt>ddispose_derived</tt> are used to generate the class constructor, destructor and <tt>dispose()</tt> method, respectively. The auxiliary code for handling the pointer to the C++ object is stored in <tt>dbody</tt> and <tt>dbody_derived</tt>. You can override them for specific types.</p>
<H3><a name="D_special_variables"></a>21.3.7 Special variable macros</H3>
<p>The standard SWIG special variables are available for use within typemaps as described in the <a href="Typemaps.html#Typemaps">Typemaps documentation</a>, for example <tt>$1</tt>, <tt>$input</tt>, <tt>$result</tt> etc.</p>
<p>When generating D wrappers, a few additional macros are available:</p>
<dl>
<dt><tt>$dclassname</tt> (C#: <tt>$csclassname</tt>)</dt>
<dd>
<p>This special variable works similar to <a href="Typemaps.html#Typemaps_special_variables"><tt>$n_type</tt></a> in that it returns the name of a type - it expands to the D proxy class name of the type being wrapped. If the type does not have an associated proxy class, it expands to the type wrapper class name, for example, <tt>SWIGTYPE_p_p_SomeCppClass</tt> is generated when wrapping <tt>SomeCppClass **</tt>.</p>
<p>There are two other variants available, <tt>$&amp;dclassname</tt> and <tt>$*dclassname</tt>. The former adds a level of indirection, while the latter removes one. For instance, when wrapping <tt>Foo **</tt>, <tt>$*dclassname</tt> would be replaced by the proxy class name corresponding to <tt>Foo *</tt>.</p>
</dd>
<dt><tt>$dclazzname</tt> (C#: <tt>$csclazzname</tt>)</dt>
<dd>
<p>This special variable expands the fully qualified C++ class into the package name, if used by the <a href="SWIGPlus.html#SWIGPlus_nspace"><tt>nspace</tt> feature</a>, and the proxy class name, mangled for use as a function name. For example, <tt>Namespace1::Namespace2::Klass</tt> is expanded into <tt>Namespace1_Namespace2_Klass_</tt>.</p>
<p>This special variable might be useful for calling certain functions in the wrapper layer (e.g. upcast wrappers) which are mangled like this.</p>
</dd>
<dt><tt>$null</tt></dt>
<dd><p>In code inserted into the generated C/C++ wrapper functions, this variable is replaced by either <tt>0</tt> or nothing at all, depending on whether the function has a return value or not. It can be used to bail out early e.g. in case of errors (<tt>return $null;</tt>).</p></dd>
<dt id="D_dinput"><tt>$dinput</tt> (C#: <tt>$csinput</tt>)</dt>
<dd>
<p>This variable is used in <tt><a href="D.html#D_din">din</a></tt> typemaps and is replaced by the expression which is to be passed to C/C++.</p>
<p>For example, this input</p>
<div class="code"><pre>
%typemap(din) SomeClass * "SomeClass.getCPointer($dinput)"
%inline %{
class SomeClass {};
void foo(SomeClass *arg);
%}</pre></div>
<p>leads to the following D proxy code being generated:</p>
<div class="targetlang"><pre>
void foo(SomeClass arg) {
example_im.foo(SomeClass.getCPointer(arg));
}</pre></div></dd>
<dt id="D_imcall"><tt>$imcall</tt> and <tt>$owner</tt> (C#: <tt>$imcall</tt>)</dt>
<dd>
<p>These variables are used in <tt><a href="D.html#D_dout">dout</a></tt> typemaps. <tt>$imcall</tt> contains the call to the intermediary module which provides the value to be used, and <tt>$owner</tt> signals if the caller is responsible for managing the object lifetime (that is, if the called method is a constructor or has been marked via <tt>%newobject</tt>).</p>
<p>Consider the following example:</p>
<div class="code"><pre>
%typemap(dout) SomeClass * {
return new SomeClass($imcall, $owner);
}
%inline %{
class SomeClass;
SomeClass *foo();
%newobject bar();
SomeClass *bar();
%}</pre></div>
<p>The code generated for <tt>foo()</tt> and <tt>bar()</tt> looks like this:</p>
<div class="targetlang"><pre>
SomeClass foo() {
return new SomeClass(example_im.foo(), false);
}
SomeClass bar() {
return new SomeClass(example_im.bar(), true);
}
</pre></div>
</dd>
<dt><tt>$dcall</tt> and <tt>$winput</tt> (C#: <tt>$cscall</tt>, <tt>$iminput</tt>)</dt>
<dd id="D_dpcall"><p>These variables are used in the director-specific typemaps <a href="D.html#D_ddirectorinout"><tt>ddirectorin</tt></a> and <a href="D.html#D_ddirectorinout"><tt>ddirectorout</tt></a>. They are more or less the reverse of the <tt>$imcall</tt> and <tt>$dinput</tt> macros: <tt>$dcall</tt> contains the invocation of the D proxy method of which the return value is to be passed back to C++, <tt>$winput</tt> contains the parameter value from C++.</p></dd>
<dt><tt>$excode</tt></dt>
<dd><p>This variable is used in <tt>dout</tt> and <tt>dconstructor</tt> typemaps and is filled with the contents of the <tt>excode</tt> typemap attribute if an exception could be thrown from the C++ side. See the <a href="CSharp.html#CSharp_exceptions">C# documentation</a> for details.</p></dd>
<dt><tt>$dbaseclass</tt></dt>
<dd><p>Currently for internal use only, it contains the D name of the C++ base class (if any) inside proxy classes.</p></dd>
<dt><tt>$directorconnect</tt></dt>
<dd>
<p>This macro is only valid inside the <tt><a href="D.html#D_class_code_typemaps">dconstructor</a></tt> typemap and contains the value of the <tt>dconstructor</tt> typemap attribute if the currently wrapped class has directors enabled.</p>
<p>This is how the default <tt>dconstructor</tt> typemap looks like (you usually do not want to specify a custom one):</p>
<div class="code"><pre>
%typemap(dconstructor, excode=SWIGEXCODE,
directorconnect="\n swigDirectorConnect();") SWIGTYPE {
this($imcall, true);$excode$directorconnect
}
</pre></div>
</dd>
<dt id="D_importtype"><tt>$importtype(SomeDType)</tt></dt>
<dd>
<p>This macro is used in the <tt>dimports</tt> typemap if a dependency on another D type generated by SWIG is added by a custom typemap.</p>
<p>Consider the following code snippet:</p>
<div class="code"><pre>
%typemap(dinterfaces) SomeClass "AnInterface, AnotherInterface";
</pre></div>
<p>This causes SWIG to add <tt>AnInterface</tt> and <tt>AnotherInterface</tt> to the base class list of <tt>SomeClass</tt>:</p>
<div class="targetlang"><pre>
class SomeClass : AnInterface, AnotherInterface {
...
}
</pre></div>
<p>For this to work, <tt>AnInterface</tt> and <tt>AnotherInterface</tt> have to be in scope. If SWIG is not in split proxy mode, this is already the case, but it it is, they have to be added to the import list via the <tt>dimports</tt> typemap. Additionally, the import statement depends on the package SWIG is configured to emit the modules to.</p>
<p>The <tt>$importtype</tt> macro helps you to elegantly solve this problem:</p>
<div class="code"><pre>
%typemap(dimports) RemoteMpe %{
$importtype(AnInterface)
$importtype(AnotherInterface)
%}
</pre></div>
<p>If SWIG is in split proxy mode, it expands to an <tt>import</tt> statement for the specified type, to nothing if not.</p>
</dd>
<dt><tt>$module</tt></dt>
<dd><p>Expands to the name of the main proxy D module.</p></dd>
<dt><tt>$imdmodule</tt></dt>
<dd><p>Contains the fully qualified name of the intermediary D module.</p></dd>
</dl>
<H2><a name="D_features"></a>21.4 <tt>%feature</tt>s</H2>
<p>The D module defines a number of directives which modify the <a href="Customization.html#Customization_features">SWIG features</a> set globally or for a specific declaration:</p>
<dl>
<dt><tt>%dmanifestconst</tt> and <tt>%dconstvalue(value)</tt></dt>
<dd>
<p>Out of the box, SWIG generates accessor methods for C <tt>#defines</tt> and C++ constants. The <tt>%dmanifestconst</tt> directive enables wrapping these constants as D manifest constants (<tt>const</tt> in D1, <tt>enum</tt> in D2).</p>
<p>For this to work, the C/C++ code for the constant value must directly compile as D code, though. If this is not the case, you can manually override the expression written to the D proxy module using the <tt>%dconstvalue</tt> directive, passing the new value as parameter.</p>
<p>For <tt>enum</tt>s, again <tt>%dconstvalue</tt> can be used to override the value of an enum item if the initializer should not compile in D.</p>
</dd>
<dt><tt>%dmethodmodifiers</tt></dt>
<dd>
<p>This directive can be used to override the modifiers for a proxy function. For instance, you could make a <tt>public</tt> C++ member function <tt>private</tt> in D like this:</p>
<div class="code"><pre>
%dmethodmodifiers A::foo "private";
%inline %{
struct A {
void foo();
};
%}
</pre></div>
</dd>
</dl>
<H2><a name="D_pragmas"></a>21.5 Pragmas</H2>
<p>There are a few SWIG pragmas specific to the D module, which you can use to influence the D code SWIG generates:</p>
<dl>
<dt><tt>%pragma(d) imdmodulecode</tt></dt>
<dd><p>The passed text (D code) is copied verbatim to the intermediary D module. For example, it can be (and is, internally) used to emit additional private helper code for the use by proxy typemaps.</p></dd>
<dt><tt>%pragma(d) imdmoduleimports</tt></dt>
<dd><p>Additional code to be emitted to the imports section of the intermediary D module (the <a href="D.html#D_importtype">$importtype</a> macro can be used here). You probably want to use this in conjunction with the <tt>imdmodulecode</tt> pragma.</p></dd>
<dt><tt>%pragma(d) proxydmodulecode</tt></dt>
<dd><p>Just like <tt>proxydmodulecode</tt>, the argument is copied to the proxy D module (if SWIG is in <a href="D.html#D_splitproxy">split proxy mode</a> and/or the <tt>nspace</tt> feature is used, it is emitted to the main proxy D module only).</p></dd>
<dt><tt>%pragma(d) globalproxyimports</tt></dt>
<dd>
<p>The D module currently does not support specifying dependencies on external modules (e.g. from the standard library) for the D typemaps. To add the import statements to the proxy modules (resp. to <em>all</em> proxy modules if in split proxy mode), you can use the <tt>globalproxyimports</tt> directive.</p>
<p>For example:</p>
<div class="code"><pre>
%typemap(din) char[] "($dinput ? tango.stdc.stringz.toStringz($dinput) : null)"
%pragma(d) globalproxyimports = "static import tango.stdc.stringz;";
</pre></div>
</dd>
<dt><tt>%pragma(d) wrapperloadercode</tt></dt>
<dd>
<p>The D code for loading the wrapper library (it is copied to the intermediary D module). The <tt>$wrapperloaderbindcode</tt> variable is replaced by the list of commands for binding the functions from the wrapper library to the symbols in the intermediary D module.</p>
<p>Each time this pragma is specified, the previous value is overwritten.</p>
</dd>
<dt><tt>%pragma(d) wrapperloaderbindcommand</tt></dt>
<dd>
<p>The D command to use for binding the wrapper functions from the C/C++ library to the symbols in the intermediary D module. The <tt>$function</tt> variable contains the name of the D function in the wrap module, the <tt>$symbol</tt> variable is replaced by the name of the symbol in the library.</p>
<p>Each time this pragma is specified, the previous value is overwritten.</p>
</dd>
</dl>
<H2><a name="D_exceptions"></a>21.6 D Exceptions</H2>
<p>Out of the box, C++ exceptions are fundamentally incompatible to their equivalent in the D world and cannot simply be propagated to a calling D method. There is, however, an easy way to solve this problem: Just catch the exception in the C/C++ wrapper layer, pass the contents to D, and make the wrapper code rethrow the exception in the D world.</p>
<p>The implementation details of this are a bit crude, but the SWIG D module automatically takes care of this, as long as it is able to detect that an exception could potentially be thrown (e.g. because the C++ method has a <tt>throw(...)</tt> exception specification).</p>
<p>As this feature is implemented in exactly the same way it is for C#, please see the <a href="CSharp.html#CSharp_exceptions">C# documentation</a> for a more detailed explanation.</p>
<H2><a name="D_directors"></a>21.7 D Directors</H2>
<p>When the directors feature is activated, SWIG generates extra code on both the C++ and the D side to enable cross-language polymorphism. Essentially, this means that if you subclass a proxy class in D, C++ code can access any overridden virtual methods just as if you created a derived class in C++.</p>
<p>There is no D specific documentation yet, but the way the feature is implemented is very similar to how it is done in <a href="Java.html#Java_directors">Java</a> and <a href="CSharp.html#CSharp_directors">C#</a>.
</p>
<H2><a name="D_other_features"></a>21.8 Other features</H2>
<H3><a name="D_nspace"></a>21.8.1 Extended namespace support (<tt>nspace</tt>)</H3>
<p>By default, SWIG flattens all C++ namespaces into a single target language namespace, but as for Java and C#, the <a href="SWIGPlus.html#SWIGPlus_nspace"><tt>nspace</tt></a> feature is supported for D. If it is active, C++ namespaces are mapped to D packages/modules. Note, however, that like for the other languages, <em>free</em> variables and functions are not supported yet; currently, they are all allows written to the main proxy D module.</p>
<H3><a name="D_native_pointer_support"></a>21.8.2 Native pointer support</H3>
<p>Contrary to many of the scripting languages supported by SWIG, D fully supports C-style pointers. The D module thus includes a custom mechanism to wrap C pointers directly as D pointers where applicable, that is, if the type that is pointed to is represented the same in C and D (on the bit-level), dubbed a <em>primitive type</em> below.</p>
<p>Central to this custom pointer handling scheme are two typemap attributes: the <tt>cprimitive</tt> attribute on the <tt>dtype</tt> typemap and the <tt>nativepointer</tt> attribute on all the typemaps which influence the D side of the code (<tt>dtype</tt>, <tt>din</tt>, <tt>dout</tt>, ...). When a D typemap is looked up, the following happens behind the scenes:</p>
<p>First, the matching typemap is determined by the usual typemap lookup rules. Then, it is checked if the result has the <tt>nativepointer</tt> attribute set. If it is present, it means that its value should replace the typemap value <em>if and only if</em> the actual type the typemap is looked up for is a primitive type, a pointer to a primitive type (through an arbitrary level of indirections), or a function pointer with only primitive types in its signature.</p>
<p>To determine if a type should be considered primitive, the <tt>cprimitive</tt> attribute on its <tt>dtype</tt> attribute is used. For example, the <tt>dtype</tt> typemap for <tt>float</tt> has <tt>cprimitive="1"</tt>, so the code from the <tt>nativepointer</tt> attribute is taken into account e.g. for <tt>float **</tt> or the function pointer <tt>float (*)(float *)</tt>.</p>
<H3><a name="D_operator_overloading"></a>21.8.3 Operator overloading</H3>
<p>The D module comes with basic operator overloading support for both D1 and D2. There are, however, a few limitations arising from conceptual differences between C++ and D:</p>
<p>The first key difference is that C++ supports free functions as operators (along with argument-dependent lookup), while D requires operators to be member functions of the class they are operating on. SWIG can only automatically generate wrapping code for member function operators; if you want to use operators defined as free functions in D, you need to handle them manually.</p>
<p>Another set of differences between C++ and D concerns individual operators. For example, there are quite a few operators which are overloadable in C++, but not in D, for example <tt>&amp;&amp;</tt> and <tt>||</tt>, but also <tt>!</tt>, and prefix increment/decrement operators in <a href="http://www.digitalmars.com/d/1.0/operatoroverloading.html">D1</a> resp. their postfix pendants in <a href="http://www.digitalmars.com/d/2.0/operatoroverloading.html">D2</a>.</p>
<p>There are also some cases where the operators can be translated to D, but the differences in the implementation details are big enough that a rather involved scheme would be required for automatic wrapping them, which has not been implemented yet. This affects, for example, the array subscript operator, <tt>[]</tt>, in combination with assignments - while <tt>operator []</tt> in C++ simply returns a reference which is then written to, D resorts to a separate <tt>opIndexAssign</tt> method -, or implicit casting (which was introduced in D2 via <tt>alias this</tt>). Despite the lack of automatic support, manually handling these cases should be perfectly possible.</p>
<H3><a name="D_test_suite"></a>21.8.4 Running the test-suite</H3>
<p>As with any other language, the SWIG test-suite can be built for D using the <tt>*-d-test-suite</tt> targets of the top-level Makefile. By default, D1 is targeted, to build it with D2, use the optional <tt>D_VERSION</tt> variable, e.g. <tt>make check-d-test-suite D_VERSION=2</tt>.</p>
<p>Note: If you want to use GDC on Linux or another platform which requires you to link <tt>libdl</tt> for dynamically loading the shared library, you might have to add <tt>-ldl</tt> manually to the <tt>d_compile</tt> target in <tt>Examples/Makefile</tt>, because GDC does not currently honor the <tt>pragma(lib,...)</tt> statement.</p>
<H2><a name="D_typemap_examples"></a>21.9 D Typemap examples</H2>
<p>There are no D-specific typemap examples yet. However, with the above <a href="D.html#D_typemap_name_comparison">name comparison table</a>, you should be able to get an idea what can be done by looking at the <a href="CSharp.html#CSharp_typemap_examples">corresponding C# section</a>.</p>
<H2><a name="D_planned_features"></a>21.10 Work in progress and planned features</H2>
<p>There are a couple of features which are not implemented yet, but would be very useful and might be added in the near future:</p>
<ul>
<li><em>Static linking:</em> Currently, the C wrapper code is compiled into a dynamic library, out of which the symbol addresses are looked up at runtime by the D part. If statically linking the different languages into one binary was supported, a tool-chain capable of performing IPO at link time could inline the wrapping code, effectively reducing the overhead for simple calls to zero.</li>
<li><em>C array handling:</em> Many data structures in some C/C++ libraries contain array containing of a pointer to the first element and the element count. Currently, one must manually writing wrapper code to be able to access these from D. It should be possible to add a set of SWIG macros to semi-automatically generate conversion code.</li>
</ul>
<p>Some generated code might also be a bit rough around the edges, particularly in the following areas:</p>
<ul>
<li><em>Memory management:</em> Although the currently generated wrapper code works fine with regard to the GC for the test-suite, there might be issues coming up in real-world multi-threaded usage.</li>
<li><em>D2 support</em>: Originally, the module has been developed for the use with D1, D2/Phobos support has been added in later. The basic features should work equally well for both, but there <em>could</em> be issues concerning const-correctness etc.</li>
</ul>
</body>
</html>

517
Doc/Manual/Extending.html
View file

File diff suppressed because it is too large Load diff

635
Doc/Manual/Go.html Normal file
View file

@ -0,0 +1,635 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>SWIG and Go</title>
<link rel="stylesheet" type="text/css" href="style.css">
</head>
<body bgcolor="#FFFFFF">
<H1><a name="Go"></a>22 SWIG and Go</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="#Go_overview">Overview</a>
<li><a href="#Go_running_swig">Running SWIG with Go</a>
<ul>
<li><a href="#Go_commandline">Additional Commandline Options</a>
<li><a href="#Go_outputs">Go Output Files</a>
</ul>
<li><a href="#Go_basic_tour">A tour of basic C/C++ wrapping</a>
<ul>
<li><a href="#Go_package">Go Package Name</a>
<li><a href="#Go_names">Go Names</a>
<li><a href="#Go_constants">Go Constants</a>
<li><a href="#Go_enumerations">Go Enumerations</a>
<li><a href="#Go_classes">Go Classes</a>
<ul>
<li><a href="#Go_class_inheritance">Go Class Inheritance</a>
</ul>
<li><a href="#Go_templates">Go Templates</a>
<li><a href="#Go_director_classes">Go Director Classes</a>
<li><a href="#Go_primitive_type_mappings">Default Go primitive type mappings</a>
<li><a href="#Go_output_arguments">Output arguments</a>
<li><a href="#Go_adding_additional_code">Adding additional go code</a>
</ul>
</ul>
</div>
<!-- INDEX -->
<p>
This chapter describes SWIG's support of Go. For more information on
the Go programming language
see <a href="http://golang.org/">golang.org</a>.
</p>
<H2><a name="Go_overview"></a>22.1 Overview</H2>
<p>
Go is a compiled language, not a scripting language. However, it does
not support direct calling of functions written in C/C++. The cgo
program may be used to generate wrappers to call C code from Go, but
there is no convenient way to call C++ code. SWIG fills this gap.
</p>
<p>
There are (at least) two different Go compilers. One is the gc
compiler, normally invoked under the names 6g, 8g, or 5g. The other
is the gccgo compiler, which is a frontend to the gcc compiler suite.
The interface to C/C++ code is completely different for the two Go
compilers. SWIG supports both, selected by a command line option.
</p>
<p>
Because Go is a type-safe compiled language, SWIG's runtime type
checking and runtime library are not used with Go. This should be
borne in mind when reading the rest of the SWIG documentation.
</p>
<H2><a name="Go_running_swig"></a>22.2 Running SWIG with Go</H2>
<p>
To generate Go code, use the <tt>-go</tt> option with SWIG. By
default SWIG will generate code for the gc compilers. To generate
code for gccgo, you should also use the <tt>-gccgo</tt> option.
</p>
<H3><a name="Go_commandline"></a>22.2.1 Additional Commandline Options</H3>
<p>
These are the command line options for SWIG's GO module. They can
also be seen by using:
</p>
<div class="code"><pre>
swig -go -help
</pre></div>
<table summary="Go specific options">
<tr>
<th>Go specific options</th>
</tr>
<tr>
<td>-gccgo</td>
<td>Generate code for gccgo. The default is to generate code for
6g/8g/5g.</td>
</tr>
<tr>
<td>-gccgo-46</td>
<td>Generate code for gccgo 4.6. The default is set by the configure
script. This generates code that does not use some facilities
that are only available in gccgo 4.7 and later.</td>
</tr>
<tr>
<td>-no-gccgo-46</td>
<td>Turn off <code>-gccgo-46</code>, whether set by default or earlier
on the command line.
</tr>
<tr>
<td>-package &lt;name&gt;</td>
<td>Set the name of the Go package to &lt;name&gt;. The default
package name is the SWIG module name.</td>
</tr>
<tr>
<td>-soname %lt;name%gt;</td>
<td>Set the runtime name of the shared library that the dynamic linker
should include at runtime. The default is the package name with
".so" appended. This is only used when generating code for
6g/8g/5g; when using gccgo, the equivalent name will be taken from
the <code>-soname</code> option passed to the linker.</td>
</tr>
<tr>
<td>-go-prefix &lt;prefix&gt;</td>
<td>When generating code for gccgo, set the prefix to use. This
corresponds to the <tt>-fgo-prefix</tt> option to gccgo.</td>
</tr>
<tr>
<td>-long-type-size &lt;s&gt;</td>
<td>Set the size for the C/C++ type <tt>long</tt>. This controls
whether <tt>long</tt> is converted to the Go type <tt>int32</tt>
or <tt>int64</tt>. The &lt;s&gt; argument should be 32 or 64.</td>
</tr>
</table>
<H3><a name="Go_outputs"></a>22.2.2 Go Output Files</H3>
<p> When generating Go code, SWIG will generate the following
files:</p>
<ul>
<li>
MODULE.go will contain the Go functions that your Go code will call.
These functions will be wrappers for the C++ functions defined by your
module. This file should, of course, be compiled with the Go
compiler.
<li>
MODULE_wrap.c or MODULE_wrap.cxx will contain C/C++ functions will be
invoked by the Go wrapper code. This file should be compiled with the
usual C or C++ compiler and linked into a shared library.
<li>
MODULE_wrap.h will be generated if you use the directors feature. It
provides a definition of the generated C++ director classes. It is
generally not necessary to use this file, but in some special cases it
may be helpful to include it in your code, compiled with the usual C
or C++ compiler.
<li>
If using the gc compiler, MODULE_gc.c will contain C code which should
be compiled with the C compiler distributed as part of the gc compiler: 6c, 8c,
or 5c. It should then be combined with the compiled MODULE.go using
gopack. This file will not be generated when using gccgo.
</ul>
<p>
A typical command sequence would look like this:
</p>
<div class="code"><pre>
% swig -go example.i
% gcc -c -fpic example.c
% gcc -c -fpic example_wrap.c
% gcc -shared example.o example_wrap.o -o example.so
% 6g example.go
% 6c example_gc.c
% gopack grc example.a example.6 example_gc.6
% 6g main.go # your code, not generated by SWIG
% 6l main.6
</pre></div>
<H2><a name="Go_basic_tour"></a>22.3 A tour of basic C/C++ wrapping</H2>
<p>
By default, SWIG attempts to build a natural Go interface to your
C/C++ code. However, the languages are somewhat different, so some
modifications have to occur. This section briefly covers the
essential aspects of this wrapping.
</p>
<H3><a name="Go_package"></a>22.3.1 Go Package Name</H3>
<p>
All Go source code lives in a package. The name of this package will
default to the name of the module from SWIG's <tt>%module</tt>
directive. You may override this by using SWIG's <tt>-package</tt>
command line option.
</p>
<H3><a name="Go_names"></a>22.3.2 Go Names</H3>
<p>
In Go, a function is only visible outside the current package if the
first letter of the name is uppercase. This is quite different from
C/C++. Because of this, C/C++ names are modified when generating the
Go interface: the first letter is forced to be uppercase if it is not
already. This affects the names of functions, methods, variables,
constants, enums, and classes.
</p>
<p>
C/C++ variables are wrapped with setter and getter functions in Go.
First the first letter of the variable name will be forced to
uppercase, and then <tt>Get</tt> or <tt>Set</tt> will be prepended.
For example, if the C/C++ variable is called <tt>var</tt>, then SWIG
will define the functions <tt>GetVar</tt> and <tt>SetVar</tt>. If a
variable is declared as <tt>const</tt>, or if
SWIG's <a href="SWIG.html#SWIG_readonly_variables">
<tt>%immutable</tt> directive</a> is used for the variable, then only
the getter will be defined.
</p>
<p>
C++ classes will be discussed further below. Here we'll note that the
first letter of the class name will be forced to uppercase to give the
name of a type in Go. A constructor will be named <tt>New</tt>
followed by that name, and the destructor will be
named <tt>Delete</tt> followed by that name.
</p>
<H3><a name="Go_constants"></a>22.3.3 Go Constants</H3>
<p>
C/C++ constants created via <tt>#define</tt> or the <tt>%constant</tt>
directive become Go constants, declared with a <tt>const</tt>
declaration.
<H3><a name="Go_enumerations"></a>22.3.4 Go Enumerations</H3>
<p>
C/C++ enumeration types will cause SWIG to define an integer type with
the name of the enumeration (with first letter forced to uppercase as
usual). The values of the enumeration will become variables in Go;
code should avoid modifying those variables.
</p>
<H3><a name="Go_classes"></a>22.3.5 Go Classes</H3>
<p>
Go has interfaces, methods and inheritance, but it does not have
classes in the same sense as C++. This sections describes how SWIG
represents C++ classes represented in Go.
</p>
<p>
For a C++ class <tt>ClassName</tt>, SWIG will define two types in Go:
an underlying type, which will just hold a pointer to the C++ type,
and an interface type. The interface type will be
named <tt>ClassName</tt>. SWIG will define a
function <tt>NewClassName</tt> which will take any constructor
arguments and return a value of the interface
type <tt>ClassName</tt>. SWIG will also define a
destructor <tt>DeleteClassName</tt>.
</p>
<p>
SWIG will represent any methods of the C++ class as methods on the
underlying type, and also as methods of the interface type. Thus C++
methods may be invoked directly using the
usual <tt>val.MethodName</tt> syntax. Public members of the C++ class
will be given getter and setter functions defined as methods of the
class.
</p>
<p>
SWIG will represent static methods of C++ classes as ordinary Go
functions. SWIG will use names like <tt>ClassNameMethodName</tt>.
SWIG will give static members getter and setter functions with names
like <tt>GetClassName_VarName</tt>.
</p>
<p>
Given a value of the interface type, Go code can retrieve the pointer
to the C++ type by calling the <tt>Swigcptr</tt> method. This will
return a value of type <tt>SwigcptrClassName</tt>, which is just a
name for <tt>uintptr</tt>. A Go type conversion can be used to
convert this value to a different C++ type, but note that this
conversion will not be type checked and is essentially equivalent
to <tt>reinterpret_cast</tt>. This should only be used for very
special cases, such as where C++ would use a <tt>dynamic_cast</tt>.
</p>
<p>Note that C++ pointers to compound objects are represented in go as objects
themselves, not as go pointers. So, for example, if you wrap the following
function:</p>
<div class="code">
<pre>
class MyClass {
int MyMethod();
static MyClass *MyFactoryFunction();
};
</pre>
</div>
<p>You will get go code that looks like this:</p>
<div class="code">
<pre>
type MyClass interface {
Swigcptr() uintptr
SwigIsMyClass()
MyMethod() int
}
MyClassMyFactoryFunction() MyClass {
// swig magic here
}
</pre>
</div>
<p>Note that the factory function does not return a go pointer; it actually
returns a go interface. If the returned pointer can be null, you can check
for this by calling the Swigcptr() method.
</p>
<H4><a name="Go_class_inheritance"></a>22.3.5.1 Go Class Inheritance</H4>
<p>
C++ class inheritance is automatically represented in Go due to its
use of interfaces. The interface for a child class will be a superset
of the interface of its parent class. Thus a value of the child class
type in Go may be passed to a function which expects the parent class.
Doing the reverse will require an explicit type assertion, which will
be checked dynamically.
</p>
<H3><a name="Go_templates"></a>22.3.6 Go Templates</H3>
<p>
In order to use C++ templates in Go, you must tell SWIG to create
wrappers for a particular template instantation. To do this, use
the <tt>%template</tt> directive.
<H3><a name="Go_director_classes"></a>22.3.7 Go Director Classes</H3>
<p>
SWIG's director feature permits a Go type to act as the subclass of a
C++ class with virtual methods. This is complicated by the fact that
C++ and Go define inheritance differently. In Go, structs can inherit
methods via anonymous field embedding. However, when a method is
called for an embedded struct, if that method calls any other methods,
they are called for the embedded struct, not for the original type.
Therefore, SWIG must use Go interfaces to represent C++ inheritance.
</p>
<p>
In order to use the director feature in Go, you must define a type in
your Go code. You must then add methods for the type. Define a
method in Go for each C++ virtual function that you want to override.
You must then create a value of your new type, and pass a pointer to
it to the function <tt>NewDirectorClassName</tt>,
where <tt>ClassName</tt> is the name of the C++ class. That will
return a value of type <tt>ClassName</tt>.
</p>
<p>
For example:
</p>
<div class="code">
<pre>
type GoClass struct { }
func (p *GoClass) VirtualFunction() { }
func MakeClass() ClassName {
return NewDirectorClassName(&amp;GoClass{})
}
</pre>
</div>
<p>
Any call in C++ code to the virtual function will wind up calling the
method defined in Go. The Go code may of course call other methods on
itself, and those methods may be defined either in Go or in C++.
</p>
<H3><a name="Go_primitive_type_mappings"></a>22.3.8 Default Go primitive type mappings</H3>
<p>
The following table lists the default type mapping from C/C++ to Go.
This table will tell you which Go type to expect for a function which
uses a given C/C++ type.
</p>
<table BORDER summary="Go primitive type mappings">
<tr>
<td><b>C/C++ type</b></td>
<td><b>Go type</b></td>
</tr>
<tr>
<td>bool</td>
<td>bool</td>
</tr>
<tr>
<td>char</td>
<td>byte</td>
</tr>
<tr>
<td>signed char</td>
<td>int8</td>
</tr>
<tr>
<td>unsigned char</td>
<td>byte</td>
</tr>
<tr>
<td>short</td>
<td>int16</td>
</tr>
<tr>
<td>unsigned short</td>
<td>uint16</td>
</tr>
<tr>
<td>int</td>
<td>int</td>
</tr>
<tr>
<td>unsigned int</td>
<td>uint</td>
</tr>
<tr>
<td>long</td>
<td>int32 or int64, depending on <tt>-long-type-size</tt></td>
</tr>
<tr>
<td>unsigned long</td>
<td>uint32 or uint64, depending on <tt>-long-type-size</tt></td>
</tr>
<tr>
<td>long long</td>
<td>int64</td>
</tr>
<tr>
<td>unsigned long long</td>
<td>uint64</td>
</tr>
<tr>
<td>float</td>
<td>float32</td>
</tr>
<tr>
<td>double</td>
<td>float64</td>
</tr>
<tr>
<td>char *<br>char []</td>
<td>string</td>
</tr>
</table>
<p>
Note that SWIG wraps the C <tt>char</tt> type as a character. Pointers
and arrays of this type are wrapped as strings. The <tt>signed
char</tt> type can be used if you want to treat <tt>char</tt> as a
signed number rather than a character. Also note that all const
references to primitive types are treated as if they are passed by
value.
</p>
<p>
These type mappings are defined by the "gotype" typemap. You may change
that typemap, or add new values, to control how C/C++ types are mapped
into Go types.
</p>
<H3><a name="Go_output_arguments"></a>22.3.9 Output arguments</H3>
<p>Because of limitations in the way output arguments are processed in swig,
a function with output arguments will not have multiple return values.
Instead, you must pass a pointer into the C++ function to tell it where to
store the ouput value. In go, you supply a slice in the place of the output
argument.</p>
<p>For example, suppose you were trying to wrap the modf() function in the
C math library which splits x into integral and fractional parts (and
returns the integer part in one of its parameters):</p>
<div class="code">
<pre>
double modf(double x, double *ip);
</pre>
</div>
<p>You could wrap it with SWIG as follows:</p>
<div class="code">
<pre>
%include &lt;typemaps.i&gt;
double modf(double x, double *OUTPUT);
</pre>
</div>
<p>or you can use the <code>%apply</code> directive:</p>
<div class="code">
<pre>
%include &lt;typemaps.i&gt;
%apply double *OUTPUT { double *ip };
double modf(double x, double *ip);
</pre>
</div>
<p>In Go you would use it like this:</p>
<div class="code">
<pre>
ptr := []float64{0.0}
fraction := modulename.Modf(5.0, ptr)
</pre>
</div>
<p>Since this is ugly, you may want to wrap the swig-generated API with
some <a href="#Embedded_go_code">additional functions written in go</a> that
hide the ugly details.</p>
<p>There are no <code>char&nbsp;*OUTPUT</code> typemaps. However you can
apply the <code>signed&nbsp;char&nbsp;*</code> typemaps instead:</p>
<div class="code">
<pre>
%include &lt;typemaps.i&gt;
%apply signed char *OUTPUT {char *output};
void f(char *output);
</pre>
</div>
<H3><a name="Go_adding_additional_code"></a>22.3.10 Adding additional go code</H3>
<p>Often the APIs generated by swig are not very natural in go, especially if
there are output arguments. You can
insert additional go wrapping code to add new APIs
with <code>%insert(go_wrapper)</code>, like this:</p>
<div class="code">
<pre>
%include &lt;typemaps.i&gt;
// Change name of what swig generates to Wrapped_modf. This function will
// have the following signature in go:
// func Wrapped_modf(float64, []float64) float64
%rename(wrapped_modf) modf(double x, double *ip);
%apply double *OUTPUT { double *ip };
double modf(double x, double *ip);
%insert(go_wrapper) %{
// The improved go interface to this function, which has two return values,
// in the more natural go idiom:
func Modf(x float64) (fracPart float64, intPart float64) {
ip := []float64{0.0}
fracPart = Wrapped_modf(x, ip)
intPart = ip[0]
return
}
%}
</pre>
</div>
<p>For classes, since swig generates an interface, you can add additional
methods by defining another interface that includes the swig-generated
interface. For example,</p>
<div class="code">
<pre>
%rename(Wrapped_MyClass) MyClass;
%rename(Wrapped_GetAValue) MyClass::GetAValue(int *x);
%apply int *OUTPUT { int *x };
class MyClass {
public:
MyClass();
int AFineMethod(const char *arg); // Swig's wrapping is fine for this one.
bool GetAValue(int *x);
};
%insert(go_wrapper) %{
type MyClass interface {
Wrapped_MyClass
GetAValue() (int, bool)
}
func (arg SwigcptrWrapped_MyClass) GetAValue() (int, bool) {
ip := []int{0}
ok := arg.Wrapped_GetAValue(ip)
return ip[0], ok
}
%}
</pre>
</div>
<p>Of course, if you have to rewrite most of the methods, instead of just a
few, then you might as well define your own struct that includes the
swig-wrapped object, instead of adding methods to the swig-generated object.</p>
<p>This only works if your wrappers do not need to import other go modules.
There is at present no way to insert import statements in the correct place
in swig-generated go. If you need to do that, you must put your go code
in a separate file.</p>
</body>
</html>

56
Doc/Manual/Guile.html
View file

@ -8,7 +8,7 @@
<body bgcolor="#ffffff">
<H1><a name="Guile"></a>19 SWIG and Guile</H1>
<H1><a name="Guile"></a>23 SWIG and Guile</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -47,7 +47,7 @@
<p>
This section details guile-specific support in SWIG.
<H2><a name="Guile_nn2"></a>19.1 Meaning of "Module"</H2>
<H2><a name="Guile_nn2"></a>23.1 Meaning of "Module"</H2>
<p>
@ -55,7 +55,7 @@ There are three different concepts of "module" involved, defined
separately for SWIG, Guile, and Libtool. To avoid horrible confusion,
we explicitly prefix the context, e.g., "guile-module".
<H2><a name="Guile_nn3"></a>19.2 Using the SCM or GH Guile API</H2>
<H2><a name="Guile_nn3"></a>23.2 Using the SCM or GH Guile API</H2>
<p>The guile module can currently export wrapper files that use the guile GH interface or the
@ -69,7 +69,7 @@ SCM interface is the default. The SCM and GH interface differ greatly in how th
pointers and have completely different run-time code. See below for more info.
<p>The GH interface to guile is deprecated. Read more about why in the
<a href="http://www.gnu.org/software/guile/docs/guile-ref/GH-deprecation.html">Guile manual</a>.
<a href="http://www.gnu.org/software/guile/docs/docs-1.6/guile-ref/GH.html#GH">Guile manual</a>.
The idea of the GH interface was to provide a high level API that other languages and projects
could adopt. This was a good idea, but didn't pan out well for general development. But for the
specific, minimal uses that the SWIG typemaps put the GH interface to use is ideal for
@ -103,7 +103,7 @@ for the specific API. Currently only the guile language module has created a ma
but there is no reason other languages (like mzscheme or chicken) couldn't also use this.
If that happens, there is A LOT less code duplication in the standard typemaps.</p>
<H2><a name="Guile_nn4"></a>19.3 Linkage</H2>
<H2><a name="Guile_nn4"></a>23.3 Linkage</H2>
<p>
@ -111,7 +111,7 @@ Guile support is complicated by a lack of user community cohesiveness,
which manifests in multiple shared-library usage conventions. A set of
policies implementing a usage convention is called a <b>linkage</b>.
<H3><a name="Guile_nn5"></a>19.3.1 Simple Linkage</H3>
<H3><a name="Guile_nn5"></a>23.3.1 Simple Linkage</H3>
<p>
@ -206,7 +206,7 @@ placed between the <code>define-module</code> form and the
<code>SWIG_init</code> via a preprocessor define to avoid symbol
clashes. For this case, however, passive linkage is available.
<H3><a name="Guile_nn6"></a>19.3.2 Passive Linkage</H3>
<H3><a name="Guile_nn6"></a>23.3.2 Passive Linkage</H3>
<p>Passive linkage is just like simple linkage, but it generates an
@ -216,7 +216,7 @@ package name (see below).
<p>You should use passive linkage rather than simple linkage when you
are using multiple modules.
<H3><a name="Guile_nn7"></a>19.3.3 Native Guile Module Linkage</H3>
<H3><a name="Guile_nn7"></a>23.3.3 Native Guile Module Linkage</H3>
<p>SWIG can also generate wrapper code that does all the Guile module
@ -257,7 +257,7 @@ Newer Guile versions have a shorthand procedure for this:
</div>
</ul>
<H3><a name="Guile_nn8"></a>19.3.4 Old Auto-Loading Guile Module Linkage</H3>
<H3><a name="Guile_nn8"></a>23.3.4 Old Auto-Loading Guile Module Linkage</H3>
<p>Guile used to support an autoloading facility for object-code
@ -283,7 +283,7 @@ option, SWIG generates an exported module initialization function with
an appropriate name.
<H3><a name="Guile_nn9"></a>19.3.5 Hobbit4D Linkage</H3>
<H3><a name="Guile_nn9"></a>23.3.5 Hobbit4D Linkage</H3>
<p>
@ -308,7 +308,7 @@ my/lib/libfoo.so.X.Y.Z and friends. This scheme is still very
experimental; the (hobbit4d link) conventions are not well understood.
</p>
<H2><a name="Guile_nn10"></a>19.4 Underscore Folding</H2>
<H2><a name="Guile_nn10"></a>23.4 Underscore Folding</H2>
<p>
@ -320,7 +320,7 @@ complained so far.
<code>%rename</code> to specify the Guile name of the wrapped
functions and variables (see CHANGES).
<H2><a name="Guile_nn11"></a>19.5 Typemaps</H2>
<H2><a name="Guile_nn11"></a>23.5 Typemaps</H2>
<p>
@ -409,10 +409,10 @@ See also the "multivalue" example.
%feature("constasvar") can be applied to any constant, immutable variable, or enum.
Instead of exporting the constant as a function that must be called, the
constant will appear as a scheme variable. See
<a href="Customization.html#features">Features and the %feature directive</a>
<a href="Customization.html#Customization_features">Features and the %feature directive</a>
for info on how to apply the %feature.</p>
<H2><a name="Guile_nn12"></a>19.6 Representation of pointers as smobs</H2>
<H2><a name="Guile_nn12"></a>23.6 Representation of pointers as smobs</H2>
<p>
@ -429,11 +429,11 @@ upper half of the CAR is read from this struct.
To get the pointer represented by a smob, the wrapper code calls the
function <code>SWIG_ConvertPtr()</code>, passing a pointer to a struct
representing the expected pointer type. See also
<a href="Typemaps.html#runtime_type_checker">The run-time type checker</a>.
<a href="Typemaps.html#Typemaps_runtime_type_checker">The run-time type checker</a>.
If the Scheme object passed was not a SWIG smob representing a compatible
pointer, a <code>wrong-type-arg</code> exception is raised.
<H3><a name="Guile_nn13"></a>19.6.1 GH Smobs</H3>
<H3><a name="Guile_nn13"></a>23.6.1 GH Smobs</H3>
<p>
@ -462,7 +462,7 @@ that created them, so the first module we check will most likely be correct.
Once we have a swig_type_info structure, we loop through the linked list of
casts, using pointer comparisons.</p>
<H3><a name="Guile_nn14"></a>19.6.2 SCM Smobs</H3>
<H3><a name="Guile_nn14"></a>23.6.2 SCM Smobs</H3>
<p>The SCM interface (using the "-scm" argument to swig) uses swigrun.swg.
@ -477,7 +477,7 @@ in the smob tag. If a generated GOOPS module has been loaded, smobs will be wra
GOOPS class.</p>
<H3><a name="Guile_nn15"></a>19.6.3 Garbage Collection</H3>
<H3><a name="Guile_nn15"></a>23.6.3 Garbage Collection</H3>
<p>Garbage collection is a feature of the new SCM interface, and it is automatically included
@ -487,11 +487,11 @@ to the destructor for this type. The destructor is the generated wrapper around
So swig still exports a wrapper for the destructor, it just does not call scm_c_define_gsubr() for
the wrapped delete function. So the only way to delete an object is from the garbage collector, since the
delete function is not available to scripts. How swig determines if a type should be garbage collected
is exactly like described in <a href="Customization.html#ownership">
is exactly like described in <a href="Customization.html#Customization_ownership">
Object ownership and %newobject</a> in the SWIG manual. All typemaps use an $owner var, and
the guile module replaces $owner with 0 or 1 depending on feature:new.</p>
<H2><a name="Guile_nn16"></a>19.7 Exception Handling</H2>
<H2><a name="Guile_nn16"></a>23.7 Exception Handling</H2>
<p>
@ -517,7 +517,7 @@ mapping:
The default when not specified here is to use "swig-error".
See Lib/exception.i for details.
<H2><a name="Guile_nn17"></a>19.8 Procedure documentation</H2>
<H2><a name="Guile_nn17"></a>23.8 Procedure documentation</H2>
<p>If invoked with the command-line option <code>-procdoc
@ -553,7 +553,7 @@ like this:
typemap argument <code>doc</code>. See <code>Lib/guile/typemaps.i</code> for
details.
<H2><a name="Guile_nn18"></a>19.9 Procedures with setters</H2>
<H2><a name="Guile_nn18"></a>23.9 Procedures with setters</H2>
<p>For global variables, SWIG creates a single wrapper procedure
@ -581,7 +581,7 @@ struct members, the procedures <code>(<var>struct</var>-<var>member</var>-get
pointer)</code> and <code>(<var>struct-member</var>-set pointer
value)</code> are <em>not</em> generated.
<H2><a name="Guile_nn19"></a>19.10 GOOPS Proxy Classes</H2>
<H2><a name="Guile_nn19"></a>23.10 GOOPS Proxy Classes</H2>
<p>SWIG can also generate classes and generic functions for use with
@ -730,7 +730,7 @@ Notice that &lt;Foo&gt; is used before it is defined. The fix is to just put th
<code>%import "foo.h"</code> before the <code>%inline</code> block.
</p>
<H3><a name="Guile_nn20"></a>19.10.1 Naming Issues</H3>
<H3><a name="Guile_nn20"></a>23.10.1 Naming Issues</H3>
<p>As you can see in the example above, there are potential naming conflicts. The default exported
@ -767,9 +767,7 @@ guile-modules. For example,</p>
(use-modules ((Test) #:renamer (symbol-prefix-proc 'goops:)))
</pre></div>
<p>TODO: Renaming class name prefixes?</p>
<H3><a name="Guile_nn21"></a>19.10.2 Linking</H3>
<H3><a name="Guile_nn21"></a>23.10.2 Linking</H3>
<p>The guile-modules generated above all need to be linked together. GOOPS support requires
@ -814,7 +812,7 @@ Produces the following code at the top of the generated GOOPS guile-module
<code>Module-primitive.scm</code> (with <i>primitive</i> replaced with whatever is given with the <code>-primsuffix</code>
argument. The code to load the <code>.so</code> library should be located in the <code>%scheme</code> directive,
which will then be added to the scmstub file.
Swig will automatically generate the line <code>(use-modules (<i>Package</i> <i>Module-primitive</i>))</code>
SWIG will automatically generate the line <code>(use-modules (<i>Package</i> <i>Module-primitive</i>))</code>
into the GOOPS guile-module. So if <i>Module-primitive.scm</i> is on the autoload path for guile, the
<code>%goops</code> directive can be empty. Otherwise, the <code>%goops</code> directive should contain
whatever code is needed to load the <i>Module-primitive.scm</i> file into guile.</p>
@ -848,7 +846,7 @@ Produces the following code at the top of the generated GOOPS guile-module
</li>
<li><p><b>Module Linkage</b>: This is very similar to passive linkage with a scmstub file.
Swig will also automatically generate the line <code>(use-modules
SWIG will also automatically generate the line <code>(use-modules
(<i>Package</i> <i>Module-primitive</i>))</code> into the GOOPS guile-module. Again the <code>%goops</code>
directive should contain whatever code is needed to get that module loaded into guile.</p>

32
Doc/Manual/Introduction.html
View file

@ -37,7 +37,7 @@
<p>
SWIG is a software development tool that simplifies the task of
interfacing different languages to C and C++ programs. In a
nutshell, SWIG is a compiler that takes C declarations and creates
nutshell, SWIG is a compiler that takes C/C++ declarations and creates
the wrappers needed to access those declarations from other languages including
including Perl, Python, Tcl, Ruby, Guile, and Java. SWIG normally
requires no modifications to existing code and can often be used to
@ -68,7 +68,8 @@ a dedicated IDL compiler). Although
this style of development isn't appropriate for every
project, it is particularly well suited to software development in the
small; especially the research and development work that is commonly found
in scientific and engineering projects.
in scientific and engineering projects. However, nowadays SWIG is known to be used in many
large open source and commercial projects.
<H2><a name="Introduction_nn3"></a>2.2 Why use SWIG?</H2>
@ -194,9 +195,9 @@ extern int my_mod(int n, int m);
<p>
The interface file contains ANSI C function prototypes and variable
declarations. The <tt>%module</tt> directive defines the name of the
module that will be created by SWIG. The <tt>%{,%}</tt> block
provides a location for inserting additional code such as C header
files or additional C declarations.
module that will be created by SWIG. The <tt>%{ %}</tt> block
provides a location for inserting additional code, such as C header
files or additional C declarations, into the generated C wrapper code.
<H3><a name="Introduction_nn6"></a>2.3.2 The swig command</H3>
@ -334,7 +335,7 @@ major features include:
<p>
Currently, the only major C++ feature not supported is nested classes--a limitation
that will be removed in a future release.
that should be removed in a future release, but has some workarounds for the moment.
</p>
<p>
@ -365,20 +366,20 @@ possible to support different types of interfaces depending on the application.
<p>
SWIG is a command line tool and as such can be incorporated into any build system that supports invoking external tools/compilers.
SWIG is most commonly invoked from within a Makefile, but is also known to be invoked from from popular IDEs such as
SWIG is most commonly invoked from within a Makefile, but is also known to be invoked from popular IDEs such as
Microsoft Visual Studio.
</p>
<p>
If you are using the GNU Autotools
(<a href="http://www.gnu.org/software/autoconf">Autoconf</a>/
<a href="http://www.gnu.org/software/automake">Automake</a>/
<a href="http://www.gnu.org/software/libtool">Libtool</a>)
(<a href="http://www.gnu.org/software/autoconf/">Autoconf</a>/
<a href="http://www.gnu.org/software/automake/">Automake</a>/
<a href="http://www.gnu.org/software/libtool/">Libtool</a>)
to configure SWIG use in your project, the SWIG Autoconf macros can be used.
The primary macro is <tt>ac_pkg_swig</tt>, see
<a href="http://www.gnu.org/software/ac-archive/htmldoc/ac_pkg_swig.html">http://www.gnu.org/software/ac-archive/htmldoc/ac_pkg_swig.html</a>.
The <tt>ac_python_devel</tt> macro is also helpful for generating Python extensions. See the
<a href="http://www.gnu.org/software/ac-archive/htmldoc/index.html">Autoconf Macro Archive</a>
The primary macro is <tt>ax_pkg_swig</tt>, see
<a href="http://www.gnu.org/software/autoconf-archive/ax_pkg_swig.html#ax_pkg_swig">http://www.gnu.org/software/autoconf-archive/ax_pkg_swig.html#ax_pkg_swig</a>.
The <tt>ax_python_devel</tt> macro is also helpful for generating Python extensions. See the
<a href="http://www.gnu.org/software/autoconf-archive/">Autoconf Archive</a>
for further information on this and other Autoconf macros.
</p>
@ -414,7 +415,8 @@ SWIG_LINK_LIBRARIES(example ${PYTHON_LIBRARIES})
</pre></div>
<p>
The above example will generate native build files such as makefiles, nmake files and Visual Studio projects
which will invoke SWIG and compile the generated C++ files into _example.so (UNIX) or _example.dll (Windows).
which will invoke SWIG and compile the generated C++ files into _example.so (UNIX) or _example.pyd (Windows).
For other target languages on Windows a dll, instead of a .pyd file, is usually generated.
</p>
<H2><a name="Introduction_nn12"></a>2.7 Hands off code generation</H2>

745
Doc/Manual/Java.html
View file

File diff suppressed because it is too large Load diff

212
Doc/Manual/Library.html
View file

@ -14,7 +14,7 @@
<li><a href="#Library_nn3">C Arrays and Pointers</a>
<ul>
<li><a href="#Library_nn4">cpointer.i</a>
<li><a href="#Library_nn5">carrays.i</a>
<li><a href="#Library_carrays">carrays.i</a>
<li><a href="#Library_nn6">cmalloc.i</a>
<li><a href="#Library_nn7">cdata.i</a>
</ul>
@ -27,9 +27,10 @@
</ul>
<li><a href="#Library_stl_cpp_library">STL/C++ Library</a>
<ul>
<li><a href="#Library_nn14">std_string.i</a>
<li><a href="#Library_nn15">std_vector.i</a>
<li><a href="#Library_std_string">std::string</a>
<li><a href="#Library_std_vector">std::vector</a>
<li><a href="#Library_stl_exceptions">STL exceptions</a>
<li><a href="#Library_std_shared_ptr">shared_ptr smart pointer</a>
</ul>
<li><a href="#Library_nn16">Utility Libraries</a>
<ul>
@ -316,7 +317,7 @@ In this example, the function <tt>int_to_uint()</tt> would be used to cast type
<b>Note:</b> When working with simple pointers, typemaps can often be used to provide more seamless operation.
</p>
<H3><a name="Library_nn5"></a>8.2.2 carrays.i</H3>
<H3><a name="Library_carrays"></a>8.2.2 carrays.i</H3>
<p>
@ -419,7 +420,9 @@ delete_doubleArray(a) # Destroy array
</div>
<p>
<b><tt>%array_class(type,name)</tt></b>
</p>
<div class="indent">
<p>
@ -665,7 +668,7 @@ in order for this to work.
</p>
<p>
<b><tt>char *cdata(void *ptr, int nbytes)</tt></b>
<b><tt>const char *cdata(void *ptr, size_t nbytes)</tt></b>
</p>
<div class="indent"><p>
@ -674,13 +677,17 @@ pointer.
</p></div>
<p>
<b><tt>void memmove(void *ptr, char *s)</tt></b>
<b><tt>void memmove(void *ptr, const char *s)</tt></b>
</p>
<div class="indent"><p>
Copies all of the string data in <tt>s</tt> into the memory pointed to by
<tt>ptr</tt>. The string may contain embedded NULL bytes. The length of
the string is implicitly determined in the underlying wrapper code.
<tt>ptr</tt>. The string may contain embedded NULL bytes.
This is actually a wrapper to the standard C library <tt>memmove</tt> function, which is
declared as
<b><tt>void memmove(void *ptr, const void *src, size_t n)</tt></b>.
The <tt>src</tt> and length <tt>n</tt> parameters are
extracted from the language specific string <tt>s</tt> in the underlying wrapper code.
</p></div>
<p>
@ -821,20 +828,20 @@ If you have a function that expects binary data,
<div class="code">
<pre>
int parity(char *str, int len, int initial);
size_t parity(char *str, size_t len, size_t initial);
</pre>
</div>
<p>
you can wrap the parameters <tt>(char *str, int len)</tt> as a single
you can wrap the parameters <tt>(char *str, size_t len)</tt> as a single
argument using a typemap. Just do this:
</p>
<div class="code">
<pre>
%apply (char *STRING, int LENGTH) { (char *str, int len) };
%apply (char *STRING, size_t LENGTH) { (char *str, size_t len) };
...
int parity(char *str, int len, int initial);
size_t parity(char *str, size_t len, size_t initial);
</pre>
</div>
@ -851,6 +858,7 @@ Now, in the target language, you can use binary string data like this:
<p>
In the wrapper function, the passed string will be expanded to a pointer and length parameter.
The <tt>(char *STRING, int LENGTH)</tt> multi-argument typemap is also available in addition to <tt>(char *STRING, size_t LENGTH)</tt>.
</p>
<H3><a name="Library_nn11"></a>8.3.3 Using %newobject to release memory</H3>
@ -888,7 +896,10 @@ char *foo();
</div>
<p>
This will release the result.
This will release the result if the appropriate target language support is available.
SWIG provides the appropriate "newfree" typemap for <tt>char *</tt> so that the memory is released,
however, you may need to provide your own "newfree" typemap for other types.
See <a href="Customization.html#Customization_ownership">Object ownership and %newobject</a> for more details.
</p>
<H3><a name="Library_nn12"></a>8.3.4 cstring.i</H3>
@ -1378,6 +1389,7 @@ The following table shows which C++ classes are supported and the equivalent SWI
<tr> <td>std::set</td> <td>set</td> <td>std_set.i</td> </tr>
<tr> <td>std::string</td> <td>string</td> <td>std_string.i</td> </tr>
<tr> <td>std::vector</td> <td>vector</td> <td>std_vector.i</td> </tr>
<tr> <td>std::shared_ptr</td> <td>shared_ptr</td> <td>std_shared_ptr.i</td> </tr>
</table>
@ -1387,7 +1399,7 @@ Please look for the library files in the appropriate language library directory.
</p>
<H3><a name="Library_nn14"></a>8.4.1 std_string.i</H3>
<H3><a name="Library_std_string"></a>8.4.1 std::string</H3>
<p>
@ -1471,16 +1483,11 @@ void foo(string s, const String &amp;t); // std_string typemaps still applie
</pre>
</div>
<p>
<b>Note:</b> The <tt>std_string</tt> library is incompatible with Perl on some platforms.
We're looking into it.
</p>
<H3><a name="Library_nn15"></a>8.4.2 std_vector.i</H3>
<H3><a name="Library_std_vector"></a>8.4.2 std::vector</H3>
<p>
The <tt>std_vector.i</tt> library provides support for the C++ <tt>vector</tt> class in the STL.
The <tt>std_vector.i</tt> library provides support for the C++ <tt>std::vector</tt> class in the STL.
Using this library involves the use of the <tt>%template</tt> directive. All you need to do is to
instantiate different versions of <tt>vector</tt> for the types that you want to use. For example:
</p>
@ -1655,11 +1662,6 @@ if you want to make their head explode.
details and the public API exposed to the interpreter vary.
</p>
<p>
<b>Note:</b> <tt>std_vector.i</tt> was written by Luigi "The Amazing" Ballabio.
</p>
<H3><a name="Library_stl_exceptions"></a>8.4.3 STL exceptions</H3>
@ -1710,6 +1712,164 @@ The <tt>%exception</tt> directive can be used by placing the following code befo
Any thrown STL exceptions will then be gracefully handled instead of causing a crash.
</p>
<H3><a name="Library_std_shared_ptr"></a>8.4.4 shared_ptr smart pointer</H3>
<p>
Some target languages have support for handling the widely used <tt>boost::shared_ptr</tt> smart pointer.
This smart pointer is also available as <tt>std::tr1::shared_ptr</tt> before it becomes fully standardized as <tt>std::shared_ptr</tt>.
The <tt>boost_shared_ptr.i</tt> library provides support for <tt>boost::shared_ptr</tt> and <tt>std_shared_ptr.i</tt> provides support for <tt>std::shared_ptr</tt>, but if the following macro is defined as shown, it can be used for <tt>std::tr1::shared_ptr</tt>:
</p>
<div class="code">
<pre>
#define SWIG_SHARED_PTR_SUBNAMESPACE tr1
%include &lt;std_shared_ptr.i&gt;
</pre>
</div>
<p>
You can only use one of these variants of shared_ptr in your interface file at a time.
and all three variants must be used in conjunction with the <tt>%shared_ptr(T)</tt> macro,
where <tt>T</tt> is the underlying pointer type equating to usage <tt>shared_ptr&lt;T&gt;</tt>.
The type <tt>T</tt> must be non-primitive.
A simple example demonstrates usage:
</p>
<div class="code">
<pre>
%module example
%include &lt;boost_shared_ptr.i&gt;
%shared_ptr(IntValue)
%inline %{
#include &lt;boost/shared_ptr.hpp&gt;
struct IntValue {
int value;
IntValue(int v) : value(v) {}
};
static int extractValue(const IntValue &amp;t) {
return t.value;
}
static int extractValueSmart(boost::shared_ptr&lt;IntValue&gt; t) {
return t-&gt;value;
}
%}
</pre>
</div>
<p>
Note that the <tt>%shared_ptr(IntValue)</tt> declaration occurs after the inclusion of the <tt>boost_shared_ptr.i</tt>
library which provides the macro and, very importantly, before any usage or declaration of the type, <tt>IntValue</tt>.
The <tt>%shared_ptr</tt> macro provides, a few things for handling this smart pointer, but mostly a number of
typemaps. These typemaps override the default typemaps so that the underlying proxy class is stored and passed around
as a pointer to a <tt>shared_ptr</tt> instead of a plain pointer to the underlying type.
This approach means that any instantiation of the type can be passed to methods taking the type by value, reference, pointer
or as a smart pointer.
The interested reader might want to look at the generated code, however, usage is simple and no different
handling is required from the target language.
For example, a simple use case of the above code from Java would be:
</p>
<div class="targetlang">
<pre>
IntValue iv = new IntValue(1234);
int val1 = example.extractValue(iv);
int val2 = example.extractValueSmart(iv);
System.out.println(val1 + " " + val2);
</pre>
</div>
<p>
This shared_ptr library works quite differently to SWIG's normal, but somewhat limited,
<a href="SWIGPlus.html#SWIGPlus_smart_pointers">smart pointer handling</a>.
The shared_ptr library does not generate extra wrappers, just for smart pointer handling, in addition to the proxy class.
The normal proxy class including inheritance relationships is generated as usual.
The only real change introduced by the <tt>%shared_ptr</tt> macro is that the proxy class stores a pointer to the shared_ptr instance instead of a raw pointer to the instance.
A proxy class derived from a base which is being wrapped with shared_ptr can and <b>must</b> be wrapped as a shared_ptr too.
In other words all classes in an inheritance hierarchy must all be used with the <tt>%shared_ptr</tt> macro.
For example the following code can be used with the base class shown earlier:
</p>
<div class="code">
<pre>
%shared_ptr(DerivedIntValue)
%inline %{
struct DerivedIntValue : IntValue {
DerivedIntValue(int value) : IntValue(value) {}
...
};
%}
</pre>
</div>
<p>
A shared_ptr of the derived class can now be passed to a method where the base is expected in the target language, just as it can in C++:
</p>
<div class="targetlang">
<pre>
DerivedIntValue div = new DerivedIntValue(5678);
int val3 = example.extractValue(div);
int val4 = example.extractValueSmart(div);
</pre>
</div>
<p>
If the <tt>%shared_ptr</tt> macro is omitted for any class in the inheritance hierarchy, SWIG will warn about this and the generated code may or may not result in a C++ compilation error.
For example, the following input:
</p>
<div class="code">
<pre>
%include "boost_shared_ptr.i"
%shared_ptr(Parent);
%inline %{
#include &lt;boost/shared_ptr.hpp&gt;
struct GrandParent {
virtual ~GrandParent() {}
};
struct Parent : GrandParent {
virtual ~Parent() {}
};
struct Child : Parent {
virtual ~Child() {}
};
%}
</pre>
</div>
<p>
warns about the missing smart pointer information:
</p>
<div class="shell">
<pre>
example.i:12: Warning 520: Base class 'GrandParent' of 'Parent' is not similarly marked as a smart pointer.
example.i:16: Warning 520: Derived class 'Child' of 'Parent' is not similarly marked as a smart pointer.
</pre>
</div>
<p>
Adding the missing <tt>%shared_ptr</tt> macros will fix this:
</p>
<div class="code">
<pre>
%include "boost_shared_ptr.i"
%shared_ptr(GrandParent);
%shared_ptr(Parent);
%shared_ptr(Child);
... as before ...
</pre>
</div>
<H2><a name="Library_nn16"></a>8.5 Utility Libraries</H2>

34
Doc/Manual/Lisp.html
View file

@ -6,7 +6,7 @@
</head>
<body bgcolor="#ffffff">
<H1><a name="Lisp_nn1"></a>21 SWIG and Common Lisp</H1>
<H1><a name="Lisp"></a>25 SWIG and Common Lisp</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -41,16 +41,16 @@
Lisp, Common Foreign Function Interface(CFFI), CLisp and UFFI
foreign function interfaces.
</p>
<H2><a name="Lisp_nn2"></a>21.1 Allegro Common Lisp</H2>
<H2><a name="Lisp_nn2"></a>25.1 Allegro Common Lisp</H2>
<p>
Allegro Common Lisp support in SWIG has been updated to include
support for both C and C++. You can read about the interface
<a href="Allegrocl.html#Allegrocl_nn1">here</a>
<a href="Allegrocl.html#Allegrocl">here</a>
</p>
<H2><a name="Lisp_nn3"></a>21.2 Common Foreign Function Interface(CFFI)</H2>
<H2><a name="Lisp_nn3"></a>25.2 Common Foreign Function Interface(CFFI)</H2>
<p>
@ -77,7 +77,7 @@ swig -cffi -module <i>module-name</i> <i>file-name</i>
files and the various things which you can do with them.
</p>
<H3><a name="Lisp_nn4"></a>21.2.1 Additional Commandline Options </H3>
<H3><a name="Lisp_nn4"></a>25.2.1 Additional Commandline Options </H3>
<p>
@ -96,14 +96,14 @@ swig -cffi -help
<tr>
<td>-generate-typedef</td>
<td>If this option is given then defctype will be used to generate<br\>
<td>If this option is given then defctype will be used to generate<br/>
shortcuts according to the typedefs in the input.
</td>
</tr>
<tr>
<td>-[no]cwrap</td>
<td>Turn on or turn off generation of an intermediate C file when<br\>
<td>Turn on or turn off generation of an intermediate C file when<br/>
creating a C interface. By default this is only done for C++ code.
</td>
</tr>
@ -118,7 +118,7 @@ swig -cffi -help
</table>
<H3><a name="Lisp_nn5"></a>21.2.2 Generating CFFI bindings</H3>
<H3><a name="Lisp_nn5"></a>25.2.2 Generating CFFI bindings</H3>
As we mentioned earlier the ideal way to use SWIG is to use interface
@ -269,7 +269,7 @@ The generated SWIG Code will be:
want to lispify the names, also, before we forget you want to
export the generated lisp names. To do this, we will use the
SWIG <a
href="Customization.html#features">feature directive</a>.
href="Customization.html#Customization_features">feature directive</a>.
Let's edit the interface file such that the C type "div_t*" is changed
to Lisp type ":my-pointer", we lispify all names,
export everything, and do some more stuff.
@ -392,7 +392,7 @@ The feature <i>intern_function</i> ensures that all C names are
</pre></div>
<H3><a name="Lisp_nn6"></a>21.2.3 Generating CFFI bindings for C++ code</H3>
<H3><a name="Lisp_nn6"></a>25.2.3 Generating CFFI bindings for C++ code</H3>
<p>This feature to SWIG (for CFFI) is very new and still far from
@ -568,7 +568,7 @@ If you have any questions, suggestions, patches, etc., related to CFFI
module feel free to contact us on the SWIG mailing list, and
also please add a "[CFFI]" tag in the subject line.
<H3><a name="Lisp_nn7"></a>21.2.4 Inserting user code into generated files</H3>
<H3><a name="Lisp_nn7"></a>25.2.4 Inserting user code into generated files</H3>
<p>
@ -583,7 +583,7 @@ using the SWIG <tt>%insert(section) %{ ...code... %}</tt> directive:
<pre>
%module example
%insert("runtime") %{
%{
#include "header.h"
%}
@ -604,11 +604,11 @@ generated lisp interface file:
</ul>
<p>
Note that the block <tt>%{ ... %}</tt> is effectively a shortcut for
<tt>%insert("runtime") %{ ... %}</tt>.
<tt>%insert("header") %{ ... %}</tt>.
</p>
<H2><a name="Lisp_nn8"></a>21.3 CLISP</H2>
<H2><a name="Lisp_nn8"></a>25.3 CLISP</H2>
<p>
@ -638,7 +638,7 @@ swig -clisp -module <i>module-name</i> <i>file-name</i>
interface file for the CLISP module. The CLISP module tries to
produce code which is both human readable and easily modifyable.
</p>
<H3><a name="Lisp_nn9"></a>21.3.1 Additional Commandline Options </H3>
<H3><a name="Lisp_nn9"></a>25.3.1 Additional Commandline Options </H3>
<p>
@ -671,7 +671,7 @@ and global variables will be created otherwise only definitions for<br/>
</table>
<H3><a name="Lisp_nn10"></a>21.3.2 Details on CLISP bindings</H3>
<H3><a name="Lisp_nn10"></a>25.3.2 Details on CLISP bindings</H3>
<p>
@ -795,7 +795,7 @@ struct bar {
</pre></div>
<H2><a name="Lisp_nn11"></a>21.4 UFFI </H2>
<H2><a name="Lisp_nn11"></a>25.4 UFFI </H2>
</body>

621
Doc/Manual/Lua.html
View file

File diff suppressed because it is too large Load diff

39
Doc/Manual/Makefile
View file

@ -9,55 +9,70 @@
# validation.
#
# Additional html validation can be done using the validate target.
# Additional link checking can be done using the linkchecker target.
#
# Note the # and " are escaped
HTMLDOC_OPTIONS = "--book --toclevels 4 --no-numbered --toctitle \"Table of Contents\" --title --titleimage swig16.png --linkcolor \#0000ff --linkstyle underline --size Universal --left 0.50in --right 0.50in --top 0.50in --bottom 0.50in --header .t. --footer h.1 --nup 1 --tocheader .t. --tocfooter ..i --portrait --color --no-pscommands --no-xrxcomments --compression=1 --jpeg=0 --fontsize 10.0 --fontspacing 1.2 --headingfont Helvetica --bodyfont Times --headfootsize 10.0 --headfootfont Helvetica --charset iso-8859-1 --links --no-embedfonts --pagemode outline --pagelayout single --firstpage c1 --pageeffect none --pageduration 10 --effectduration 1.0 --no-encryption --permissions all --owner-password \"\" --user-password \"\" --browserwidth 680"
.PHONY: maketoc check generate all clean validate test
.PHONY: maketoc check generate all maintainer-clean validate test
all: maketoc check generate
maketoc:
maketoc: CCache.html
python maketoc.py
CCache.html: ../../CCache/ccache.yo
yodl2html -o CCache.html ../../CCache/ccache.yo
# Use htmltidy to warn about some HTML errors. Note that it is not used to clean/tidy the HTML,
# it is just used as a primitive HTML checker.
# CCache.html is generated by yodl2html and has a few insignificant problems, so we don't put it through tidy
check:
tidy -errors --gnu-emacs yes -quiet index.html
tidy -errors --gnu-emacs yes -quiet Sections.html
all=`sed '/^#/d' chapters`; for a in $$all; do tidy -errors --gnu-emacs yes -quiet $$a; done;
tidy -errors --gnu-emacs yes -quiet index.html
tidy -errors --gnu-emacs yes -quiet Sections.html
all=`sed '/^#/d' chapters | grep -v CCache.html`; for a in $$all; do tidy -errors --gnu-emacs yes -quiet $$a; done;
generate: swightml.book swigpdf.book
htmldoc --batch swightml.book || true
htmldoc --batch swigpdf.book || true
python fixstyle.py SWIGDocumentation.html
swigpdf.book:
swigpdf.book: chapters Sections.html
echo "#HTMLDOC 1.8.24" > swigpdf.book
echo -t pdf13 -f SWIGDocumentation.pdf $(HTMLDOC_OPTIONS) --stylesheet style.css >> swigpdf.book
echo "Sections.html" >> swigpdf.book
cat chapters >> swigpdf.book
swightml.book:
swightml.book: chapters Sections.html
echo "#HTMLDOC 1.8.24" > swightml.book
echo -t html -f SWIGDocumentation.html $(HTMLDOC_OPTIONS) >> swightml.book
echo "Sections.html" >> swightml.book
cat chapters >> swightml.book
clean:
maintainer-clean: clean-baks
rm -f swightml.book
rm -f swigpdf.book
rm -f CCache.html
rm -f SWIGDocumentation.html
rm -f SWIGDocumentation.pdf
clean-baks:
rm -f *.bak
test:
grep "href=\".*\.html\"" index.html
grep "href=\".*\.html\"" Sections.html
all=`sed '/^#/d' chapters`; for a in $$all; do grep -l "href=\".*\.html\"" $$a; done;
grep "href=\".*\.html\"" index.html
grep "href=\".*\.html\"" Sections.html
all=`sed '/^#/d' chapters`; for a in $$all; do grep -l "href=\".*\.html\"" $$a; done;
# Validating using the WDG offline validator - http://www.htmlhelp.com/tools/validator/offline/
validate:
all=`sed '/^#/d' chapters`; for a in $$all; do validate --emacs $$a; done;
all=`sed '/^#/d' chapters`; for a in $$all; do validate --emacs $$a; done;
# Link checking using linkchecker
linkchecker:
@echo -----------------------------------------------------------------------
@echo Note linkchecker versions prior to 6.1 do not work properly wrt anchors
@echo -----------------------------------------------------------------------
linkchecker --config=./linkchecker.config index.html

300
Doc/Manual/Modula3.html
View file

@ -5,42 +5,39 @@
<link rel="stylesheet" type="text/css" href="style.css">
</head>
<body bgcolor="#FFFFFF">
<H1><a name="Modula3"></a>23 SWIG and Modula-3</H1>
<H1><a name="Modula3"></a>27 SWIG and Modula-3</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="#modula3_overview">Overview</a>
<li><a href="#Modula3_modula3_overview">Overview</a>
<ul>
<li><a href="#whyscripting">Why not scripting ?</a>
<li><a href="#whymodula3">Why Modula-3 ?</a>
<li><a href="#whycpp">Why C / C++ ?</a>
<li><a href="#whyswig">Why SWIG ?</a>
<li><a href="#Modula3_motivation">Motivation</a>
</ul>
<li><a href="#conception">Conception</a>
<li><a href="#Modula3_conception">Conception</a>
<ul>
<li><a href="#cinterface">Interfaces to C libraries</a>
<li><a href="#cppinterface">Interfaces to C++ libraries</a>
<li><a href="#Modula3_cinterface">Interfaces to C libraries</a>
<li><a href="#Modula3_cppinterface">Interfaces to C++ libraries</a>
</ul>
<li><a href="#preliminaries">Preliminaries</a>
<li><a href="#Modula3_preliminaries">Preliminaries</a>
<ul>
<li><a href="#compilers">Compilers</a>
<li><a href="#commandline">Additional Commandline Options</a>
<li><a href="#Modula3_compilers">Compilers</a>
<li><a href="#Modula3_commandline">Additional Commandline Options</a>
</ul>
<li><a href="#modula3_typemaps">Modula-3 typemaps</a>
<li><a href="#Modula3_typemaps">Modula-3 typemaps</a>
<ul>
<li><a href="#inoutparam">Inputs and outputs</a>
<li><a href="#ordinals">Subranges, Enumerations, Sets</a>
<li><a href="#class">Objects</a>
<li><a href="#imports">Imports</a>
<li><a href="#exceptions">Exceptions</a>
<li><a href="#typemap_example">Example</a>
<li><a href="#Modula3_inoutparam">Inputs and outputs</a>
<li><a href="#Modula3_ordinals">Subranges, Enumerations, Sets</a>
<li><a href="#Modula3_class">Objects</a>
<li><a href="#Modula3_imports">Imports</a>
<li><a href="#Modula3_exceptions">Exceptions</a>
<li><a href="#Modula3_typemap_example">Example</a>
</ul>
<li><a href="#hints">More hints to the generator</a>
<li><a href="#Modula3_hints">More hints to the generator</a>
<ul>
<li><a href="#features">Features</a>
<li><a href="#pragmas">Pragmas</a>
<li><a href="#Modula3_features">Features</a>
<li><a href="#Modula3_pragmas">Pragmas</a>
</ul>
<li><a href="#remarks">Remarks</a>
<li><a href="#Modula3_remarks">Remarks</a>
</ul>
</div>
<!-- INDEX -->
@ -49,24 +46,29 @@
<p>
This chapter describes SWIG's support of
<a href="http://www.m3.org/">Modula-3</a>.
<a href="http://modula3.org/">Modula-3</a>.
You should be familiar with the
<a href="SWIG.html#SWIG">basics</a>
of SWIG,
especially
<a href="Typemaps.html">typemaps</a>.
<a href="Typemaps.html#Typemaps">typemaps</a>.
</p>
<H2><a name="modula3_overview"></a>23.1 Overview</H2>
<H2><a name="Modula3_modula3_overview"></a>27.1 Overview</H2>
<p>
The Modula-3 support is very basic and highly experimental!
Modula-3 is a compiled language in the tradition of Niklaus Wirth's Modula 2,
which is in turn a successor to Pascal.
</p>
<p>
SWIG's Modula-3 support is currently very basic and highly experimental!
Many features are still not designed satisfyingly
and I need more discussion about the odds and ends.
Don't rely on any feature, incompatible changes are likely in the future!
The Modula-3 generator was already useful for interfacing
to the libraries
However, the Modula-3 generator was already useful for interfacing
to the libraries:
</p>
<ol>
@ -78,130 +80,34 @@ PLPlot
<li>
<a href="http://www.elegosoft.com/cgi-bin/cvsweb.cgi/cm3/m3-libs/fftw/">
FFTW
</a> .
</a>
</li>
</ol>
<p>
I took some more time to explain
why I think it's right what I'm doing.
So the introduction got a bit longer than it should ... ;-)
</p>
<H3><a name="whyscripting"></a>23.1.1 Why not scripting ?</H3>
<H3><a name="Modula3_motivation"></a>27.1.1 Motivation</H3>
<p>
SWIG started as wrapper from the fast compiled languages C and C++
to high level scripting languages like Python.
Although scripting languages are designed
to make programming life easier
by hiding machine internals from the programmer
there are several aspects of today's scripting languages
that are unfavourable in my opinion.
Although it is possible to write Modula-3 code that performs as well as C/C++
most existing libraries are not written in Modula-3 but in C or C++, and
even libraries in other languages may provide C header files.
</p>
<p>
Besides C, C++, Cluster (a Modula derivate for Amiga computers)
I evaluated several scripting like languages in the past:
Different dialects of BASIC,
Perl, ARexx (a variant of Rexx for Amiga computers),
shell scripts.
I found them too inconsistent,
too weak in distinguishing types,
too weak in encapsulating pieces of code.
Eventually I have started several projects in Python
because of the fine syntax.
But when projects became larger
I lost the track.
I got convinced that one can not have
maintainable code in a language
that is not statically typed.
In fact the main advantages of scripting languages
e.g. matching regular expressions,
complex built-in datatypes like lists, dictionaries,
are not advantages of the language itself
but can be provided by function libraries.
</p>
<H3><a name="whymodula3"></a>23.1.2 Why Modula-3 ?</H3>
<p>
Modula-3 is a compiler language
in the tradition of Niklaus Wirth's Modula 2,
which is in turn a successor of the popular Pascal.
I have chosen Modula-3
because of its
logical syntax,
strong modularization,
the type system which is very detailed
for machine types compared to other languages.
Of course it supports all of the modern games
like exceptions, objects, garbage collection, threads.
While C++ programmers must
control three languages,
namely the preprocessor, C and ++,
Modula-3 is made in one go
and the language definition is really compact.
Fortunately Modula-3 can call C functions, but you have to write Modula-3
interfaces to them, and to make things comfortable you will also need
wrappers that convert between high-level features of Modula-3 (garbage
collecting, exceptions) and the explicit tracking of allocated memory and
exception codes used by C APIs.
</p>
<p>
On the one hand Modula-3 can be safe
(but probably less efficient) in normal modules
while providing much static and dynamic safety.
On the other hand you can write efficient
but less safe code in the style of C
within <tt>UNSAFE</tt> modules.
SWIG converts C headers to Modula-3 interfaces for you, and using typemaps
you can pass <tt>TEXT</tt>s or open arrays, and convert error return codes
into exceptions.
</p>
<p>
Unfortunately Modula's safety and strength
requires more writing than scripting languages do.
Today if I want to safe characters
I prefer Haskell (similar to OCAML) -
it's statically typed, too.
</p>
<H3><a name="whycpp"></a>23.1.3 Why C / C++ ?</H3>
<p>
Although it is no problem to write Modula-3 programs
that performs as fast as C
most libraries are not written in Modula-3 but in C.
Fortunately the binary interface of most function libraries
can be addressed by Modula-3.
Even more fortunately even non-C libraries may provide C header files.
This is where SWIG becomes helpful.
</p>
<H3><a name="whyswig"></a>23.1.4 Why SWIG ?</H3>
<p>
The C headers and the possibility to interface to C libraries
still leaves the work for you
to write Modula-3 interfaces to them.
To make things comfortable you will also need
wrappers that convert between high-level features of Modula-3
(garbage collecting, exceptions)
and the low level of the C libraries.
</p>
<p>
SWIG converts C headers to Modula-3 interfaces for you.
You could call the C functions without loss
of efficiency but it won't be joy
because you could not pass <tt>TEXT</tt>s
or open arrays and
you would have to process error return codes
rather then exceptions.
But using some typemaps SWIG will also generate
wrappers that bring the whole Modula-3 comfort to you.
If the library API is ill designed
writing appropriate typemaps can be still time-consuming.
E.g. C programmers are very creative to work-around
@ -211,59 +117,32 @@ otherwise you lose static safety and consistency.
</p>
<p>
But you have still a problem:
C library interfaces are often ill.
They lack for certain information
because C compilers wouldn't care about.
You should integrate detailed type information
by adding <tt>typedef</tt>s and <tt>const</tt>s
and you should persuade the C library programmer
to add this information to his interface.
Only this way other language users can benefit from your work
and only this way you can easily update your interfaces
when a new library version is released.
You will realise that writing <b>good</b> SWIG interfaces
is very costly and it will only amortise
when considering evolving libraries.
</p>
<p>
Without SWIG you would probably never consider
to call C++ libraries from Modula-3.
But with SWIG this is worth a consideration.
SWIG can write C wrappers to C++ functions and object methods
that may throw exceptions.
In fact it breaks down C++ libraries to C interfaces
which can be in turn called from Modula-3.
To make it complete you can hide the C interface
with Modula-3 classes and exceptions.
Without SWIG you would probably never consider trying to call C++ libraries
from Modula-3, but with SWIG this is becomes feasible.
SWIG can generate C wrappers to C++ functions and object methods
that may throw exceptions, and then wrap these C wrappers for Module-3.
To make it complete you can then hide the C interface with Modula-3 classes and
exceptions.
</p>
<p>
Although SWIG does the best it can do
it can only serve as a one-way strategy.
That means you can use C++ libraries
with Modula-3 (even with call back functions),
but it's certainly not possible to smoothly
integrate Modula-3 code into a C / C++ project.
SWIG allows you to call C and C++ libraries from Modula-3 (even with call back
functions), but it doesn't allow you to easily integrate a Module-3 module into
a C/C++ project.
</p>
<H2><a name="conception"></a>23.2 Conception</H2>
<H2><a name="Modula3_conception"></a>27.2 Conception</H2>
<H3><a name="cinterface"></a>23.2.1 Interfaces to C libraries</H3>
<H3><a name="Modula3_cinterface"></a>27.2.1 Interfaces to C libraries</H3>
<p>
Modula-3 has an integrated support for calling C functions.
Modula-3 has integrated support for calling C functions.
This is also extensively used by the standard Modula-3 libraries
to call OS functions.
The Modula-3 part of SWIG and the corresponding SWIG library
<a href="../../Lib/modula3/modula3.swg"><tt>modula3.swg</tt></a>
modula3.swg
contain code that uses these features.
Because of the built-in support there is no need
for calling the SWIG kernel to generate wrappers written in C.
@ -404,7 +283,7 @@ and the principal type must be renamed (<tt>%typemap</tt>).
</p>
<H3><a name="cppinterface"></a>23.2.2 Interfaces to C++ libraries</H3>
<H3><a name="Modula3_cppinterface"></a>27.2.2 Interfaces to C++ libraries</H3>
<p>
@ -417,7 +296,7 @@ with a C interface.
<p>
Here's a scheme of how the function calls to Modula-3 wrappers
a redirected to C library functions:
are redirected to C library functions:
</p>
<table summary="Modula-3 C++ library">
@ -477,13 +356,13 @@ Is it possible to sub-class C++ classes with Modula-3 code?
This issue is addressed by directors,
a feature that was experimentally added to some Language modules
like
<a href="Java.html#java_directors">Java</a> and
<a href="Python.html#directors">Python</a>.
<a href="Java.html#Java_directors">Java</a> and
<a href="Python.html#Python_directors">Python</a>.
</li>
<li>
How to manage storage with the garbage collector of Modula-3?
Support for
<a href="Customization.html#ownership">
<a href="Customization.html#Customization_ownership">
<tt>%newobject</tt> and <tt>%typemap(newfree)</tt></a>
isn't implemented, yet.
What's about resources that are managed by the garbage collector
@ -494,7 +373,7 @@ as far as I know.
<li>
How to turn C++ exceptions into Modula-3 exceptions?
There's also no support for
<a href="Customization.html#exception">
<a href="Customization.html#Customization_exception">
<tt>%exception</tt></a>, yet.
</li>
</ul>
@ -505,24 +384,23 @@ There is no C++ library I wrote a SWIG interface for,
so I'm not sure if this is possible or sensible, yet.
</p>
<H2><a name="preliminaries"></a>23.3 Preliminaries</H2>
<H2><a name="Modula3_preliminaries"></a>27.3 Preliminaries</H2>
<H3><a name="compilers"></a>23.3.1 Compilers</H3>
<H3><a name="Modula3_compilers"></a>27.3.1 Compilers</H3>
<p>
There are different Modula-3 compilers around:
cm3, pm3, ezm3, Klagenfurth Modula-3, Cambridge Modula-3.
SWIG itself does not contain compiler specific code
but the library file
<a href="../../Lib/modula3/modula3.swg"><tt>modula3.swg</tt></a>
but the modula3.swg library file
may do so.
For testing examples I use Critical Mass cm3.
</p>
<H3><a name="commandline"></a>23.3.2 Additional Commandline Options</H3>
<H3><a name="Modula3_commandline"></a>27.3.2 Additional Commandline Options</H3>
<p>
@ -599,10 +477,10 @@ Instead generate templates for some basic typemaps.
</tr>
</table>
<H2><a name="modula3_typemaps"></a>23.4 Modula-3 typemaps</H2>
<H2><a name="Modula3_typemaps"></a>27.4 Modula-3 typemaps</H2>
<H3><a name="inoutparam"></a>23.4.1 Inputs and outputs</H3>
<H3><a name="Modula3_inoutparam"></a>27.4.1 Inputs and outputs</H3>
<p>
@ -620,9 +498,7 @@ or for a return value.
A further typemap may specify
the direction that is used for certain parameters.
I have chosen this separation
in order to be able to write general typemaps for the typemap library
<a href="../../Lib/modula3/modula3.swg"><tt>modula3.swg</tt></a>
.
in order to be able to write general typemaps for the modula3.swg typemap library.
In the library code the final usage of the type is not known.
Using separate typemaps for each possible use
allows appropriate definitions for each case.
@ -818,7 +694,7 @@ consist of the following parts:
</table>
<H3><a name="ordinals"></a>23.4.2 Subranges, Enumerations, Sets</H3>
<H3><a name="Modula3_ordinals"></a>27.4.2 Subranges, Enumerations, Sets</H3>
<p>
@ -860,8 +736,8 @@ that split the task up into converting
the C bit patterns (integer or bit set)
into Modula-3 bit patterns (integer or bit set)
and change the type as requested.
See the corresponding
<a href="../../Examples/modula3/enum/example.i">example</a>.
See the corresponding example in the
Examples/modula3/enum/example.i file.
This is quite messy and not satisfying.
So the best what you can currently do is
to rewrite constant definitions manually.
@ -870,20 +746,20 @@ that I'd like to automate.
</p>
<H3><a name="class"></a>23.4.3 Objects</H3>
<H3><a name="Modula3_class"></a>27.4.3 Objects</H3>
<p>
Declarations of C++ classes are mapped to <tt>OBJECT</tt> types
while it is tried to retain the access hierarchy
"public - protected - private" using partial revelation.
Though the
<a href="../../Examples/modula3/class/example.i">implementation</a>
Though the example in
Examples/modula3/class/example.i
is not really useful, yet.
</p>
<H3><a name="imports"></a>23.4.4 Imports</H3>
<H3><a name="Modula3_imports"></a>27.4.4 Imports</H3>
<p>
@ -903,9 +779,7 @@ Unqualified import is not supported.
<p>
It is cumbersome to add this typemap to each piece of Modula-3 code.
It is especially useful when writing general typemaps
for the typemap library
<a href="../../Lib/modula3/modula3.swg"><tt>modula3.swg</tt></a>
.
for the modula3.swg typemap library.
For a monolithic module you might be better off
if you add the imports directly:
</p>
@ -918,7 +792,7 @@ IMPORT M3toC;
</pre></div>
<H3><a name="exceptions"></a>23.4.5 Exceptions</H3>
<H3><a name="Modula3_exceptions"></a>27.4.5 Exceptions</H3>
<p>
@ -942,7 +816,7 @@ you should declare
<tt>%typemap("m3wrapinconv:throws") blah * %{OSError.E%}</tt>.
</p>
<H3><a name="typemap_example"></a>23.4.6 Example</H3>
<H3><a name="Modula3_typemap_example"></a>27.4.6 Example</H3>
<p>
@ -989,10 +863,10 @@ where almost everything is generated by a typemap:
</pre></div>
<H2><a name="hints"></a>23.5 More hints to the generator</H2>
<H2><a name="Modula3_hints"></a>27.5 More hints to the generator</H2>
<H3><a name="features"></a>23.5.1 Features</H3>
<H3><a name="Modula3_features"></a>27.5.1 Features</H3>
<table border summary="Modula-3 features">
@ -1022,14 +896,14 @@ where almost everything is generated by a typemap:
This is necessary in the cases
where it was defined by a non-trivial C expression.
This feature is used by the
<tt>-generateconst</tt> <a href="#options">option</a>.
<tt>-generateconst</tt> <a href="#Modula3_commandline">option</a>.
In future it may be generalized to other kind of values
such as strings.
</td>
</tr>
</table>
<H3><a name="pragmas"></a>23.5.2 Pragmas</H3>
<H3><a name="Modula3_pragmas"></a>27.5.2 Pragmas</H3>
<table border summary="Modula-3 pragmas">
@ -1052,14 +926,14 @@ where almost everything is generated by a typemap:
</tr>
</table>
<H2><a name="remarks"></a>23.6 Remarks</H2>
<H2><a name="Modula3_remarks"></a>27.6 Remarks</H2>
<ul>
<li>
The Modula-3 part of SWIG doesn't try to generate nicely formatted code.
Use <tt>m3pp</tt> to postprocess the Modula files,
it does a very good job here.
If you need to read the generated code, use <tt>m3pp</tt> to postprocess the
Modula files.
</li>
</ul>

144
Doc/Manual/Modules.html
View file

@ -10,9 +10,10 @@
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="#Modules_introduction">Modules Introduction</a>
<li><a href="#Modules_nn1">Basics</a>
<li><a href="#Modules_nn2">The SWIG runtime code</a>
<li><a href="#external_run_time">External access to the runtime</a>
<li><a href="#Modules_external_run_time">External access to the runtime</a>
<li><a href="#Modules_nn4">A word of caution about static libraries</a>
<li><a href="#Modules_nn5">References</a>
<li><a href="#Modules_nn6">Reducing the wrapper file size</a>
@ -22,11 +23,49 @@
<H2><a name="Modules_introduction"></a>15.1 Modules Introduction</H2>
<p>
Each invocation of SWIG requires a module name to be specified.
The module name is used to name the resulting target language extension module.
Exactly what this means and what the name is used for
depends on the target language, for example the name can define
a target language namespace or merely be a useful name for naming files or helper classes.
Essentially, a module comprises target language wrappers for a chosen collection of global variables/functions, structs/classes and other C/C++ types.
</p>
<p>
The module name can be supplied in one of two ways.
The first is to specify it with the special <tt>%module</tt>
directive. This directive must appear at the beginning of the interface file.
The general form of this directive is:
</p>
<div class="code"><pre>
<tt>%module(option1="value1",option2="value2",...) modulename</tt>
</pre></div>
<p>
where the modulename is mandatory and the options add one or more optional additional features.
Typically no options are specified, for example:
</p>
<div class="code"><pre>
<tt>%module mymodule</tt>
</pre></div>
<p>
The second way to specify the module name is with the <tt>-module</tt> command line option, for example <tt>-module mymodule</tt>.
If the module name is supplied on the command line, it overrides the name specified by the
<tt>%module</tt> directive.
</p>
<p>
When first working with SWIG, users commonly start by creating a
single module. That is, you might define a single SWIG interface that
wraps some set of C/C++ code. You then compile all of the generated
wrapper code into a module and use it. For large applications, however,
wrapper code together and use it. For large applications, however,
this approach is problematic---the size of the generated wrapper code
can be rather large. Moreover, it is probably easier to manage the
target language interface when it is broken up into smaller pieces.
@ -34,10 +73,11 @@ target language interface when it is broken up into smaller pieces.
<p>
This chapter describes the problem of using SWIG in programs
where you want to create a collection of modules.
where you want to create a collection of modules.
Each module in the collection is created via separate invocations of SWIG.
</p>
<H2><a name="Modules_nn1"></a>15.1 Basics</H2>
<H2><a name="Modules_nn1"></a>15.2 Basics</H2>
<p>
@ -50,43 +90,93 @@ scripting language runtime as you would do for the single module case.
<p>
A bit more complex is the case in which modules need to share information.
For example, when one module extends the class of the another by deriving from
For example, when one module extends the class of another by deriving from
it:
</p>
<div class="code"><pre>
%module base
%inline %{
// File: base.h
class base {
public:
int foo(void);
int foo();
};
%}
</pre></div>
&nbsp;
<div class="code"><pre>
%module derived
%import "base.i"
<div class="code"><pre>
// File: base_module.i
%module base_module
%{
#include "base.h"
%}
%include "base.h"
</pre></div>
&nbsp;
<div class="code"><pre>
// File: derived_module.i
%module derived_module
%import "base_module.i"
%inline %{
class derived : public base {
public:
int bar(void);
int bar();
};
%}
</pre></div>
<p>To create the wrapper properly, module <tt>derived</tt> needs to know the
<tt>base</tt> class and that it's interface is covered in another module. The
line <tt>%import "base.i"</tt> lets SWIG know exactly that. The common mistake here is
to <tt>%import</tt> the <tt>.h</tt> file instead of the <tt>.i</tt>, which sadly won't do the trick. Another issue
to take care of is that multiple dependent wrappers should not be linked/loaded
in parallel from multiple threads as SWIG provides no locking - for more on that
issue, read on.</p>
<p>To create the wrapper properly, module <tt>derived_module</tt> needs to know about the
<tt>base</tt> class and that its interface is covered in another module. The
line <tt>%import "base_module.i"</tt> lets SWIG know exactly that. Oftentimes
the <tt>.h</tt> file is passed to <tt>%import</tt> instead of the <tt>.i</tt>,
which unfortunately doesn't work for all language modules. For example, Python requires the
name of module that the base class exists in so that the proxy classes can fully inherit the
base class's methods. Typically you will get a warning when the module name is missing, eg:
</p>
<H2><a name="Modules_nn2"></a>15.2 The SWIG runtime code</H2>
<div class="shell"> <pre>
derived_module.i:8: Warning 401: Base class 'base' ignored - unknown module name for base. Either
import
the appropriate module interface file or specify the name of the module in the %import directive.
</pre></div>
<p>
It is sometimes desirable to import the header file rather than the interface file and overcome
the above warning.
For example in the case of the imported interface being quite large, it may be desirable to
simplify matters and just import a small header file of dependent types.
This can be done by specifying the optional <tt>module</tt> attribute in the <tt>%import</tt> directive.
The <tt>derived_module.i</tt> file shown above could be replaced with the following:
<div class="code"><pre>
// File: derived_module.i
%module derived_module
%import(module="base_module") "base.h"
%inline %{
class derived : public base {
public:
int bar();
};
</pre></div>
<p>
Note that "base_module" is the module name and is the same as that specified in <tt>%module</tt>
in <tt>base_module.i</tt> as well as the <tt>%import</tt> in <tt>derived_module.i</tt>.
</p>
<p>
Another issue
to beware of is that multiple dependent wrappers should not be linked/loaded
in parallel from multiple threads as SWIG provides no locking - for more on that
issue, read on.
</p>
<H2><a name="Modules_nn2"></a>15.3 The SWIG runtime code</H2>
<p>
@ -152,10 +242,10 @@ can peacefully coexist. So the type structures are separated by the
is empty. Only modules compiled with the same pair will share type information.
</p>
<H2><a name="external_run_time"></a>15.3 External access to the runtime</H2>
<H2><a name="Modules_external_run_time"></a>15.4 External access to the runtime</H2>
<p>As described in <a href="Typemaps.html#runtime_type_checker">The run-time type checker</a>,
<p>As described in <a href="Typemaps.html#Typemaps_runtime_type_checker">The run-time type checker</a>,
the functions <tt>SWIG_TypeQuery</tt>, <tt>SWIG_NewPointerObj</tt>, and others sometimes need
to be called. Calling these functions from a typemap is supported, since the typemap code
is embedded into the <tt>_wrap.c</tt> file, which has those declarations available. If you need
@ -189,7 +279,7 @@ SWIG_TYPE_TABLE to be the same as the module whose types you are trying to
access.
</p>
<H2><a name="Modules_nn4"></a>15.4 A word of caution about static libraries</H2>
<H2><a name="Modules_nn4"></a>15.5 A word of caution about static libraries</H2>
<p>
@ -200,7 +290,7 @@ into it. This is very often <b>NOT</b> what you want and it can lead to unexpect
behavior. When working with dynamically loadable modules, you should try to work exclusively with shared libraries.
</p>
<H2><a name="Modules_nn5"></a>15.5 References</H2>
<H2><a name="Modules_nn5"></a>15.6 References</H2>
<p>
@ -208,7 +298,7 @@ Due to the complexity of working with shared libraries and multiple modules, it
an outside reference. John Levine's "Linkers and Loaders" is highly recommended.
</p>
<H2><a name="Modules_nn6"></a>15.6 Reducing the wrapper file size</H2>
<H2><a name="Modules_nn6"></a>15.7 Reducing the wrapper file size</H2>
<p>

122
Doc/Manual/Mzscheme.html
View file

@ -2,17 +2,19 @@
<!-- Hand-written HTML -->
<html>
<head>
<title>SWIG and MzScheme</title>
<title>SWIG and MzScheme/Racket</title>
<link rel="stylesheet" type="text/css" href="style.css">
</head>
<body bgcolor="#ffffff">
<H1><a name="MzScheme"></a>24 SWIG and MzScheme</H1>
<H1><a name="Mzscheme"></a>28 SWIG and MzScheme/Racket</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="#MzScheme_nn2">Creating native MzScheme structures</a>
<li><a href="#MzScheme_nn2">Creating native structures</a>
<li><a href="#MzScheme_simple">Simple example</a>
<li><a href="#MzScheme_external_docs">External documentation</a>
</ul>
</div>
<!-- INDEX -->
@ -20,9 +22,9 @@
<p>
This section contains information on SWIG's support of MzScheme.
This section contains information on SWIG's support of Racket, formally known as MzScheme.
<H2><a name="MzScheme_nn2"></a>24.1 Creating native MzScheme structures</H2>
<H2><a name="MzScheme_nn2"></a>28.1 Creating native structures</H2>
<p>
@ -63,8 +65,116 @@ Then in scheme, you can use regular struct access procedures like
</pre>
</div>
<H2><a name="MzScheme_simple"></a>28.2 Simple example</H2>
<p>
That's pretty much it. It works with nested structs as well.
A few examples are available in the Examples/mzscheme directory.
The code and log of a session using SWIG below should help getting started.
</p>
<p>
C header file:
</p>
<div class="code">
<pre>
// example.h
int fact(int n);
</pre>
</div>
<p>
C source code:
</p>
<div class="code">
<pre>
// File: example.c
#include "example.h"
int fact(int n) {
if (n &lt; 0) { /* This should probably return an error, but this is simpler */
return 0;
}
if (n == 0) {
return 1;
}
else {
/* testing for overflow would be a good idea here */
return n * fact(n-1);
}
}
</pre>
</div>
<p>
SWIG interface file:
</p>
<div class="code">
<pre>
/* File: example.i */
%module example
%{
#include "example.h"
%}
int fact(int n);
</pre>
</div>
<p>
The session below using the above files is on an OS X machine, but the points to be made are more general. On OS X, libtool is the tool which creates libraries, which are named .dylib, rather than .so on other unixes, or .dll on Windows.
</p>
<div class="shell">
<pre>
% swig -mzscheme -declaremodule example.i
% gcc -c -m32 -o example.o example.c # force 32-bit object file (mzscheme is 32-bit only)
% libtool -dynamic -o libexample.dylib example.o # make it into a library
% ls # what've we got so far?
example.c example.o
example.h example_wrap.c
example.i libexample.dylib*
% mzc --cgc --cc example_wrap.c # compile the wrapping code
% LDFLAGS="-L. -lexample" mzc --ld example_wrap.dylib example_wrap.o # ...and link it
% mzscheme -e '(path-&gt;string (build-path "compiled" "native" (system-library-subpath)))'
"compiled/native/i386-macosx/3m"
% mkdir -p compiled/native/i386-macosx/3m # move the extension library to a magic place
% mv example_wrap.dylib compiled/native/i386-macosx/3m/example_ss.dylib
% mzscheme
Welcome to MzScheme v4.2.4 [3m], Copyright (c) 2004-2010 PLT Scheme Inc.
&gt; (require "example.ss")
&gt; (fact 5)
120
&gt; ^D
% echo 'It works!'
</pre>
</div>
<p>
Some points of interest:
</p>
<ul>
<li> This is on a 64-bit machine, so we have to include the -m32 option when building the object file
<li> If you want to declare a scheme module (and you probably do), it's important that you include the -declaremodule option to swig (if you miss this out, it'll appear to work, but fail later).
<li> Use mzc to compile and then link the wrapped code. You'll probably need to adjust the link flags to refer to the library you're wrapping (you can either do this with an LDFLAGS declaration, as here, or with multiple ++ldf options to mzc).
<li> Create the directory with path (build-path "compiled" "native" (system-library-subpath)) and move the freshly-generated .dylib to there, changing its name to module-name_ss.dylib. After that, you can REQUIRE the new module with (require "module-name.ss").
<li> The above requests mzc to create an extension using the CGC garbage-collector. The alternative -- the 3m collector -- has generally better performance, but work is still required for SWIG to emit code which is compatible with it.
</ul>
<H2><a name="MzScheme_external_docs"></a>28.3 External documentation</H2>
<p>
See the <a href="http://docs.racket-lang.org/inside/index.html">C API</a> for more description of using the mechanism for adding extensions. The main documentation is <a href="http://docs.racket-lang.org/">here</a>.
</p>
<p>
Tip: mzc's --vv option is very useful for debugging the inevitable library problems you'll encounter.
</p>
</body>

68
Doc/Manual/Ocaml.html
View file

@ -6,7 +6,7 @@
</head>
<body bgcolor="#ffffff">
<a name="n1"></a>
<H1><a name="Ocaml"></a>25 SWIG and Ocaml</H1>
<H1><a name="Ocaml"></a>29 SWIG and Ocaml</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -80,7 +80,7 @@ If you're not familiar with the Objective Caml language, you can visit
<a href="http://www.ocaml.org/">The Ocaml Website</a>.
</p>
<H2><a name="Ocaml_nn2"></a>25.1 Preliminaries</H2>
<H2><a name="Ocaml_nn2"></a>29.1 Preliminaries</H2>
<p>
@ -93,13 +93,13 @@ examples and test-suite which come with SWIG. You can do this by running
The Ocaml module has been tested using the system's dynamic linking (the
usual -lxxx against libxxx.so, as well as with Gerd Stolpmann's
<a
href="http://www.ocaml-programming.de/packages/documentation/dl/">Dl package
href="http://download.camlcity.org/download/">Dl package
</a>. The ocaml_dynamic and ocaml_dynamic_cpp targets in the
file Examples/Makefile illustrate how to compile and link SWIG modules that
will be loaded dynamically. This has only been tested on Linux so far.
</p>
<H3><a name="Ocaml_nn3"></a>25.1.1 Running SWIG</H3>
<H3><a name="Ocaml_nn3"></a>29.1.1 Running SWIG</H3>
<p>
@ -122,7 +122,7 @@ you will compile the file <tt>example_wrap.c</tt> with <tt>ocamlc</tt> or
the resulting .ml and .mli files as well, and do the final link with -custom
(not needed for native link). </p>
<H3><a name="Ocaml_nn4"></a>25.1.2 Compiling the code</H3>
<H3><a name="Ocaml_nn4"></a>29.1.2 Compiling the code</H3>
<p>
@ -158,7 +158,7 @@ the user more freedom with respect to custom typing.
</pre>
</div>
<H3><a name="Ocaml_nn5"></a>25.1.3 The camlp4 module</H3>
<H3><a name="Ocaml_nn5"></a>29.1.3 The camlp4 module</H3>
<p>
@ -234,7 +234,7 @@ let b = C_string (getenv "PATH")
</td></tr>
</table>
<H3><a name="Ocaml_nn6"></a>25.1.4 Using your module</H3>
<H3><a name="Ocaml_nn6"></a>29.1.4 Using your module</H3>
<p>
@ -248,7 +248,7 @@ When linking any ocaml bytecode with your module, use the -custom
option is not needed when you build native code.
</p>
<H3><a name="Ocaml_nn7"></a>25.1.5 Compilation problems and compiling with C++</H3>
<H3><a name="Ocaml_nn7"></a>29.1.5 Compilation problems and compiling with C++</H3>
<p>
@ -259,7 +259,7 @@ liberal with pointer types may not compile under the C++ compiler.
Most code meant to be compiled as C++ will not have problems.
</p>
<H2><a name="Ocaml_nn8"></a>25.2 The low-level Ocaml/C interface</H2>
<H2><a name="Ocaml_nn8"></a>29.2 The low-level Ocaml/C interface</H2>
<p>
@ -360,7 +360,7 @@ is that you must append them to the return list with swig_result = caml_list_a
signature for a function that uses value in this way.
</p>
<H3><a name="Ocaml_nn9"></a>25.2.1 The generated module</H3>
<H3><a name="Ocaml_nn9"></a>29.2.1 The generated module</H3>
<p>
@ -394,7 +394,7 @@ it describes the output SWIG will generate for class definitions.
</td></tr>
</table>
<H3><a name="Ocaml_nn10"></a>25.2.2 Enums</H3>
<H3><a name="Ocaml_nn10"></a>29.2.2 Enums</H3>
<p>
@ -457,7 +457,7 @@ val x : Enum_test.c_obj = C_enum `a
</pre>
</div>
<H4><a name="Ocaml_nn11"></a>25.2.2.1 Enum typing in Ocaml</H4>
<H4><a name="Ocaml_nn11"></a>29.2.2.1 Enum typing in Ocaml</H4>
<p>
@ -470,10 +470,10 @@ functions imported from different modules. You must convert values to master
values using the swig_val function before sharing them with another module.
</p>
<H3><a name="Ocaml_nn12"></a>25.2.3 Arrays</H3>
<H3><a name="Ocaml_nn12"></a>29.2.3 Arrays</H3>
<H4><a name="Ocaml_nn13"></a>25.2.3.1 Simple types of bounded arrays</H4>
<H4><a name="Ocaml_nn13"></a>29.2.3.1 Simple types of bounded arrays</H4>
<p>
@ -494,7 +494,7 @@ arrays of simple types with known bounds in your code, but this only works
for arrays whose bounds are completely specified.
</p>
<H4><a name="Ocaml_nn14"></a>25.2.3.2 Complex and unbounded arrays</H4>
<H4><a name="Ocaml_nn14"></a>29.2.3.2 Complex and unbounded arrays</H4>
<p>
@ -507,7 +507,7 @@ SWIG can't predict which of these methods will be used in the array,
so you have to specify it for yourself in the form of a typemap.
</p>
<H4><a name="Ocaml_nn15"></a>25.2.3.3 Using an object</H4>
<H4><a name="Ocaml_nn15"></a>29.2.3.3 Using an object</H4>
<p>
@ -521,7 +521,7 @@ Consider writing an object when the ending condition of your array is complex,
such as using a required sentinel, etc.
</p>
<H4><a name="Ocaml_nn16"></a>25.2.3.4 Example typemap for a function taking float * and int</H4>
<H4><a name="Ocaml_nn16"></a>29.2.3.4 Example typemap for a function taking float * and int</H4>
<p>
@ -572,7 +572,7 @@ void printfloats( float *tab, int len );
</pre></td></tr></table>
<H3><a name="Ocaml_nn17"></a>25.2.4 C++ Classes</H3>
<H3><a name="Ocaml_nn17"></a>29.2.4 C++ Classes</H3>
<p>
@ -615,7 +615,7 @@ the underlying pointer, so using create_[x]_from_ptr alters the
returned value for the same object.
</p>
<H4><a name="Ocaml_nn18"></a>25.2.4.1 STL vector and string Example</H4>
<H4><a name="Ocaml_nn18"></a>29.2.4.1 STL vector and string Example</H4>
<p>
@ -634,13 +634,13 @@ length. Instead, use multiple returns, as in the argout_ref example.
#include "example.h"
%}
%include stl.i
%include &lt;stl.i&gt;
namespace std {
%template(StringVector) std::vector &lt; string &gt;;
};
%include example.h
%include "example.h"
</pre></td></tr>
<tr><td><font size="-1"><i>This example is in Examples/ocaml/stl
</i></font></td></tr>
@ -695,7 +695,7 @@ baz
#
</pre></div>
<H4><a name="Ocaml_nn19"></a>25.2.4.2 C++ Class Example</H4>
<H4><a name="Ocaml_nn19"></a>29.2.4.2 C++ Class Example</H4>
<p>
@ -725,7 +725,7 @@ public:
};
</pre></td></tr></table>
<H4><a name="Ocaml_nn20"></a>25.2.4.3 Compiling the example</H4>
<H4><a name="Ocaml_nn20"></a>29.2.4.3 Compiling the example</H4>
<div class="code"><pre>
@ -743,7 +743,7 @@ bash-2.05a$ ocamlmktop -custom swig.cmo -I `camlp4 -where` \
-L$QTPATH/lib -cclib -lqt
</pre></div>
<H4><a name="Ocaml_nn21"></a>25.2.4.4 Sample Session</H4>
<H4><a name="Ocaml_nn21"></a>29.2.4.4 Sample Session</H4>
<div class="code"><pre>
@ -770,10 +770,10 @@ Assuming you have a working installation of QT, you will see a window
containing the string "hi" in a button.
</p>
<H3><a name="Ocaml_nn22"></a>25.2.5 Director Classes</H3>
<H3><a name="Ocaml_nn22"></a>29.2.5 Director Classes</H3>
<H4><a name="Ocaml_nn23"></a>25.2.5.1 Director Introduction</H4>
<H4><a name="Ocaml_nn23"></a>29.2.5.1 Director Introduction</H4>
<p>
@ -800,7 +800,7 @@ class foo {
};
</pre></div>
<H4><a name="Ocaml_nn24"></a>25.2.5.2 Overriding Methods in Ocaml</H4>
<H4><a name="Ocaml_nn24"></a>29.2.5.2 Overriding Methods in Ocaml</H4>
<p>
@ -828,7 +828,7 @@ In this example, I'll examine the objective caml code involved in providing
an overloaded class. This example is contained in Examples/ocaml/shapes.
</p>
<H4><a name="Ocaml_nn25"></a>25.2.5.3 Director Usage Example</H4>
<H4><a name="Ocaml_nn25"></a>29.2.5.3 Director Usage Example</H4>
<table border="1" bgcolor="#dddddd" summary="Director usage example">
@ -887,7 +887,7 @@ in a more effortless style in ocaml, while leaving the "engine" part of the
program in C++.
</p>
<H4><a name="Ocaml_nn26"></a>25.2.5.4 Creating director objects</H4>
<H4><a name="Ocaml_nn26"></a>29.2.5.4 Creating director objects</H4>
<p>
@ -928,7 +928,7 @@ object from causing a core dump, as long as the object is destroyed
properly.
</p>
<H4><a name="Ocaml_nn27"></a>25.2.5.5 Typemaps for directors, <tt>directorin, directorout, directorargout</tt></H4>
<H4><a name="Ocaml_nn27"></a>29.2.5.5 Typemaps for directors, <tt>directorin, directorout, directorargout</tt></H4>
<p>
@ -939,7 +939,7 @@ well as a function return value in the same way you provide function arguments,
and to receive arguments the same way you normally receive function returns.
</p>
<H4><a name="Ocaml_nn28"></a>25.2.5.6 <tt>directorin</tt> typemap</H4>
<H4><a name="Ocaml_nn28"></a>29.2.5.6 <tt>directorin</tt> typemap</H4>
<p>
@ -950,7 +950,7 @@ code receives when you are called. In general, a simple <tt>directorin</tt> typ
can use the same body as a simple <tt>out</tt> typemap.
</p>
<H4><a name="Ocaml_nn29"></a>25.2.5.7 <tt>directorout</tt> typemap</H4>
<H4><a name="Ocaml_nn29"></a>29.2.5.7 <tt>directorout</tt> typemap</H4>
<p>
@ -961,7 +961,7 @@ for the same type, except when there are special requirements for object
ownership, etc.
</p>
<H4><a name="Ocaml_nn30"></a>25.2.5.8 <tt>directorargout</tt> typemap</H4>
<H4><a name="Ocaml_nn30"></a>29.2.5.8 <tt>directorargout</tt> typemap</H4>
<p>
@ -978,7 +978,7 @@ In the event that you don't specify all of the necessary values, integral
values will read zero, and struct or object returns have undefined results.
</p>
<H3><a name="Ocaml_nn31"></a>25.2.6 Exceptions</H3>
<H3><a name="Ocaml_nn31"></a>29.2.6 Exceptions</H3>
<p>

188
Doc/Manual/Octave.html
View file

@ -8,13 +8,14 @@
<body bgcolor="#ffffff">
<H1><a name="Octave"></a>26 SWIG and Octave</H1>
<H1><a name="Octave"></a>30 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">Command-line options</a>
<li><a href="#Octave_nn5">Compiling a dynamic module</a>
<li><a href="#Octave_nn6">Using your module</a>
</ul>
@ -46,7 +47,7 @@
<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">www.octave.org</a>.
More information can be found at <a href="http://www.gnu.org/software/octave/">Octave web site</a>.
</p>
<p>
@ -54,21 +55,26 @@ More information can be found at <a href="http://www.octave.org">www.octave.org<
Also, there are a dozen or so examples in the Examples/octave directory, and hundreds in the test suite (Examples/test-suite and Examples/test-suite/octave).
</p>
<H2><a name="Octave_nn2"></a>26.1 Preliminaries</H2>
<H2><a name="Octave_nn2"></a>30.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.
The SWIG implemention was first based on Octave 2.9.12, so this is the minimum version required. Testing has only been done on Linux.
</p>
<H2><a name="Octave_nn3"></a>26.2 Running SWIG</H2>
<p>
As of SWIG 2.0.5, the Octave module should work with Octave versions 3.0.5, 3.2.4, and 3.4.0.
</p>
<H2><a name="Octave_nn3"></a>30.2 Running SWIG</H2>
<p>
Let's start with a very simple SWIG interface file:
Let's start with a very simple SWIG interface file, example.i:
</p>
<div class="code"><pre>%module example
<div class="code"><pre>
%module example
%{
#include "example.h"
%}
@ -76,20 +82,49 @@ int gcd(int x, int y);
extern double Foo; </pre></div>
<p>
To build an Octave module, run SWIG using the <tt>-octave</tt> option. The <tt>-c++</tt> option is required (for now) as Octave itself is written in C++ and thus the wrapper code must also be.
To build an Octave module when wrapping C code, run SWIG using the <tt>-octave</tt> option:
</p>
<div class="shell"><pre>$ swig -octave -c++ example.i </pre></div>
<div class="shell"><pre>$ swig -octave -o example_wrap.cpp example.i </pre></div>
<p>
This creates a C/C++ source file <tt>example_wrap.cxx</tt>. The generated C++ source file contains the low-level wrappers that need to be compiled and linked with the rest of your C/C++ application (in this case, the gcd implementation) to create an extension module.
The <tt>-c++</tt> option is also required when wrapping C++ code:
</p>
<div class="shell"><pre>$ swig -octave -c++ -o example_wrap.cpp example.i </pre></div>
<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.
This creates a C++ source file <tt>example_wrap.cpp</tt>. A C++ file is generated even when wrapping C code as Octave is itself written in C++ and requires wrapper code to be in the same language. The generated C++ source file contains the low-level wrappers that need to be compiled and linked with the rest of your C/C++ application (in this case, the gcd implementation) to create an extension module.
</p>
<H3><a name="Octave_nn5"></a>26.2.1 Compiling a dynamic module</H3>
<H3><a name="Octave_nn4"></a>30.2.1 Command-line options</H3>
<p>
The swig command line has a number of options you can use, like to redirect its output. Use <tt>swig -help</tt> to learn about these.
Options specific to the Octave module are:
</p>
<div class="shell">
<pre>$ swig -octave -help
...
Octave Options (available with -octave)
-global - Load all symbols into the global namespace [default]
-globals <em>name</em> - Set <em>name</em> used to access C global variables [default: 'cvar']
- Use '.' to load C global variables into module namespace
-noglobal - Do not load all symbols into the global namespace
-opprefix <em>str</em> - Prefix <em>str</em> for global operator functions [default: 'op_']
</pre></div>
<p>
The <em>-global</em> and <em>-noglobal</em> options determine whether the Octave module will load all symbols into the global namespace in addition to the global namespace.
The <em>-globals</em> option sets the name of the variable which is the namespace for C global variables exported by the module.
The special name "." loads C global variables into the module namespace, i.e. alongside C functions and structs exported by the module.
The <em>-opprefix</em> options sets the prefix of the names of global/friend <a href="#Octave_nn18">operator</a> functions.
</p>
<H3><a name="Octave_nn5"></a>30.2.2 Compiling a dynamic module</H3>
<p>
@ -98,8 +133,8 @@ Building an oct file is usually done with the mkoctfile command (either within O
</p>
<div class="shell"><pre>
$ swig -octave -c++ example.i -o example_wrap.cxx
$ mkoctfile example_wrap.cxx example.c
$ swig -octave -c++ -o example_wrap.cpp example.i
$ mkoctfile example_wrap.cpp example.c
</pre></div>
<p>
@ -116,7 +151,7 @@ $ mkoctfile example_wrap.cxx example.c
<div class="targetlang"><pre>octave:1&gt; example</pre></div>
<H3><a name="Octave_nn6"></a>26.2.2 Using your module</H3>
<H3><a name="Octave_nn6"></a>30.2.3 Using your module</H3>
<p>
@ -134,10 +169,10 @@ octave:4&gt; example.cvar.Foo=4;
octave:5&gt; example.cvar.Foo
ans = 4 </pre></div>
<H2><a name="Octave_nn7"></a>26.3 A tour of basic C/C++ wrapping</H2>
<H2><a name="Octave_nn7"></a>30.3 A tour of basic C/C++ wrapping</H2>
<H3><a name="Octave_nn8"></a>26.3.1 Modules</H3>
<H3><a name="Octave_nn8"></a>30.3.1 Modules</H3>
<p>
@ -149,37 +184,73 @@ When Octave is asked to invoke <tt>example</tt>, it will try to find the .m or .
</p>
<p>
Giving this function a parameter "global" will cause it to load all symbols into the global namespace in addition to the <tt>example</tt> namespace. For example:
An Octave module takes three options, <em>-global</em>, <em>-noglobal</em>, and <em>-globals</em>, which behave the same as the corresponding swig <a href="#Octave_nn4">command-line options</a>.
Here are some example usages:
</p>
<div class="targetlang"><pre>$ octave -q
octave:1&gt; example("global")
octave:2&gt; gcd(4,6)
<div class="targetlang"><pre>
octave:1&gt; example -help
usage: example [-global|-noglobal] [-globals &lt;name&gt;]
octave:2&gt; example -global
octave:3&gt; gcd(4,6)
ans = 2
octave:3&gt; cvar.Foo
octave:4&gt; cvar.Foo
ans = 3
octave:4&gt; cvar.Foo=4;
octave:5&gt; cvar.Foo
ans = 4
octave:5&gt; cvar.Foo=4;
octave:6&gt; cvar.Foo
ans = 4
</pre></div>
<br>
<div class="targetlang"><pre>
octave:1&gt; example -noglobal
octave:2&gt; gcd(6,9)
ans = 3
octave:3&gt; cvar.Foo
error: `cvar' undefined near line 3 column 1
octave:3&gt; example.cvar.Foo
ans = 3
</pre></div>
<br>
<div class="targetlang"><pre>
octave:1&gt; example -globals mycvar
octave:2&gt; cvar.Foo
error: `cvar' undefined near line 2 column 1
octave:2&gt; mycvar.Foo
ans = 3
</pre></div>
<p>
It is also possible to rename the module namespace with an assignment, as in: <br>
<div class="targetlang"><pre>octave:1&gt; example;
It is also possible to rename the module / global variables namespaces with an assignment, as in: <br>
<div class="targetlang"><pre>
octave:1&gt; example
octave:2&gt; c=example;
octave:3&gt; c.gcd(10,4)
ans = 2 </pre></div>
<p>
All global variables are put into the cvar namespace object. This is accessible either as <tt>my_module.cvar</tt>, or just <tt>cvar</tt> (if the module is imported into the global namespace).
</p>
<p>
One can also rename it by simple assignment, e.g.,
</p>
<div class="targetlang"><pre>
octave:1&gt; some_vars = cvar;
ans = 2
octave:4&gt; some_vars = cvar;
octave:5&gt; some_vars.Foo
ans = 3
</pre></div>
<H3><a name="Octave_nn9"></a>26.3.2 Functions</H3>
<p>
Modules can also be loaded from within functions, even before being loaded in the base context.
If the module is also used in the base context, however, it must first be loaded again:
</p>
<div class="targetlang"><pre>
octave:1&gt; function l = my_lcm(a,b)
&gt; example
&gt; l = abs(a*b)/example.gcd(a,b);
&gt; endfunction
octave:2&gt; my_lcm(4,6)
ans = 12
octave:3&gt; example.gcd(4,6)
error: can't perform indexing operations for &lt;unknown type&gt; type
octave:3&gt; example;
octave:4&gt; example.gcd(4,6)
ans = 2
</pre></div>
<H3><a name="Octave_nn9"></a>30.3.2 Functions</H3>
<p>
@ -196,7 +267,7 @@ int fact(int n); </pre></div>
<div class="targetlang"><pre>octave:1&gt; example.fact(4)
24 </pre></div>
<H3><a name="Octave_nn10"></a>26.3.3 Global variables</H3>
<H3><a name="Octave_nn10"></a>30.3.3 Global variables</H3>
<p>
@ -231,7 +302,7 @@ extern double Foo;
</pre></div>
<p>
SWIG will allow the the reading of <tt>Foo</tt> but when a set attempt is made, an error function will be called.
SWIG will allow the reading of <tt>Foo</tt> but when a set attempt is made, an error function will be called.
</p>
<div class="targetlang"><pre>octave:1&gt; example
@ -249,7 +320,7 @@ octave:2&gt; example.PI=3.142;
octave:3&gt; example.PI
ans = 3.1420 </pre></div>
<H3><a name="Octave_nn11"></a>26.3.4 Constants and enums</H3>
<H3><a name="Octave_nn11"></a>30.3.4 Constants and enums</H3>
<p>
@ -271,7 +342,7 @@ example.SCONST="Hello World"
example.SUNDAY=0
.... </pre></div>
<H3><a name="Octave_nn12"></a>26.3.5 Pointers</H3>
<H3><a name="Octave_nn12"></a>30.3.5 Pointers</H3>
<p>
@ -318,7 +389,7 @@ octave:2&gt; f=example.fopen("not there","r");
error: value on right hand side of assignment is undefined
error: evaluating assignment expression near line 2, column 2 </pre></div>
<H3><a name="Octave_nn13"></a>26.3.6 Structures and C++ classes</H3>
<H3><a name="Octave_nn13"></a>30.3.6 Structures and C++ classes</H3>
<p>
@ -453,7 +524,7 @@ ans = 1
Depending on the ownership setting of a <tt>swig_ref</tt>, it may call C++ destructors when its reference count goes to zero. See the section on memory management below for details.
</p>
<H3><a name="Octave_nn15"></a>26.3.7 C++ inheritance</H3>
<H3><a name="Octave_nn15"></a>30.3.7 C++ inheritance</H3>
<p>
@ -462,7 +533,7 @@ This information contains the full class hierarchy. When an indexing operation (
the tree is walked to find a match in the current class as well as any of its bases. The lookup is then cached in the <tt>swig_ref</tt>.
</p>
<H3><a name="Octave_nn17"></a>26.3.8 C++ overloaded functions</H3>
<H3><a name="Octave_nn17"></a>30.3.8 C++ overloaded functions</H3>
<p>
@ -472,7 +543,7 @@ The dispatch function selects which overload to call (if any) based on the passe
<tt>typecheck</tt> typemaps are used to analyze each argument, as well as assign precedence. See the chapter on typemaps for details.
</p>
<H3><a name="Octave_nn18"></a>26.3.9 C++ operators</H3>
<H3><a name="Octave_nn18"></a>30.3.9 C++ operators</H3>
<p>
@ -572,7 +643,11 @@ On the C++ side, the default mappings are as follows:
%rename(__brace) *::operator[];
</pre></div>
<H3><a name="Octave_nn19"></a>26.3.10 Class extension with %extend</H3>
<p>
Octave can also utilise friend (i.e. non-member) operators with a simple %rename: see the example in the Examples/octave/operator directory.
</p>
<H3><a name="Octave_nn19"></a>30.3.10 Class extension with %extend</H3>
<p>
@ -602,7 +677,7 @@ octave:3&gt; printf("%s\n",a);
octave:4&gt; a.__str()
4
</pre></div>
<H3><a name="Octave_nn20"></a>26.3.11 C++ templates</H3>
<H3><a name="Octave_nn20"></a>30.3.11 C++ templates</H3>
<p>
@ -679,14 +754,14 @@ ans =
</pre></div>
<H3><a name="Octave_nn21"></a>26.3.12 C++ Smart Pointers</H3>
<H3><a name="Octave_nn21"></a>30.3.12 C++ Smart Pointers</H3>
<p>
C++ smart pointers are fully supported as in other modules.
</p>
<H3><a name="Octave_nn22"></a>26.3.13 Directors (calling Octave from C++ code)</H3>
<H3><a name="Octave_nn22"></a>30.3.13 Directors (calling Octave from C++ code)</H3>
<p>
@ -747,7 +822,8 @@ Note that you have to enable directors via the %feature directive (see other mod
<tt>subclass()</tt> will accept any number of C++ bases or other <tt>subclass()</tt>'ed objects, <tt>(string,octave_value)</tt> pairs, and <tt>function_handles</tt>. In the first case, these are taken as base classes; in the second case, as named members (either variables or functions, depending on whether the given value is a function handle); in the third case, as member functions whose name is taken from the given function handle. E.g.,
</p>
<div class="targetlang"><pre>
octave:1&gt; B=@(some_var=2) subclass(A(),'some_var',some_var,@some_func,'another_func',@(self) do_stuff())
octave:1&gt; B=@(some_var=2) subclass(A(),'some_var',some_var,@some_func,'another_func',
@(self) do_stuff())
</pre></div>
<p>
You can also assign non-C++ member variables and functions after construct time. There is no support for non-C++ static members.
@ -766,14 +842,14 @@ c-side routine called
octave-side routine called
</pre></div>
<H3><a name="Octave_nn23"></a>26.3.14 Threads</H3>
<H3><a name="Octave_nn23"></a>30.3.14 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>26.3.15 Memory management</H3>
<H3><a name="Octave_nn24"></a>30.3.15 Memory management</H3>
<p>
@ -807,14 +883,14 @@ The %newobject directive may be used to control this behavior for pointers retur
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>26.3.16 STL support</H3>
<H3><a name="Octave_nn25"></a>30.3.16 STL support</H3>
<p>
This is some skeleton support for various STL containers.
Various STL library files are provided for wrapping STL containers.
</p>
<H3><a name="Octave_nn26"></a>26.3.17 Matrix typemaps</H3>
<H3><a name="Octave_nn26"></a>30.3.17 Matrix typemaps</H3>
<p>

281
Doc/Manual/Perl5.html
View file

@ -6,7 +6,7 @@
</head>
<body bgcolor="#ffffff">
<H1><a name="Perl5"></a>27 SWIG and Perl5</H1>
<H1><a name="Perl5"></a>31 SWIG and Perl5</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -40,7 +40,7 @@
<li><a href="#Perl5_nn24">Modules and packages</a>
</ul>
<li><a href="#Perl5_nn25">Input and output parameters</a>
<li><a href="#Perl5_nn26">Exception handling </a>
<li><a href="#Perl5_nn26">Exception handling</a>
<li><a href="#Perl5_nn27">Remapping datatypes with typemaps</a>
<ul>
<li><a href="#Perl5_nn28">A simple typemap example</a>
@ -50,8 +50,8 @@
</ul>
<li><a href="#Perl5_nn32">Typemap Examples</a>
<ul>
<li><a href="#Perl5_nn33">Converting a Perl5 array to a char ** </a>
<li><a href="#Perl5_nn34">Return values </a>
<li><a href="#Perl5_nn33">Converting a Perl5 array to a char **</a>
<li><a href="#Perl5_nn34">Return values</a>
<li><a href="#Perl5_nn35">Returning values from arguments</a>
<li><a href="#Perl5_nn36">Accessing array structure members</a>
<li><a href="#Perl5_nn37">Turning Perl references into C pointers</a>
@ -82,12 +82,12 @@
This chapter describes SWIG's support of Perl5. Although the Perl5
module is one of the earliest SWIG modules, it has continued to evolve
and has been improved greatly with the help of SWIG users. For the
best results, it is recommended that SWIG be used with Perl5.003 or
later. Earlier versions are problematic and SWIG generated extensions
may not compile or run correctly.
best results, it is recommended that SWIG be used with Perl 5.8 or
later. We're no longer testing regularly with older versions, but
Perl 5.6 seems to mostly work, while older versions don't.
</p>
<H2><a name="Perl5_nn2"></a>27.1 Overview</H2>
<H2><a name="Perl5_nn2"></a>31.1 Overview</H2>
<p>
@ -108,12 +108,12 @@ described. Advanced customization features, typemaps, and other
options are found near the end of the chapter.
</p>
<H2><a name="Perl5_nn3"></a>27.2 Preliminaries</H2>
<H2><a name="Perl5_nn3"></a>31.2 Preliminaries</H2>
<p>
To build a Perl5 module, run Swig using the <tt>-perl</tt> option as
follows :
To build a Perl5 module, run SWIG using the <tt>-perl</tt> option as
follows:
</p>
<div class="code"><pre>
@ -133,11 +133,11 @@ To build the module, you will need to compile the file
<tt>example_wrap.c</tt> and link it with the rest of your program.
</p>
<H3><a name="Perl5_nn4"></a>27.2.1 Getting the right header files</H3>
<H3><a name="Perl5_nn4"></a>31.2.1 Getting the right header files</H3>
<p>
In order to compile, SWIG extensions need the following Perl5 header files :</p>
In order to compile, SWIG extensions need the following Perl5 header files:</p>
<div class="code"><pre>
#include "Extern.h"
@ -149,23 +149,23 @@ In order to compile, SWIG extensions need the following Perl5 header files :</p>
These are typically located in a directory like this</p>
<div class="code"><pre>
/usr/lib/perl5/5.00503/i386-linux/CORE
/usr/lib/perl/5.14/CORE
</pre></div>
<p>
The SWIG configuration script automatically tries to locate this directory so
that it can compile examples. However, if you need to find out where the directory is
loaded, an easy way to find out is to run Perl itself.
located, an easy way to find out is to ask Perl itself:
</p>
<div class="code">
<pre>
% perl -e 'use Config; print $Config{archlib};'
/usr/lib/perl5/5.00503/i386-linux
$ perl -e 'use Config; print "$Config{archlib}\n";'
/usr/lib/perl/5.14
</pre>
</div>
<H3><a name="Perl5_nn5"></a>27.2.2 Compiling a dynamic module</H3>
<H3><a name="Perl5_nn5"></a>31.2.2 Compiling a dynamic module</H3>
<p>
@ -176,9 +176,9 @@ using commands like this (shown for Linux):
<div class="code"><pre>
$ swig -perl example.i
% gcc example.c
% gcc -c example_wrap.c -I/usr/lib/perl5/5.00503/i386-linux/CORE -Dbool=char
% gcc -shared example.o example_wrap.o -o example.so
$ gcc -fPIC example.c
$ gcc -fPIC -c example_wrap.c -I/usr/lib/perl/5.14/CORE -Dbool=char
$ gcc -shared example.o example_wrap.o -o example.so
</pre></div>
<p>
@ -198,13 +198,13 @@ the target should be named `<tt>example.so</tt>',
`<tt>example.sl</tt>', or the appropriate dynamic module name on your system.
</p>
<H3><a name="Perl5_nn6"></a>27.2.3 Building a dynamic module with MakeMaker</H3>
<H3><a name="Perl5_nn6"></a>31.2.3 Building a dynamic module with MakeMaker</H3>
<p>
It is also possible to use Perl to build dynamically loadable modules
for you using the MakeMaker utility. To do this, write a Perl
script such as the following :</p>
script such as the following:</p>
<div class="targetlang"><pre>
# File : Makefile.PL
@ -218,12 +218,12 @@ WriteMakefile(
</pre></div>
<p>
Now, to build a module, simply follow these steps :</p>
Now, to build a module, simply follow these steps:</p>
<div class="code"><pre>
% perl Makefile.PL
% make
% make install
$ perl Makefile.PL
$ make
$ make install
</pre></div>
<p>
@ -232,17 +232,17 @@ the preferred approach to compilation. More information about MakeMaker can be
found in "Programming Perl, 2nd ed." by Larry Wall, Tom Christiansen,
and Randal Schwartz.</p>
<H3><a name="Perl5_nn7"></a>27.2.4 Building a static version of Perl</H3>
<H3><a name="Perl5_nn7"></a>31.2.4 Building a static version of Perl</H3>
<p>
If you machine does not support dynamic loading or if you've tried to
use it without success, you can build a new version of the Perl
interpreter with your SWIG extensions added to it. To build a static
extension, you first need to invoke SWIG as follows :</p>
extension, you first need to invoke SWIG as follows:</p>
<div class="code"><pre>
% swig -perl -static example.i
$ swig -perl -static example.i
</pre></div>
<p>
@ -253,7 +253,7 @@ By default SWIG includes code for dynamic loading, but the
Next, you will need to supply a <tt>main()</tt> function that
initializes your extension and starts the Perl interpreter. While,
this may sound daunting, SWIG can do this for you automatically as
follows :</p>
follows:</p>
<div class="targetlang"><pre>
%module example
@ -264,14 +264,14 @@ extern int fact(int);
%}
// Include code for rebuilding Perl
%include perlmain.i
%include &lt;perlmain.i&gt;
</pre></div>
<p>
The same thing can be accomplished by running SWIG as follows :</p>
The same thing can be accomplished by running SWIG as follows:</p>
<div class="code"><pre>
% swig -perl -static -lperlmain.i example.i
$ swig -perl -static -lperlmain.i example.i
</pre></div>
<p>
@ -290,7 +290,7 @@ for a dynamic module, but change the link line to something like this:
</p>
<div class="code"><pre>
% gcc example.o example_wrap.o -L/usr/lib/perl5/5.00503/i386-linux/CORE \
$ gcc example.o example_wrap.o -L/usr/lib/perl/5.14/CORE \
-lperl -lsocket -lnsl -lm -o myperl
</pre></div>
@ -301,7 +301,7 @@ added to it. Depending on your machine, you may need to link with
additional libraries such as <tt>-lsocket, -lnsl, -ldl</tt>, etc.
</p>
<H3><a name="Perl5_nn8"></a>27.2.5 Using the module</H3>
<H3><a name="Perl5_nn8"></a>31.2.5 Using the module</H3>
<p>
@ -323,9 +323,7 @@ A common error received by first-time users is the following:
<div class="targetlang">
<pre>
use example;
Can't locate example.pm in @INC (@INC contains: /usr/lib/perl5/5.00503/i386-lin
ux /usr/lib/perl5/5.00503 /usr/lib/perl5/site_perl/5.005/i386-linux /usr/lib/pe
rl5/site_perl/5.005 .) at - line 1.
Can't locate example.pm in @INC (@INC contains: /etc/perl /usr/local/lib/perl/5.14.2 /usr/local/share/perl/5.14.2 /usr/lib/perl5 /usr/share/perl5 /usr/lib/perl/5.14 /usr/share/perl/5.14 /usr/local/lib/site_perl .) at - line 1.
BEGIN failed--compilation aborted at - line 1.
</pre>
</div>
@ -363,7 +361,7 @@ Another common error is the following:
<pre>
use example;
Can't load './example.so' for module example: ./example.so:
undefined symbol: Foo at /usr/lib/perl5/5.00503/i386-linux/DynaLoader.pm line 169.
undefined symbol: Foo at /usr/lib/perl/5.14/i386-linux/DynaLoader.pm line 169.
at - line 1
BEGIN failed--compilation aborted at - line 1.
@ -409,7 +407,7 @@ error when you try to use your module:
<pre>
use example;
Can't load './example.so' for module example: libfoo.so: cannot open shared object file:
No such file or directory at /usr/lib/perl5/5.00503/i386-linux/DynaLoader.pm line 169.
No such file or directory at /usr/lib/perl/5.14/i386-linux/DynaLoader.pm line 169.
at - line 1
BEGIN failed--compilation aborted at - line 1.
@ -456,7 +454,7 @@ system configuration (this requires root access and you will need to
read the man pages).
</p>
<H3><a name="Perl5_nn9"></a>27.2.6 Compilation problems and compiling with C++</H3>
<H3><a name="Perl5_nn9"></a>31.2.6 Compilation problems and compiling with C++</H3>
<p>
@ -472,10 +470,10 @@ compiler. For example:
</p>
<div class="code"><pre>
% swig -c++ -perl example.i
% g++ -c example.cxx
% g++ -c example_wrap.cxx -I/usr/lib/perl5/5.00503/i386-linux/CORE
% <b>g++ -shared example.o example_wrap.o -o example.so</b>
$ swig -c++ -perl example.i
$ g++ -fPIC -c example.cxx
$ g++ -fPIC -c example_wrap.cxx -I/usr/lib/perl/5.14/i386-linux/CORE
$ <b>g++ -shared example.o example_wrap.o -o example.so</b>
</pre></div>
<p>
@ -485,10 +483,10 @@ Solaris, you often need to add an extra library <tt>-lCrun</tt> like this:
</p>
<div class="code"><pre>
% swig -c++ -perl example.i
% g++ -c example.cxx
% g++ -c example_wrap.cxx -I/usr/lib/perl5/5.00503/i386-linux/CORE
% g++ -shared example.o example_wrap.o -o example.so <b>-lCrun</b>
$ swig -c++ -perl example.i
$ CC -c example.cxx
$ CC -c example_wrap.cxx -I/usr/lib/perl/5.14/i386-linux/CORE
$ CC -shared example.o example_wrap.o -o example.so <b>-lCrun</b>
</pre></div>
<p>
@ -503,7 +501,7 @@ it needs to be. So you should compile the wrapper like:
</p>
<div class="code"><pre>
% g++ -c example_wrap.cxx -I/usr/lib/perl/5.8.0/CORE -D_GNU_SOURCE
$ g++ -fPIC -c example_wrap.cxx -I/usr/lib/perl/5.8.0/CORE -D_GNU_SOURCE
</pre></div>
<p>
@ -511,7 +509,7 @@ it needs to be. So you should compile the wrapper like:
</p>
<div class="code"><pre>
% perl -e 'use Config; print $Config{ccflags};'
$ perl -e 'use Config; print "$Config{ccflags}\n";'
</pre></div>
<p>
@ -519,8 +517,8 @@ So you could also compile the wrapper like
</p>
<div class="code"><pre>
% g++ -c example_wrap.cxx -I/usr/lib/perl/5.8.0/CORE \
`perl -e 'use Config; print $Config{ccflags}'`
$ g++ -fPIC -c example_wrap.cxx -I/usr/lib/perl/5.8.0/CORE \
`perl -MConfig -e 'print $Config{ccflags}'`
</pre></div>
<p>
@ -568,8 +566,8 @@ can behave strangely when working with multiple modules.
<p>
It should be noted that you may get a lot of error messages
about the `<tt>bool</tt>' datatype when compiling a C++ Perl module. If
you experience this problem, you can try the following :</p>
about the '<tt>bool</tt>' datatype when compiling a C++ Perl module. If
you experience this problem, you can try the following:</p>
<ul>
<li>Use <tt>-DHAS_BOOL</tt> when compiling the SWIG wrapper code
@ -599,7 +597,7 @@ have to find the macro that conflicts and add an #undef into the .i file. Pleas
any conflicting macros you find to <a href="http://www.swig.org/mail.html">swig-user mailing list</a>.
</p>
<H3><a name="Perl5_nn10"></a>27.2.7 Compiling for 64-bit platforms</H3>
<H3><a name="Perl5_nn10"></a>31.2.7 Compiling for 64-bit platforms</H3>
<p>
@ -626,7 +624,7 @@ also introduce problems on platforms that support more than one
linking standard (e.g., -o32 and -n32 on Irix).
</p>
<H2><a name="Perl5_nn11"></a>27.3 Building Perl Extensions under Windows</H2>
<H2><a name="Perl5_nn11"></a>31.3 Building Perl Extensions under Windows</H2>
<p>
@ -637,13 +635,13 @@ section assumes you are using SWIG with Microsoft Visual C++
although the procedure may be similar with other compilers.
</p>
<H3><a name="Perl5_nn12"></a>27.3.1 Running SWIG from Developer Studio</H3>
<H3><a name="Perl5_nn12"></a>31.3.1 Running SWIG from Developer Studio</H3>
<p>
If you are developing your application within Microsoft developer
studio, SWIG can be invoked as a custom build option. The process
roughly requires these steps :</p>
roughly requires these steps:</p>
<ul>
<li>Open up a new workspace and use the AppWizard to select a DLL
@ -651,7 +649,7 @@ project.
<li>Add both the SWIG interface file (the .i file), any supporting C
files, and the name of the wrapper file that will be created by SWIG
(ie. <tt>example_wrap.c</tt>). Note : If using C++, choose a
(ie. <tt>example_wrap.c</tt>). Note: If using C++, choose a
different suffix for the wrapper file such as
<tt>example_wrap.cxx</tt>. Don't worry if the wrapper file doesn't
exist yet--Developer studio will keep a reference to it around.
@ -689,7 +687,7 @@ Now, assuming you made it this far, SWIG will be automatically invoked when
you build your project. Any changes made to the interface file will
result in SWIG being automatically invoked to produce a new version of
the wrapper file. To run your new Perl extension, simply run Perl and
use the use command as normal. For example :
use the use command as normal. For example:
</p>
<div class="targetlang"><pre>
@ -700,7 +698,7 @@ print "$a\n";
</pre></div>
<H3><a name="Perl5_nn13"></a>27.3.2 Using other compilers</H3>
<H3><a name="Perl5_nn13"></a>31.3.2 Using other compilers</H3>
<p>
@ -708,7 +706,7 @@ SWIG is known to work with Cygwin and may work with other compilers on Windows.
For general hints and suggestions refer to the <a href="Windows.html#Windows">Windows</a> chapter.
</p>
<H2><a name="Perl5_nn14"></a>27.4 The low-level interface</H2>
<H2><a name="Perl5_nn14"></a>31.4 The low-level interface</H2>
<p>
@ -718,7 +716,7 @@ can be used to control your application. However, it is also used to
construct more user-friendly proxy classes as described in the next section.
</p>
<H3><a name="Perl5_nn15"></a>27.4.1 Functions</H3>
<H3><a name="Perl5_nn15"></a>31.4.1 Functions</H3>
<p>
@ -741,7 +739,7 @@ use example;
$a = &amp;example::fact(2);
</pre></div>
<H3><a name="Perl5_nn16"></a>27.4.2 Global variables</H3>
<H3><a name="Perl5_nn16"></a>31.4.2 Global variables</H3>
<p>
@ -758,7 +756,7 @@ double Spam;
</pre></div>
<p>
is accessed as follows :</p>
is accessed as follows:</p>
<div class="targetlang"><pre>
use example;
@ -811,11 +809,11 @@ extern char *path; // Declared later in the input
</pre>
</div>
<H3><a name="Perl5_nn17"></a>27.4.3 Constants</H3>
<H3><a name="Perl5_nn17"></a>31.4.3 Constants</H3>
<p>
Constants are wrapped as read-only Perl variables. For example:
By default, constants are wrapped as read-only Perl variables. For example:
</p>
<div class="code">
@ -838,14 +836,27 @@ $example::FOO = 2; # Error
</pre>
</div>
<H3><a name="Perl5_nn18"></a>27.4.4 Pointers</H3>
<p>
Alternatively, if you use swig's <tt>-const</tt> option, constants are wrapped
such that the leading $ isn't required (by using a constant subroutine), which
usually gives a more natural Perl interface, for example:
</p>
<div class="targetlang">
<pre>
use example;
print example::FOO,"\n";
</pre>
</div>
<H3><a name="Perl5_nn18"></a>31.4.4 Pointers</H3>
<p>
SWIG represents pointers as blessed references. A blessed reference
is the same as a Perl reference except that it has additional
information attached to it indicating what kind of reference it
is. That is, if you have a C declaration like this :</p>
is. That is, if you have a C declaration like this:</p>
<div class="code"><pre>
Matrix *new_Matrix(int n, int m);
@ -867,7 +878,7 @@ generated.</p>
<p>
To check to see if a value is the NULL pointer, use the
<tt>defined()</tt> command :</p>
<tt>defined()</tt> command:</p>
<div class="targetlang"><pre>
if (defined($ptr)) {
@ -879,7 +890,7 @@ if (defined($ptr)) {
</pre></div>
<p>
To create a NULL pointer, you should pass the <tt>undef </tt>value to
To create a NULL pointer, you should pass the <tt>undef</tt> value to
a function.
</p>
@ -889,9 +900,9 @@ pointer that SWIG wrapper functions return. Suppose that <tt>$a</tt>
and <tt>$b</tt> are two references that point to the same C object.
In general, <tt>$a</tt> and <tt>$b</tt> will be different--since they
are different references. Thus, it is a mistake to check the equality
of <tt>$a </tt>and <tt>$b</tt> to check the equality of two C
of <tt>$a</tt> and <tt>$b</tt> to check the equality of two C
pointers. The correct method to check equality of C pointers is to
dereference them as follows :
dereference them as follows:
</p>
<div class="targetlang"><pre>
@ -947,7 +958,7 @@ as XS and <tt>xsubpp</tt>. Given the advancement of the SWIG typesystem and the
SWIG and XS, this is no longer supported.
</p>
<H3><a name="Perl5_nn19"></a>27.4.5 Structures</H3>
<H3><a name="Perl5_nn19"></a>31.4.5 Structures</H3>
<p>
@ -1081,12 +1092,12 @@ void Bar_f_set(Bar *b, Foo *val) {
</div>
<H3><a name="Perl5_nn20"></a>27.4.6 C++ classes</H3>
<H3><a name="Perl5_nn20"></a>31.4.6 C++ classes</H3>
<p>
C++ classes are wrapped by building a set of low level accessor functions.
Consider the following class :
Consider the following class:
</p>
<div class="code"><pre>
@ -1104,7 +1115,7 @@ static void print(List *l);
</pre></div>
<p>
When wrapped by SWIG, the following functions are created :
When wrapped by SWIG, the following functions are created:
</p>
<div class="code"><pre>
@ -1146,7 +1157,7 @@ provides direct access to C++ objects. A higher level interface using Perl prox
can be built using these low-level accessors. This is described shortly.
</p>
<H3><a name="Perl5_nn21"></a>27.4.7 C++ classes and type-checking</H3>
<H3><a name="Perl5_nn21"></a>31.4.7 C++ classes and type-checking</H3>
<p>
@ -1182,7 +1193,7 @@ If necessary, the type-checker also adjusts the value of the pointer (as is nece
multiple inheritance is used).
</p>
<H3><a name="Perl5_nn22"></a>27.4.8 C++ overloaded functions</H3>
<H3><a name="Perl5_nn22"></a>31.4.8 C++ overloaded functions</H3>
<p>
@ -1226,7 +1237,7 @@ example::Spam_foo_d($s,3.14);
Please refer to the "SWIG Basics" chapter for more information.
</p>
<H3><a name="Perl5_nn23"></a>27.4.9 Operators</H3>
<H3><a name="Perl5_nn23"></a>31.4.9 Operators</H3>
<p>
@ -1253,17 +1264,17 @@ The following C++ operators are currently supported by the Perl module:
<li>operator or </li>
</ul>
<H3><a name="Perl5_nn24"></a>27.4.10 Modules and packages</H3>
<H3><a name="Perl5_nn24"></a>31.4.10 Modules and packages</H3>
<p>
When you create a SWIG extension, everything gets placed into
a single Perl module. The name of the module is determined by the
<tt>%module</tt> directive. To use the module, do the following :
<tt>%module</tt> directive. To use the module, do the following:
</p>
<div class="targetlang"><pre>
% perl5
$ perl5
use example; # load the example module
print example::fact(4),"\n" # Call a function in it
24
@ -1329,17 +1340,17 @@ nested namespace simply provide the fully qualified name in your
<!--
<p>
This can be changed by giving SWIG the -package
option :
option:
</p>
<div class="code"><pre>
% swig -perl -package Foo example.i
$ swig -perl -package Foo example.i
</pre></div>
<p>
In this case, you still create a module called `<tt>example</tt>' exactly as before, but
all of the functions in that module will be installed into the package
`<tt>Foo</tt>.' For example :
`<tt>Foo</tt>.' For example:
</p>
<div class="targetlang"><pre>
@ -1348,7 +1359,7 @@ print Foo::fact(4),"\n"; # Call a function in package FooBar
</pre></div>
-->
<H2><a name="Perl5_nn25"></a>27.5 Input and output parameters</H2>
<H2><a name="Perl5_nn25"></a>31.5 Input and output parameters</H2>
<p>
@ -1543,7 +1554,7 @@ example:
<div class="code">
<pre>
%module example
%include typemaps.i
%include "typemaps.i"
void add(int x, int y, int *REFERENCE);
</pre>
@ -1567,7 +1578,7 @@ print "$c\n";
<b>Note:</b> The <tt>REFERENCE</tt> feature is only currently supported for numeric types (integers and floating point).
</p>
<H2><a name="Perl5_nn26"></a>27.6 Exception handling </H2>
<H2><a name="Perl5_nn26"></a>31.6 Exception handling</H2>
<p>
@ -1575,7 +1586,7 @@ The SWIG <tt>%exception</tt> directive can be used to create a
user-definable exception handler for converting exceptions in your
C/C++ program into Perl exceptions. The chapter on customization features
contains more details, but suppose you have a C++ class like the
following :
following:
</p>
<div class="code"><pre>
@ -1732,7 +1743,7 @@ This is still supported, but it is deprecated. The newer <tt>%exception</tt> di
functionality, but it has additional capabilities that make it more powerful.
</p>
<H2><a name="Perl5_nn27"></a>27.7 Remapping datatypes with typemaps</H2>
<H2><a name="Perl5_nn27"></a>31.7 Remapping datatypes with typemaps</H2>
<p>
@ -1749,7 +1760,7 @@ Typemaps are only used if you want to change some aspect of the primitive
C-Perl interface.
</p>
<H3><a name="Perl5_nn28"></a>27.7.1 A simple typemap example</H3>
<H3><a name="Perl5_nn28"></a>31.7.1 A simple typemap example</H3>
<p>
@ -1783,7 +1794,7 @@ The <tt>$input</tt> variable is the input object (usually a <tt>SV *</tt>).
</p>
<p>
When this example is used in Perl5, it will operate as follows :
When this example is used in Perl5, it will operate as follows:
</p>
<div class="targetlang"><pre>
@ -1792,7 +1803,7 @@ $n = example::fact(6);
print "$n\n";
...
Output :
Output:
Received an integer : 6
720
</pre></div>
@ -1853,7 +1864,7 @@ example::count("e","Hello World");
</div>
<H3><a name="Perl5_nn29"></a>27.7.2 Perl5 typemaps</H3>
<H3><a name="Perl5_nn29"></a>31.7.2 Perl5 typemaps</H3>
<p>
@ -1958,7 +1969,7 @@ Return of C++ member data (all languages).
Check value of input parameter.
</div>
<H3><a name="Perl5_nn30"></a>27.7.3 Typemap variables</H3>
<H3><a name="Perl5_nn30"></a>31.7.3 Typemap variables</H3>
<p>
@ -2029,7 +2040,7 @@ properly assigned.
The Perl name of the wrapper function being created.
</div>
<H3><a name="Perl5_nn31"></a>27.7.4 Useful functions</H3>
<H3><a name="Perl5_nn31"></a>31.7.4 Useful functions</H3>
<p>
@ -2098,7 +2109,7 @@ int sv_isa(SV *, char *0;
</div>
<H2><a name="Perl5_nn32"></a>27.8 Typemap Examples</H2>
<H2><a name="Perl5_nn32"></a>31.8 Typemap Examples</H2>
<p>
@ -2107,7 +2118,7 @@ might look at the files "<tt>perl5.swg</tt>" and "<tt>typemaps.i</tt>" in
the SWIG library.
</p>
<H3><a name="Perl5_nn33"></a>27.8.1 Converting a Perl5 array to a char ** </H3>
<H3><a name="Perl5_nn33"></a>31.8.1 Converting a Perl5 array to a char **</H3>
<p>
@ -2160,7 +2171,7 @@ reference to be used as a char ** datatype.
};
myav = av_make(len,svs);
free(svs);
$result = newRV((SV*)myav);
$result = newRV_noinc((SV*)myav);
sv_2mortal($result);
argvi++;
}
@ -2187,7 +2198,7 @@ char **get_args() {
<p>
When this module is compiled, the wrapped C functions can be used in a
Perl script as follows :
Perl script as follows:
</p>
<div class="targetlang"><pre>
@ -2199,7 +2210,7 @@ print @$b,"\n"; # Print it out
</pre></div>
<H3><a name="Perl5_nn34"></a>27.8.2 Return values </H3>
<H3><a name="Perl5_nn34"></a>31.8.2 Return values</H3>
<p>
@ -2214,7 +2225,7 @@ number of output values.
<p>
The total number of return values should not exceed the number of
input values unless you explicitly extend the argument stack. This
can be done using the <tt>EXTEND()</tt> macro as in :
can be done using the <tt>EXTEND()</tt> macro as in:
</p>
<div class="code"><pre>
@ -2228,7 +2239,7 @@ can be done using the <tt>EXTEND()</tt> macro as in :
}
</pre></div>
<H3><a name="Perl5_nn35"></a>27.8.3 Returning values from arguments</H3>
<H3><a name="Perl5_nn35"></a>31.8.3 Returning values from arguments</H3>
<p>
@ -2273,7 +2284,7 @@ int multout(double a, double b, double *OUTPUT, double *OUTPUT);
<p>
When this function is called, the output arguments are appended to the stack used
to return results. This shows up an array in Perl.
For example :
For example:
</p>
<div class="targetlang"><pre>
@ -2282,11 +2293,11 @@ print "multout(7,13) = @r\n";
($x,$y) = multout(7,13);
</pre></div>
<H3><a name="Perl5_nn36"></a>27.8.4 Accessing array structure members</H3>
<H3><a name="Perl5_nn36"></a>31.8.4 Accessing array structure members</H3>
<p>
Consider the following data structure :
Consider the following data structure:
</p>
<div class="code"><pre>
@ -2345,13 +2356,13 @@ the "in" typemap in the previous section would be used to convert an
to copy the converted array into a C data structure.
</p>
<H3><a name="Perl5_nn37"></a>27.8.5 Turning Perl references into C pointers</H3>
<H3><a name="Perl5_nn37"></a>31.8.5 Turning Perl references into C pointers</H3>
<p>
A frequent confusion on the SWIG mailing list is errors caused by the
mixing of Perl references and C pointers. For example, suppose you
have a C function that modifies its arguments like this :
have a C function that modifies its arguments like this:
</p>
<div class="code"><pre>
@ -2361,7 +2372,7 @@ void add(double a, double b, double *c) {
</pre></div>
<p>
A common misinterpretation of this function is the following Perl script :
A common misinterpretation of this function is the following Perl script:
</p>
<div class="targetlang"><pre>
@ -2398,7 +2409,7 @@ To make this work with a reference, you can use a typemap such as this:
</pre></div>
<p>
Now, if you place this before the add function, you can do this :
Now, if you place this before the add function, you can do this:
</p>
<div class="targetlang"><pre>
@ -2410,7 +2421,7 @@ print "$c\n";
</pre></div>
<H3><a name="Perl5_nn38"></a>27.8.6 Pointer handling</H3>
<H3><a name="Perl5_nn38"></a>31.8.6 Pointer handling</H3>
<p>
@ -2489,7 +2500,7 @@ For example:
</pre>
</div>
<H2><a name="Perl5_nn39"></a>27.9 Proxy classes</H2>
<H2><a name="Perl5_nn39"></a>31.9 Proxy classes</H2>
<p>
@ -2505,7 +2516,7 @@ to the underlying code. This section describes the implementation
details of the proxy interface.
</p>
<H3><a name="Perl5_nn40"></a>27.9.1 Preliminaries</H3>
<H3><a name="Perl5_nn40"></a>31.9.1 Preliminaries</H3>
<p>
@ -2527,11 +2538,11 @@ SWIG creates a collection of high-level Perl wrappers. In your scripts, you wil
high level wrappers. The wrappers, in turn, interact with the low-level procedural module.
</p>
<H3><a name="Perl5_nn41"></a>27.9.2 Structure and class wrappers</H3>
<H3><a name="Perl5_nn41"></a>31.9.2 Structure and class wrappers</H3>
<p>
Suppose you have the following SWIG interface file :
Suppose you have the following SWIG interface file:
</p>
<div class="code"><pre>
@ -2653,13 +2664,13 @@ $v-&gt;DESTROY();
</pre></div>
<H3><a name="Perl5_nn42"></a>27.9.3 Object Ownership</H3>
<H3><a name="Perl5_nn42"></a>31.9.3 Object Ownership</H3>
<p>
In order for proxy classes to work properly, it is necessary for Perl
to manage some mechanism of object ownership. Here's the crux of the
problem---suppose you had a function like this :
problem---suppose you had a function like this:
</p>
<div class="code"><pre>
@ -2672,7 +2683,7 @@ Vector *Vector_get(Vector *v, int index) {
This function takes a Vector pointer and returns a pointer to another
Vector. Such a function might be used to manage arrays or lists of
vectors (in C). Now contrast this function with the constructor for a
Vector object :
Vector object:
</p>
<div class="code"><pre>
@ -2714,7 +2725,7 @@ corresponding Perl object (this situation turns out to come up
frequently when constructing objects like linked lists and trees).
When C takes possession of an object, you can change Perl's ownership
by simply deleting the object from the <tt>%OWNER</tt> hash. This is
done using the <tt>DISOWN </tt>method.
done using the <tt>DISOWN</tt> method.
</p>
<div class="targetlang"><pre>
@ -2740,11 +2751,11 @@ counting, garbage collection, or advanced features one might find in
sophisticated languages.
</p>
<H3><a name="Perl5_nn43"></a>27.9.4 Nested Objects</H3>
<H3><a name="Perl5_nn43"></a>31.9.4 Nested Objects</H3>
<p>
Suppose that we have a new object that looks like this :
Suppose that we have a new object that looks like this:
</p>
<div class="code"><pre>
@ -2761,7 +2772,7 @@ struct Particle {
In this case, the members of the structure are complex objects that
have already been encapsulated in a Perl proxy class. To handle
these correctly, we use the <tt>%BLESSEDMEMBERS</tt> hash which would
look like this (along with some supporting code) :
look like this (along with some supporting code):
</p>
<div class="targetlang"><pre>
@ -2783,7 +2794,7 @@ unmodified.
</p>
<p>
This implementation allows us to operate on nested structures as follows :
This implementation allows us to operate on nested structures as follows:
</p>
<div class="targetlang"><pre>
@ -2793,12 +2804,12 @@ $p-&gt;{f}-&gt;{x} = 0.0;
%${$p-&gt;{v}} = ( x=&gt;0, y=&gt;0, z=&gt;0);
</pre></div>
<H3><a name="Perl5_nn44"></a>27.9.5 Proxy Functions</H3>
<H3><a name="Perl5_nn44"></a>31.9.5 Proxy Functions</H3>
<p>
When functions take arguments involving a complex object, it is
sometimes necessary to write a proxy function. For example :
sometimes necessary to write a proxy function. For example:
</p>
<div class="code"><pre>
@ -2809,7 +2820,7 @@ double dot_product(Vector *v1, Vector *v2);
Since Vector is an object already wrapped into a proxy class, we need
to modify this function to accept arguments that are given in the form
of tied hash tables. This is done by creating a Perl function like
this :
this:
</p>
<div class="targetlang"><pre>
@ -2827,13 +2838,13 @@ This function replaces the original function, but operates in an
identical manner.
</p>
<H3><a name="Perl5_nn45"></a>27.9.6 Inheritance</H3>
<H3><a name="Perl5_nn45"></a>31.9.6 Inheritance</H3>
<p>
Simple C++ inheritance is handled using the Perl <tt>@ISA</tt> array
in each class package. For example, if you have the following
interface file :
interface file:
</p>
<div class="code"><pre>
@ -2868,7 +2879,7 @@ public:
</pre></div>
<p>
The resulting, Perl wrapper class will create the following code :
The resulting, Perl wrapper class will create the following code:
</p>
<div class="targetlang"><pre>
@ -2903,12 +2914,12 @@ particular, inheritance of data members is extremely tricky (and I'm
not even sure if it really works).
</p>
<H3><a name="Perl5_nn46"></a>27.9.7 Modifying the proxy methods</H3>
<H3><a name="Perl5_nn46"></a>31.9.7 Modifying the proxy methods</H3>
<p>
It is possible to override the SWIG generated proxy/shadow methods, using <tt>%feature("shadow")</tt>.
It works like all the other <a href="Customization.html#features">%feature directives</a>.
It works like all the other <a href="Customization.html#Customization_features">%feature directives</a>.
Here is a simple example showing how to add some Perl debug code to the constructor:
</p>
@ -2931,7 +2942,7 @@ public:
};
</pre></div>
<H2><a name="Perl5_nn47"></a>27.10 Adding additional Perl code</H2>
<H2><a name="Perl5_nn47"></a>31.10 Adding additional Perl code</H2>
<p>

722
Doc/Manual/Php.html
View file

@ -7,14 +7,13 @@
</head>
<body bgcolor="#ffffff">
<H1><a name="Php"></a>28 SWIG and PHP</H1>
<H1><a name="Php"></a>32 SWIG and PHP</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="#Php_nn1">Generating PHP Extensions</a>
<ul>
<li><a href="#Php_nn1_1">Building a loadable extension</a>
<li><a href="#Php_nn1_2">Building extensions into PHP</a>
<li><a href="#Php_nn1_3">Using PHP Extensions</a>
</ul>
<li><a href="#Php_nn2">Basic PHP interface</a>
@ -33,6 +32,16 @@
</ul>
<li><a href="#Php_nn2_7">PHP Pragmas, Startup and Shutdown code</a>
</ul>
<li><a href="#Php_nn3">Cross language polymorphism</a>
<ul>
<li><a href="#Php_nn3_1">Enabling directors</a>
<li><a href="#Php_nn3_2">Director classes</a>
<li><a href="#Php_nn3_3">Ownership and object destruction</a>
<li><a href="#Php_nn3_4">Exception unrolling</a>
<li><a href="#Php_nn3_5">Overhead and code bloat</a>
<li><a href="#Php_nn3_6">Typemaps</a>
<li><a href="#Php_nn3_7">Miscellaneous</a>
</ul>
</ul>
</div>
<!-- INDEX -->
@ -40,24 +49,27 @@
<p>
<b>Caution: This chapter (and module!) is still under construction</b>
SWIG supports generating wrappers for PHP5. Support for PHP4 was removed
in SWIG 1.3.37. The PHP developers are no longer making new PHP4 releases,
and won't even be patching critical security issues after 2008-08-08, so it
doesn't make much sense for SWIG to continue to support PHP4 now. If you
really need to continue to use PHP4, just stick with SWIG 1.3.36.
</p>
<p>
Currently any PHP5 release should work, but we don't regularly test with
PHP &lt; 5.3.
</p>
<p>
In this chapter, we discuss SWIG's support of PHP. The PHP module
was extensively rewritten in release 1.3.26, and although it is
significantly more functional, it still does not implement all the
features available in some of the other languages.
was extensively rewritten in release 1.3.26, and support for generating
OO wrappers for PHP5 was added in 1.3.30. The PHP module now supports most
of the features available in some of the other languages.
</p>
<p>
The examples and test cases have been developed with PHP4. Release
1.3.30 added support for generating PHP5 class wrappers for C++
libraries.
</p>
<p>
In order to use this module, you will need to have a copy of the PHP4 or PHP5
In order to use this module, you will need to have a copy of the PHP5
include files to compile the SWIG generated files. If you installed
PHP from a binary package, you may need to install a "php-dev" or "php-devel"
package for these to be installed. You can find out where these files are
@ -67,7 +79,7 @@ your extension into php directly, you will need the complete PHP source tree
available.
</p>
<H2><a name="Php_nn1"></a>28.1 Generating PHP Extensions</H2>
<H2><a name="Php_nn1"></a>32.1 Generating PHP Extensions</H2>
<p>
@ -88,19 +100,20 @@ you wish to statically link the extension into the php interpreter.
The third file,
<tt>example.php</tt> can be included by PHP scripts. It attempts to
dynamically load the extension and contains extra php code specified
in the interface file. If wrapping C++ code for PHP5, it will
in the interface file. If wrapping C++ code with PHP classes, it will
also contain PHP5 class wrappers.
</p>
<p>
Swig can generate PHP extensions from C++ libraries as well when
SWIG can generate PHP extensions from C++ libraries as well when
given the <tt>-c++</tt> option. The support for C++ is discussed in
more detail in <a href="#Php_nn2_6">section 27.2.6</a>.
</p>
<p>
The usual (and recommended) way is to build the extension as a separate
dynamically loaded module. You can then specify that this be loaded
dynamically loaded module (which is supported by all modern operating
systems). You can then specify that this be loaded
automatically in <tt>php.ini</tt> or load it explicitly for any script which
needs it.
</p>
@ -110,17 +123,16 @@ It is also possible to rebuild PHP from source so that your module is
statically linked into the php executable/library. This is a lot more
work, and also requires a full rebuild of PHP to update your module,
and it doesn't play nicely with package system. We don't recommend
this approach, but if you really want to do this, the <tt>-phpfull</tt>
command line argument to swig may be of use - see below for details.
this approach, or provide explicit support for it.
</p>
<H3><a name="Php_nn1_1"></a>28.1.1 Building a loadable extension</H3>
<H3><a name="Php_nn1_1"></a>32.1.1 Building a loadable extension</H3>
<p>
To build your module as a dynamically loadable extension, use compilation
commands like these (if you aren't using GCC, the commands will be different,
and there may be so variation between platforms - these commands should at
and there may be some variation between platforms - these commands should at
least work for Linux though):
</p>
@ -129,135 +141,7 @@ least work for Linux though):
gcc -shared example_wrap.o -o example.so
</pre></div>
<p>
There is a deprecated <tt>-make</tt> command line argument to swig which will
generate an additional file <tt>makefile</tt> which can usually build the
extension (at least on some UNIX platforms), but the Makefile generated isn't
very flexible, and the commands required are trivial so it is simpler to just
add them to your Makefile or other build system directly. We recommend that
you don't use <tt>-make</tt> and it's likely to be removed at some point.
</p>
<H3><a name="Php_nn1_2"></a>28.1.2 Building extensions into PHP</H3>
<p>
Note that we don't recommend this approach - it's cleaner and simpler to
use dynamically loadable modules, which are supported by all modern OSes.
Support for this may be discontinued entirely in the future.
</p>
<p>
It is possible to rebuild PHP itself with your module statically linked
in. To do this, you can use the <tt>-phpfull</tt> command line option to
swig. Using this option will generate three additional files. The first
extra file, <tt>config.m4</tt> contains the m4 and shell code needed to
enable the extension as part of the PHP build process. The second
extra file, <tt>Makefile.in</tt> contains the information needed to
build the final Makefile after substitutions. The third and final
extra file, <tt>CREDITS</tt> should contain the credits for the
extension.
</p>
<p>
To build with phpize, after you have run swig you will need to run the
'phpize' command (installed as part of php) in the same
directory. This re-creates the php build environment in that
directory. It also creates a configure file which includes the shell
code from the config.m4 that was generated by SWIG, this configure
script will accept a command line argument to enable the extension to
be run (by default the command line argument is --enable-modulename,
however you can edit the config.m4 file before running phpize to
accept --with-modulename. You can also add extra tests in config.m4 to
check that a correct library version is installed or correct header
files are included, etc, but you must edit this file before running
phpize.) You can also get SWIG to generate simple extra tests for
libraries and header files for you.
</p>
<div class="code"><pre>
swig -php -phpfull
</pre></div>
<p>
If you depend on source files not generated by SWIG, before generating
the configure file, you may need to edit the <tt>Makefile.in</tt>
file. This contains the names of the source files to compile (just the
wrapper file by default) and any additional libraries needed to be
linked in. If there are extra C files to compile, you will need to add
them to the <tt>Makefile.in</tt>, or add the names of libraries if they are
needed. In simple cases SWIG is pretty good at generating a complete
<tt>Makefile.in</tt> and <tt>config.m4</tt> which need no further editing.
</p>
<p>
You then run the configure script with the command line argument needed
to enable the extension. Then run make, which builds the extension.
The extension object file will be left in the modules sub directory, you can
move it to wherever it is convenient to call from your php script.
</p>
<p>
When using <tt>-phpfull</tt>, swig also accepts the following
additional optional arguments:
</p>
<ul>
<li><tt>-withincs "&lt;incs&gt;"</tt> Adds include files to the config.m4 file.
<li><tt>-withlibs "&lt;libs&gt;"</tt> Links with the specified libraries.
<li><tt>-withc "&lt;files&gt;"</tt> Compiles and links the additional specified C files.
<li><tt>-withcxx "&lt;files&gt;"</tt> Compiles and links the additional specified C++ files.
</ul>
<p>
After running swig with the <tt>-phpfull</tt> switch, you will be left with a shockingly
similar set of files to the previous build process. However you will then need
to move these files to a subdirectory within the php source tree, this subdirectory you will need to create under the ext directory, with the name of the extension (e.g. <tt>mkdir php-4.0.6/ext/modulename</tt>).
</p>
<p>
After moving the files into this directory, you will need to run the 'buildall'
script in the php source directory. This rebuilds the configure script
and includes the extra command line arguments from the module you have added.
</p>
<p>
Before running the generated configure file, you may need to edit the <tt>
Makefile.in</tt>. This contains the names of the source files to compile (
just the wrapper file by default) and any additional libraries needed to
link in. If there are extra C files to compile you will need to add them
to the Makefile, or add the names of libraries if they are needed.
In most cases <tt>Makefile.in</tt> will be complete, especially if you
make use of <tt>-withlibs</tt> and <tt>-withincs</tt>
</p>
<div class="code"><pre>
swig -php -phpfull -withlibs "xapian omquery" --withincs "om.h"
</pre></div>
<p>
Will include in the <tt>config.m4</tt> and <tt>Makefile.in</tt> search for
<tt>libxapian.a</tt> or <tt>libxapian.so</tt> and search for
<tt>libomquery.a</tt> or <tt>libomquery.so</tt> as well as a
search for <tt>om.h</tt>.
</p>
<p>
You then need to run the configure command and pass the necessary command
line arguments to enable your module (by default this is --enable-modulename,
but this can be changed by editing the config.m4 file in the modules directory
before running the buildall script. In addition, extra tests can be added to
the config.m4 file to ensure the correct libraries and header files are
installed.)
</p>
<p>
Once configure has completed, you can run make to build php. If this all
compiles correctly, you should end up with a php executable/library
which contains your new module. You can test it with a php script which
does not have the 'dl' command as used above.
</p>
<H3><a name="Php_nn1_3"></a>28.1.3 Using PHP Extensions</H3>
<H3><a name="Php_nn1_3"></a>32.1.2 Using PHP Extensions</H3>
<p>
@ -288,21 +172,22 @@ attempts to do the <tt>dl()</tt> call for you:
include("example.php");
</pre></div>
<H2><a name="Php_nn2"></a>28.2 Basic PHP interface</H2>
<H2><a name="Php_nn2"></a>32.2 Basic PHP interface</H2>
<p>
It is important to understand that PHP uses a single global namespace
into which all symbols from extension modules are loaded. It is quite
possible for names of symbols in one extension module to clash with
other symbols unless care is taken to <tt>%rename</tt> them.
other symbols unless care is taken to <tt>%rename</tt> them. At present
SWIG doesn't have support for the namespace feature added in PHP 5.3.
</p>
<H3><a name="Php_nn2_1"></a>28.2.1 Constants</H3>
<H3><a name="Php_nn2_1"></a>32.2.1 Constants</H3>
<p>
These work in much the same way as in C/C++, constants can be defined
These work in much the same way as in C/C++. Constants can be defined
by using either the normal C pre-processor declarations, or the
<tt>%constant</tt> SWIG directive. These will then be available from
your PHP script as a PHP constant, (i.e. no dollar sign is needed to
@ -319,7 +204,7 @@ access them.) For example, with a swig interface file like this,
</div>
<p>
you can access the constants in your php script like this,
you can access the constants in your PHP script like this,
</p>
<div class="code"><pre>
@ -333,9 +218,16 @@ echo "E = " . E . "\n";
</div>
<p>
There are two peculiarities with using constants in PHP. The first is that
if you try to use an undeclared constant, it will evaluate to a string
set to the constant's name. For example,
There's one peculiarity of how constants work in PHP which it is useful
to note (this is not specific to SWIG though) - if you try to use an undeclared
constant, PHP will issue a warning and then expand the constant to a string
version of the constant's name. The warning will often be missed though as
if you're using PHP in a webserver, it will probably end up in error.log or
similar.
</p>
<p>
For example,
</p>
<div class="code"><pre>
@ -363,67 +255,12 @@ if(EASY_TO_MISPEL) {
</div>
<p>
will issue a warning about the undeclared constant, but will then
evaluate it and turn it into a string ('EASY_TO_MISPEL'), which
evaluates to true, rather than the value of the constant which would
be false. This is a feature!
The mis-spelled constant will become the string 'EASY_TO_MISPEL', which
is treated as true by the if test, when the value of the intended constant
would be treated as false!
</p>
<p>
The second 'feature' is that although constants are case sensitive (by
default), you cannot declare a constant twice with alternative
cases. E.g.,
</p>
<div class="code">
<pre>
%module example
#define TEST Hello
#define Test World
</pre>
</div>
<p>
accessed from PHP,
</p>
<div class="code">
<pre>
include("example.php");
echo TEST, Test;
</pre>
</div>
<p>
will output "Hello Test" rather than "Hello World". This is because
internally, all constants are stored in a hash table by their lower
case name, so 'TEST' and 'Test' will map to the same hash element
('Test'). But, because we declared them case sensitive, the Zend
engine will test if the case matches with the case the constant was
declared with first.
</p>
<p>
So, in the example above, the TEST constant was declared first, and
will be stored under the hash element 'test'. The 'Test' constant will
also map to the same hash element 'test', but will not overwrite
it. When called from the script, the TEST constant will again be
mapped to the hash element 'test' so the constant will be
retrieved. The case will then be checked, and will match up, so the
value ('Hello') will be returned. When 'Test' is evaluated, it will
also map to the same hash element 'test'. The same constant will be
retrieved, this time though the case check will fail as 'Test' !=
'TEST'. So PHP will assume that Test is a undeclared constant, and as
explained above, will return it as a string set to the constant name
('Test'). Hence the script above will print 'Hello Test'. If they were
declared non-case sensitive, the output would be 'Hello Hello', as
both point to the same value, without the case test taking place. (
Apologies, this paragraph needs rewriting to make some sense. )
</p>
<H3><a name="Php_nn2_2"></a>28.2.2 Global Variables</H3>
<H3><a name="Php_nn2_2"></a>32.2.2 Global Variables</H3>
<p>
@ -472,7 +309,7 @@ undefined.
At this time SWIG does not support custom accessor methods.
</p>
<H3><a name="Php_nn2_3"></a>28.2.3 Functions</H3>
<H3><a name="Php_nn2_3"></a>32.2.3 Functions</H3>
<p>
@ -525,7 +362,7 @@ print $s; # The value of $s was not changed.
-->
<H3><a name="Php_nn2_4"></a>28.2.4 Overloading</H3>
<H3><a name="Php_nn2_4"></a>32.2.4 Overloading</H3>
<p>
@ -533,13 +370,13 @@ Although PHP does not support overloading functions natively, swig
will generate dispatch functions which will use <tt>%typecheck</tt>
typemaps to allow overloading. This dispatch function's operation and
precedence is described in <a
href="TypemapsSWIGPlus.html#SWIGPlus_overloaded_methods">Wrapping
href="SWIGPlus.html#SWIGPlus_overloaded_methods">Wrapping
Overloaded Functions and Methods</a>.
</p>
<!-- This isn't correct for 1.3.30 and needs rewriting to reflect reality
<p>
Because PHP4 is a dynamically typed language, simple values can be
Because PHP is a dynamically typed language, simple values can be
silently converted from one type to another. For example, integers,
doubles and strings silently convert to each other depending on
context. This situation make overloading slightly problematic because
@ -559,7 +396,7 @@ PHP. The string <tt>"2"</tt> simultaneously represents the integer
<p>
In order to provide the most natural experience to PHP programmers,
the default <tt>%typecheck</tt> implemented in <tt>php4.swg</tt>
the default <tt>%typecheck</tt> implemented in <tt>php.swg</tt>
allows any simple type (integer, double, string) in PHP to be used for
any simple C type (int, double, char *). The function selected then
depends only on the argument type precedence defined by SWIG.
@ -581,7 +418,7 @@ taking the integer argument.
</p>
-->
<H3><a name="Php_nn2_5"></a>28.2.5 Pointers and References</H3>
<H3><a name="Php_nn2_5"></a>32.2.5 Pointers and References</H3>
<p>
@ -605,7 +442,7 @@ One can include <b>cpointer.i</b> to generate PHP wrappers to <tt>int
<div class="code"><pre>
%module example
%include cpointer.i
%include "cpointer.i"
%pointer_functions(int,intp)
void add( int *in1, int *in2, int *result);
@ -639,7 +476,7 @@ parameter names as appropriate.
<div class="code"><pre>
%module example
%include typemaps.i
%include "typemaps.i"
void add( int *INPUT, int *INPUT, int *OUTPUT);
@ -671,7 +508,7 @@ named typemap REFERENCE.
<div class="code"><pre>
%module example
%include phppointers.i
%include "phppointers.i"
void add( int *REF, int *REF, int *REF);
@ -713,24 +550,15 @@ PHP in a number of ways: by using <tt>unset</tt> on an existing
variable, or assigning <tt>NULL</tt> to a variable.
</p>
<H3><a name="Php_nn2_6"></a>28.2.6 Structures and C++ classes</H3>
<H3><a name="Php_nn2_6"></a>32.2.6 Structures and C++ classes</H3>
<p>
SWIG defaults to wrapping C++ structs and classes with PHP classes. This
requires SWIG to generate different code for PHP4 and PHP5, so you must
specify which you want using <tt>-php4</tt> or <tt>-php5</tt> (currently
<tt>-php</tt> generates PHP4 class wrappers for compatibility with
SWIG 1.3.29 and earlier, but this may change in the future).
</p>
<p>
PHP4 classes are implemented entirely using the Zend C API so
no additional php code is generated. For PHP5, a PHP wrapper
class is generated which calls a set of flat functions wrapping the C++ class.
In many cases the PHP4 and PHP5 wrappers will behave the same way,
but the PHP5 ones make use of better PHP5's better OO functionality
where appropriate.
SWIG defaults to wrapping C++ structs and classes with PHP classes - this
is done by generating a PHP wrapper script which defines proxy classes
which calls a set of flat functions which actually wrap the C++ class.
You can disable this wrapper layer by passing the command-line option
"-noproxy" in which case you'll just get the flat functions.
</p>
<p>
@ -754,7 +582,7 @@ struct Complex {
</pre></div>
<p>
Would be used in the following way from either PHP4 or PHP5:
Would be used in the following way from PHP5:
</p>
<div class="code"><pre>
@ -783,7 +611,7 @@ Would be used in the following way from either PHP4 or PHP5:
Member variables and methods are accessed using the <tt>-&gt;</tt> operator.
</p>
<H4><a name="Php_nn2_6_1"></a>28.2.6.1 Using <tt>-noproxy</tt></H4>
<H4><a name="Php_nn2_6_1"></a>32.2.6.1 Using <tt>-noproxy</tt></H4>
<p>
@ -809,7 +637,7 @@ Complex_im_set($obj,$d);
Complex_im_get($obj);
</pre></div>
<H4><a name="Php_nn2_6_2"></a>28.2.6.2 Constructors and Destructors</H4>
<H4><a name="Php_nn2_6_2"></a>32.2.6.2 Constructors and Destructors</H4>
<p>
@ -850,13 +678,13 @@ the programmer can either reassign the variable or call
<tt>unset($v)</tt>
</p>
<H4><a name="Php_nn2_6_3"></a>28.2.6.3 Static Member Variables</H4>
<H4><a name="Php_nn2_6_3"></a>32.2.6.3 Static Member Variables</H4>
<p>
Static member variables are not supported in PHP4, and it does not
appear to be possible to intercept accesses to static member variables
in PHP5. Therefore, static member variables are
Static member variables in C++ are not wrapped as such in PHP
as it does not appear to be possible to intercept accesses to such variables.
Therefore, static member variables are
wrapped using a class function with the same name, which
returns the current value of the class variable. For example
</p>
@ -893,7 +721,7 @@ Ko::threats(10);
echo "There has now been " . Ko::threats() . " threats\n";
</pre></div>
<H4><a name="Php_nn2_6_4"></a>28.2.6.4 Static Member Functions</H4>
<H4><a name="Php_nn2_6_4"></a>32.2.6.4 Static Member Functions</H4>
<p>
@ -915,15 +743,9 @@ Ko::threats();
</pre></div>
<H3><a name="Php_nn2_7"></a>28.2.7 PHP Pragmas, Startup and Shutdown code</H3>
<H3><a name="Php_nn2_7"></a>32.2.7 PHP Pragmas, Startup and Shutdown code</H3>
<p>
Note: Currently pragmas for PHP need to be specified using
<tt>%pragma(php4)</tt> but also apply for PHP5! This is just a historical
oddity because SWIG's PHP support predates PHP5.
</p>
<p>
To place PHP code in the generated "example.php" file one can use the
<b>code</b> pragma. The code is inserted after loading the shared
@ -932,7 +754,7 @@ object.
<div class="code"><pre>
%module example
%pragma(php4) code="
%pragma(php) code="
# This code is inserted into example.php
echo \"example.php execution\\n\";
"
@ -954,7 +776,7 @@ the example.php file.
<div class="code"><pre>
%module example
%pragma(php4) code="
%pragma(php) code="
include \"include.php\";
"
%pragma(php) include="include.php" // equivalent.
@ -968,7 +790,7 @@ phpinfo() function.
<div class="code"><pre>
%module example;
%pragma(php4) phpinfo="
%pragma(php) phpinfo="
zend_printf("An example of PHP support through SWIG\n");
php_info_print_table_start();
php_info_print_table_header(2, \"Directive\", \"Value\");
@ -994,7 +816,7 @@ either <tt>%init</tt> or <tt>%minit</tt>.
<p>
To insert code into the <tt>PHP_MSHUTDOWN_FUNCTION</tt>, one can use
either <tt>%init</tt> or <tt>%minit</tt>.
either <tt>%shutdown</tt> or <tt>%mshutdown</tt>.
</p>
<div class="code"><pre>
@ -1005,8 +827,384 @@ either <tt>%init</tt> or <tt>%minit</tt>.
</pre></div>
<p>
The <tt>%rinit</tt> and <tt>%rshutdown</tt> statements insert code
into the request init and shutdown code respectively.
The <tt>%rinit</tt> and <tt>%rshutdown</tt> statements are very similar but insert code
into the request init (PHP_RINIT_FUNCTION) and request shutdown (PHP_RSHUTDOWN_FUNCTION) code respectively.
</p>
<H2><a name="Php_nn3"></a>32.3 Cross language polymorphism</H2>
<p>
Proxy classes provide a more natural, object-oriented way to access
extension classes. As described above, each proxy instance has an
associated C++ instance, and method calls to the proxy are passed to the
C++ instance transparently via C wrapper functions.
</p>
<p>
This arrangement is asymmetric in the sense that no corresponding
mechanism exists to pass method calls down the inheritance chain from
C++ to PHP. In particular, if a C++ class has been extended in PHP
(by extending the proxy class), these extensions will not be visible
from C++ code. Virtual method calls from C++ are thus not able access
the lowest implementation in the inheritance chain.
</p>
<p>
Changes have been made to SWIG 1.3.18 to address this problem and make
the relationship between C++ classes and proxy classes more symmetric.
To achieve this goal, new classes called directors are introduced at the
bottom of the C++ inheritance chain. Support for generating PHP classes
has been added in SWIG 1.3.40. The job of the directors is to route
method calls correctly, either to C++ implementations higher in the
inheritance chain or to PHP implementations lower in the inheritance
chain. The upshot is that C++ classes can be extended in PHP and from
C++ these extensions look exactly like native C++ classes. Neither C++
code nor PHP code needs to know where a particular method is
implemented: the combination of proxy classes, director classes, and C
wrapper functions takes care of all the cross-language method routing
transparently.
</p>
<H3><a name="Php_nn3_1"></a>32.3.1 Enabling directors</H3>
<p>
The director feature is disabled by default. To use directors you
must make two changes to the interface file. First, add the "directors"
option to the %module directive, like this:
</p>
<div class="code">
<pre>
%module(directors="1") modulename
</pre>
</div>
<p>
Without this option no director code will be generated. Second, you
must use the %feature("director") directive to tell SWIG which classes
and methods should get directors. The %feature directive can be applied
globally, to specific classes, and to specific methods, like this:
</p>
<div class="code">
<pre>
// generate directors for all classes that have virtual methods
%feature("director");
// generate directors for all virtual methods in class Foo
%feature("director") Foo;
// generate a director for just Foo::bar()
%feature("director") Foo::bar;
</pre>
</div>
<p>
You can use the %feature("nodirector") directive to turn off
directors for specific classes or methods. So for example,
</p>
<div class="code">
<pre>
%feature("director") Foo;
%feature("nodirector") Foo::bar;
</pre>
</div>
<p>
will generate directors for all virtual methods of class Foo except
bar().
</p>
<p>
Directors can also be generated implicitly through inheritance.
In the following, class Bar will get a director class that handles
the methods one() and two() (but not three()):
</p>
<div class="code">
<pre>
%feature("director") Foo;
class Foo {
public:
Foo(int foo);
virtual void one();
virtual void two();
};
class Bar: public Foo {
public:
virtual void three();
};
</pre>
</div>
<p>
then at the PHP side you can define
</p>
<div class="targetlang">
<pre>
require("mymodule.php");
class MyFoo extends Foo {
function one() {
print "one from php\n";
}
}
</pre>
</div>
<H3><a name="Php_nn3_2"></a>32.3.2 Director classes</H3>
<p>
For each class that has directors enabled, SWIG generates a new class
that derives from both the class in question and a special
<tt>Swig::Director</tt> class. These new classes, referred to as director
classes, can be loosely thought of as the C++ equivalent of the PHP
proxy classes. The director classes store a pointer to their underlying
PHP object. Indeed, this is quite similar to the "_cPtr" and "thisown"
members of the PHP proxy classes.
</p>
<p>
For simplicity let's ignore the <tt>Swig::Director</tt> class and refer to the
original C++ class as the director's base class. By default, a director
class extends all virtual methods in the inheritance chain of its base
class (see the preceding section for how to modify this behavior).
Thus all virtual method calls, whether they originate in C++ or in
PHP via proxy classes, eventually end up in at the implementation in the
director class. The job of the director methods is to route these method
calls to the appropriate place in the inheritance chain. By "appropriate
place" we mean the method that would have been called if the C++ base
class and its extensions in PHP were seamlessly integrated. That
seamless integration is exactly what the director classes provide,
transparently skipping over all the messy extension API glue that binds
the two languages together.
</p>
<p>
In reality, the "appropriate place" is one of only two possibilities:
C++ or PHP. Once this decision is made, the rest is fairly easy. If the
correct implementation is in C++, then the lowest implementation of the
method in the C++ inheritance chain is called explicitly. If the correct
implementation is in PHP, the Zend API is used to call the method of the
underlying PHP object (after which the usual virtual method resolution
in PHP automatically finds the right implementation).
</p>
<p>
Now how does the director decide which language should handle the method call?
The basic rule is to handle the method in PHP, unless there's a good
reason not to. The reason for this is simple: PHP has the most
"extended" implementation of the method. This assertion is guaranteed,
since at a minimum the PHP proxy class implements the method. If the
method in question has been extended by a class derived from the proxy
class, that extended implementation will execute exactly as it should.
If not, the proxy class will route the method call into a C wrapper
function, expecting that the method will be resolved in C++. The wrapper
will call the virtual method of the C++ instance, and since the director
extends this the call will end up right back in the director method. Now
comes the "good reason not to" part. If the director method were to blindly
call the PHP method again, it would get stuck in an infinite loop. We avoid this
situation by adding special code to the C wrapper function that tells
the director method to not do this. The C wrapper function compares the
called and the declaring class name of the given method. If these are
not the same, then the C wrapper function tells the director to resolve
the method by calling up the C++ inheritance chain, preventing an
infinite loop.
</p>
<p>
One more point needs to be made about the relationship between director
classes and proxy classes. When a proxy class instance is created in
PHP, SWIG creates an instance of the original C++ class and assigns it
to <tt>-&gt;_cPtr</tt>. This is exactly what happens without directors
and is true even if directors are enabled for the particular class in
question. When a class <i>derived</i> from a proxy class is created,
however, SWIG then creates an instance of the corresponding C++ director
class. The reason for this difference is that user-defined subclasses
may override or extend methods of the original class, so the director
class is needed to route calls to these methods correctly. For
unmodified proxy classes, all methods are ultimately implemented in C++
so there is no need for the extra overhead involved with routing the
calls through PHP.
</p>
<H3><a name="Php_nn3_3"></a>32.3.3 Ownership and object destruction</H3>
<p>
Memory management issues are slightly more complicated with directors
than for proxy classes alone. PHP instances hold a pointer to the
associated C++ director object, and the director in turn holds a pointer
back to the PHP object. By default, proxy classes own their C++ director
object and take care of deleting it when they are garbage collected.
</p>
<p>
This relationship can be reversed by calling the special
<tt>-&gt;thisown</tt> property of the proxy class. After setting this
property to <tt>0</tt>, the director class no longer destroys the PHP
object. Assuming no outstanding references to the PHP object remain,
the PHP object will be destroyed at the same time. This is a good thing,
since directors and proxies refer to each other and so must be created
and destroyed together. Destroying one without destroying the other will
likely cause your program to segfault.
</p>
<p>
Here is an example:
</p>
<div class="code">
<pre>
class Foo {
public:
...
};
class FooContainer {
public:
void addFoo(Foo *);
...
};
</pre>
</div>
<br>
<div class="targetlang">
<pre>
$c = new FooContainer();
$a = new Foo();
$a-&gt;thisown = 0;
$c-&gt;addFoo($a);
</pre>
</div>
<p>
In this example, we are assuming that FooContainer will take care of
deleting all the Foo pointers it contains at some point.
</p>
<H3><a name="Php_nn3_4"></a>32.3.4 Exception unrolling</H3>
<p>
With directors routing method calls to PHP, and proxies routing them
to C++, the handling of exceptions is an important concern. By default, the
directors ignore exceptions that occur during method calls that are
resolved in PHP. To handle such exceptions correctly, it is necessary
to temporarily translate them into C++ exceptions. This can be done with
the %feature("director:except") directive. The following code should
suffice in most cases:
</p>
<div class="code">
<pre>
%feature("director:except") {
if ($error == FAILURE) {
throw Swig::DirectorMethodException();
}
}
</pre>
</div>
<p>
This code will check the PHP error state after each method call from a
director into PHP, and throw a C++ exception if an error occurred. This
exception can be caught in C++ to implement an error handler.
Currently no information about the PHP error is stored in the
Swig::DirectorMethodException object, but this will likely change in the
future.
</p>
<p>
It may be the case that a method call originates in PHP, travels up to
C++ through a proxy class, and then back into PHP via a director method.
If an exception occurs in PHP at this point, it would be nice for that
exception to find its way back to the original caller. This can be done
by combining a normal %exception directive with the
<tt>director:except</tt> handler shown above. Here is an example of a
suitable exception handler:
</p>
<div class="code">
<pre>
%exception {
try { $action }
catch (Swig::DirectorException &amp;e) { SWIG_fail; }
}
</pre>
</div>
<p>
The class Swig::DirectorException used in this example is actually a
base class of Swig::DirectorMethodException, so it will trap this
exception. Because the PHP error state is still set when
Swig::DirectorMethodException is thrown, PHP will register the exception
as soon as the C wrapper function returns.
</p>
<H3><a name="Php_nn3_5"></a>32.3.5 Overhead and code bloat</H3>
<p>
Enabling directors for a class will generate a new director method for
every virtual method in the class' inheritance chain. This alone can
generate a lot of code bloat for large hierarchies. Method arguments
that require complex conversions to and from target language types can
result in large director methods. For this reason it is recommended that
you selectively enable directors only for specific classes that are
likely to be extended in PHP and used in C++.
</p>
<p>
Compared to classes that do not use directors, the call routing in the
director methods does add some overhead. In particular, at least one
dynamic cast and one extra function call occurs per method call from
PHP. Relative to the speed of PHP execution this is probably completely
negligible. For worst case routing, a method call that ultimately
resolves in C++ may take one extra detour through PHP in order to ensure
that the method does not have an extended PHP implementation. This could
result in a noticeable overhead in some cases.
</p>
<p>
Although directors make it natural to mix native C++ objects with PHP
objects (as director objects) via a common base class pointer, one
should be aware of the obvious fact that method calls to PHP objects
will be much slower than calls to C++ objects. This situation can be
optimized by selectively enabling director methods (using the %feature
directive) for only those methods that are likely to be extended in PHP.
</p>
<H3><a name="Php_nn3_6"></a>32.3.6 Typemaps</H3>
<p>
Typemaps for input and output of most of the basic types from director
classes have been written. These are roughly the reverse of the usual
input and output typemaps used by the wrapper code. The typemap
operation names are 'directorin', 'directorout', and 'directorargout'.
The director code does not currently use any of the other kinds of
typemaps. It is not clear at this point which kinds are appropriate and
need to be supported.
</p>
<H3><a name="Php_nn3_7"></a>32.3.7 Miscellaneous</H3>
<p> Director typemaps for STL classes are mostly in place, and hence you
should be able to use std::string, etc., as you would any other type.
</p>
</body>

26
Doc/Manual/Pike.html
View file

@ -6,7 +6,7 @@
</head>
<body bgcolor="#ffffff">
<H1><a name="Pike"></a>29 SWIG and Pike</H1>
<H1><a name="Pike"></a>33 SWIG and Pike</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -46,10 +46,10 @@ least, make sure you read the "<a href="SWIG.html#SWIG">SWIG Basics</a>"
chapter.<br>
</p>
<H2><a name="Pike_nn2"></a>29.1 Preliminaries</H2>
<H2><a name="Pike_nn2"></a>33.1 Preliminaries</H2>
<H3><a name="Pike_nn3"></a>29.1.1 Running SWIG</H3>
<H3><a name="Pike_nn3"></a>33.1.1 Running SWIG</H3>
<p>
@ -94,7 +94,7 @@ can use the <tt>-o</tt> option:
<div class="code">
<pre>$ <b>swig -pike -o pseudonym.c example.i</b><br></pre>
</div>
<H3><a name="Pike_nn4"></a>29.1.2 Getting the right header files</H3>
<H3><a name="Pike_nn4"></a>33.1.2 Getting the right header files</H3>
<p>
@ -114,7 +114,7 @@ You're looking for files with the names <tt>global.h</tt>, <tt>program.h</tt>
and so on.
</p>
<H3><a name="Pike_nn5"></a>29.1.3 Using your module</H3>
<H3><a name="Pike_nn5"></a>33.1.3 Using your module</H3>
<p>
@ -129,10 +129,10 @@ Pike v7.4 release 10 running Hilfe v3.5 (Incremental Pike Frontend)
(1) Result: 24
</pre></div>
<H2><a name="Pike_nn6"></a>29.2 Basic C/C++ Mapping</H2>
<H2><a name="Pike_nn6"></a>33.2 Basic C/C++ Mapping</H2>
<H3><a name="Pike_nn7"></a>29.2.1 Modules</H3>
<H3><a name="Pike_nn7"></a>33.2.1 Modules</H3>
<p>
@ -143,7 +143,7 @@ concerned), SWIG's <tt>%module</tt> directive doesn't really have any
significance.
</p>
<H3><a name="Pike_nn8"></a>29.2.2 Functions</H3>
<H3><a name="Pike_nn8"></a>33.2.2 Functions</H3>
<p>
@ -168,11 +168,11 @@ exactly as you'd expect it to:
(1) Result: 24
</pre></div>
<H3><a name="Pike_nn9"></a>29.2.3 Global variables</H3>
<H3><a name="Pike_nn9"></a>33.2.3 Global variables</H3>
<p>
Global variables are currently wrapped as a pair of of functions, one to get
Global variables are currently wrapped as a pair of functions, one to get
the current value of the variable and another to set it. For example, the
declaration
</p>
@ -197,7 +197,7 @@ will result in two functions, <tt>Foo_get()</tt> and <tt>Foo_set()</tt>:
(3) Result: 3.141590
</pre></div>
<H3><a name="Pike_nn10"></a>29.2.4 Constants and enumerated types</H3>
<H3><a name="Pike_nn10"></a>33.2.4 Constants and enumerated types</H3>
<p>
@ -205,7 +205,7 @@ Enumerated types in C/C++ declarations are wrapped as Pike constants,
not as Pike enums.
</p>
<H3><a name="Pike_nn11"></a>29.2.5 Constructors and Destructors</H3>
<H3><a name="Pike_nn11"></a>33.2.5 Constructors and Destructors</H3>
<p>
@ -213,7 +213,7 @@ Constructors are wrapped as <tt>create()</tt> methods, and destructors are
wrapped as <tt>destroy()</tt> methods, for Pike classes.
</p>
<H3><a name="Pike_nn12"></a>29.2.6 Static Members</H3>
<H3><a name="Pike_nn12"></a>33.2.6 Static Members</H3>
<p>

100
Doc/Manual/Preface.html
View file

@ -11,13 +11,12 @@
<div class="sectiontoc">
<ul>
<li><a href="#Preface_nn2">Introduction</a>
<li><a href="#Preface_nn3">Special Introduction for Version 1.3</a>
<li><a href="#Preface_nn4">SWIG Versions</a>
<li><a href="#Preface_nn5">SWIG resources</a>
<li><a href="#Preface_nn6">Prerequisites</a>
<li><a href="#Preface_nn7">Organization of this manual</a>
<li><a href="#Preface_nn8">How to avoid reading the manual</a>
<li><a href="#Preface_nn9">Backwards Compatibility</a>
<li><a href="#Preface_nn9">Backwards compatibility</a>
<li><a href="#Preface_nn10">Credits</a>
<li><a href="#Preface_nn11">Bug reports</a>
</ul>
@ -49,34 +48,22 @@ has since evolved into a general purpose tool that is used in a wide
variety of applications--in fact almost anything where C/C++ programming
is involved.
<H2><a name="Preface_nn3"></a>1.2 Special Introduction for Version 1.3</H2>
<H2><a name="Preface_nn4"></a>1.2 SWIG Versions</H2>
<p>
Since SWIG was released in 1996, its user base and applicability has
continued to grow. Although its rate of development has varied, an
active development effort has continued to make improvements to the
system. Today, nearly a dozen developers are working to create
SWIG-2.0---a system that aims to provide wrapping support for nearly
all of the ANSI C++ standard and approximately ten target languages
including Guile, Java, Mzscheme, Ocaml, Perl, Pike, PHP, Python, Ruby,
and Tcl.
In the late 1990's, the most stable version of SWIG was release
1.1p5. Versions 1.3.x were officially development versions and these were released
over a period of 10 years starting from the year 2000. The final version in the 1.3.x
series was 1.3.40, but in truth the 1.3.x series had been stable for many years.
An official stable version was released along with the decision to make SWIG
license changes and this gave rise to version 2.0.0 in 2010. The license was clarified
so that the code that SWIG generated could be distributed
under license terms of the user's choice/requirements and at the same time the SWIG
source was placed under the GNU General Public License version 3.
</p>
<H2><a name="Preface_nn4"></a>1.3 SWIG Versions</H2>
<p>
For several years, the most stable version of SWIG has been release
1.1p5. Starting with version 1.3, a new version numbering scheme has
been adopted. Odd version numbers (1.3, 1.5, etc.) represent
development versions of SWIG. Even version numbers (1.4, 1.6, etc.)
represent stable releases. Currently, developers are working to
create a stable SWIG-2.0 release. Don't let the development status
of SWIG-1.3 scare you---it is much more stable (and capable) than SWIG-1.1p5.
</p>
<H2><a name="Preface_nn5"></a>1.4 SWIG resources</H2>
<H2><a name="Preface_nn5"></a>1.3 SWIG resources</H2>
<p>
@ -106,7 +93,7 @@ SWIG along with information about beta releases and future work.
</p>
<p>
SVN access to the latest version of SWIG is also available. More information
Subversion access to the latest version of SWIG is also available. More information
about this can be obtained at:
</p>
@ -115,7 +102,7 @@ about this can be obtained at:
</pre></div>
<H2><a name="Preface_nn6"></a>1.5 Prerequisites</H2>
<H2><a name="Preface_nn6"></a>1.4 Prerequisites</H2>
<p>
@ -132,7 +119,7 @@ writing a normal C program.
</p>
<p>
Recent SWIG releases have become significantly more capable in
Over time SWIG releases have become significantly more capable in
their C++ handling--especially support for advanced features like
namespaces, overloaded operators, and templates. Whenever possible,
this manual tries to cover the technicalities of this interface.
@ -140,7 +127,7 @@ However, this isn't meant to be a tutorial on C++ programming. For many
of the gory details, you will almost certainly want to consult a good C++ reference. If you don't program
in C++, you may just want to skip those parts of the manual.
<H2><a name="Preface_nn7"></a>1.6 Organization of this manual</H2>
<H2><a name="Preface_nn7"></a>1.5 Organization of this manual</H2>
<p>
@ -149,11 +136,10 @@ provide an overview of its capabilities. The remaining chapters are
devoted to specific SWIG language modules and are self
contained. Thus, if you are using SWIG to build Python interfaces, you
can probably skip to that chapter and find almost everything you need
to know. Caveat: we are currently working on a documentation rewrite and many
of the older language module chapters are still somewhat out of date.
to know.
</p>
<H2><a name="Preface_nn8"></a>1.7 How to avoid reading the manual</H2>
<H2><a name="Preface_nn8"></a>1.6 How to avoid reading the manual</H2>
<p>
@ -165,24 +151,19 @@ The SWIG distribution also comes with a large directory of
examples that illustrate different topics.
</p>
<H2><a name="Preface_nn9"></a>1.8 Backwards Compatibility</H2>
<H2><a name="Preface_nn9"></a>1.7 Backwards compatibility</H2>
<p>
If you are a previous user of SWIG, don't expect recent versions of
SWIG to provide backwards compatibility. In fact, backwards
compatibility issues may arise even between successive 1.3.x releases.
Although these incompatibilities are regrettable, SWIG-1.3 is an active
development project. The primary goal of this effort is to make SWIG
If you are a previous user of SWIG, don't expect
SWIG to provide complete backwards compatibility.
Although the developers strive to the utmost to keep backwards compatibility,
this isn't always possible as the
primary goal over time is to make SWIG
better---a process that would simply be impossible if the developers
are constantly bogged down with backwards compatibility issues.
</p>
<p>
On a positive note, a few incompatibilities are a small price to pay
for the large number of new features that have been
added---namespaces, templates, smart pointers, overloaded methods,
operators, and more.
Potential incompatibilities are clearly marked in the detailed release notes
(CHANGES files).
</p>
@ -206,33 +187,20 @@ Note: The version symbol is not defined in the generated SWIG
wrapper file. The SWIG preprocessor has defined SWIG_VERSION since SWIG-1.3.11.
</p>
<H2><a name="Preface_nn10"></a>1.9 Credits</H2>
<H2><a name="Preface_nn10"></a>1.8 Credits</H2>
<p>
SWIG is an unfunded project that would not be possible without the
contributions of many people. Most recent SWIG development has been
supported by Matthias K&ouml;ppe, William Fulton, Lyle Johnson,
Richard Palmer, Thien-Thi Nguyen, Jason Stewart, Loic Dachary, Masaki
Fukushima, Luigi Ballabio, Sam Liddicott, Art Yerkes, Marcelo Matus,
Harco de Hilster, John Lenz, and Surendra Singhi.
contributions of many people working in their spare time.
If you have benefitted from using SWIG, please consider
<a href="http://www.swig.org/donate.html">Donating to SWIG</a> to keep development going.
There have been a large varied number of people
who have made contributions at all levels over time. Contributors
are mentioned either in the COPYRIGHT file or CHANGES files shipped with SWIG or in submitted bugs.
</p>
<p>
Historically, the following people contributed to early versions of SWIG.
Peter Lomdahl, Brad Holian, Shujia Zhou, Niels Jensen, and Tim Germann
at Los Alamos National Laboratory were the first users. Patrick
Tullmann at the University of Utah suggested the idea of automatic
documentation generation. John Schmidt and Kurtis Bleeker at the
University of Utah tested out the early versions. Chris Johnson
supported SWIG's developed at the University of Utah. John Buckman,
Larry Virden, and Tom Schwaller provided valuable input on the first
releases and improving the portability of SWIG. David Fletcher and
Gary Holt have provided a great deal of input on improving SWIG's
Perl5 implementation. Kevin Butler contributed the first Windows NT
port.
<H2><a name="Preface_nn11"></a>1.10 Bug reports</H2>
<H2><a name="Preface_nn11"></a>1.9 Bug reports</H2>
<p>

37
Doc/Manual/Preprocessor.html
View file

@ -16,8 +16,11 @@
<li><a href="#Preprocessor_nn5">Macro Expansion</a>
<li><a href="#Preprocessor_nn6">SWIG Macros</a>
<li><a href="#Preprocessor_nn7">C99 and GNU Extensions</a>
<li><a href="#Preprocessor_delimiters">Preprocessing and delimiters</a>
<ul>
<li><a href="#Preprocessor_nn8">Preprocessing and %{ ... %} &amp; " ... " delimiters</a>
<li><a href="#Preprocessor_nn9">Preprocessing and { ... } delimiters</a>
</ul>
<li><a href="#Preprocessor_typemap_delimiters">Preprocessor and Typemaps</a>
<li><a href="#Preprocessor_nn10">Viewing preprocessor output</a>
<li><a href="#Preprocessor_warning_error">The #error and #warning directives</a>
@ -81,7 +84,7 @@ Such information generally includes type declarations (e.g., <tt>typedef</tt>) a
C++ classes that might be used as base-classes for class declarations in the interface.
The use of <tt>%import</tt> is also important when SWIG is used to generate
extensions as a collection of related modules. This is an advanced topic and is described
in a later chapter.
in later in the <a href="Modules.html#Modules">Working with Modules</a> chapter.
</p>
<P>
@ -102,12 +105,13 @@ by SWIG when it is parsing the interface:
<div class="code"><pre>
SWIG Always defined when SWIG is processing a file
SWIGIMPORTED Defined when SWIG is importing a file with <tt>%import</tt>
SWIGMAC Defined when running SWIG on the Macintosh
SWIGWIN Defined when running SWIG under Windows
SWIG_VERSION Hexadecimal number containing SWIG version,
SWIG_VERSION Hexadecimal (binary-coded decimal) number containing SWIG version,
such as 0x010311 (corresponding to SWIG-1.3.11).
SWIGALLEGROCL Defined when using Allegro CL
SWIGCFFI Defined when using CFFI
SWIGCHICKEN Defined when using CHICKEN
SWIGCLISP Defined when using CLISP
SWIGCSHARP Defined when using C#
SWIGGUILE Defined when using Guile
SWIGJAVA Defined when using Java
@ -115,17 +119,15 @@ SWIGLUA Defined when using Lua
SWIGMODULA3 Defined when using Modula-3
SWIGMZSCHEME Defined when using Mzscheme
SWIGOCAML Defined when using Ocaml
SWIGOCTAVE Defined when using Octave
SWIGPERL Defined when using Perl
SWIGPERL5 Defined when using Perl5
SWIGPHP Defined when using PHP
SWIGPHP4 Defined when using PHP4
SWIGPHP5 Defined when using PHP5
SWIGPIKE Defined when using Pike
SWIGPYTHON Defined when using Python
SWIGR Defined when using R
SWIGRUBY Defined when using Ruby
SWIGSEXP Defined when using S-expressions
SWIGTCL Defined when using Tcl
SWIGTCL8 Defined when using Tcl8.0
SWIGXML Defined when using XML
</pre></div>
@ -307,7 +309,14 @@ interface building. However, they are used internally to implement a number of
SWIG directives and are provided to make SWIG more compatible with C99 code.
</p>
<H2><a name="Preprocessor_nn8"></a>7.7 Preprocessing and %{ ... %} &amp; " ... " delimiters</H2>
<H2><a name="Preprocessor_delimiters"></a>7.7 Preprocessing and delimiters</H2>
<p>
The preprocessor handles { }, " " and %{ %} delimiters differently.
</p>
<H3><a name="Preprocessor_nn8"></a>7.7.1 Preprocessing and %{ ... %} &amp; " ... " delimiters</H3>
<p>
@ -332,7 +341,7 @@ the contents of the <tt>%{ ... %}</tt> block are copied without
modification to the output (including all preprocessor directives).
</p>
<H2><a name="Preprocessor_nn9"></a>7.8 Preprocessing and { ... } delimiters</H2>
<H3><a name="Preprocessor_nn9"></a>7.7.2 Preprocessing and { ... } delimiters</H3>
<p>
@ -374,11 +383,11 @@ to actually go into the wrapper file, prefix the preprocessor directives with <t
SWIG will strip the extra <tt>%</tt> and leave the preprocessor directive in the code.
</p>
<H2><a name="Preprocessor_typemap_delimiters"></a>7.9 Preprocessor and Typemaps</H2>
<H2><a name="Preprocessor_typemap_delimiters"></a>7.8 Preprocessor and Typemaps</H2>
<p>
<a href="Typemaps.html">Typemaps</a> support a special attribute called <tt>noblock</tt> where the { ... } delimiters can be used,
<a href="Typemaps.html#Typemaps">Typemaps</a> support a special attribute called <tt>noblock</tt> where the { ... } delimiters can be used,
but the delimiters are not actually generated into the code.
The effect is then similar to using "" or %{ %} delimiters but the code <b>is</b> run through the preprocessor. For example:
</p>
@ -445,7 +454,7 @@ would generate
</div>
<H2><a name="Preprocessor_nn10"></a>7.10 Viewing preprocessor output</H2>
<H2><a name="Preprocessor_nn10"></a>7.9 Viewing preprocessor output</H2>
<p>
@ -455,7 +464,7 @@ Instead the results after the preprocessor has run are displayed.
This might be useful as an aid to debugging and viewing the results of macro expansions.
</p>
<H2><a name="Preprocessor_warning_error"></a>7.11 The #error and #warning directives</H2>
<H2><a name="Preprocessor_warning_error"></a>7.10 The #error and #warning directives</H2>
<p>

1072
Doc/Manual/Python.html
View file

File diff suppressed because it is too large Load diff

50
Doc/Manual/R.html
View file

@ -6,7 +6,7 @@
</head>
<body bgcolor="#ffffff">
<H1><a name="R"></a>33 SWIG and R</H1>
<H1><a name="R"></a>35 SWIG and R</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -33,7 +33,7 @@ compile and run an R interface to QuantLib running on Mandriva Linux
with gcc. The R bindings also work on Microsoft Windows using Visual C++.
</p>
<H2><a name="R_nn2"></a>33.1 Bugs</H2>
<H2><a name="R_nn2"></a>35.1 Bugs</H2>
<p>
@ -45,7 +45,7 @@ Currently the following features are not implemented or broken:
<li>C Array wrappings
</ul>
<H2><a name="R_nn3"></a>33.2 Using R and SWIG</H2>
<H2><a name="R_nn3"></a>35.2 Using R and SWIG</H2>
<p>
@ -56,28 +56,48 @@ example.c is the name of the file with the functions in them
<div class="shell">
<pre>
swig -r example.i
PKG_LIBS="example.c" R CMD SHLIB example_wrap.c
R CMD SHLIB example_wrap.c example.c
</pre>
</div>
<p>
The corresponding comments for C++ mode are
The corresponding options for C++ mode are
</p>
<div class="shell">
<pre>
swig -c++ -r -o example_wrap.cpp example.i
PKG_LIBS="example.cxx" R CMD SHLIB example_wrap.cpp
R CMD SHLIB example_wrap.cpp example.cpp
</pre>
</div>
<p>
Note that R is sensitive to the name of the file and to the file
extension in C and C++ mode. The name of the wrapper file must be the
name of the library. Also in C++ mode, the file extension must be .cpp
rather than .cxx for the R compile command to recognize it.
Note that R is sensitive to the names of the files.
The name of the wrapper file must be the
name of the library unless you use the -o option to R when building the library, for example:
</p>
<div class="shell">
<pre>
swig -c++ -r -o example_wrap.cpp example.i
R CMD SHLIB -o example.so example_wrap.cpp example.cpp
</pre>
</div>
<p>
R is also sensitive to the name of the file
extension in C and C++ mode. In C++ mode, the file extension must be .cpp
rather than .cxx for the R compile command to recognize it. If your C++ code is
in a file using something other than a .cpp extension, then it may still work using PKG_LIBS:
</p>
<div class="shell">
<pre>
swig -c++ -r -o example_wrap.cpp example.i
PKG_LIBS="example.cxx" R CMD SHLIB -o example example_wrap.cpp
</pre>
</div>
<p>
The commands produces two files. A dynamic shared object file called
example.so, or example.dll, and an R wrapper file called example.R. To load these
@ -99,7 +119,7 @@ Without it, inheritance of wrapped objects may fail.
These two files can be loaded in any order
</p>
<H2><a name="R_nn4"></a>33.3 Precompiling large R files</H2>
<H2><a name="R_nn4"></a>35.3 Precompiling large R files</H2>
In cases where the R file is large, one make save a lot of loading
@ -117,7 +137,7 @@ will save a large amount of loading time.
<H2><a name="R_nn5"></a>33.4 General policy</H2>
<H2><a name="R_nn5"></a>35.4 General policy</H2>
<p>
@ -126,7 +146,7 @@ wrapping over the underlying functions and rely on the R type system
to provide R syntax.
</p>
<H2><a name="R_language_conventions"></a>33.5 Language conventions</H2>
<H2><a name="R_language_conventions"></a>35.5 Language conventions</H2>
<p>
@ -135,7 +155,7 @@ and [ are overloaded to allow for R syntax (one based indices and
slices)
</p>
<H2><a name="R_nn6"></a>33.6 C++ classes</H2>
<H2><a name="R_nn6"></a>35.6 C++ classes</H2>
<p>
@ -147,7 +167,7 @@ keep track of the pointer object which removes the necessity for a lot
of the proxy class baggage you see in other languages.
</p>
<H2><a name="R_nn7"></a>33.7 Enumerations</H2>
<H2><a name="R_nn7"></a>35.7 Enumerations</H2>
<p>

603
Doc/Manual/Ruby.html
View file

File diff suppressed because it is too large Load diff

561
Doc/Manual/SWIG.html
View file

@ -13,7 +13,7 @@
<li><a href="#SWIG_nn2">Running SWIG</a>
<ul>
<li><a href="#SWIG_nn3">Input format</a>
<li><a href="#output">SWIG Output</a>
<li><a href="#SWIG_output">SWIG Output</a>
<li><a href="#SWIG_nn5">Comments</a>
<li><a href="#SWIG_nn6">C Preprocessor</a>
<li><a href="#SWIG_nn7">SWIG Directives</a>
@ -44,6 +44,12 @@
<li><a href="#SWIG_nn26">Arrays</a>
<li><a href="#SWIG_readonly_variables">Creating read-only variables</a>
<li><a href="#SWIG_rename_ignore">Renaming and ignoring declarations</a>
<ul>
<li><a href="#SWIG_nn29">Simple renaming of specific identifiers</a>
<li><a href="#SWIG_advanced_renaming">Advanced renaming support</a>
<li><a href="#SWIG_limiting_renaming">Limiting global renaming rules</a>
<li><a href="#SWIG_chosen_unignore">Ignoring everything then wrapping a few selected symbols</a>
</ul>
<li><a href="#SWIG_default_args">Default/optional arguments</a>
<li><a href="#SWIG_nn30">Pointers to functions and callbacks</a>
</ul>
@ -53,7 +59,7 @@
<li><a href="#SWIG_nn33">Character strings and structures</a>
<li><a href="#SWIG_nn34">Array members</a>
<li><a href="#SWIG_structure_data_members">Structure data members</a>
<li><a href="#SWIG_nn36">C constructors and destructors </a>
<li><a href="#SWIG_nn36">C constructors and destructors</a>
<li><a href="#SWIG_adding_member_functions">Adding member functions to C structures</a>
<li><a href="#SWIG_nested_structs">Nested structures</a>
<li><a href="#SWIG_nn39">Other things to note about structure wrapping</a>
@ -92,7 +98,7 @@ chapters.
<p>
To run SWIG, use the <tt>swig</tt> command with options options and a filename like this:
To run SWIG, use the <tt>swig</tt> command with options and a filename like this:
</p>
<div class="shell"><pre>
@ -113,6 +119,7 @@ can be obtained by typing <tt>swig -help</tt> or <tt>swig
-clisp Generate CLISP wrappers
-cffi Generate CFFI wrappers
-csharp Generate C# wrappers
-go Generate Go wrappers
-guile Generate Guile wrappers
-java Generate Java wrappers
-lua Generate Lua wrappers
@ -120,8 +127,7 @@ can be obtained by typing <tt>swig -help</tt> or <tt>swig
-mzscheme Generate Mzscheme wrappers
-ocaml Generate Ocaml wrappers
-perl Generate Perl wrappers
-php4 Generate PHP4 wrappers
-php5 Generate PHP5 wrappers
-php Generate PHP wrappers
-pike Generate Pike wrappers
-python Generate Python wrappers
-r Generate R (aka GNU S) wrappers
@ -140,7 +146,9 @@ can be obtained by typing <tt>swig -help</tt> or <tt>swig
-l<em>file</em> Include a SWIG library file.
-module <em>name</em> Set the name of the SWIG module
-o <em>outfile</em> Name of output file
-outcurrentdir Set default output dir to current dir instead of input file's path
-outdir <em>dir</em> Set language specific files output directory
-pcreversion Display PCRE version information
-swiglib Show location of SWIG library
-version Show SWIG version number
@ -174,13 +182,8 @@ int bar(int x);
...
</pre></div>
<p>
The name of the module is supplied using the special <tt>%module</tt>
directive (or the <tt>-module</tt> command line option). This
directive must appear at the beginning of the file and is used to name
the resulting extension module (in addition, this name often defines
a namespace in the target language). If the module name is supplied on the
command line, it overrides the name specified with the
<tt>%module</tt> directive.
The module name is supplied using the special <tt>%module</tt>
directive. Modules are described further in the <a href="Modules.html#Modules_introduction">Modules Introduction</a> section.
</p>
<p>
@ -198,7 +201,7 @@ semantics in SWIG is analogous to that of the declarations section
used in input files to parser generation tools such as yacc or bison.
</p>
<H3><a name="output"></a>5.1.2 SWIG Output</H3>
<H3><a name="SWIG_output"></a>5.1.2 SWIG Output</H3>
<p>
@ -224,7 +227,7 @@ The C/C++ output file created by SWIG often
contains everything that is needed to construct a extension module
for the target scripting language. SWIG is not a stub compiler nor is it
usually necessary to edit the output file (and if you look at the output,
you probably won't want to). To build the final extension module, the
you probably won't want to). To build the final extension module, the
SWIG output file is compiled and linked with the rest of your C/C++
program to create a shared library.
</p>
@ -232,7 +235,7 @@ program to create a shared library.
<p>
Many target languages will also generate proxy class files in the
target language. The default output directory for these language
specific files is the same directory as the generated C/C++ file. This can
specific files is the same directory as the generated C/C++ file. This
can be modified using the <tt>-outdir</tt> option. For example:
</p>
@ -247,6 +250,17 @@ cppfiles/example_wrap.cpp
pyfiles/example.py
</pre></div>
<p>
If the <tt>-outcurrentdir</tt> option is used (without <tt>-o</tt>)
then SWIG behaves like a typical C/C++
compiler and the default output directory is then the current directory. Without
this option the default output directory is the path to the input file.
If <tt>-o</tt> and
<tt>-outcurrentdir</tt> are used together, <tt>-outcurrentdir</tt> is effectively ignored
as the output directory for the language files is the same directory as the
generated C/C++ file if not overidden with <tt>-outdir</tt>.
</p>
<H3><a name="SWIG_nn5"></a>5.1.3 Comments</H3>
@ -324,10 +338,13 @@ currently supported:
</p>
<ul>
<li>Non-conventional type declarations.
<li>
<p>
Non-conventional type declarations.
For example, SWIG does not support declarations such as the following
(even though this is legal C):
</p>
<div class="code">
<pre>
/* Non-conventional placement of storage specifier (extern) */
@ -349,15 +366,19 @@ if you're feeling particularly obfuscated, you can certainly break SWIG (althoug
</p>
</li>
<li>Running SWIG on C++ source files (what would appear in a .C or .cxx file)
is not recommended. Even though SWIG can parse C++ class declarations,
it ignores declarations that are decoupled from their
original class definition (the declarations are parsed, but a lot of warning
messages may be generated). For example:
<li>
<p>
Running SWIG on C++ source files (the code in a .C, .cpp or .cxx file) is not recommended.
The usual approach is to feed SWIG header files for parsing C++ definitions and declarations.
The main reason is if SWIG parses a scoped definition or declaration (as is normal for C++ source files),
it is ignored, unless a declaration for the symbol was parsed earlier.
For example
</p>
<div class="code">
<pre>
/* Not supported by SWIG */
/* bar not wrapped unless foo has been defined and
the declaration of bar within foo has already been parsed */
int foo::bar(int) {
... whatever ...
}
@ -365,9 +386,12 @@ int foo::bar(int) {
</div>
</li>
<li>Certain advanced features of C++ such as nested classes
are not yet supported. Please see the section on using SWIG
with C++ for more information.
<li>
<p>
Certain advanced features of C++ such as nested classes
are not yet fully supported. Please see the C++ <a href="SWIGPlus.html#SWIGPlus_nested_classes">Nested classes</a> section
for more information.
</p>
</ul>
<p>
@ -661,7 +685,6 @@ enum boolean {NO=0, YES=1};
enum months {JAN, FEB, MAR, APR, MAY, JUN, JUL, AUG,
SEP, OCT, NOV, DEC};
%constant double BLAH = 42.37;
#define F_CONST (double) 5 // A floating pointer constant with cast
#define PI_4 PI/4
#define FLAGS 0x04 | 0x08 | 0x40
@ -700,8 +723,15 @@ the declaration
<p>
defines a constant because <tt>PI</tt> was already defined as a
constant and the value is known.
However, for the same conservative reasons even a constant with a simple cast will be ignored, such as
</p>
<div class="code">
<pre>
#define F_CONST (double) 5 // A floating pointer constant with cast
</pre>
</div>
<p>
The use of constant expressions is allowed, but SWIG does not evaluate
them. Rather, it passes them through to the output file and lets the C
@ -775,6 +805,12 @@ In this case, the pointer <tt>e</tt> can change---it's only the value
being pointed to that is read-only.
</p>
<p>
Please note that for const parameters or return types used in a function, SWIG pretty much ignores
the fact that these are const, see the section on <a href="SWIGPlus.html#SWIGPlus_const">const-correctness</a>
for more information.
</p>
<p>
<b>Compatibility Note:</b> One reason for changing SWIG to handle
<tt>const</tt> declarations as read-only variables is that there are
@ -1590,7 +1626,7 @@ double y; // Read-write
<p>
The <tt>%mutable</tt> and <tt>%immutable</tt> directives are actually
<a href="Customization.html#features">%feature directives</a> defined like this:
<a href="Customization.html#Customization_features">%feature directives</a> defined like this:
</p>
<div class="code"><pre>
@ -1633,6 +1669,9 @@ generate a warning message. Simply change the directives to <tt>%immutable;</t
<H3><a name="SWIG_rename_ignore"></a>5.4.7 Renaming and ignoring declarations</H3>
<H4><a name="SWIG_nn29"></a>5.4.7.1 Simple renaming of specific identifiers</H4>
<p>
Normally, the name of a C declaration is used when that declaration is
wrapped into the target language. However, this may generate a
@ -1644,7 +1683,7 @@ directive as shown :</p>
// interface.i
%rename(my_print) print;
extern void print(char *);
extern void print(const char *);
%rename(foo) a_really_long_and_annoying_name;
extern int a_really_long_and_annoying_name;
@ -1697,9 +1736,10 @@ to ignore declarations that match a given identifier. For example:
<div class="code">
<pre>
%ignore print; // Ignore all declarations named print
%ignore _HAVE_FOO_H; // Ignore an include guard constant
%ignore MYMACRO; // Ignore a macro
...
%include "foo.h" // Grab a header file
#define MYMACRO 123
void print(const char *);
...
</pre>
</div>
@ -1711,12 +1751,6 @@ to add conditional compilation to the header. However, it should be stressed t
declarations. If you need to remove a whole section of problematic code, the SWIG preprocessor should be used instead.
</p>
<p>
More powerful variants of <tt>%rename</tt> and <tt>%ignore</tt> directives can be used to help
wrap C++ overloaded functions and methods or C++ methods which use default arguments. This is described in the
<a href="SWIGPlus.html#ambiguity_resolution_renaming">Ambiguity resolution and renaming</a> section in the C++ chapter.
</p>
<p>
<b>Compatibility note: </b> Older versions of SWIG provided a special <tt>%name</tt> directive for renaming declarations.
For example:
@ -1724,7 +1758,7 @@ For example:
<div class="code">
<pre>
%name(output) extern void print(char *);
%name(output) extern void print(const char *);
</pre>
</div>
@ -1733,6 +1767,337 @@ This directive is still supported, but it is deprecated and should probably be a
directive is more powerful and better supports wrapping of raw header file information.
</p>
<H4><a name="SWIG_advanced_renaming"></a>5.4.7.2 Advanced renaming support</H4>
<p>
While writing <tt>%rename</tt> for specific declarations is simple enough,
sometimes the same renaming rule needs to be applied to many, maybe all,
identifiers in the SWIG input. For example, it may be necessary to apply some
transformation to all the names in the target language to better follow its
naming conventions, like adding a specific prefix to all wrapped functions. Doing it individually
for each function is impractical so SWIG supports applying a renaming rule to
all declarations if the name of the identifier to be renamed is not specified:
</p>
<div class="code">
<pre>
%rename("myprefix_%s") ""; // print&nbsp;-&gt;&nbsp;myprefix_print
</pre>
</div>
<p>
This also shows that the argument of <tt>%rename</tt> doesn't have to be a
literal string but can be a <tt>printf()</tt>-like format string. In the
simplest form, <tt>"%s"</tt> is replaced with the name of the original
declaration, as shown above. However this is not always enough and SWIG
provides extensions to the usual format string syntax to allow applying a
(SWIG-defined) function to the argument. For example, to wrap all C functions
<tt>do_something_long()</tt> as more Java-like <tt>doSomethingLong()</tt> you
can use the <tt>"lowercamelcase"</tt> extended format specifier like this:
</p>
<div class="code">
<pre>
%rename("%(lowercamelcase)s") ""; // foo_bar -&gt; fooBar; FooBar -&gt; fooBar
</pre>
</div>
<p>
Some functions can be parametrized, for example the <tt>"strip"</tt> one
strips the provided prefix from its argument. The prefix is specified as part
of the format string, following a colon after the function name:
</p>
<div class="code">
<pre>
%rename("%(strip:[wx])s") ""; // wxHello -&gt; Hello; FooBar -&gt; FooBar
</pre>
</div>
<p>
Below is the table summarizing all currently defined functions with an example
of applying each one. Note that some of them have two names, a shorter one
and a more descriptive one, but the two functions are otherwise equivalent:
</p>
<table summary="Format string functions" border="1" cellpadding="5">
<tr>
<th>Function</th><th>Returns</th><th colspan=2>Example (in/out)</th>
</tr>
<tr>
<td><tt>uppercase</tt> or <tt>upper</tt></td>
<td>Upper case version of the string.</td>
<td><tt>Print</tt></td><td><tt>PRINT</tt></td>
</tr>
<tr>
<td><tt>lowercase</tt> or <tt>lower</tt></td>
<td>Lower case version of the string.</td>
<td><tt>Print</tt></td><td><tt>print</tt></td>
</tr>
<tr>
<td><tt>title</tt></td>
<td>String with first letter capitalized and the rest in lower case.</td>
<td><tt>print</tt></td><td><tt>Print</tt></td>
</tr>
<tr>
<td><tt>firstuppercase</tt></td>
<td>String with the first letter capitalized and the rest unchanged.</td>
<td><tt>printIt</tt></td><td><tt>PrintIt</tt></td>
</tr>
<tr>
<td><tt>firstlowercase</tt></td>
<td>String with the first letter in lower case and the rest unchanged.</td>
<td><tt>PrintIt</tt></td><td><tt>printIt</tt></td>
</tr>
<tr>
<td><tt>camelcase</tt> or <tt>ctitle</tt></td>
<td>String with capitalized first letter and any letter following an
underscore (which are removed in the process) and rest in lower case.</td>
<td><tt>print_it</tt></td><td><tt>PrintIt</tt></td>
</tr>
<tr>
<td><tt>lowercamelcase</tt> or <tt>lctitle</tt></td>
<td>String with every letter following an underscore (which is removed in
the process) capitalized and rest, including the first letter, in lower
case.</td>
<td><tt>print_it</tt></td><td><tt>printIt</tt></td>
</tr>
<tr>
<td><tt>undercase</tt> or <tt>utitle</tt></td>
<td>Lower case string with underscores inserted before every upper case
letter in the original string and any number not at the end of string.
Logically, this is the reverse of <tt>camelcase</tt>.</td>
<td><tt>PrintIt</tt></td><td><tt>print_it</tt></td>
</tr>
<tr>
<td><tt>schemify</tt></td>
<td>String with all underscores replaced with dashes, resulting in more
Lispers/Schemers-pleasing name.</td>
<td><tt>print_it</tt></td><td><tt>print-it</tt></td>
</tr>
<tr>
<td><tt>strip:[prefix]</tt></td>
<td>String without the given prefix or the original string if it doesn't
start with this prefix. Note that square brackets should be used
literally, e.g. <tt>%rename("strip:[wx]")</tt></td>
<td><tt>wxPrint</tt></td><td><tt>Print</tt></td>
</tr>
<tr>
<td><span style="white-space: nowrap;"><tt>regex:/pattern/subst/</tt></span></td>
<td>String after (Perl-like) regex substitution operation. This function
allows to apply arbitrary regular expressions to the identifier names. The
<i>pattern</i> part is a regular expression in Perl syntax (as supported
by the <a href="http://www.pcre.org/">Perl Compatible Regular Expressions (PCRE)</a>)
library and the <i>subst</i> string
can contain back-references introduced by <tt>'\'</tt> or, as backslashes need
to be escaped in C strings, rather by <tt>"\\"</tt>. For example, to remove
any alphabetic prefix before an underscore you could use the following directive:
<tt>%rename("regex:/(\\w+)_(.*)/\\2/")</tt></td>
<td><tt>Prefix_Print</tt></td><td><tt>Print</tt></td>
</tr>
<tr>
<td><tt>command:cmd</tt></td>
<td>Output of an external command <tt>cmd</tt> with the string passed to
it as input. Notice that this function is extremely slow compared to all
the other ones as it involves spawning a separate process and using it for
many declarations is not recommended. The <i>cmd</i> is not enclosed in
square brackets but must be terminated with a triple <tt>'&lt;'</tt> sign,
e.g. <tt>%rename("command:tr&nbsp;-d&nbsp;aeiou &lt;&lt;&lt;")</tt>
(nonsensical example removing all vowels)</td>
<td><tt>Print</tt></td><td><tt>Prnt</tt></td>
</tr>
</table>
<p>
The most general function of all of the above ones (not counting
<tt>command</tt> which is even more powerful in principle but which should
generally be avoided because of performance considerations) is the
<tt>regex</tt> one. Here are some more examples of its use:
</p>
<div class="code">
<pre>
// Strip the wx prefix from all identifiers except those starting with wxEVT
%rename("%(regex:/wx(?!EVT)(.*)/\\1/)s") ""; // wxSomeWidget -&gt; SomeWidget
// wxEVT_PAINT -&gt; wxEVT_PAINT
// Apply a rule for renaming the enum elements to avoid the common prefixes
// which are redundant in C#/Java
%rename("%(regex:/^([A-Z][a-z]+)+_(.*)/\\2/)s", %$isenumitem) ""; // Colour_Red -&gt; Red
// Remove all "Set/Get" prefixes.
%rename("%(regex:/^(Set|Get)(.*)/\\2/)s") ""; // SetValue -&gt; Value
// GetValue -&gt; Value
</pre>
</div>
<p>
As before, everything that was said above about <tt>%rename</tt> also applies to
<tt>%ignore</tt>. In fact, the latter is just a special case of the former and
ignoring an identifier is the same as renaming it to the special
<tt>"$ignore"</tt> value. So the following snippets
</p>
<div class="code">
<pre>
%ignore print;
</pre>
</div>
<p>
and
</p>
<div class="code">
<pre>
%rename("$ignore") print;
</pre>
</div>
<p>
are exactly equivalent and <tt>%rename</tt> can be used to selectively ignore
multiple declarations using the previously described matching possibilities.
</p>
<H4><a name="SWIG_limiting_renaming"></a>5.4.7.3 Limiting global renaming rules</H4>
<p>
As explained in the previous sections, it is possible to either rename
individual declarations or apply a rename rule to all of them at once. In
practice, the latter is however rarely appropriate as there are always some
exceptions to the general rules. To deal with them, the scope of an unnamed
<tt>%rename</tt> can be limited using subsequent <tt>match</tt> parameters.
They can be applied to any of the attributes associated by SWIG with the
declarations appearing in its input. For example:
</p>
<div class="code">
<pre>
%rename("foo", match$name="bar") "";
</pre>
</div>
<p>
can be used to achieve the same effect as the simpler
</p>
<div class="code">
<pre>
%rename("foo") bar;
</pre>
</div>
<p>
and so is not very interesting on its own. However <tt>match</tt> can also be
applied to the declaration type, for example <tt>match="class"</tt> restricts
the match to class declarations only (in C++) and <tt>match="enumitem"</tt>
restricts it to the enum elements. SWIG also provides convenience macros for
such match expressions, for example
</p>
<div class="code">
<pre>
%rename("%(title)s", %$isenumitem) "";
</pre>
</div>
<p>
will capitalize the names of all the enum elements but not change the case of
the other declarations. Similarly, <tt>%$isclass</tt>, <tt>%$isfunction</tt>,
<tt>%$isconstructor</tt>, <tt>%$isunion</tt>, <tt>%$istemplate</tt>,
and <tt>%$isvariable</tt> can be used. Many other checks are possible and this
documentation is not exhaustive, see the "%rename predicates" section in
<tt>swig.swg</tt> for the full list of supported match expressions.
</p>
<p>
In addition to literally matching some string with <tt>match</tt> you can
also use <tt>regexmatch</tt> or <tt>notregexmatch</tt> to match a string
against a regular expression. For example, to ignore all functions having
"Old" as a suffix you could use
</p>
<div class="code">
<pre>
%rename("$ignore", regexmatch$name="Old$") "";
</pre>
</div>
<p>
For simple cases like this, specifying the regular expression for the
declaration name directly can be preferable and can also be done using
<tt>regextarget</tt>:
</p>
<div class="code">
<pre>
%rename("$ignore", regextarget=1) "Old$";
</pre>
</div>
<p>
Notice that the check is done only against the name of the declaration
itself, if you need to match the full name of a C++ declaration you
must use <tt>fullname</tt> attribute:
</p>
<div class="code">
<pre>
%rename("$ignore", regextarget=1, fullname=1) "NameSpace::ClassName::.*Old$";
</pre>
</div>
<p>
As for <tt>notregexmatch</tt>, it restricts the match only to the strings not
matching the specified regular expression. So to rename all declarations to lower case
except those consisting of capital letters only:
</p>
<div class="code">
<pre>
%rename("$(lower)s", notregexmatch$name="^[A-Z]+$") "";
</pre>
</div>
<p>
Finally, variants of <tt>%rename</tt> and <tt>%ignore</tt> directives can be used to help
wrap C++ overloaded functions and methods or C++ methods which use default arguments. This is described in the
<a href="SWIGPlus.html#SWIGPlus_ambiguity_resolution_renaming">Ambiguity resolution and renaming</a> section in the C++ chapter.
</p>
<H4><a name="SWIG_chosen_unignore"></a>5.4.7.4 Ignoring everything then wrapping a few selected symbols</H4>
<p>
Using the techniques described above it is possible to ignore everything in a header and then
selectively wrap a few chosen methods or classes. For example, consider a header, <tt>myheader.h</tt>
which has many classes in it and just the one class called <tt>Star</tt> is wanted within this header,
the following approach could be taken:
</p>
<div class="code">
<pre>
%ignore ""; // Ignore everything
// Unignore chosen class 'Star'
%rename("%s") Star;
// As the ignore everything will include the constructor, destructor, methods etc
// in the class, these have to be explicitly unignored too:
%rename("%s") Star::Star;
%rename("%s") Star::~Star;
%rename("%s") Star::shine; // named method
%include "myheader.h"
</pre>
</div>
<p>
Another approach which might be more suitable as it does not require naming all the methods in the
chosen class is to begin by ignoring just the classes. This does not add an explicit ignore to any
members of the class, so when the chosen class is unignored, all of its methods will be wrapped.
</p>
<div class="code">
<pre>
%rename($ignore, %$isclass) ""; // Only ignore all classes
%rename("%s") Star; // Unignore 'Star'
%include "myheader.h"
</pre>
</div>
<H3><a name="SWIG_default_args"></a>5.4.8 Default/optional arguments</H3>
@ -1896,13 +2261,13 @@ normally, just use the original function name such as <tt>add()</tt>.
<p>
SWIG provides a number of extensions to standard C printf formatting
that may be useful in this context. For instance, the following
variation installs the callbacks as all upper-case constants such as
variation installs the callbacks as all upper case constants such as
<tt>ADD</tt>, <tt>SUB</tt>, and <tt>MUL</tt>:
</p>
<div class="code"><pre>
/* Some callback functions */
%callback("%(upper)s");
%callback("%(uppercase)s");
int add(int,int);
int sub(int,int);
int mul(int,int);
@ -1910,7 +2275,7 @@ int mul(int,int);
</pre></div>
<p>
A format string of <tt>"%(lower)s"</tt> converts all characters to lower-case.
A format string of <tt>"%(lowercase)s"</tt> converts all characters to lower case.
A string of <tt>"%(title)s"</tt> capitalizes the first character and converts the
rest to lower case.
</p>
@ -1919,7 +2284,8 @@ rest to lower case.
And now, a final note about function pointer support. Although SWIG
does not normally allow callback functions to be written in the target language, this
can be accomplished with the use of typemaps and other advanced SWIG features.
This is described in a later chapter.
See the <a href="Typemaps.html#Typemaps">Typemaps chapter</a> for more about typemaps
and individual target language chapters for more on callbacks and the 'director' feature.
</p>
<H2><a name="SWIG_nn31"></a>5.5 Structures and unions</H2>
@ -2219,13 +2585,13 @@ void Foo_w_set(FOO *f, WORD value) {
<p>
<b>Compatibility Note: </b> SWIG-1.3.11 and earlier releases transformed all non-primitive member datatypes
to pointers. Starting in SWIG-1.3.12, this transformation <em>only</em> occurs if a datatype is known to be a structure,
class, or union. This is unlikely to break existing code. However, if you need to tell SWIG that an undeclared
<b>Compatibility Note:</b> SWIG-1.3.11 and earlier releases transformed all non-primitive member datatypes
to pointers. Starting in SWIG-1.3.12, this transformation <em>only</em> occurs if a datatype is known to be a structure,
class, or union. This is unlikely to break existing code. However, if you need to tell SWIG that an undeclared
datatype is really a struct, simply use a forward struct declaration such as <tt>"struct Foo;"</tt>.
</p>
<H3><a name="SWIG_nn36"></a>5.5.5 C constructors and destructors </H3>
<H3><a name="SWIG_nn36"></a>5.5.5 C constructors and destructors</H3>
<p>
@ -2282,7 +2648,7 @@ struct Bar { // Default constructor generated.
Since ignoring the implicit or default destructors most of the times
produce memory leaks, SWIG will always try to generate them. If
needed, however, you can selectively disable the generation of the
default/implicit destructor by using <tt>%nodefaultdtor </tt>
default/implicit destructor by using <tt>%nodefaultdtor</tt>
</p>
<div class="code">
@ -2350,7 +2716,7 @@ You can make a <tt>Vector</tt> look a lot like a class by writing a SWIG interfa
#include "vector.h"
%}
%include vector.h // Just grab original C header file
%include "vector.h" // Just grab original C header file
%extend Vector { // Attach these functions to struct Vector
Vector(double x, double y, double z) {
Vector *v;
@ -2376,6 +2742,10 @@ You can make a <tt>Vector</tt> look a lot like a class by writing a SWIG interfa
<p>
Note the usage of the <tt>$self</tt> special variable.
Its usage is identical to a C++ 'this' pointer and should be used whenever access to the struct instance is required.
Also note that C++ constructor and destructor syntax has been used to simulate a constructor and destructor, even for C code.
There is one subtle difference to a normal C++ constructor implementation though and that is although the constructor declaration
is as per a normal C++ constructor, the newly constructed object must be returned <b>as if</b> the constructor declaration
had a return value, a <tt>Vector *</tt> in this case.
</p>
<p>
@ -2473,7 +2843,7 @@ instead of a method. To do this, you might write some code like this:
// Now supply the implementation of the Vector_magnitude_get function
%{
const double Vector_magnitude_get(Vector *v) {
return (const double) return sqrt(v-&gt;x*v-&gt;x+v-&gt;y*v-&gt;y+v-&gt;z*v-&gt;z);
return (const double) sqrt(v-&gt;x*v-&gt;x+v-&gt;y*v-&gt;y+v-&gt;z*v-&gt;z);
}
%}
@ -2486,41 +2856,53 @@ of the object.
</p>
<p>
A similar technique can also be used to work with problematic data members.
A similar technique can also be used to work with data members that you want to process.
For example, consider this interface:
</p>
<div class="code">
<pre>
struct Person {
char name[50];
...
}
typedef struct {
char name[50];
...
} Person;
</pre>
</div>
<p>
By default, the <tt>name</tt> attribute is read-only because SWIG does not
normally know how to modify arrays. However, you can rewrite the interface
as follows to change this:
Say you wanted to ensure <tt>name</tt> was always upper case, you can rewrite
the interface as follows to ensure this occurs whenever a name is read or written to:
</p>
<div class="code">
<pre>
struct Person {
%extend {
char *name;
}
...
typedef struct {
%extend {
char name[50];
}
...
} Person;
%{
#include &lt;string.h&gt;
#include &lt;ctype.h&gt;
void make_upper(char *name) {
char *c;
for (c = name; *c; ++c)
*c = (char)toupper((int)*c);
}
// Specific implementation of set/get functions
%{
/* Specific implementation of set/get functions forcing capitalization */
char *Person_name_get(Person *p) {
return p-&gt;name;
make_upper(p-&gt;name);
return p-&gt;name;
}
void Person_name_set(Person *p, char *val) {
strncpy(p-&gt;name,val,50);
strncpy(p-&gt;name,val,50);
make_upper(p-&gt;name);
}
%}
</pre>
@ -2530,7 +2912,7 @@ void Person_name_set(Person *p, char *val) {
Finally, it should be stressed that even though <tt>%extend</tt>
can be used to add new data members, these new members can not require
the allocation of additional storage in the object (e.g., their values must
be entirely synthesized from existing attributes of the structure).
be entirely synthesized from existing attributes of the structure or obtained elsewhere).
</p>
<p>
@ -2613,10 +2995,16 @@ $o-&gt;{intRep}-&gt;{ivalue} = 7 # Change value of o.intRep.ivalue
</pre></div>
<p>
If you have a lot nested structure declarations, it is
If you have a lot of nested structure declarations, it is
advisable to double-check them after running SWIG. Although,
there is a good chance that they will work, you may have to
modify the interface file in certain cases.
</p>
<p>
Finally, note that nesting is handled differently in C++ mode,
see <a href="SWIGPlus.html#SWIGPlus_nested_classes">Nested classes</a>.
</p>
<H3><a name="SWIG_nn39"></a>5.5.8 Other things to note about structure wrapping</H3>
@ -2694,12 +3082,17 @@ output of SWIG is structured first.</p>
<p>
When SWIG creates its output file, it is broken up into four sections
When SWIG creates its output file, it is broken up into five sections
corresponding to runtime code, headers, wrapper functions, and module
initialization code (in that order).
</p>
<ul>
<li><b>Begin section</b>. <br>
A placeholder for users to put code at the beginning of the C/C++ wrapper file.
This is most often used to define preprocessor macros that are used in later sections.
</li>
<li><b>Runtime code</b>. <br>
This code is internal to SWIG and is used to include
type-checking and other support functions that are used by the rest of the module.
@ -2726,11 +3119,16 @@ the module upon loading.
<p>
Code is inserted into the appropriate code section by using one
of the following code insertion directives:
of the code insertion directives listed below. The order of the sections in
the wrapper file is as shown:
</p>
<div class="code">
<pre>
%begin %{
... code in begin section ...
%}
%runtime %{
... code in runtime section ...
%}
@ -2751,10 +3149,12 @@ of the following code insertion directives:
<p>
The bare <tt>%{ ... %}</tt> directive is a shortcut that is the same as
<tt>%header %{ ... %}</tt>.
<tt>%header %{ ... %}</tt>.
</p>
<p>
The <tt>%begin</tt> section is effectively empty as it just contains the SWIG banner by default.
This section is provided as a way for users to insert code at the top of the wrapper file before any other code is generated.
Everything in a code insertion block is copied verbatim into the output file and is
not parsed by SWIG. Most SWIG input files have at least one such block to include header
files and support C code. Additional code blocks may be placed anywhere in a
@ -2865,10 +3265,16 @@ interface to your program.
SWIG's <tt>%include</tt> directive to process an entire C
source/header file.
<li>Make sure everything in the interface file uses ANSI C/C++syntax.
<li>Make sure everything in the interface file uses ANSI C/C++ syntax.
<li>Make sure all necessary `<tt>typedef</tt>' declarations and
type-information is available in the interface file.
type-information is available in the interface file.
In particular, ensure that the type information is specified in the correct order as required by a C/C++ compiler.
Most importantly, define a type before it is used! A C compiler will tell you
if the full type information is not available if it is needed, whereas
SWIG will usually not warn or error out as it is designed to work without
full type information. However, if type information is not specified
correctly, the wrappers can be sub-optimal and even result in uncompileable C/C++ code.
<li>If your program has a main() function, you may need to rename it
(read on).
@ -2927,16 +3333,21 @@ extern void dump(FILE *f);
<p>
Of course, in this case, our header file is pretty simple so we could
have made an interface file like this as well:</p>
use a simpler approach and use an interface file like this:</p>
<div class="code"><pre>
/* File : interface.i */
%module mymodule
%include header.h
%{
#include "header.h"
%}
%include "header.h"
</pre></div>
<p>
Naturally, your mileage may vary.</p>
The main advantage of this approach is minimal maintenance of an interface file for when the header file changes in the future.
In more complex projects, an interface file containing numerous <tt>%include</tt> and <tt>#include</tt> statements like this is one of the most common approaches to interface file design due to lower maintenance overhead.
</p>
<H3><a name="SWIG_nn48"></a>5.7.3 Why use separate interface files?</H3>

466
Doc/Manual/SWIGPlus.html
View file

@ -42,21 +42,25 @@
<ul>
<li><a href="#SWIGPlus_nn24">Dispatch function generation</a>
<li><a href="#SWIGPlus_nn25">Ambiguity in Overloading</a>
<li><a href="#ambiguity_resolution_renaming">Ambiguity resolution and renaming</a>
<li><a href="#SWIGPlus_ambiguity_resolution_renaming">Ambiguity resolution and renaming</a>
<li><a href="#SWIGPlus_nn27">Comments on overloading</a>
</ul>
<li><a href="#SWIGPlus_nn28">Wrapping overloaded operators</a>
<li><a href="#SWIGPlus_class_extension">Class extension</a>
<li><a href="#SWIGPlus_nn30">Templates</a>
<li><a href="#SWIGPlus_nn31">Namespaces</a>
<li><a href="#SWIGPlus_namespaces">Namespaces</a>
<ul>
<li><a href="#SWIGPlus_nspace">The nspace feature for namespaces</a>
</ul>
<li><a href="#SWIGPlus_renaming_templated_types_namespaces">Renaming templated types in namespaces</a>
<li><a href="#SWIGPlus_exception_specifications">Exception specifications</a>
<li><a href="#SWIGPlus_catches">Exception handling with %catches</a>
<li><a href="#SWIGPlus_nn33">Pointers to Members</a>
<li><a href="#SWIGPlus_nn34">Smart pointers and operator-&gt;()</a>
<li><a href="#SWIGPlus_smart_pointers">Smart pointers and operator-&gt;()</a>
<li><a href="#SWIGPlus_ref_unref">C++ reference counted objects - ref/unref feature</a>
<li><a href="#SWIGPlus_nn35">Using declarations and inheritance</a>
<li><a href="#SWIGPlus_nested_classes">Nested classes</a>
<li><a href="#SWIGPlus_nn37">A brief rant about const-correctness</a>
<li><a href="#SWIGPlus_const">A brief rant about const-correctness</a>
<li><a href="#SWIGPlus_nn42">Where to go for more information</a>
</ul>
</div>
@ -1125,7 +1129,7 @@ For example if a method has ten default arguments, then eleven wrapper methods a
<p>
Please see the <a href="Customization.html#Customization_features_default_args">Features and default arguments</a>
section for more information on using <tt>%feature</tt> with functions with default arguments.
The <a href="#ambiguity_resolution_renaming">Ambiguity resolution and renaming</a> section
The <a href="#SWIGPlus_ambiguity_resolution_renaming">Ambiguity resolution and renaming</a> section
also deals with using <tt>%rename</tt> and <tt>%ignore</tt> on methods with default arguments.
If you are writing your own typemaps for types used in methods with default arguments, you may also need to write a <tt>typecheck</tt> typemap.
See the <a href="Typemaps.html#Typemaps_overloading">Typemaps and overloading</a> section for details or otherwise
@ -1153,8 +1157,9 @@ public:
<p>
This is great for reducing the size of the wrappers, but the caveat is it does not work for the strongly typed languages
which don't have optional arguments in the language, such as C# and Java.
This is great for reducing the size of the wrappers, but the caveat is it does not work for the statically typed languages,
such as C# and Java,
which don't have optional arguments in the language,
Another restriction of this feature is that it cannot handle default arguments that are not public.
The following example illustrates this:
</p>
@ -1615,7 +1620,7 @@ warning message like this:
<div class="shell">
<pre>
example.i:18: Warning(401): Nothing known about base class 'Foo'. Ignored.
example.i:18: Warning 401: Nothing known about base class 'Foo'. Ignored.
</pre>
</div>
@ -2030,7 +2035,8 @@ Therefore, when SWIG encounters this situation, it may generate a warning messag
<div class="shell">
<pre>
example.i:4: Warning(509): Overloaded foo(long) is shadowed by foo(int) at example.i:3.
example.i:4: Warning 509: Overloaded method foo(long) effectively ignored,
example.i:3: Warning 509: as it is shadowed by foo(int).
</pre>
</div>
@ -2040,7 +2046,8 @@ or for statically typed languages like Java:
<div class="shell">
<pre>
example.i:4: Warning(516): Overloaded method foo(long) ignored. Method foo(int)
example.i:4: Warning 516: Overloaded method foo(long) ignored,
example.i:3: Warning 516: using foo(int) instead.
at example.i:3 used.
</pre>
</div>
@ -2090,7 +2097,7 @@ When wrapping an overloaded function, there is a chance that you will get an err
<div class="shell">
<pre>
example.i:3: Warning(467): Overloaded foo(int) not supported (no type checking
example.i:3: Warning 467: Overloaded foo(int) not supported (no type checking
rule for 'int').
</pre>
</div>
@ -2121,7 +2128,7 @@ it means that the target language module has not yet implemented support for ove
functions and methods. The only way to fix the problem is to read the next section.
</p>
<H3><a name="ambiguity_resolution_renaming"></a>6.15.3 Ambiguity resolution and renaming</H3>
<H3><a name="SWIGPlus_ambiguity_resolution_renaming"></a>6.15.3 Ambiguity resolution and renaming</H3>
<p>
@ -3245,22 +3252,39 @@ public:
</div>
<p>
SWIG should be able to handle most simple uses of partial specialization. However, it may fail
to match templates properly in more complicated cases. For example, if you have this code,
SWIG supports both template explicit specialization and partial specialization. Consider:
</p>
<div class="code">
<pre>
template&lt;class T1, class T2&gt; class Foo&lt;T1, T2 *&gt; { };
template&lt;class T1, class T2&gt; class Foo { }; // (1) primary template
template&lt;&gt; class Foo&lt;double *, int *&gt; { }; // (2) explicit specialization
template&lt;class T1, class T2&gt; class Foo&lt;T1, T2 *&gt; { }; // (3) partial specialization
</pre>
</div>
<p>
SWIG isn't able to match it properly for instantiations like <tt>Foo&lt;int *, int *&gt;</tt>.
This problem is not due to parsing, but due to the fact that SWIG does not currently implement all
of the C++ argument deduction rules.
SWIG is able to properly match explicit instantiations:
</p>
<div class="code">
<pre>
<tt>Foo&lt;double *, int *&gt;</tt> // explicit specialization matching (2)
</pre>
</div>
<p>
SWIG implements template argument deduction so that the following partial specialization examples work just like they would with a C++ compiler:
</p>
<div class="code">
<pre>
<tt>Foo&lt;int *, int *&gt;</tt> // partial specialization matching (3)
<tt>Foo&lt;int *, const int *&gt;</tt> // partial specialization matching (3)
<tt>Foo&lt;int *, int **&gt;</tt> // partial specialization matching (3)
</pre>
</div>
<p>
Member function templates are supported. The underlying principle is the same
as for normal templates--SWIG can't create a wrapper unless you provide
@ -3333,7 +3357,7 @@ public:
<p>
In this case, the <tt>%extend</tt> directive is not needed, and
<tt>%template</tt> does the exactly same job, i.e., it adds two new
<tt>%template</tt> does exactly the same job, i.e., it adds two new
methods to the Foo class.
</p>
@ -3470,7 +3494,7 @@ instead:
<p>
In this case, the default and conversion constructors have the same
name. Hence, Swig will overload them and define an unique visible
name. Hence, SWIG will overload them and define an unique visible
constructor, that will dispatch the proper call depending on the argument
type.
</p>
@ -3627,12 +3651,16 @@ as the class name. For example:
Similar changes apply to typemaps and other customization features.
</p>
<H2><a name="SWIGPlus_nn31"></a>6.19 Namespaces</H2>
<H2><a name="SWIGPlus_namespaces"></a>6.19 Namespaces</H2>
<p>
Support for C++ namespaces is a relatively late addition to SWIG,
first appearing in SWIG-1.3.12. Before describing the implementation,
Support for C++ namespaces is comprehensive, but by default simple, however,
some target languages can turn on more advanced namespace support via the
<a href="#SWIGPlus_nspace">nspace feature</a>, described later.
Code within unnamed namespaces is ignored as there is no external
access to symbols declared within the unnamed namespace.
Before detailing the default implementation for named namespaces,
it is worth noting that the semantics of C++ namespaces is extremely
non-trivial--especially with regard to the C++ type system and class
machinery. At a most basic level, namespaces are sometimes used to
@ -3816,7 +3844,7 @@ When this conflict occurs, you will get an error message that resembles this:
<div class="shell">
<pre>
example.i:26. Error. 'foo' is multiply defined in the generated module.
example.i:26. Error. 'foo' is multiply defined in the generated target language module.
example.i:23. Previous declaration of 'foo'
</pre>
</div>
@ -4072,6 +4100,87 @@ with any namespace awareness. In the future, language modules may or may not p
more advanced namespace support.
</p>
<H3><a name="SWIGPlus_nspace"></a>6.19.1 The nspace feature for namespaces</H3>
<p>
Some target languages provide support for the <tt>nspace</tt> <a href="Customization.html#Customization_features">feature</a>.
The feature can be applied to any class, struct, union or enum declared within a named namespace.
The feature wraps the type within the target language specific concept of a namespace,
for example, a Java package or C# namespace.
Please see the language specific sections to see if the target language you are interested in supports the nspace feature.
</p>
<p>
The feature is demonstrated below for C# using the following example:
</p>
<div class="code">
<pre>
%feature("nspace") MyWorld::Material::Color;
%nspace MyWorld::Wrapping::Color; // %nspace is a macro for %feature("nspace")
namespace MyWorld {
namespace Material {
class Color {
...
};
}
namespace Wrapping {
class Color {
...
};
}
}
</pre>
</div>
<p>
Without the <tt>nspace</tt> feature directives above or <tt>%rename</tt>, you would get the following warning resulting in just one of the <tt>Color</tt> classes being available for use from the target language:
</p>
<div class="shell">
<pre>
example.i:9: Error: 'Color' is multiply defined in the generated target language module.
example.i:5: Error: Previous declaration of 'Color'
</pre>
</div>
<p>
With the <tt>nspace</tt> feature the two <tt>Color</tt> classes are wrapped into the equivalent C# namespaces.
A fully qualified constructor call of each these two types in C# is then:
</p>
<div class="targetlang">
<pre>
MyWorld.Material.Color materialColor = new MyWorld.Material.Color();
MyWorld.Wrapping.Color wrappingColor = new MyWorld.Wrapping.Color();
</pre>
</div>
<p>
Note that the <tt>nspace</tt> feature does not apply to variables and functions simply declared in a namespace. For example, the following symbols cannot co-exist in the target language without renaming. This may change in a future version.
</p>
<div class="code">
<pre>
namespace MyWorld {
namespace Material {
int quantity;
void dispatch();
}
namespace Wrapping {
int quantity;
void dispatch();
}
}
</pre>
</div>
<p>
<b>Compatibility Note:</b> The nspace feature was first introduced in SWIG-2.0.0.
</p>
<H2><a name="SWIGPlus_renaming_templated_types_namespaces"></a>6.20 Renaming templated types in namespaces</H2>
@ -4084,8 +4193,9 @@ In the example below, the generic template type is used to rename to <tt>bbb</tt
<div class="code">
<pre>
%rename(bbb) Space::ABC::aaa(T t); // will match but with lower precedence than ccc
%rename(ccc) Space::ABC&lt;Space::XYZ&gt;::aaa(Space::XYZ t); // will match but with higher precedence than bbb
%rename(bbb) Space::ABC::aaa(T t); // will match but with lower precedence than ccc
%rename(ccc) Space::ABC&lt;Space::XYZ&gt;::aaa(Space::XYZ t);// will match but with higher precedence
// than bbb
namespace Space {
class XYZ {};
@ -4106,9 +4216,9 @@ Below shows how %rename can be placed inside a namespace.
<div class="code">
<pre>
namespace Space {
%rename(bbb) ABC::aaa(T t); // will match but with lower precedence than ccc
%rename(ccc) ABC&lt;Space::XYZ&gt;::aaa(Space::XYZ t); // will match but with higher precedence than bbb
%rename(ddd) ABC&lt;Space::XYZ&gt;::aaa(XYZ t); // will not match
%rename(bbb) ABC::aaa(T t); // will match but with lower precedence than ccc
%rename(ccc) ABC&lt;Space::XYZ&gt;::aaa(Space::XYZ t);// will match but with higher precedence than bbb
%rename(ddd) ABC&lt;Space::XYZ&gt;::aaa(XYZ t); // will not match
}
namespace Space {
@ -4130,11 +4240,11 @@ The following example shows how %rename can be placed within %extend.
<pre>
namespace Space {
%extend ABC {
%rename(bbb) aaa(T t); // will match but with lower precedence than ccc
%rename(bbb) aaa(T t); // will match but with lower precedence than ccc
}
%extend ABC&lt;Space::XYZ&gt; {
%rename(ccc) aaa(Space::XYZ t); // will match but with higher precedence than bbb
%rename(ddd) aaa(XYZ t); // will not match
%rename(ccc) aaa(Space::XYZ t);// will match but with higher precedence than bbb
%rename(ddd) aaa(XYZ t); // will not match
}
}
@ -4196,7 +4306,7 @@ is outlined in the <a href="Typemaps.html#throws_typemap">"throws" typemap</a> s
<p>
Since exception specifications are sometimes only used sparingly, this alone may not be enough to
properly handle C++ exceptions. To do that, a different set of special SWIG directives are used.
Consult the "<a href="Customization.html#exception">Exception handling with %exception</a>" section for details.
Consult the "<a href="Customization.html#Customization_exception">Exception handling with %exception</a>" section for details.
The next section details a way of simulating an exception specification or replacing an existing one.
</p>
@ -4300,7 +4410,7 @@ when checking types. However, no such support is currently provided
for member pointers.
</p>
<H2><a name="SWIGPlus_nn34"></a>6.24 Smart pointers and operator-&gt;()</H2>
<H2><a name="SWIGPlus_smart_pointers"></a>6.24 Smart pointers and operator-&gt;()</H2>
<p>
@ -4509,8 +4619,179 @@ p = f.__deref__() # Raw pointer from operator-&gt;
<b>Note:</b> Smart pointer support was first added in SWIG-1.3.14.
</p>
<H2><a name="SWIGPlus_ref_unref"></a>6.25 C++ reference counted objects - ref/unref feature</H2>
<H2><a name="SWIGPlus_nn35"></a>6.25 Using declarations and inheritance</H2>
<p>
Another similar idiom in C++ is the use of reference counted objects. Consider for example:
<div class="code">
<pre>
class RCObj {
// implement the ref counting mechanism
int add_ref();
int del_ref();
int ref_count();
public:
virtual ~RCObj() = 0;
int ref() const {
return add_ref();
}
int unref() const {
if (ref_count() == 0 || del_ref() == 0 ) {
delete this;
return 0;
}
return ref_count();
}
};
class A : RCObj {
public:
A();
int foo();
};
class B {
A *_a;
public:
B(A *a) : _a(a) {
a-&gt;ref();
}
~B() {
a-&gt;unref();
}
};
int main() {
A *a = new A(); // (count: 0)
a-&gt;ref(); // 'a' ref here (count: 1)
B *b1 = new B(a); // 'a' ref here (count: 2)
if (1 + 1 == 2) {
B *b2 = new B(a); // 'a' ref here (count: 3)
delete b2; // 'a' unref, but not deleted (count: 2)
}
delete b1; // 'a' unref, but not deleted (count: 1)
a-&gt;unref(); // 'a' unref and deleted (count: 0)
}
</pre>
</div>
<p>
In the example above, the 'A' class instance 'a' is a reference counted
object, which can't be deleted arbitrarily since it is shared between
the objects 'b1' and 'b2'. 'A' is derived from a <i>Reference Counted
Object</i> 'RCObj', which implements the ref/unref idiom.
</p>
<p>
To tell SWIG that 'RCObj' and all its derived classes are reference
counted objects, use the "ref" and "unref" <a href="Customization.html#Customization_features">features</a>.
These are also available as <tt>%refobject</tt> and <tt>%unrefobject</tt>, respectively.
For example:
</p>
<div class="code">
<pre>
%module example
...
%feature("ref") RCObj "$this-&gt;ref();"
%feature("unref") RCObj "$this-&gt;unref();"
%include "rcobj.h"
%include "A.h"
...
</pre>
</div>
<p>
where the code passed to the "ref" and "unref" features will be
executed as needed whenever a new object is passed to python, or when
python tries to release the proxy object instance, respectively.
</p>
<p>
On the python side, the use of a reference counted object is no
different to any other regular instance:
</p>
<div class="targetlang">
<pre>
def create_A():
a = A() # SWIG ref 'a' - new object is passed to python (count: 1)
b1 = B(a) # C++ ref 'a (count: 2)
if 1 + 1 == 2:
b2 = B(a) # C++ ref 'a' (count: 3)
return a # 'b1' and 'b2' are released and deleted, C++ unref 'a' twice (count: 1)
a = create_A() # (count: 1)
exit # 'a' is released, SWIG unref 'a' called in the destructor wrapper (count: 0)
</pre>
</div>
<p>
Note that the user doesn't explicitly need to call 'a-&gt;ref()' nor 'a-&gt;unref()'
(and neither 'delete a'). Instead, SWIG takes cares of executing the "ref"
and "unref" calls as needed. If the user doesn't specify the
"ref/unref" feature for a type, SWIG will produce code equivalent to defining these
features:
</p>
<div class="code">
<pre>
%feature("ref") ""
%feature("unref") "delete $this;"
</pre>
</div>
<p>
In other words, SWIG will not do anything special when a new object
is passed to python, and it will always 'delete' the underlying object when
python releases the proxy instance.
</p>
<p>
The <a href="Customization.html#Customization_ownership">%newobject feature</a> is designed to indicate to
the target language that it should take ownership of the returned object.
When used in conjunction with a type that has the "ref" feature associated with it, it additionally emits the
code in the "ref" feature into the C++ wrapper.
Consider wrapping the following factory function in addition to the above:
</p>
<div class="code">
<pre>
%newobject AFactory;
A *AFactory() {
return new A();
}
</pre>
</div>
<p>
The <tt>AFactory</tt> function now acts much like a call to the <tt>A</tt> constructor with respect to memory handling:
</p>
<div class="targetlang">
<pre>
a = AFactory() # SWIG ref 'a' due to %newobject (count: 1)
exit # 'a' is released, SWIG unref 'a' called in the destructor wrapper (count: 0)
</pre>
</div>
<H2><a name="SWIGPlus_nn35"></a>6.26 Using declarations and inheritance</H2>
<p>
@ -4673,41 +4954,54 @@ public:
</div>
</ul>
<H2><a name="SWIGPlus_nested_classes"></a>6.26 Nested classes</H2>
<H2><a name="SWIGPlus_nested_classes"></a>6.27 Nested classes</H2>
<p>
There is limited support for nested structs and unions when wrapping C code, see <a href="SWIG.html#SWIG_nested_structs">Nested structures</a> for further details.
However, there is no nested class/struct/union support when wrapping C++ code (using the -c++ commandline option).
This may be added at a future date, however, until then some of the following workarounds can be applied.
There is some support for nested structs and unions when wrapping C code,
see <a href="SWIG.html#SWIG_nested_structs">Nested structures</a> for further details.
The added complexity of C++ compared to C means this approach does not work well for
C++ code (when using the -c++ command line option).
For C++, a nested class is treated much like an opaque pointer, so anything useful within the nested class, such as its
methods and variables, are not accessible from the target language.
True nested class support may be added to SWIG in the future, however,
until then some of the following workarounds can be applied to improve the situation.
</p>
<p>
It might be possible to use partial class information. Since
SWIG does not need the entire class specification to work, conditional
compilation can be used to comment out the problematic nested class definition, you might do this:
It might be possible to use partial class information as often you can accept that the nested class is not needed,
especially if it is not actually used in any methods you need from the target language.
Imagine you are wrapping the following <tt>Outer</tt> class which contains a nested class <tt>Inner</tt>.
The easiest thing to do is turn a blind eye to the warning that SWIG generates, or simply suppress it:
</p>
<div class="code">
<pre>
class Foo {
%warnfilter(SWIGWARN_PARSE_NAMED_NESTED_CLASS) Outer::Inner;
class Outer {
public:
#ifndef SWIG
class Bar {
public:
...
};
#endif
Foo();
~Foo();
...
class Inner {
public:
...
};
Inner getInner();
void useInner(const Inner&amp; inner);
...
};
</pre>
</div>
<p>
The next workaround assumes you cannot modify the source code as was done above and it provides a solution for methods that use nested class types.
Imagine we are wrapping the <tt>Outer</tt> class which contains a nested class <tt>Inner</tt>:
Note that if <tt>Inner</tt> can be used as an opaque type, the default wrapping approach suffices.
For example, if the nested class does not need to be created from the target language, but can be obtained via a method
call, such as the <tt>getInner()</tt> method above, the returned value can then be passed around, such as passed into the
<tt>useInner()</tt> method.
</p>
<p>
With some more effort the above situation can be improved somewhat and a nested class can be constructed and used
from the target language much like any other non-nested class. Assuming we have the <tt>Outer</tt> class in a header file:
</p>
<div class="code">
@ -4720,14 +5014,18 @@ public:
int var;
Inner(int v = 0) : var(v) {}
};
void method(Inner inner);
Inner getInner();
void useInner(const Inner&amp; inner);
};
</pre>
</div>
<p>
The following interface file works around SWIG nested class limitations by redefining the nested class as a global class.
A typedef for the compiler is also required in order for the generated wrappers to compile.
The following interface file works around the nested class limitations by redefining the nested class as a global class.
A typedef for the compiler and the <tt>nestedworkaround</tt>
<a href="Customization.html#Customization_feature_flags">feature flag</a> is also required in
order for the generated wrappers to compile. This flag simply removes all the type information from SWIG, so SWIG treats
the nested class as if it had not been parsed at all.
</p>
<div class="code">
@ -4735,9 +5033,6 @@ A typedef for the compiler is also required in order for the generated wrappers
// File : example.i
%module example
// Suppress SWIG warning
#pragma SWIG nowarn=SWIGWARN_PARSE_NESTED_CLASS
// Redefine nested class in global scope in order for SWIG to generate
// a proxy class. Only SWIG parses this definition.
class Inner {
@ -4746,25 +5041,64 @@ class Inner {
Inner(int v = 0) : var(v) {}
};
%nestedworkaround Outer::Inner;
%{
#include "outer.h"
%}
%include "outer.h"
// We've fooled SWIG into thinking that Inner is a global class, so now we need
// to trick the C++ compiler into understanding this apparent global type.
%{
// SWIG thinks that Inner is a global class, so we need to trick the C++
// compiler into understanding this so called global type.
typedef Outer::Inner Inner;
%}
</pre>
</div>
<p>
The downside to this approach is having to maintain two definitions of <tt>Inner</tt>, the real one and the one in the interface file that SWIG parses.
The downside to this approach is a more complex interface file and having to maintain two definitions of <tt>Inner</tt>,
the real one and the one in the interface file that SWIG parses.
However, the upside is that all the methods/variables in the nested class are available from the target language
as a proxy class is generated instead of treating the nested class as an opaque type.
The proxy class can be constructed from the target language and passed into any methods accepting the nested class.
Also note that the original header file is parsed unmodified.
</p>
<H2><a name="SWIGPlus_nn37"></a>6.27 A brief rant about const-correctness</H2>
<p>
Finally, conditional compilation can be used as a workaround to comment out nested class definitions in the actual headers,
assuming you are able to modify them.
</p>
<div class="code">
<pre>
// File outer.h
class Outer {
public:
#ifndef SWIG
class Inner {
public:
...
};
#endif
...
};
</pre>
</div>
<p>
This workaround used to be common when SWIG could not deal with nested classes particulary well.
This should just be a last resort for unusual corner cases now as SWIG can parse nested classes and even handle nested template classes fairly well.
</p>
<p>
<b>Compatibility Note:</b> SWIG-1.3.40 and earlier versions did not have the <tt>nestedworkaround</tt> feature
and the generated code resulting from parsing nested classes did not always compile.
Nested class warnings could also not be suppressed using %warnfilter.
</p>
<H2><a name="SWIGPlus_const"></a>6.28 A brief rant about const-correctness</H2>
<p>
@ -4822,7 +5156,7 @@ using another tool if maintaining constness is the most important part
of your project.
</p>
<H2><a name="SWIGPlus_nn42"></a>6.28 Where to go for more information</H2>
<H2><a name="SWIGPlus_nn42"></a>6.29 Where to go for more information</H2>
<p>

45
Doc/Manual/Sections.html
View file

@ -1,23 +1,15 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>SWIG-1.3 Documentation</title>
<title>SWIG-2.0 Documentation</title>
</head>
<body bgcolor="#ffffff">
<H1><a name="Sections"></a>SWIG-1.3 Development Documentation</H1>
<H1><a name="Sections"></a>SWIG-2.0 Documentation</H1>
Last update : SWIG-1.3.36 (in progress)
Last update : SWIG-2.0.6 (30 April 2012)
<H2>Sections</H2>
<p>
The SWIG documentation is being updated to reflect new SWIG
features and enhancements. However, this update process is not quite
finished--there is a lot of old SWIG-1.1 documentation and it is taking
some time to update all of it. Please pardon our dust (or volunteer
to help!).
</p>
<H3>SWIG Core Documentation</H3>
<ul>
<li><a href="Preface.html#Preface">Preface</a></li>
@ -27,7 +19,7 @@ to help!).
<li><a href="SWIG.html#SWIG">SWIG Basics</a> (Read this!)</li>
<li><a href="SWIGPlus.html#SWIGPlus">SWIG and C++</a></li>
<li><a href="Preprocessor.html#Preprocessor">The SWIG preprocessor</a></li>
<li><a href="Library.html#Library">The SWIG Library</a></li>
<li><a href="Library.html#Library">The SWIG library</a></li>
<li><a href="Arguments.html#Arguments">Argument handling</a></li>
<li><a href="Typemaps.html#Typemaps">Typemaps</a></li>
<li><a href="Customization.html#Customization">Customization features</a></li>
@ -35,28 +27,32 @@ to help!).
<li><a href="Varargs.html#Varargs">Variable length arguments</a></li>
<li><a href="Warnings.html#Warnings">Warning messages</a></li>
<li><a href="Modules.html#Modules">Working with Modules</a></li>
<li><a href="CCache.html#CCache">Using SWIG with ccache</a></li>
</ul>
<H3>Language Module Documentation</H3>
<ul>
<li><a href="Allegrocl.html#Allegrocl_nn1">Allegro CL support</a></li>
<li><a href="Allegrocl.html#Allegrocl">Allegro Common Lisp support</a></li>
<li><a href="Android.html#Android">Android support</a></li>
<li><a href="CSharp.html#CSharp">C# support</a></li>
<li><a href="Chicken.html#Chicken">Chicken support</a></li>
<li><a href="D.html#D">D support</a></li>
<li><a href="Go.html#Go">Go support</a></li>
<li><a href="Guile.html#Guile">Guile support</a></li>
<li><a href="Java.html#Java">Java support</a></li>
<li><a href="Lua.html#Lua_nn1">Lua support</a></li>
<li><a href="Lisp.html#Lisp_nn1">Common Lisp support</a></li>
<li><a href="Lisp.html#Lisp">Common Lisp support</a></li>
<li><a href="Lua.html#Lua">Lua support</a></li>
<li><a href="Modula3.html#Modula3">Modula3 support</a></li>
<li><a href="Mzscheme.html#MzScheme">MzScheme support</a></li>
<li><a href="Mzscheme.html#Mzscheme">MzScheme/Racket support</a></li>
<li><a href="Ocaml.html#Ocaml">Ocaml support</a></li>
<li><a href="Octave.html#Octave">Octave support</a></li>
<li><a href="Perl5.html#Perl5">Perl5 support</a></li>
<li><a href="Php.html#Php">PHP support</a></li>
<li><a href="Pike.html#Pike">Pike support</a></li>
<li><a href="Python.html#Python">Python support</a></li>
<li><a href="Ruby.html#Ruby">Ruby support</a></li>
<li><a href="R.html#R">R support</a></li>
<li><a href="Ruby.html#Ruby">Ruby support</a></li>
<li><a href="Tcl.html#Tcl">Tcl support</a></li>
</ul>
@ -66,20 +62,5 @@ to help!).
<li><a href="Extending.html#Extending">Extending SWIG</a></li>
</ul>
<H3>Documentation that has not yet been updated</H3>
<p>
This documentation has not been completely updated from SWIG-1.1, but most of the topics
still apply to the current release. Make sure you read the
<a href="SWIG.html#SWIG">SWIG Basics</a> chapter before reading
any of these chapters. Also, SWIG-1.3.10 features extensive changes to the
implementation of typemaps. Make sure you read the <a href="Typemaps.html#Typemaps">Typemaps</a>
chapter above if you are using this feature.
</p>
<ul>
<li><a href="Advanced.html#Advanced">Advanced topics</a> (see <a href="Modules.html#Modules">Modules</a> for updated information).</li>
</ul>
</body>
</html>

121
Doc/Manual/Tcl.html
View file

@ -6,7 +6,7 @@
</head>
<body bgcolor="#ffffff">
<H1><a name="Tcl"></a>32 SWIG and Tcl</H1>
<H1><a name="Tcl"></a>37 SWIG and Tcl</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -66,6 +66,7 @@
<ul>
<li><a href="#Tcl_nn45">Proxy classes</a>
</ul>
<li><a href="#Tcl_nn46">Tcl/Tk Stubs</a>
</ul>
</div>
<!-- INDEX -->
@ -82,7 +83,7 @@ Tcl 8.0 or a later release. Earlier releases of SWIG supported Tcl 7.x, but
this is no longer supported.
</p>
<H2><a name="Tcl_nn2"></a>32.1 Preliminaries</H2>
<H2><a name="Tcl_nn2"></a>37.1 Preliminaries</H2>
<p>
@ -108,7 +109,7 @@ build a Tcl extension module. To finish building the module, you
need to compile this file and link it with the rest of your program.
</p>
<H3><a name="Tcl_nn3"></a>32.1.1 Getting the right header files</H3>
<H3><a name="Tcl_nn3"></a>37.1.1 Getting the right header files</H3>
<p>
@ -126,7 +127,7 @@ this is the case, you should probably make a symbolic link so that <tt>tcl.h</tt
header file.
</p>
<H3><a name="Tcl_nn4"></a>32.1.2 Compiling a dynamic module</H3>
<H3><a name="Tcl_nn4"></a>37.1.2 Compiling a dynamic module</H3>
<p>
@ -161,7 +162,7 @@ The name of the module is specified using the <tt>%module</tt> directive or the
<tt> -module</tt> command line option.
</p>
<H3><a name="Tcl_nn5"></a>32.1.3 Static linking</H3>
<H3><a name="Tcl_nn5"></a>37.1.3 Static linking</H3>
<p>
@ -190,7 +191,7 @@ extern int mod(int, int);
extern double My_variable;
%}
%include tclsh.i // Include code for rebuilding tclsh
%include "tclsh.i" // Include code for rebuilding tclsh
</pre></div>
@ -227,7 +228,7 @@ minimal in most situations (and quite frankly not worth the extra
hassle in the opinion of this author).
</p>
<H3><a name="Tcl_nn6"></a>32.1.4 Using your module</H3>
<H3><a name="Tcl_nn6"></a>37.1.4 Using your module</H3>
<p>
@ -355,7 +356,7 @@ to the default system configuration (this requires root access and you will need
the man pages).
</p>
<H3><a name="Tcl_nn7"></a>32.1.5 Compilation of C++ extensions</H3>
<H3><a name="Tcl_nn7"></a>37.1.5 Compilation of C++ extensions</H3>
<p>
@ -438,7 +439,7 @@ erratic program behavior. If working with lots of software components, you
might want to investigate using a more formal standard such as COM.
</p>
<H3><a name="Tcl_nn8"></a>32.1.6 Compiling for 64-bit platforms</H3>
<H3><a name="Tcl_nn8"></a>37.1.6 Compiling for 64-bit platforms</H3>
<p>
@ -465,7 +466,7 @@ also introduce problems on platforms that support more than one
linking standard (e.g., -o32 and -n32 on Irix).
</p>
<H3><a name="Tcl_nn9"></a>32.1.7 Setting a package prefix</H3>
<H3><a name="Tcl_nn9"></a>37.1.7 Setting a package prefix</H3>
<p>
@ -484,7 +485,7 @@ option will append the prefix to the name when creating a command and
call it "<tt>Foo_bar</tt>".
</p>
<H3><a name="Tcl_nn10"></a>32.1.8 Using namespaces</H3>
<H3><a name="Tcl_nn10"></a>37.1.8 Using namespaces</H3>
<p>
@ -506,7 +507,7 @@ When the<tt> -namespace</tt> option is used, objects in the module
are always accessed with the namespace name such as <tt>Foo::bar</tt>.
</p>
<H2><a name="Tcl_nn11"></a>32.2 Building Tcl/Tk Extensions under Windows 95/NT</H2>
<H2><a name="Tcl_nn11"></a>37.2 Building Tcl/Tk Extensions under Windows 95/NT</H2>
<p>
@ -517,7 +518,7 @@ covers the process of using SWIG with Microsoft Visual C++.
although the procedure may be similar with other compilers.
</p>
<H3><a name="Tcl_nn12"></a>32.2.1 Running SWIG from Developer Studio</H3>
<H3><a name="Tcl_nn12"></a>37.2.1 Running SWIG from Developer Studio</H3>
<p>
@ -575,7 +576,7 @@ MSDOS &gt; tclsh80
%
</pre></div>
<H3><a name="Tcl_nn13"></a>32.2.2 Using NMAKE</H3>
<H3><a name="Tcl_nn13"></a>37.2.2 Using NMAKE</H3>
<p>
@ -638,7 +639,7 @@ to get you started. With a little practice, you'll be making lots of
Tcl extensions.
</p>
<H2><a name="Tcl_nn14"></a>32.3 A tour of basic C/C++ wrapping</H2>
<H2><a name="Tcl_nn14"></a>37.3 A tour of basic C/C++ wrapping</H2>
<p>
@ -649,7 +650,7 @@ classes. This section briefly covers the essential aspects of this
wrapping.
</p>
<H3><a name="Tcl_nn15"></a>32.3.1 Modules</H3>
<H3><a name="Tcl_nn15"></a>37.3.1 Modules</H3>
<p>
@ -683,7 +684,7 @@ To fix this, supply an extra argument to <tt>load</tt> like this:
</pre>
</div>
<H3><a name="Tcl_nn16"></a>32.3.2 Functions</H3>
<H3><a name="Tcl_nn16"></a>37.3.2 Functions</H3>
<p>
@ -708,7 +709,7 @@ like you think it does:
%
</pre></div>
<H3><a name="Tcl_nn17"></a>32.3.3 Global variables</H3>
<H3><a name="Tcl_nn17"></a>37.3.3 Global variables</H3>
<p>
@ -788,7 +789,7 @@ extern char *path; // Read-only (due to %immutable)
</pre>
</div>
<H3><a name="Tcl_nn18"></a>32.3.4 Constants and enums</H3>
<H3><a name="Tcl_nn18"></a>37.3.4 Constants and enums</H3>
<p>
@ -872,7 +873,7 @@ When an identifier name is given, it is used to perform an implicit hash-table l
conversion. This allows the <tt>global</tt> statement to be omitted.
</p>
<H3><a name="Tcl_nn19"></a>32.3.5 Pointers</H3>
<H3><a name="Tcl_nn19"></a>37.3.5 Pointers</H3>
<p>
@ -968,7 +969,7 @@ C-style cast may return a bogus result whereas as the C++-style cast will return
<tt>None</tt> if the conversion can't be performed.
</p>
<H3><a name="Tcl_nn20"></a>32.3.6 Structures</H3>
<H3><a name="Tcl_nn20"></a>37.3.6 Structures</H3>
<p>
@ -1250,7 +1251,7 @@ Note: Tcl only destroys the underlying object if it has ownership. See the
memory management section that appears shortly.
</p>
<H3><a name="Tcl_nn21"></a>32.3.7 C++ classes</H3>
<H3><a name="Tcl_nn21"></a>37.3.7 C++ classes</H3>
<p>
@ -1317,7 +1318,7 @@ In Tcl, the static member is accessed as follows:
</pre>
</div>
<H3><a name="Tcl_nn22"></a>32.3.8 C++ inheritance</H3>
<H3><a name="Tcl_nn22"></a>37.3.8 C++ inheritance</H3>
<p>
@ -1366,7 +1367,7 @@ For instance:
It is safe to use multiple inheritance with SWIG.
</p>
<H3><a name="Tcl_nn23"></a>32.3.9 Pointers, references, values, and arrays</H3>
<H3><a name="Tcl_nn23"></a>37.3.9 Pointers, references, values, and arrays</H3>
<p>
@ -1420,7 +1421,7 @@ to hold the result and a pointer is returned (Tcl will release this memory
when the return value is garbage collected).
</p>
<H3><a name="Tcl_nn24"></a>32.3.10 C++ overloaded functions</H3>
<H3><a name="Tcl_nn24"></a>37.3.10 C++ overloaded functions</H3>
<p>
@ -1501,8 +1502,8 @@ If declarations such as these appear, you will get a warning message like this:
<div class="code">
<pre>
example.i:12: Warning(509): Overloaded spam(short) is shadowed by spam(int)
at example.i:11.
example.i:12: Warning 509: Overloaded method spam(short) effectively ignored,
example.i:11: Warning 509: as it is shadowed by spam(int).
</pre>
</div>
@ -1543,7 +1544,7 @@ first declaration takes precedence.
Please refer to the "SWIG and C++" chapter for more information about overloading.
</p>
<H3><a name="Tcl_nn25"></a>32.3.11 C++ operators</H3>
<H3><a name="Tcl_nn25"></a>37.3.11 C++ operators</H3>
<p>
@ -1645,7 +1646,7 @@ There are ways to make this operator appear as part of the class using the <tt>%
Keep reading.
</p>
<H3><a name="Tcl_nn26"></a>32.3.12 C++ namespaces</H3>
<H3><a name="Tcl_nn26"></a>37.3.12 C++ namespaces</H3>
<p>
@ -1709,7 +1710,7 @@ utilizes thousands of small deeply nested namespaces each with
identical symbol names, well, then you get what you deserve.
</p>
<H3><a name="Tcl_nn27"></a>32.3.13 C++ templates</H3>
<H3><a name="Tcl_nn27"></a>37.3.13 C++ templates</H3>
<p>
@ -1761,7 +1762,7 @@ More details can be found in the <a href="SWIGPlus.html#SWIGPlus">SWIG and C++</
examples will appear later.
</p>
<H3><a name="Tcl_nn28"></a>32.3.14 C++ Smart Pointers</H3>
<H3><a name="Tcl_nn28"></a>37.3.14 C++ Smart Pointers</H3>
<p>
@ -1845,7 +1846,7 @@ simply use the <tt>__deref__()</tt> method. For example:
</pre>
</div>
<H2><a name="Tcl_nn29"></a>32.4 Further details on the Tcl class interface</H2>
<H2><a name="Tcl_nn29"></a>37.4 Further details on the Tcl class interface</H2>
<p>
@ -1858,7 +1859,7 @@ of low-level details were omitted. This section provides a brief overview
of how the proxy classes work.
</p>
<H3><a name="Tcl_nn30"></a>32.4.1 Proxy classes</H3>
<H3><a name="Tcl_nn30"></a>37.4.1 Proxy classes</H3>
<p>
@ -1923,7 +1924,7 @@ function. This allows objects to be encapsulated objects that look a lot like
as shown in the last section.
</p>
<H3><a name="Tcl_nn31"></a>32.4.2 Memory management</H3>
<H3><a name="Tcl_nn31"></a>37.4.2 Memory management</H3>
<p>
@ -2111,7 +2112,7 @@ typemaps--an advanced topic discussed later.
</p>
<H2><a name="Tcl_nn32"></a>32.5 Input and output parameters</H2>
<H2><a name="Tcl_nn32"></a>37.5 Input and output parameters</H2>
<p>
@ -2299,7 +2300,7 @@ set c [lindex $dim 1]
</pre>
</div>
<H2><a name="Tcl_nn33"></a>32.6 Exception handling </H2>
<H2><a name="Tcl_nn33"></a>37.6 Exception handling </H2>
<p>
@ -2433,7 +2434,7 @@ Since SWIG's exception handling is user-definable, you are not limited to C++ ex
See the chapter on "<a href="Customization.html#Customization">Customization Features</a>" for more examples.
</p>
<H2><a name="Tcl_nn34"></a>32.7 Typemaps</H2>
<H2><a name="Tcl_nn34"></a>37.7 Typemaps</H2>
<p>
@ -2450,7 +2451,7 @@ Typemaps are only used if you want to change some aspect of the primitive
C-Tcl interface.
</p>
<H3><a name="Tcl_nn35"></a>32.7.1 What is a typemap?</H3>
<H3><a name="Tcl_nn35"></a>37.7.1 What is a typemap?</H3>
<p>
@ -2567,7 +2568,7 @@ parameter is omitted):
</pre>
</div>
<H3><a name="Tcl_nn36"></a>32.7.2 Tcl typemaps</H3>
<H3><a name="Tcl_nn36"></a>37.7.2 Tcl typemaps</H3>
<p>
@ -2705,7 +2706,7 @@ Initialize an argument to a value before any conversions occur.
Examples of these methods will appear shortly.
</p>
<H3><a name="Tcl_nn37"></a>32.7.3 Typemap variables</H3>
<H3><a name="Tcl_nn37"></a>37.7.3 Typemap variables</H3>
<p>
@ -2776,7 +2777,7 @@ properly assigned.
The Tcl name of the wrapper function being created.
</div>
<H3><a name="Tcl_nn38"></a>32.7.4 Converting a Tcl list to a char ** </H3>
<H3><a name="Tcl_nn38"></a>37.7.4 Converting a Tcl list to a char ** </H3>
<p>
@ -2822,7 +2823,7 @@ int print_args(char **argv) {
return i;
}
%}
%include tclsh.i
%include "tclsh.i"
</pre></div>
@ -2838,7 +2839,7 @@ argv[2] = Larry
3
</pre></div>
<H3><a name="Tcl_nn39"></a>32.7.5 Returning values in arguments</H3>
<H3><a name="Tcl_nn39"></a>37.7.5 Returning values in arguments</H3>
<p>
@ -2880,7 +2881,7 @@ result, a Tcl function using these typemaps will work like this :
%
</pre></div>
<H3><a name="Tcl_nn40"></a>32.7.6 Useful functions</H3>
<H3><a name="Tcl_nn40"></a>37.7.6 Useful functions</H3>
<p>
@ -2957,7 +2958,7 @@ int Tcl_IsShared(Tcl_Obj *obj);
</pre>
</div>
<H3><a name="Tcl_nn41"></a>32.7.7 Standard typemaps</H3>
<H3><a name="Tcl_nn41"></a>37.7.7 Standard typemaps</H3>
<p>
@ -3041,7 +3042,7 @@ work)
</pre>
</div>
<H3><a name="Tcl_nn42"></a>32.7.8 Pointer handling</H3>
<H3><a name="Tcl_nn42"></a>37.7.8 Pointer handling</H3>
<p>
@ -3117,7 +3118,7 @@ For example:
</pre>
</div>
<H2><a name="Tcl_nn43"></a>32.8 Turning a SWIG module into a Tcl Package.</H2>
<H2><a name="Tcl_nn43"></a>37.8 Turning a SWIG module into a Tcl Package.</H2>
<p>
@ -3189,7 +3190,7 @@ As a final note, most SWIG examples do not yet use the
to use the <tt>load</tt> command instead.
</p>
<H2><a name="Tcl_nn44"></a>32.9 Building new kinds of Tcl interfaces (in Tcl)</H2>
<H2><a name="Tcl_nn44"></a>37.9 Building new kinds of Tcl interfaces (in Tcl)</H2>
<p>
@ -3288,7 +3289,7 @@ danger of blowing something up (although it is easily accomplished
with an out of bounds array access).
</p>
<H3><a name="Tcl_nn45"></a>32.9.1 Proxy classes</H3>
<H3><a name="Tcl_nn45"></a>37.9.1 Proxy classes</H3>
<p>
@ -3409,5 +3410,27 @@ short, but clever Tcl script can be combined with SWIG to do many
interesting things.
</p>
<H2><a name="Tcl_nn46"></a>37.10 Tcl/Tk Stubs</H2>
<p>
For background information about the Tcl Stubs feature, see
<a href="http://www.tcl.tk/doc/howto/stubs.html">http://www.tcl.tk/doc/howto/stubs.html</a>.
</p>
<p>
As of SWIG 1.3.10, the generated C/C++ wrapper will use the Tcl Stubs
feature if compiled with <tt>-DUSE_TCL_STUBS</tt>.
</p>
<p>
As of SWIG 1.3.40, the generated C/C++ wrapper will use the Tk Stubs
feature if compiled with <tt>-DUSE_TK_STUBS</tt>. Also, you can override
the minimum version to support which is passed to <tt>Tcl_InitStubs()</tt>
and <tt>Tk_InitStubs()</tt> with <tt>-DSWIG_TCL_STUBS_VERSION="8.3"</tt>
or the version being compiled with using
<tt>-DSWIG_TCL_STUBS_VERSION=TCL_VERSION</tt>.
</p>
</body>
</html>

1322
Doc/Manual/Typemaps.html
View file

File diff suppressed because it is too large Load diff

130
Doc/Manual/Varargs.html
View file

@ -270,21 +270,37 @@ traceprintf(arg1, NULL);
<p>
Arguably, this approach seems to defeat the whole point of variable length arguments. However,
this actually provides enough support for many simple kinds of varargs functions to still be useful. For
instance, you could make function calls like this (in Python):
this actually provides enough support for many simple kinds of varargs functions to still be useful, however it does come with a caveat.
For instance, you could make function calls like this (in Python):
</p>
<div class="targetlang">
<pre>
&gt;&gt;&gt; traceprintf("Hello World")
&gt;&gt;&gt; traceprintf("Hello %s. Your number is %d\n" % (name, num))
&gt;&gt;&gt; traceprintf("Your result is 90%%.")
</pre>
</div>
<p>
Notice how string formatting is being done in Python instead of C.
The caveat is the strings passed must be safe to use in C though.
For example if name was to contain a "%" it should be double escaped in order to avoid unpredictable
behaviour:
</p>
<div class="targetlang">
<pre>
&gt;&gt;&gt; traceprintf("Your result is 90%.\n") # unpredictable behaviour
&gt;&gt;&gt; traceprintf("Your result is 90%%.\n") # good
</pre>
</div>
<p>
Read on for further solutions.
</p>
<H2><a name="Varargs_nn5"></a>13.4 Argument replacement using %varargs</H2>
@ -315,33 +331,82 @@ int open(const char *path, int oflags, int mode = 0);
<p>
In this case, <tt>%varargs</tt> is simply providing more specific information about the
extra arguments that might be passed to a function.
If the parameters to a varargs function are of uniform type, <tt>%varargs</tt> can also
If the arguments to a varargs function are of uniform type, <tt>%varargs</tt> can also
accept a numerical argument count as follows:
</p>
<div class="code">
<pre>
%varargs(10,char *arg = NULL) execlp;
%varargs(3, char *str = NULL) execlp;
...
int execlp(const char *path, const char *arg1, ...);
int execlp(const char *path, const char *arg, ...);
</pre>
</div>
<p>
This would wrap <tt>execlp()</tt> as a function that accepted up to 10 optional arguments.
and is effectively seen as:
</p>
<div class="code">
<pre>
int execlp(const char *path, const char *arg,
char *str1 = NULL,
char *str2 = NULL,
char *str3 = NULL);
</pre>
</div>
<p>
This would wrap <tt>execlp()</tt> as a function that accepted up to 3 optional arguments.
Depending on the application, this may be more than enough for practical purposes.
</p>
<p>
Argument replacement is most appropriate in cases where the types of
the extra arguments is uniform and the maximum number of arguments is
known. When replicated argument replacement is used, at least one extra
argument is added to the end of the arguments when making the function call.
This argument serves as a sentinel to make sure the list is properly terminated.
It has the same value as that supplied to the <tt>%varargs</tt> directive.
The handling of <a href="SWIGPlus.html#SWIGPlus_default_args">default arguments</a> can be changed via the
<tt>compactdefaultargs</tt> feature. If this feature is used, for example
</p>
<div class="code">
<pre>
%feature("compactdefaultargs") execlp;
%varargs(3, char *str = NULL) execlp;
...
int execlp(const char *path, const char *arg, ...);
</pre>
</div>
<p>
a call from the target language which does not provide the maximum number of arguments, such as,
<tt>execlp("a", "b", "c")</tt>
will generate C code which includes the missing default values, that is, <tt>execlp("a", "b", "c", NULL, NULL)</tt>.
If <tt>compactdefaultargs</tt> is not used, then the generated code will be
<tt>execlp("a", "b", "c")</tt>. The former is useful for helping providing a sentinel to terminate the argument list.
However, this is not guaranteed, for example when a user passes a non-NULL value for all the parameters.
When using <tt>compactdefaultargs</tt> it is possible to guarantee the NULL sentinel is passed through the,
<tt>numinputs=0</tt> <a href="Typemaps.html#Typemaps_nn26">'in' typemap attribute</a>, naming the <b>last parameter</b>.
For example,
</p>
<div class="code">
<pre>
%feature("compactdefaultargs") execlp;
%varargs(3, char *str = NULL) execlp;
%typemap(in, numinputs=0) char *str3 ""
...
int execlp(const char *path, const char *arg, ...);
</pre>
</div>
<p>
Note that <tt>str3</tt> is the name of the last argument, as we have used <tt>%vargars</tt> with 3.
Now <tt>execlp("a", "b", "c", "d", "e")</tt> will result in an error as one too many arguments has been passed,
as now only 2 additional 'str' arguments can be passed with the 3rd one always using the specified default <tt>NULL</tt>.
</p>
<p>
Argument replacement is most appropriate in cases where the types of
the extra arguments are uniform and the maximum number of arguments are
known.
Argument replacement is not as useful when working with functions that accept
mixed argument types such as <tt>printf()</tt>. Providing general purpose
wrappers to such functions presents special problems (covered shortly).
@ -445,23 +510,36 @@ like this:
<div class="code">
<pre>
%typemap(in) (...)(char *args[10]) {
int i;
int argc;
for (i = 0; i &lt; 10; i++) args[i] = 0;
argc = PyTuple_Size(varargs);
if (argc &gt; 10) {
PyErr_SetString(PyExc_ValueError,"Too many arguments");
int i;
int argc;
for (i = 0; i &lt; 10; i++) args[i] = 0;
argc = PyTuple_Size(varargs);
if (argc &gt; 10) {
PyErr_SetString(PyExc_ValueError, "Too many arguments");
return NULL;
}
for (i = 0; i &lt; argc; i++) {
PyObject *pyobj = PyTuple_GetItem(varargs, i);
char *str = 0;
%#if PY_VERSION_HEX&gt;=0x03000000
PyObject *pystr;
if (!PyUnicode_Check(pyobj)) {
PyErr_SetString(PyExc_ValueError, "Expected a string");
return NULL;
}
for (i = 0; i &lt; argc; i++) {
PyObject *o = PyTuple_GetItem(varargs,i);
if (!PyString_Check(o)) {
PyErr_SetString(PyExc_ValueError,"Expected a string");
return NULL;
}
args[i] = PyString_AsString(o);
pystr = PyUnicode_AsUTF8String(pyobj);
str = PyBytes_AsString(pystr);
Py_XDECREF(pystr);
%#else
if (!PyString_Check(pyobj)) {
PyErr_SetString(PyExc_ValueError, "Expected a string");
return NULL;
}
$1 = (void *) args;
str = PyString_AsString(pyobj);
%#endif
args[i] = str;
}
$1 = (void *) args;
}
</pre>
</div>

63
Doc/Manual/Warnings.html
View file

@ -25,7 +25,7 @@
<li><a href="#Warnings_nn12">C/C++ Parser (300-399)</a>
<li><a href="#Warnings_nn13">Types and typemaps (400-499) </a>
<li><a href="#Warnings_nn14">Code generation (500-599)</a>
<li><a href="#Warnings_nn15">Language module specific (800-899) </a>
<li><a href="#Warnings_nn15">Language module specific (700-899) </a>
<li><a href="#Warnings_nn16">User defined (900-999)</a>
</ul>
<li><a href="#Warnings_nn17">History</a>
@ -44,8 +44,8 @@ During compilation, SWIG may generate a variety of warning messages. For exampl
<div class="shell">
<pre>
example.i:16: Warning(501): Overloaded declaration ignored. bar(double)
example.i:15: Warning(501): Previous declaration is bar(int)
example.i:16: Warning 501: Overloaded declaration ignored. bar(double)
example.i:15: Warning 501: Previous declaration is bar(int)
</pre>
</div>
@ -102,7 +102,7 @@ int foo(double); // Silently ignored.
<p>
The <tt>%warnfilter</tt> directive has the same semantics as other declaration modifiers like
<tt>%rename</tt>, <tt>%ignore</tt> and <tt>%feature</tt>, see the
<a href="Customization.html#features">%feature directive</a> section. For example, if you wanted to
<a href="Customization.html#Customization_features">%feature directive</a> section. For example, if you wanted to
suppress a warning for a method in a class hierarchy, you could do this:
</p>
@ -257,16 +257,23 @@ Warning messages can be associated with typemaps using the
<div class="code">
<pre>
%typemap(in, warning="901:You are really going to regret this") blah * {
%typemap(in, warning="901:You are really going to regret this usage of $1_type $1_name") blah * {
...
}
</pre>
</div>
<p>
In this case, the warning message will be printed whenever the typemap is actually used.
In this case, the warning message will be printed whenever the typemap is actually used and the <a href="Typemaps.html#Typemaps_special_variables">special variables</a> will be expanded as appropriate, for example:
</p>
<div class="shell">
<pre>
example.i:23: Warning 901: You are really going to regret this usage of blah * self
example.i:24: Warning 901: You are really going to regret this usage of blah * stuff
</pre>
</div>
<H2><a name="Warnings_symbolic_symbols"></a>14.5 Symbolic symbols</H2>
@ -344,7 +351,7 @@ These can be overridden using command line options, for example:
$ swig -python -Fstandard example.i
example.i:4: Syntax error in input.
$ swig -python -Fmicrosoft example.i
example.i(4): Syntax error in input.
example.i(4) : Syntax error in input.
</pre></div>
<H2><a name="Warnings_nn9"></a>14.9 Warning number reference</H2>
@ -373,7 +380,7 @@ example.i(4): Syntax error in input.
<li>117. Deprecated <tt>%new</tt> directive.
<li>118. Deprecated <tt>%typemap(except)</tt>.
<li>119. Deprecated <tt>%typemap(ignore)</tt>.
<li>120. Deprecated command line option (-c).
<li>120. Deprecated command line option (-runtime, -noruntime).
<li>121. Deprecated <tt>%name</tt> directive.
</ul>
@ -381,8 +388,12 @@ example.i(4): Syntax error in input.
<ul>
<li>201. Unable to find 'filename'.
<li>202. Could not evaluate 'expr'.
<li>201. Unable to find <em>filename</em>.
<li>202. Could not evaluate expression <em>expr</em>.
<li>203. Both includeall and importall are defined: using includeall.
<li>204. CPP #warning, "<em>warning</em>".
<li>205. CPP #error, "<em>error</em>".
<li>206. Unexpected tokens after #<em>directive</em> directive.
</ul>
<H3><a name="Warnings_nn12"></a>14.9.3 C/C++ Parser (300-399)</H3>
@ -399,18 +410,20 @@ example.i(4): Syntax error in input.
<li>308. Namespace alias '<em>name</em>' not allowed here. Assuming '<em>name</em>'
<li>309. [private | protected] inheritance ignored.
<li>310. Template '<em>name</em>' was already wrapped as '<em>name</em>' (ignored)
<li>311. Template partial specialization not supported.
<li>312. Nested classes not currently supported (ignored).
<li>312. Unnamed nested class not currently supported (ignored).
<li>313. Unrecognized extern type "<em>name</em>" (ignored).
<li>314. '<em>identifier</em>' is a <em>lang</em> keyword.
<li>315. Nothing known about '<em>identifier</em>'.
<li>316. Repeated %module directive.
<li>317. Specialization of non-template '<em>name</em>'.
<li>318. Instantiation of template <em>name</em> is ambiguous. Using <em>templ</em> at <em>file</em>:<em>line</em>
<li>318. Instantiation of template '<em>name</em>' is ambiguous, instantiation <em>templ</em> used, instantiation <em>templ</em> ignored.
<li>319. No access specifier given for base class <em>name</em> (ignored).
<li>320. Explicit template instantiation ignored.
<li>321. <em>identifier</em> conflicts with a built-in name.
<li>322. Redundant redeclaration of '<em>name</em>'.
<li>323. Recursive scope inheritance of '<em>name</em>'.
<li>324. Named nested template instantiations not supported. Processing as if no name was given to %template().
<li>325. Nested class not currently supported (<em>name</em> ignored).
<li>350. operator new ignored.
<li>351. operator delete ignored.
<li>352. operator+ ignored.
@ -482,8 +495,8 @@ example.i(4): Syntax error in input.
<li>469. No or improper directorin typemap defined for <em>type</em>
<li>470. Thread/reentrant unsafe wrapping, consider returning by value instead.
<li>471. Unable to use return type <em>type</em> in director method
<li>474. Method <em>method</em> usage of the optimal attribute in the out typemap at <em>file</em>:<em>line</em> ignored as the following cannot be used to generate optimal code: <em>code</em>
<li>475. Multiple calls to <em>method</em> might be generated due to optimal attribute usage in the out typemap at <em>file</em>:<em>line</em>.
<li>474. Method <em>method</em> usage of the optimal attribute ignored in the out typemap as the following cannot be used to generate optimal code: <em>code</em>
<li>475. Multiple calls to <em>method</em> might be generated due to optimal attribute usage in the out typemap.
</ul>
@ -492,28 +505,30 @@ example.i(4): Syntax error in input.
<ul>
<li>501. Overloaded declaration ignored. <em>decl</em>
<li>502. Overloaded constructor ignored. <em>decl</em>
<li>501. Overloaded declaration ignored. <em>decl</em>. Previous declaration is <em>decl</em>.
<li>502. Overloaded constructor ignored. <em>decl</em>. Previous declaration is <em>decl</em>.
<li>503. Can't wrap '<em>identifier</em>' unless renamed to a valid identifier.
<li>504. Function <em>name</em> must have a return type.
<li>504. Function <em>name</em> must have a return type. Ignored.
<li>505. Variable length arguments discarded.
<li>506. Can't wrap varargs with keyword arguments enabled.
<li>507. Adding native function <em>name</em> not supported (ignored).
<li>508. Declaration of '<em>name</em>' shadows declaration accessible via operator-&gt;() at <em>file:line</em>.
<li>509. Overloaded <em>declaration</em> is shadowed by <em>declaration</em> at <em>file</em>:<em>line</em>.
<li>508. Declaration of '<em>name</em>' shadows declaration accessible via operator-&gt;(), previous declaration of'<em>declaration</em>'.
<li>509. Overloaded method <em>declaration</em> effectively ignored, as it is shadowed by <em>declaration</em>.
<li>510. Friend function '<em>name</em>' ignored.
<li>511. Can't use keyword arguments with overloaded functions.
<li>512. Overloaded <em>declaration</em> const ignored. Non-const method at <em>file</em>:<em>line</em> used.
<li>512. Overloaded method <em>declaration</em> ignored, using non-const method <em>declaration</em> instead.
<li>513. Can't generate wrappers for unnamed struct/class.
<li>514.
<li>515.
<li>516. Overloaded method <em>declaration</em> ignored. Method <em>declaration</em> at <em>file</em>:<em>line</em> used.
<li>516. Overloaded method <em>declaration</em> ignored, using <em>declaration</em> instead.
<li>517.
<li>518. Portability warning: File <em>file1</em> will be overwritten by <em>file2</em> on case insensitive filesystems such as Windows' FAT32 and NTFS unless the class/module name is renamed.
<li>519. %template() contains no name. Template method ignored: <em>declaration</em>
<li>520. <em>Base/Derived</em> class '<em>classname1</em>' of '<em>classname2</em>' is not similarly marked as a smart pointer.
<li>521. Illegal destructor name <em>name</em>. Ignored.
</ul>
<H3><a name="Warnings_nn15"></a>14.9.6 Language module specific (800-899) </H3>
<H3><a name="Warnings_nn15"></a>14.9.6 Language module specific (700-899) </H3>
<ul>
@ -558,7 +573,7 @@ example.i(4): Syntax error in input.
</ul>
<ul>
<li>870. Warning for <em>classname</em>: Base <em>baseclass</em> ignored. Multiple inheritance is not supported in Php4. (Php).
<li>870. Warning for <em>classname</em>: Base <em>baseclass</em> ignored. Multiple inheritance is not supported in PHP.
<li>871. Unrecognized pragma <em>pragma</em>. (Php).
</ul>

22
Doc/Manual/Windows.html
View file

@ -67,7 +67,7 @@ SWIG does not come with the usual Windows type installation program, however it
<p>
The swigwin distribution contains the SWIG Windows executable, swig.exe, which will run on 32 bit versions of Windows, ie Windows 95/98/ME/NT/2000/XP.
The swigwin distribution contains the SWIG Windows executable, swig.exe, which will run on 32 bit versions of Windows, ie Windows 95 and later.
If you want to build your own swig.exe have a look at <a href="#Windows_swig_exe">Building swig.exe on Windows</a>.
</p>
@ -78,7 +78,7 @@ If you want to build your own swig.exe have a look at <a href="#Windows_swig_exe
<p>
Using Microsoft Visual C++ is the most common approach to compiling and linking SWIG's output.
The Examples directory has a few Visual C++ project files (.dsp files).
These were produced by Visual C++ 6, although they should also work in Visual C++ 5.
These were produced by Visual C++ 6.
Later versions of Visual Studio should also be able to open and convert these project files.
The C# examples come with .NET 2003 solution (.sln) and project files instead of Visual C++ 6 project files.
The project files have been set up to execute SWIG in a custom build rule for the SWIG interface (.i) file.
@ -248,7 +248,7 @@ Execute the steps in the order shown and don't use spaces in path names. In fact
<ol>
<li>
Download the following packages from the <a href="http://www.mingw.org/download.shtml">MinGW download page</a>
or <a href="http://sourceforge.net/project/showfiles.php?group_id=2435">MinGW SourceForge download page</a>.
or <a href="http://sourceforge.net/projects/mingw/files/">MinGW SourceForge download page</a>.
Note that at the time of writing, the majority of these are in the Current
release list and some are in the Snapshot or Previous release list.
<ul>
@ -272,7 +272,7 @@ Execute the steps in the order shown and don't use spaces in path names. In fact
<ul>
<li>Answer y to the "do you wish to continue with the post install?"</li>
<li>Answer y to the "do you have MinGW installed?"</li>
<li>Type in the the folder in which you installed MinGW (C:/MinGW is default)</li>
<li>Type in the folder in which you installed MinGW (C:/MinGW is default)</li>
</ul>
</li>
@ -281,7 +281,7 @@ Execute the steps in the order shown and don't use spaces in path names. In fact
</li>
<li>
Copy the followig to the MSYS install folder (C:\msys\1.0 is default):
Copy the following to the MSYS install folder (C:\msys\1.0 is default):
<ul>
<li>msys-automake-1.8.2.tar.bz2</li>
<li>msys-autoconf-2.59.tar.bz2</li>
@ -313,6 +313,18 @@ If you want to check out SWIG to a different folder to the proposed
the autotools will fail miserably on those.
</li>
<li>
The PCRE third party library needs to be built next.
Download the latest PCRE source tarball, such as <tt>pcre-8.10.tar.bz2</tt>, from
<a href=http://www.pcre.org>PCRE</a> and place in the <tt>/usr/src/swig</tt> directory.
Build PCRE as a static library using the Tools/pcre-build.sh script as follows:
<div class="shell"><pre>
cd /usr/src/swig
Tools/pcre-build.sh
</pre></div>
</li>
<li>
You are now ready to build SWIG. Execute the following commands to build swig.exe:
<div class="shell"><pre>

BIN
Doc/Manual/android-class.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 14 KiB

BIN
Doc/Manual/android-simple.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 7.7 KiB

BIN
Doc/Manual/ch11.1.png
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 2.4 KiB

BIN
Doc/Manual/ch11.2.png
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 2.6 KiB

BIN
Doc/Manual/ch11.3.png
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 2.9 KiB

BIN
Doc/Manual/ch12.1.png
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 3.5 KiB

BIN
Doc/Manual/ch9.table.2.png
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 3.7 KiB

7
Doc/Manual/chapters
View file

@ -13,10 +13,14 @@ Contract.html
Varargs.html
Warnings.html
Modules.html
CCache.html
Allegrocl.html
Android.html
C.html
CSharp.html
Chicken.html
D.html
Go.html
Guile.html
Java.html
Lisp.html
@ -29,8 +33,7 @@ Perl5.html
Php.html
Pike.html
Python.html
R.html
Ruby.html
Tcl.html
R.html
Extending.html

4
Doc/Manual/index.html
View file

@ -1,10 +1,10 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>SWIG-1.3 Documentation</title>
<title>SWIG-2.0 Documentation</title>
</head>
<body bgcolor="#ffffff">
<H1><a name="index"></a>SWIG-1.3 Development Documentation</h1>
<H1><a name="index"></a>SWIG-2.0 Documentation</h1>
The SWIG documentation is available in one of the following formats.
<ul>

5
Doc/Manual/linkchecker.config Normal file
View file

@ -0,0 +1,5 @@
[checking]
anchors=1
[filtering]
ignorewarnings=http-robots-denied

2
Doc/Manual/makechap.py
View file

@ -1,4 +1,4 @@
#!/usr/local/bin/python
#!/usr/bin/env python
###############################################################################
# Takes a chapter as input and adds internal links and numbering to all

4
Doc/Manual/maketoc.py
View file

@ -1,4 +1,4 @@
#!/usr/local/bin/python
#!/usr/bin/env python
import sys
import os
@ -12,7 +12,7 @@ print >>f, """
<TITLE>SWIG Users Manual</TITLE>
</HEAD>
<BODY BGCOLOR="#ffffff">
<H1>SWIG Users Manual</H1>
<H1><a name="Contents"></a>SWIG Users Manual</H1>
<p>
"""

0
Doc/Manual/swig16.png Executable file → Normal file
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 5.4 KiB

After

Width:  |  Height:  |  Size: 5.4 KiB

Before After
Before After

3
Doc/README
View file

@ -2,4 +2,5 @@ Doc/Manual - Latest version of the SWIG user manual
Doc/Devel - Developer documentation concerning SWIG internals.
(not necessarily up to date)
Open the index.html file in each of these directories with a web browser.