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@7003 626c5289-ae23-0410-ae9c-e8d60b6d4f22
This commit is contained in:
John Lenz 2005-02-26 02:56:29 +00:00
commit 4737da0be0
35 changed files with 8013 additions and 4099 deletions
Download patch file Download diff file Expand all files Collapse all files

139
SWIG/Doc/Manual/Arguments.html
View file

@ -2,11 +2,13 @@
<html> <html>
<head> <head>
<title>Argument Handling</title> <title>Argument Handling</title>
<link rel="stylesheet" type="text/css" href="style.css"/>
</head> </head>
<body bgcolor="#ffffff"> <body bgcolor="#ffffff">
<H1><a name="Arguments"></a>9 Argument Handling</H1> <H1><a name="Arguments"></a>9 Argument Handling</H1>
<!-- INDEX --> <!-- INDEX -->
<div class="sectiontoc">
<ul> <ul>
<li><a href="#Arguments_nn2">The typemaps.i library</a> <li><a href="#Arguments_nn2">The typemaps.i library</a>
<ul> <ul>
@ -23,6 +25,7 @@
<li><a href="#Arguments_nn11">Applying constraints to new datatypes</a> <li><a href="#Arguments_nn11">Applying constraints to new datatypes</a>
</ul> </ul>
</ul> </ul>
</div>
<!-- INDEX --> <!-- 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> <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 This section describes the <tt>typemaps.i</tt> library file--commonly used to
change certain properties of argument conversion. change certain properties of argument conversion.
</p>
<H3><a name="Arguments_nn3"></a>9.1.1 Introduction</H3> <H3><a name="Arguments_nn3"></a>9.1.1 Introduction</H3>
<p>
Suppose you had a C function like this: Suppose you had a C function like this:
</p>
<blockquote><pre> <div class="code"><pre>
void add(double a, double b, double *result) { void add(double a, double b, double *result) {
*result = a + b; *result = a + b;
} }
</pre></blockquote> </pre></div>
<p> <p>
From reading the source code, it is clear that the function is storing 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: <tt>typemaps.i</tt> library file and write interface code like this:
</p> </p>
<blockquote><pre> <div class="code"><pre>
// Simple example using typemaps // Simple example using typemaps
%module example %module example
%include "typemaps.i" %include "typemaps.i"
%apply double *OUTPUT { double *result }; %apply double *OUTPUT { double *result };
extern void add(double a, double b, double *result); extern void add(double a, double b, double *result);
</pre></blockquote> </pre></div>
<p> <p>
The <tt>%apply</tt> directive tells SWIG that you are going to apply 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): like this (shown for Python):
</p> </p>
<blockquote><pre> <div class="code"><pre>
&gt;&gt;&gt; a = add(3,4) &gt;&gt;&gt; a = add(3,4)
&gt;&gt;&gt; print a &gt;&gt;&gt; print a
7 7
&gt;&gt;&gt; &gt;&gt;&gt;
</pre></blockquote> </pre></div>
<p>
In this case, you can see how the output value normally returned in In this case, you can see how the output value normally returned in
the third argument has magically been transformed into a function the third argument has magically been transformed into a function
return value. Clearly this makes the function much easier to use return value. Clearly this makes the function much easier to use
since it is no longer necessary to manufacture a special <tt>double since it is no longer necessary to manufacture a special <tt>double
*</tt> object and pass it to the function somehow. *</tt> object and pass it to the function somehow.
</p>
<p> <p>
Once a typemap has been applied to a type, it stays in effect for all future occurrences 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: of the type and name. For example, you could write the following:
</p> </p>
<blockquote><pre> <div class="code"><pre>
%module example %module example
%include "typemaps.i" %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 mul(double a, double b, double *result);
extern void div(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. In this case, the <tt>double *OUTPUT</tt> rule is applied to all of the functions that follow.
</p>
<p> <p>
Typemap transformations can even be extended to multiple return values. Typemap transformations can even be extended to multiple return values.
For example, consider this code: For example, consider this code:
</p> </p>
<blockquote> <div class="code">
<pre> <pre>
%include "typemaps.i" %include "typemaps.i"
%apply int *OUTPUT { int *width, int *height }; %apply int *OUTPUT { int *width, int *height };
@ -136,11 +147,13 @@ For example, consider this code:
// Returns a pair (width,height) // Returns a pair (width,height)
void getwinsize(int winid, int *width, int *height); void getwinsize(int winid, int *width, int *height);
</pre> </pre>
</blockquote> </div>
<p>
In this case, the function returns multiple values, allowing it to be used like this: 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; w,h = genwinsize(wid)
&gt;&gt;&gt; print w &gt;&gt;&gt; print w
400 400
@ -148,7 +161,7 @@ In this case, the function returns multiple values, allowing it to be used like
300 300
&gt;&gt;&gt; &gt;&gt;&gt;
</pre> </pre>
</blockquote> </div>
<p> <p>
It should also be noted that although the <tt>%apply</tt> directive is 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: rule names directly in arguments. For example, you could write this:
</p> </p>
<blockquote><pre> <div class="code"><pre>
// Simple example using typemaps // Simple example using typemaps
%module example %module example
%include "typemaps.i" %include "typemaps.i"
extern void add(double a, double b, double *OUTPUT); 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 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: else. To clear a typemap, the <tt>%clear</tt> directive should be used. For example:
</p>
<blockquote> <div class="code">
<pre> <pre>
%clear double *result; // Remove all typemaps for double *result %clear double *result; // Remove all typemaps for double *result
</pre> </pre>
</blockquote> </div>
<H3><a name="Arguments_nn4"></a>9.1.2 Input parameters</H3> <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: input value:
</p> </p>
<blockquote><pre> <div class="code"><pre>
int *INPUT int *INPUT
short *INPUT short *INPUT
long *INPUT long *INPUT
@ -190,34 +205,38 @@ unsigned short *INPUT
unsigned long *INPUT unsigned long *INPUT
double *INPUT double *INPUT
float *INPUT float *INPUT
</pre></blockquote> </pre></div>
<p>
When used, it allows values to be passed instead of pointers. For example, consider this When used, it allows values to be passed instead of pointers. For example, consider this
function: function:
</p>
<blockquote><pre> <div class="code"><pre>
double add(double *a, double *b) { double add(double *a, double *b) {
return *a+*b; return *a+*b;
} }
</pre></blockquote> </pre></div>
<p>
Now, consider this SWIG interface: Now, consider this SWIG interface:
</p>
<blockquote><pre> <div class="code"><pre>
%module example %module example
%include "typemaps.i" %include "typemaps.i"
... ...
extern double add(double *INPUT, double *INPUT); extern double add(double *INPUT, double *INPUT);
</pre></blockquote> </pre></div>
<p> <p>
When the function is used in the scripting language interpreter, it will work like this: When the function is used in the scripting language interpreter, it will work like this:
</p> </p>
<blockquote><pre> <div class="code"><pre>
result = add(3,4) result = add(3,4)
</pre></blockquote> </pre></div>
<H3><a name="Arguments_nn5"></a>9.1.3 Output parameters</H3> <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. calling the function. Instead, one or more output values are returned.
</p> </p>
<blockquote><pre> <div class="code"><pre>
int *OUTPUT int *OUTPUT
short *OUTPUT short *OUTPUT
long *OUTPUT long *OUTPUT
@ -238,47 +257,51 @@ unsigned long *OUTPUT
double *OUTPUT double *OUTPUT
float *OUTPUT float *OUTPUT
</pre></blockquote> </pre></div>
<p> <p>
These methods can be used as shown in an earlier example. For example, if you have this C function :</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) { void add(double a, double b, double *c) {
*c = a+b; *c = a+b;
} }
</pre></blockquote> </pre></div>
<p> <p>
A SWIG interface file might look like this :</p> A SWIG interface file might look like this :</p>
<blockquote><pre> <div class="code"><pre>
%module example %module example
%include "typemaps.i" %include "typemaps.i"
... ...
extern void add(double a, double b, double *OUTPUT); 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 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 a restriction. An arbitrary number of output values can be returned by applying
the output rules to more than one argument (as shown previously). the output rules to more than one argument (as shown previously).
</p>
<p> <p>
If the function also returns a value, it is returned along with the argument. For example, If the function also returns a value, it is returned along with the argument. For example,
if you had this: if you had this:
</p> </p>
<blockquote><pre> <div class="code"><pre>
extern int foo(double a, double b, double *OUTPUT); extern int foo(double a, double b, double *OUTPUT);
</pre></blockquote> </pre></div>
<p>
The function will return two values like this: The function will return two values like this:
</p>
<blockquote> <div class="code">
<pre> <pre>
iresult, dresult = foo(3.5, 2) iresult, dresult = foo(3.5, 2)
</pre> </pre>
</blockquote> </div>
<H3><a name="Arguments_nn6"></a>9.1.4 Input/Output parameters</H3> <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 When a pointer serves as both an input and output value you can use
the following typemaps :</p> the following typemaps :</p>
<blockquote><pre> <div class="code"><pre>
int *INOUT int *INOUT
short *INOUT short *INOUT
long *INOUT long *INOUT
@ -297,43 +320,45 @@ unsigned long *INOUT
double *INOUT double *INOUT
float *INOUT float *INOUT
</pre></blockquote> </pre></div>
<p> <p>
A C function that uses this might be something like this:</p> A C function that uses this might be something like this:</p>
<blockquote><pre> <div class="code"><pre>
void negate(double *x) { void negate(double *x) {
*x = -(*x); *x = -(*x);
} }
</pre></blockquote> </pre></div>
<p> <p>
To make x function as both and input and output value, declare the To make x function as both and input and output value, declare the
function like this in an interface file :</p> function like this in an interface file :</p>
<blockquote><pre> <div class="code"><pre>
%module example %module example
%include typemaps.i %include typemaps.i
... ...
extern void negate(double *INOUT); extern void negate(double *INOUT);
</pre></blockquote> </pre></div>
<p> <p>
Now within a script, you can simply call the function normally :</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 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 One subtle point of the <tt>INOUT</tt> rule is that many scripting languages
enforce mutability constraints on primitive objects (meaning that simple objects 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 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. 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 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. rather than directly overwriting the value of the original input object.
</p>
<p> <p>
<b>Compatibility note :</b> The <tt>INOUT</tt> rule used to be known as <tt>BOTH</tt> in earlier versions of <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: <tt>INOUT</tt> typemaps to different argument names. For example:
</p> </p>
<blockquote><pre> <div class="code"><pre>
// Make double *result an output value // Make double *result an output value
%apply double *OUTPUT { double *result }; %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 // Make long *x inout
%apply long *INOUT {long *x}; %apply long *INOUT {long *x};
</pre></blockquote> </pre></div>
<p>
To clear a rule, the <tt>%clear</tt> directive is used: To clear a rule, the <tt>%clear</tt> directive is used:
</p>
<blockquote><pre> <div class="code"><pre>
%clear double *result; %clear double *result;
%clear Int32 *in, long *x; %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 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. file or a matching <tt>%clear</tt> declaration.
</p>
<H2><a name="Arguments_nn8"></a>9.2 Applying constraints to input values</H2> <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 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 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 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. 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> <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 The constraints library is best illustrated by the following interface
file :</p> file :</p>
<blockquote><pre> <div class="code"><pre>
// Interface file with constraints // Interface file with constraints
%module example %module example
%include "constraints.i" %include "constraints.i"
@ -396,7 +427,7 @@ double sqrt(double NONNEGATIVE); // Non-negative values only
double inv(double NONZERO); // Non-zero values double inv(double NONZERO); // Non-zero values
void free(void *NONNULL); // Non-NULL pointers only void free(void *NONNULL); // Non-NULL pointers only
</pre></blockquote> </pre></div>
<p> <p>
The behavior of this file is exactly as you would expect. If any of 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> <p>
The following constraints are currently available</p> The following constraints are currently available</p>
<blockquote><pre> <div class="code"><pre>
POSITIVE Any number &gt; 0 (not zero) POSITIVE Any number &gt; 0 (not zero)
NEGATIVE Any number &lt; 0 (not zero) NEGATIVE Any number &lt; 0 (not zero)
NONNEGATIVE Any number &gt;= 0 NONNEGATIVE Any number &gt;= 0
@ -418,7 +449,7 @@ NONPOSITIVE Any number &lt;= 0
NONZERO Nonzero number NONZERO Nonzero number
NONNULL Non-NULL pointer (pointers only). 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> <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 is easy to apply it to new datatypes using <tt>%apply</tt>. For
example :</p> example :</p>
<blockquote><pre> <div class="code"><pre>
// Apply a constraint to a Real variable // Apply a constraint to a Real variable
%apply Number POSITIVE { Real in }; %apply Number POSITIVE { Real in };
// Apply a constraint to a pointer type // Apply a constraint to a pointer type
%apply Pointer NONNULL { Vector * }; %apply Pointer NONNULL { Vector * };
</pre></blockquote> </pre></div>
<p> <p>
The special types of "Number" and "Pointer" can be applied to any The special types of "Number" and "Pointer" can be applied to any
numeric and pointer variable type respectively. To later remove a numeric and pointer variable type respectively. To later remove a
constraint, the <tt>%clear</tt> directive can be used :</p> constraint, the <tt>%clear</tt> directive can be used :</p>
<blockquote><pre> <div class="code"><pre>
%clear Real in; %clear Real in;
%clear Vector *; %clear Vector *;
</pre></blockquote> </pre></div>
</body> </body>
</html> </html>

37
SWIG/Doc/Manual/CSharp.html
View file

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

34
SWIG/Doc/Manual/Chicken.html
View file

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

71
SWIG/Doc/Manual/Contents.html
View file

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

72
SWIG/Doc/Manual/Contract.html
View file

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

191
SWIG/Doc/Manual/Customization.html
View file

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

891
SWIG/Doc/Manual/Extending.html
View file

File diff suppressed because it is too large Load diff

198
SWIG/Doc/Manual/Guile.html
View file

@ -3,12 +3,14 @@
<html> <html>
<head> <head>
<title>SWIG and Guile</title> <title>SWIG and Guile</title>
<link rel="stylesheet" type="text/css" href="style.css"/>
</head> </head>
<body bgcolor="#ffffff"> <body bgcolor="#ffffff">
<H1><a name="Guile"></a>18 SWIG and Guile</H1> <H1><a name="Guile"></a>18 SWIG and Guile</H1>
<!-- INDEX --> <!-- INDEX -->
<div class="sectiontoc">
<ul> <ul>
<li><a href="#Guile_nn2">Meaning of "Module"</a> <li><a href="#Guile_nn2">Meaning of "Module"</a>
<li><a href="#Guile_nn3">Using the SCM or GH Guile API</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> <li><a href="#Guile_nn21">Linking</a>
</ul> </ul>
</ul> </ul>
</div>
<!-- INDEX --> <!-- 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. 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> 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_append2(a, b) scm_append(scm_listify(a, b, SCM_UNDEFINED))
#define gh_apply(a, b) scm_apply(a, b, SCM_EOL) #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_cons scm_cons
#define gh_double2scm scm_make_real #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 <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; 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> <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 The default linkage is the simplest; nothing special is done. In this
case the function <code>SWIG_init()</code> is exported. Simple linkage case the function <code>SWIG_init()</code> is exported. Simple linkage
can be used in several ways: can be used in several ways:
</p>
<ul> <ul>
<li><b>Embedded Guile, no modules.</b> You want to embed a Guile <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>inner_main()</code> function. See the "simple" and "matrix" examples under
<code>Examples/guile</code>. <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 using <code>define-module</code>, containing both Scheme code and
bindings made by SWIG; you want to load the SWIG modules as shared bindings made by SWIG; you want to load the SWIG modules as shared
libraries into Guile. libraries into Guile.</p>
<blockquote> <div class="targetlang">
<pre> <pre>
(define-module (my module)) (define-module (my module))
(define my-so (dynamic-link "./example.so")) (define my-so (dynamic-link "./example.so"))
(dynamic-call "SWIG_init" my-so) ; make SWIG bindings (dynamic-call "SWIG_init" my-so) ; make SWIG bindings
;; Scheme definitions can go here ;; Scheme definitions can go here
</pre> </pre>
</blockquote> </div>
<p>
Newer Guile versions provide a shorthand for <code>dynamic-link</code> Newer Guile versions provide a shorthand for <code>dynamic-link</code>
and <code>dynamic-call</code>: and <code>dynamic-call</code>:
<blockquote> </p>
<div class="targetlang">
<pre> <pre>
(load-extension "./example.so" "SWIG_init") (load-extension "./example.so" "SWIG_init")
</pre> </pre>
</blockquote> </div>
<p>
You need to explicitly export those bindings made by SWIG that you You need to explicitly export those bindings made by SWIG that you
want to import into other modules: want to import into other modules:
<blockquote> </p>
<div class="targetlang">
<pre> <pre>
(export foo bar) (export foo bar)
</pre> </pre>
</blockquote> </div>
<p>
In this example, the procedures <code>foo</code> and <code>bar</code> In this example, the procedures <code>foo</code> and <code>bar</code>
would be exported. Alternatively, you can export all bindings with the would be exported. Alternatively, you can export all bindings with the
following module-system hack: following module-system hack:
<blockquote> </p>
<div class="targetlang">
<pre> <pre>
(module-map (lambda (sym var) (module-map (lambda (sym var)
(module-export! (current-module) (list sym))) (module-export! (current-module) (list sym)))
(current-module)) (current-module))
</pre> </pre>
</blockquote> </div>
<p>SWIG can also generate this Scheme stub (from <p>SWIG can also generate this Scheme stub (from
<code>define-module</code> up to <code>export</code>) <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: information by including a directive like this in the interface file:
</p> </p>
<blockquote> <div class="code">
<pre> <pre>
%scheme %{ (load-extension "./example.so" "SWIG_init") %} %scheme %{ (load-extension "./example.so" "SWIG_init") %}
</pre> </pre>
</blockquote> </div>
<p>
(The <code>%scheme</code> directive allows to insert arbitrary Scheme (The <code>%scheme</code> directive allows to insert arbitrary Scheme
code into the generated file <code><var>module.scm</var></code>; it is code into the generated file <code><var>module.scm</var></code>; it is
placed between the <code>define-module</code> form and the placed between the <code>define-module</code> form and the
<code>export</code> form.) <code>export</code> form.)
</p>
</ul> </ul>
<p>If you want to include several SWIG modules, you would need to rename <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 <li><b>Dynamic Guile modules.</b> You want to load the SWIG modules as
shared libraries into Guile; all bindings are automatically put in shared libraries into Guile; all bindings are automatically put in
newly created Guile modules. newly created Guile modules.
<blockquote> <div class="targetlang">
<pre> <pre>
(define my-so (dynamic-link "./foo.so")) (define my-so (dynamic-link "./foo.so"))
;; create new module and put bindings there: ;; create new module and put bindings there:
(dynamic-call "scm_init_my_modules_foo_module" my-so) (dynamic-call "scm_init_my_modules_foo_module" my-so)
</pre> </pre>
</blockquote> </div>
Newer Guile versions have a shorthand procedure for this: Newer Guile versions have a shorthand procedure for this:
<blockquote> <div class="targetlang">
<pre> <pre>
(load-extension "./foo.so" "scm_init_my_modules_foo_module") (load-extension "./foo.so" "scm_init_my_modules_foo_module")
</pre> </pre>
</blockquote> </div>
</ul> </ul>
<H3><a name="Guile_nn8"></a>18.3.4 Old Auto-Loading Guile Module Linkage</H3> <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: name before the last symbol. For example, both command lines:
</p> </p>
<blockquote> <div class="shell">
<pre> <pre>
swig -guile -package my/lib foo.i swig -guile -package my/lib foo.i
swig -guile -package my/lib -module foo foo.i swig -guile -package my/lib -module foo foo.i
</pre> </pre>
</blockquote> </div>
<p> <p>
would create module <code>(my lib foo)</code> (assuming in the first 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: <p>Multiple values can be passed up to Scheme in one of three ways:
<ul> <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 By default, if more than one value is to
be returned, a list of the values is created and returned; to switch be returned, a list of the values is created and returned; to switch
back to this behavior, use back to this behavior, use</p>
<blockquote>
<div class="code">
<pre> <pre>
%values_as_list;</pre> %values_as_list;</pre>
</blockquote> </div>
<p>
<li><em>Multiple values as vectors.</em> <li><em>Multiple values as vectors.</em>
By issuing By issuing
<blockquote> </p>
<div class="code">
<pre> <pre>
%values_as_vector;</pre> %values_as_vector;</pre>
</blockquote> </div>
<p>
vectors instead of lists will be used. vectors instead of lists will be used.
<li><em>Multiple values for multiple-value continuations.</em> <li><em>Multiple values for multiple-value continuations.</em>
<strong>This is the most elegant way.</strong> By issuing <strong>This is the most elegant way.</strong> By issuing
<blockquote> </p>
<div class="code">
<pre> <pre>
%multiple_values;</pre> %multiple_values;</pre>
</blockquote> </div>
<p>
multiple values are passed to the multiple-value multiple values are passed to the multiple-value
continuation, as created by <code>call-with-values</code> or the continuation, as created by <code>call-with-values</code> or the
convenience macro <code>receive</code>. The latter is available if you convenience macro <code>receive</code>. The latter is available if you
issue <code>(use-modules (srfi srfi-8))</code>. Assuming that your issue <code>(use-modules (srfi srfi-8))</code>. Assuming that your
<code>divide</code> function <code>divide</code> function
wants to return two values, a quotient and a remainder, you can write: wants to return two values, a quotient and a remainder, you can write:
<blockquote> </p>
<div class="targetlang">
<pre> <pre>
(receive (quotient remainder) (receive (quotient remainder)
(divide 35 17) (divide 35 17)
<var>body</var>...) <var>body</var>...)
</pre> </pre>
</blockquote> </div>
<p>
In <code><var>body</var></code>, the first result of In <code><var>body</var></code>, the first result of
<code>divide</code> will be bound to the variable <code>divide</code> will be bound to the variable
<code>quotient</code>, and the second result to <code>remainder</code>. <code>quotient</code>, and the second result to <code>remainder</code>.
</p>
</ul> </ul>
<p>
See also the "multivalue" example. See also the "multivalue" example.
</p>
<H2><a name="Guile_nn12"></a>18.6 Representation of pointers as smobs</H2> <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. pointer, a <code>wrong-type-arg</code> exception is raised.
<H3><a name="Guile_nn13"></a>18.6.1 GH Smobs</H3> <H3><a name="Guile_nn13"></a>18.6.1 GH Smobs</H3>
<p> <p>
In earlier versions of SWIG, C pointers were represented as Scheme In earlier versions of SWIG, C pointers were represented as Scheme
strings containing a hexadecimal rendering of the pointer value and a 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 SWIG code calls <code>scm_error</code> on exception, using the following
mapping: mapping:
<div class="code">
<pre> <pre>
MAP(SWIG_MemoryError, "swig-memory-error"); MAP(SWIG_MemoryError, "swig-memory-error");
MAP(SWIG_IOError, "swig-io-error"); MAP(SWIG_IOError, "swig-io-error");
@ -462,6 +505,7 @@ mapping:
MAP(SWIG_ValueError, "swig-value-error"); MAP(SWIG_ValueError, "swig-value-error");
MAP(SWIG_SystemError, "swig-system-error"); MAP(SWIG_SystemError, "swig-system-error");
</pre> </pre>
</div>
<p> <p>
The default when not specified here is to use "swig-error". 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 <p>You need to register the generated documentation file with Guile
like this: like this:
<div class="targetlang">
<pre> <pre>
(use-modules (ice-9 documentation)) (use-modules (ice-9 documentation))
(set! documentation-files (set! documentation-files
(cons "<var>file</var>" documentation-files)) (cons "<var>file</var>" documentation-files))
</pre> </pre>
</div>
<p>Documentation strings can be configured using the Guile-specific <p>Documentation strings can be configured using the Guile-specific
typemap argument <code>doc</code>. See <code>Lib/guile/typemaps.i</code> for 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, <p>If <code>-emit-slot-accessors</code> is also passed as an argument,
then the generated file will contain accessor methods for all the then the generated file will contain accessor methods for all the
slots in the classes and for global variables. The input class</p> slots in the classes and for global variables. The input class</p>
<blockquote><pre> <div class="code"><pre>
class Foo { class Foo {
public: public:
Foo(int i) : a(i) {} 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 getFooMultBy(int i) { return Foo(a * i); }
}; };
Foo getFooPlus(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) 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;) (define-class &lt;Foo&gt; (&lt;swig&gt;)
(a #:allocation #:swig-virtual (a #:allocation #:swig-virtual
#:slot-ref primitive:Foo-a-get #: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))) (make &lt;Foo&gt; #:init-smob (primitive:getFooPlus i)))
(export &lt;Foo&gt; getMultBy getFooMultBy getFooPlus ) (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) 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;) (define-class &lt;Foo&gt; (&lt;swig&gt;)
(a #:allocation #:swig-virtual (a #:allocation #:swig-virtual
#:slot-ref primitive:Foo-a-get #: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))) (make &lt;Foo&gt; #:init-smob (primitive:getFooPlus i)))
(export &lt;Foo&gt; <b>a</b> getMultBy getFooMultBy getFooPlus ) (export &lt;Foo&gt; <b>a</b> getMultBy getFooMultBy getFooPlus )
</pre></blockquote> </pre></div>
<p>
which can then be used by this code which can then be used by this code
<blockquote><pre> </p>
<div class="targetlang"><pre>
;; not using getters and setters ;; not using getters and setters
(define foo (make &lt;Foo&gt; #:args '(45))) (define foo (make &lt;Foo&gt; #:args '(45)))
(slot-ref foo 'a) (slot-ref foo 'a)
@ -616,13 +675,15 @@ which can then be used by this code
(set! (a foo) 5) (set! (a foo) 5)
(getMultBy foo 4) (getMultBy foo 4)
(a (getFooMultBy foo 7)) (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 <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> 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>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 %module test
%{ #include "foo.h" %} %{ #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" %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 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 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> 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 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;)) (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 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. <code>%import "foo.h"</code> before the <code>%inline</code> block.
</p>
<H3><a name="Guile_nn20"></a>18.10.1 Naming Issues</H3> <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 <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 at the same time. To do this, you need to rename the exported symbols from one or both
guile-modules. For example,</p> guile-modules. For example,</p>
<blockquote><pre> <div class="targetlang"><pre>
(use-modules ((Test-primitive) #:renamer (symbol-prefix-proc 'primitive:))) (use-modules ((Test-primitive) #:renamer (symbol-prefix-proc 'primitive:)))
(use-modules ((Test) #:renamer (symbol-prefix-proc 'goops:))) (use-modules ((Test) #:renamer (symbol-prefix-proc 'goops:)))
</pre></blockquote> </pre></div>
<p>TODO: Renaming class name prefixes?</p> <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. of the generated GOOPS guile-module.
The <code>%goops</code> directive should contain code to load the .so library. 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") %} %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 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) (with the <code>-package my/modules -module foo</code> command line arguments)
<blockquote><pre> </p>
<div class="targetlang"><pre>
(define-module (my modules foo)) (define-module (my modules foo))
;; %goops directive goes here ;; %goops directive goes here
(load-extension "./foo.so" "scm_init_my_modules_foo_module") (load-extension "./foo.so" "scm_init_my_modules_foo_module")
(use-modules (oop goops) (Swig common)) (use-modules (oop goops) (Swig common))
</pre></blockquote> </pre></div>
</li> </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> <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, 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. which will then be added to the scmstub file.
Swig will automatically generate the line <code>(use-modules (<i>Package</i> <i>Module-primitive</i>))</code> Swig will automatically generate the line <code>(use-modules (<i>Package</i> <i>Module-primitive</i>))</code>
into the GOOPS guile-module. So if <i>Module-primitive.scm</i> is on the autoload path for guile, the 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 <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") %} %scheme %{ (load-extension "./foo.so" "scm_init_my_modules_foo_module") %}
// only include the following definition if (my modules foo) cannot // only include the following definition if (my modules foo) cannot
// be loaded automatically // 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/foo-primitive.scm")
(primitive-load "/path/to/Swig/common.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 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)) (define-module (my modules foo))
;; %goops directive goes here (if any) ;; %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 (use-modules ((my modules foo-primitive) :renamer (symbol-prefix-proc
'primitive:))) 'primitive:)))
</pre></blockquote> </pre></div>
</li> </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 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> (<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") %} %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 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)) (define-module (my modules foo))
;; %goops directive goes here (if any) ;; %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 (use-modules ((my modules foo-primitive) :renamer (symbol-prefix-proc
'primitive:))) 'primitive:)))
</pre></blockquote> </pre></div>
</li> </li>
</ul> </ul>

66
SWIG/Doc/Manual/Introduction.html
View file

@ -2,11 +2,13 @@
<html> <html>
<head> <head>
<title>Introduction</title> <title>Introduction</title>
<link rel="stylesheet" type="text/css" href="style.css"/>
</head> </head>
<body bgcolor="#ffffff"> <body bgcolor="#ffffff">
<H1><a name="Introduction"></a>2 Introduction</H1> <H1><a name="Introduction"></a>2 Introduction</H1>
<!-- INDEX --> <!-- INDEX -->
<div class="sectiontoc">
<ul> <ul>
<li><a href="#Introduction_nn2">What is SWIG?</a> <li><a href="#Introduction_nn2">What is SWIG?</a>
<li><a href="#Introduction_nn3">Why use 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_nn12">Hands off code generation</a>
<li><a href="#Introduction_nn13">SWIG and freedom</a> <li><a href="#Introduction_nn13">SWIG and freedom</a>
</ul> </ul>
</div>
<!-- INDEX --> <!-- INDEX -->
@ -31,6 +34,7 @@
<H2><a name="Introduction_nn2"></a>2.1 What is SWIG?</H2> <H2><a name="Introduction_nn2"></a>2.1 What is SWIG?</H2>
<p>
SWIG is a software development tool that simplifies the task of SWIG is a software development tool that simplifies the task of
interfacing different languages to C and C++ programs. In a interfacing different languages to C and C++ programs. In a
nutshell, SWIG is a compiler that takes C declarations and creates nutshell, SWIG is a compiler that takes C 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 requires no modifications to existing code and can often be used to
build a usable interface in only a few minutes. Possible applications build a usable interface in only a few minutes. Possible applications
of SWIG include: of SWIG include:
</p>
<ul> <ul>
<li>Building interpreted interfaces to existing C programs. <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> <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 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 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 anyone want to do that? To answer that question, it is useful to list a few strengths
of C/C++ programming: of C/C++ programming:
</p>
<ul> <ul>
<li>Excellent support for writing programming libraries. <li>Excellent support for writing programming libraries.
@ -80,7 +87,9 @@ of C/C++ programming:
<li>Large user community and software base. <li>Large user community and software base.
</ul> </ul>
<p>
Next, let's list a few problems with C/C++ programming Next, let's list a few problems with C/C++ programming
</p>
<ul> <ul>
<li>Writing a user interface is rather painful (i.e., consider programming with MFC, X11, GTK, or any number <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>Modularization can be tricky.
<li>Security concerns (buffer overflow for instance). <li>Security concerns (buffer overflow for instance).
</ul> </ul>
<p>
To address these limitations, many programmers have arrived at the To address these limitations, many programmers have arrived at the
conclusion that it is much easier to use different programming conclusion that it is much easier to use different programming
languages for different tasks. For instance, writing a graphical user 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 programming is ever going to be perfect. Therefore, by combining
languages together, you can utilize the best features of each language languages together, you can utilize the best features of each language
and greatly simplify certain aspects of software development. and greatly simplify certain aspects of software development.
</p>
<p> <p>
From the standpoint of C/C++, a lot of people use SWIG because they want to break 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 <li>A horrible collection of hacks that form some kind of user interface (but
which no-one really wants to touch). which no-one really wants to touch).
</ul> </ul>
<p>
Instead of going down that route, incorporating C/C++ into a higher level language 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 often results in a more modular design, less code, better flexibility, and increased
programmer productivity. programmer productivity.
</p>
<p> <p>
SWIG tries to make the problem of C/C++ integration as painless as possible. 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> <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 The best way to illustrate SWIG is with a simple example. Consider the
following C code: following C code:
</p>
<blockquote><pre> <div class="code"><pre>
/* File : example.c */ /* File : example.c */
double My_variable = 3.0; double My_variable = 3.0;
@ -152,7 +165,7 @@ int fact(int n) {
int my_mod(int n, int m) { int my_mod(int n, int m) {
return(n % m); return(n % m);
} }
</pre></blockquote> </pre></div>
<p> <p>
Suppose that you wanted to access these functions and the global 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> <H3><a name="Introduction_nn5"></a>2.3.1 SWIG interface file</H3>
<blockquote><pre> <div class="code"><pre>
/* File : example.i */ /* File : example.i */
%module example %module example
%{ %{
@ -173,7 +186,7 @@ suffix) :
extern double My_variable; extern double My_variable;
extern int fact(int); extern int fact(int);
extern int my_mod(int n, int m); extern int my_mod(int n, int m);
</pre></blockquote> </pre></div>
<p> <p>
The interface file contains ANSI C function prototypes and variable 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> <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 SWIG is invoked using the <tt>swig</tt> command. We can use this to
build a Tcl module (under Linux) as follows : 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>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 -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> 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> % <b>expr $My_variable + 4.5</b>
7.5 7.5
% %
</pre></blockquote> </pre></div>
<p> <p>
The <tt>swig</tt> command produced a new file called 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> <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 Now, let's turn these functions into a Perl5 module. Without making
any changes type the following (shown for Solaris): 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>swig -perl5 example.i</b>
unix &gt; <b>gcc -c example.c example_wrap.c \ unix &gt; <b>gcc -c example.c example_wrap.c \
-I/usr/local/lib/perl5/sun4-solaris/5.003/CORE</b> -I/usr/local/lib/perl5/sun4-solaris/5.003/CORE</b>
@ -235,15 +252,17 @@ print $example::My_variable + 4.5, "\n";
2 2
7.5 7.5
unix &gt; unix &gt;
</pre></blockquote> </pre></div>
<H3><a name="Introduction_nn8"></a>2.3.4 Building a Python module</H3> <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). 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>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 -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> 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 2
&gt;&gt;&gt; <b>example.cvar.My_variable + 4.5</b> &gt;&gt;&gt; <b>example.cvar.My_variable + 4.5</b>
7.5 7.5
</pre></blockquote> </pre></div>
<H3><a name="Introduction_nn9"></a>2.3.5 Shortcuts</H3> <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 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 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 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 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>swig -perl5 -module example example.h</b>
unix &gt; <b>gcc -c example.c example_wrap.c \ unix &gt; <b>gcc -c example.c example_wrap.c \
-I/usr/local/lib/perl5/sun4-solaris/5.003/CORE</b> -I/usr/local/lib/perl5/sun4-solaris/5.003/CORE</b>
@ -282,15 +303,17 @@ print $example::My_variable + 4.5, "\n";
24 24
2 2
7.5 7.5
</pre></blockquote> </pre></div>
<H2><a name="Introduction_nn10"></a>2.4 Supported C/C++ language features</H2> <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 A primary goal of the SWIG project is to make the language binding
process extremely easy. Although a few simple examples have been shown, process extremely easy. Although a few simple examples have been shown,
SWIG is quite capable in supporting most of C++. Some of the SWIG is quite capable in supporting most of C++. Some of the
major features include: major features include:
</p>
<ul> <ul>
<li>Full C99 preprocessing. <li>Full C99 preprocessing.
@ -306,8 +329,10 @@ major features include:
<li>C++ smart pointers. <li>C++ smart pointers.
</ul> </ul>
<p>
Currently, the only major C++ feature not supported is nested classes--a limitation Currently, the only major C++ feature not supported is nested classes--a limitation
that will be removed in a future release. that will be removed in a future release.
</p>
<p> <p>
It is important to stress that SWIG is not a simplistic C++ lexing 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> <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 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 existing C or C++ code. This makes SWIG extremely easy to use with existing
packages and promotes software reuse and modularity. By making packages and promotes software reuse and modularity. By making
the C/C++ code independent of the high level interface, you can change the 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 interface and reuse the code in other applications. It is also
possible to support different types of interfaces depending on the application. 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> <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: The following example is a CMake input file for creating a python wrapper for the SWIG interface file, example.i:
</p> </p>
<blockquote><pre> <div class="code"><pre>
# This is a CMake example for Python # 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_ADD_MODULE(example python example.i example.cxx)
SWIG_LINK_LIBRARIES(example ${PYTHON_LIBRARIES}) 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 The above example will generate native build files such as makefiles, nmake files and Visual Studio projects
which will invoke SWIG and compile the generated C++ files into _example.so (UNIX) or _example.dll (Windows). which will invoke SWIG and compile the generated C++ files into _example.so (UNIX) or _example.dll (Windows).
</p>
<H2><a name="Introduction_nn12"></a>2.7 Hands off code generation</H2> <H2><a name="Introduction_nn12"></a>2.7 Hands off code generation</H2>
<p>
SWIG is designed to produce working code that needs no SWIG is designed to produce working code that needs no
hand-modification (in fact, if you look at the output, you probably 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 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, file. While this approach may limit flexibility for hard-core hackers,
it allows others to forget about the low-level implementation it allows others to forget about the low-level implementation
details. details.
</p>
<H2><a name="Introduction_nn13"></a>2.8 SWIG and freedom</H2> <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. 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 However, it may be useful to know that SWIG was written with a
certain "philosophy" about programming---namely that programmers are 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. "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 On the other hand, this kind of freedoom may be exactly what is needed
to work with complicated and unusual C/C++ applications. to work with complicated and unusual C/C++ applications.
</p>
<p> <p>
Ironically, the freedom that SWIG provides is countered by an Ironically, the freedom that SWIG provides is countered by an

1775
SWIG/Doc/Manual/Java.html
View file

File diff suppressed because it is too large Load diff

608
SWIG/Doc/Manual/Library.html
View file

File diff suppressed because it is too large Load diff

3
SWIG/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; all=`sed '/^#/d' chapters`; for a in $$all; do tidy -errors --gnu-emacs yes -quiet $$a; done;
generate: swightml.book swigpdf.book generate: swightml.book swigpdf.book
htmldoc --batch swightml.book htmldoc --batch swightml.book || true
htmldoc --batch swigpdf.book htmldoc --batch swigpdf.book
python fixstyle.py SWIGDocumentation.html
swightml.book: swightml.book:
echo "#HTMLDOC 1.8.23" > swightml.book echo "#HTMLDOC 1.8.23" > swightml.book

49
SWIG/Doc/Manual/Modula3.html
View file

@ -2,10 +2,12 @@
<html> <html>
<head> <head>
<title>SWIG and Modula-3</title> <title>SWIG and Modula-3</title>
<link rel="stylesheet" type="text/css" href="style.css"/>
</head> </head>
<body bgcolor="#FFFFFF"> <body bgcolor="#FFFFFF">
<H1><a name="Modula3"></a>20 SWIG and Modula-3</H1> <H1><a name="Modula3"></a>20 SWIG and Modula-3</H1>
<!-- INDEX --> <!-- INDEX -->
<div class="sectiontoc">
<ul> <ul>
<li><a href="#modula3_overview">Overview</a> <li><a href="#modula3_overview">Overview</a>
<ul> <ul>
@ -40,10 +42,12 @@
</ul> </ul>
<li><a href="#remarks">Remarks</a> <li><a href="#remarks">Remarks</a>
</ul> </ul>
</div>
<!-- INDEX --> <!-- INDEX -->
<p>
This chapter describes SWIG's support of This chapter describes SWIG's support of
<a href="http://www.m3.org/">Modula-3</a>. <a href="http://www.m3.org/">Modula-3</a>.
You should be familiar with the You should be familiar with the
@ -51,6 +55,7 @@ You should be familiar with the
of SWIG, of SWIG,
especially especially
<a href="Typemaps.html">typemaps</a>. <a href="Typemaps.html">typemaps</a>.
</p>
<H2><a name="modula3_overview"></a>20.1 Overview</H2> <H2><a name="modula3_overview"></a>20.1 Overview</H2>
@ -78,9 +83,11 @@ FFTW
</ol> </ol>
<p>
I took some more time to explain I took some more time to explain
why I think it's right what I'm doing. why I think it's right what I'm doing.
So the introduction got a bit longer than it should ... ;-) So the introduction got a bit longer than it should ... ;-)
</p>
<H3><a name="whyscripting"></a>20.1.1 Why not scripting ?</H3> <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. and the language definition is really compact.
</p> </p>
<p>
On the one hand Modula-3 can be safe On the one hand Modula-3 can be safe
(but probably less efficient) in normal modules (but probably less efficient) in normal modules
while providing much static and dynamic safety. while providing much static and dynamic safety.
On the other hand you can write efficient On the other hand you can write efficient
but less safe code in the style of C but less safe code in the style of C
within <tt>UNSAFE</tt> modules. within <tt>UNSAFE</tt> modules.
</p>
<p> <p>
Unfortunately Modula's safety and strength Unfortunately Modula's safety and strength
@ -337,8 +346,11 @@ generates several files:
</tr> </tr>
</table> </table>
<p>
Here's a scheme of how the function calls to Modula-3 wrappers Here's a scheme of how the function calls to Modula-3 wrappers
are redirected to C library functions: are redirected to C library functions:
</p>
<table summary="Modula-3 C library"> <table summary="Modula-3 C library">
<tr> <tr>
<td align=center> <td align=center>
@ -403,8 +415,11 @@ but C++ compilers should support generating C++ functions
with a C interface. with a C interface.
</p> </p>
<p>
Here's a scheme of how the function calls to Modula-3 wrappers Here's a scheme of how the function calls to Modula-3 wrappers
a redirected to C library functions: a redirected to C library functions:
</p>
<table summary="Modula-3 C++ library"> <table summary="Modula-3 C++ library">
<tr> <tr>
<td align=center> <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> <H3><a name="compilers"></a>20.3.1 Compilers</H3>
<p>
There are different Modula-3 compilers around: There are different Modula-3 compilers around:
cm3, pm3, ezm3, Klagenfurth Modula-3, Cambridge Modula-3. cm3, pm3, ezm3, Klagenfurth Modula-3, Cambridge Modula-3.
SWIG itself does not contain compiler specific code 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> <a href="../../Lib/modula3/modula3.swg"><tt>modula3.swg</tt></a>
may do so. may do so.
For testing examples I use Critical Mass cm3. For testing examples I use Critical Mass cm3.
</p>
<H3><a name="commandline"></a>20.3.2 Additional Commandline Options</H3> <H3><a name="commandline"></a>20.3.2 Additional Commandline Options</H3>
<p>
There are some experimental command line options There are some experimental command line options
that prevent SWIG from generating interface files. that prevent SWIG from generating interface files.
Instead files are emitted that may assist you Instead files are emitted that may assist you
when writing SWIG interface files. when writing SWIG interface files.
</p>
<table border summary="Modula-3 specific options"> <table border summary="Modula-3 specific options">
<tr> <tr>
@ -802,9 +821,12 @@ consist of the following parts:
<H3><a name="ordinals"></a>20.4.2 Subranges, Enumerations, Sets</H3> <H3><a name="ordinals"></a>20.4.2 Subranges, Enumerations, Sets</H3>
<p>
Subranges, enumerations, and sets are machine oriented types Subranges, enumerations, and sets are machine oriented types
that make Modula very strong and expressive compared that make Modula very strong and expressive compared
with the type systems of many other languages. with the type systems of many other languages.
</p>
<ul> <ul>
<li> <li>
Subranges are used for statically restricted choices of integers. 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. Sets are commonly used for flag (option) sets.
</li> </li>
</ul> </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. C supports enumerations, too, but they are not as safe as the ones of Modula.
Thus they are abused for many things: Thus they are abused for many things:
For named choices, for integer constant definitions, for sets. 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 is somewhere used for defining something
that must be handled completely different in Modula-3 that must be handled completely different in Modula-3
(<tt>INTEGER</tt>, enumeration, <tt>SET</tt>). (<tt>INTEGER</tt>, enumeration, <tt>SET</tt>).
</p>
<p>
I played around with several <tt>%feature</tt>s and <tt>%pragma</tt>s I played around with several <tt>%feature</tt>s and <tt>%pragma</tt>s
that split the task up into converting that split the task up into converting
the C bit patterns (integer or bit set) 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. to rewrite constant definitions manually.
Though this is a tedious work Though this is a tedious work
that I'd like to automate. that I'd like to automate.
</p>
<H3><a name="class"></a>20.4.3 Objects</H3> <H3><a name="class"></a>20.4.3 Objects</H3>
<p>
Declarations of C++ classes are mapped to <tt>OBJECT</tt> types Declarations of C++ classes are mapped to <tt>OBJECT</tt> types
while it is tried to retain the access hierarchy while it is tried to retain the access hierarchy
"public - protected - private" using partial revelation. "public - protected - private" using partial revelation.
Though the Though the
<a href="../../Examples/modula3/class/example.i">implementation</a> <a href="../../Examples/modula3/class/example.i">implementation</a>
is not really useful, yet. is not really useful, yet.
</p>
<H3><a name="imports"></a>20.4.4 Imports</H3> <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 For a monolithic module you might be better off
if you add the imports directly: if you add the imports directly:
</p> </p>
<div class="code">
<pre> <pre>
%insert(m3rawintf) %{ %insert(m3rawintf) %{
IMPORT M3toC; IMPORT M3toC;
%} %}
</pre> </pre></div>
<H3><a name="exceptions"></a>20.4.5 Exceptions</H3> <H3><a name="exceptions"></a>20.4.5 Exceptions</H3>
<p>
Modula-3 provides another possibility Modula-3 provides another possibility
of an output of a function: exceptions. of an output of a function: exceptions.
</p>
<p>
Any piece of Modula-3 code that SWIG inserts Any piece of Modula-3 code that SWIG inserts
due to a typemap can raise an exception. due to a typemap can raise an exception.
This way you can also convert an error code This way you can also convert an error code
from a C function into a Modula-3 exception. from a C function into a Modula-3 exception.
</p>
<p>
The <tt>RAISES</tt> clause is controlled The <tt>RAISES</tt> clause is controlled
by typemaps with the <tt>throws</tt> extension. by typemaps with the <tt>throws</tt> extension.
If the typemap <tt>m3wrapinconv</tt> for <tt>blah *</tt> If the typemap <tt>m3wrapinconv</tt> for <tt>blah *</tt>
contains code that may raise the exceptions <tt>OSError.E</tt> contains code that may raise the exceptions <tt>OSError.E</tt>
you should declare you should declare
<tt>%typemap("m3wrapinconv:throws") blah * %{OSError.E%}</tt>. <tt>%typemap("m3wrapinconv:throws") blah * %{OSError.E%}</tt>.
</p>
<H3><a name="typemap_example"></a>20.4.6 Example</H3> <H3><a name="typemap_example"></a>20.4.6 Example</H3>
<p>
The generation of wrappers in Modula-3 needs very fine control The generation of wrappers in Modula-3 needs very fine control
to take advantage of the language features. to take advantage of the language features.
Here is an example of a generated wrapper Here is an example of a generated wrapper
where almost everything is generated by a typemap: where almost everything is generated by a typemap:
</p>
<blockquote><pre> <div class="code"><pre>
<I> (* %relabel m3wrapinmode m3wrapinname m3wrapintype m3wrapindefault *)</I> <I> (* %relabel m3wrapinmode m3wrapinname m3wrapintype m3wrapindefault *)</I>
PROCEDURE Name (READONLY str : TEXT := "" ) PROCEDURE Name (READONLY str : TEXT := "" )
<I> (* m3wrapoutcheck:throws *)</I> <I> (* m3wrapoutcheck:throws *)</I>
@ -945,7 +986,7 @@ where almost everything is generated by a typemap:
M3toC.FreeSharedS(str,arg1); <I>(* m3wrapfreearg *)</I> M3toC.FreeSharedS(str,arg1); <I>(* m3wrapfreearg *)</I>
END; END;
END Name; END Name;
</pre></blockquote> </pre></div>
<H2><a name="hints"></a>20.5 More hints to the generator</H2> <H2><a name="hints"></a>20.5 More hints to the generator</H2>

29
SWIG/Doc/Manual/Modules.html
View file

@ -2,22 +2,26 @@
<html> <html>
<head> <head>
<title>Working with Modules</title> <title>Working with Modules</title>
<link rel="stylesheet" type="text/css" href="style.css"/>
</head> </head>
<body bgcolor="#ffffff"> <body bgcolor="#ffffff">
<H1><a name="Modules"></a>15 Working with Modules</H1> <H1><a name="Modules"></a>15 Working with Modules</H1>
<!-- INDEX --> <!-- INDEX -->
<div class="sectiontoc">
<ul> <ul>
<li><a href="#Modules_nn2">The SWIG runtime code</a> <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_nn4">A word of caution about static libraries</a>
<li><a href="#Modules_nn5">References</a> <li><a href="#Modules_nn5">References</a>
<li><a href="#Modules_nn6">Reducing the wrapper file size</a> <li><a href="#Modules_nn6">Reducing the wrapper file size</a>
</ul> </ul>
</div>
<!-- INDEX --> <!-- INDEX -->
<p>
When first working with SWIG, users commonly start by creating a When first working with SWIG, users commonly start by creating a
single module. That is, you might define a single SWIG interface that 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 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 this approach is problematic---the size of the generated wrapper code
can be rather large. Moreover, it is probably easier to manage the can be rather large. Moreover, it is probably easier to manage the
target language interface when it is broken up into smaller pieces. target language interface when it is broken up into smaller pieces.
</p>
<p> <p>
This chapter describes the problem of using SWIG in programs 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> <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 Many of SWIG's target languages generate a set of functions
commonly known as the "SWIG runtime." These functions are commonly known as the "SWIG runtime." These functions are
primarily related to the runtime type system which checks pointer 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 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 have no need for a SWIG runtime. All the dynamically typed / interpreted
languages rely on the SWIG runtime. languages rely on the SWIG runtime.
</p>
<p> <p>
The runtime functions are private to each SWIG-generated 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. languages provide. One solution is to load all modules before spawning any threads.
</p> </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>, <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 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 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: 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; $ 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 <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 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> <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 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 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 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 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. 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> <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 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. 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> <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. 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>
<p>
<b>-fcompact</b><br> <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. 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. 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. This is useful for compilers that have a maximum file size that can be handled.
</p>
<p> <p>
<b>-fvirtual</b><br> <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: Consider the following inheritance hierarchy:
</p> </p>
<blockquote> <div class="code">
<pre> <pre>
struct Base { struct Base {
virtual void method(); virtual void method();
@ -145,10 +159,13 @@ struct Derived : Base {
... ...
}; };
</pre> </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>. 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 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>. a <tt>Derived</tt> instance and call the wrapper for <tt>Base::method</tt>.
</p>
<p> <p>
<b>%feature("compactdefaultargs")</b><br> <b>%feature("compactdefaultargs")</b><br>

19
SWIG/Doc/Manual/Mzscheme.html
View file

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

83
SWIG/Doc/Manual/Ocaml.html
View file

@ -2,12 +2,13 @@
<html> <html>
<head> <head>
<title>SWIG and Ocaml</title> <title>SWIG and Ocaml</title>
<link rel="stylesheet" type="text/css" href="style.css"/>
</head> </head>
<body bgcolor="#ffffff"> <body bgcolor="#ffffff">
<a name="n1"></a> <a name="n1"></a>
<H1><a name="Ocaml"></a>22 SWIG and Ocaml</H1> <H1><a name="Ocaml"></a>22 SWIG and Ocaml</H1>
<!-- INDEX --> <!-- INDEX -->
<div class="sectiontoc">
<ul> <ul>
<li><a href="#Ocaml_nn2">Preliminaries</a> <li><a href="#Ocaml_nn2">Preliminaries</a>
<ul> <ul>
@ -52,10 +53,12 @@
<li><a href="#Ocaml_nn31">Exceptions</a> <li><a href="#Ocaml_nn31">Exceptions</a>
</ul> </ul>
</ul> </ul>
</div>
<!-- INDEX --> <!-- INDEX -->
<p>
This chapter describes SWIG's This chapter describes SWIG's
support of Ocaml. Ocaml is a relatively recent addition to the ML family, 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 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. which creates and uses Ocaml values to communicate with C and C++ code.
In addition, SWIG also produces the needed Ocaml source that binds In addition, SWIG also produces the needed Ocaml source that binds
variants, functions, classes, etc. variants, functions, classes, etc.
</p>
<p> <p>
If you're not familiar with the Objective Caml language, you can visit 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> <H2><a name="Ocaml_nn2"></a>22.1 Preliminaries</H2>
<p>
SWIG 1.3 works with Ocaml 3.04 and above. Given the choice, 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 you should use the latest stable release. The SWIG Ocaml module has
been tested on Linux (x86,PPC,Sparc) and Cygwin on Windows. The 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 </a>. The ocaml_dynamic and ocaml_dynamic_cpp targets in the
file Examples/Makefile illustrate how to compile and link SWIG modules that 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. 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> <H3><a name="Ocaml_nn3"></a>22.1.1 Running SWIG</H3>
<p>
The basics of getting a SWIG Ocaml module up and running 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 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> here. To build an Ocaml module, run SWIG using the <tt>-ocaml</tt>
option. option.
</p>
<blockquote> <div class="code">
<pre> <pre>
%swig -ocaml example.i %swig -ocaml example.i
</pre> </pre>
</blockquote> </div>
<p> This will produce 3 files. The file <tt>example_wrap.c</tt> contains <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, 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: SWIG interface like:
</p> </p>
<blockquote> <div class="code">
<pre> <pre>
% swig -ocaml -co swig.mli ; swig -ocaml co swig.ml % swig -ocaml -co swig.mli ; swig -ocaml co swig.ml
% ocamlc -c swig.mli ; ocamlc -c 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.mli
% ocamlc -c example.ml % ocamlc -c example.ml
</pre> </pre>
</blockquote> </div>
<p> <tt>ocamlc</tt> is aware of .c files and knows how to handle them. Unfortunately, <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 it does not know about .cxx, .cc, or .cpp files, so when SWIG is invoked
in C++ mode, you must: </p> in C++ mode, you must: </p>
<blockquote> <div class="code">
<pre> <pre>
% cp example_wrap.cxx example_wrap.cxx.c<br>% ocamlc -c ... -ccopt -xc++ example_wrap.cxx.c<br>% ...<br> % cp example_wrap.cxx example_wrap.cxx.c<br>% ocamlc -c ... -ccopt -xc++ example_wrap.cxx.c<br>% ...<br>
</pre> </pre>
</blockquote> </div>
<H3><a name="Ocaml_nn5"></a>22.1.3 The camlp4 module</H3> <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> objective caml.<br>
</p> </p>
<blockquote><pre> <div class="code"><pre>
type c_obj = type c_obj =
C_void C_void
| C_bool of bool | C_bool of bool
@ -288,8 +296,11 @@ type c_obj =
| C_obj of (string -&gt; c_obj -&gt; c_obj) | C_obj of (string -&gt; c_obj -&gt; c_obj)
| C_string of string | C_string of string
| C_enum of c_enum_t | C_enum of c_enum_t
</pre></blockquote> </pre></div>
A few functions exist which generate and return these:<br>
<p>
A few functions exist which generate and return these:
</p>
<ul> <ul>
<li>caml_ptr_val receives a c_obj and returns a void *. &nbsp;This <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: argument. Example:
</p> </p>
<blockquote><pre> <div class="code"><pre>
%module enum_test %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 };
%} %}
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> <p>
The output mli contains: The output mli contains:
</p> </p>
<blockquote><pre> <div class="code"><pre>
type c_enum_type = [ type c_enum_type = [
`unknown `unknown
| `c_enum_type | `c_enum_type
@ -424,9 +435,13 @@ type c_enum_tag = [
val int_to_enum c_enum_type -&gt; int -&gt; c_obj 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 val enum_to_int c_enum_type -&gt; c_obj -&gt; c_obj
</pre> </pre>
</blockquote> </div>
<p>
So it's possible to do this: So it's possible to do this:
<blockquote> </p>
<div class="code">
<pre> <pre>
bash-2.05a$ ocamlmktop -custom enum_test_wrap.o enum_test.cmo -o enum_test_top bash-2.05a$ ocamlmktop -custom enum_test_wrap.o enum_test.cmo -o enum_test_top
bash-2.05a$ ./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 ;; # int_to_enum `c_enum_type 4 ;;
- : Enum_test.c_obj = C_enum `c - : Enum_test.c_obj = C_enum `c
</pre> </pre>
</blockquote> </div>
<H4><a name="Ocaml_nn11"></a>22.2.2.1 Enum typing in Ocaml</H4> <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 The ocaml SWIG module now has support for loading and using multiple SWIG
modules at the same time. This enhances modularity, but presents problems 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 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 isolated per-module. The type issue matters when values are shared between
functions imported from different modules. You must convert values to master functions imported from different modules. You must convert values to master
values using the swig_val function before sharing them with another module. values using the swig_val function before sharing them with another module.
</p>
<H3><a name="Ocaml_nn12"></a>22.2.3 Arrays</H3> <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> <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 C++ classes, along with structs and unions are represented by C_obj
(string -&gt; c_obj -&gt; c_obj) wrapped closures. &nbsp;These objects (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 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 and each method table exists in memory only once. &nbsp;In addition
to any other operators an object might have, certain builtin ones are to any other operators an object might have, certain builtin ones are
provided by SWIG: (all of these take no arguments (C_void)) provided by SWIG: (all of these take no arguments (C_void))
</p>
<table summary="SWIG provided operators"> <table summary="SWIG provided operators">
<tr><td>"~"</td><td>Delete this object</td></tr> <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. argument. With zero arguments, the value is returned.
</td></tr> </td></tr>
</table> </table>
<p>
Note that this string belongs to the wrapper object, and not Note that this string belongs to the wrapper object, and not
the underlying pointer, so using create_[x]_from_ptr alters the the underlying pointer, so using create_[x]_from_ptr alters the
returned value for the same object. returned value for the same object.
</p>
<H4><a name="Ocaml_nn18"></a>22.2.4.1 STL vector and string Example</H4> <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 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 the works. STL strings are passed just like normal strings, and returned
as strings. STL string references don't mutate the original string, (which as strings. STL string references don't mutate the original string, (which
might be surprising), because Ocaml strings are mutable but have fixed might be surprising), because Ocaml strings are mutable but have fixed
length. Instead, use multiple returns, as in the argout_ref example. length. Instead, use multiple returns, as in the argout_ref example.
</p>
<table border="1" bgcolor="#dddddd" summary="STL vector and string example"> <table border="1" bgcolor="#dddddd" summary="STL vector and string example">
<tr><th><center>example.i</center></th></tr> <tr><th><center>example.i</center></th></tr>
@ -632,7 +656,7 @@ after making a toplevel (make toplevel). This example uses the camlp4
module. module.
</p> </p>
<blockquote><pre> <div class="code"><pre>
bash-2.05a$ ./example_top bash-2.05a$ ./example_top
Objective Caml version 3.06 Objective Caml version 3.06
@ -669,12 +693,14 @@ bar
baz baz
- : unit = () - : unit = ()
# #
</pre></blockquote> </pre></div>
<H4><a name="Ocaml_nn19"></a>22.2.4.2 C++ Class Example</H4> <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: Here's a simple example using Trolltech's Qt Library:
</p>
<table border="1" bgcolor="#dddddd" summary="Qt Library example"> <table border="1" bgcolor="#dddddd" summary="Qt Library example">
<tr><th><center>qt.i</center></th></tr> <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> <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$ 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$ 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 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` \ bash-2.05a$ ocamlmktop -custom swig.cmo -I `camlp4 -where` \
camlp4o.cma swigp4.cmo qt_wrap.o qt.cmo -o qt_top -cclib \ camlp4o.cma swigp4.cmo qt_wrap.o qt.cmo -o qt_top -cclib \
-L$QTPATH/lib -cclib -lqt -L$QTPATH/lib -cclib -lqt
</pre></blockquote> </pre></div>
<H4><a name="Ocaml_nn21"></a>22.2.4.4 Sample Session</H4> <H4><a name="Ocaml_nn21"></a>22.2.4.4 Sample Session</H4>
<blockquote><pre> <div class="code"><pre>
bash-2.05a$ ./qt_top bash-2.05a$ ./qt_top
Objective Caml version 3.06 Objective Caml version 3.06
@ -737,7 +763,7 @@ val hello : Qt.c_obj = C_obj &lt;fun&gt;
# hello -&gt; show () ;; # hello -&gt; show () ;;
- : Qt.c_obj = C_void - : Qt.c_obj = C_void
# a -&gt; exec () ;; # a -&gt; exec () ;;
</pre></blockquote> </pre></div>
<p> <p>
Assuming you have a working installation of QT, you will see a window 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: this:
</p> </p>
<blockquote><pre> <div class="code"><pre>
%module(directors="1") %module(directors="1")
... ...
@ -772,7 +798,7 @@ this:
class foo { class foo {
... ...
}; };
</pre></blockquote> </pre></div>
<H4><a name="Ocaml_nn24"></a>22.2.5.2 Overriding Methods in Ocaml</H4> <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> <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: The definition of the actual object triangle can be described this way:
<blockquote><pre> </p>
<div class="code"><pre>
let triangle = let triangle =
new_derived_object new_derived_object
new_shape new_shape
(triangle_class ((0.0,0.0),(0.5,1.0),(1.0,0.0))) (triangle_class ((0.0,0.0),(0.5,1.0),(1.0,0.0)))
'() '()
</pre></blockquote> </pre></div>
<p> <p>
The first argument to <tt>new_derived_object</tt>, new_shape is the method 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> <H3><a name="Ocaml_nn31"></a>22.2.6 Exceptions</H3>
<p>
Catching exceptions is now supported using SWIG's %exception feature. A simple 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 but not too useful example is provided by the throw_exception testcase in
Examples/test-suite. You can provide your own exceptions, too. Examples/test-suite. You can provide your own exceptions, too.
</p>
</body> </body>
</html> </html>

725
SWIG/Doc/Manual/Perl5.html
View file

File diff suppressed because it is too large Load diff

115
SWIG/Doc/Manual/Php.html
View file

@ -3,11 +3,13 @@
<html> <html>
<head> <head>
<title>SWIG and PHP4</title> <title>SWIG and PHP4</title>
<link rel="stylesheet" type="text/css" href="style.css"/>
</head> </head>
<body bgcolor="#ffffff"> <body bgcolor="#ffffff">
<H1><a name="Php"></a>24 SWIG and PHP4</H1> <H1><a name="Php"></a>24 SWIG and PHP4</H1>
<!-- INDEX --> <!-- INDEX -->
<div class="sectiontoc">
<ul> <ul>
<li><a href="#Php_nn2">Preliminaries</a> <li><a href="#Php_nn2">Preliminaries</a>
<li><a href="#Php_nn3">Building PHP4 Extensions</a> <li><a href="#Php_nn3">Building PHP4 Extensions</a>
@ -27,6 +29,7 @@
<li><a href="#Php_nn16">To be furthered...</a> <li><a href="#Php_nn16">To be furthered...</a>
</ul> </ul>
</ul> </ul>
</div>
<!-- INDEX --> <!-- INDEX -->
@ -52,12 +55,14 @@ of in the generated .php file in php.
<H2><a name="Php_nn2"></a>24.1 Preliminaries</H2> <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 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 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 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 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 extension into php directly (without having the overhead of loading it into
each script), you will need the complete PHP source tree available. each script), you will need the complete PHP source tree available.
</p>
<H2><a name="Php_nn3"></a>24.2 Building PHP4 Extensions</H2> <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 : To build a PHP4 extension, run swig using the <tt>-php4</tt> option as follows :
</p> </p>
<blockquote><pre> <div class="code"><pre>
swig -php4 example.i swig -php4 example.i
</pre></blockquote> </pre></div>
<p> <p>
This will produce 3 files by default. The first file, <tt>example_wrap.c</tt> 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 To build manually, use a compile string similar to this (different for each
OS): OS):
</p> </p>
<blockquote><pre> <div class="code"><pre>
cc -I.. $(PHPINC) -fpic -c example_wrap.c cc -I.. $(PHPINC) -fpic -c example_wrap.c
cc -shared example_wrap.o -o libexample.so cc -shared example_wrap.o -o libexample.so
</pre></blockquote> </pre></div>
<p> <p>
To build with phpize, after you have run swig you will need 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. files for you.
</p> </p>
<blockquote><pre> <div class="code"><pre>
swig -php4 -phpfull -withlibs "xapian omquery" --withincs "om.h" swig -php4 -phpfull -withlibs "xapian omquery" --withincs "om.h"
</pre></blockquote> </pre></div>
<p> <p>
Will include in the config.m4 search for libxapian.a or libxapian.so and 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, this by putting the line,
</p> </p>
<blockquote><pre> <div class="code"><pre>
dl("/path/to/modulename.so"); // Load the module 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 at the start of each PHP file. SWIG also generates a php module, which
attempts to do the <tt>dl()</tt> call for you: attempts to do the <tt>dl()</tt> call for you:
<blockquote><pre> </p>
include("example.php");
</pre></blockquote>
<div class="code"><pre>
include("example.php");
</pre></div>
<p>
A more complicated method which builds the module directly into the <tt>php</tt> A more complicated method which builds the module directly into the <tt>php</tt>
executable is described <a href="n12">below</a>. executable is described <a href="n12">below</a>.
</p>
<H3><a name="Php_nn5"></a>24.2.2 Basic PHP4 interface</H3> <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 : also allowed. An interface file like this :
</p> </p>
<blockquote><pre> <div class="code"><pre>
%module default %module default
int foo(int a); int foo(int a);
double bar(double, double b = 3.0); double bar(double, double b = 3.0);
... ...
</pre></blockquote> </pre></div>
<p> <p>
Will be accessed in PHP like this : Will be accessed in PHP like this :
</p> </p>
<blockquote><pre> <div class="code"><pre>
dl("default.so"); $a = foo(2); dl("default.so"); $a = foo(2);
$b = bar(3.5, -1.5); $b = bar(3.5, -1.5);
$c = bar(3.5); # Use default argument for 2nd parameter $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> <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. is handled for you, you can modify the variables in PHP as normal, e.g.
</p> </p>
<blockquote><pre> <div class="code"><pre>
%module example; %module example;
... ...
double seki = 2; double seki = 2;
... ...
int example_func(void); int example_func(void);
</pre></blockquote> </pre></div>
<p> <p>
is accessed as follow : is accessed as follow :
</p> </p>
<blockquote><pre> <div class="code"><pre>
dl("example.so"); dl("example.so");
print $seki; print $seki;
$seki = $seki * 2; # Does not affect C variable, still equal to 2 $seki = $seki * 2; # Does not affect C variable, still equal to 2
example_func(); # Syncs C variable to PHP Variable, now both 4 example_func(); # Syncs C variable to PHP Variable, now both 4
</pre></blockquote> </pre></div>
<p> <p>
SWIG supports global variables of all C datatypes including pointers and complex 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 : For structures and classes, SWIG produces accessor fuction for each member function and data. For example :
</p> </p>
<blockquote><pre> <div class="code"><pre>
%module vector %module vector
class Vector { class Vector {
@ -273,13 +284,13 @@ public:
double magnitude(); double magnitude();
}; };
</pre></blockquote> </pre></div>
<p> <p>
This gets turned into the following collection of PHP functions : This gets turned into the following collection of PHP functions :
</p> </p>
<blockquote><pre> <div class="code"><pre>
Vector_x_set($obj); Vector_x_set($obj);
Vector_x_get($obj); Vector_x_get($obj);
Vector_y_set($obj); Vector_y_set($obj);
@ -290,10 +301,13 @@ new_Vector();
delete_Vector($obj); delete_Vector($obj);
Vector_magnitude($obj); Vector_magnitude($obj);
</pre></blockquote> </pre></div>
<p>
To use the class, simply use these functions. However, SWIG also has a mechanism 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 for creating proxy classes that hides these functions and uses an object
oriented interface instead - see <a href="n7">below</a> oriented interface instead - see <a href="n7">below</a>
</p>
<H3><a name="Php_nn10"></a>24.2.7 Constants</H3> <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, (e.g. no dollar sign is needed to access them. ) For example, with a swig file like this,
</p> </p>
<blockquote><pre> <div class="code"><pre>
%module example %module example
#define PI 3.14159 #define PI 3.14159
%constant int E = 2.71828 %constant int E = 2.71828
</pre> </pre>
</blockquote> </div>
<p> <p>
you can access from in your php script like this, you can access from in your php script like this,
</p> </p>
<blockquote><pre> <div class="code"><pre>
dl("libexample.so"); dl("libexample.so");
echo "PI = " . PI . "\n"; echo "PI = " . PI . "\n";
@ -326,7 +340,7 @@ echo "PI = " . PI . "\n";
echo "E = " . E . "\n"; echo "E = " . E . "\n";
</pre> </pre>
</blockquote> </div>
<p> <p>
There are two peculiarities with using constants in PHP4. The first is that 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, set to the constants name. For example,
</p> </p>
<blockquote><pre> <div class="code"><pre>
%module example %module example
#define EASY_TO_MISPELL 0 #define EASY_TO_MISPELL 0
</pre> </pre>
</blockquote> </div>
<p> <p>
accessed incorrectly in PHP, accessed incorrectly in PHP,
</p> </p>
<blockquote> <div class="code">
<pre> <pre>
dl("libexample.so"); dl("libexample.so");
@ -356,7 +370,7 @@ if(EASY_TO_MISPEL) {
} }
</pre> </pre>
</blockquote> </div>
<p> <p>
will issue a warning about the undeclared constant, but will then evalute 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., you cannot declare a constant twice with alternative cases. E.g.,
</p> </p>
<blockquote> <div class="code">
<pre> <pre>
%module example %module example
#define TEST Hello #define TEST Hello
#define Test World #define Test World
</pre> </pre>
</blockquote> </div>
<p> <p>
accessed from PHP, accessed from PHP,
</p> </p>
<blockquote> <div class="code">
<pre> <pre>
dl("libexample.so"); dl("libexample.so");
echo TEST, Test; echo TEST, Test;
</pre> </pre>
</blockquote> </div>
<p> <p>
will output "Hello Test" rather than "Hello World". This is because internally, 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 : To have SWIG create proxy classes, use the <tt>-proxy</tt> option :
</p> </p>
<blockquote><pre> <div class="code"><pre>
% swig -php4 -proxy tbc.i % swig -php4 -proxy tbc.i
</pre></blockquote> </pre></div>
<p> <p>
This will produce the same files as before except that the final module 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> <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 Class variables are not supported in PHP, however class functions are, using
'::' syntax. Static member variables are therefore accessed using a class '::' 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 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 %module example
class Ko { class Ko {
@ -485,38 +501,43 @@ class Ko {
... ...
}; };
</pre></blockquote> </pre></div>
<p> <p>
would be accessed in PHP as, would be accessed in PHP as,
</p> </p>
<blockquote><pre> <div class="code"><pre>
dl("libexample.so"); dl("libexample.so");
echo "There has now been " . Ko::threats() . " threats\n"; 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. 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); Ko::threats(10);
echo "There has now been " . Ko::threats() . " threats\n"; 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> <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, 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 <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, 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() <b>phpinfo</b> inserts code to the function called when PHP's phpinfo()
function is called. function is called.
</p>
<blockquote><pre> <div class="code"><pre>
/* example.i */ /* example.i */
%pragma(php4) include="foo.php" %pragma(php4) include="foo.php"
@ -534,7 +555,7 @@ function is called.
" "
%include "example.h" %include "example.h"
</pre></blockquote> </pre></div>
<H3><a name="Php_nn15"></a>24.2.12 Building extensions into php</H3> <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> make use of <tt>-withlibs</tt> and <tt>-withincs</tt>
</p> </p>
<blockquote><pre> <div class="code"><pre>
swig -php4 -phpfull -withlibs "xapian omquery" --withincs "om.h" swig -php4 -phpfull -withlibs "xapian omquery" --withincs "om.h"
</pre></blockquote> </pre></div>
<p> <p>
Will include in the config.m4 and Makefile.in search for libxapian.a or Will include in the config.m4 and Makefile.in search for libxapian.a or

78
SWIG/Doc/Manual/Pike.html
View file

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

35
SWIG/Doc/Manual/Preface.html
View file

@ -2,11 +2,13 @@
<html> <html>
<head> <head>
<title>Preface</title> <title>Preface</title>
<link rel="stylesheet" type="text/css" href="style.css"/>
</head> </head>
<body bgcolor="#ffffff"> <body bgcolor="#ffffff">
<H1><a name="Preface"></a>1 Preface</H1> <H1><a name="Preface"></a>1 Preface</H1>
<!-- INDEX --> <!-- INDEX -->
<div class="sectiontoc">
<ul> <ul>
<li><a href="#Preface_nn2">Introduction</a> <li><a href="#Preface_nn2">Introduction</a>
<li><a href="#Preface_nn3">Special Introduction for Version 1.3</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_nn10">Credits</a>
<li><a href="#Preface_nn11">Bug reports</a> <li><a href="#Preface_nn11">Bug reports</a>
</ul> </ul>
</div>
<!-- INDEX --> <!-- INDEX -->
@ -26,6 +29,7 @@
<H2><a name="Preface_nn2"></a>1.1 Introduction</H2> <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 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 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 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 types of problems. SWIG simplifies development by largely automating
the task of scripting language integration--allowing developers and users the task of scripting language integration--allowing developers and users
to focus on more important problems. to focus on more important problems.
</p>
<p> <p>
Although SWIG was originally developed for scientific applications, it 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> <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 Since SWIG was released in 1996, its user base and applicability has
continued to grow. Although its rate of development has varied, an continued to grow. Although its rate of development has varied, an
active development effort has continued to make improvements to the 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 all of the ANSI C++ standard and approximately ten target languages
including Guile, Java, Mzscheme, Ocaml, Perl, Pike, PHP, Python, Ruby, including Guile, Java, Mzscheme, Ocaml, Perl, Pike, PHP, Python, Ruby,
and Tcl. and Tcl.
</p>
<H2><a name="Preface_nn4"></a>1.3 SWIG Versions</H2> <H2><a name="Preface_nn4"></a>1.3 SWIG Versions</H2>
<p>
For several years, the most stable version of SWIG has been release 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 1.1p5. Starting with version 1.3, a new version numbering scheme has
been adopted. Odd version numbers (1.3, 1.5, etc.) represent 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 represent stable releases. Currently, developers are working to
create a stable SWIG-2.0 release. Don't let the development status 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. of SWIG-1.3 scare you---it is much more stable (and capable) than SWIG-1.1p5.
</p>
<H2><a name="Preface_nn5"></a>1.4 SWIG resources</H2> <H2><a name="Preface_nn5"></a>1.4 SWIG resources</H2>
<p>
The official location of SWIG related material is 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> <a href="http://www.swig.org">http://www.swig.org</a>
</pre></blockquote> </pre></div>
<p> <p>
This site contains the latest version of the software, users guide, 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 You can also subscribe to the SWIG mailing list by visiting the page
</p> </p>
<blockquote><pre> <div class="code"><pre>
<a href="http://www.swig.org/mail.html">http://www.swig.org/mail.html</a> <a href="http://www.swig.org/mail.html">http://www.swig.org/mail.html</a>
</pre></blockquote> </pre></div>
<p> <p>
The mailing list often discusses some of the more technical aspects of 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: about this can be obtained at:
</p> </p>
<blockquote><pre> <div class="code"><pre>
<a href="http://www.swig.org/cvs.html">http://www.swig.org/cvs.html</a> <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> <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> <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 The first few chapters of this manual describe SWIG in general and
provide an overview of its capabilities. The remaining chapters are provide an overview of its capabilities. The remaining chapters are
devoted to specific SWIG language modules and are self 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 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 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. 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> <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 If you hate reading manuals, glance at the "Introduction" which
contains a few simple examples. These contains a few simple examples. These
examples contain about 95% of everything you need to know to use examples contain about 95% of everything you need to know to use
SWIG. After that, simply use the language-specific chapters as a reference. SWIG. After that, simply use the language-specific chapters as a reference.
The SWIG distribution also comes with a large directory of The SWIG distribution also comes with a large directory of
examples that illustrate different topics. examples that illustrate different topics.
</p>
<H2><a name="Preface_nn9"></a>1.8 Backwards Compatibility</H2> <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: advantage of different features etc:
</p> </p>
<blockquote><pre> <div class="code"><pre>
#if SWIG_VERSION &gt;= 0x010311 #if SWIG_VERSION &gt;= 0x010311
/* Use some fancy new feature */ /* Use some fancy new feature */
#endif #endif
</pre></blockquote> </pre></div>
<p> <p>
Note: The version symbol is not defined in the generated SWIG 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> <H2><a name="Preface_nn10"></a>1.9 Credits</H2>
<p>
SWIG is an unfunded project that would not be possible without the SWIG is an unfunded project that would not be possible without the
contributions of many people. Most recent SWIG development has been contributions of many people. Most recent SWIG development has been
supported by Matthias K&ouml;ppe, William Fulton, Lyle Johnson, supported by Matthias K&ouml;ppe, William Fulton, Lyle Johnson,
Richard Palmer, Thien-Thi Nguyen, Jason Stewart, Loic Dachary, Masaki Richard Palmer, Thien-Thi Nguyen, Jason Stewart, Loic Dachary, Masaki
Fukushima, Luigi Ballabio, Sam Liddicott, Art Yerkes, Marcelo Matus, Fukushima, Luigi Ballabio, Sam Liddicott, Art Yerkes, Marcelo Matus,
Harco de Hilster, and John Lenz. Harco de Hilster, and John Lenz.
</p>
<p> <p>
Historically, the following people contributed to early versions of SWIG. 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> <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 Although every attempt has been made to make SWIG bug-free, we are also trying
to make feature improvements that may introduce bugs. to make feature improvements that may introduce bugs.
To report a bug, either send mail to the SWIG developer 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 core dump occurred), corresponding portions of the SWIG interface file
used, and any important pieces of the SWIG generated wrapper code. We used, and any important pieces of the SWIG generated wrapper code. We
can only fix bugs if we know about them. can only fix bugs if we know about them.
</p>
</body> </body>
</html> </html>

98
SWIG/Doc/Manual/Preprocessor.html
View file

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

1171
SWIG/Doc/Manual/Python.html
View file

File diff suppressed because it is too large Load diff

14
SWIG/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 script. The Makefile has further information on how the various alternative
forms of the documentation is generated from the hand-written HTML. 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
SWIG/Doc/Manual/Ruby.html
View file

File diff suppressed because it is too large Load diff

704
SWIG/Doc/Manual/SWIG.html
View file

File diff suppressed because it is too large Load diff

1107
SWIG/Doc/Manual/SWIGPlus.html
View file

File diff suppressed because it is too large Load diff

93
SWIG/Doc/Manual/Scripting.html
View file

@ -2,11 +2,13 @@
<html> <html>
<head> <head>
<title>Scripting Languages</title> <title>Scripting Languages</title>
<link rel="stylesheet" type="text/css" href="style.css"/>
</head> </head>
<body bgcolor="#ffffff"> <body bgcolor="#ffffff">
<H1><a name="Scripting"></a>4 Scripting Languages</H1> <H1><a name="Scripting"></a>4 Scripting Languages</H1>
<!-- INDEX --> <!-- INDEX -->
<div class="sectiontoc">
<ul> <ul>
<li><a href="#Scripting_nn2">The two language view of the world</a> <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> <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> <li><a href="#Scripting_nn12">Static linking</a>
</ul> </ul>
</ul> </ul>
</div>
<!-- INDEX --> <!-- INDEX -->
<p>
This chapter provides a brief overview of scripting language extension This chapter provides a brief overview of scripting language extension
programming and the mechanisms by which scripting language interpreters programming and the mechanisms by which scripting language interpreters
access C and C++ code. access C and C++ code.
</p>
<H2><a name="Scripting_nn2"></a>4.1 The two language view of the world</H2> <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> <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 Scripting languages are built around a parser that knows how
to execute commands and scripts. Within this parser, there is a to execute commands and scripts. Within this parser, there is a
mechanism for executing commands and accessing variables. 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. most languages define a special API for adding new commands.
Furthermore, a special foreign function interface defines how these Furthermore, a special foreign function interface defines how these
new commands are supposed to hook into the interpreter. new commands are supposed to hook into the interpreter.
</p>
<p> <p>
Typically, when you add a new command to a scripting interpreter Typically, when you add a new command to a scripting interpreter
@ -92,12 +99,12 @@ the process.
<p> <p>
Suppose you have an ordinary C function like this :</p> Suppose you have an ordinary C function like this :</p>
<blockquote><pre> <div class="code"><pre>
int fact(int n) { int fact(int n) {
if (n &lt;= 1) return 1; if (n &lt;= 1) return 1;
else return n*fact(n-1); else return n*fact(n-1);
} }
</pre></blockquote> </pre></div>
<p> <p>
In order to access this function from a scripting language, it is 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> As an example, the Tcl wrapper function for the <tt>fact()</tt>
function above example might look like the following : </p> function above example might look like the following : </p>
<blockquote><pre> <div class="code"><pre>
int wrap_fact(ClientData clientData, Tcl_Interp *interp, int wrap_fact(ClientData clientData, Tcl_Interp *interp,
int argc, char *argv[]) { int argc, char *argv[]) {
int result; int result;
@ -130,7 +137,7 @@ int wrap_fact(ClientData clientData, Tcl_Interp *interp,
return TCL_OK; return TCL_OK;
} }
</pre></blockquote> </pre></div>
<p> <p>
Once you have created a wrapper function, the final step is to tell the 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 loaded. For example, adding the above function to the Tcl interpreter
requires code like the following :</p> requires code like the following :</p>
<blockquote><pre> <div class="code"><pre>
int Wrap_Init(Tcl_Interp *interp) { int Wrap_Init(Tcl_Interp *interp) {
Tcl_CreateCommand(interp, "fact", wrap_fact, (ClientData) NULL, Tcl_CreateCommand(interp, "fact", wrap_fact, (ClientData) NULL,
(Tcl_CmdDeleteProc *) NULL); (Tcl_CmdDeleteProc *) NULL);
return TCL_OK; return TCL_OK;
} }
</pre></blockquote> </pre></div>
<p> <p>
When executed, Tcl will now have a new command called "<tt>fact</tt>" 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 language interpeter. For example, suppose you had the following
variable:</p> variable:</p>
<blockquote><pre> <div class="code"><pre>
double Foo = 3.5; double Foo = 3.5;
</pre></blockquote> </pre></div>
<p> <p>
It might be nice to access it from a script as follows (shown for Perl):</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 $a = $Foo * 2.3; # Evaluation
$Foo = $a + 2.0; # Assignment $Foo = $a + 2.0; # Assignment
</pre></blockquote> </pre></div>
<p> <p>
To provide such access, variables are commonly manipulated using a 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> <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 In many cases, a C program or library may define a large collection of
constants. For example: constants. For example:
</p>
<blockquote><pre> <div class="code"><pre>
#define RED 0xff0000 #define RED 0xff0000
#define BLUE 0x0000ff #define BLUE 0x0000ff
#define GREEN 0x00ff00 #define GREEN 0x00ff00
</pre></blockquote> </pre></div>
<p>
To make constants available, their values can be stored in scripting To make constants available, their values can be stored in scripting
language variables such as <tt>$RED</tt>, <tt>$BLUE</tt>, and language variables such as <tt>$RED</tt>, <tt>$BLUE</tt>, and
<tt>$GREEN</tt>. Virtually all scripting languages provide C <tt>$GREEN</tt>. Virtually all scripting languages provide C
functions for creating variables so installing constants is usually functions for creating variables so installing constants is usually
a trivial exercise. a trivial exercise.
</p>
<H3><a name="Scripting_nn7"></a>4.2.4 Structures and classes</H3> <H3><a name="Scripting_nn7"></a>4.2.4 Structures and classes</H3>
<p>
Although scripting languages have no trouble accessing simple Although scripting languages have no trouble accessing simple
functions and variables, accessing C/C++ structures and classes functions and variables, accessing C/C++ structures and classes
present a different problem. This is because the implementation 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 data representation and layout. Furthermore, certain language features
are difficult to map to an interpreter. For instance, what are difficult to map to an interpreter. For instance, what
does C++ inheritance mean in a Perl interface? does C++ inheritance mean in a Perl interface?
</p>
<p> <p>
The most straightforward technique for handling structures is to 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, representation of a structure. For example,
</p> </p>
<blockquote><pre> <div class="code"><pre>
struct Vector { struct Vector {
Vector(); Vector();
~Vector(); ~Vector();
double x,y,z; double x,y,z;
}; };
</pre></blockquote> </pre></div>
can be transformed into the following set of functions :
<blockquote><pre> <p>
can be transformed into the following set of functions :
</p>
<div class="code"><pre>
Vector *new_Vector(); Vector *new_Vector();
void delete_Vector(Vector *v); void delete_Vector(Vector *v);
double Vector_x_get(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_y_set(Vector *v, double y);
void Vector_z_set(Vector *v, double z); void Vector_z_set(Vector *v, double z);
</pre></blockquote> </pre></div>
<p>
Now, from an interpreter these function might be used as follows: Now, from an interpreter these function might be used as follows:
</p>
<blockquote><pre> <div class="code"><pre>
% set v [new_Vector] % set v [new_Vector]
% Vector_x_set $v 3.5 % Vector_x_set $v 3.5
% Vector_y_get $v % Vector_y_get $v
% delete_Vector $v % delete_Vector $v
% ... % ...
</pre></blockquote> </pre></div>
<p> <p>
Since accessor functions provide a mechanism for accessing the 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 C++ class). For example, if you
have the following C definition :</p> have the following C definition :</p>
<blockquote><pre> <div class="code"><pre>
class Vector { class Vector {
public: public:
Vector(); Vector();
~Vector(); ~Vector();
double x,y,z; double x,y,z;
}; };
</pre></blockquote> </pre></div>
<p> <p>
A proxy classing mechanism would allow you to access the structure in 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: a more natural manner from the interpreter. For example, in Python, you might want to do this:
</p> </p>
<blockquote><pre> <div class="code"><pre>
&gt;&gt;&gt; v = Vector() &gt;&gt;&gt; v = Vector()
&gt;&gt;&gt; v.x = 3 &gt;&gt;&gt; v.x = 3
&gt;&gt;&gt; v.y = 4 &gt;&gt;&gt; v.y = 4
&gt;&gt;&gt; v.z = -13 &gt;&gt;&gt; v.z = -13
&gt;&gt;&gt; ... &gt;&gt;&gt; ...
&gt;&gt;&gt; del v &gt;&gt;&gt; del v
</pre></blockquote> </pre></div>
<p> <p>
Similarly, in Perl5 you may want the interface to work like this:</p> Similarly, in Perl5 you may want the interface to work like this:</p>
<blockquote><pre> <div class="code"><pre>
$v = new Vector; $v = new Vector;
$v-&gt;{x} = 3; $v-&gt;{x} = 3;
$v-&gt;{y} = 4; $v-&gt;{y} = 4;
$v-&gt;{z} = -13; $v-&gt;{z} = -13;
</pre></blockquote> </pre></div>
<p>
Finally, in Tcl : Finally, in Tcl :
</p>
<blockquote><pre> <div class="code"><pre>
Vector v Vector v
v configure -x 3 -y 4 -z 13 v configure -x 3 -y 4 -z 13
</pre></blockquote> </pre></div>
<p> <p>
When proxy classes are used, two objects are at really work--one in 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 manual pages for your compiler and linker. However, the procedure
for a few common machines is shown below:</p> for a few common machines is shown below:</p>
<blockquote><pre> <div class="code"><pre>
# Build a shared library for Solaris # Build a shared library for Solaris
gcc -c example.c example_wrap.c -I/usr/local/include gcc -c example.c example_wrap.c -I/usr/local/include
ld -G example.o example_wrap.o -o example.so 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 gcc -c example.c example_wrap.c -I/usr/local/include
ld -shared example.o example_wrap.o -o example.so ld -shared example.o example_wrap.o -o example.so
</pre></blockquote> </pre></div>
<p> <p>
To use your shared library, you simply use the corresponding command 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: import your module and allow you to start using it. For example:
</p> </p>
<blockquote><pre> <div class="code"><pre>
% load ./example.so % load ./example.so
% fact 4 % fact 4
24 24
% %
</pre></blockquote> </pre></div>
<p> <p>
When working with C++ codes, the process of building shared libraries 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 can build a shared C++ module by following the above procedures, but
changing the link line to the following :</p> changing the link line to the following :</p>
<blockquote><pre> <div class="code"><pre>
c++ -shared example.o example_wrap.o -o example.so 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> <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 these libraries at run-time. Otherwise, you may get an error such as
the following :</p> the following :</p>
<blockquote><pre> <div class="code"><pre>
&gt;&gt;&gt; import graph &gt;&gt;&gt; import graph
Traceback (innermost last): Traceback (innermost last):
File "&lt;stdin&gt;", line 1, in ? 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:/ 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: lib/libgraph.so:/lib/cmplrs/cc/libgraph.so:/usr/lib/cmplrs/cc/libgraph.so:
&gt;&gt;&gt; &gt;&gt;&gt;
</pre></blockquote> </pre></div>
<p> <p>
What this error means is that the extension module created by SWIG What this error means is that the extension module created by SWIG

933
SWIG/Doc/Manual/Tcl.html
View file

File diff suppressed because it is too large Load diff

951
SWIG/Doc/Manual/Typemaps.html
View file

File diff suppressed because it is too large Load diff

188
SWIG/Doc/Manual/Varargs.html
View file

@ -2,11 +2,13 @@
<html> <html>
<head> <head>
<title>Variable Length Arguments</title> <title>Variable Length Arguments</title>
<link rel="stylesheet" type="text/css" href="style.css"/>
</head> </head>
<body bgcolor="#ffffff"> <body bgcolor="#ffffff">
<H1><a name="Varargs"></a>13 Variable Length Arguments</H1> <H1><a name="Varargs"></a>13 Variable Length Arguments</H1>
<!-- INDEX --> <!-- INDEX -->
<div class="sectiontoc">
<ul> <ul>
<li><a href="#Varargs_nn2">Introduction</a> <li><a href="#Varargs_nn2">Introduction</a>
<li><a href="#Varargs_nn3">The Problem</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_nn9">C++ Issues</a>
<li><a href="#Varargs_nn10">Discussion</a> <li><a href="#Varargs_nn10">Discussion</a>
</ul> </ul>
</div>
<!-- INDEX --> <!-- INDEX -->
<p>
<b>(a.k.a, "The horror. The horror.")</b> <b>(a.k.a, "The horror. The horror.")</b>
</p>
<p> <p>
This chapter describes the problem of wrapping functions that take a 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> <H2><a name="Varargs_nn2"></a>13.1 Introduction</H2>
<p>
Some C and C++ programs may include functions that accept a variable Some C and C++ programs may include functions that accept a variable
number of arguments. For example, most programmers are number of arguments. For example, most programmers are
familiar with functions from the C library such as the following: familiar with functions from the C library such as the following:
</p>
<blockquote> <div class="code">
<pre> <pre>
int printf(const char *fmt, ...) int printf(const char *fmt, ...)
int fprintf(FILE *, const char *fmt, ...); int fprintf(FILE *, const char *fmt, ...);
int sprintf(char *s, const char *fmt, ...); int sprintf(char *s, const char *fmt, ...);
</pre> </pre>
</blockquote> </div>
<p>
Although there is probably little practical purpose in wrapping these Although there is probably little practical purpose in wrapping these
specific C library functions in a scripting language (what would be the specific C library functions in a scripting language (what would be the
point?), a library may include its own set of special functions based point?), a library may include its own set of special functions based
on a similar API. For example: on a similar API. For example:
</p>
<blockquote> <div class="code">
<pre> <pre>
int traceprintf(const char *fmt, ...); int traceprintf(const char *fmt, ...);
</pre> </pre>
</blockquote> </div>
<p>
In this case, you may want to have some kind of access from the target language. In this case, you may want to have some kind of access from the target language.
</p>
<p> <p>
Before describing the SWIG implementation, it is important to discuss 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: be a function like this:
</p> </p>
<blockquote> <div class="code">
<pre> <pre>
int execlp(const char *path, const char *arg1, ...); int execlp(const char *path, const char *arg1, ...);
... ...
@ -85,14 +96,16 @@ int execlp(const char *path, const char *arg1, ...);
/* Example */ /* Example */
execlp("ls","ls","-l",NULL); execlp("ls","ls","-l",NULL);
</pre> </pre>
</blockquote> </div>
<p>
In addition, varargs is sometimes used to fake default arguments in older In addition, varargs is sometimes used to fake default arguments in older
C libraries. For instance, the low level <tt>open()</tt> system call 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 is often declared as a varargs function so that it will accept two
or three arguments: or three arguments:
</p>
<blockquote> <div class="code">
<pre> <pre>
int open(const char *path, int oflag, ...); int open(const char *path, int oflag, ...);
... ...
@ -101,13 +114,15 @@ int open(const char *path, int oflag, ...);
f = open("foo", O_RDONLY); f = open("foo", O_RDONLY);
g = open("bar", O_WRONLY | O_CREAT, 0644); g = open("bar", O_WRONLY | O_CREAT, 0644);
</pre> </pre>
</blockquote> </div>
<p>
Finally, to implement a varargs function, recall that you have to use 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 the C library functions defined in <tt>&lt;stdarg.h&gt;</tt>. For
example: example:
</p>
<blockquote> <div class="code">
<pre> <pre>
List make_list(const char *s, ...) { List make_list(const char *s, ...) {
va_list ap; va_list ap;
@ -122,17 +137,19 @@ List make_list(const char *s, ...) {
return x; return x;
} }
</pre> </pre>
</blockquote> </div>
<H2><a name="Varargs_nn3"></a>13.2 The Problem</H2> <H2><a name="Varargs_nn3"></a>13.2 The Problem</H2>
<p>
Generating wrappers for a variable length argument function presents a Generating wrappers for a variable length argument function presents a
number of special challenges. Although C provides support for number of special challenges. Although C provides support for
implementing functions that receive variable length arguments, there implementing functions that receive variable length arguments, there
are no functions that can go in the other direction. Specifically, are no functions that can go in the other direction. Specifically,
you can't write a function that dynamically creates a list of you can't write a function that dynamically creates a list of
arguments and which invokes a varargs function on your behalf. arguments and which invokes a varargs function on your behalf.
</p>
<p> <p>
Although it is possible to write functions that accept the special 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: calls get compiled. For example, suppose that your program has a function call like this:
</p> </p>
<blockquote> <div class="code">
<pre> <pre>
printf("Hello %s. Your number is %d\n", name, num); printf("Hello %s. Your number is %d\n", name, num);
</pre> </pre>
</blockquote> </div>
<p>
When the compiler looks at this, it knows that you are calling When the compiler looks at this, it knows that you are calling
<tt>printf()</tt> with exactly three arguments. Furthermore, it knows <tt>printf()</tt> with exactly three arguments. Furthermore, it knows
that the number of arguments as well are their types and sizes is that the number of arguments as well are their types and sizes is
<em>never</em> going to change during program execution. Therefore, <em>never</em> going to change during program execution. Therefore,
this gets turned to machine code that sets up a three-argument stack this gets turned to machine code that sets up a three-argument stack
frame followed by a call to <tt>printf()</tt>. frame followed by a call to <tt>printf()</tt>.
</p>
<p> <p>
In contrast, suppose you attempted to make some kind of wrapper around In contrast, suppose you attempted to make some kind of wrapper around
<tt>printf()</tt> using code like this: <tt>printf()</tt> using code like this:
</p> </p>
<blockquote> <div class="code">
<pre> <pre>
int wrap_printf(const char *fmt, ...) { int wrap_printf(const char *fmt, ...) {
va_list ap; va_list ap;
@ -176,14 +195,16 @@ int wrap_printf(const char *fmt, ...) {
va_end(ap); va_end(ap);
}; };
</pre> </pre>
</blockquote> </div>
<p>
Athough this code might compile, it won't do what you expect. This is 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 because the call to <tt>printf()</tt> is compiled as a procedure call
involving only two arguments. However, clearly a two-argument involving only two arguments. However, clearly a two-argument
configuration of the call stack is completely wrong if your intent is configuration of the call stack is completely wrong if your intent is
to pass an arbitrary number of arguments to the real to pass an arbitrary number of arguments to the real
<tt>printf()</tt>. Needless to say, it won't work. <tt>printf()</tt>. Needless to say, it won't work.
</p>
<p> <p>
Unfortunately, the situation just described is exactly the problem 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> <H2><a name="Varargs_nn4"></a>13.3 Default varargs support</H2>
<p>
When variable length arguments appear in an interface, the default When variable length arguments appear in an interface, the default
behavior is to drop the variable argument list entirely, replacing behavior is to drop the variable argument list entirely, replacing
them with a single NULL pointer. For example, if you had this them with a single NULL pointer. For example, if you had this
function, function,
</p>
<blockquote> <div class="code">
<pre> <pre>
void traceprintf(const char *fmt, ...); void traceprintf(const char *fmt, ...);
</pre> </pre>
</blockquote> </div>
<p>
it would be wrapped as if it had been declared as follows: it would be wrapped as if it had been declared as follows:
</p>
<blockquote> <div class="code">
<pre> <pre>
void traceprintf(const char *fmt); void traceprintf(const char *fmt);
</pre> </pre>
</blockquote> </div>
<p>
When the function is called inside the wrappers, it is called as follows: When the function is called inside the wrappers, it is called as follows:
</p>
<blockquote> <div class="code">
<pre> <pre>
traceprintf(arg1, NULL); traceprintf(arg1, NULL);
</pre> </pre>
</blockquote> </div>
<p>
Arguably, this approach seems to defeat the whole point of variable length arguments. However, 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 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): instance, you could make function calls like this (in Python):
</p>
<blockquote> <div class="code">
<pre> <pre>
&gt;&gt;&gt; traceprintf("Hello World") &gt;&gt;&gt; traceprintf("Hello World")
&gt;&gt;&gt; traceprintf("Hello %s. Your number is %d\n" % (name, num)) &gt;&gt;&gt; traceprintf("Hello %s. Your number is %d\n" % (name, num))
</pre> </pre>
</blockquote> </div>
<p>
Notice how string formatting is being done in Python instead of C. 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> <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 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 <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, that can be used to do this. For example,
</p>
<blockquote> <div class="code">
<pre> <pre>
%varargs(int mode = 0) open; %varargs(int mode = 0) open;
... ...
int open(const char *path, int oflags, ...); int open(const char *path, int oflags, ...);
</pre> </pre>
</blockquote> </div>
<p>
is equivalent to this: is equivalent to this:
</p>
<blockquote> <div class="code">
<pre> <pre>
int open(const char *path, int oflags, int mode = 0); int open(const char *path, int oflags, int mode = 0);
</pre> </pre>
</blockquote> </div>
<p>
In this case, <tt>%varargs</tt> is simply providing more specific information about the In this case, <tt>%varargs</tt> is simply providing more specific information about the
extra arguments that might be passed to a function. extra arguments that might be passed to a function.
If the parameters to a varargs function are of uniform type, <tt>%varargs</tt> can also If the parameters to a varargs function are of uniform type, <tt>%varargs</tt> can also
accept a numerical argument count as follows: accept a numerical argument count as follows:
</p>
<blockquote> <div class="code">
<pre> <pre>
%varargs(10,char *arg = NULL) execlp; %varargs(10,char *arg = NULL) execlp;
... ...
int execlp(const char *path, const char *arg1, ...); int execlp(const char *path, const char *arg1, ...);
</pre> </pre>
</blockquote> </div>
<p>
This would wrap <tt>execlp()</tt> as a function that accepted up to 10 optional arguments. 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. Depending on the application, this may be more than enough for practical purposes.
</p>
<p> <p>
Argument replacement is most appropriate in cases where the types of 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> <H2><a name="Varargs_nn6"></a>13.5 Varargs and typemaps</H2>
<p>
Variable length arguments may be used in typemap specifications. For example: Variable length arguments may be used in typemap specifications. For example:
</p>
<blockquote> <div class="code">
<pre> <pre>
%typemap(in) (...) { %typemap(in) (...) {
// Get variable length arguments (somehow) // Get variable length arguments (somehow)
@ -324,8 +365,9 @@ Variable length arguments may be used in typemap specifications. For example:
// Multi-argument typemap // Multi-argument typemap
} }
</pre> </pre>
</blockquote> </div>
<p>
However, this immediately raises the question of what "type" is actually used 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 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 <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 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 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. the function. Therefore, you could use the pointer to hold a valid argument value if you wanted.
</p>
<p> <p>
To illustrate, here is a safer version of wrapping <tt>printf()</tt> in Python: To illustrate, here is a safer version of wrapping <tt>printf()</tt> in Python:
</p> </p>
<blockquote> <div class="code">
<pre> <pre>
%typemap(in) (const char *fmt, ...) { %typemap(in) (const char *fmt, ...) {
$1 = "%s"; /* Fix format string to %s */ $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, ...); int printf(const char *fmt, ...);
</pre> </pre>
</blockquote> </div>
<p>
In this example, the format string is implicitly set to <tt>"%s"</tt>. 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 This prevents a program from passing a bogus format string to the
extension. Then, the passed input object is decoded and placed in 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 <tt>void *</tt> argument defined for the <tt>(...)</tt> argument. When the
actual function call is made, the underlying wrapper code will look roughly actual function call is made, the underlying wrapper code will look roughly
like this: like this:
</p>
<blockquote> <div class="code">
<pre> <pre>
wrap_printf() { wrap_printf() {
char *arg1; char *arg1;
@ -370,10 +416,12 @@ wrap_printf() {
... ...
} }
</pre> </pre>
</blockquote> </div>
<p>
Notice how both arguments are passed to the function and it does what you Notice how both arguments are passed to the function and it does what you
would expect. would expect.
</p>
<p> <p>
The next example illustrates a more advanced kind of varargs typemap. 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: like this:
</p> </p>
<blockquote> <div class="code">
<pre> <pre>
%typemap(in) (...)(char *args[10]) { %typemap(in) (...)(char *args[10]) {
int i; int i;
@ -416,8 +464,9 @@ like this:
$1 = (void *) args; $1 = (void *) args;
} }
</pre> </pre>
</blockquote> </div>
<p>
In this typemap, the special variable <tt>varargs</tt> is a tuple In this typemap, the special variable <tt>varargs</tt> is a tuple
holding all of the extra arguments passed (this is specific to the holding all of the extra arguments passed (this is specific to the
Python module). The typemap then pulls this apart and sticks 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 make the function work. To patch everything up, you have to rewrite the
underlying action code using the <tt>%feature</tt> directive like underlying action code using the <tt>%feature</tt> directive like
this: this:
</p>
<blockquote> <div class="code">
<pre> <pre>
%feature("action") execlp { %feature("action") execlp {
char *args = (char **) arg3; char *args = (char **) arg3;
@ -439,7 +489,7 @@ this:
int execlp(const char *path, const char *arg, ...); int execlp(const char *path, const char *arg, ...);
</pre> </pre>
</blockquote> </div>
<p> <p>
This patches everything up and creates a function that more or less 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> <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 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 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 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 with a fixed number of arguments of known types. In many cases, this
works perfectly fine. However, if you want more generality than this, works perfectly fine. However, if you want more generality than this,
you need to bring out some bigger guns. you need to bring out some bigger guns.
</p>
<p> <p>
One way to do this is to use a special purpose library such as libffi 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: example. For example:
</p> </p>
<blockquote> <div class="code">
<pre> <pre>
/* Take an arbitrary number of extra arguments and place into an array /* Take an arbitrary number of extra arguments and place into an array
of strings */ of strings */
@ -547,19 +599,21 @@ example. For example:
/* Declare the function. Whew! */ /* Declare the function. Whew! */
int execlp(const char *path, const char *arg1, ...); int execlp(const char *path, const char *arg1, ...);
</pre> </pre>
</blockquote> </div>
<p>
Looking at this example, you may start to wonder if SWIG is making 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 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 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 "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. first place?!?" Obviously, those are questions you'll have to answer for yourself.
</p>
<p> <p>
As a more extreme example of libffi, here is some code that attempts to wrap <tt>printf()</tt>, As a more extreme example of libffi, here is some code that attempts to wrap <tt>printf()</tt>,
</p> </p>
<blockquote> <div class="code">
<pre> <pre>
/* A wrapper for printf() using libffi */ /* 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 */ /* The function */
int printf(const char *fmt, ...); int printf(const char *fmt, ...);
</pre> </pre>
</blockquote> </div>
<p>
Much to your amazement, it even seems to work if you try it: Much to your amazement, it even seems to work if you try it:
</p>
<blockquote> <div class="code">
<pre> <pre>
&gt;&gt;&gt; import example &gt;&gt;&gt; import example
&gt;&gt;&gt; example.printf("Grade: %s %d/60 = %0.2f%%\n", "Dave", 47, 47.0*100/60) &gt;&gt;&gt; example.printf("Grade: %s %d/60 = %0.2f%%\n", "Dave", 47, 47.0*100/60)
Grade: Dave 47/60 = 78.33% Grade: Dave 47/60 = 78.33%
&gt;&gt;&gt; &gt;&gt;&gt;
</pre> </pre>
</blockquote> </div>
<p>
Of course, there are still some limitations to consider: Of course, there are still some limitations to consider:
</p>
<blockquote> <div class="code">
<pre> <pre>
&gt;&gt;&gt; example.printf("la de da de da %s", 42) &gt;&gt;&gt; example.printf("la de da de da %s", 42)
Segmentation fault (core dumped) Segmentation fault (core dumped)
</pre> </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, 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 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 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 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 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. 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> <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 Closely related to variable length argument wrapping, you may encounter functions that accept a parameter
of type <tt>va_list</tt>. For example: of type <tt>va_list</tt>. For example:
</p>
<blockquote> <div class="code">
<pre> <pre>
int vfprintf(FILE *f, const char *fmt, va_list ap); int vfprintf(FILE *f, const char *fmt, va_list ap);
</pre> </pre>
</blockquote> </div>
<p>
As far as we know, there is no obvious way to wrap these functions 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 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 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 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 call-stack. It's not clear that exporting a <tt>va_list</tt> would
have any use or that it would work at all. have any use or that it would work at all.
</p>
<H2><a name="Varargs_nn9"></a>13.8 C++ Issues</H2> <H2><a name="Varargs_nn9"></a>13.8 C++ Issues</H2>
<p>
Wrapping of C++ member functions that accept a variable number of Wrapping of C++ member functions that accept a variable number of
arguments presents a number of challenges. By far, the easiest way to 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 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: and it fully supports classes much like the <tt>%rename</tt> directive. For example:
</p>
<blockquote> <div class="code">
<pre> <pre>
%varargs (10, char * = NULL) Foo::bar; %varargs (10, char * = NULL) Foo::bar;
@ -733,10 +799,12 @@ public:
virtual void bar(char *arg, ...); // gets varargs above virtual void bar(char *arg, ...); // gets varargs above
}; };
</pre> </pre>
</blockquote> </div>
<p>
<tt>%varargs</tt> also works with constructors, operators, and any <tt>%varargs</tt> also works with constructors, operators, and any
other C++ programming construct that accepts variable arguments. other C++ programming construct that accepts variable arguments.
</p>
<p> <p>
Doing anything more advanced than this is likely to involve a serious 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: are placed in <tt>arg2</tt>, <tt>arg3</tt>, and so forth. For example:
</p> </p>
<blockquote> <div class="code">
<pre> <pre>
%feature("action") Foo::bar { %feature("action") Foo::bar {
... ...
@ -768,19 +836,23 @@ are placed in <tt>arg2</tt>, <tt>arg3</tt>, and so forth. For example:
... ...
} }
</pre> </pre>
</blockquote> </div>
<p>
Given the potential to shoot yourself in the foot, it is probably easier to reconsider your 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 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. fully general wrapper to a varargs C++ member function.
</p>
<H2><a name="Varargs_nn10"></a>13.9 Discussion</H2> <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 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 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 probably the easiest way to tackle the problem. However, using typemaps, it is possible to do some very advanced
kinds of wrapping. kinds of wrapping.
</p>
<p> <p>
One point of discussion concerns the structure of the libffi examples in the previous section. Looking 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: you might structure your interface like this:
</p> </p>
<blockquote> <div class="code">
<pre> <pre>
%typemap(const char *fmt, ...) { %typemap(const char *fmt, ...) {
... ...
@ -803,16 +875,18 @@ you might structure your interface like this:
/* Include some header file with traceprintf in it */ /* Include some header file with traceprintf in it */
%include "someheader.h" %include "someheader.h"
</pre> </pre>
</blockquote> </div>
<p>
Second, careful scrutiny will reveal that the typemaps involving <tt>(...)</tt> have nothing 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 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 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 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 platform, you might be able to use something else instead. You could use conditional compilation
to control this: to control this:
</p>
<blockquote> <div class="code">
<pre> <pre>
#ifdef USE_LIBFFI #ifdef USE_LIBFFI
%feature("action") printf { %feature("action") printf {
@ -825,11 +899,13 @@ to control this:
} }
#endif #endif
</pre> </pre>
</blockquote> </div>
<p>
Finally, even though you might be inclined to just write a hand-written wrapper for varargs functions, 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 the techniques used in the previous section have the advantage of being compatible with all other features
of SWIG such as exception handling. of SWIG such as exception handling.
</p>
<p> <p>
As a final word, some C programmers seem to have the assumption that As a final word, some C programmers seem to have the assumption that

103
SWIG/Doc/Manual/Warnings.html
View file

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

41
SWIG/Doc/Manual/Windows.html
View file

@ -2,11 +2,13 @@
<html> <html>
<head> <head>
<title>Getting started on Windows</title> <title>Getting started on Windows</title>
<link rel="stylesheet" type="text/css" href="style.css"/>
</head> </head>
<body bgcolor="#ffffff"> <body bgcolor="#ffffff">
<H1><a name="Windows"></a>3 Getting started on Windows </H1> <H1><a name="Windows"></a>3 Getting started on Windows </H1>
<!-- INDEX --> <!-- INDEX -->
<div class="sectiontoc">
<ul> <ul>
<li><a href="#Windows_nn2">Installation on Windows</a> <li><a href="#Windows_nn2">Installation on Windows</a>
<ul> <ul>
@ -36,34 +38,42 @@
<li><a href="#examples_cygwin">Running the examples on Windows using Cygwin</a> <li><a href="#examples_cygwin">Running the examples on Windows using Cygwin</a>
</ul> </ul>
</ul> </ul>
</div>
<!-- INDEX --> <!-- INDEX -->
<p>
This chapter describes SWIG usage on Microsoft Windows. This chapter describes SWIG usage on Microsoft Windows.
Installing SWIG and running the examples is covered as well as building the SWIG executable. 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. 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> <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: SWIG does not come with the usual Windows type installation program, however it is quite easy to get started. The main steps are:
<ul> <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>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++. <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> </ul>
</p>
<H3><a name="Windows_nn3"></a>3.1.1 Windows Executable</H3> <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. 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>. 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> <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. 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). The Examples directory has a few Visual C++ project files (.dsp files).
These were produced by Visual C++ 6, although they should also work in Visual C++ 5. These were produced by Visual C++ 6, 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 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. 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>. 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). 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> <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. 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++. 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. 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). 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. 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> 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. 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. 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 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. 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> <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_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> <b><tt>PYTHON_LIB</tt></b> : Set this to the python library including path for linking<p>
Example using Python 2.1.1:<br> 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_INCLUDE: d:\python21\include<br>
PYTHON_LIB: d:\python21\libs\python21.lib<br> PYTHON_LIB: d:\python21\libs\python21.lib<br>
</tt> </tt>
</p>
<H4><a name="Windows_nn7"></a>3.2.1.2 TCL</H4> <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_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> <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> 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_INCLUDE: d:\tcl\include<br>
TCL_LIB: d:\tcl\lib\tcl83.lib<br> TCL_LIB: d:\tcl\lib\tcl83.lib<br>
</tt> </tt>
</p>
<H4><a name="Windows_nn8"></a>3.2.1.3 Perl</H4> <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_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> <b><tt>PERL5_LIB</tt></b> : Set this to the Perl library including path for linking<p>
Example using nsPerl 5.004_04:<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_INCLUDE: D:\nsPerl5.004_04\lib\CORE<br>
PERL5_LIB: D:\nsPerl5.004_04\lib\CORE\perl.lib<br> PERL5_LIB: D:\nsPerl5.004_04\lib\CORE\perl.lib<br>
</tt> </tt>
</p>
<H4><a name="Windows_nn9"></a>3.2.1.4 Java</H4> <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_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> <b><tt>JAVA_BIN</tt></b> : Set this to the bin directory containing javac.exe<p>
Example using JDK1.3:<br> Example using JDK1.3:<br>
@ -133,10 +153,12 @@ Example using JDK1.3:<br>
JAVA_INCLUDE: d:\jdk1.3\include<br> JAVA_INCLUDE: d:\jdk1.3\include<br>
JAVA_BIN: d:\jdk1.3\bin<br> JAVA_BIN: d:\jdk1.3\bin<br>
</tt> </tt>
</p>
<H4><a name="Windows_nn10"></a>3.2.1.5 Ruby</H4> <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_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> <b><tt>RUBY_LIB</tt></b> : Set this to the ruby library including path for linking<p>
Example using Ruby 1.6.4:<br> 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_INCLUDE: D:\ruby\lib\ruby\1.6\i586-mswin32<br>
RUBY_LIB: D:\ruby\lib\mswin32-ruby16.lib<br> RUBY_LIB: D:\ruby\lib\mswin32-ruby16.lib<br>
</tt> </tt>
</p>
<H4><a name="Windows_nn11"></a>3.2.1.6 C#</H4> <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. 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. 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. 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> <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. 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> <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. 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> <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. 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 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. 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. 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> <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> <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. Note that SWIG can also be built using Cygwin.
However, the SWIG will then require the Cygwin DLL when executing. However, the SWIG will then require the Cygwin DLL when executing.
Follow the Unix instructions in the README file in the SWIG root directory. 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. 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. 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> <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 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 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. 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> <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 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#. 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. Follow the Unix instructions in the README file in the SWIG root directory to build the examples.
</p>
</body> </body>
</html> </html>

25
SWIG/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
SWIG/Doc/Manual/makechap.py
View file

@ -70,7 +70,7 @@ open(filename+".bak","w").write(data) # Make backup
lines = data.splitlines() lines = data.splitlines()
result = [ ] # This is the result of postprocessing the file 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 skip = 0
skipspace = 0 skipspace = 0
@ -195,7 +195,7 @@ if subsection:
if section: if section:
index += "</ul>\n" index += "</ul>\n"
index += "<!-- INDEX -->\n" index += "</div>\n<!-- INDEX -->\n"
data = "\n".join(result) data = "\n".join(result)

84
SWIG/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;
}