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

- Updated documentation to use CSS and <div> instead of blockquotes

Browse source 
git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk/SWIG@7003 626c5289-ae23-0410-ae9c-e8d60b6d4f22
This commit is contained in:
John Lenz 2005-02-26 02:56:29 +00:00
commit 13ad5fff85
35 changed files with 8013 additions and 4099 deletions
Download patch file Download diff file Expand all files Collapse all files

139
Doc/Manual/Arguments.html
View file

@ -2,11 +2,13 @@
<html>
<head>
<title>Argument Handling</title>
<link rel="stylesheet" type="text/css" href="style.css"/>
</head>
<body bgcolor="#ffffff">
<H1><a name="Arguments"></a>9 Argument Handling</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="#Arguments_nn2">The typemaps.i library</a>
<ul>
@ -23,6 +25,7 @@
<li><a href="#Arguments_nn11">Applying constraints to new datatypes</a>
</ul>
</ul>
</div>
<!-- INDEX -->
@ -44,19 +47,23 @@ describes some of the techniques for doing this.
<H2><a name="Arguments_nn2"></a>9.1 The typemaps.i library</H2>
<p>
This section describes the <tt>typemaps.i</tt> library file--commonly used to
change certain properties of argument conversion.
</p>
<H3><a name="Arguments_nn3"></a>9.1.1 Introduction</H3>
<p>
Suppose you had a C function like this:
</p>
<blockquote><pre>
<div class="code"><pre>
void add(double a, double b, double *result) {
*result = a + b;
}
</pre></blockquote>
</pre></div>
<p>
From reading the source code, it is clear that the function is storing
@ -70,14 +77,14 @@ One way to deal with this is to use the
<tt>typemaps.i</tt> library file and write interface code like this:
</p>
<blockquote><pre>
<div class="code"><pre>
// Simple example using typemaps
%module example
%include "typemaps.i"
%apply double *OUTPUT { double *result };
extern void add(double a, double b, double *result);
</pre></blockquote>
</pre></div>
<p>
The <tt>%apply</tt> directive tells SWIG that you are going to apply
@ -91,25 +98,27 @@ When the resulting module is created, you can now use the function
like this (shown for Python):
</p>
<blockquote><pre>
<div class="code"><pre>
&gt;&gt;&gt; a = add(3,4)
&gt;&gt;&gt; print a
7
&gt;&gt;&gt;
</pre></blockquote>
</pre></div>
<p>
In this case, you can see how the output value normally returned in
the third argument has magically been transformed into a function
return value. Clearly this makes the function much easier to use
since it is no longer necessary to manufacture a special <tt>double
*</tt> object and pass it to the function somehow.
</p>
<p>
Once a typemap has been applied to a type, it stays in effect for all future occurrences
of the type and name. For example, you could write the following:
</p>
<blockquote><pre>
<div class="code"><pre>
%module example
%include "typemaps.i"
@ -119,16 +128,18 @@ extern void sub(double a, double b, double *result);
extern void mul(double a, double b, double *result);
extern void div(double a, double b, double *result);
...
</pre></blockquote>
</pre></div>
<p>
In this case, the <tt>double *OUTPUT</tt> rule is applied to all of the functions that follow.
</p>
<p>
Typemap transformations can even be extended to multiple return values.
For example, consider this code:
</p>
<blockquote>
<div class="code">
<pre>
%include "typemaps.i"
%apply int *OUTPUT { int *width, int *height };
@ -136,11 +147,13 @@ For example, consider this code:
// Returns a pair (width,height)
void getwinsize(int winid, int *width, int *height);
</pre>
</blockquote>
</div>
<p>
In this case, the function returns multiple values, allowing it to be used like this:
</p>
<blockquote><pre>
<div class="code"><pre>
&gt;&gt;&gt; w,h = genwinsize(wid)
&gt;&gt;&gt; print w
400
@ -148,7 +161,7 @@ In this case, the function returns multiple values, allowing it to be used like
300
&gt;&gt;&gt;
</pre>
</blockquote>
</div>
<p>
It should also be noted that although the <tt>%apply</tt> directive is
@ -156,22 +169,24 @@ used to associate typemap rules to datatypes, you can also use the
rule names directly in arguments. For example, you could write this:
</p>
<blockquote><pre>
<div class="code"><pre>
// Simple example using typemaps
%module example
%include "typemaps.i"
extern void add(double a, double b, double *OUTPUT);
</pre></blockquote>
</pre></div>
<p>
Typemaps stay in effect until they are explicitly deleted or redefined to something
else. To clear a typemap, the <tt>%clear</tt> directive should be used. For example:
</p>
<blockquote>
<div class="code">
<pre>
%clear double *result; // Remove all typemaps for double *result
</pre>
</blockquote>
</div>
<H3><a name="Arguments_nn4"></a>9.1.2 Input parameters</H3>
@ -181,7 +196,7 @@ The following typemaps instruct SWIG that a pointer really only holds a single
input value:
</p>
<blockquote><pre>
<div class="code"><pre>
int *INPUT
short *INPUT
long *INPUT
@ -190,34 +205,38 @@ unsigned short *INPUT
unsigned long *INPUT
double *INPUT
float *INPUT
</pre></blockquote>
</pre></div>
<p>
When used, it allows values to be passed instead of pointers. For example, consider this
function:
</p>
<blockquote><pre>
<div class="code"><pre>
double add(double *a, double *b) {
return *a+*b;
}
</pre></blockquote>
</pre></div>
<p>
Now, consider this SWIG interface:
</p>
<blockquote><pre>
<div class="code"><pre>
%module example
%include "typemaps.i"
...
extern double add(double *INPUT, double *INPUT);
</pre></blockquote>
</pre></div>
<p>
When the function is used in the scripting language interpreter, it will work like this:
</p>
<blockquote><pre>
<div class="code"><pre>
result = add(3,4)
</pre></blockquote>
</pre></div>
<H3><a name="Arguments_nn5"></a>9.1.3 Output parameters</H3>
@ -228,7 +247,7 @@ function. When used, you do not need to supply the argument when
calling the function. Instead, one or more output values are returned.
</p>
<blockquote><pre>
<div class="code"><pre>
int *OUTPUT
short *OUTPUT
long *OUTPUT
@ -238,47 +257,51 @@ unsigned long *OUTPUT
double *OUTPUT
float *OUTPUT
</pre></blockquote>
</pre></div>
<p>
These methods can be used as shown in an earlier example. For example, if you have this C function :</p>
<blockquote><pre>
<div class="code"><pre>
void add(double a, double b, double *c) {
*c = a+b;
}
</pre></blockquote>
</pre></div>
<p>
A SWIG interface file might look like this :</p>
<blockquote><pre>
<div class="code"><pre>
%module example
%include "typemaps.i"
...
extern void add(double a, double b, double *OUTPUT);
</pre></blockquote>
</pre></div>
<p>
In this case, only a single output value is returned, but this is not
a restriction. An arbitrary number of output values can be returned by applying
the output rules to more than one argument (as shown previously).
</p>
<p>
If the function also returns a value, it is returned along with the argument. For example,
if you had this:
</p>
<blockquote><pre>
<div class="code"><pre>
extern int foo(double a, double b, double *OUTPUT);
</pre></blockquote>
</pre></div>
<p>
The function will return two values like this:
</p>
<blockquote>
<div class="code">
<pre>
iresult, dresult = foo(3.5, 2)
</pre>
</blockquote>
</div>
<H3><a name="Arguments_nn6"></a>9.1.4 Input/Output parameters</H3>
@ -287,7 +310,7 @@ iresult, dresult = foo(3.5, 2)
When a pointer serves as both an input and output value you can use
the following typemaps :</p>
<blockquote><pre>
<div class="code"><pre>
int *INOUT
short *INOUT
long *INOUT
@ -297,43 +320,45 @@ unsigned long *INOUT
double *INOUT
float *INOUT
</pre></blockquote>
</pre></div>
<p>
A C function that uses this might be something like this:</p>
<blockquote><pre>
<div class="code"><pre>
void negate(double *x) {
*x = -(*x);
}
</pre></blockquote>
</pre></div>
<p>
To make x function as both and input and output value, declare the
function like this in an interface file :</p>
<blockquote><pre>
<div class="code"><pre>
%module example
%include typemaps.i
...
extern void negate(double *INOUT);
</pre></blockquote>
</pre></div>
<p>
Now within a script, you can simply call the function normally :</p>
<blockquote><pre>
<div class="code"><pre>
a = negate(3); # a = -3 after calling this
</pre></blockquote>
</pre></div>
<p>
One subtle point of the <tt>INOUT</tt> rule is that many scripting languages
enforce mutability constraints on primitive objects (meaning that simple objects
like integers and strings aren't supposed to change). Because of this, you can't
just modify the object's value in place as the underlying C function does in this example.
Therefore, the <tt>INOUT</tt> rule returns the modified value as a new object
rather than directly overwriting the value of the original input object.
</p>
<p>
<b>Compatibility note :</b> The <tt>INOUT</tt> rule used to be known as <tt>BOTH</tt> in earlier versions of
@ -348,7 +373,7 @@ As previously shown, the <tt>%apply</tt> directive can be used to apply the <tt>
<tt>INOUT</tt> typemaps to different argument names. For example:
</p>
<blockquote><pre>
<div class="code"><pre>
// Make double *result an output value
%apply double *OUTPUT { double *result };
@ -358,25 +383,31 @@ As previously shown, the <tt>%apply</tt> directive can be used to apply the <tt>
// Make long *x inout
%apply long *INOUT {long *x};
</pre></blockquote>
</pre></div>
<p>
To clear a rule, the <tt>%clear</tt> directive is used:
</p>
<blockquote><pre>
<div class="code"><pre>
%clear double *result;
%clear Int32 *in, long *x;
</pre></blockquote>
</pre></div>
<p>
Typemap declarations are lexically scoped so a typemap takes effect from the point of definition to the end of the
file or a matching <tt>%clear</tt> declaration.
</p>
<H2><a name="Arguments_nn8"></a>9.2 Applying constraints to input values</H2>
<p>
In addition to changing the handling of various input values, it is
also possible to use typemaps to apply constraints. For example, maybe you want to
insure that a value is positive, or that a pointer is non-NULL. This
can be accomplished including the <tt>constraints.i</tt> library file.
</p>
<H3><a name="Arguments_nn9"></a>9.2.1 Simple constraint example</H3>
@ -385,7 +416,7 @@ can be accomplished including the <tt>constraints.i</tt> library file.
The constraints library is best illustrated by the following interface
file :</p>
<blockquote><pre>
<div class="code"><pre>
// Interface file with constraints
%module example
%include "constraints.i"
@ -396,7 +427,7 @@ double sqrt(double NONNEGATIVE); // Non-negative values only
double inv(double NONZERO); // Non-zero values
void free(void *NONNULL); // Non-NULL pointers only
</pre></blockquote>
</pre></div>
<p>
The behavior of this file is exactly as you would expect. If any of
@ -410,7 +441,7 @@ values, prevent mysterious program crashes and so on.</p>
<p>
The following constraints are currently available</p>
<blockquote><pre>
<div class="code"><pre>
POSITIVE Any number &gt; 0 (not zero)
NEGATIVE Any number &lt; 0 (not zero)
NONNEGATIVE Any number &gt;= 0
@ -418,7 +449,7 @@ NONPOSITIVE Any number &lt;= 0
NONZERO Nonzero number
NONNULL Non-NULL pointer (pointers only).
</pre></blockquote>
</pre></div>
<H3><a name="Arguments_nn11"></a>9.2.3 Applying constraints to new datatypes</H3>
@ -428,24 +459,24 @@ The constraints library only supports the primitive C datatypes, but it
is easy to apply it to new datatypes using <tt>%apply</tt>. For
example :</p>
<blockquote><pre>
<div class="code"><pre>
// Apply a constraint to a Real variable
%apply Number POSITIVE { Real in };
// Apply a constraint to a pointer type
%apply Pointer NONNULL { Vector * };
</pre></blockquote>
</pre></div>
<p>
The special types of "Number" and "Pointer" can be applied to any
numeric and pointer variable type respectively. To later remove a
constraint, the <tt>%clear</tt> directive can be used :</p>
<blockquote><pre>
<div class="code"><pre>
%clear Real in;
%clear Vector *;
</pre></blockquote>
</pre></div>
</body>
</html>

37
Doc/Manual/CSharp.html
View file

@ -2,19 +2,24 @@
<html>
<head>
<title>SWIG and C#</title>
<link rel="stylesheet" type="text/css" href="style.css"/>
</head>
<body bgcolor="#FFFFFF">
<H1><a name="CSharp"></a>16 SWIG and C#</H1>
<!-- INDEX -->
<div class="sectiontoc">
</div>
<!-- INDEX -->
<p>
The purpose of the C# module is to offer an automated way of accessing existing C/C++ code from .NET languages.
The wrapper code implementation uses the Platform Invoke (PINVOKE) interface to access natively compiled C/C++ code.
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.
Swig C# works equally well on non-Microsoft operating systems such as Linux, Solaris and Apple Mac using Mono and Portable.NET.
</p>
<p>
The C# module is very similar to the Java module, so until some documentation has been written,
@ -75,9 +80,9 @@ Likewise there is no need for an equivalent to <tt>%javaexception</tt>.
</li>
<li>
Typemap equivalent names:
<p>Typemap equivalent names:</p>
<blockquote><pre>
<div class="code"><pre>
jni -&gt; ctype
jtype -&gt; imtype
jstype -&gt; cstype
@ -92,48 +97,48 @@ javabody -&gt; csbody
javafinalize -&gt; csfinalize
javadestruct -&gt; csdestruct
javadestruct_derived -&gt; csdestruct_derived
</pre></blockquote>
</pre></div>
</li>
<li>
Additional typemaps:
<p>Additional typemaps:</p>
<blockquote><pre>
<div class="code"><pre>
csvarin C# code property set typemap
csvarout C# code property get typemap
</pre></blockquote>
</pre></div>
</li>
<li>
Feature equivalent names:
<blockquote><pre>
<p>Feature equivalent names:</p>
<div class="code"><pre>
%javaconst -&gt; %csconst
%javaconstvalue -&gt; %csconstvalue
%javamethodmodifiers -&gt; %csmethodmodifiers
</pre></blockquote>
</pre></div>
</li>
<li>
Pragma equivalent names:
<blockquote><pre>
<p>Pragma equivalent names:</p>
<div class="code"><pre>
%pragma(java) -&gt; %pragma(csharp)
jniclassbase -&gt; imclassbase
jniclassclassmodifiers -&gt; imclassclassmodifiers
jniclasscode -&gt; imclasscode
jniclassimports -&gt; imclassimports
jniclassinterfaces -&gt; imclassinterfaces
</pre></blockquote>
</pre></div>
</li>
<li>
Special variable equivalent names:
<blockquote><pre>
<p>Special variable equivalent names:</p>
<div class="code"><pre>
$javaclassname -&gt; $csclassname
$javainput -&gt; $csinput
$jnicall -&gt; $imcall
</pre></blockquote>
</pre></div>
</li>
</ul>
@ -145,7 +150,9 @@ The special variable will get translated into the value specified by the <tt>-dl
if specified, otherwise it is equivalent to the <b>$module</b> special variable.
</p>
<p>
The intermediary classname has <tt>PINVOKE</tt> appended after the module name instead of <tt>JNI</tt>, for example <tt>modulenamePINVOKE</tt>.
</p>
<p>
The directory <tt>Examples/csharp</tt> has a number of simple examples.

34
Doc/Manual/Chicken.html
View file

@ -3,12 +3,14 @@
<html>
<head>
<title>SWIG and Chicken</title>
<link rel="stylesheet" type="text/css" href="style.css"/>
</head>
<body bgcolor="#ffffff">
<H1><a name="Chicken"></a>17 SWIG and Chicken</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="#Chicken_nn2">Preliminaries</a>
<ul>
@ -33,6 +35,7 @@
<li><a href="#Chicken_nn16">Pointers</a>
<li><a href="#Chicken_nn17">Unsupported features and known problems</a>
</ul>
</div>
<!-- INDEX -->
@ -90,9 +93,9 @@
the -chicken option.
</p>
<blockquote>
<div class="code">
<pre>% swig -chicken example.i</pre>
</blockquote>
</div>
<p>
To allow the wrapper to take advantage of future CHICKEN code
@ -102,9 +105,9 @@
be compiled to C using your system's CHICKEN compiler.
</p>
<blockquote>
<div class="code">
<pre>% chicken example.scm -output-file oexample.c</pre>
</blockquote>
</div>
<p>
So for the C mode of SWIG CHICKEN, <tt>example_wrap.c</tt> and
@ -120,9 +123,9 @@
the -chicken -c++ option.
</p>
<blockquote>
<div class="code">
<pre>% swig -chicken -c++ example.i</pre>
</blockquote>
</div>
<p>
This will generate <tt>example_wrap.cxx</tt> and
@ -130,9 +133,9 @@
compiled to C using your system's CHICKEN compiler.
</p>
<blockquote>
<div class="code">
<pre>% chicken example.scm -output-file oexample.c</pre>
</blockquote>
</div>
<p>
So for the C++ mode of SWIG CHICKEN, <tt>example_wrap.cxx</tt>
@ -163,6 +166,7 @@
<H3><a name="Chicken_nn7"></a>17.2.2 Modules</H3>
<p>
The name of the module must be declared one of two ways:
<ul>
<li>Placing <tt>%module example</tt> in the SWIG interface
@ -170,6 +174,8 @@
<li>Using <tt>-module example</tt> on the SWIG command
line.</li>
</ul>
<p>
The generated example.scm file then exports <code>(declare (unit modulename))</code>.
If you do not want SWIG to export the <code>(declare (unit modulename))</code>, pass
the -nounit option to SWIG.
@ -230,13 +236,13 @@
<p>
The author of TinyCLOS, Gregor Kiczales, describes TinyCLOS as:
</p>
<blockquote>
<div class="code">
Tiny CLOS is a Scheme implementation of a `kernelized' CLOS, with a
metaobject protocol. The implementation is even simpler than
the simple CLOS found in `The Art of the Metaobject Protocol,'
weighing in at around 850 lines of code, including (some)
comments and documentation.
</blockquote>
</div>
<p>
Almost all good Scheme books describe how to use metaobjects and
@ -306,13 +312,13 @@
in example.i and the C functions being wrapped are in example_impl.c.
</p>
<blockquote>
<div class="code">
<pre>
$ swig -chicken example.i
$ csc -svk example.scm example_impl.c example_wrap.c
$ csi example.so test_script.scm
</pre>
</blockquote>
</div>
<p>
You must be careful not to name the example_impl.c file example.c because
@ -330,13 +336,13 @@
<p>Again, we can easily use csc to build a binary.</p>
<blockquote>
<div class="code">
<pre>
$ swig -chicken example.i
$ csc -vk example.scm example_impl.c example_wrap.c test_script.scm -o example
$ ./example
</pre>
</blockquote>
</div>
<H2><a name="Chicken_nn15"></a>17.6 Typemaps</H2>

71
Doc/Manual/Contents.html
View file

@ -12,6 +12,7 @@
<h3><a href="Preface.html#Preface">1 Preface</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="Preface.html#Preface_nn2">Introduction</a>
<li><a href="Preface.html#Preface_nn3">Special Introduction for Version 1.3</a>
@ -24,11 +25,13 @@
<li><a href="Preface.html#Preface_nn10">Credits</a>
<li><a href="Preface.html#Preface_nn11">Bug reports</a>
</ul>
</div>
<!-- INDEX -->
<h3><a href="Introduction.html#Introduction">2 Introduction</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="Introduction.html#Introduction_nn2">What is SWIG?</a>
<li><a href="Introduction.html#Introduction_nn3">Why use SWIG?</a>
@ -46,11 +49,13 @@
<li><a href="Introduction.html#Introduction_nn12">Hands off code generation</a>
<li><a href="Introduction.html#Introduction_nn13">SWIG and freedom</a>
</ul>
</div>
<!-- INDEX -->
<h3><a href="Windows.html#Windows">3 Getting started on Windows </a></h3>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="Windows.html#Windows_nn2">Installation on Windows</a>
<ul>
@ -80,11 +85,13 @@
<li><a href="Windows.html#examples_cygwin">Running the examples on Windows using Cygwin</a>
</ul>
</ul>
</div>
<!-- INDEX -->
<h3><a href="Scripting.html#Scripting">4 Scripting Languages</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="Scripting.html#Scripting_nn2">The two language view of the world</a>
<li><a href="Scripting.html#Scripting_nn3">How does a scripting language talk to C?</a>
@ -102,11 +109,13 @@
<li><a href="Scripting.html#Scripting_nn12">Static linking</a>
</ul>
</ul>
</div>
<!-- INDEX -->
<h3><a href="SWIG.html#SWIG">5 SWIG Basics</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="SWIG.html#SWIG_nn2">Running SWIG</a>
<ul>
@ -172,11 +181,13 @@
<li><a href="SWIG.html#SWIG_nn50">What to do with main()</a>
</ul>
</ul>
</div>
<!-- INDEX -->
<h3><a href="SWIGPlus.html#SWIGPlus">6 SWIG and C++</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="SWIGPlus.html#SWIGPlus_nn2">Comments on C++ Wrapping</a>
<li><a href="SWIGPlus.html#SWIGPlus_nn3">Approach</a>
@ -226,11 +237,13 @@
</ul>
<li><a href="SWIGPlus.html#SWIGPlus_nn42">Where to go for more information</a>
</ul>
</div>
<!-- INDEX -->
<h3><a href="Preprocessor.html#Preprocessor">7 Preprocessing</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="Preprocessor.html#Preprocessor_nn2">File inclusion</a>
<li><a href="Preprocessor.html#Preprocessor_nn3">File imports</a>
@ -242,11 +255,13 @@
<li><a href="Preprocessor.html#Preprocessor_nn9">Preprocessing and { ... }</a>
<li><a href="Preprocessor.html#Preprocessor_nn10">Viewing preprocessor output</a>
</ul>
</div>
<!-- INDEX -->
<h3><a href="Library.html#Library">8 SWIG library</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="Library.html#Library_nn2">The %include directive and library search path</a>
<li><a href="Library.html#Library_nn3">C Arrays and Pointers</a>
@ -273,11 +288,13 @@
<li><a href="Library.html#Library_nn17">exception.i</a>
</ul>
</ul>
</div>
<!-- INDEX -->
<h3><a href="Arguments.html#Arguments">9 Argument Handling</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="Arguments.html#Arguments_nn2">The typemaps.i library</a>
<ul>
@ -294,11 +311,13 @@
<li><a href="Arguments.html#Arguments_nn11">Applying constraints to new datatypes</a>
</ul>
</ul>
</div>
<!-- INDEX -->
<h3><a href="Typemaps.html#Typemaps">10 Typemaps</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="Typemaps.html#Typemaps_nn2">Introduction</a>
<ul>
@ -355,17 +374,23 @@
</ul>
<li><a href="Typemaps.html#Typemaps_nn42">Multi-argument typemaps</a>
<li><a href="Typemaps.html#runtime_type_checker">The run-time type checker</a>
<ul>
<li><a href="Typemaps.html#Typemaps_nn45">Implementation</a>
<li><a href="Typemaps.html#Typemaps_nn46">Usage</a>
</ul>
<li><a href="Typemaps.html#Typemaps_overloading">Typemaps and overloading</a>
<li><a href="Typemaps.html#Typemaps_nn45">More about <tt>%apply</tt> and <tt>%clear</tt></a>
<li><a href="Typemaps.html#Typemaps_nn46">Reducing wrapper code size</a>
<li><a href="Typemaps.html#Typemaps_nn47">Passing data between typemaps</a>
<li><a href="Typemaps.html#Typemaps_nn48">Where to go for more information?</a>
</ul>
</div>
<!-- INDEX -->
<h3><a href="Customization.html#Customization">11 Customization Features</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="Customization.html#exception">Exception handling with %exception</a>
<ul>
@ -382,22 +407,26 @@
<li><a href="Customization.html#features_example">Feature example</a>
</ul>
</ul>
</div>
<!-- INDEX -->
<h3><a href="Contract.html#Contract">12 Contracts</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="Contract.html#Contract_nn2">The %contract directive</a>
<li><a href="Contract.html#Contract_nn3">%contract and classes</a>
<li><a href="Contract.html#Contract_nn4">Constant aggregation and %aggregate_check</a>
<li><a href="Contract.html#Contract_nn5">Notes</a>
</ul>
</div>
<!-- INDEX -->
<h3><a href="Varargs.html#Varargs">13 Variable Length Arguments</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="Varargs.html#Varargs_nn2">Introduction</a>
<li><a href="Varargs.html#Varargs_nn3">The Problem</a>
@ -409,11 +438,13 @@
<li><a href="Varargs.html#Varargs_nn9">C++ Issues</a>
<li><a href="Varargs.html#Varargs_nn10">Discussion</a>
</ul>
</div>
<!-- INDEX -->
<h3><a href="Warnings.html#Warnings">14 Warning Messages</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="Warnings.html#Warnings_nn2">Introduction</a>
<li><a href="Warnings.html#Warnings_nn3">Warning message suppression</a>
@ -434,27 +465,34 @@
</ul>
<li><a href="Warnings.html#Warnings_nn17">History</a>
</ul>
</div>
<!-- INDEX -->
<h3><a href="Modules.html#Modules">15 Working with Modules</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="Modules.html#Modules_nn2">The SWIG runtime code</a>
<li><a href="Modules.html#Modules_nn3">A word of caution about static libraries</a>
<li><a href="Modules.html#Modules_nn4">References</a>
<li><a href="Modules.html#Modules_nn5">Reducing the wrapper file size</a>
<li><a href="Modules.html#external_run_time">External access to the runtime</a>
<li><a href="Modules.html#Modules_nn4">A word of caution about static libraries</a>
<li><a href="Modules.html#Modules_nn5">References</a>
<li><a href="Modules.html#Modules_nn6">Reducing the wrapper file size</a>
</ul>
</div>
<!-- INDEX -->
<h3><a href="CSharp.html#CSharp">16 SWIG and C#</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
</div>
<!-- INDEX -->
<h3><a href="Chicken.html#Chicken">17 SWIG and Chicken</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="Chicken.html#Chicken_nn2">Preliminaries</a>
<ul>
@ -479,11 +517,13 @@
<li><a href="Chicken.html#Chicken_nn16">Pointers</a>
<li><a href="Chicken.html#Chicken_nn17">Unsupported features and known problems</a>
</ul>
</div>
<!-- INDEX -->
<h3><a href="Guile.html#Guile">18 SWIG and Guile</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="Guile.html#Guile_nn2">Meaning of "Module"</a>
<li><a href="Guile.html#Guile_nn3">Using the SCM or GH Guile API</a>
@ -512,11 +552,13 @@
<li><a href="Guile.html#Guile_nn21">Linking</a>
</ul>
</ul>
</div>
<!-- INDEX -->
<h3><a href="Java.html#Java">19 SWIG and Java</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="Java.html#java_overview">Overview</a>
<li><a href="Java.html#java_preliminaries">Preliminaries</a>
@ -641,11 +683,13 @@
</ul>
<li><a href="Java.html#java_examples">Examples</a>
</ul>
</div>
<!-- INDEX -->
<h3><a href="Modula3.html#Modula3">20 SWIG and Modula-3</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="Modula3.html#modula3_overview">Overview</a>
<ul>
@ -680,19 +724,23 @@
</ul>
<li><a href="Modula3.html#remarks">Remarks</a>
</ul>
</div>
<!-- INDEX -->
<h3><a href="Mzscheme.html#Mzscheme">21 SWIG and MzScheme</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="Mzscheme.html#MzScheme_nn2">Creating native MzScheme structures</a>
</ul>
</div>
<!-- INDEX -->
<h3><a href="Ocaml.html#Ocaml">22 SWIG and Ocaml</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="Ocaml.html#Ocaml_nn2">Preliminaries</a>
<ul>
@ -737,11 +785,13 @@
<li><a href="Ocaml.html#Ocaml_nn31">Exceptions</a>
</ul>
</ul>
</div>
<!-- INDEX -->
<h3><a href="Perl5.html#Perl5">23 SWIG and Perl5</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="Perl5.html#Perl5_nn2">Overview</a>
<li><a href="Perl5.html#Perl5_nn3">Preliminaries</a>
@ -801,11 +851,13 @@
<li><a href="Perl5.html#Perl5_nn46">Modifying the proxy methods</a>
</ul>
</ul>
</div>
<!-- INDEX -->
<h3><a href="Php.html#Php">24 SWIG and PHP4</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="Php.html#Php_nn2">Preliminaries</a>
<li><a href="Php.html#Php_nn3">Building PHP4 Extensions</a>
@ -825,11 +877,13 @@
<li><a href="Php.html#Php_nn16">To be furthered...</a>
</ul>
</ul>
</div>
<!-- INDEX -->
<h3><a href="Pike.html#Pike">25 SWIG and Pike</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="Pike.html#Pike_nn2">Preliminaries</a>
<ul>
@ -847,11 +901,13 @@
<li><a href="Pike.html#Pike_nn12">Static Members</a>
</ul>
</ul>
</div>
<!-- INDEX -->
<h3><a href="Python.html#Python">26 SWIG and Python</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="Python.html#Python_nn2">Overview</a>
<li><a href="Python.html#Python_nn3">Preliminaries</a>
@ -889,7 +945,7 @@
<li><a href="Python.html#Python_nn30">Memory management</a>
<li><a href="Python.html#Python_nn31">Python 2.2 and classic classes</a>
</ul>
<li><a href="Python.html#directors">Cross language polymorphism (experimental)</a>
<li><a href="Python.html#directors">Cross language polymorphism</a>
<ul>
<li><a href="Python.html#Python_nn33">Enabling directors</a>
<li><a href="Python.html#Python_nn34">Director classes</a>
@ -945,11 +1001,13 @@
</ul>
<li><a href="Python.html#Python_nn72">Python Packages</a>
</ul>
</div>
<!-- INDEX -->
<h3><a href="Ruby.html#Ruby">27 SWIG and Ruby</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="Ruby.html#Ruby_nn2">Preliminaries</a>
<ul>
@ -1020,11 +1078,13 @@
<li><a href="Ruby.html#Ruby_nn51">Interacting with Ruby's Garbage Collector</a>
</ul>
</ul>
</div>
<!-- INDEX -->
<h3><a href="Tcl.html#Tcl">28 SWIG and Tcl</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="Tcl.html#Tcl_nn2">Preliminaries</a>
<ul>
@ -1083,11 +1143,13 @@
<li><a href="Tcl.html#Tcl_nn45">Proxy classes</a>
</ul>
</ul>
</div>
<!-- INDEX -->
<h3><a href="Extending.html#Extending">29 Extending SWIG</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="Extending.html#Extending_nn2">Introduction</a>
<li><a href="Extending.html#Extending_nn3">Prerequisites</a>
@ -1145,6 +1207,7 @@
</ul>
<li><a href="Extending.html#Extending_nn46">Guide to parse tree nodes</a>
</ul>
</div>
<!-- INDEX -->

72
Doc/Manual/Contract.html
View file

@ -2,27 +2,32 @@
<html>
<head>
<title>Contract Checking</title>
<link rel="stylesheet" type="text/css" href="style.css"/>
</head>
<body bgcolor="#ffffff">
<H1><a name="Contract"></a>12 Contracts</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="#Contract_nn2">The %contract directive</a>
<li><a href="#Contract_nn3">%contract and classes</a>
<li><a href="#Contract_nn4">Constant aggregation and %aggregate_check</a>
<li><a href="#Contract_nn5">Notes</a>
</ul>
</div>
<!-- INDEX -->
<p>
A common problem that arises when wrapping C libraries is that of maintaining
reliability and checking for errors. The fact of the matter is that many
C programs are notorious for not providing error checks. Not only that,
when you expose the internals of an application as a library, it
often becomes possible to crash it simply by providing bad inputs or
using it in a way that wasn't intended.
</p>
<p>
This chapter describes SWIG's support for software contracts. In the context
@ -36,10 +41,12 @@ generated rather than having the program continue to execute.
<H2><a name="Contract_nn2"></a>12.1 The %contract directive</H2>
<p>
Contracts are added to a declaration using the %contract directive. Here
is a simple example:
</p>
<blockquote>
<div class="code">
<pre>
%contract sqrt(double x) {
require:
@ -51,8 +58,9 @@ ensure:
...
double sqrt(double);
</pre>
</blockquote>
</div>
<p>
In this case, a contract is being added to the <tt>sqrt()</tt> function.
The <tt>%contract</tt> directive must always appear before the declaration
in question. Within the contract there are two sections, both of which
@ -62,6 +70,7 @@ Typically, this is used to check argument values. The <tt>ensure:</tt> section
specifies conditions that must hold after the function is called. This is
often used to check return values or the state of the program. In both
cases, the conditions that must hold must be specified as boolean expressions.
</p>
<p>
In the above example, we're simply making sure that sqrt() returns a non-negative
@ -73,7 +82,7 @@ Once a contract has been specified, it modifies the behavior of the
resulting module. For example:
</p>
<blockquote>
<div class="code">
<pre>
&gt;&gt;&gt; example.sqrt(2)
1.4142135623730951
@ -83,14 +92,16 @@ Traceback (most recent call last):
RuntimeError: Contract violation: require: (arg1&gt;=0)
&gt;&gt;&gt;
</pre>
</blockquote>
</div>
<H2><a name="Contract_nn3"></a>12.2 %contract and classes</H2>
<p>
The <tt>%contract</tt> directive can also be applied to class methods and constructors. For example:
</p>
<blockquote>
<div class="code">
<pre>
%contract Foo::bar(int x, int y) {
require:
@ -110,23 +121,27 @@ public:
int bar(int, int);
};
</pre>
</blockquote>
</div>
<p>
The way in which <tt>%contract</tt> is applied is exactly the same as the <tt>%feature</tt> directive.
Thus, any contract that you specified for a base class will also be attached to inherited methods. For example:
</p>
<blockquote>
<div class="code">
<pre>
class Spam : public Foo {
public:
int bar(int,int); // Gets contract defined for Foo::bar(int,int)
};
</pre>
</blockquote>
</div>
<p>
In addition to this, separate contracts can be applied to both the base class and a derived class. For example:
</p>
<blockquote>
<div class="code">
<pre>
%contract Foo::bar(int x, int) {
require:
@ -148,20 +163,24 @@ public:
int bar(int,int); // Gets Foo::bar and Spam::bar contract
};
</pre>
</blockquote>
</div>
<p>
When more than one contract is applied, the conditions specified in a
"require:" section are combined together using a logical-AND operation.
In other words conditions specified for the base class and conditions
specified for the derived class all must hold. In the above example,
this means that both the arguments to <tt>Spam::bar</tt> must be positive.
</p>
<H2><a name="Contract_nn4"></a>12.3 Constant aggregation and %aggregate_check</H2>
<p>
Consider an interface file that contains the following code:
</p>
<blockquote>
<div class="code">
<pre>
#define UP 1
#define DOWN 2
@ -170,30 +189,36 @@ Consider an interface file that contains the following code:
void move(SomeObject *, int direction, int distance);
</pre>
</blockquote>
</div>
<p>
One thing you might want to do is impose a constraint on the direction parameter to
make sure it's one of a few accepted values. To do that, SWIG provides an easy to
use macro %aggregate_check() that works like this:
</p>
<blockquote>
<div class="code">
<pre>
%aggregate_check(int, check_direction, UP, DOWN, LEFT, RIGHT);
</pre>
</blockquote>
</div>
<p>
This merely defines a utility function of the form
</p>
<blockquote>
<div class="code">
<pre>
int check_direction(int x);
</pre>
</blockquote>
</div>
<p>
That checks the argument x to see if it is one of the values listed. This utility
function can be used in contracts. For example:
</p>
<blockquote>
<div class="code">
<pre>
%aggregate_check(int, check_direction, UP, DOWN, RIGHT, LEFT);
@ -209,10 +234,13 @@ require:
void move(SomeObject *, int direction, int distance);
</pre>
</blockquote>
</div>
<p>
Alternatively, it can be used in typemaps and other directives. For example:
<blockquote>
</p>
<div class="code">
<pre>
%aggregate_check(int, check_direction, UP, DOWN, RIGHT, LEFT);
@ -227,16 +255,20 @@ Alternatively, it can be used in typemaps and other directives. For example:
void move(SomeObject *, int direction, int distance);
</pre>
</blockquote>
</div>
<p>
Regrettably, there is no automatic way to perform similar checks with enums values. Maybe in a future
release.
</p>
<H2><a name="Contract_nn5"></a>12.4 Notes</H2>
<p>
Contract support was implemented by Songyan (Tiger) Feng and first appeared
in SWIG-1.3.20.
</p>
</body>
</html>

191
Doc/Manual/Customization.html
View file

@ -2,11 +2,13 @@
<html>
<head>
<title>Customization Features</title>
<link rel="stylesheet" type="text/css" href="style.css"/>
</head>
<body bgcolor="#ffffff">
<H1><a name="Customization"></a>11 Customization Features</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="#exception">Exception handling with %exception</a>
<ul>
@ -23,10 +25,12 @@
<li><a href="#features_example">Feature example</a>
</ul>
</ul>
</div>
<!-- INDEX -->
<p>
In many cases, it is desirable to change the default wrapping of
particular declarations in an interface. For example, you might want
to provide hooks for catching C++ exceptions, add assertions, or
@ -34,6 +38,7 @@ provide hints to the underlying code generator. This chapter
describes some of these customization techniques. First, a discussion
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>
@ -43,7 +48,7 @@ The <tt>%exception</tt> directive allows you to define a general purpose excepti
handler. For example, you can specify the following:
</p>
<blockquote><pre>
<div class="code"><pre>
%exception {
try {
$action
@ -53,7 +58,7 @@ handler. For example, you can specify the following:
return NULL;
}
}
</pre></blockquote>
</pre></div>
<p>
When defined, the code enclosed in braces is inserted directly into the low-level wrapper
@ -63,9 +68,9 @@ remains in effect until it is explicitly deleted. This is done by using either
or <tt>%noexception</tt> with no code. For example:
</p>
<blockquote><pre>
<div class="code"><pre>
%exception; // Deletes any previously defined handler
</pre></blockquote>
</pre></div>
<p>
<b>Compatibility note:</b> Previous versions of SWIG used a special directive <tt>%except</tt>
@ -81,7 +86,7 @@ C has no formal exception handling mechanism so there are several approaches tha
used. A somewhat common technique is to simply set a special error code. For example:
</p>
<blockquote><pre>
<div class="code"><pre>
/* File : except.c */
static char error_message[256];
@ -100,14 +105,14 @@ char *check_exception() {
else return NULL;
}
</pre></blockquote>
</pre></div>
<p>
To use these functions, functions simply call
<tt>throw_exception()</tt> to indicate an error occurred. For example
:</p>
<blockquote><pre>
<div class="code"><pre>
double inv(double x) {
if (x != 0) return 1.0/x;
else {
@ -116,13 +121,13 @@ double inv(double x) {
}
}
</pre></blockquote>
</pre></div>
<p>
To catch the exception, you can write a simple exception handler such
as the following (shown for Perl5) :</p>
<blockquote><pre>
<div class="code"><pre>
%exception {
char *err;
clear_exception();
@ -131,7 +136,7 @@ as the following (shown for Perl5) :</p>
croak(err);
}
}
</pre></blockquote>
</pre></div>
<p>
In this case, when an error occurs, it is translated into a Perl error.
@ -140,11 +145,13 @@ In this case, when an error occurs, it is translated into a Perl error.
<H3><a name="Customization_nn4"></a>11.1.2 Exception handling with longjmp()</H3>
<p>
Exception handling can also be added to C code using the
<tt>&lt;setjmp.h&gt;</tt> library. Here is a minimalistic implementation that
relies on the C preprocessor :
</p>
<blockquote><pre>
<div class="code"><pre>
/* File : except.c
Just the declaration of a few global variables we're going to use */
@ -168,23 +175,23 @@ extern int exception_status;
#define DivisionByZero 2
#define OutOfMemory 3
</pre></blockquote>
</pre></div>
<p>
Now, within a C program, you can do the following :</p>
<blockquote><pre>
<div class="code"><pre>
double inv(double x) {
if (x) return 1.0/x;
else throw(DivisionByZero);
}
</pre></blockquote>
</pre></div>
<p>
Finally, to create a SWIG exception handler, write the following :</p>
<blockquote><pre>
<div class="code"><pre>
%{
#include "except.h"
%}
@ -202,10 +209,12 @@ Finally, to create a SWIG exception handler, write the following :</p>
croak("Unknown exception");
}
}
</pre></blockquote>
</pre></div>
<p>
Note: This implementation is only intended to illustrate the general idea. To make it work better, you'll need to
modify it to handle nested <tt>try</tt> declarations.
</p>
<H3><a name="Customization_nn5"></a>11.1.3 Handling C++ exceptions</H3>
@ -214,7 +223,7 @@ modify it to handle nested <tt>try</tt> declarations.
Handling C++ exceptions is also straightforward. For example:
</p>
<blockquote><pre>
<div class="code"><pre>
%exception {
try {
$action
@ -229,27 +238,29 @@ Handling C++ exceptions is also straightforward. For example:
}
}
</pre></blockquote>
</pre></div>
<p>
The exception types need to be declared as classes elsewhere, possibly
in a header file :</p>
<blockquote><pre>
<div class="code"><pre>
class RangeError {};
class DivisionByZero {};
class OutOfMemory {};
</pre>
</blockquote>
</div>
<H3><a name="Customization_nn6"></a>11.1.4 Defining different exception handlers</H3>
<p>
By default, the <tt>%exception</tt> directive creates an exception
handler that is used for all wrapper functions that follow it. Unless
there is a well-defined (and simple) error handling mechanism in place,
defining one universal exception handler may be unwieldy and result
in excessive code bloat since the handler is inlined into each wrapper function.
</p>
<p>
To fix this, you can be more selective about how you use the
@ -257,7 +268,7 @@ To fix this, you can be more selective about how you use the
critical pieces of code. For example:
</p>
<blockquote><pre>
<div class="code"><pre>
%exception {
... your exception handler ...
}
@ -266,12 +277,14 @@ critical pieces of code. For example:
%exception;
/* Define non-critical operations that don't throw exceptions */
</pre></blockquote>
</pre></div>
<p>
More precise control over exception handling can be obtained by attaching an exception handler
to specific declaration name. For example:
</p>
<blockquote>
<div class="code">
<pre>
%exception allocate {
try {
@ -282,8 +295,9 @@ to specific declaration name. For example:
}
}
</pre>
</blockquote>
</div>
<p>
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
@ -291,8 +305,9 @@ rules as for <tt>%rename</tt> described in the section on
<a href="SWIGPlus.html#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>
<blockquote>
<div class="code">
<pre>
%exception Object::allocate {
try {
@ -303,16 +318,18 @@ an exception handler for a specific class, you might write this:
}
}
</pre>
</blockquote>
</div>
<p>
When a class prefix is supplied, the exception handler is applied to the corresponding declaration
in the specified class as well as for identically named functions appearing in derived classes.
</p>
<p>
<tt>%exception</tt> can even be used to pinpoint a precise declaration when overloading is used. For example:
</p>
<blockquote>
<div class="code">
<pre>
%exception Object::allocate(int) {
try {
@ -323,12 +340,14 @@ in the specified class as well as for identically named functions appearing in d
}
}
</pre>
</blockquote>
</div>
<p>
Attaching exceptions to specific declarations is a good way to reduce code bloat. It can also be a useful way
to attach exceptions to specific parts of a header file. For example:
</p>
<blockquote>
<div class="code">
<pre>
%module example
%{
@ -357,8 +376,9 @@ to attach exceptions to specific parts of a header file. For example:
// Read a raw header file
%include "someheader.h"
</pre>
</blockquote>
</div>
<p>
<b>Compatibility note:</b> The <tt>%exception</tt> directive replaces
the functionality provided by the deprecated "except" typemap.
The typemap would allow exceptions to be thrown in the target
@ -366,6 +386,7 @@ language based on the return type of a function and
was intended to be a mechanism for pinpointing specific
declarations. However, it never really worked that well and the new
%exception directive is much better.
</p>
<H3><a name="Customization_nn7"></a>11.1.5 Using The SWIG exception library</H3>
@ -377,7 +398,7 @@ put an "<tt>%include exception.i</tt>" in your interface file. This
creates a function<tt> SWIG_exception()</tt> that can be used to raise
common scripting language exceptions in a portable manner. For example :</p>
<blockquote><pre>
<div class="code"><pre>
// Language independent exception handler
%include exception.i
@ -395,14 +416,14 @@ common scripting language exceptions in a portable manner. For example :</p>
}
}
</pre></blockquote>
</pre></div>
<p>
As arguments, <tt>SWIG_exception()</tt> takes an error type code (an
integer) and an error message string. The currently supported error
types are :</p>
<blockquote><pre>
<div class="code"><pre>
SWIG_MemoryError
SWIG_IOError
SWIG_RuntimeError
@ -414,7 +435,7 @@ SWIG_SyntaxError
SWIG_ValueError
SWIG_SystemError
SWIG_UnknownError
</pre></blockquote>
</pre></div>
<p>
Since the <tt>SWIG_exception()</tt> function is defined at the C-level
@ -425,53 +446,61 @@ functions.
<H2><a name="ownership"></a>11.2 Object ownership and %newobject</H2>
<p>
A common problem in some applications is managing proper ownership of objects. For
example, consider a function like this:
</p>
<blockquote>
<div class="code">
<pre>
Foo *blah() {
Foo *f = new Foo();
return f;
}
</pre>
</blockquote>
</div>
<p>
If you wrap the function <tt>blah()</tt>, SWIG has no idea that the
return value is a newly allocated object. As a result, the resulting
extension module may produce a memory leak (SWIG is conservative and
will never delete objects unless it knows for certain that the
returned object was newly created).
</p>
<p>
To fix this, you can provide an extra hint to the code generator using
the <tt>%newobject</tt> directive. For example:
</p>
<blockquote>
<div class="code">
<pre>
%newobject blah;
Foo *blah();
</pre>
</blockquote>
</div>
<p>
<tt>%newobject</tt> works exactly like <tt>%rename</tt> and <tt>%exception</tt>. In other words,
you can attach it to class members and parameterized declarations as before. For example:
</p>
<blockquote>
<div class="code">
<pre>
%newobject ::blah(); // Only applies to global blah
%newobject Object::blah(int,double); // Only blah(int,double) in Object
%newobject *::copy; // Copy method in all classes
...
</pre>
</blockquote>
</div>
<p>
When <tt>%newobject</tt> is supplied, many language modules will
arrange to take ownership of the return value. This allows the value
to be automatically garbage-collected when it is no longer in use. However,
this depends entirely on the target language (a language module may also choose to ignore
the <tt>%newobject</tt> directive).
</p>
<p>
Closely related to <tt>%newobject</tt> is a special typemap. The "newfree" typemap
@ -480,7 +509,7 @@ methods for which <tt>%newobject</tt> has been applied and is commonly used to c
results. For example:
</p>
<blockquote>
<div class="code">
<pre>
%typemap(newfree) char * "free($1);";
...
@ -488,48 +517,54 @@ results. For example:
...
char *strdup(const char *s);
</pre>
</blockquote>
</div>
<p>
In this case, the result of the function is a string in the target language. Since this string
is a copy of the original result, the data returned by <tt>strdup()</tt> is no longer needed.
The "newfree" typemap in the example simply releases this memory.
</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:
</p>
<blockquote>
<div class="code">
<pre>
%new char *strdup(const char *s);
</pre>
</blockquote>
</div>
<p>
For now this is still supported but is deprecated.
</p>
<p>
<b>How to shoot yourself in the foot:</b> The <tt>%newobject</tt> directive is not a declaration modifier like the old
<tt>%new</tt> directive. Don't write code like this:
</p>
<blockquote>
<div class="code">
<pre>
%newobject
char *strdup(const char *s);
</pre>
</blockquote>
</div>
The results might not be what you expect.
<H2><a name="features"></a>11.3 Features and the %feature directive</H2>
<p>
Both <tt>%exception</tt> and <tt>%newobject</tt> are examples of a
more general purpose customization mechanism known as "features." A
feature is simply a user-definable property that is attached to
specific declarations in an interface file. Features are attached
using the <tt>%feature</tt> directive. For example:
</p>
<blockquote>
<div class="code">
<pre>
%feature("except") Object::allocate {
try {
@ -542,22 +577,26 @@ using the <tt>%feature</tt> directive. For example:
%feature("new","1") *::copy;
</pre>
</blockquote>
</div>
<p>
In fact, the <tt>%exception</tt> and <tt>%newobject</tt> directives are really nothing more than macros
involving <tt>%feature</tt>:
</p>
<blockquote>
<div class="code">
<pre>
#define %exception %feature("except")
#define %newobject %feature("new","1")
</pre>
</blockquote>
</div>
<p>
The <tt>%feature</tt> directive follows the same name matching rules
as the <tt>%rename</tt> directive (which is in fact just a special
form of <tt>%feature</tt>). This means that features can be applied with
pinpoint accuracy to specific declarations if needed.
</p>
<p>
When a feature is defined, it is given a name and a value. Most commonly, the
@ -571,11 +610,11 @@ A feature stays in effect until it is explicitly disabled. A feature is disable
supplying a <tt>%feature</tt> directive with no value. For example:
</p>
<blockquote>
<div class="code">
<pre>
%feature("except") Object::allocate; // Removes any previously defined feature
</pre>
</blockquote>
</div>
<p>
If no declaration name is given, a global feature is defined. This feature is then
@ -583,7 +622,7 @@ attached to <em>every</em> declaration that follows. This is how global excepti
are defined. For example:
</p>
<blockquote>
<div class="code">
<pre>
/* Define a global exception handler */
%feature("except") {
@ -598,40 +637,46 @@ are defined. For example:
/* Disable the exception handler */
%feature("except");
</pre>
</blockquote>
</div>
<p>
The <tt>%feature</tt> directive can be used with different syntax.
The following are all equivalent:
</p>
<blockquote>
<div class="code">
<pre>
%feature("except") Object::method { $action };
%feature("except") Object::method %{ $action %};
%feature("except") Object::method " $action ";
%feature("except","$action") Object::method;
</pre>
</blockquote>
</div>
<p>
The syntax in the first variation will generate the <tt>{ }</tt> delimeters used whereas the other variations will not.
The <tt>%feature</tt> directive also accepts XML style attributes in the same way that typemaps will.
Any number of attributes can be specified.
The following is the generic syntax for features:
</p>
<blockquote>
<div class="code">
<pre>
%feature("name","value", attribute1="AttibuteValue1") symbol;
%feature("name", attribute1="AttibuteValue1") symbol {value};
%feature("name", attribute1="AttibuteValue1") symbol %{value%};
%feature("name", attribute1="AttibuteValue1") symbol "value";
</pre>
</blockquote>
</div>
<p>
More than one attribute can be specified using a comma separated list.
The Java module is an example that uses attributes in <tt>%feature("except")</tt>.
The <tt>throws</tt> attribute specifies the name of a Java class to add to a proxy method's throws clause.
In the following example, <tt>MyExceptionClass</tt> is the name of the Java class for adding to the throws clause.
</p>
<blockquote>
<div class="code">
<pre>
%feature("except", throws="MyExceptionClass") Object::method {
try {
@ -641,7 +686,7 @@ In the following example, <tt>MyExceptionClass</tt> is the name of the Java clas
}
};
</pre>
</blockquote>
</div>
<p>
Further details can be obtained from the <a href="Java.html#exception_handling">Java exception handling</a> section.
@ -661,56 +706,56 @@ wrapper method only and not the extra overloaded methods that SWIG generates.
For example:
</p>
<blockquote>
<div class="code">
<pre>
%feature("except") void hello(int i=0, double d=0.0);
void hello(int i=0, double d=0.0);
</pre>
</blockquote>
</div>
<p>
will apply the feature to all three wrapper methods, that is:
</p>
<blockquote>
<div class="code">
<pre>
void hello(int i, double d);
void hello(int i);
void hello();
</pre>
</blockquote>
</div>
<p>
If the default arguments are not specified in the feature:
</p>
<blockquote>
<div class="code">
<pre>
%feature("except") void hello(int i, double d);
void hello(int i=0, double d=0.0);
</pre>
</blockquote>
</div>
<p>
then the feature will only apply to this wrapper method:
</p>
<blockquote>
<div class="code">
<pre>
void hello(int i, double d);
</pre>
</blockquote>
</div>
<p>
and not these wrapper methods:
</p>
<blockquote>
<div class="code">
<pre>
void hello(int i);
void hello();
</pre>
</blockquote>
</div>
<p>
If <a href="SWIGPlus.html#SWIGPlus_default_args">compactdefaultargs</a> are being used, then the difference between
@ -731,7 +776,7 @@ declarations with additional information for use by specific target language mod
in the Python module. You might use <tt>%feature</tt> to rewrite proxy/shadow class code as follows:
</p>
<blockquote>
<div class="code">
<pre>
%module example
%rename(bar_id) bar(int,double);
@ -751,9 +796,11 @@ public:
int bar(int x, double y);
}
</pre>
</blockquote>
</div>
<p>
Further details of <tt>%feature</tt> usage is described in the documentation for specific language modules.
</p>
</body>
</html>

891
Doc/Manual/Extending.html
View file

File diff suppressed because it is too large Load diff

198
Doc/Manual/Guile.html
View file

@ -3,12 +3,14 @@
<html>
<head>
<title>SWIG and Guile</title>
<link rel="stylesheet" type="text/css" href="style.css"/>
</head>
<body bgcolor="#ffffff">
<H1><a name="Guile"></a>18 SWIG and Guile</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="#Guile_nn2">Meaning of "Module"</a>
<li><a href="#Guile_nn3">Using the SCM or GH Guile API</a>
@ -37,6 +39,7 @@
<li><a href="#Guile_nn21">Linking</a>
</ul>
</ul>
</div>
<!-- INDEX -->
@ -80,7 +83,7 @@ whatever custom API the language uses. This is currently implemented by the gui
the SCM guile API rather than the GH guile API.
For example, here are some of the current mapping file for the SCM API</p>
<blockquote><pre>
<div class="code"><pre>
#define gh_append2(a, b) scm_append(scm_listify(a, b, SCM_UNDEFINED))
#define gh_apply(a, b) scm_apply(a, b, SCM_EOL)
@ -91,7 +94,7 @@ For example, here are some of the current mapping file for the SCM API</p>
#define gh_cons scm_cons
#define gh_double2scm scm_make_real
...
</pre></blockquote>
</pre></div>
<p>This file is parsed by SWIG at wrapper generation time, so every reference to a gh_ function is replaced
by a scm_ function in the wrapper file. Thus the gh_ function calls will never be seen in the wrapper;
@ -111,9 +114,11 @@ policies implementing a usage convention is called a <b>linkage</b>.
<H3><a name="Guile_nn5"></a>18.3.1 Simple Linkage</H3>
<p>
The default linkage is the simplest; nothing special is done. In this
case the function <code>SWIG_init()</code> is exported. Simple linkage
can be used in several ways:
</p>
<ul>
<li><b>Embedded Guile, no modules.</b> You want to embed a Guile
@ -122,42 +127,54 @@ in the root module. Then call <code>SWIG_init()</code> in the
<code>inner_main()</code> function. See the "simple" and "matrix" examples under
<code>Examples/guile</code>.
<li><b>Dynamic module mix-in.</b> You want to create a Guile module
<li><p><b>Dynamic module mix-in.</b> You want to create a Guile module
using <code>define-module</code>, containing both Scheme code and
bindings made by SWIG; you want to load the SWIG modules as shared
libraries into Guile.
<blockquote>
libraries into Guile.</p>
<div class="targetlang">
<pre>
(define-module (my module))
(define my-so (dynamic-link "./example.so"))
(dynamic-call "SWIG_init" my-so) ; make SWIG bindings
;; Scheme definitions can go here
</pre>
</blockquote>
</div>
<p>
Newer Guile versions provide a shorthand for <code>dynamic-link</code>
and <code>dynamic-call</code>:
<blockquote>
</p>
<div class="targetlang">
<pre>
(load-extension "./example.so" "SWIG_init")
</pre>
</blockquote>
</div>
<p>
You need to explicitly export those bindings made by SWIG that you
want to import into other modules:
<blockquote>
</p>
<div class="targetlang">
<pre>
(export foo bar)
</pre>
</blockquote>
</div>
<p>
In this example, the procedures <code>foo</code> and <code>bar</code>
would be exported. Alternatively, you can export all bindings with the
following module-system hack:
<blockquote>
</p>
<div class="targetlang">
<pre>
(module-map (lambda (sym var)
(module-export! (current-module) (list sym)))
(current-module))
</pre>
</blockquote>
</div>
<p>SWIG can also generate this Scheme stub (from
<code>define-module</code> up to <code>export</code>)
@ -171,15 +188,18 @@ to load your extension module (with <code>dynamic-link</code> or
information by including a directive like this in the interface file:
</p>
<blockquote>
<div class="code">
<pre>
%scheme %{ (load-extension "./example.so" "SWIG_init") %}
</pre>
</blockquote>
</div>
<p>
(The <code>%scheme</code> directive allows to insert arbitrary Scheme
code into the generated file <code><var>module.scm</var></code>; it is
placed between the <code>define-module</code> form and the
<code>export</code> form.)
</p>
</ul>
<p>If you want to include several SWIG modules, you would need to rename
@ -222,19 +242,19 @@ in the <code>inner_main()</code> function.
<li><b>Dynamic Guile modules.</b> You want to load the SWIG modules as
shared libraries into Guile; all bindings are automatically put in
newly created Guile modules.
<blockquote>
<div class="targetlang">
<pre>
(define my-so (dynamic-link "./foo.so"))
;; create new module and put bindings there:
(dynamic-call "scm_init_my_modules_foo_module" my-so)
</pre>
</blockquote>
</div>
Newer Guile versions have a shorthand procedure for this:
<blockquote>
<div class="targetlang">
<pre>
(load-extension "./foo.so" "scm_init_my_modules_foo_module")
</pre>
</blockquote>
</div>
</ul>
<H3><a name="Guile_nn8"></a>18.3.4 Old Auto-Loading Guile Module Linkage</H3>
@ -274,12 +294,12 @@ using the "-package" command line option to set the part of the module
name before the last symbol. For example, both command lines:
</p>
<blockquote>
<div class="shell">
<pre>
swig -guile -package my/lib foo.i
swig -guile -package my/lib -module foo foo.i
</pre>
</blockquote>
</div>
<p>
would create module <code>(my lib foo)</code> (assuming in the first
@ -326,45 +346,65 @@ a value to the list of function return values.
<p>Multiple values can be passed up to Scheme in one of three ways:
<ul>
<li><em>Multiple values as lists.</em>
<li><p><em>Multiple values as lists.</em>
By default, if more than one value is to
be returned, a list of the values is created and returned; to switch
back to this behavior, use
<blockquote>
back to this behavior, use</p>
<div class="code">
<pre>
%values_as_list;</pre>
</blockquote>
</div>
<p>
<li><em>Multiple values as vectors.</em>
By issuing
<blockquote>
</p>
<div class="code">
<pre>
%values_as_vector;</pre>
</blockquote>
</div>
<p>
vectors instead of lists will be used.
<li><em>Multiple values for multiple-value continuations.</em>
<strong>This is the most elegant way.</strong> By issuing
<blockquote>
</p>
<div class="code">
<pre>
%multiple_values;</pre>
</blockquote>
</div>
<p>
multiple values are passed to the multiple-value
continuation, as created by <code>call-with-values</code> or the
convenience macro <code>receive</code>. The latter is available if you
issue <code>(use-modules (srfi srfi-8))</code>. Assuming that your
<code>divide</code> function
wants to return two values, a quotient and a remainder, you can write:
<blockquote>
</p>
<div class="targetlang">
<pre>
(receive (quotient remainder)
(divide 35 17)
<var>body</var>...)
</pre>
</blockquote>
</div>
<p>
In <code><var>body</var></code>, the first result of
<code>divide</code> will be bound to the variable
<code>quotient</code>, and the second result to <code>remainder</code>.
</p>
</ul>
<p>
See also the "multivalue" example.
</p>
<H2><a name="Guile_nn12"></a>18.6 Representation of pointers as smobs</H2>
@ -388,6 +428,8 @@ 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>18.6.1 GH Smobs</H3>
<p>
In earlier versions of SWIG, C pointers were represented as Scheme
strings containing a hexadecimal rendering of the pointer value and a
@ -450,6 +492,7 @@ the guile module replaces $owner with 0 or 1 depending on feature:new.</p>
SWIG code calls <code>scm_error</code> on exception, using the following
mapping:
<div class="code">
<pre>
MAP(SWIG_MemoryError, "swig-memory-error");
MAP(SWIG_IOError, "swig-io-error");
@ -462,6 +505,7 @@ mapping:
MAP(SWIG_ValueError, "swig-value-error");
MAP(SWIG_SystemError, "swig-system-error");
</pre>
</div>
<p>
The default when not specified here is to use "swig-error".
@ -490,11 +534,14 @@ later.
<p>You need to register the generated documentation file with Guile
like this:
<div class="targetlang">
<pre>
(use-modules (ice-9 documentation))
(set! documentation-files
(cons "<var>file</var>" documentation-files))
</pre>
</div>
<p>Documentation strings can be configured using the Guile-specific
typemap argument <code>doc</code>. See <code>Lib/guile/typemaps.i</code> for
@ -550,7 +597,7 @@ current directory. GOOPS support requires either passive or module linkage.</p>
<p>If <code>-emit-slot-accessors</code> is also passed as an argument,
then the generated file will contain accessor methods for all the
slots in the classes and for global variables. The input class</p>
<blockquote><pre>
<div class="code"><pre>
class Foo {
public:
Foo(int i) : a(i) {}
@ -559,9 +606,13 @@ slots in the classes and for global variables. The input class</p>
Foo getFooMultBy(int i) { return Foo(a * i); }
};
Foo getFooPlus(int i) { return Foo(a + i); }
</pre></blockquote>
</pre></div>
<p>
will produce (if <code>-emit-slot-accessors</code> is not passed as a parameter)
<blockquote><pre>
</p>
<div class="targetlang"><pre>
(define-class &lt;Foo&gt; (&lt;swig&gt;)
(a #:allocation #:swig-virtual
#:slot-ref primitive:Foo-a-get
@ -578,9 +629,13 @@ will produce (if <code>-emit-slot-accessors</code> is not passed as a parameter)
(make &lt;Foo&gt; #:init-smob (primitive:getFooPlus i)))
(export &lt;Foo&gt; getMultBy getFooMultBy getFooPlus )
</pre></blockquote>
</pre></div>
<p>
and will produce (if <code>-emit-slot-accessors</code> is passed as a parameter)
<blockquote><pre>
</p>
<div class="targetlang"><pre>
(define-class &lt;Foo&gt; (&lt;swig&gt;)
(a #:allocation #:swig-virtual
#:slot-ref primitive:Foo-a-get
@ -598,9 +653,13 @@ and will produce (if <code>-emit-slot-accessors</code> is passed as a parameter)
(make &lt;Foo&gt; #:init-smob (primitive:getFooPlus i)))
(export &lt;Foo&gt; <b>a</b> getMultBy getFooMultBy getFooPlus )
</pre></blockquote>
</pre></div>
<p>
which can then be used by this code
<blockquote><pre>
</p>
<div class="targetlang"><pre>
;; not using getters and setters
(define foo (make &lt;Foo&gt; #:args '(45)))
(slot-ref foo 'a)
@ -616,13 +675,15 @@ which can then be used by this code
(set! (a foo) 5)
(getMultBy foo 4)
(a (getFooMultBy foo 7))
</pre></blockquote>
</pre></div>
<p>Notice that constructor arguments are passed as a list after the <code>#:args</code> keyword. Hopefully in
the future the following will be valid <code>(make &lt;Foo&gt; #:a 5 #:b 4)</code></p>
<p>Also note that the order the declarations occur in the .i file make a difference. For example,
</p><blockquote><pre>
</p>
<div class="code"><pre>
%module test
%{ #include "foo.h" %}
@ -634,12 +695,16 @@ the future the following will be valid <code>(make &lt;Foo&gt; #:a 5 #:b 4)</cod
%}
%include "foo.h"
</pre></blockquote>
</pre></div>
<p>
This is a valid SWIG file it will work as you think it will for primitive support, but the generated
GOOPS file will be broken. Since the <code>someFunc</code> definition is parsed by SWIG before all the
declarations in foo.h, the generated GOOPS file will contain the definition of <code>someFunc()</code>
before the definition of &lt;Foo&gt;. The generated GOOPS file would look like
<blockquote><pre>
</p>
<div class="targetlang"><pre>
;;...
(define-method (someFunc (swig_smob &lt;Foo&gt;))
@ -652,9 +717,12 @@ before the definition of &lt;Foo&gt;. The generated GOOPS file would look like
)
;;...
</pre></blockquote>
</pre></div>
<p>
Notice that &lt;Foo&gt; is used before it is defined. The fix is to just put the
<code>%import "foo.h"</code> before the <code>%inline</code> block.
</p>
<H3><a name="Guile_nn20"></a>18.10.1 Naming Issues</H3>
@ -688,10 +756,10 @@ In the previous example, the GOOPS definitions will be in a file named Test.scm.
<p>Because of the naming conflicts, you can't in general use both the <code>-primitive</code> and the GOOPS
guile-modules at the same time. To do this, you need to rename the exported symbols from one or both
guile-modules. For example,</p>
<blockquote><pre>
<div class="targetlang"><pre>
(use-modules ((Test-primitive) #:renamer (symbol-prefix-proc 'primitive:)))
(use-modules ((Test) #:renamer (symbol-prefix-proc 'goops:)))
</pre></blockquote>
</pre></div>
<p>TODO: Renaming class name prefixes?</p>
@ -717,31 +785,35 @@ argument to solve this problem. If the <code>-exportprimitive</code> option is
of the generated GOOPS guile-module.
The <code>%goops</code> directive should contain code to load the .so library.
<blockquote><pre>
<div class="code"><pre>
%goops %{ (load-extension "./foo.so" "scm_init_my_modules_foo_module") %}
</pre></blockquote>
</pre></div>
<p>
Produces the following code at the top of the generated GOOPS guile-module
(with the <code>-package my/modules -module foo</code> command line arguments)
<blockquote><pre>
</p>
<div class="targetlang"><pre>
(define-module (my modules foo))
;; %goops directive goes here
(load-extension "./foo.so" "scm_init_my_modules_foo_module")
(use-modules (oop goops) (Swig common))
</pre></blockquote>
</pre></div>
</li>
<li><b>Passive Linkage with -scmstub</b>: Here, the name of the scmstub file should be
<li><p><b>Passive Linkage with -scmstub</b>: Here, the name of the scmstub file should be
<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>
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.
whatever code is needed to load the <i>Module-primitive.scm</i> file into guile.</p>
<blockquote><pre>
<div class="targetlang"><pre>
%scheme %{ (load-extension "./foo.so" "scm_init_my_modules_foo_module") %}
// only include the following definition if (my modules foo) cannot
// be loaded automatically
@ -749,9 +821,13 @@ whatever code is needed to load the <i>Module-primitive.scm</i> file into guile.
(primitive-load "/path/to/foo-primitive.scm")
(primitive-load "/path/to/Swig/common.scm")
%}
</pre></blockquote>
</pre></div>
<p>
Produces the following code at the top of the generated GOOPS guile-module
<blockquote><pre>
</p>
<div class="targetlang"><pre>
(define-module (my modules foo))
;; %goops directive goes here (if any)
@ -762,21 +838,23 @@ Produces the following code at the top of the generated GOOPS guile-module
(use-modules ((my modules foo-primitive) :renamer (symbol-prefix-proc
'primitive:)))
</pre></blockquote>
</pre></div>
</li>
<li><b>Module Linkage</b>: This is very similar to passive linkage with a scmstub file.
<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
(<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.
directive should contain whatever code is needed to get that module loaded into guile.</p>
<blockquote><pre>
<div class="code"><pre>
%goops %{ (load-extension "./foo.so" "scm_init_my_modules_foo_module") %}
</pre></blockquote>
</pre></div>
<p>
Produces the following code at the top of the generated GOOPS guile-module
</p>
<blockquote><pre>
<div class="targetlang"><pre>
(define-module (my modules foo))
;; %goops directive goes here (if any)
@ -786,7 +864,7 @@ Produces the following code at the top of the generated GOOPS guile-module
(use-modules ((my modules foo-primitive) :renamer (symbol-prefix-proc
'primitive:)))
</pre></blockquote>
</pre></div>
</li>
</ul>

66
Doc/Manual/Introduction.html
View file

@ -2,11 +2,13 @@
<html>
<head>
<title>Introduction</title>
<link rel="stylesheet" type="text/css" href="style.css"/>
</head>
<body bgcolor="#ffffff">
<H1><a name="Introduction"></a>2 Introduction</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="#Introduction_nn2">What is SWIG?</a>
<li><a href="#Introduction_nn3">Why use SWIG?</a>
@ -24,6 +26,7 @@
<li><a href="#Introduction_nn12">Hands off code generation</a>
<li><a href="#Introduction_nn13">SWIG and freedom</a>
</ul>
</div>
<!-- INDEX -->
@ -31,6 +34,7 @@
<H2><a name="Introduction_nn2"></a>2.1 What is SWIG?</H2>
<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
@ -39,6 +43,7 @@ including Perl, Python, Tcl, Ruby, Guile, and Java. SWIG normally
requires no modifications to existing code and can often be used to
build a usable interface in only a few minutes. Possible applications
of SWIG include:
</p>
<ul>
<li>Building interpreted interfaces to existing C programs.
@ -68,10 +73,12 @@ in scientific and engineering projects.
<H2><a name="Introduction_nn3"></a>2.2 Why use SWIG?</H2>
<p>
As stated in the previous section, the primary purpose of SWIG is to simplify
the task of integrating C/C++ with other programming languages. However, why would
anyone want to do that? To answer that question, it is useful to list a few strengths
of C/C++ programming:
</p>
<ul>
<li>Excellent support for writing programming libraries.
@ -80,7 +87,9 @@ of C/C++ programming:
<li>Large user community and software base.
</ul>
<p>
Next, let's list a few problems with C/C++ programming
</p>
<ul>
<li>Writing a user interface is rather painful (i.e., consider programming with MFC, X11, GTK, or any number
@ -90,7 +99,7 @@ of other libraries).
<li>Modularization can be tricky.
<li>Security concerns (buffer overflow for instance).
</ul>
<p>
To address these limitations, many programmers have arrived at the
conclusion that it is much easier to use different programming
languages for different tasks. For instance, writing a graphical user
@ -104,6 +113,7 @@ strengths and weaknesses. Moreover, it is extremely unlikely that any
programming is ever going to be perfect. Therefore, by combining
languages together, you can utilize the best features of each language
and greatly simplify certain aspects of software development.
</p>
<p>
From the standpoint of C/C++, a lot of people use SWIG because they want to break
@ -116,10 +126,11 @@ in programs that resemble this:
<li>A horrible collection of hacks that form some kind of user interface (but
which no-one really wants to touch).
</ul>
<p>
Instead of going down that route, incorporating C/C++ into a higher level language
often results in a more modular design, less code, better flexibility, and increased
programmer productivity.
</p>
<p>
SWIG tries to make the problem of C/C++ integration as painless as possible.
@ -134,10 +145,12 @@ user manual ;-).
<H2><a name="Introduction_nn4"></a>2.3 A SWIG example</H2>
<p>
The best way to illustrate SWIG is with a simple example. Consider the
following C code:
</p>
<blockquote><pre>
<div class="code"><pre>
/* File : example.c */
double My_variable = 3.0;
@ -152,7 +165,7 @@ int fact(int n) {
int my_mod(int n, int m) {
return(n % m);
}
</pre></blockquote>
</pre></div>
<p>
Suppose that you wanted to access these functions and the global
@ -163,7 +176,7 @@ suffix) :
<H3><a name="Introduction_nn5"></a>2.3.1 SWIG interface file</H3>
<blockquote><pre>
<div class="code"><pre>
/* File : example.i */
%module example
%{
@ -173,7 +186,7 @@ suffix) :
extern double My_variable;
extern int fact(int);
extern int my_mod(int n, int m);
</pre></blockquote>
</pre></div>
<p>
The interface file contains ANSI C function prototypes and variable
@ -185,10 +198,12 @@ files or additional C declarations.
<H3><a name="Introduction_nn6"></a>2.3.2 The swig command</H3>
<p>
SWIG is invoked using the <tt>swig</tt> command. We can use this to
build a Tcl module (under Linux) as follows :
</p>
<blockquote><pre>
<div class="code"><pre>
unix &gt; <b>swig -tcl example.i</b>
unix &gt; <b>gcc -c -fpic example.c example_wrap.c -I/usr/local/include</b>
unix &gt; <b>gcc -shared example.o example_wrap.o -o example.so</b>
@ -201,7 +216,7 @@ unix &gt; <b>tclsh</b>
% <b>expr $My_variable + 4.5</b>
7.5
%
</pre></blockquote>
</pre></div>
<p>
The <tt>swig</tt> command produced a new file called
@ -217,10 +232,12 @@ almost never need to worry about it.
<H3><a name="Introduction_nn7"></a>2.3.3 Building a Perl5 module</H3>
<p>
Now, let's turn these functions into a Perl5 module. Without making
any changes type the following (shown for Solaris):
</p>
<blockquote><pre>
<div class="code"><pre>
unix &gt; <b>swig -perl5 example.i</b>
unix &gt; <b>gcc -c example.c example_wrap.c \
-I/usr/local/lib/perl5/sun4-solaris/5.003/CORE</b>
@ -235,15 +252,17 @@ print $example::My_variable + 4.5, "\n";
2
7.5
unix &gt;
</pre></blockquote>
</pre></div>
<H3><a name="Introduction_nn8"></a>2.3.4 Building a Python module</H3>
<p>
Finally, let's build a module for Python (shown for Irix).
</p>
<blockquote><pre>
<div class="code"><pre>
unix &gt; <b>swig -python example.i</b>
unix &gt; <b>gcc -c -fpic example.c example_wrap.c -I/usr/local/include/python2.0</b>
unix &gt; <b>gcc -shared example.o example_wrap.o -o _example.so</b>
@ -258,17 +277,19 @@ Type "copyright", "credits" or "license" for more information.
2
&gt;&gt;&gt; <b>example.cvar.My_variable + 4.5</b>
7.5
</pre></blockquote>
</pre></div>
<H3><a name="Introduction_nn9"></a>2.3.5 Shortcuts</H3>
<p>
To the truly lazy programmer, one may wonder why we needed the extra
interface file at all. As it turns out, you can often do without
it. For example, you could also build a Perl5 module by just running
SWIG on the C header file and specifying a module name as follows
</p>
<blockquote><pre>
<div class="code"><pre>
unix &gt; <b>swig -perl5 -module example example.h</b>
unix &gt; <b>gcc -c example.c example_wrap.c \
-I/usr/local/lib/perl5/sun4-solaris/5.003/CORE</b>
@ -282,15 +303,17 @@ print $example::My_variable + 4.5, "\n";
24
2
7.5
</pre></blockquote>
</pre></div>
<H2><a name="Introduction_nn10"></a>2.4 Supported C/C++ language features</H2>
<p>
A primary goal of the SWIG project is to make the language binding
process extremely easy. Although a few simple examples have been shown,
SWIG is quite capable in supporting most of C++. Some of the
major features include:
</p>
<ul>
<li>Full C99 preprocessing.
@ -306,8 +329,10 @@ major features include:
<li>C++ smart pointers.
</ul>
<p>
Currently, the only major C++ feature not supported is nested classes--a limitation
that will be removed in a future release.
</p>
<p>
It is important to stress that SWIG is not a simplistic C++ lexing
@ -323,12 +348,14 @@ stresses the very limits of many C++ compilers.
<H2><a name="Introduction_nn11"></a>2.5 Non-intrusive interface building</H2>
<p>
When used as intended, SWIG requires minimal (if any) modification to
existing C or C++ code. This makes SWIG extremely easy to use with existing
packages and promotes software reuse and modularity. By making
the C/C++ code independent of the high level interface, you can change the
interface and reuse the code in other applications. It is also
possible to support different types of interfaces depending on the application.
</p>
<H2><a name="Introduction_build_system"></a>2.6 Incorporating SWIG into a build system</H2>
@ -362,7 +389,7 @@ driving SWIG from IDE's and makefiles. All of this can be done from a single cr
The following example is a CMake input file for creating a python wrapper for the SWIG interface file, example.i:
</p>
<blockquote><pre>
<div class="code"><pre>
# This is a CMake example for Python
@ -381,14 +408,16 @@ SET_SOURCE_FILES_PROPERTIES(example.i PROPERTIES SWIG_FLAGS "-includeall")
SWIG_ADD_MODULE(example python example.i example.cxx)
SWIG_LINK_LIBRARIES(example ${PYTHON_LIBRARIES})
</pre></blockquote>
</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).
</p>
<H2><a name="Introduction_nn12"></a>2.7 Hands off code generation</H2>
<p>
SWIG is designed to produce working code that needs no
hand-modification (in fact, if you look at the output, you probably
won't want to modify it). You should think of your target language interface being
@ -396,10 +425,12 @@ defined entirely by the input to SWIG, not the resulting output
file. While this approach may limit flexibility for hard-core hackers,
it allows others to forget about the low-level implementation
details.
</p>
<H2><a name="Introduction_nn13"></a>2.8 SWIG and freedom</H2>
<p>
No, this isn't a special section on the sorry state of world politics.
However, it may be useful to know that SWIG was written with a
certain "philosophy" about programming---namely that programmers are
@ -409,6 +440,7 @@ you get away with. In fact, you can use SWIG to go well beyond
"shooting yourself in the foot" if dangerous programming is your goal.
On the other hand, this kind of freedoom may be exactly what is needed
to work with complicated and unusual C/C++ applications.
</p>
<p>
Ironically, the freedom that SWIG provides is countered by an

1775
Doc/Manual/Java.html
View file

File diff suppressed because it is too large Load diff

608
Doc/Manual/Library.html
View file

File diff suppressed because it is too large Load diff

3
Doc/Manual/Makefile
View file

@ -26,8 +26,9 @@ check:
all=`sed '/^#/d' chapters`; for a in $$all; do tidy -errors --gnu-emacs yes -quiet $$a; done;
generate: swightml.book swigpdf.book
htmldoc --batch swightml.book
htmldoc --batch swightml.book || true
htmldoc --batch swigpdf.book
python fixstyle.py SWIGDocumentation.html
swightml.book:
echo "#HTMLDOC 1.8.23" > swightml.book

49
Doc/Manual/Modula3.html
View file

@ -2,10 +2,12 @@
<html>
<head>
<title>SWIG and Modula-3</title>
<link rel="stylesheet" type="text/css" href="style.css"/>
</head>
<body bgcolor="#FFFFFF">
<H1><a name="Modula3"></a>20 SWIG and Modula-3</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="#modula3_overview">Overview</a>
<ul>
@ -40,10 +42,12 @@
</ul>
<li><a href="#remarks">Remarks</a>
</ul>
</div>
<!-- INDEX -->
<p>
This chapter describes SWIG's support of
<a href="http://www.m3.org/">Modula-3</a>.
You should be familiar with the
@ -51,6 +55,7 @@ You should be familiar with the
of SWIG,
especially
<a href="Typemaps.html">typemaps</a>.
</p>
<H2><a name="modula3_overview"></a>20.1 Overview</H2>
@ -78,9 +83,11 @@ FFTW
</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>20.1.1 Why not scripting ?</H3>
@ -141,12 +148,14 @@ Modula-3 is made in one go
and the language definition is really compact.
</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.
</p>
<p>
Unfortunately Modula's safety and strength
@ -337,8 +346,11 @@ generates several files:
</tr>
</table>
<p>
Here's a scheme of how the function calls to Modula-3 wrappers
are redirected to C library functions:
</p>
<table summary="Modula-3 C library">
<tr>
<td align=center>
@ -403,8 +415,11 @@ but C++ compilers should support generating C++ functions
with a C interface.
</p>
<p>
Here's a scheme of how the function calls to Modula-3 wrappers
a redirected to C library functions:
</p>
<table summary="Modula-3 C++ library">
<tr>
<td align=center>
@ -496,6 +511,7 @@ so I'm not sure if this is possible or sensible, yet.
<H3><a name="compilers"></a>20.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
@ -503,15 +519,18 @@ but the library file
<a href="../../Lib/modula3/modula3.swg"><tt>modula3.swg</tt></a>
may do so.
For testing examples I use Critical Mass cm3.
</p>
<H3><a name="commandline"></a>20.3.2 Additional Commandline Options</H3>
<p>
There are some experimental command line options
that prevent SWIG from generating interface files.
Instead files are emitted that may assist you
when writing SWIG interface files.
</p>
<table border summary="Modula-3 specific options">
<tr>
@ -802,9 +821,12 @@ consist of the following parts:
<H3><a name="ordinals"></a>20.4.2 Subranges, Enumerations, Sets</H3>
<p>
Subranges, enumerations, and sets are machine oriented types
that make Modula very strong and expressive compared
with the type systems of many other languages.
</p>
<ul>
<li>
Subranges are used for statically restricted choices of integers.
@ -816,8 +838,12 @@ Enumerations are used for named choices.
Sets are commonly used for flag (option) sets.
</li>
</ul>
Using them extensively makes Modula code very safe and readable.
<p>
Using them extensively makes Modula code very safe and readable.
</p>
<p>
C supports enumerations, too, but they are not as safe as the ones of Modula.
Thus they are abused for many things:
For named choices, for integer constant definitions, for sets.
@ -826,7 +852,9 @@ To make it complete every way of defining a value in C
is somewhere used for defining something
that must be handled completely different in Modula-3
(<tt>INTEGER</tt>, enumeration, <tt>SET</tt>).
</p>
<p>
I played around with several <tt>%feature</tt>s and <tt>%pragma</tt>s
that split the task up into converting
the C bit patterns (integer or bit set)
@ -839,17 +867,20 @@ So the best what you can currently do is
to rewrite constant definitions manually.
Though this is a tedious work
that I'd like to automate.
</p>
<H3><a name="class"></a>20.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>
is not really useful, yet.
</p>
<H3><a name="imports"></a>20.4.4 Imports</H3>
@ -878,40 +909,50 @@ for the typemap library
For a monolithic module you might be better off
if you add the imports directly:
</p>
<div class="code">
<pre>
%insert(m3rawintf) %{
IMPORT M3toC;
%}
</pre>
</pre></div>
<H3><a name="exceptions"></a>20.4.5 Exceptions</H3>
<p>
Modula-3 provides another possibility
of an output of a function: exceptions.
</p>
<p>
Any piece of Modula-3 code that SWIG inserts
due to a typemap can raise an exception.
This way you can also convert an error code
from a C function into a Modula-3 exception.
</p>
<p>
The <tt>RAISES</tt> clause is controlled
by typemaps with the <tt>throws</tt> extension.
If the typemap <tt>m3wrapinconv</tt> for <tt>blah *</tt>
contains code that may raise the exceptions <tt>OSError.E</tt>
you should declare
<tt>%typemap("m3wrapinconv:throws") blah * %{OSError.E%}</tt>.
</p>
<H3><a name="typemap_example"></a>20.4.6 Example</H3>
<p>
The generation of wrappers in Modula-3 needs very fine control
to take advantage of the language features.
Here is an example of a generated wrapper
where almost everything is generated by a typemap:
</p>
<blockquote><pre>
<div class="code"><pre>
<I> (* %relabel m3wrapinmode m3wrapinname m3wrapintype m3wrapindefault *)</I>
PROCEDURE Name (READONLY str : TEXT := "" )
<I> (* m3wrapoutcheck:throws *)</I>
@ -945,7 +986,7 @@ where almost everything is generated by a typemap:
M3toC.FreeSharedS(str,arg1); <I>(* m3wrapfreearg *)</I>
END;
END Name;
</pre></blockquote>
</pre></div>
<H2><a name="hints"></a>20.5 More hints to the generator</H2>

29
Doc/Manual/Modules.html
View file

@ -2,22 +2,26 @@
<html>
<head>
<title>Working with Modules</title>
<link rel="stylesheet" type="text/css" href="style.css"/>
</head>
<body bgcolor="#ffffff">
<H1><a name="Modules"></a>15 Working with Modules</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="#Modules_nn2">The SWIG runtime code</a>
<li><a href="#external_run_time">External access to runtime system</a>
<li><a href="#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>
</ul>
</div>
<!-- INDEX -->
<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
@ -25,6 +29,7 @@ wrapper code into a module 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.
</p>
<p>
This chapter describes the problem of using SWIG in programs
@ -34,6 +39,7 @@ where you want to create a collection of modules.
<H2><a name="Modules_nn2"></a>15.1 The SWIG runtime code</H2>
<p>
Many of SWIG's target languages generate a set of functions
commonly known as the "SWIG runtime." These functions are
primarily related to the runtime type system which checks pointer
@ -42,6 +48,7 @@ values in C++. As a general rule, the statically typed target languages,
such as Java, use the language's built in static type checking and
have no need for a SWIG runtime. All the dynamically typed / interpreted
languages rely on the SWIG runtime.
</p>
<p>
The runtime functions are private to each SWIG-generated
@ -69,7 +76,8 @@ Be careful if you use threads and the automatic module loading that some scripti
languages provide. One solution is to load all modules before spawning any threads.
</p>
<H2><a name="external_run_time"></a>15.2 External access to the run-time system</a></H2>
<H2><a name="external_run_time"></a>15.2 External access to the runtime</H2>
<p>As described in <a href="Typemaps.html#runtime_type_checker">The run-time type checker</a>,
the functions <tt>SWIG_TypeQuery</tt>, <tt>SWIG_NewPointerObj</tt>, and others sometimes need
@ -78,9 +86,9 @@ is embedded into the <tt>_wrap.c</tt> file, which has those declerations availab
to call the SWIG run-time functions from another C file, there is one header you need
to include. To generate the header that needs to be included, run the following command:
<blockquote><pre>
<div class="code"><pre>
$ swig -python -external-runtime &lt;filename&gt;
</pre></blockquote>
</pre></div>
<p>The filename argument is optional and if it is not passed, then the default filename will
be something like <tt>swigpyrun.h</tt>, depending on the language. This header file should
@ -101,17 +109,21 @@ because the header file is self contained, and does not need to link with anythi
<H2><a name="Modules_nn4"></a>15.3 A word of caution about static libraries</H2>
<p>
When working with multiple SWIG modules, you should take care not to use static
libraries. For example, if you have a static library <tt>libfoo.a</tt> and you link a collection
of SWIG modules with that library, each module will get its own private copy of the library code inserted
into it. This is very often <b>NOT</b> what you want and it can lead to unexpected or bizarre program
behavior. When working with dynamically loadable modules, you should try to work exclusively with shared libaries.
</p>
<H2><a name="Modules_nn5"></a>15.4 References</H2>
<p>
Due to the complexity of working with shared libraries and multiple modules, it might be a good idea to consult
an outside reference. John Levine's "Linkers and Loaders" is highly recommended.
</p>
<H2><a name="Modules_nn6"></a>15.5 Reducing the wrapper file size</H2>
@ -122,10 +134,12 @@ In this way a number of different wrapper files can be generated, thereby avoidi
There are a couple of alternative solutions for reducing the size of a wrapper file through the use of command line options and features.
</p>
<p>
<b>-fcompact</b><br>
This command line option will compact the size of the wrapper file without changing the code generated into the wrapper file.
It simply removes blank lines and joins lines of code together.
This is useful for compilers that have a maximum file size that can be handled.
</p>
<p>
<b>-fvirtual</b><br>
@ -133,7 +147,7 @@ This command line option will remove the generation of superfluous virtual metho
Consider the following inheritance hierarchy:
</p>
<blockquote>
<div class="code">
<pre>
struct Base {
virtual void method();
@ -145,10 +159,13 @@ struct Derived : Base {
...
};
</pre>
</blockquote>
</div>
<p>
Normally wrappers are generated for both methods, whereas this command line option will suppress the generation of a wrapper for <tt>Derived::method</tt>.
Normal polymorphic behaviour remains as <tt>Derived::method</tt> will still be called should you have
a <tt>Derived</tt> instance and call the wrapper for <tt>Base::method</tt>.
</p>
<p>
<b>%feature("compactdefaultargs")</b><br>

19
Doc/Manual/Mzscheme.html
View file

@ -3,15 +3,18 @@
<html>
<head>
<title>SWIG and MzScheme</title>
<link rel="stylesheet" type="text/css" href="style.css"/>
</head>
<body bgcolor="#ffffff">
<H1><a name="MzScheme"></a>21 SWIG and MzScheme</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="#MzScheme_nn2">Creating native MzScheme structures</a>
</ul>
</div>
<!-- INDEX -->
@ -22,8 +25,11 @@ This section contains information on SWIG's support of MzScheme.
<H2><a name="MzScheme_nn2"></a>21.1 Creating native MzScheme structures</H2>
<p>
Example interface file:
<blockquote>
</p>
<div class="code">
<pre>
/* define a macro for the struct creation */
%define handle_ptr(TYPE,NAME)
@ -40,10 +46,13 @@ Example interface file:
/* setup the typemaps for the pointer to an output parameter cntrs */
handle_ptr(struct diag_cntrs, cntrs);
</pre>
</blockquote>
</div>
<p>
Then in scheme, you can use regular struct access procedures like
<blockquote>
</p>
<div class="code">
<pre>
; suppose a function created a struct foo as
; (define foo (make-diag-cntrs (#x1 #x2 #x3) (make-inspector))
@ -52,9 +61,11 @@ Then in scheme, you can use regular struct access procedures like
(format "0x~x" (diag-cntrs-field2 foo))
;etc...
</pre>
</blockquote>
</div>
<p>
That's pretty much it. It works with nested structs as well.
</p>
</body>
</html>

83
Doc/Manual/Ocaml.html
View file

@ -2,12 +2,13 @@
<html>
<head>
<title>SWIG and Ocaml</title>
<link rel="stylesheet" type="text/css" href="style.css"/>
</head>
<body bgcolor="#ffffff">
<a name="n1"></a>
<H1><a name="Ocaml"></a>22 SWIG and Ocaml</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="#Ocaml_nn2">Preliminaries</a>
<ul>
@ -52,10 +53,12 @@
<li><a href="#Ocaml_nn31">Exceptions</a>
</ul>
</ul>
</div>
<!-- INDEX -->
<p>
This chapter describes SWIG's
support of Ocaml. Ocaml is a relatively recent addition to the ML family,
and is a recent addition to SWIG. It's the second compiled, typed
@ -70,6 +73,7 @@ way with Ocaml, by providing the necessary, but repetetive glue code
which creates and uses Ocaml values to communicate with C and C++ code.
In addition, SWIG also produces the needed Ocaml source that binds
variants, functions, classes, etc.
</p>
<p>
If you're not familiar with the Objective Caml language, you can visit
@ -79,6 +83,7 @@ If you're not familiar with the Objective Caml language, you can visit
<H2><a name="Ocaml_nn2"></a>22.1 Preliminaries</H2>
<p>
SWIG 1.3 works with Ocaml 3.04 and above. Given the choice,
you should use the latest stable release. The SWIG Ocaml module has
been tested on Linux (x86,PPC,Sparc) and Cygwin on Windows. The
@ -92,20 +97,23 @@ usual -lxxx against libxxx.so, as well as with Gerd Stolpmann's
</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>22.1.1 Running SWIG</H3>
<p>
The basics of getting a SWIG Ocaml module up and running
can be seen from one of SWIG's example Makefiles, but is also described
here. To build an Ocaml module, run SWIG using the <tt>-ocaml</tt>
option.
</p>
<blockquote>
<div class="code">
<pre>
%swig -ocaml example.i
</pre>
</blockquote>
</div>
<p> This will produce 3 files. The file <tt>example_wrap.c</tt> contains
all of the C code needed to build an Ocaml module. To build the module,
@ -130,7 +138,7 @@ the user more freedom with respect to custom typing.
SWIG interface like:
</p>
<blockquote>
<div class="code">
<pre>
% swig -ocaml -co swig.mli ; swig -ocaml co swig.ml
% ocamlc -c swig.mli ; ocamlc -c swig.ml
@ -138,17 +146,17 @@ the user more freedom with respect to custom typing.
% ocamlc -c example.mli
% ocamlc -c example.ml
</pre>
</blockquote>
</div>
<p> <tt>ocamlc</tt> is aware of .c files and knows how to handle them. Unfortunately,
it does not know about .cxx, .cc, or .cpp files, so when SWIG is invoked
in C++ mode, you must: </p>
<blockquote>
<div class="code">
<pre>
% cp example_wrap.cxx example_wrap.cxx.c<br>% ocamlc -c ... -ccopt -xc++ example_wrap.cxx.c<br>% ...<br>
</pre>
</blockquote>
</div>
<H3><a name="Ocaml_nn5"></a>22.1.3 The camlp4 module</H3>
@ -268,7 +276,7 @@ caml_list_append function, or with functions and macros provided by
objective caml.<br>
</p>
<blockquote><pre>
<div class="code"><pre>
type c_obj =
C_void
| C_bool of bool
@ -288,8 +296,11 @@ type c_obj =
| C_obj of (string -&gt; c_obj -&gt; c_obj)
| C_string of string
| C_enum of c_enum_t
</pre></blockquote>
A few functions exist which generate and return these:<br>
</pre></div>
<p>
A few functions exist which generate and return these:
</p>
<ul>
<li>caml_ptr_val receives a c_obj and returns a void *. &nbsp;This
@ -397,19 +408,19 @@ enum_to_int and int_to_enum functions take an enum type label as an
argument. Example:
</p>
<blockquote><pre>
<div class="code"><pre>
%module enum_test
%{
enum c_enum_type { a = 1, b, c = 4, d = 8 };
%}
enum c_enum_type { a = 1, b, c = 4, d = 8 };
</pre></blockquote>
</pre></div>
<p>
The output mli contains:
</p>
<blockquote><pre>
<div class="code"><pre>
type c_enum_type = [
`unknown
| `c_enum_type
@ -424,9 +435,13 @@ type c_enum_tag = [
val int_to_enum c_enum_type -&gt; int -&gt; c_obj
val enum_to_int c_enum_type -&gt; c_obj -&gt; c_obj
</pre>
</blockquote>
</div>
<p>
So it's possible to do this:
<blockquote>
</p>
<div class="code">
<pre>
bash-2.05a$ ocamlmktop -custom enum_test_wrap.o enum_test.cmo -o enum_test_top
bash-2.05a$ ./enum_test_top
@ -440,11 +455,12 @@ val x : Enum_test.c_obj = C_enum `a
# int_to_enum `c_enum_type 4 ;;
- : Enum_test.c_obj = C_enum `c
</pre>
</blockquote>
</div>
<H4><a name="Ocaml_nn11"></a>22.2.2.1 Enum typing in Ocaml</H4>
<p>
The ocaml SWIG module now has support for loading and using multiple SWIG
modules at the same time. This enhances modularity, but presents problems
when used with a language which assumes that each module's types are complete
@ -452,6 +468,7 @@ at compile time. In order to achieve total soundness enum types are now
isolated per-module. The type issue matters when values are shared between
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>22.2.3 Arrays</H3>
@ -558,6 +575,7 @@ void printfloats( float *tab, int len );
<H3><a name="Ocaml_nn17"></a>22.2.4 C++ Classes</H3>
<p>
C++ classes, along with structs and unions are represented by C_obj
(string -&gt; c_obj -&gt; c_obj) wrapped closures. &nbsp;These objects
contain a method list, and a type, which allow them to be used like
@ -567,6 +585,7 @@ an object has is represented as a string in the object's method table,
and each method table exists in memory only once. &nbsp;In addition
to any other operators an object might have, certain builtin ones are
provided by SWIG: (all of these take no arguments (C_void))
</p>
<table summary="SWIG provided operators">
<tr><td>"~"</td><td>Delete this object</td></tr>
@ -589,18 +608,23 @@ Called with one argument, the member variable is set to the value of the
argument. With zero arguments, the value is returned.
</td></tr>
</table>
<p>
Note that this string belongs to the wrapper object, and not
the underlying pointer, so using create_[x]_from_ptr alters the
returned value for the same object.
</p>
<H4><a name="Ocaml_nn18"></a>22.2.4.1 STL vector and string Example</H4>
<p>
Standard typemaps are now provided for STL vector and string. More are in
the works. STL strings are passed just like normal strings, and returned
as strings. STL string references don't mutate the original string, (which
might be surprising), because Ocaml strings are mutable but have fixed
length. Instead, use multiple returns, as in the argout_ref example.
</p>
<table border="1" bgcolor="#dddddd" summary="STL vector and string example">
<tr><th><center>example.i</center></th></tr>
@ -632,7 +656,7 @@ after making a toplevel (make toplevel). This example uses the camlp4
module.
</p>
<blockquote><pre>
<div class="code"><pre>
bash-2.05a$ ./example_top
Objective Caml version 3.06
@ -669,12 +693,14 @@ bar
baz
- : unit = ()
#
</pre></blockquote>
</pre></div>
<H4><a name="Ocaml_nn19"></a>22.2.4.2 C++ Class Example</H4>
<p>
Here's a simple example using Trolltech's Qt Library:
</p>
<table border="1" bgcolor="#dddddd" summary="Qt Library example">
<tr><th><center>qt.i</center></th></tr>
@ -702,7 +728,7 @@ public:
<H4><a name="Ocaml_nn20"></a>22.2.4.3 Compiling the example</H4>
<blockquote><pre>
<div class="code"><pre>
bash-2.05a$ QTPATH=/your/qt/path
bash-2.05a$ for file in swig.mli swig.ml swigp4.ml ; do swig -ocaml -co $file ; done
bash-2.05a$ ocamlc -c swig.mli ; ocamlc -c swig.ml
@ -715,12 +741,12 @@ bash-2.05a$ ocamlc -c qt.ml
bash-2.05a$ ocamlmktop -custom swig.cmo -I `camlp4 -where` \
camlp4o.cma swigp4.cmo qt_wrap.o qt.cmo -o qt_top -cclib \
-L$QTPATH/lib -cclib -lqt
</pre></blockquote>
</pre></div>
<H4><a name="Ocaml_nn21"></a>22.2.4.4 Sample Session</H4>
<blockquote><pre>
<div class="code"><pre>
bash-2.05a$ ./qt_top
Objective Caml version 3.06
@ -737,7 +763,7 @@ val hello : Qt.c_obj = C_obj &lt;fun&gt;
# hello -&gt; show () ;;
- : Qt.c_obj = C_void
# a -&gt; exec () ;;
</pre></blockquote>
</pre></div>
<p>
Assuming you have a working installation of QT, you will see a window
@ -762,7 +788,7 @@ You can turn on director classes by using an optional module argument like
this:
</p>
<blockquote><pre>
<div class="code"><pre>
%module(directors="1")
...
@ -772,7 +798,7 @@ this:
class foo {
...
};
</pre></blockquote>
</pre></div>
<H4><a name="Ocaml_nn24"></a>22.2.5.2 Overriding Methods in Ocaml</H4>
@ -864,14 +890,17 @@ program in C++.
<H4><a name="Ocaml_nn26"></a>22.2.5.4 Creating director objects</H4>
<p>
The definition of the actual object triangle can be described this way:
<blockquote><pre>
</p>
<div class="code"><pre>
let triangle =
new_derived_object
new_shape
(triangle_class ((0.0,0.0),(0.5,1.0),(1.0,0.0)))
'()
</pre></blockquote>
</pre></div>
<p>
The first argument to <tt>new_derived_object</tt>, new_shape is the method
@ -952,9 +981,11 @@ values will read zero, and struct or object returns have undefined results.
<H3><a name="Ocaml_nn31"></a>22.2.6 Exceptions</H3>
<p>
Catching exceptions is now supported using SWIG's %exception feature. A simple
but not too useful example is provided by the throw_exception testcase in
Examples/test-suite. You can provide your own exceptions, too.
</p>
</body>
</html>

725
Doc/Manual/Perl5.html
View file

File diff suppressed because it is too large Load diff

115
Doc/Manual/Php.html
View file

@ -3,11 +3,13 @@
<html>
<head>
<title>SWIG and PHP4</title>
<link rel="stylesheet" type="text/css" href="style.css"/>
</head>
<body bgcolor="#ffffff">
<H1><a name="Php"></a>24 SWIG and PHP4</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="#Php_nn2">Preliminaries</a>
<li><a href="#Php_nn3">Building PHP4 Extensions</a>
@ -27,6 +29,7 @@
<li><a href="#Php_nn16">To be furthered...</a>
</ul>
</ul>
</div>
<!-- INDEX -->
@ -52,12 +55,14 @@ of in the generated .php file in php.
<H2><a name="Php_nn2"></a>24.1 Preliminaries</H2>
<p>
In order to use this module, you will need to have a copy of the PHP 4.0 (or
above) include files to compile the SWIG generated files. You can find these
files by running <tt>'php-config --includes'</tt>. To test the modules you will
need either the php binary or the Apache php module. If you want to build your
extension into php directly (without having the overhead of loading it into
each script), you will need the complete PHP source tree available.
</p>
<H2><a name="Php_nn3"></a>24.2 Building PHP4 Extensions</H2>
@ -66,9 +71,9 @@ each script), you will need the complete PHP source tree available.
To build a PHP4 extension, run swig using the <tt>-php4</tt> option as follows :
</p>
<blockquote><pre>
<div class="code"><pre>
swig -php4 example.i
</pre></blockquote>
</pre></div>
<p>
This will produce 3 files by default. The first file, <tt>example_wrap.c</tt>
@ -112,10 +117,10 @@ To build a dynamic module for PHP, you have two options. You can use the
To build manually, use a compile string similar to this (different for each
OS):
</p>
<blockquote><pre>
<div class="code"><pre>
cc -I.. $(PHPINC) -fpic -c example_wrap.c
cc -shared example_wrap.o -o libexample.so
</pre></blockquote>
</pre></div>
<p>
To build with phpize, after you have run swig you will need
@ -132,9 +137,9 @@ If you like SWIG can generate simple extra tests for libraries and header
files for you.
</p>
<blockquote><pre>
<div class="code"><pre>
swig -php4 -phpfull -withlibs "xapian omquery" --withincs "om.h"
</pre></blockquote>
</pre></div>
<p>
Will include in the config.m4 search for libxapian.a or libxapian.so and
@ -164,17 +169,23 @@ To test the extension from a PHP script, you need to load it first. You do
this by putting the line,
</p>
<blockquote><pre>
<div class="code"><pre>
dl("/path/to/modulename.so"); // Load the module
</pre></blockquote>
</pre></div>
<p>
at the start of each PHP file. SWIG also generates a php module, which
attempts to do the <tt>dl()</tt> call for you:
<blockquote><pre>
include("example.php");
</pre></blockquote>
</p>
<div class="code"><pre>
include("example.php");
</pre></div>
<p>
A more complicated method which builds the module directly into the <tt>php</tt>
executable is described <a href="n12">below</a>.
</p>
<H3><a name="Php_nn5"></a>24.2.2 Basic PHP4 interface</H3>
@ -187,23 +198,23 @@ C functions are converted into PHP functions. Default/optional arguments are
also allowed. An interface file like this :
</p>
<blockquote><pre>
<div class="code"><pre>
%module default
int foo(int a);
double bar(double, double b = 3.0);
...
</pre></blockquote>
</pre></div>
<p>
Will be accessed in PHP like this :
</p>
<blockquote><pre>
<div class="code"><pre>
dl("default.so"); $a = foo(2);
$b = bar(3.5, -1.5);
$c = bar(3.5); # Use default argument for 2nd parameter
</pre></blockquote>
</pre></div>
<H3><a name="Php_nn7"></a>24.2.4 Global Variables</H3>
@ -217,24 +228,24 @@ ensuring changes made in PHP are updated in C ( and vice versa. ) Because this
is handled for you, you can modify the variables in PHP as normal, e.g.
</p>
<blockquote><pre>
<div class="code"><pre>
%module example;
...
double seki = 2;
...
int example_func(void);
</pre></blockquote>
</pre></div>
<p>
is accessed as follow :
</p>
<blockquote><pre>
<div class="code"><pre>
dl("example.so");
print $seki;
$seki = $seki * 2; # Does not affect C variable, still equal to 2
example_func(); # Syncs C variable to PHP Variable, now both 4
</pre></blockquote>
</pre></div>
<p>
SWIG supports global variables of all C datatypes including pointers and complex
@ -262,7 +273,7 @@ or by passing a null or empty value.
For structures and classes, SWIG produces accessor fuction for each member function and data. For example :
</p>
<blockquote><pre>
<div class="code"><pre>
%module vector
class Vector {
@ -273,13 +284,13 @@ public:
double magnitude();
};
</pre></blockquote>
</pre></div>
<p>
This gets turned into the following collection of PHP functions :
</p>
<blockquote><pre>
<div class="code"><pre>
Vector_x_set($obj);
Vector_x_get($obj);
Vector_y_set($obj);
@ -290,10 +301,13 @@ new_Vector();
delete_Vector($obj);
Vector_magnitude($obj);
</pre></blockquote>
</pre></div>
<p>
To use the class, simply use these functions. However, SWIG also has a mechanism
for creating proxy classes that hides these functions and uses an object
oriented interface instead - see <a href="n7">below</a>
</p>
<H3><a name="Php_nn10"></a>24.2.7 Constants</H3>
@ -305,20 +319,20 @@ directive. These will then be available from your PHP script as a PHP constant,
(e.g. no dollar sign is needed to access them. ) For example, with a swig file like this,
</p>
<blockquote><pre>
<div class="code"><pre>
%module example
#define PI 3.14159
%constant int E = 2.71828
</pre>
</blockquote>
</div>
<p>
you can access from in your php script like this,
</p>
<blockquote><pre>
<div class="code"><pre>
dl("libexample.so");
echo "PI = " . PI . "\n";
@ -326,7 +340,7 @@ echo "PI = " . PI . "\n";
echo "E = " . E . "\n";
</pre>
</blockquote>
</div>
<p>
There are two peculiarities with using constants in PHP4. The first is that
@ -334,18 +348,18 @@ if you try to use an undeclared constant, it will evaulate to a string
set to the constants name. For example,
</p>
<blockquote><pre>
<div class="code"><pre>
%module example
#define EASY_TO_MISPELL 0
</pre>
</blockquote>
</div>
<p>
accessed incorrectly in PHP,
</p>
<blockquote>
<div class="code">
<pre>
dl("libexample.so");
@ -356,7 +370,7 @@ if(EASY_TO_MISPEL) {
}
</pre>
</blockquote>
</div>
<p>
will issue a warning about the undeclared constant, but will then evalute
@ -369,26 +383,26 @@ The second 'feature' is that although constants are case sensitive (by default),
you cannot declare a constant twice with alternative cases. E.g.,
</p>
<blockquote>
<div class="code">
<pre>
%module example
#define TEST Hello
#define Test World
</pre>
</blockquote>
</div>
<p>
accessed from PHP,
</p>
<blockquote>
<div class="code">
<pre>
dl("libexample.so");
echo TEST, Test;
</pre>
</blockquote>
</div>
<p>
will output "Hello Test" rather than "Hello World". This is because internally,
@ -417,9 +431,9 @@ can be be used directly in PHP scripts as objects and object methods. This is do
To have SWIG create proxy classes, use the <tt>-proxy</tt> option :
</p>
<blockquote><pre>
<div class="code"><pre>
% swig -php4 -proxy tbc.i
</pre></blockquote>
</pre></div>
<p>
This will produce the same files as before except that the final module
@ -473,11 +487,13 @@ when they each go out of scope.
<H3><a name="Php_nn13"></a>24.2.10 Static Member Variables</H3>
<p>
Class variables are not supported in PHP, however class functions are, using
'::' syntax. Static member variables are therefore accessed using a class
function with the same name, which returns the current value of the class variable. For example
</p>
<blockquote><pre>
<div class="code"><pre>
%module example
class Ko {
@ -485,38 +501,43 @@ class Ko {
...
};
</pre></blockquote>
</pre></div>
<p>
would be accessed in PHP as,
</p>
<blockquote><pre>
<div class="code"><pre>
dl("libexample.so");
echo "There has now been " . Ko::threats() . " threats\n";
</pre></blockquote>
</pre></div>
<p>
To set the static member variable, pass the value as the argument to the class function, e.g.
<blockquote><pre>
</p>
<div class="code"><pre>
Ko::threats(10);
echo "There has now been " . Ko::threats() . " threats\n";
</pre></blockquote>
</pre></div>
<H3><a name="Php_nn14"></a>24.2.11 PHP4 Pragmas</H3>
<p>
There are a few pragmas understood by the PHP4 module. The first,
<b>include</b> adds a file to be included by the generated PHP module. The
second, <b>code</b> adds literal code to the generated PHP module. The third,
<b>phpinfo</b> inserts code to the function called when PHP's phpinfo()
function is called.
</p>
<blockquote><pre>
<div class="code"><pre>
/* example.i */
%pragma(php4) include="foo.php"
@ -534,7 +555,7 @@ function is called.
"
%include "example.h"
</pre></blockquote>
</pre></div>
<H3><a name="Php_nn15"></a>24.2.12 Building extensions into php</H3>
@ -568,9 +589,9 @@ In most cases <tt>Makefile.in</tt> will be complete, especially if you
make use of <tt>-withlibs</tt> and <tt>-withincs</tt>
</p>
<blockquote><pre>
<div class="code"><pre>
swig -php4 -phpfull -withlibs "xapian omquery" --withincs "om.h"
</pre></blockquote>
</pre></div>
<p>
Will include in the config.m4 and Makefile.in search for libxapian.a or

78
Doc/Manual/Pike.html
View file

@ -2,11 +2,13 @@
<html>
<head>
<title>SWIG and Pike</title>
<link rel="stylesheet" type="text/css" href="style.css"/>
</head>
<body bgcolor="#ffffff">
<H1><a name="Pike"></a>25 SWIG and Pike</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="#Pike_nn2">Preliminaries</a>
<ul>
@ -24,6 +26,7 @@
<li><a href="#Pike_nn12">Static Members</a>
</ul>
</ul>
</div>
<!-- INDEX -->
@ -49,18 +52,29 @@ chapter.<br>
<H3><a name="Pike_nn3"></a>25.1.1 Running SWIG</H3>
<p>
Suppose that you defined a SWIG module such as the following:
<blockquote>
</p>
<div class="code">
<pre>%module example<br><br>%{<br>#include "example.h"<br>%}<br><br>int fact(int n);<br></pre>
</blockquote>
</div>
<p>
To build a C extension module for Pike, run SWIG using the <tt>-pike</tt> option :
<blockquote>
</p>
<div class="code">
<pre>$ <b>swig -pike example.i</b><br></pre>
</blockquote>
</div>
<p>
If you're building a C++ extension, be sure to add the <tt>-c++</tt> option:
<blockquote>
</p>
<div class="code">
<pre>$ <b>swig -c++ -pike example.i</b><br></pre>
</blockquote>
</div>
<p>
This creates a single source file named <tt>example_wrap.c</tt> (or <tt>example_wrap.cxx</tt>, if you
@ -77,9 +91,9 @@ of the wrapper file is <tt>example_wrap.c</tt>. To change this, you
can use the <tt>-o</tt> option:
</p>
<blockquote>
<div class="code">
<pre>$ <b>swig -pike -o pseudonym.c example.i</b><br></pre>
</blockquote>
</div>
<H3><a name="Pike_nn4"></a>25.1.2 Getting the right header files</H3>
@ -89,9 +103,9 @@ path to the Pike header files. These files are usually contained in a
directory such as
</p>
<blockquote>
<div class="code">
<pre>/usr/local/pike/7.4.10/include/pike<br></pre>
</blockquote>
</div>
<p>
There doesn't seem to be any way to get Pike itself to reveal the
@ -103,15 +117,17 @@ and so on.
<H3><a name="Pike_nn5"></a>25.1.3 Using your module</H3>
<p>
To use your module, simply use Pike's <tt>import</tt> statement:
</p>
<blockquote><pre>
<div class="code"><pre>
$ <b>pike</b>
Pike v7.4 release 10 running Hilfe v3.5 (Incremental Pike Frontend)
&gt; <b>import example;</b>
&gt; <b>fact(4);</b>
(1) Result: 24
</pre></blockquote>
</pre></div>
<H2><a name="Pike_nn6"></a>25.2 Basic C/C++ Mapping</H2>
@ -119,49 +135,59 @@ Pike v7.4 release 10 running Hilfe v3.5 (Incremental Pike Frontend)
<H3><a name="Pike_nn7"></a>25.2.1 Modules</H3>
<p>
All of the code for a given SWIG module is wrapped into a single Pike
module. Since the name of the shared library that implements your
module ultimately determines the module's name (as far as Pike is
concerned), SWIG's <tt>%module</tt> directive doesn't really have any
significance.
</p>
<H3><a name="Pike_nn8"></a>25.2.2 Functions</H3>
<p>
Global functions are wrapped as new Pike built-in functions. For
example,
</p>
<blockquote><pre>
<div class="code"><pre>
%module example
int fact(int n);
</pre></blockquote>
</pre></div>
<p>
creates a new built-in function <tt>example.fact(n)</tt> that works
exactly as you'd expect it to:
</p>
<blockquote><pre>
<div class="code"><pre>
&gt; <b>import example;</b>
&gt; <b>fact(4);</b>
(1) Result: 24
</pre></blockquote>
</pre></div>
<H3><a name="Pike_nn9"></a>25.2.3 Global variables</H3>
<p>
Global variables are currently wrapped as a pair of of functions, one to get
the current value of the variable and another to set it. For example, the
declaration
</p>
<blockquote><pre>
<div class="code"><pre>
%module example
double Foo;
</pre></blockquote>
</pre></div>
<p>
will result in two functions, <tt>Foo_get()</tt> and <tt>Foo_set()</tt>:
</p>
<blockquote><pre>
<div class="code"><pre>
&gt; <b>import example;</b>
&gt; <b>Foo_get();</b>
(1) Result: 3.000000
@ -169,43 +195,51 @@ will result in two functions, <tt>Foo_get()</tt> and <tt>Foo_set()</tt>:
(2) Result: 0
&gt; <b>Foo_get();</b>
(3) Result: 3.141590
</pre></blockquote>
</pre></div>
<H3><a name="Pike_nn10"></a>25.2.4 Constants and enumerated types</H3>
<p>
Enumerated types in C/C++ declarations are wrapped as Pike constants,
not as Pike enums.
</p>
<H3><a name="Pike_nn11"></a>25.2.5 Constructors and Destructors</H3>
<p>
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>25.2.6 Static Members</H3>
<p>
Since Pike doesn't support static methods or data for Pike classes, static
member functions in your C++ classes are wrapped as regular functions and
static member variables are wrapped as pairs of functions (one to get the
value of the static member variable, and another to set it). The names of
these functions are prepended with the name of the class.
For example, given this C++ class declaration:
</p>
<blockquote><pre>
<div class="code"><pre>
class Shape
{
public:
static void print();
static int nshapes;
};
</pre></blockquote>
</pre></div>
<p>
SWIG will generate a <tt>Shape_print()</tt> method that invokes the static
<tt>Shape::print()</tt> member function, as well as a pair of methods,
<tt>Shape_nshapes_get()</tt> and <tt>Shape_nshapes_set()</tt>, to get and set
the value of <tt>Shape::nshapes</tt>.
</p>
</body>
</html>

35
Doc/Manual/Preface.html
View file

@ -2,11 +2,13 @@
<html>
<head>
<title>Preface</title>
<link rel="stylesheet" type="text/css" href="style.css"/>
</head>
<body bgcolor="#ffffff">
<H1><a name="Preface"></a>1 Preface</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="#Preface_nn2">Introduction</a>
<li><a href="#Preface_nn3">Special Introduction for Version 1.3</a>
@ -19,6 +21,7 @@
<li><a href="#Preface_nn10">Credits</a>
<li><a href="#Preface_nn11">Bug reports</a>
</ul>
</div>
<!-- INDEX -->
@ -26,6 +29,7 @@
<H2><a name="Preface_nn2"></a>1.1 Introduction</H2>
<p>
SWIG (Simplified Wrapper and Interface Generator) is a software development tool for building scripting language
interfaces to C and C++ programs. Originally developed in 1995, SWIG was
first used by scientists in the Theoretical Physics Division at Los Alamos National Laboratory for
@ -37,6 +41,7 @@ interface provided a simple yet highly flexible foundation for solving these
types of problems. SWIG simplifies development by largely automating
the task of scripting language integration--allowing developers and users
to focus on more important problems.
</p>
<p>
Although SWIG was originally developed for scientific applications, it
@ -47,6 +52,7 @@ is involved.
<H2><a name="Preface_nn3"></a>1.2 Special Introduction for Version 1.3</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
@ -55,10 +61,12 @@ 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.
</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
@ -66,15 +74,18 @@ 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>
<p>
The official location of SWIG related material is
</p>
<blockquote><pre>
<div class="code"><pre>
<a href="http://www.swig.org">http://www.swig.org</a>
</pre></blockquote>
</pre></div>
<p>
This site contains the latest version of the software, users guide,
@ -85,9 +96,9 @@ implementation tricks.
You can also subscribe to the SWIG mailing list by visiting the page
</p>
<blockquote><pre>
<div class="code"><pre>
<a href="http://www.swig.org/mail.html">http://www.swig.org/mail.html</a>
</pre></blockquote>
</pre></div>
<p>
The mailing list often discusses some of the more technical aspects of
@ -99,9 +110,9 @@ CVS access to the latest version of SWIG is also available. More information
about this can be obtained at:
</p>
<blockquote><pre>
<div class="code"><pre>
<a href="http://www.swig.org/cvs.html">http://www.swig.org/cvs.html</a>
</pre></blockquote>
</pre></div>
<H2><a name="Preface_nn6"></a>1.5 Prerequisites</H2>
@ -132,6 +143,7 @@ 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>
<p>
The first few chapters of this manual describe SWIG in general and
provide an overview of its capabilities. The remaining chapters are
devoted to specific SWIG language modules and are self
@ -139,16 +151,19 @@ 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.
</p>
<H2><a name="Preface_nn8"></a>1.7 How to avoid reading the manual</H2>
<p>
If you hate reading manuals, glance at the "Introduction" which
contains a few simple examples. These
examples contain about 95% of everything you need to know to use
SWIG. After that, simply use the language-specific chapters as a reference.
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>
@ -180,11 +195,11 @@ This can be used in an interface file to define different typemaps, take
advantage of different features etc:
</p>
<blockquote><pre>
<div class="code"><pre>
#if SWIG_VERSION &gt;= 0x010311
/* Use some fancy new feature */
#endif
</pre></blockquote>
</pre></div>
<p>
Note: The version symbol is not defined in the generated SWIG
@ -194,12 +209,14 @@ wrapper file. The SWIG preprocessor has defined SWIG_VERSION since SWIG-1.3.11.
<H2><a name="Preface_nn10"></a>1.9 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, and John Lenz.
</p>
<p>
Historically, the following people contributed to early versions of SWIG.
@ -218,6 +235,7 @@ port.
<H2><a name="Preface_nn11"></a>1.10 Bug reports</H2>
<p>
Although every attempt has been made to make SWIG bug-free, we are also trying
to make feature improvements that may introduce bugs.
To report a bug, either send mail to the SWIG developer
@ -227,6 +245,7 @@ possible, including (if applicable), error messages, tracebacks (if a
core dump occurred), corresponding portions of the SWIG interface file
used, and any important pieces of the SWIG generated wrapper code. We
can only fix bugs if we know about them.
</p>
</body>
</html>

98
Doc/Manual/Preprocessor.html
View file

@ -2,11 +2,13 @@
<html>
<head>
<title>SWIG Preprocessor</title>
<link rel="stylesheet" type="text/css" href="style.css"/>
</head>
<body bgcolor="#ffffff">
<H1><a name="Preprocessor"></a>7 Preprocessing</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="#Preprocessor_nn2">File inclusion</a>
<li><a href="#Preprocessor_nn3">File imports</a>
@ -18,30 +20,37 @@
<li><a href="#Preprocessor_nn9">Preprocessing and { ... }</a>
<li><a href="#Preprocessor_nn10">Viewing preprocessor output</a>
</ul>
</div>
<!-- INDEX -->
<p>
SWIG includes its own enhanced version of the C preprocessor. The preprocessor
supports the standard preprocessor directives and macro expansion rules.
However, a number of modifications and enhancements have been made. This
chapter describes some of these modifications.
</p>
<H2><a name="Preprocessor_nn2"></a>7.1 File inclusion</H2>
<p>
To include another file into a SWIG interface, use the <tt>%include</tt> directive
like this:
</p>
<blockquote>
<div class="code">
<pre>
%include "pointer.i"
</pre>
</blockquote>
</div>
<p>
Unlike, <tt>#include</tt>, <tt>%include</tt> includes each file once (and will not
reload the file on subsequent <tt>%include</tt> declarations). Therefore, it
is not necessary to use include-guards in SWIG interfaces.
</p>
<p>
By default, the <tt>#include</tt> is ignored unless you run SWIG with the
@ -52,15 +61,18 @@ in standard header system headers and auxilliary files.
<H2><a name="Preprocessor_nn3"></a>7.2 File imports</H2>
<p>
SWIG provides another file inclusion directive with the <tt>%import</tt> directive.
For example:
</p>
<blockquote>
<div class="code">
<pre>
%import "foo.i"
</pre>
</blockquote>
</div>
<p>
The purpose of <tt>%import</tt> is to collect certain information from another
SWIG interface file or a header file without actually generating any wrapper code.
Such information generally includes type declarations (e.g., <tt>typedef</tt>) as well as
@ -68,6 +80,7 @@ C++ classes that might be used as base-classes for class declarations in the int
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.
</p>
<P>
The <tt>-importall</tt> directive tells SWIG to follow all <tt>#include</tt> statements
@ -84,7 +97,7 @@ include parts of an interface. The following symbols are predefined
by SWIG when it is parsing the interface:
</p>
<blockquote><pre>
<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
@ -108,18 +121,20 @@ SWIGSEXP Defined when using S-expressions
SWIGTCL Defined when using Tcl
SWIGTCL8 Defined when using Tcl8.0
SWIGXML Defined when using XML
</pre></blockquote>
</pre></div>
<p>
In addition, SWIG defines the following set of standard C/C++ macros:
</p>
<blockquote>
<div class="code">
<pre>
__LINE__ Current line number
__FILE__ Current file name
__STDC__ Defined to indicate ANSI C
__cplusplus Defined when -c++ option used
</pre>
</blockquote>
</div>
<p>
Interface files can look at these symbols as necessary to change the
@ -132,24 +147,29 @@ within the SWIG compiler).
<H2><a name="Preprocessor_nn5"></a>7.4 Macro Expansion</H2>
<p>
Traditional preprocessor macros can be used in SWIG interfaces. Be aware that the <tt>#define</tt> statement
is also used to try and detect constants. Therefore, if you have something like this in your file,
</p>
<blockquote>
<div class="code">
<pre>
#ifndef _FOO_H 1
#define _FOO_H 1
...
#endif
</pre>
</blockquote>
</div>
<p>
you may get some extra constants such as <tt>_FOO_H</tt> showing up in the scripting interface.
</p>
<p>
More complex macros can be defined in the standard way. For example:
</p>
<blockquote>
<div class="code">
<pre>
#define EXTERN extern
#ifdef __STDC__
@ -158,9 +178,11 @@ More complex macros can be defined in the standard way. For example:
#define _ANSI(args) ()
#endif
</pre>
</blockquote>
</div>
<p>
The following operators can appear in macro definitions:
</p>
<ul>
<li><tt>#x</tt><br>
@ -180,10 +202,12 @@ like <tt>#x</tt>. This is a non-standard SWIG extension.
<H2><a name="Preprocessor_nn6"></a>7.5 SWIG Macros</H2>
<p>
SWIG provides an enhanced macro capability with the <tt>%define</tt> and <tt>%enddef</tt> directives.
For example:
</p>
<blockquote>
<div class="code">
<pre>
%define ARRAYHELPER(type,name)
%inline %{
@ -205,13 +229,15 @@ void name ## _set(type *t, int index, type val) {
ARRAYHELPER(int, IntArray)
ARRAYHELPER(double, DoubleArray)
</pre>
</blockquote>
</div>
<p>
The primary purpose of <tt>%define</tt> is to define large macros of code. Unlike normal C preprocessor
macros, it is not necessary to terminate each line with a continuation character (\)--the macro definition
extends to the first occurrence of <tt>%enddef</tt>. Furthermore, when such macros are expanded,
they are reparsed through the C preprocessor. Thus, SWIG macros can contain all other preprocessor
directives except for nested <tt>%define</tt> statements.
</p>
<p>
The SWIG macro capability is a very quick and easy way to generate large amounts of code. In fact,
@ -222,58 +248,68 @@ support).
<H2><a name="Preprocessor_nn7"></a>7.6 C99 and GNU Extensions</H2>
<p>
SWIG-1.3.12 and newer releases support variadic preprocessor macros. For example:
</p>
<blockquote>
<div class="code">
<pre>
#define DEBUGF(fmt,...) fprintf(stderr,fmt,__VA_ARGS__)
</pre>
</blockquote>
</div>
<p>
When used, any extra arguments to <tt>...</tt> are placed into the
special variable <tt>__VA_ARGS__</tt>. This also works with special SWIG
macros defined using <tt>%define</tt>.
</p>
<p>
SWIG allows a variable number of arguments to be empty. However, this often results
in an extra comma (,) and syntax error in the resulting expansion. For example:
</p>
<blockquote>
<div class="code">
<pre>
DEBUGF("hello"); --&gt; fprintf(stderr,"hello",);
</pre>
</blockquote>
</div>
<p>
To get rid of the extra comma, use <tt>##</tt> like this:
</p>
<blockquote>
<div class="code">
<pre>
#define DEBUGF(fmt,...) fprintf(stderr,fmt, ##__VA_ARGS__)
</pre>
</blockquote>
</div>
<p>
SWIG also supports GNU-style variadic macros. For example:
</p>
<blockquote>
<div class="code">
<pre>
#define DEBUGF(fmt, args...) fprintf(stdout,fmt,args)
</pre>
</blockquote>
</div>
<p>
<b>Comment:</b> It's not entirely clear how variadic macros might be useful to
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 %{ ... %} blocks</H2>
<p>
The SWIG preprocessor does not process any text enclosed in a code block %{ ... %}. Therefore,
if you write code like this,
</p>
<blockquote>
<div class="code">
<pre>
%{
#ifdef NEED_BLAH
@ -283,19 +319,23 @@ int blah() {
#endif
%}
</pre>
</blockquote>
</div>
<p>
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 { ... }</H2>
<p>
SWIG always runs the preprocessor on text appearing inside <tt>{ ... }</tt>. However,
sometimes it is desirable to make a preprocessor directive pass through to the output
file. For example:
</p>
<blockquote>
<div class="code">
<pre>
%extend Foo {
void bar() {
@ -305,12 +345,14 @@ file. For example:
}
}
</pre>
</blockquote>
</div>
<p>
By default, SWIG will interpret the <tt>#ifdef DEBUG</tt> statement. However, if you really wanted that code
to actually go into the wrapper file, prefix the preprocessor directives with <tt>%</tt> like this:
</p>
<blockquote>
<div class="code">
<pre>
%extend Foo {
void bar() {
@ -320,7 +362,7 @@ to actually go into the wrapper file, prefix the preprocessor directives with <t
}
}
</pre>
</blockquote>
</div>
<p>
SWIG will strip the extra <tt>%</tt> and leave the preprocessor directive in the code.

1171
Doc/Manual/Python.html
View file

File diff suppressed because it is too large Load diff

14
Doc/Manual/README
View file

@ -5,3 +5,17 @@ and the table of contents is generated automatically by the 'maketoc.py'
script. The Makefile has further information on how the various alternative
forms of the documentation is generated from the hand-written HTML.
There are 4 types of boxes that code or whatever can be inside:
- <div class="shell">...</div>
This is for text that shows the output of running commands on the shell.
- <div class="code">...</div>
This is for either C, C++, or SWIG code
- <div class="targetlang">...</div>
This is for code in a target scripting language
- <div class="diagram">...</div>
This is for text that is not code or a shell
The general format is
<div class="foo"><pre>
whatever here
</pre></div>

1378
Doc/Manual/Ruby.html
View file

File diff suppressed because it is too large Load diff

704
Doc/Manual/SWIG.html
View file

File diff suppressed because it is too large Load diff

1107
Doc/Manual/SWIGPlus.html
View file

File diff suppressed because it is too large Load diff

93
Doc/Manual/Scripting.html
View file

@ -2,11 +2,13 @@
<html>
<head>
<title>Scripting Languages</title>
<link rel="stylesheet" type="text/css" href="style.css"/>
</head>
<body bgcolor="#ffffff">
<H1><a name="Scripting"></a>4 Scripting Languages</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="#Scripting_nn2">The two language view of the world</a>
<li><a href="#Scripting_nn3">How does a scripting language talk to C?</a>
@ -24,13 +26,16 @@
<li><a href="#Scripting_nn12">Static linking</a>
</ul>
</ul>
</div>
<!-- INDEX -->
<p>
This chapter provides a brief overview of scripting language extension
programming and the mechanisms by which scripting language interpreters
access C and C++ code.
</p>
<H2><a name="Scripting_nn2"></a>4.1 The two language view of the world</H2>
@ -66,6 +71,7 @@ arrays. </p>
<H2><a name="Scripting_nn3"></a>4.2 How does a scripting language talk to C?</H2>
<p>
Scripting languages are built around a parser that knows how
to execute commands and scripts. Within this parser, there is a
mechanism for executing commands and accessing variables.
@ -75,6 +81,7 @@ possible to add new commands and variables. To do this,
most languages define a special API for adding new commands.
Furthermore, a special foreign function interface defines how these
new commands are supposed to hook into the interpreter.
</p>
<p>
Typically, when you add a new command to a scripting interpreter
@ -92,12 +99,12 @@ the process.
<p>
Suppose you have an ordinary C function like this :</p>
<blockquote><pre>
<div class="code"><pre>
int fact(int n) {
if (n &lt;= 1) return 1;
else return n*fact(n-1);
}
</pre></blockquote>
</pre></div>
<p>
In order to access this function from a scripting language, it is
@ -115,7 +122,7 @@ wrapper function must do three things :</p>
As an example, the Tcl wrapper function for the <tt>fact()</tt>
function above example might look like the following : </p>
<blockquote><pre>
<div class="code"><pre>
int wrap_fact(ClientData clientData, Tcl_Interp *interp,
int argc, char *argv[]) {
int result;
@ -130,7 +137,7 @@ int wrap_fact(ClientData clientData, Tcl_Interp *interp,
return TCL_OK;
}
</pre></blockquote>
</pre></div>
<p>
Once you have created a wrapper function, the final step is to tell the
@ -139,13 +146,13 @@ initialization function called by the language when the module is
loaded. For example, adding the above function to the Tcl interpreter
requires code like the following :</p>
<blockquote><pre>
<div class="code"><pre>
int Wrap_Init(Tcl_Interp *interp) {
Tcl_CreateCommand(interp, "fact", wrap_fact, (ClientData) NULL,
(Tcl_CmdDeleteProc *) NULL);
return TCL_OK;
}
</pre></blockquote>
</pre></div>
<p>
When executed, Tcl will now have a new command called "<tt>fact</tt>"
@ -167,17 +174,17 @@ C/C++ global variable to a variable in the scripting
language interpeter. For example, suppose you had the following
variable:</p>
<blockquote><pre>
<div class="code"><pre>
double Foo = 3.5;
</pre></blockquote>
</pre></div>
<p>
It might be nice to access it from a script as follows (shown for Perl):</p>
<blockquote><pre>
<div class="code"><pre>
$a = $Foo * 2.3; # Evaluation
$Foo = $a + 2.0; # Assignment
</pre></blockquote>
</pre></div>
<p>
To provide such access, variables are commonly manipulated using a
@ -197,24 +204,28 @@ the value.
<H3><a name="Scripting_nn6"></a>4.2.3 Constants</H3>
<p>
In many cases, a C program or library may define a large collection of
constants. For example:
</p>
<blockquote><pre>
<div class="code"><pre>
#define RED 0xff0000
#define BLUE 0x0000ff
#define GREEN 0x00ff00
</pre></blockquote>
</pre></div>
<p>
To make constants available, their values can be stored in scripting
language variables such as <tt>$RED</tt>, <tt>$BLUE</tt>, and
<tt>$GREEN</tt>. Virtually all scripting languages provide C
functions for creating variables so installing constants is usually
a trivial exercise.
</p>
<H3><a name="Scripting_nn7"></a>4.2.4 Structures and classes</H3>
<p>
Although scripting languages have no trouble accessing simple
functions and variables, accessing C/C++ structures and classes
present a different problem. This is because the implementation
@ -222,6 +233,7 @@ of structures is largely related to the problem of
data representation and layout. Furthermore, certain language features
are difficult to map to an interpreter. For instance, what
does C++ inheritance mean in a Perl interface?
</p>
<p>
The most straightforward technique for handling structures is to
@ -229,17 +241,20 @@ implement a collection of accessor functions that hide the underlying
representation of a structure. For example,
</p>
<blockquote><pre>
<div class="code"><pre>
struct Vector {
Vector();
~Vector();
double x,y,z;
};
</pre></blockquote>
can be transformed into the following set of functions :
</pre></div>
<blockquote><pre>
<p>
can be transformed into the following set of functions :
</p>
<div class="code"><pre>
Vector *new_Vector();
void delete_Vector(Vector *v);
double Vector_x_get(Vector *v);
@ -249,17 +264,18 @@ void Vector_x_set(Vector *v, double x);
void Vector_y_set(Vector *v, double y);
void Vector_z_set(Vector *v, double z);
</pre></blockquote>
</pre></div>
<p>
Now, from an interpreter these function might be used as follows:
</p>
<blockquote><pre>
<div class="code"><pre>
% set v [new_Vector]
% Vector_x_set $v 3.5
% Vector_y_get $v
% delete_Vector $v
% ...
</pre></blockquote>
</pre></div>
<p>
Since accessor functions provide a mechanism for accessing the
@ -279,47 +295,48 @@ that looks like the original structure (that is, it proxies the real
C++ class). For example, if you
have the following C definition :</p>
<blockquote><pre>
<div class="code"><pre>
class Vector {
public:
Vector();
~Vector();
double x,y,z;
};
</pre></blockquote>
</pre></div>
<p>
A proxy classing mechanism would allow you to access the structure in
a more natural manner from the interpreter. For example, in Python, you might want to do this:
</p>
<blockquote><pre>
<div class="code"><pre>
&gt;&gt;&gt; v = Vector()
&gt;&gt;&gt; v.x = 3
&gt;&gt;&gt; v.y = 4
&gt;&gt;&gt; v.z = -13
&gt;&gt;&gt; ...
&gt;&gt;&gt; del v
</pre></blockquote>
</pre></div>
<p>
Similarly, in Perl5 you may want the interface to work like this:</p>
<blockquote><pre>
<div class="code"><pre>
$v = new Vector;
$v-&gt;{x} = 3;
$v-&gt;{y} = 4;
$v-&gt;{z} = -13;
</pre></blockquote>
</pre></div>
<p>
Finally, in Tcl :
</p>
<blockquote><pre>
<div class="code"><pre>
Vector v
v configure -x 3 -y 4 -z 13
</pre></blockquote>
</pre></div>
<p>
When proxy classes are used, two objects are at really work--one in
@ -349,7 +366,7 @@ To create a shared library or DLL, you often need to look at the
manual pages for your compiler and linker. However, the procedure
for a few common machines is shown below:</p>
<blockquote><pre>
<div class="code"><pre>
# Build a shared library for Solaris
gcc -c example.c example_wrap.c -I/usr/local/include
ld -G example.o example_wrap.o -o example.so
@ -362,7 +379,7 @@ gcc -shared example.o example_wrap.o -o example.so
gcc -c example.c example_wrap.c -I/usr/local/include
ld -shared example.o example_wrap.o -o example.so
</pre></blockquote>
</pre></div>
<p>
To use your shared library, you simply use the corresponding command
@ -370,12 +387,12 @@ in the scripting language (load, import, use, etc...). This will
import your module and allow you to start using it. For example:
</p>
<blockquote><pre>
<div class="code"><pre>
% load ./example.so
% fact 4
24
%
</pre></blockquote>
</pre></div>
<p>
When working with C++ codes, the process of building shared libraries
@ -384,9 +401,9 @@ additional code in order to operate correctly. On many machines, you
can build a shared C++ module by following the above procedures, but
changing the link line to the following :</p>
<blockquote><pre>
<div class="code"><pre>
c++ -shared example.o example_wrap.o -o example.so
</pre></blockquote>
</pre></div>
<H3><a name="Scripting_nn11"></a>4.3.2 Linking with shared libraries</H3>
@ -398,7 +415,7 @@ order for the extension to work, it needs to be able to find all of
these libraries at run-time. Otherwise, you may get an error such as
the following :</p>
<blockquote><pre>
<div class="code"><pre>
&gt;&gt;&gt; import graph
Traceback (innermost last):
File "&lt;stdin&gt;", line 1, in ?
@ -408,7 +425,7 @@ ImportError: 1101:/home/sci/data1/beazley/bin/python: rld: Fatal Error: cannot
successfully map soname 'libgraph.so' under any of the filenames /usr/lib/libgraph.so:/
lib/libgraph.so:/lib/cmplrs/cc/libgraph.so:/usr/lib/cmplrs/cc/libgraph.so:
&gt;&gt;&gt;
</pre></blockquote>
</pre></div>
<p>
What this error means is that the extension module created by SWIG

933
Doc/Manual/Tcl.html
View file

File diff suppressed because it is too large Load diff

951
Doc/Manual/Typemaps.html
View file

File diff suppressed because it is too large Load diff

188
Doc/Manual/Varargs.html
View file

@ -2,11 +2,13 @@
<html>
<head>
<title>Variable Length Arguments</title>
<link rel="stylesheet" type="text/css" href="style.css"/>
</head>
<body bgcolor="#ffffff">
<H1><a name="Varargs"></a>13 Variable Length Arguments</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="#Varargs_nn2">Introduction</a>
<li><a href="#Varargs_nn3">The Problem</a>
@ -18,11 +20,14 @@
<li><a href="#Varargs_nn9">C++ Issues</a>
<li><a href="#Varargs_nn10">Discussion</a>
</ul>
</div>
<!-- INDEX -->
<p>
<b>(a.k.a, "The horror. The horror.")</b>
</p>
<p>
This chapter describes the problem of wrapping functions that take a
@ -40,30 +45,36 @@ wisely chosen to avoid this issue.
<H2><a name="Varargs_nn2"></a>13.1 Introduction</H2>
<p>
Some C and C++ programs may include functions that accept a variable
number of arguments. For example, most programmers are
familiar with functions from the C library such as the following:
</p>
<blockquote>
<div class="code">
<pre>
int printf(const char *fmt, ...)
int fprintf(FILE *, const char *fmt, ...);
int sprintf(char *s, const char *fmt, ...);
</pre>
</blockquote>
</div>
<p>
Although there is probably little practical purpose in wrapping these
specific C library functions in a scripting language (what would be the
point?), a library may include its own set of special functions based
on a similar API. For example:
</p>
<blockquote>
<div class="code">
<pre>
int traceprintf(const char *fmt, ...);
</pre>
</blockquote>
</div>
<p>
In this case, you may want to have some kind of access from the target language.
</p>
<p>
Before describing the SWIG implementation, it is important to discuss
@ -77,7 +88,7 @@ NULL-terminated list of pointers. A good example of this would
be a function like this:
</p>
<blockquote>
<div class="code">
<pre>
int execlp(const char *path, const char *arg1, ...);
...
@ -85,14 +96,16 @@ int execlp(const char *path, const char *arg1, ...);
/* Example */
execlp("ls","ls","-l",NULL);
</pre>
</blockquote>
</div>
<p>
In addition, varargs is sometimes used to fake default arguments in older
C libraries. For instance, the low level <tt>open()</tt> system call
is often declared as a varargs function so that it will accept two
or three arguments:
</p>
<blockquote>
<div class="code">
<pre>
int open(const char *path, int oflag, ...);
...
@ -101,13 +114,15 @@ int open(const char *path, int oflag, ...);
f = open("foo", O_RDONLY);
g = open("bar", O_WRONLY | O_CREAT, 0644);
</pre>
</blockquote>
</div>
<p>
Finally, to implement a varargs function, recall that you have to use
the C library functions defined in <tt>&lt;stdarg.h&gt;</tt>. For
example:
</p>
<blockquote>
<div class="code">
<pre>
List make_list(const char *s, ...) {
va_list ap;
@ -122,17 +137,19 @@ List make_list(const char *s, ...) {
return x;
}
</pre>
</blockquote>
</div>
<H2><a name="Varargs_nn3"></a>13.2 The Problem</H2>
<p>
Generating wrappers for a variable length argument function presents a
number of special challenges. Although C provides support for
implementing functions that receive variable length arguments, there
are no functions that can go in the other direction. Specifically,
you can't write a function that dynamically creates a list of
arguments and which invokes a varargs function on your behalf.
</p>
<p>
Although it is possible to write functions that accept the special
@ -147,25 +164,27 @@ The reason this doesn't work has to do with the way that function
calls get compiled. For example, suppose that your program has a function call like this:
</p>
<blockquote>
<div class="code">
<pre>
printf("Hello %s. Your number is %d\n", name, num);
</pre>
</blockquote>
</div>
<p>
When the compiler looks at this, it knows that you are calling
<tt>printf()</tt> with exactly three arguments. Furthermore, it knows
that the number of arguments as well are their types and sizes is
<em>never</em> going to change during program execution. Therefore,
this gets turned to machine code that sets up a three-argument stack
frame followed by a call to <tt>printf()</tt>.
</p>
<p>
In contrast, suppose you attempted to make some kind of wrapper around
<tt>printf()</tt> using code like this:
</p>
<blockquote>
<div class="code">
<pre>
int wrap_printf(const char *fmt, ...) {
va_list ap;
@ -176,14 +195,16 @@ int wrap_printf(const char *fmt, ...) {
va_end(ap);
};
</pre>
</blockquote>
</div>
<p>
Athough this code might compile, it won't do what you expect. This is
because the call to <tt>printf()</tt> is compiled as a procedure call
involving only two arguments. However, clearly a two-argument
configuration of the call stack is completely wrong if your intent is
to pass an arbitrary number of arguments to the real
<tt>printf()</tt>. Needless to say, it won't work.
</p>
<p>
Unfortunately, the situation just described is exactly the problem
@ -214,84 +235,102 @@ are willing to get hands dirty. Keep reading.
<H2><a name="Varargs_nn4"></a>13.3 Default varargs support</H2>
<p>
When variable length arguments appear in an interface, the default
behavior is to drop the variable argument list entirely, replacing
them with a single NULL pointer. For example, if you had this
function,
</p>
<blockquote>
<div class="code">
<pre>
void traceprintf(const char *fmt, ...);
</pre>
</blockquote>
</div>
<p>
it would be wrapped as if it had been declared as follows:
</p>
<blockquote>
<div class="code">
<pre>
void traceprintf(const char *fmt);
</pre>
</blockquote>
</div>
<p>
When the function is called inside the wrappers, it is called as follows:
</p>
<blockquote>
<div class="code">
<pre>
traceprintf(arg1, NULL);
</pre>
</blockquote>
</div>
<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):
</p>
<blockquote>
<div class="code">
<pre>
&gt;&gt;&gt; traceprintf("Hello World")
&gt;&gt;&gt; traceprintf("Hello %s. Your number is %d\n" % (name, num))
</pre>
</blockquote>
</div>
<p>
Notice how string formatting is being done in Python instead of C.
</p>
<H2><a name="Varargs_nn5"></a>13.4 Argument replacement using %varargs</H2>
<p>
Instead of dropping the variable length arguments, an alternative approach is to replace
<tt>(...)</tt> with a set of suitable arguments. SWIG provides a special <tt>%varargs</tt> directive
that can be used to do this. For example,
</p>
<blockquote>
<div class="code">
<pre>
%varargs(int mode = 0) open;
...
int open(const char *path, int oflags, ...);
</pre>
</blockquote>
</div>
<p>
is equivalent to this:
</p>
<blockquote>
<div class="code">
<pre>
int open(const char *path, int oflags, int mode = 0);
</pre>
</blockquote>
</div>
<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
accept a numerical argument count as follows:
</p>
<blockquote>
<div class="code">
<pre>
%varargs(10,char *arg = NULL) execlp;
...
int execlp(const char *path, const char *arg1, ...);
</pre>
</blockquote>
</div>
<p>
This would wrap <tt>execlp()</tt> as a function that accepted up to 10 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
@ -311,9 +350,11 @@ wrappers to such functions presents special problems (covered shortly).
<H2><a name="Varargs_nn6"></a>13.5 Varargs and typemaps</H2>
<p>
Variable length arguments may be used in typemap specifications. For example:
</p>
<blockquote>
<div class="code">
<pre>
%typemap(in) (...) {
// Get variable length arguments (somehow)
@ -324,8 +365,9 @@ Variable length arguments may be used in typemap specifications. For example:
// Multi-argument typemap
}
</pre>
</blockquote>
</div>
<p>
However, this immediately raises the question of what "type" is actually used
to represent <tt>(...)</tt>. For lack of a better alternative, the type of
<tt>(...)</tt> is set to <tt>void *</tt>. Since there is no
@ -334,11 +376,13 @@ the <tt>void *</tt> argument value is intended to serve as a place holder
for storing some kind of information about the extra arguments (if any). In addition, the
default behavior of SWIG is to pass the <tt>void *</tt> value as an argument to
the function. Therefore, you could use the pointer to hold a valid argument value if you wanted.
</p>
<p>
To illustrate, here is a safer version of wrapping <tt>printf()</tt> in Python:
</p>
<blockquote>
<div class="code">
<pre>
%typemap(in) (const char *fmt, ...) {
$1 = "%s"; /* Fix format string to %s */
@ -347,16 +391,18 @@ To illustrate, here is a safer version of wrapping <tt>printf()</tt> in Python:
...
int printf(const char *fmt, ...);
</pre>
</blockquote>
</div>
<p>
In this example, the format string is implicitly set to <tt>"%s"</tt>.
This prevents a program from passing a bogus format string to the
extension. Then, the passed input object is decoded and placed in the
<tt>void *</tt> argument defined for the <tt>(...)</tt> argument. When the
actual function call is made, the underlying wrapper code will look roughly
like this:
</p>
<blockquote>
<div class="code">
<pre>
wrap_printf() {
char *arg1;
@ -370,10 +416,12 @@ wrap_printf() {
...
}
</pre>
</blockquote>
</div>
<p>
Notice how both arguments are passed to the function and it does what you
would expect.
</p>
<p>
The next example illustrates a more advanced kind of varargs typemap.
@ -394,7 +442,7 @@ instead of using <tt>%varargs</tt>, you might first write a typemap
like this:
</p>
<blockquote>
<div class="code">
<pre>
%typemap(in) (...)(char *args[10]) {
int i;
@ -416,8 +464,9 @@ like this:
$1 = (void *) args;
}
</pre>
</blockquote>
</div>
<p>
In this typemap, the special variable <tt>varargs</tt> is a tuple
holding all of the extra arguments passed (this is specific to the
Python module). The typemap then pulls this apart and sticks the
@ -428,8 +477,9 @@ is only half of the picture----clearly this alone is not enough to
make the function work. To patch everything up, you have to rewrite the
underlying action code using the <tt>%feature</tt> directive like
this:
</p>
<blockquote>
<div class="code">
<pre>
%feature("action") execlp {
char *args = (char **) arg3;
@ -439,7 +489,7 @@ this:
int execlp(const char *path, const char *arg, ...);
</pre>
</blockquote>
</div>
<p>
This patches everything up and creates a function that more or less
@ -452,6 +502,7 @@ security, continue to the next section.
<H2><a name="Varargs_nn7"></a>13.6 Varargs wrapping with libffi</H2>
<p>
All of the previous examples have relied on features of SWIG that are
portable and which don't rely upon any low-level machine-level
details. In many ways, they have all dodged the real issue of variable
@ -459,6 +510,7 @@ length arguments by recasting a varargs function into some weaker variation
with a fixed number of arguments of known types. In many cases, this
works perfectly fine. However, if you want more generality than this,
you need to bring out some bigger guns.
</p>
<p>
One way to do this is to use a special purpose library such as libffi
@ -477,7 +529,7 @@ arguments. To do this, you might make a few adjustments to the previous
example. For example:
</p>
<blockquote>
<div class="code">
<pre>
/* Take an arbitrary number of extra arguments and place into an array
of strings */
@ -547,19 +599,21 @@ example. For example:
/* Declare the function. Whew! */
int execlp(const char *path, const char *arg1, ...);
</pre>
</blockquote>
</div>
<p>
Looking at this example, you may start to wonder if SWIG is making
life any easier. Given the amount of code involved, you might also wonder
why you didn't just write a hand-crafted wrapper! Either that or you're wondering
"why in the hell am I trying to wrap this varargs function in the
first place?!?" Obviously, those are questions you'll have to answer for yourself.
</p>
<p>
As a more extreme example of libffi, here is some code that attempts to wrap <tt>printf()</tt>,
</p>
<blockquote>
<div class="code">
<pre>
/* A wrapper for printf() using libffi */
@ -662,47 +716,56 @@ As a more extreme example of libffi, here is some code that attempts to wrap <tt
/* The function */
int printf(const char *fmt, ...);
</pre>
</blockquote>
</div>
<p>
Much to your amazement, it even seems to work if you try it:
</p>
<blockquote>
<div class="code">
<pre>
&gt;&gt;&gt; import example
&gt;&gt;&gt; example.printf("Grade: %s %d/60 = %0.2f%%\n", "Dave", 47, 47.0*100/60)
Grade: Dave 47/60 = 78.33%
&gt;&gt;&gt;
</pre>
</blockquote>
</div>
<p>
Of course, there are still some limitations to consider:
</p>
<blockquote>
<div class="code">
<pre>
&gt;&gt;&gt; example.printf("la de da de da %s", 42)
Segmentation fault (core dumped)
</pre>
</blockquote>
</div>
<p>
And, on this note, we leave further exploration of libffi to the reader as an exercise. Although Python has been used as an example,
most of the techniques in this section can be extrapolated to other language modules with a bit of work. The only
details you need to know is how the extra arguments are accessed in each target language. For example, in the Python
module, we used the special <tt>varargs</tt> variable to get these arguments. Modules such as Tcl8 and Perl5 simply
provide an argument number for the first extra argument. This can be used to index into an array of passed arguments to get
values. Please consult the chapter on each language module for more details.
</p>
<H2><a name="Varargs_nn8"></a>13.7 Wrapping of va_list</H2>
<p>
Closely related to variable length argument wrapping, you may encounter functions that accept a parameter
of type <tt>va_list</tt>. For example:
</p>
<blockquote>
<div class="code">
<pre>
int vfprintf(FILE *f, const char *fmt, va_list ap);
</pre>
</blockquote>
</div>
<p>
As far as we know, there is no obvious way to wrap these functions
with SWIG. This is because there is no documented way to assemble the
proper va_list structure (there are no C library functions to do it
@ -710,16 +773,19 @@ and the contents of va_list are opaque). Not only that, the contents
of a <tt>va_list</tt> structure are closely tied to the underlying
call-stack. It's not clear that exporting a <tt>va_list</tt> would
have any use or that it would work at all.
</p>
<H2><a name="Varargs_nn9"></a>13.8 C++ Issues</H2>
<p>
Wrapping of C++ member functions that accept a variable number of
arguments presents a number of challenges. By far, the easiest way to
handle this is to use the <tt>%varargs</tt> directive. This is portable
and it fully supports classes much like the <tt>%rename</tt> directive. For example:
</p>
<blockquote>
<div class="code">
<pre>
%varargs (10, char * = NULL) Foo::bar;
@ -733,10 +799,12 @@ public:
virtual void bar(char *arg, ...); // gets varargs above
};
</pre>
</blockquote>
</div>
<p>
<tt>%varargs</tt> also works with constructors, operators, and any
other C++ programming construct that accepts variable arguments.
</p>
<p>
Doing anything more advanced than this is likely to involve a serious
@ -760,7 +828,7 @@ always places the <tt>this</tt> pointer in <tt>arg1</tt>. Other arguments
are placed in <tt>arg2</tt>, <tt>arg3</tt>, and so forth. For example:
</p>
<blockquote>
<div class="code">
<pre>
%feature("action") Foo::bar {
...
@ -768,19 +836,23 @@ are placed in <tt>arg2</tt>, <tt>arg3</tt>, and so forth. For example:
...
}
</pre>
</blockquote>
</div>
<p>
Given the potential to shoot yourself in the foot, it is probably easier to reconsider your
design or to provide an alternative interface using a helper function than it is to create a
fully general wrapper to a varargs C++ member function.
</p>
<H2><a name="Varargs_nn10"></a>13.9 Discussion</H2>
<p>
This chapter has provided a number of techniques that can be used to address the problem of variable length
argument wrapping. If you care about portability and ease of use, the <tt>%varargs</tt> directive is
probably the easiest way to tackle the problem. However, using typemaps, it is possible to do some very advanced
kinds of wrapping.
</p>
<p>
One point of discussion concerns the structure of the libffi examples in the previous section. Looking
@ -791,7 +863,7 @@ between wrapper-specific information and the declaration of the function itself.
you might structure your interface like this:
</p>
<blockquote>
<div class="code">
<pre>
%typemap(const char *fmt, ...) {
...
@ -803,16 +875,18 @@ you might structure your interface like this:
/* Include some header file with traceprintf in it */
%include "someheader.h"
</pre>
</blockquote>
</div>
<p>
Second, careful scrutiny will reveal that the typemaps involving <tt>(...)</tt> have nothing
whatsoever to do with the libffi library. In fact, they are generic with respect to the way in which
the function is actually called. This decoupling means that it will be much easier to consider
other library alternatives for making the function call. For instance, if libffi wasn't supported on a certain
platform, you might be able to use something else instead. You could use conditional compilation
to control this:
</p>
<blockquote>
<div class="code">
<pre>
#ifdef USE_LIBFFI
%feature("action") printf {
@ -825,11 +899,13 @@ to control this:
}
#endif
</pre>
</blockquote>
</div>
<p>
Finally, even though you might be inclined to just write a hand-written wrapper for varargs functions,
the techniques used in the previous section have the advantage of being compatible with all other features
of SWIG such as exception handling.
</p>
<p>
As a final word, some C programmers seem to have the assumption that

103
Doc/Manual/Warnings.html
View file

@ -2,11 +2,13 @@
<html>
<head>
<title>Warning Messages</title>
<link rel="stylesheet" type="text/css" href="style.css"/>
</head>
<body bgcolor="#ffffff">
<H1><a name="Warnings"></a>14 Warning Messages</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="#Warnings_nn2">Introduction</a>
<li><a href="#Warnings_nn3">Warning message suppression</a>
@ -27,6 +29,7 @@
</ul>
<li><a href="#Warnings_nn17">History</a>
</ul>
</div>
<!-- INDEX -->
@ -34,48 +37,58 @@
<H2><a name="Warnings_nn2"></a>14.1 Introduction</H2>
<p>
During compilation, SWIG may generate a variety of warning messages. For example:
</p>
<blockquote>
<div class="code">
<pre>
example.i:16: Warning(501): Overloaded declaration ignored. bar(double)
example.i:15: Warning(501): Previous declaration is bar(int)
</pre>
</blockquote>
</div>
<p>
Typically, warning messages indicate non-fatal problems with the input
where the generated wrapper code will probably compile, but it may not
work like you expect.
</p>
<H2><a name="Warnings_nn3"></a>14.2 Warning message suppression</H2>
<p>
All warning messages have a numeric code that is shown in the warning message itself.
To suppress the printing of a warning message, a number of techniques can be used.
First, you can run SWIG with the <tt>-w</tt> command line option. For example:
</p>
<blockquote>
<div class="code">
<pre>
% swig -python -w501 example.i
% swig -python -w501,505,401 example.i
</pre>
</blockquote>
</div>
<p>
Alternatively, warnings can be suppressed by inserting a special preprocessor pragma
into the input file:
</p>
<blockquote>
<div class="code">
<pre>
%module example
#pragma SWIG nowarn=501
#pragma SWIG nowarn=501,505,401
</pre>
</blockquote>
</div>
<p>
Finally, code-generation warnings can be disabled on a declaration by declaration basis using
the <tt>%warnfilter</tt> directive. For example:
</p>
<blockquote>
<div class="code">
<pre>
%module example
%warnfilter(501) foo;
@ -83,13 +96,15 @@ the <tt>%warnfilter</tt> directive. For example:
int foo(int);
int foo(double); // Silently ignored.
</pre>
</blockquote>
</div>
<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>. For example, if you wanted to
suppress a warning for a method in a class hierarchy, you could do this:
</p>
<blockquote>
<div class="code">
<pre>
%warnfilter(501) Object::foo;
class Object {
@ -106,11 +121,13 @@ public:
...
};
</pre>
</blockquote>
</div>
<p>
Warnings can be suppressed for an entire class by supplying a class name. For example:
</p>
<blockquote>
<div class="code">
<pre>
%warnfilter(501) Object;
@ -119,104 +136,126 @@ public:
... // All 501 warnings ignored in class
};
</pre>
</blockquote>
</div>
<p>
There is no option to suppress all SWIG warning messages. The warning messages are there
for a reason---to tell you that something may be <em>broken</em> in
your interface. Ignore the warning messages at your own peril.
</p>
<H2><a name="Warnings_nn4"></a>14.3 Enabling additional warnings</H2>
<p>
Some warning messages are disabled by default and are generated only
to provide additional diagnostics. All warning messages can be
enabled using the <tt>-Wall</tt> option. For example:
</p>
<blockquote>
<div class="code">
<pre>
% swig -Wall -python example.i
</pre>
</blockquote>
</div>
<p>
When <tt>-Wall</tt> is used, all other warning filters are disabled.
</p>
<p>
To selectively turn on extra warning messages, you can use the directives and options in the
previous section--simply add a "+" to all warning numbers. For example:
</p>
<blockquote>
<div class="code">
<pre>
% swig -w+309,+452 example.i
</pre>
</blockquote>
</div>
<p>
or
</p>
<blockquote>
<div class="code">
<pre>
#pragma SWIG nowarn=+309,+452
</pre>
</blockquote>
</div>
<p>
or
</p>
<blockquote>
<div class="code">
<pre>
%warnfilter(+309,+452) foo;
</pre>
</blockquote>
</div>
<p>
Note: selective enabling of warnings with <tt>%warnfilter</tt> overrides any global settings you might have
made using <tt>-w</tt> or <tt>#pragma</tt>.
</p>
<H2><a name="Warnings_nn5"></a>14.4 Issuing a warning message</H2>
<p>
Warning messages can be issued from an interface file using a number of directives. The
<tt>%warn</tt> directive is the most simple:
</p>
<blockquote>
<div class="code">
<pre>
%warn "750:This is your last warning!"
</pre>
</blockquote>
</div>
<p>
All warning messages are optionally prefixed by the warning number to use. If you are generating
your own warnings, make sure you don't use numbers defined in the table at the end of this section.
</p>
<p>
The <tt>%ignorewarn</tt> directive is the same as <tt>%ignore</tt> except that it issues a
warning message whenever a matching declaration is found. For example:
</p>
<blockquote>
<div class="code">
<pre>
%ignorewarn("362:operator= ignored") operator=;
</pre>
</blockquote>
</div>
<p>
Warning messages can be associated with typemaps using the
<tt>warning</tt> attribute of a typemap declaration. For example:
</p>
<blockquote>
<div class="code">
<pre>
%typemap(in, warning="751:You are really going to regret this") blah * {
...
}
</pre>
</blockquote>
</div>
<p>
In this case, the warning message will be printed whenever the typemap is actually used.
</p>
<H2><a name="Warnings_nn6"></a>14.5 Commentary</H2>
<p>
The ability to suppress warning messages is really only provided for
advanced users and is not recommended in normal use. There are no
plans to provide symbolic names or options that identify specific
types or groups of warning messages---the numbers must be used
explicitly.
</p>
<p>
Certain types of SWIG problems are errors. These usually arise due to
@ -228,26 +267,30 @@ messages.
<H2><a name="Warnings_nn7"></a>14.6 Warnings as errors</H2>
<p>
Warnings can be handled as errors by using the <tt>-Werror</tt> command line
option. This will cause SWIG to exit with a non successful exit code if a
warning is encountered.
</p>
<H2><a name="Warnings_nn8"></a>14.7 Message output format</H2>
<p>
The output format for both warnings and errors can be selected for
integration with your favourite IDE/editor. Editors and IDEs can usually parse
error messages and if in the appropriate format will easily take you
directly to the source of the error. The standard format is used by
default except on Windows where the Microsoft format is used by default.
These can be overridden using command line options, for example:
</p>
<blockquote><pre>
<div class="code"><pre>
$ swig -python -Fstandard example.i
example.i:4: Syntax error in input.
$ swig -python -Fmicrosoft example.i
example.i(4): Syntax error in input.
</pre></blockquote>
</pre></div>
<H2><a name="Warnings_nn9"></a>14.8 Warning number reference</H2>
@ -447,12 +490,16 @@ example.i(4): Syntax error in input.
<H3><a name="Warnings_nn16"></a>14.8.7 User defined (900-999)</H3>
<p>
These numbers can be used by your own application.
</p>
<H2><a name="Warnings_nn17"></a>14.9 History</H2>
<p>
The ability to control warning messages was first added to SWIG-1.3.12.
</p>
</body>
</html>

41
Doc/Manual/Windows.html
View file

@ -2,11 +2,13 @@
<html>
<head>
<title>Getting started on Windows</title>
<link rel="stylesheet" type="text/css" href="style.css"/>
</head>
<body bgcolor="#ffffff">
<H1><a name="Windows"></a>3 Getting started on Windows </H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="#Windows_nn2">Installation on Windows</a>
<ul>
@ -36,34 +38,42 @@
<li><a href="#examples_cygwin">Running the examples on Windows using Cygwin</a>
</ul>
</ul>
</div>
<!-- INDEX -->
<p>
This chapter describes SWIG usage on Microsoft Windows.
Installing SWIG and running the examples is covered as well as building the SWIG executable.
Usage within the Unix like environments MinGW and Cygwin is also detailed.
</p>
<H2><a name="Windows_nn2"></a>3.1 Installation on Windows</H2>
<p>
SWIG does not come with the usual Windows type installation program, however it is quite easy to get started. The main steps are:
<ul>
<li>Download the swigwin zip package from the <a href="http://www.swig.org">SWIG website</a> and unzip into a directory. This is all that needs downloading for the Windows platform.
<li>Set environment variables as described in the <a href="#examples">SWIG Windows Examples</a> section in order to run examples using Visual C++.
</ul>
</p>
<H3><a name="Windows_nn3"></a>3.1.1 Windows Executable</H3>
<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.
If you want to build your own swig.exe have a look at <a href="#swig_exe">Building swig.exe on Windows</a>.
</p>
<H2><a name="examples"></a>3.2 SWIG Windows Examples</H2>
<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.
@ -71,28 +81,32 @@ Later versions of Visual Studio should also be able to open and convert these pr
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.
Alternatively run the <a href="#examples_cygwin">examples using Cygwin</a>.
<p>
<p>
More information on each of the examples is available with the examples distributed with SWIG (Examples/index.html).
<H3><a name="Windows_nn5"></a>3.2.1 Instructions for using the Examples with Visual Studio</H3>
<p>
Ensure the SWIG executable is as supplied in the SWIG root directory in order for the examples to work.
Most languages require some environment variables to be set <b>before</b> running Visual C++.
Note that Visual C++ must be re-started to pick up any changes in environment variables.
Open up an example .dsp file, Visual C++ will create a workspace for you (.dsw file).
Ensure the Release build is selected then do a Rebuild All from the Build menu.
The required environment variables are displayed with their current values. <p>
</p>
<p>
The list of required environment variables for each module language is also listed below.
They are usually set from the Control Panel and System properties, but this depends on which flavour of Windows you are running.
If you don't want to use environment variables then change all occurences of the environment variables in the .dsp files with hard coded values.
If you are interested in how the project files are set up there is explanatory information in some of the language module's documentation.
</p>
<H4><a name="Windows_nn6"></a>3.2.1.1 Python</H4>
<p>
<b><tt>PYTHON_INCLUDE</tt></b> : Set this to the directory that contains python.h<br>
<b><tt>PYTHON_LIB</tt></b> : Set this to the python library including path for linking<p>
Example using Python 2.1.1:<br>
@ -100,10 +114,12 @@ Example using Python 2.1.1:<br>
PYTHON_INCLUDE: d:\python21\include<br>
PYTHON_LIB: d:\python21\libs\python21.lib<br>
</tt>
</p>
<H4><a name="Windows_nn7"></a>3.2.1.2 TCL</H4>
<p>
<b><tt>TCL_INCLUDE</tt></b> : Set this to the directory containing tcl.h<br>
<b><tt>TCL_LIB</tt></b> : Set this to the TCL library including path for linking<p>
Example using ActiveTcl 8.3.3.3 <br>
@ -111,10 +127,12 @@ Example using ActiveTcl 8.3.3.3 <br>
TCL_INCLUDE: d:\tcl\include<br>
TCL_LIB: d:\tcl\lib\tcl83.lib<br>
</tt>
</p>
<H4><a name="Windows_nn8"></a>3.2.1.3 Perl</H4>
<p>
<b><tt>PERL5_INCLUDE</tt></b> : Set this to the directory containing perl.h<br>
<b><tt>PERL5_LIB</tt></b> : Set this to the Perl library including path for linking<p>
Example using nsPerl 5.004_04:<p>
@ -122,10 +140,12 @@ Example using nsPerl 5.004_04:<p>
PERL5_INCLUDE: D:\nsPerl5.004_04\lib\CORE<br>
PERL5_LIB: D:\nsPerl5.004_04\lib\CORE\perl.lib<br>
</tt>
</p>
<H4><a name="Windows_nn9"></a>3.2.1.4 Java</H4>
<p>
<b><tt>JAVA_INCLUDE</tt></b> : Set this to the directory containing jni.h<br>
<b><tt>JAVA_BIN</tt></b> : Set this to the bin directory containing javac.exe<p>
Example using JDK1.3:<br>
@ -133,10 +153,12 @@ Example using JDK1.3:<br>
JAVA_INCLUDE: d:\jdk1.3\include<br>
JAVA_BIN: d:\jdk1.3\bin<br>
</tt>
</p>
<H4><a name="Windows_nn10"></a>3.2.1.5 Ruby</H4>
<p>
<b><tt>RUBY_INCLUDE</tt></b> : Set this to the directory containing ruby.h<br>
<b><tt>RUBY_LIB</tt></b> : Set this to the ruby library including path for linking<p>
Example using Ruby 1.6.4:<br>
@ -144,31 +166,40 @@ Example using Ruby 1.6.4:<br>
RUBY_INCLUDE: D:\ruby\lib\ruby\1.6\i586-mswin32<br>
RUBY_LIB: D:\ruby\lib\mswin32-ruby16.lib<br>
</tt>
</p>
<H4><a name="Windows_nn11"></a>3.2.1.6 C#</H4>
<p>
The C# examples do not require any environment variables to be set as a C# project file is included.
Just open up the .sln solution file in Visual Studio .NET 2003 and do a Rebuild All from the Build menu.
The accompanying C# and C++ project file are automatically used by the solution file.
</p>
<H3><a name="Windows_nn12"></a>3.2.2 Instructions for using the Examples with other compilers</H3>
<p>
If you do not have access to Visual C++ you will have to set up project files / Makefiles for your chosen compiler. There is a section in each of the language modules detailing what needs setting up using Visual C++ which may be of some guidance. Alternatively you may want to use Cygwin as described in the following section.
</p>
<H2><a name="Windows_nn13"></a>3.3 SWIG on Cygwin and MinGW</H2>
<p>
SWIG can also be compiled and run using <a href="http://www.cygwin.com">Cygwin</a> or <a href="http://www.mingw.org">MinGW</a> which provides a Unix like front end to Windows and comes free with gcc, an ANSI C/C++ compiler. However, this is not a recommended approach as the prebuilt executable is supplied.
</p>
<H3><a name="swig_exe"></a>3.3.1 Building swig.exe on Windows</H3>
<p>
If you want to replicate the build of swig.exe that comes with the download, follow the MinGW instructions below.
This is not necessary to use the supplied swig.exe.
This information is provided for those that want to modify the SWIG source code in a Windows environment.
Normally this is not needed, so most people will want to ignore this section.
</p>
<H4><a name="Windows_nn15"></a>3.3.1.1 Building swig.exe using MinGW and MSYS</H4>
@ -182,26 +213,32 @@ Normally this is not needed, so most people will want to ignore this section.
<H4><a name="Windows_nn16"></a>3.3.1.2 Building swig.exe using Cygwin</H4>
<p>
Note that SWIG can also be built using Cygwin.
However, the SWIG will then require the Cygwin DLL when executing.
Follow the Unix instructions in the README file in the SWIG root directory.
Note that the Cygwin environment will also allow one to regenerate the autotool generated files which are supplied with the release distribution.
These files are generated using the <tt>autogen.sh</tt> script and will only need regenerating in circumstances such as changing the build system.
</p>
<H4><a name="Windows_nn17"></a>3.3.1.3 Building swig.exe alternatives</H4>
<p>
If you don't want to install Cygwin or MinGW, use a different compiler to build
SWIG. For example, all the source code files can be added to a Visual C++ project
file in order to build swig.exe from the Visual C++ IDE.
</p>
<H3><a name="examples_cygwin"></a>3.3.2 Running the examples on Windows using Cygwin</H3>
<p>
The examples and test-suite work as successfully on Cygwin as on any other Unix operating system.
The modules which are known to work are Python, Tcl, Perl, Ruby, Java and C#.
Follow the Unix instructions in the README file in the SWIG root directory to build the examples.
</p>
</body>
</html>

25
Doc/Manual/fixstyle.py Normal file
View file

@ -0,0 +1,25 @@
#!/usr/bin/python
# Adds the SWIG stylesheet to the generated documentation on a single page
import sys
import string
filename = sys.argv[1]
data = open(filename).read()
open(filename+".bak","w").write(data)
swigstyle = "\n" + open("style.css").read()
lines = data.splitlines()
result = [ ]
for s in lines:
if s == "<STYLE TYPE=\"text/css\"><!--":
result.append(s + swigstyle)
else:
result.append(s)
data = "\n".join(result)
open(filename,"w").write(data)

4
Doc/Manual/makechap.py
View file

@ -70,7 +70,7 @@ open(filename+".bak","w").write(data) # Make backup
lines = data.splitlines()
result = [ ] # This is the result of postprocessing the file
index = "<!-- INDEX -->\n" # index contains the index for adding at the top of the file. Also printed to stdout.
index = "<!-- INDEX -->\n<div class=\"sectiontoc\">\n" # index contains the index for adding at the top of the file. Also printed to stdout.
skip = 0
skipspace = 0
@ -195,7 +195,7 @@ if subsection:
if section:
index += "</ul>\n"
index += "<!-- INDEX -->\n"
index += "</div>\n<!-- INDEX -->\n"
data = "\n".join(result)

84
Doc/Manual/style.css Normal file
View file

@ -0,0 +1,84 @@
div.sectiontoc {
border-style: dotted;
border-width: 2px;
padding: 2pt;
}
h2 {
padding: 3px;
color: #000000;
border-bottom: 2px
solid #dddddd;
}
h3, h4 {
margin-left: 1em;
}
p,lu,li,table,dl {
margin-left: 2em;
margin-right: 2em;
}
div.indent {
margin-left: 4em;
margin-right: 4em;
}
div.code {
border-style: solid;
border-width: 1px;
padding: 2pt;
margin-left: 4em;
margin-right: 4em;
background-color: #F0FFFF;
}
div.targetlang {
border-style: solid;
border-width: 1px;
padding: 2pt;
margin-left: 4em;
margin-right: 4em;
background-color: #d7f6bb;
}
div.shell {
border-style: solid;
border-width: 1px;
padding: 2pt;
margin-left: 4em;
margin-right: 4em;
background-color: #DCDCDC;
}
div.diagram {
border-style: solid;
border-width: 1px;
padding: 2pt;
margin-left: 4em;
margin-right: 4em;
background-color: #FFEBCD;
}
ul li p {
margin-left: 0;
margin-right: 0;
}
ol li p {
margin-left: 0;
margin-right: 0;
}
dl dd p {
margin-left: 0;
margin-right: 0;
}
div.indent p {
margin-left: 0;
margin-right: 0;
}