Merge remote-tracking branch 'origin/master' into gsoc2012-scilab
Conflicts: Examples/Makefile.in
This commit is contained in:
Sylvestre Ledru
commit
21e17eaa73
795 changed files with 16905 additions and 11792 deletions
|
|
@ -25,7 +25,7 @@
|
|||
<li><a name="i8" href="#8">8. Naming Conventions</a>
|
||||
<li><a name="i9" href="#9">9. Visibility</a>
|
||||
<li><a name="i10" href="#10">10. Miscellaneous Coding Guidelines</a>
|
||||
<li><a name="i11" href="#11">11. SVN Tagging Conventions</a>
|
||||
<li><a name="i11" href="#11">11. Git Tagging Conventions</a>
|
||||
</ul>
|
||||
|
||||
<a name="1" href="#i1">
|
||||
|
|
@ -119,8 +119,8 @@ are case-insensitive on Windows so this convention will prevent you from inadver
|
|||
creating two files that differ in case-only.
|
||||
|
||||
<p>
|
||||
Each file should include a short abstract, license information and
|
||||
a SVN revision tag like this:
|
||||
Each file should include a short abstract and license information
|
||||
like this:
|
||||
|
||||
<blockquote>
|
||||
<pre>
|
||||
|
|
@ -137,8 +137,6 @@ a SVN revision tag like this:
|
|||
* This file defines ...
|
||||
* ----------------------------------------------------------------------------- */
|
||||
|
||||
static char cvs[] = "$Id$";
|
||||
|
||||
#include "swig.h"
|
||||
|
||||
/* Declarations */
|
||||
|
|
@ -159,12 +157,6 @@ static int avariable;
|
|||
</pre>
|
||||
</blockquote>
|
||||
|
||||
The SVN revision tag should be placed into a static string as shown
|
||||
above mangled with the name of the file.
|
||||
This adds the revision information to the SWIG executable and
|
||||
makes it possible to extract version information from a raw binary
|
||||
(sometimes useful in debugging).
|
||||
|
||||
<p>
|
||||
As a general rule, files start to get unmanageable once they exceed
|
||||
about 2000 lines. Files larger than this should be broken up into
|
||||
|
|
@ -379,10 +371,10 @@ making your changes.
|
|||
These are largely covered in the main documentation in the Extending.html file.
|
||||
|
||||
<a name="11" href="#i11">
|
||||
<h2>11. SVN Tagging Conventions</h2>
|
||||
<h2>11. Git Tagging Conventions</h2>
|
||||
</a>
|
||||
|
||||
Use <tt>svn tag</tt> to declare some set of file revisions as related in some
|
||||
Use <tt>git tag</tt> to declare some set of file revisions as related in some
|
||||
symbolic way. This eases reference, retrieval and manipulation of these files
|
||||
later. At the moment (2001/01/16 14:02:53), the conventions are very simple;
|
||||
let's hope they stay that way!
|
||||
|
|
@ -390,10 +382,10 @@ let's hope they stay that way!
|
|||
<p>
|
||||
There are two types of tags, internal (aka personal) and external.
|
||||
Internal tags are used by SWIG developers primarily, whereas external
|
||||
tags are used when communicating with people w/ anonymous svn access.
|
||||
tags are used when communicating with people w/ anonymous git access.
|
||||
<ul>
|
||||
<li> Internal tags should start with the developer name and a hyphen.
|
||||
<li> External tags should start with "v-".
|
||||
<li> External tags should start with "rel-".
|
||||
</ul>
|
||||
|
||||
That's all there is to it. Some example tags:
|
||||
|
|
@ -402,10 +394,8 @@ That's all there is to it. Some example tags:
|
|||
<li> ttn-pre-xml-patch
|
||||
<li> ttn-post-xml-patch
|
||||
<li> ttn-going-on-vacation-so-dutifully-tagging-now
|
||||
<li> v-1-3-a37-fixes-bug-2432
|
||||
<li> v-1-3-a37-fixes-bug-2433
|
||||
<li> v-1-3-a37-fixes-bug-2432-again
|
||||
<li> v-1-3-a37-release
|
||||
<li> rel-1.3.40
|
||||
<li> rel-2.0.9
|
||||
</ul>
|
||||
|
||||
<hr>
|
||||
|
|
|
|||
|
|
@ -42,6 +42,7 @@
|
|||
<li><a name="i7" href="#7">7. Debugging SWIG</a>
|
||||
<ul>
|
||||
<li><a name="i7.1" href="#7.1">7.1 Debugging DOH Types The Hard Way</a>
|
||||
<li><a name="i7.2" href="#7.2">7.2 Debugging DOH memory allocation problems</a>
|
||||
</ul>
|
||||
</ul>
|
||||
|
||||
|
|
@ -1179,6 +1180,34 @@ Either <br>
|
|||
|
||||
</ul>
|
||||
|
||||
<a name="7.2" href="#i7.2">
|
||||
<h3>7.2 Debugging DOH memory allocation problems</h3>
|
||||
</a>
|
||||
|
||||
<p>
|
||||
The DOH objects are reference counted and use pools for memory allocation.
|
||||
The implementation is in <tt>memory.c</tt>. When there are memory corruption problems,
|
||||
various memory allocator tools are normally used to diagnose problems. These can be used
|
||||
on SWIG and can be very useful. However, they won't necessarily find use of stale DOH objects,
|
||||
that is, DOH objects
|
||||
that are used after they have been deleted. This is because the DOH memory allocator
|
||||
grabs a chunk of memory from the C memory allocator and manages the usage internally.
|
||||
Stale DOH object usage can be checked for by defining <tt>DOH_DEBUG_MEMORY_POOLS</tt> in
|
||||
<tt>memory.c</tt>. If an attempt to use an object is made after the reference count is
|
||||
zero, an assertion is triggered instead of quietly re-using the stale object...
|
||||
</p>
|
||||
|
||||
<blockquote>
|
||||
<pre>
|
||||
swig: DOH/memory.c:91: DohCheck: Assertion `!DOH_object_already_deleted' failed.
|
||||
</pre>
|
||||
</blockquote>
|
||||
|
||||
<p>
|
||||
This can be memory intensive as previously used memory in the pool is not re-used so is
|
||||
only recommended for diagnosing memory corruption problems.
|
||||
</p>
|
||||
|
||||
<hr>
|
||||
Copyright (C) 1999-2010 SWIG Development Team.
|
||||
|
||||
|
|
|
|||
|
|
@ -1118,7 +1118,7 @@ namespace BAR {
|
|||
function that returns an object (or pointer/reference) of C/C++
|
||||
type <tt>X</tt>, the wrapping defun (or defmethod) on the Lisp
|
||||
side will automatically wrap the pointer returned in an instance
|
||||
of the apropriate class. This makes it much easier to write and
|
||||
of the appropriate class. This makes it much easier to write and
|
||||
debug code than if pointers were passed around as a jumble of
|
||||
integer values.
|
||||
</p>
|
||||
|
|
@ -1613,7 +1613,7 @@ opoverload>
|
|||
<p>
|
||||
Variable length argument lists are not supported, by default. If
|
||||
such a function is encountered, a warning will generated to
|
||||
stderr. Varargs are supported via the SWIG <tt>%vararg</tt>
|
||||
stderr. Varargs are supported via the SWIG <tt>%varargs</tt>
|
||||
directive. This directive allows you to specify a (finite)
|
||||
argument list which will be inserted into the wrapper in place
|
||||
of the variable length argument indicator. As an example,
|
||||
|
|
@ -1624,7 +1624,7 @@ opoverload>
|
|||
<p>
|
||||
See the following section
|
||||
on <a href="Varargs.html#Varargs">Variable Length arguments</a>
|
||||
provides examples on how <tt>%vararg</tt> can be used, along
|
||||
provides examples on how <tt>%varargs</tt> can be used, along
|
||||
with other ways such functions can be wrapped.
|
||||
</p>
|
||||
|
||||
|
|
|
|||
|
|
@ -15,7 +15,9 @@
|
|||
<li><a href="#Android_examples_intro">Examples introduction</a>
|
||||
<li><a href="#Android_example_simple">Simple C example</a>
|
||||
<li><a href="#Android_example_class">C++ class example</a>
|
||||
<li><a href="#Android_examples_other">Other examples</a>
|
||||
</ul>
|
||||
<li><a href="#Android_stl">C++ STL</a>
|
||||
</ul>
|
||||
</div>
|
||||
<!-- INDEX -->
|
||||
|
|
@ -45,7 +47,7 @@ This chapter contains a few Android specific notes and examples.
|
|||
|
||||
|
||||
<p>
|
||||
The examples require the the <a href="http://developer.android.com/sdk/index.html">Android SDK</a> and <a href="http://developer.android.com/sdk/ndk/index.html">Android NDK</a> which can be installed as per instructions in the links.
|
||||
The examples require the <a href="http://developer.android.com/sdk/index.html">Android SDK</a> and <a href="http://developer.android.com/sdk/ndk/index.html">Android NDK</a> which can be installed as per instructions in the links.
|
||||
The Eclipse version is not required for these examples as just the command line tools are used (shown for Linux as the host, but Windows will be very similar, if not identical in most places).
|
||||
Add the SDK tools and NDK tools to your path and create a directory somewhere for your Android projects (adjust PATH as necessary to where you installed the tools):
|
||||
</p>
|
||||
|
|
@ -744,6 +746,36 @@ Run the app to see the result of calling the C++ code from Java:
|
|||
|
||||
<center><img src="android-class.png" alt="Android screenshot of SwigClass example"></center>
|
||||
|
||||
<H3><a name="Android_examples_other"></a>18.2.4 Other examples</H3>
|
||||
|
||||
|
||||
<p>
|
||||
The Examples/android directory contains further examples which can be run and installed in a similar manner to the previous two examples.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Note that the 'extend' example is demonstrates the directors feature.
|
||||
Normally C++ exception handling and the STL is not available by default in the version of g++ shipped with Android, but this example turns these features on as described in the next section.
|
||||
</p>
|
||||
|
||||
<H2><a name="Android_stl"></a>18.3 C++ STL</H2>
|
||||
|
||||
|
||||
<p>
|
||||
Should the C++ Standard Template Library (STL) be required, an <tt>Application.mk</tt> file needs to be created
|
||||
in the same directory as the <tt>Android.mk</tt> directory containing information about the STL to use.
|
||||
See the NDK documentation in the $NDKROOT/docs folder especially CPLUSPLUS-SUPPORT.html.
|
||||
Below is an example of the <tt>Application.mk</tt> file to make the STLport static library available for use:
|
||||
</p>
|
||||
|
||||
<div class="code">
|
||||
<pre>
|
||||
# File: Application.mk
|
||||
APP_STL := gnustl_static
|
||||
</pre>
|
||||
</div>
|
||||
|
||||
|
||||
</body>
|
||||
</html>
|
||||
|
||||
|
|
|
|||
|
|
@ -38,6 +38,7 @@
|
|||
<li><a href="#CSharp_memory_management_objects">Memory management for objects passed to the C++ layer</a>
|
||||
<li><a href="#CSharp_date_marshalling">Date marshalling using the csin typemap and associated attributes</a>
|
||||
<li><a href="#CSharp_date_properties">A date example demonstrating marshalling of C# properties</a>
|
||||
<li><a href="#CSharp_date_pre_post_directors">Date example demonstrating the 'pre' and 'post' typemap attributes for directors</a>
|
||||
<li><a href="#CSharp_partial_classes">Turning wrapped classes into partial classes</a>
|
||||
<li><a href="#CSharp_extending_proxy_class">Extending proxy classes with additional C# code</a>
|
||||
<li><a href="#CSharp_enum_underlying_type">Underlying type for enums</a>
|
||||
|
|
@ -190,6 +191,20 @@ csattributes C# attributes for attaching to proxy classes/enums
|
|||
|
||||
</li>
|
||||
|
||||
<li>
|
||||
<p>Additional typemap attributes:</p>
|
||||
|
||||
<p>
|
||||
The "null" attribute in the "out" typemap can be specified to provide a value for <tt>$null</tt> to expand into for wrapped functions that return non-void. Normally the default value of <tt>0</tt> is used.
|
||||
For example this is needed if you change the return type to void:
|
||||
</p>
|
||||
<div class="code"><pre>
|
||||
%typemap(ctype) Status "void"
|
||||
%typemap(out, null="") Status { ... }
|
||||
</pre></div>
|
||||
|
||||
</li>
|
||||
|
||||
<li>
|
||||
<p>Feature equivalent names:</p>
|
||||
<div class="code"><pre>
|
||||
|
|
@ -227,10 +242,12 @@ $jnicall -> $imcall
|
|||
<p>
|
||||
Unlike the "javain" typemap, the "csin" typemap does not support the 'pgcpp' attribute as the C# module does not have a premature garbage collection prevention parameter.
|
||||
The "csin" typemap supports additional optional attributes called 'cshin' and 'terminator'.
|
||||
The "csdirectorin" typemap supports additional optional attributes called 'terminator'.
|
||||
The 'cshin' attribute should contain the parameter type and name whenever a <a href="Java.html#Java_constructor_helper_function">constructor helper function</a> is generated due to the 'pre' or 'post' attributes.
|
||||
The 'terminator' attribute normally just contains a closing brace for when the 'pre' attribute contains an opening brace, such as when a C# <tt>using</tt> or <tt>fixed</tt> block is started.
|
||||
Note that 'pre', 'post', 'terminator' and 'cshin' attributes are not used for marshalling the property set.
|
||||
Please see the <a href="#CSharp_date_marshalling">Date marshalling example</a> and <a href="#CSharp_date_properties">Date marshalling of properties example</a> for further understanding of these "csin" applicable attributes.
|
||||
Please see the <a href="#CSharp_date_pre_post_directors">Date marshalling director example</a> for further understanding of the "csdirectorin" attributes.
|
||||
</p>
|
||||
</li>
|
||||
|
||||
|
|
@ -2040,13 +2057,13 @@ The typemaps to achieve this are shown below.
|
|||
|
||||
<div class="code">
|
||||
<pre>
|
||||
%typemap(cstype) const CDate& "System.DateTime"
|
||||
%typemap(cstype) const CDate & "System.DateTime"
|
||||
%typemap(csin,
|
||||
pre=" CDate temp$csinput = new CDate($csinput.Year, $csinput.Month, $csinput.Day);"
|
||||
) const CDate &
|
||||
"$csclassname.getCPtr(temp$csinput)"
|
||||
|
||||
%typemap(cstype) CDate& "out System.DateTime"
|
||||
%typemap(cstype) CDate & "out System.DateTime"
|
||||
%typemap(csin,
|
||||
pre=" CDate temp$csinput = new CDate();",
|
||||
post=" $csinput = new System.DateTime(temp$csinput.getYear(),"
|
||||
|
|
@ -2257,7 +2274,7 @@ Console.WriteLine("Important date: " + importantDate);
|
|||
</div>
|
||||
|
||||
<p>
|
||||
When SWIG wraps a variable that is a class/struct/union, it is wrapped using a pointer to the type for the reasons given in <a href="SWIG.html#SWIG_structure_data_members">Stucture data members</a>.
|
||||
When SWIG wraps a variable that is a class/struct/union, it is wrapped using a pointer to the type for the reasons given in <a href="SWIG.html#SWIG_structure_data_members">Structure data members</a>.
|
||||
The typemap type required is thus <tt>CDate *</tt>. Given that the previous section already designed <tt>CDate *</tt> typemaps, we'll use those same typemaps plus the 'csvarin' and 'csvarout' typemaps.
|
||||
|
||||
<div class="code">
|
||||
|
|
@ -2329,8 +2346,69 @@ Some points to note:
|
|||
<li>The 'csin' typemap has 'pre', 'post' and 'cshin' attributes, and these are all ignored in the property set. The code in these attributes must instead be replicated within the 'csvarin' typemap. The line creating the <tt>temp$csinput</tt> variable is such an example; it is identical to what is in the 'pre' attribute.
|
||||
</ul>
|
||||
|
||||
<H3><a name="CSharp_date_pre_post_directors"></a>19.8.5 Date example demonstrating the 'pre' and 'post' typemap attributes for directors</H3>
|
||||
|
||||
<H3><a name="CSharp_partial_classes"></a>19.8.5 Turning wrapped classes into partial classes</H3>
|
||||
|
||||
<p>
|
||||
The 'pre' and 'post' attributes in the "csdirectorin" typemap act like the attributes of the same name in the "csin" typemap.
|
||||
For example if we modify the <a href="#CSharp_date_marshalling">Date marshalling example</a> like this:
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
class CDate {
|
||||
...
|
||||
void setYear(int);
|
||||
void setMonth(int);
|
||||
void setDay(int);
|
||||
};
|
||||
struct Action {
|
||||
virtual void someCallback(CDate &date);
|
||||
virtual ~Action();
|
||||
...
|
||||
};
|
||||
</pre></div>
|
||||
|
||||
<p>
|
||||
and declare <tt>%feature ("director")</tt> for the <tt>Action</tt> class, we would have to define additional
|
||||
marshalling rules for <tt>CDate &</tt> parameter. The typemap may look like this:
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
%typemap(csdirectorin,
|
||||
pre="System.DateTime temp$iminput = new System.DateTime();",
|
||||
post="CDate temp2$iminput = new CDate($iminput, false);\n"
|
||||
"temp2$iminput.setYear(tempdate.Year);\n"
|
||||
"temp2$iminput.setMonth(tempdate.Month);\n"
|
||||
"temp2$iminput.setDay(tempdate.Day);"
|
||||
) CDate &date "out temp$iminput"
|
||||
</pre></div>
|
||||
|
||||
<p>
|
||||
The generated proxy class code will then contain the following wrapper for calling user-overloaded <tt>someCallback()</tt>:
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
...
|
||||
private void SwigDirectorsomeCallback(IntPtr date) {
|
||||
System.DateTime tempdate = new System.DateTime();
|
||||
try {
|
||||
someCallback(out tempdate);
|
||||
} finally {
|
||||
// we create a managed wrapper around the existing C reference, just for convenience
|
||||
CDate temp2date = new CDate(date, false);
|
||||
temp2date.setYear(tempdate.Year);
|
||||
temp2date.setMonth(tempdate.Month);
|
||||
temp2date.setDay(tempdate.Day);
|
||||
}
|
||||
}
|
||||
...
|
||||
</pre></div>
|
||||
<p>
|
||||
Pay special attention to the memory management issues, using these attributes.
|
||||
</p>
|
||||
|
||||
|
||||
<H3><a name="CSharp_partial_classes"></a>19.8.6 Turning wrapped classes into partial classes</H3>
|
||||
|
||||
|
||||
<p>
|
||||
|
|
@ -2430,7 +2508,7 @@ demonstrating that the class contains methods calling both unmanaged code - <tt>
|
|||
The following example is an alternative approach to adding managed code to the generated proxy class.
|
||||
</p>
|
||||
|
||||
<H3><a name="CSharp_extending_proxy_class"></a>19.8.6 Extending proxy classes with additional C# code</H3>
|
||||
<H3><a name="CSharp_extending_proxy_class"></a>19.8.7 Extending proxy classes with additional C# code</H3>
|
||||
|
||||
|
||||
<p>
|
||||
|
|
@ -2469,7 +2547,7 @@ public class ExtendMe : IDisposable {
|
|||
</pre>
|
||||
</div>
|
||||
|
||||
<H3><a name="CSharp_enum_underlying_type"></a>19.8.7 Underlying type for enums</H3>
|
||||
<H3><a name="CSharp_enum_underlying_type"></a>19.8.8 Underlying type for enums</H3>
|
||||
|
||||
|
||||
<P>
|
||||
|
|
|
|||
|
|
@ -16,13 +16,23 @@
|
|||
<ul>
|
||||
<li><a href="Preface.html#Preface_nn2">Introduction</a>
|
||||
<li><a href="Preface.html#Preface_nn4">SWIG Versions</a>
|
||||
<li><a href="Preface.html#Preface_license">SWIG License</a>
|
||||
<li><a href="Preface.html#Preface_nn5">SWIG resources</a>
|
||||
<li><a href="Preface.html#Preface_nn6">Prerequisites</a>
|
||||
<li><a href="Preface.html#Preface_nn7">Organization of this manual</a>
|
||||
<li><a href="Preface.html#Preface_nn8">How to avoid reading the manual</a>
|
||||
<li><a href="Preface.html#Preface_nn9">Backwards compatibility</a>
|
||||
<li><a href="Preface.html#Preface_release_notes">Release notes</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_installation">Installation</a>
|
||||
<ul>
|
||||
<li><a href="Preface.html#Preface_windows_installation">Windows installation</a>
|
||||
<li><a href="Preface.html#Preface_unix_installation">Unix installation</a>
|
||||
<li><a href="Preface.html#Preface_osx_installation">Macintosh OS X installation</a>
|
||||
<li><a href="Preface.html#Preface_testing">Testing</a>
|
||||
<li><a href="Preface.html#Preface_examples">Examples</a>
|
||||
</ul>
|
||||
</ul>
|
||||
</div>
|
||||
<!-- INDEX -->
|
||||
|
|
@ -645,7 +655,9 @@
|
|||
<li><a href="Android.html#Android_examples_intro">Examples introduction</a>
|
||||
<li><a href="Android.html#Android_example_simple">Simple C example</a>
|
||||
<li><a href="Android.html#Android_example_class">C++ class example</a>
|
||||
<li><a href="Android.html#Android_examples_other">Other examples</a>
|
||||
</ul>
|
||||
<li><a href="Android.html#Android_stl">C++ STL</a>
|
||||
</ul>
|
||||
</div>
|
||||
<!-- INDEX -->
|
||||
|
|
@ -684,6 +696,7 @@
|
|||
<li><a href="CSharp.html#CSharp_memory_management_objects">Memory management for objects passed to the C++ layer</a>
|
||||
<li><a href="CSharp.html#CSharp_date_marshalling">Date marshalling using the csin typemap and associated attributes</a>
|
||||
<li><a href="CSharp.html#CSharp_date_properties">A date example demonstrating marshalling of C# properties</a>
|
||||
<li><a href="CSharp.html#CSharp_date_pre_post_directors">Date example demonstrating the 'pre' and 'post' typemap attributes for directors</a>
|
||||
<li><a href="CSharp.html#CSharp_partial_classes">Turning wrapped classes into partial classes</a>
|
||||
<li><a href="CSharp.html#CSharp_extending_proxy_class">Extending proxy classes with additional C# code</a>
|
||||
<li><a href="CSharp.html#CSharp_enum_underlying_type">Underlying type for enums</a>
|
||||
|
|
@ -800,8 +813,9 @@
|
|||
<!-- INDEX -->
|
||||
<div class="sectiontoc">
|
||||
<ul>
|
||||
<li><a href="Guile.html#Guile_nn1">Supported Guile Versions</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">Old GH Guile API</a>
|
||||
<li><a href="Guile.html#Guile_nn4">Linkage</a>
|
||||
<ul>
|
||||
<li><a href="Guile.html#Guile_nn5">Simple Linkage</a>
|
||||
|
|
@ -814,8 +828,7 @@
|
|||
<li><a href="Guile.html#Guile_nn11">Typemaps</a>
|
||||
<li><a href="Guile.html#Guile_nn12">Representation of pointers as smobs</a>
|
||||
<ul>
|
||||
<li><a href="Guile.html#Guile_nn13">GH Smobs</a>
|
||||
<li><a href="Guile.html#Guile_nn14">SCM Smobs</a>
|
||||
<li><a href="Guile.html#Guile_nn14">Smobs</a>
|
||||
<li><a href="Guile.html#Guile_nn15">Garbage Collection</a>
|
||||
</ul>
|
||||
<li><a href="Guile.html#Guile_nn16">Exception Handling</a>
|
||||
|
|
@ -912,6 +925,7 @@
|
|||
<li><a href="Java.html#Java_directors_overhead">Overhead and code bloat</a>
|
||||
<li><a href="Java.html#Java_directors_example">Simple directors example</a>
|
||||
<li><a href="Java.html#Java_directors_threading">Director threading issues</a>
|
||||
<li><a href="Java.html#Java_directors_performance">Director performance tuning</a>
|
||||
</ul>
|
||||
<li><a href="Java.html#Java_allprotected">Accessing protected members</a>
|
||||
<li><a href="Java.html#Java_common_customization">Common customization features</a>
|
||||
|
|
|
|||
|
|
@ -454,6 +454,11 @@ variables are replaced with.
|
|||
<td>The actual operation to be performed (a function call, method invocation, variable access, etc.)</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>$name</td>
|
||||
<td>The C/C++ symbol name for the function.</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>$symname</td>
|
||||
<td>The symbol name used internally by SWIG</td>
|
||||
|
|
@ -479,6 +484,16 @@ variables are replaced with.
|
|||
<td>The fully qualified C/C++ declaration of the method being wrapped including the return type</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>$parentname</td>
|
||||
<td>The parent class name (if any) for a method.</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>$parentsymname</td>
|
||||
<td>The target language parent class name (if any) for a method.</td>
|
||||
</tr>
|
||||
|
||||
</table>
|
||||
|
||||
<p>
|
||||
|
|
@ -577,9 +592,7 @@ SWIG_NullReferenceError
|
|||
</pre></div>
|
||||
|
||||
<p>
|
||||
Since the <tt>SWIG_exception()</tt> function is defined at the C-level
|
||||
it can be used elsewhere in SWIG. This includes typemaps and helper
|
||||
functions.
|
||||
The <tt>SWIG_exception()</tt> function can also be used in typemaps.
|
||||
</p>
|
||||
|
||||
<H2><a name="Customization_ownership"></a>11.2 Object ownership and %newobject</H2>
|
||||
|
|
|
|||
|
|
@ -2975,7 +2975,7 @@ There are a lot of issues to address.
|
|||
<div class="code">
|
||||
<pre>
|
||||
virtual int functionWrapper(Node *n) {
|
||||
/* get useful atributes */
|
||||
/* get useful attributes */
|
||||
String *name = Getattr(n,"sym:name");
|
||||
SwigType *type = Getattr(n,"type");
|
||||
ParmList *parms = Getattr(n,"parms");
|
||||
|
|
@ -3101,7 +3101,7 @@ As you can see, most usages are direct.
|
|||
|
||||
<dl>
|
||||
|
||||
<dt> <b>configure.in</b>
|
||||
<dt> <b>configure.ac</b>
|
||||
<dd> This file is processed by
|
||||
|
||||
<p>
|
||||
|
|
@ -3536,7 +3536,7 @@ If you wish for a new language module to be distributed with SWIG,
|
|||
which we encourage for all popular languages, there are a few requirements.
|
||||
While we appreciate that getting all aspects of a new language working
|
||||
won't happen at the outset, there are a set of minimum requirements before
|
||||
a module can be committed into the SVN repository for distribution with future
|
||||
a module can be committed into the official Github repository for distribution with future
|
||||
versions of SWIG. The following are really a summary of this whole section with
|
||||
details being outlined earlier on.
|
||||
</p>
|
||||
|
|
@ -3551,7 +3551,7 @@ details being outlined earlier on.
|
|||
a runtime test, see for example <tt>Examples/python/class</tt>.
|
||||
</li>
|
||||
<li>
|
||||
Modify <tt>configure.in</tt>, <tt>Makefile.in</tt> and <tt>Examples/Makefile.in</tt> to run
|
||||
Modify <tt>configure.ac</tt>, <tt>Makefile.in</tt> and <tt>Examples/Makefile.in</tt> to run
|
||||
these examples. Please make sure that if the new language is not
|
||||
installed properly on a box, <tt>make -k check</tt> should still work by
|
||||
skipping the tests and examples for the new language module.
|
||||
|
|
@ -3578,7 +3578,7 @@ details being outlined earlier on.
|
|||
</ol>
|
||||
|
||||
<p>
|
||||
Once accepted into SVN, development efforts should concentrate on
|
||||
Once accepted into the official Git repository, development efforts should concentrate on
|
||||
getting the entire test-suite to work with plenty of runtime tests.
|
||||
Runtime tests should be for existing testcases and new test cases
|
||||
should be added should there be an area not already covered by
|
||||
|
|
|
|||
|
|
@ -93,25 +93,24 @@ swig -go -help
|
|||
<th>Go specific options</th>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>-intgo-type-size %lt;s%gt;</td>
|
||||
<td>Set the size for the Go type <tt>int</tt>. This controls the size
|
||||
that the C/C++ code expects to see. The %lt;s%gt; argument should
|
||||
be 32 or 64. This option is currently required during the
|
||||
transition from Go 1.0 to Go 1.1, as the size of <tt>int</tt> on
|
||||
64-bit x86 systems changes between those releases (from 32 bits to
|
||||
64 bits). In the future the option may become optional, and SWIG
|
||||
will assume that the size of <tt>int</tt> is the size of a C
|
||||
pointer.</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>-gccgo</td>
|
||||
<td>Generate code for gccgo. The default is to generate code for
|
||||
6g/8g/5g.</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>-gccgo-46</td>
|
||||
<td>Generate code for gccgo 4.6. The default is set by the configure
|
||||
script. This generates code that does not use some facilities
|
||||
that are only available in gccgo 4.7 and later.</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>-no-gccgo-46</td>
|
||||
<td>Turn off <code>-gccgo-46</code>, whether set by default or earlier
|
||||
on the command line.
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>-package <name></td>
|
||||
<td>Set the name of the Go package to <name>. The default
|
||||
|
|
@ -511,7 +510,7 @@ into Go types.
|
|||
<p>Because of limitations in the way output arguments are processed in swig,
|
||||
a function with output arguments will not have multiple return values.
|
||||
Instead, you must pass a pointer into the C++ function to tell it where to
|
||||
store the ouput value. In go, you supply a slice in the place of the output
|
||||
store the output value. In go, you supply a slice in the place of the output
|
||||
argument.</p>
|
||||
|
||||
<p>For example, suppose you were trying to wrap the modf() function in the
|
||||
|
|
|
|||
|
|
@ -12,8 +12,9 @@
|
|||
<!-- INDEX -->
|
||||
<div class="sectiontoc">
|
||||
<ul>
|
||||
<li><a href="#Guile_nn1">Supported Guile Versions</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">Old GH Guile API</a>
|
||||
<li><a href="#Guile_nn4">Linkage</a>
|
||||
<ul>
|
||||
<li><a href="#Guile_nn5">Simple Linkage</a>
|
||||
|
|
@ -26,8 +27,7 @@
|
|||
<li><a href="#Guile_nn11">Typemaps</a>
|
||||
<li><a href="#Guile_nn12">Representation of pointers as smobs</a>
|
||||
<ul>
|
||||
<li><a href="#Guile_nn13">GH Smobs</a>
|
||||
<li><a href="#Guile_nn14">SCM Smobs</a>
|
||||
<li><a href="#Guile_nn14">Smobs</a>
|
||||
<li><a href="#Guile_nn15">Garbage Collection</a>
|
||||
</ul>
|
||||
<li><a href="#Guile_nn16">Exception Handling</a>
|
||||
|
|
@ -47,7 +47,21 @@
|
|||
<p>
|
||||
This section details guile-specific support in SWIG.
|
||||
|
||||
<H2><a name="Guile_nn2"></a>23.1 Meaning of "Module"</H2>
|
||||
<H2><a name="Guile_nn1"></a>23.1 Supported Guile Versions</H2>
|
||||
|
||||
|
||||
<p>
|
||||
SWIG works with Guile versions 1.8.x and 2.0.x. Support for version
|
||||
1.6.x has been dropped. The last version of SWIG that still works with
|
||||
Guile version 1.6.x is SWIG 2.0.9.
|
||||
|
||||
<p>
|
||||
Note that starting with guile 2.0, the guile sources can be compiled for
|
||||
improved performance. This is currently not tested with swig
|
||||
so your mileage may vary. To be safe set environment variable
|
||||
GUILE_AUTO_COMPILE to 0 when using swig generated guile code.
|
||||
|
||||
<H2><a name="Guile_nn2"></a>23.2 Meaning of "Module"</H2>
|
||||
|
||||
|
||||
<p>
|
||||
|
|
@ -55,55 +69,18 @@ There are three different concepts of "module" involved, defined
|
|||
separately for SWIG, Guile, and Libtool. To avoid horrible confusion,
|
||||
we explicitly prefix the context, e.g., "guile-module".
|
||||
|
||||
<H2><a name="Guile_nn3"></a>23.2 Using the SCM or GH Guile API</H2>
|
||||
<H2><a name="Guile_nn3"></a>23.3 Old GH Guile API</H2>
|
||||
|
||||
|
||||
<p>The guile module can currently export wrapper files that use the guile GH interface or the
|
||||
SCM interface. This is controlled by an argument passed to swig. The "-gh" argument causes swig
|
||||
to output GH code, and the "-scm" argument causes swig to output SCM code. Right now the "-scm" argument
|
||||
is the default. The "-scm" wrapper generation assumes a guile version >= 1.6 and has several advantages over
|
||||
the "-gh" wrapper generation including garbage collection and GOOPS support.
|
||||
The "-gh" wrapper generation can be used for older versions of guile.
|
||||
The guile GH wrapper code generation is depreciated and the
|
||||
SCM interface is the default. The SCM and GH interface differ greatly in how they store
|
||||
pointers and have completely different run-time code. See below for more info.
|
||||
|
||||
<p>The GH interface to guile is deprecated. Read more about why in the
|
||||
<p>Guile 1.8 and older could be interfaced using two different api's, the SCM
|
||||
or the GH API. The GH interface to guile is deprecated. Read more about why in the
|
||||
<a href="http://www.gnu.org/software/guile/docs/docs-1.6/guile-ref/GH.html#GH">Guile manual</a>.
|
||||
The idea of the GH interface was to provide a high level API that other languages and projects
|
||||
could adopt. This was a good idea, but didn't pan out well for general development. But for the
|
||||
specific, minimal uses that the SWIG typemaps put the GH interface to use is ideal for
|
||||
using a high level API. So even though the GH interface is depreciated, SWIG will continue to use
|
||||
the GH interface and provide mappings from the GH interface to whatever API we need.
|
||||
We can maintain this mapping where guile failed because SWIG uses a small subset of all the GH functions
|
||||
which map easily. All the guile typemaps like typemaps.i and std_vector.i
|
||||
will continue to use the GH functions to do things like create lists of values, convert strings to
|
||||
integers, etc. Then every language module will define a mapping between the GH interface and
|
||||
whatever custom API the language uses. This is currently implemented by the guile module to use
|
||||
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>
|
||||
|
||||
<div class="code"><pre>
|
||||
<p>Support for the guile GH wrapper code generation has been dropped from SWIG. The last
|
||||
version of SWIG that can still generate guile GH wrapper code is 2.0.9. Please
|
||||
use that version if you really need the GH wrapper code.
|
||||
|
||||
#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_bool2scm SCM_BOOL
|
||||
#define gh_boolean_p SCM_BOOLP
|
||||
#define gh_car SCM_CAR
|
||||
#define gh_cdr SCM_CDR
|
||||
#define gh_cons scm_cons
|
||||
#define gh_double2scm scm_make_real
|
||||
...
|
||||
</pre></div>
|
||||
|
||||
<p>This file is parsed by SWIG at wrapper generation time, so every reference to a gh_ function is replaced
|
||||
by a scm_ function in the wrapper file. Thus the gh_ function calls will never be seen in the wrapper;
|
||||
the wrapper will look exactly like it was generated
|
||||
for the specific API. Currently only the guile language module has created a mapping policy from gh_ to scm_,
|
||||
but there is no reason other languages (like mzscheme or chicken) couldn't also use this.
|
||||
If that happens, there is A LOT less code duplication in the standard typemaps.</p>
|
||||
|
||||
<H2><a name="Guile_nn4"></a>23.3 Linkage</H2>
|
||||
<H2><a name="Guile_nn4"></a>23.4 Linkage</H2>
|
||||
|
||||
|
||||
<p>
|
||||
|
|
@ -111,7 +88,7 @@ Guile support is complicated by a lack of user community cohesiveness,
|
|||
which manifests in multiple shared-library usage conventions. A set of
|
||||
policies implementing a usage convention is called a <b>linkage</b>.
|
||||
|
||||
<H3><a name="Guile_nn5"></a>23.3.1 Simple Linkage</H3>
|
||||
<H3><a name="Guile_nn5"></a>23.4.1 Simple Linkage</H3>
|
||||
|
||||
|
||||
<p>
|
||||
|
|
@ -134,7 +111,7 @@ libraries into Guile.</p>
|
|||
<div class="targetlang">
|
||||
<pre>
|
||||
(define-module (my module))
|
||||
(define my-so (dynamic-link "./example.so"))
|
||||
(define my-so (dynamic-link "./libexample.so"))
|
||||
(dynamic-call "SWIG_init" my-so) ; make SWIG bindings
|
||||
;; Scheme definitions can go here
|
||||
</pre>
|
||||
|
|
@ -147,7 +124,17 @@ and <code>dynamic-call</code>:
|
|||
|
||||
<div class="targetlang">
|
||||
<pre>
|
||||
(load-extension "./example.so" "SWIG_init")
|
||||
(load-extension "./libexample.so" "SWIG_init")
|
||||
</pre>
|
||||
</div>
|
||||
|
||||
<p>
|
||||
A more portable approach would be to drop the shared library extension:
|
||||
</p>
|
||||
|
||||
<div class="targetlang">
|
||||
<pre>
|
||||
(load-extension "./libexample" "SWIG_init")
|
||||
</pre>
|
||||
</div>
|
||||
|
||||
|
|
@ -190,7 +177,7 @@ information by including a directive like this in the interface file:
|
|||
|
||||
<div class="code">
|
||||
<pre>
|
||||
%scheme %{ (load-extension "./example.so" "SWIG_init") %}
|
||||
%scheme %{ (load-extension "./libexample.so" "SWIG_init") %}
|
||||
</pre>
|
||||
</div>
|
||||
|
||||
|
|
@ -206,7 +193,7 @@ placed between the <code>define-module</code> form and the
|
|||
<code>SWIG_init</code> via a preprocessor define to avoid symbol
|
||||
clashes. For this case, however, passive linkage is available.
|
||||
|
||||
<H3><a name="Guile_nn6"></a>23.3.2 Passive Linkage</H3>
|
||||
<H3><a name="Guile_nn6"></a>23.4.2 Passive Linkage</H3>
|
||||
|
||||
|
||||
<p>Passive linkage is just like simple linkage, but it generates an
|
||||
|
|
@ -216,12 +203,12 @@ package name (see below).
|
|||
<p>You should use passive linkage rather than simple linkage when you
|
||||
are using multiple modules.
|
||||
|
||||
<H3><a name="Guile_nn7"></a>23.3.3 Native Guile Module Linkage</H3>
|
||||
<H3><a name="Guile_nn7"></a>23.4.3 Native Guile Module Linkage</H3>
|
||||
|
||||
|
||||
<p>SWIG can also generate wrapper code that does all the Guile module
|
||||
declarations on its own if you pass it the <code>-Linkage
|
||||
module</code> command-line option. This requires Guile 1.5.0 or later.
|
||||
module</code> command-line option.
|
||||
|
||||
<p>The module name is set with the <code>-package</code> and
|
||||
<code>-module</code> command-line options. Suppose you want to define
|
||||
|
|
@ -244,7 +231,7 @@ shared libraries into Guile; all bindings are automatically put in
|
|||
newly created Guile modules.
|
||||
<div class="targetlang">
|
||||
<pre>
|
||||
(define my-so (dynamic-link "./foo.so"))
|
||||
(define my-so (dynamic-link "./libfoo"))
|
||||
;; create new module and put bindings there:
|
||||
(dynamic-call "scm_init_my_modules_foo_module" my-so)
|
||||
</pre>
|
||||
|
|
@ -252,12 +239,12 @@ newly created Guile modules.
|
|||
Newer Guile versions have a shorthand procedure for this:
|
||||
<div class="targetlang">
|
||||
<pre>
|
||||
(load-extension "./foo.so" "scm_init_my_modules_foo_module")
|
||||
(load-extension "./libfoo.so" "scm_init_my_modules_foo_module")
|
||||
</pre>
|
||||
</div>
|
||||
</ul>
|
||||
|
||||
<H3><a name="Guile_nn8"></a>23.3.4 Old Auto-Loading Guile Module Linkage</H3>
|
||||
<H3><a name="Guile_nn8"></a>23.4.4 Old Auto-Loading Guile Module Linkage</H3>
|
||||
|
||||
|
||||
<p>Guile used to support an autoloading facility for object-code
|
||||
|
|
@ -283,7 +270,7 @@ option, SWIG generates an exported module initialization function with
|
|||
an appropriate name.
|
||||
|
||||
|
||||
<H3><a name="Guile_nn9"></a>23.3.5 Hobbit4D Linkage</H3>
|
||||
<H3><a name="Guile_nn9"></a>23.4.5 Hobbit4D Linkage</H3>
|
||||
|
||||
|
||||
<p>
|
||||
|
|
@ -308,7 +295,7 @@ my/lib/libfoo.so.X.Y.Z and friends. This scheme is still very
|
|||
experimental; the (hobbit4d link) conventions are not well understood.
|
||||
</p>
|
||||
|
||||
<H2><a name="Guile_nn10"></a>23.4 Underscore Folding</H2>
|
||||
<H2><a name="Guile_nn10"></a>23.5 Underscore Folding</H2>
|
||||
|
||||
|
||||
<p>
|
||||
|
|
@ -320,7 +307,7 @@ complained so far.
|
|||
<code>%rename</code> to specify the Guile name of the wrapped
|
||||
functions and variables (see CHANGES).
|
||||
|
||||
<H2><a name="Guile_nn11"></a>23.5 Typemaps</H2>
|
||||
<H2><a name="Guile_nn11"></a>23.6 Typemaps</H2>
|
||||
|
||||
|
||||
<p>
|
||||
|
|
@ -412,7 +399,7 @@ constant will appear as a scheme variable. See
|
|||
<a href="Customization.html#Customization_features">Features and the %feature directive</a>
|
||||
for info on how to apply the %feature.</p>
|
||||
|
||||
<H2><a name="Guile_nn12"></a>23.6 Representation of pointers as smobs</H2>
|
||||
<H2><a name="Guile_nn12"></a>23.7 Representation of pointers as smobs</H2>
|
||||
|
||||
|
||||
<p>
|
||||
|
|
@ -433,7 +420,7 @@ representing the expected pointer type. See also
|
|||
If the Scheme object passed was not a SWIG smob representing a compatible
|
||||
pointer, a <code>wrong-type-arg</code> exception is raised.
|
||||
|
||||
<H3><a name="Guile_nn13"></a>23.6.1 GH Smobs</H3>
|
||||
<H3><a name="Guile_nn14"></a>23.7.1 Smobs</H3>
|
||||
|
||||
|
||||
<p>
|
||||
|
|
@ -444,44 +431,19 @@ mangled type name. As Guile allows registering user types, so-called
|
|||
implemented now. The details will be discussed in the following.
|
||||
</p>
|
||||
|
||||
<p> A smob is a cons cell where the lower half of the CAR contains the smob type
|
||||
tag, while the upper half of the CAR and the whole CDR are available. Every
|
||||
module creates its own smob type in the clientdata field of the module. So the
|
||||
lower 16 bits of the car of the smob store the tag and the upper 16 bits store
|
||||
the index this type is in the array. We can then, given a smob, find its
|
||||
swig_type_info struct by using the tag (lower 16 bits of car) to find which
|
||||
module this type is in (since each tag is unique for the module). Then we use
|
||||
the upper 16 bits to index into the array of types attached to this module.
|
||||
Looking up the module from the tag is worst case O(# of modules) but average
|
||||
case O(1). This is because the modules are stored in a circularly linked list,
|
||||
and when we start searching the modules for the tag, we start looking with the
|
||||
module that the function doing the lookup is in. SWIG_Guile_ConvertPtr() takes
|
||||
as its first argument the swig_module_info * of the calling function, which is
|
||||
where we start comparing tags. Most types will be looked up in the same module
|
||||
that created them, so the first module we check will most likely be correct.
|
||||
Once we have a swig_type_info structure, we loop through the linked list of
|
||||
casts, using pointer comparisons.</p>
|
||||
|
||||
<H3><a name="Guile_nn14"></a>23.6.2 SCM Smobs</H3>
|
||||
|
||||
|
||||
<p>The SCM interface (using the "-scm" argument to swig) uses swigrun.swg.
|
||||
The whole type system, when it is first initialized, creates two smobs named "swig" and "collected_swig".
|
||||
<p>The whole type system, when it is first initialized, creates two smobs named "swig" and "collected_swig".
|
||||
The swig smob is used for non-garbage collected smobs, while the collected_swig smob is used as described
|
||||
below. Each smob has the same format, which is a double cell created by SCM_NEWSMOB2()
|
||||
The first word of data is the pointer to the object and the second word of data is the swig_type_info *
|
||||
structure describing this type. This is a lot easier than the GH interface above because we can store
|
||||
a pointer to the type info structure right in the type. With the GH interface, there was not enough
|
||||
room in the smob to store two whole words of data so we needed to store part of the "swig_type_info address"
|
||||
in the smob tag. If a generated GOOPS module has been loaded, smobs will be wrapped by the corresponding
|
||||
GOOPS class.</p>
|
||||
structure describing this type. If a generated GOOPS module has been loaded, smobs will be wrapped by
|
||||
the corresponding GOOPS class.</p>
|
||||
|
||||
|
||||
<H3><a name="Guile_nn15"></a>23.6.3 Garbage Collection</H3>
|
||||
<H3><a name="Guile_nn15"></a>23.7.2 Garbage Collection</H3>
|
||||
|
||||
|
||||
<p>Garbage collection is a feature of the new SCM interface, and it is automatically included
|
||||
if you pass the "-scm" flag to swig. Thus the swig garbage collection support requires guile >1.6.
|
||||
<p>Garbage collection is a feature of Guile since version 1.6. As SWIG now requires Guile > 1.8,
|
||||
it is automatically included.
|
||||
Garbage collection works like this. Every swig_type_info structure stores in its clientdata field a pointer
|
||||
to the destructor for this type. The destructor is the generated wrapper around the delete function.
|
||||
So swig still exports a wrapper for the destructor, it just does not call scm_c_define_gsubr() for
|
||||
|
|
@ -491,7 +453,7 @@ is exactly like described in <a href="Customization.html#Customization_ownership
|
|||
Object ownership and %newobject</a> in the SWIG manual. All typemaps use an $owner var, and
|
||||
the guile module replaces $owner with 0 or 1 depending on feature:new.</p>
|
||||
|
||||
<H2><a name="Guile_nn16"></a>23.7 Exception Handling</H2>
|
||||
<H2><a name="Guile_nn16"></a>23.8 Exception Handling</H2>
|
||||
|
||||
|
||||
<p>
|
||||
|
|
@ -517,14 +479,13 @@ mapping:
|
|||
The default when not specified here is to use "swig-error".
|
||||
See Lib/exception.i for details.
|
||||
|
||||
<H2><a name="Guile_nn17"></a>23.8 Procedure documentation</H2>
|
||||
<H2><a name="Guile_nn17"></a>23.9 Procedure documentation</H2>
|
||||
|
||||
|
||||
<p>If invoked with the command-line option <code>-procdoc
|
||||
<var>file</var></code>, SWIG creates documentation strings for the
|
||||
generated wrapper functions, describing the procedure signature and
|
||||
return value, and writes them to <var>file</var>. You need Guile 1.4
|
||||
or later to make use of the documentation files.
|
||||
return value, and writes them to <var>file</var>.
|
||||
|
||||
<p>SWIG can generate documentation strings in three formats, which are
|
||||
selected via the command-line option <code>-procdocformat
|
||||
|
|
@ -553,7 +514,7 @@ like this:
|
|||
typemap argument <code>doc</code>. See <code>Lib/guile/typemaps.i</code> for
|
||||
details.
|
||||
|
||||
<H2><a name="Guile_nn18"></a>23.9 Procedures with setters</H2>
|
||||
<H2><a name="Guile_nn18"></a>23.10 Procedures with setters</H2>
|
||||
|
||||
|
||||
<p>For global variables, SWIG creates a single wrapper procedure
|
||||
|
|
@ -581,7 +542,7 @@ struct members, the procedures <code>(<var>struct</var>-<var>member</var>-get
|
|||
pointer)</code> and <code>(<var>struct-member</var>-set pointer
|
||||
value)</code> are <em>not</em> generated.
|
||||
|
||||
<H2><a name="Guile_nn19"></a>23.10 GOOPS Proxy Classes</H2>
|
||||
<H2><a name="Guile_nn19"></a>23.11 GOOPS Proxy Classes</H2>
|
||||
|
||||
|
||||
<p>SWIG can also generate classes and generic functions for use with
|
||||
|
|
@ -589,10 +550,7 @@ Guile's Object-Oriented Programming System (GOOPS). GOOPS is a
|
|||
sophisticated object system in the spirit of the Common Lisp Object
|
||||
System (CLOS).
|
||||
|
||||
<p>GOOPS support is
|
||||
only available with the new SCM interface (enabled with the
|
||||
<code>-scm</code> command-line option of SWIG). To enable GOOPS
|
||||
support, pass the <code>-proxy</code> argument to
|
||||
<p>To enable GOOPS support, pass the <code>-proxy</code> argument to
|
||||
swig. This will export the GOOPS wrapper definitions into the
|
||||
<code><i>module</i>.scm</code> file in the directory specified by -outdir or the
|
||||
current directory. GOOPS support requires either passive or module linkage.</p>
|
||||
|
|
@ -730,7 +688,7 @@ Notice that <Foo> is used before it is defined. The fix is to just put th
|
|||
<code>%import "foo.h"</code> before the <code>%inline</code> block.
|
||||
</p>
|
||||
|
||||
<H3><a name="Guile_nn20"></a>23.10.1 Naming Issues</H3>
|
||||
<H3><a name="Guile_nn20"></a>23.11.1 Naming Issues</H3>
|
||||
|
||||
|
||||
<p>As you can see in the example above, there are potential naming conflicts. The default exported
|
||||
|
|
@ -767,7 +725,7 @@ guile-modules. For example,</p>
|
|||
(use-modules ((Test) #:renamer (symbol-prefix-proc 'goops:)))
|
||||
</pre></div>
|
||||
|
||||
<H3><a name="Guile_nn21"></a>23.10.2 Linking</H3>
|
||||
<H3><a name="Guile_nn21"></a>23.11.2 Linking</H3>
|
||||
|
||||
|
||||
<p>The guile-modules generated above all need to be linked together. GOOPS support requires
|
||||
|
|
@ -787,10 +745,10 @@ and might conflict with names from the GOOPS guile-module (see above). Pass the
|
|||
argument to solve this problem. If the <code>-exportprimitive</code> option is passed to SWIG the
|
||||
<code>(export ...)</code> code that would be exported into the scmstub file is exported at the bottom
|
||||
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 shared library.
|
||||
|
||||
<div class="code"><pre>
|
||||
%goops %{ (load-extension "./foo.so" "scm_init_my_modules_foo_module") %}
|
||||
%goops %{ (load-extension "./libfoo.so" "scm_init_my_modules_foo_module") %}
|
||||
</pre></div>
|
||||
|
||||
<p>
|
||||
|
|
@ -802,7 +760,7 @@ Produces the following code at the top of the generated GOOPS guile-module
|
|||
(define-module (my modules foo))
|
||||
|
||||
;; %goops directive goes here
|
||||
(load-extension "./foo.so" "scm_init_my_modules_foo_module")
|
||||
(load-extension "./libfoo.so" "scm_init_my_modules_foo_module")
|
||||
|
||||
(use-modules (oop goops) (Swig common))
|
||||
</pre></div>
|
||||
|
|
@ -810,7 +768,7 @@ Produces the following code at the top of the generated GOOPS guile-module
|
|||
|
||||
<li><p><b>Passive Linkage with -scmstub</b>: Here, the name of the scmstub file should be
|
||||
<code>Module-primitive.scm</code> (with <i>primitive</i> replaced with whatever is given with the <code>-primsuffix</code>
|
||||
argument. The code to load the <code>.so</code> library should be located in the <code>%scheme</code> directive,
|
||||
argument. The code to load the shared library should be located in the <code>%scheme</code> directive,
|
||||
which will then be added to the scmstub file.
|
||||
SWIG will automatically generate the line <code>(use-modules (<i>Package</i> <i>Module-primitive</i>))</code>
|
||||
into the GOOPS guile-module. So if <i>Module-primitive.scm</i> is on the autoload path for guile, the
|
||||
|
|
@ -818,7 +776,7 @@ into the GOOPS guile-module. So if <i>Module-primitive.scm</i> is on the autolo
|
|||
whatever code is needed to load the <i>Module-primitive.scm</i> file into guile.</p>
|
||||
|
||||
<div class="targetlang"><pre>
|
||||
%scheme %{ (load-extension "./foo.so" "scm_init_my_modules_foo_module") %}
|
||||
%scheme %{ (load-extension "./libfoo.so" "scm_init_my_modules_foo_module") %}
|
||||
// only include the following definition if (my modules foo) cannot
|
||||
// be loaded automatically
|
||||
%goops %{
|
||||
|
|
@ -851,7 +809,7 @@ SWIG will also automatically generate the line <code>(use-modules
|
|||
directive should contain whatever code is needed to get that module loaded into guile.</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
%goops %{ (load-extension "./foo.so" "scm_init_my_modules_foo_module") %}
|
||||
%goops %{ (load-extension "./libfoo.so" "scm_init_my_modules_foo_module") %}
|
||||
</pre></div>
|
||||
|
||||
<p>
|
||||
|
|
@ -862,7 +820,7 @@ Produces the following code at the top of the generated GOOPS guile-module
|
|||
(define-module (my modules foo))
|
||||
|
||||
;; %goops directive goes here (if any)
|
||||
(load-extension "./foo.so" "scm_init_my_modules_foo_module")
|
||||
(load-extension "./libfoo.so" "scm_init_my_modules_foo_module")
|
||||
|
||||
(use-modules (oop goops) (Swig common))
|
||||
(use-modules ((my modules foo-primitive) :renamer (symbol-prefix-proc
|
||||
|
|
|
|||
|
|
@ -86,6 +86,7 @@
|
|||
<li><a href="#Java_directors_overhead">Overhead and code bloat</a>
|
||||
<li><a href="#Java_directors_example">Simple directors example</a>
|
||||
<li><a href="#Java_directors_threading">Director threading issues</a>
|
||||
<li><a href="#Java_directors_performance">Director performance tuning</a>
|
||||
</ul>
|
||||
<li><a href="#Java_allprotected">Accessing protected members</a>
|
||||
<li><a href="#Java_common_customization">Common customization features</a>
|
||||
|
|
@ -326,12 +327,13 @@ The exact location may vary on your machine, but the above locations are typical
|
|||
|
||||
<p>
|
||||
The JNI code exists in a dynamic module or shared library (DLL on Windows) and gets loaded by the JVM.
|
||||
To build a shared library file, you need to compile your module in a manner similar to the following (shown for Solaris):</p>
|
||||
Assuming you have code you need to link to in a file called <tt>example.c</tt>, in order to build a shared library file, you need to compile your module in a manner similar to the following (shown for Solaris):</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
$ swig -java example.i
|
||||
$ gcc -c example_wrap.c -I/usr/java/include -I/usr/java/include/solaris
|
||||
$ ld -G example_wrap.o -o libexample.so
|
||||
$ gcc -c example.c
|
||||
$ ld -G example_wrap.o example.o -o libexample.so
|
||||
</pre></div>
|
||||
|
||||
<p>
|
||||
|
|
@ -1921,19 +1923,24 @@ The default behaviour described above can be improved via the <a href="SWIGPlus.
|
|||
Note that it only works for classes, structs, unions and enums declared within a named C++ namespace.
|
||||
When the nspace feature is used, the C++ namespaces are converted into Java packages of the same name.
|
||||
Proxy classes are thus declared within a package and this proxy makes numerous calls to the JNI intermediary class which is declared in the unnamed package by default.
|
||||
As Java does not support types declared in a named package accessing types declared in an unnamed package, the <tt>-package</tt> commandline option described earlier must be used to provide a parent package.
|
||||
So if SWIG is run using the <tt>-package com.myco</tt> option, a wrapped class, <tt>MyWorld::Material::Color</tt>, can then be accessed as <tt>com.myco.MyWorld.Material.Color</tt>. If you don't specify a package, you will get the following error message:
|
||||
As Java does not support types declared in a named package accessing types declared in an unnamed package, the <tt>-package</tt> commandline option described earlier generally should be used to provide a parent package.
|
||||
So if SWIG is run using the <tt>-package com.myco</tt> option, a wrapped class, <tt>MyWorld::Material::Color</tt>, can then be accessed as <tt>com.myco.MyWorld.Material.Color</tt>.
|
||||
If you don't specify a package, you will get the following warning:
|
||||
</p>
|
||||
|
||||
<div class="shell">
|
||||
<pre>
|
||||
example.i:16: Error: The nspace feature used on 'MyWorld::Material::Color' is not supported unless
|
||||
a package is specified
|
||||
with -package - Java does not support types declared in a named package accessing types declared
|
||||
in an unnamed package.
|
||||
example.i:16: Warning 826: The nspace feature is used on 'MyWorld::Material::Color' without -package. The generated code
|
||||
may not compile as Java does not support types declared in a named package accessing types declared in an unnamed package.
|
||||
</pre>
|
||||
</div>
|
||||
|
||||
<p>
|
||||
If it is undesirable to have a single top level package, the nspace feature may be used without the <tt>-package</tt> commandline option
|
||||
(and the resulting warning ignored) if all of the types exposed using SWIG are placed in a package using the nspace feature and the
|
||||
'jniclasspackage' pragma is used to specify a package for the JNI intermediary class.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
If the resulting use of the nspace feature and hence packages results in a proxy class in one package deriving or using a proxy class from another package,
|
||||
you will need to open up the visibility for the pointer constructor and <tt>getCPtr</tt> method from the default 'protected' to 'public' with the <tt>SWIG_JAVABODY_PROXY</tt> macro. See <a href="#Java_code_typemaps">Java code typemaps</a>.
|
||||
|
|
@ -2223,6 +2230,9 @@ The intermediary JNI class can be tailored through the use of pragmas, but is no
|
|||
<tr>
|
||||
<td>jniclassbase </td> <td>Base class for the intermediary JNI class</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>jniclasspackage </td> <td>Package in which to place the intermediary JNI class</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>jniclassclassmodifiers </td> <td>Class modifiers and class type for the intermediary JNI class</td>
|
||||
</tr>
|
||||
|
|
@ -3354,9 +3364,6 @@ The %feature directive can be applied globally, to specific classes, and to spec
|
|||
|
||||
// generate directors for all virtual methods in class Foo
|
||||
%feature("director") Foo;
|
||||
|
||||
// generate a director for just Foo::bar()
|
||||
%feature("director") Foo::bar;
|
||||
</pre>
|
||||
</div>
|
||||
|
||||
|
|
@ -3527,6 +3534,28 @@ Macros can be defined on the commandline when compiling your C++ code, or altern
|
|||
</pre>
|
||||
</div>
|
||||
|
||||
<H3><a name="Java_directors_performance"></a>24.5.6 Director performance tuning</H3>
|
||||
|
||||
|
||||
<p>
|
||||
When a new instance of a director (or subclass) is created in Java, the C++ side of the director performs a runtime check per director method to determine if that particular method is overridden in Java or if it should invoke the C++ base implementation directly. Although this makes initialization slightly more expensive, it is generally a good overall tradeoff.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
However, if all director methods are expected to usually be overridden by Java subclasses, then initialization can be made faster by avoiding these checks via the <tt>assumeoverride</tt> attribute. For example:
|
||||
</p>
|
||||
|
||||
<div class="code">
|
||||
<pre>
|
||||
%feature("director", assumeoverride=1) Foo;
|
||||
</pre>
|
||||
</div>
|
||||
|
||||
<p>
|
||||
The disadvantage is that invocation of director methods from C++ when Java doesn't actually override the method will require an additional call up into Java and back to C++. As such, this option is only useful when overrides are extremely common and instantiation is frequent enough that its performance is critical.
|
||||
</p>
|
||||
|
||||
|
||||
<H2><a name="Java_allprotected"></a>24.6 Accessing protected members</H2>
|
||||
|
||||
|
||||
|
|
@ -5468,6 +5497,22 @@ interfaces (implements) for Java class: empty default
|
|||
<p><tt>%typemap(javafinalize)</tt></p>
|
||||
<div class="indent">
|
||||
the <tt>finalize()</tt> method (proxy classes only): default calls the <tt>delete()</tt> method
|
||||
|
||||
<p>
|
||||
Note that the default javafinalize typemap must contain the full implementation of the finalize method.
|
||||
Any customization to this typemap must still declare a java finalize method with the correct signature.
|
||||
Note also that the name of the generated "delete" method may be affected by <tt>javadestruct</tt> and <tt>javadestruct_derived</tt> typemaps.
|
||||
Below shows an example modifying the finalizer, assuming the <tt>delete</tt> method has been renamed to <tt>swig_delete</tt>.
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
%typemap(javafinalize) SWIGTYPE %{
|
||||
protected void finalize() {
|
||||
swig_delete(); // renamed to prevent conflict with existing delete method
|
||||
}
|
||||
]%
|
||||
</pre></div>
|
||||
|
||||
</div>
|
||||
|
||||
<p>
|
||||
|
|
@ -5617,7 +5662,7 @@ to make the method and constructor public:
|
|||
|
||||
<p>
|
||||
The Java directors feature requires the "javadirectorin", "javadirectorout", "directorin" and the "directorout" typemaps in order to work properly.
|
||||
The "javapackage" typemap is an optional typemap used to identify the Java package path for individual SWIG generated proxy classes.
|
||||
The "javapackage" typemap is an optional typemap used to identify the Java package path for individual SWIG generated proxy classes used in director methods.
|
||||
</p>
|
||||
|
||||
<p><tt>%typemap(directorin)</tt></p>
|
||||
|
|
@ -5758,6 +5803,7 @@ The target method is the method in the Java proxy class which overrides the virt
|
|||
<p>
|
||||
The "javapackage" typemap is optional; it serves to identify a class's Java package.
|
||||
This typemap should be used in conjunction with classes that are defined outside of the current SWIG interface file.
|
||||
The typemap is only used if the type is used in a director method, that is, in a virtual method in a director class.
|
||||
For example:
|
||||
</p>
|
||||
|
||||
|
|
@ -5774,7 +5820,7 @@ For example:
|
|||
class Example {
|
||||
public:
|
||||
virtual ~Example();
|
||||
void ping(Foo *arg1, Bar *arg2);
|
||||
virtual void ping(Foo *arg1, Bar *arg2);
|
||||
};
|
||||
}
|
||||
</pre>
|
||||
|
|
@ -5799,7 +5845,7 @@ The corrected interface file looks like:
|
|||
class Example {
|
||||
public:
|
||||
virtual ~Example();
|
||||
void ping(Foo *arg1, Bar *arg2);
|
||||
virtual void ping(Foo *arg1, Bar *arg2);
|
||||
};
|
||||
}
|
||||
</pre>
|
||||
|
|
@ -7864,4 +7910,3 @@ Many of these have runtime tests in the java subdirectory.
|
|||
|
||||
</body>
|
||||
</html>
|
||||
|
||||
|
|
|
|||
|
|
@ -66,18 +66,19 @@ Library files are included using the <tt>%include</tt> directive.
|
|||
When searching for files, directories are searched in the following order:
|
||||
</p>
|
||||
|
||||
<ul>
|
||||
<ol>
|
||||
<li>The current directory
|
||||
<li>Directories specified with the <tt>-I</tt> command line option
|
||||
<li>.<tt>/swig_lib</tt>
|
||||
<li>SWIG library install location as reported by <tt>swig -swiglib</tt>, for example <tt>/usr/local/share/swig/1.3.30</tt>
|
||||
<li>On Windows, a directory <tt>Lib</tt> relative to the location of <tt>swig.exe</tt> is also searched.
|
||||
</ul>
|
||||
</ol>
|
||||
|
||||
<p>
|
||||
Within each directory, SWIG first looks for a subdirectory corresponding to a target language (e.g., <tt>python</tt>,
|
||||
<tt>tcl</tt>, etc.). If found, SWIG will search the language specific directory first. This allows
|
||||
for language-specific implementations of library files.
|
||||
Within directories mentioned in points 3-5, SWIG first looks for a subdirectory
|
||||
corresponding to a target language (e.g., <tt>python</tt>, <tt>tcl</tt>, etc.).
|
||||
If found, SWIG will search the language specific directory first. This allows
|
||||
for language-specific implementations of library files.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
|
|
@ -1871,6 +1872,8 @@ Adding the missing <tt>%shared_ptr</tt> macros will fix this:
|
|||
</pre>
|
||||
</div>
|
||||
|
||||
<b>Note:</b> There is currently no support for <tt>%shared_ptr</tt> and the director feature.
|
||||
|
||||
<H2><a name="Library_nn16"></a>8.5 Utility Libraries</H2>
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -236,7 +236,7 @@ More information on building and configuring eLua can be found here: <a href="ht
|
|||
|
||||
|
||||
<p>
|
||||
Most, but not all platforms support the dynamic loading of modules (Windows & Linux do). Refer to the Lua manual to determine if your platform supports it. For compiling a dynamically loaded module the same wrapper can be used. The commands will be something like this:
|
||||
Most, but not all platforms support the dynamic loading of modules (Windows & Linux do). Refer to the Lua manual to determine if your platform supports it. For compiling a dynamically loaded module the same wrapper can be used. Assuming you have code you need to link to in a file called <tt>example.c</tt>, the commands will be something like this:
|
||||
</p>
|
||||
<div class="shell"><pre>
|
||||
$ swig -lua example.i -o example_wrap.c
|
||||
|
|
@ -1359,7 +1359,7 @@ extern void sort_double(double* arr, int len);
|
|||
to create an array in C/C++ then this can be filled within Lua and passed into the function. It works, but it's a bit tedious.
|
||||
More details can be found in the <a href="Library.html#Library_carrays">carrays.i</a> documentation.</p>
|
||||
|
||||
<p>The second and more intuitive way, would be to pass a Lua table directly into the function, and have SWIG automatically convert between Lua-table and C-array. Within the <tt><typemaps.i></tt> file there are typemaps ready written to perform this task. To use them is again a matter of using %appy in the correct manner.</p>
|
||||
<p>The second and more intuitive way, would be to pass a Lua table directly into the function, and have SWIG automatically convert between Lua-table and C-array. Within the <tt><typemaps.i></tt> file there are typemaps ready written to perform this task. To use them is again a matter of using %apply in the correct manner.</p>
|
||||
|
||||
<p>The wrapper file below, shows both the use of carrays as well as the use of the typemap to wrap arrays. </p>
|
||||
|
||||
|
|
|
|||
|
|
@ -126,7 +126,7 @@ the resulting .ml and .mli files as well, and do the final link with -custom
|
|||
|
||||
|
||||
<p>
|
||||
The O'Caml SWIG module now requires you to compile a module (<tt>Swig</tt>)
|
||||
The OCaml SWIG module now requires you to compile a module (<tt>Swig</tt>)
|
||||
separately. In addition to aggregating common SWIG functionality, the Swig
|
||||
module contains the data structure that represents C/C++ values. This allows
|
||||
easier data sharing between modules if two or more are combined, because
|
||||
|
|
|
|||
|
|
@ -63,7 +63,7 @@ The SWIG implemention was first based on Octave 2.9.12, so this is the minimum v
|
|||
</p>
|
||||
|
||||
<p>
|
||||
As of SWIG 2.0.5, the Octave module should work with Octave versions 3.0.5, 3.2.4, and 3.4.0.
|
||||
As of SWIG 2.0.7, the Octave module has been tested with Octave versions 3.0.5, 3.2.4, 3.4.3, and 3.6.1.
|
||||
</p>
|
||||
|
||||
<H2><a name="Octave_nn3"></a>30.2 Running SWIG</H2>
|
||||
|
|
@ -74,7 +74,7 @@ Let's start with a very simple SWIG interface file, example.i:
|
|||
</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
%module example
|
||||
%module swigexample
|
||||
%{
|
||||
#include "example.h"
|
||||
%}
|
||||
|
|
@ -95,7 +95,7 @@ The <tt>-c++</tt> option is also required when wrapping C++ code:
|
|||
<div class="shell"><pre>$ swig -octave -c++ -o example_wrap.cpp example.i </pre></div>
|
||||
|
||||
<p>
|
||||
This creates a C++ source file <tt>example_wrap.cpp</tt>. A C++ file is generated even when wrapping C code as Octave is itself written in C++ and requires wrapper code to be in the same language. The generated C++ source file contains the low-level wrappers that need to be compiled and linked with the rest of your C/C++ application (in this case, the gcd implementation) to create an extension module.
|
||||
This creates a C++ source file "example_wrap.cpp". A C++ file is generated even when wrapping C code as Octave is itself written in C++ and requires wrapper code to be in the same language. The generated C++ source file contains the low-level wrappers that need to be compiled and linked with the rest of your C/C++ application (in this case, the gcd implementation) to create an extension module.
|
||||
</p>
|
||||
|
||||
<H3><a name="Octave_nn4"></a>30.2.1 Command-line options</H3>
|
||||
|
|
@ -110,15 +110,12 @@ Options specific to the Octave module are:
|
|||
<pre>$ swig -octave -help
|
||||
...
|
||||
Octave Options (available with -octave)
|
||||
-global - Load all symbols into the global namespace [default]
|
||||
-globals <em>name</em> - Set <em>name</em> used to access C global variables [default: 'cvar']
|
||||
- Use '.' to load C global variables into module namespace
|
||||
-noglobal - Do not load all symbols into the global namespace
|
||||
Use '.' to load C global variables into module namespace
|
||||
-opprefix <em>str</em> - Prefix <em>str</em> for global operator functions [default: 'op_']
|
||||
</pre></div>
|
||||
|
||||
<p>
|
||||
The <em>-global</em> and <em>-noglobal</em> options determine whether the Octave module will load all symbols into the global namespace in addition to the global namespace.
|
||||
The <em>-globals</em> option sets the name of the variable which is the namespace for C global variables exported by the module.
|
||||
The special name "." loads C global variables into the module namespace, i.e. alongside C functions and structs exported by the module.
|
||||
The <em>-opprefix</em> options sets the prefix of the names of global/friend <a href="#Octave_nn18">operator</a> functions.
|
||||
|
|
@ -138,7 +135,7 @@ $ mkoctfile example_wrap.cpp example.c
|
|||
</pre></div>
|
||||
|
||||
<p>
|
||||
where example.c is the file containing the gcd() implementation.
|
||||
where "example.c" is the file containing the gcd() implementation.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
|
|
@ -146,10 +143,10 @@ $ mkoctfile example_wrap.cpp example.c
|
|||
</p>
|
||||
|
||||
<p>
|
||||
mkoctfile will produce example.oct, which contains the compiled extension module. Loading it into Octave is then a matter of invoking
|
||||
mkoctfile will produce "swigexample.oct", which contains the compiled extension module. Loading it into Octave is then a matter of invoking
|
||||
</p>
|
||||
|
||||
<div class="targetlang"><pre>octave:1> example</pre></div>
|
||||
<div class="targetlang"><pre>octave:1> swigexample</pre></div>
|
||||
|
||||
<H3><a name="Octave_nn6"></a>30.2.3 Using your module</H3>
|
||||
|
||||
|
|
@ -160,13 +157,13 @@ Assuming all goes well, you will be able to do this:
|
|||
</p>
|
||||
|
||||
<div class="targetlang"><pre>$ octave -q
|
||||
octave:1> example
|
||||
octave:2> example.gcd(4,6)
|
||||
octave:1> swigexample
|
||||
octave:2> swigexample.gcd(4,6)
|
||||
ans = 2
|
||||
octave:3> example.cvar.Foo
|
||||
octave:3> swigexample.cvar.Foo
|
||||
ans = 3
|
||||
octave:4> example.cvar.Foo=4;
|
||||
octave:5> example.cvar.Foo
|
||||
octave:4> swigexample.cvar.Foo=4;
|
||||
octave:5> swigexample.cvar.Foo
|
||||
ans = 4 </pre></div>
|
||||
|
||||
<H2><a name="Octave_nn7"></a>30.3 A tour of basic C/C++ wrapping</H2>
|
||||
|
|
@ -176,59 +173,26 @@ ans = 4 </pre></div>
|
|||
|
||||
|
||||
<p>
|
||||
The SWIG module directive specifies the name of the Octave module. If you specify `module example', then in Octave everything in the module will be accessible under "example", as in the above example. When choosing a module name, make sure you don't use the same name as a built-in Octave command or standard module name.
|
||||
The SWIG module directive specifies the name of the Octave module. If you specify "module swigexample", then in Octave everything in the module will be accessible under "swigexample", as in the above example. When choosing a module name, make sure you don't use the same name as a built-in Octave command or standard module name.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
When Octave is asked to invoke <tt>example</tt>, it will try to find the .m or .oct file that defines the function "example". It will thusly find example.oct, that upon loading will register all of the module's symbols.
|
||||
When Octave is asked to invoke <tt>swigexample</tt>, it will try to find the ".m" or ".oct" file that defines the function "swigexample". You therefore need to make sure that "swigexample.oct" is in Octave's search path, which can be specified with the environment variable "OCTAVE_PATH".
|
||||
</p>
|
||||
|
||||
<p>
|
||||
An Octave module takes three options, <em>-global</em>, <em>-noglobal</em>, and <em>-globals</em>, which behave the same as the corresponding swig <a href="#Octave_nn4">command-line options</a>.
|
||||
Here are some example usages:
|
||||
To load an Octave module, simply type its name:
|
||||
</p>
|
||||
|
||||
<div class="targetlang"><pre>
|
||||
octave:1> example -help
|
||||
usage: example [-global|-noglobal] [-globals <name>]
|
||||
octave:2> example -global
|
||||
octave:3> gcd(4,6)
|
||||
<div class="targetlang"><pre>
|
||||
octave:1> swigexample;
|
||||
octave:2> gcd(4,6)
|
||||
ans = 2
|
||||
octave:4> cvar.Foo
|
||||
ans = 3
|
||||
octave:5> cvar.Foo=4;
|
||||
octave:6> cvar.Foo
|
||||
ans = 4
|
||||
</pre></div>
|
||||
<br>
|
||||
<div class="targetlang"><pre>
|
||||
octave:1> example -noglobal
|
||||
octave:2> gcd(6,9)
|
||||
ans = 3
|
||||
octave:3> cvar.Foo
|
||||
error: `cvar' undefined near line 3 column 1
|
||||
octave:3> example.cvar.Foo
|
||||
ans = 3
|
||||
</pre></div>
|
||||
<br>
|
||||
<div class="targetlang"><pre>
|
||||
octave:1> example -globals mycvar
|
||||
octave:2> cvar.Foo
|
||||
error: `cvar' undefined near line 2 column 1
|
||||
octave:2> mycvar.Foo
|
||||
ans = 3
|
||||
</pre></div>
|
||||
|
||||
<p>
|
||||
It is also possible to rename the module / global variables namespaces with an assignment, as in: <br>
|
||||
<div class="targetlang"><pre>
|
||||
octave:1> example
|
||||
octave:2> c=example;
|
||||
octave:3> c.gcd(10,4)
|
||||
ans = 2
|
||||
octave:4> some_vars = cvar;
|
||||
octave:5> some_vars.Foo
|
||||
ans = 3
|
||||
octave:4> cvar.Foo=4;
|
||||
octave:5> cvar.Foo
|
||||
ans = 4
|
||||
</pre></div>
|
||||
|
||||
<p>
|
||||
|
|
@ -238,15 +202,15 @@ If the module is also used in the base context, however, it must first be loaded
|
|||
|
||||
<div class="targetlang"><pre>
|
||||
octave:1> function l = my_lcm(a,b)
|
||||
> example
|
||||
> l = abs(a*b)/example.gcd(a,b);
|
||||
> swigexample
|
||||
> l = abs(a*b)/swigexample.gcd(a,b);
|
||||
> endfunction
|
||||
octave:2> my_lcm(4,6)
|
||||
ans = 12
|
||||
octave:3> example.gcd(4,6)
|
||||
octave:3> swigexample.gcd(4,6)
|
||||
error: can't perform indexing operations for <unknown type> type
|
||||
octave:3> example;
|
||||
octave:4> example.gcd(4,6)
|
||||
octave:3> swigexample;
|
||||
octave:4> swigexample.gcd(4,6)
|
||||
ans = 2
|
||||
</pre></div>
|
||||
|
||||
|
|
@ -257,14 +221,14 @@ ans = 2
|
|||
Global functions are wrapped as new Octave built-in functions. For example,
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>%module example
|
||||
<div class="code"><pre>%module swigexample
|
||||
int fact(int n); </pre></div>
|
||||
|
||||
<p>
|
||||
creates a built-in function <tt>example.fact(n)</tt> that works exactly like you think it does:
|
||||
creates a built-in function <tt>swigexample.fact(n)</tt> that works exactly like you think it does:
|
||||
</p>
|
||||
|
||||
<div class="targetlang"><pre>octave:1> example.fact(4)
|
||||
<div class="targetlang"><pre>octave:1> swigexample.fact(4)
|
||||
24 </pre></div>
|
||||
|
||||
<H3><a name="Octave_nn10"></a>30.3.3 Global variables</H3>
|
||||
|
|
@ -274,28 +238,28 @@ int fact(int n); </pre></div>
|
|||
Global variables are a little special in Octave. Given a global variable:
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>%module example
|
||||
<div class="code"><pre>%module swigexample
|
||||
extern double Foo;
|
||||
</pre></div>
|
||||
</pre></div>
|
||||
|
||||
<p>
|
||||
To expose variables, SWIG actually generates two functions, to get and set the value. In this case, Foo_set and Foo_set would be generated. SWIG then automatically calls these functions when you get and set the variable-- in the former case creating a local copy in the interpreter of the C variables, and in the latter case copying an interpreter variables onto the C variable.
|
||||
</p>
|
||||
|
||||
<div class="targetlang"><pre>octave:1> example;
|
||||
octave:2> c=example.cvar.Foo
|
||||
<div class="targetlang"><pre>octave:1> swigexample;
|
||||
octave:2> c=swigexample.cvar.Foo
|
||||
c = 3
|
||||
octave:3> example.cvar.Foo=4;
|
||||
octave:3> swigexample.cvar.Foo=4;
|
||||
octave:4> c
|
||||
c = 3
|
||||
octave:5> example.cvar.Foo
|
||||
octave:5> swigexample.cvar.Foo
|
||||
ans = 4</pre></div>
|
||||
|
||||
<p>
|
||||
If a variable is marked with the %immutable directive then any attempts to set this variable will cause an Octave error. Given a global variable:
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>%module example
|
||||
<div class="code"><pre>%module swigexample
|
||||
%immutable;
|
||||
extern double Foo;
|
||||
%mutable;
|
||||
|
|
@ -305,8 +269,8 @@ extern double Foo;
|
|||
SWIG will allow the reading of <tt>Foo</tt> but when a set attempt is made, an error function will be called.
|
||||
</p>
|
||||
|
||||
<div class="targetlang"><pre>octave:1> example
|
||||
octave:2> example.Foo=4
|
||||
<div class="targetlang"><pre>octave:1> swigexample
|
||||
octave:2> swigexample.Foo=4
|
||||
error: attempt to set immutable member variable
|
||||
error: assignment failed, or no method for `swig_type = scalar'
|
||||
error: evaluating assignment expression near line 2, column 12 </pre></div>
|
||||
|
|
@ -315,9 +279,9 @@ error: evaluating assignment expression near line 2, column 12 </pre></div>
|
|||
It is possible to add new functions or variables to the module. This also allows the user to rename/remove existing functions and constants (but not linked variables, mutable or immutable). Therefore users are recommended to be careful when doing so.
|
||||
</p>
|
||||
|
||||
<div class="targetlang"><pre>octave:1> example;
|
||||
octave:2> example.PI=3.142;
|
||||
octave:3> example.PI
|
||||
<div class="targetlang"><pre>octave:1> swigexample;
|
||||
octave:2> swigexample.PI=3.142;
|
||||
octave:3> swigexample.PI
|
||||
ans = 3.1420 </pre></div>
|
||||
|
||||
<H3><a name="Octave_nn11"></a>30.3.4 Constants and enums</H3>
|
||||
|
|
@ -327,7 +291,7 @@ ans = 3.1420 </pre></div>
|
|||
Because Octave doesn't really have the concept of constants, C/C++ constants are not really constant in Octave. They are actually just a copy of the value into the Octave interpreter. Therefore they can be changed just as any other value. For example given some constants:
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>%module example
|
||||
<div class="code"><pre>%module swigexample
|
||||
%constant int ICONST=42;
|
||||
#define SCONST "Hello World"
|
||||
enum Days{SUNDAY,MONDAY,TUESDAY,WEDNESDAY,THURSDAY,FRIDAY,SATURDAY};
|
||||
|
|
@ -337,9 +301,9 @@ enum Days{SUNDAY,MONDAY,TUESDAY,WEDNESDAY,THURSDAY,FRIDAY,SATURDAY};
|
|||
This is 'effectively' converted into the following Octave code:
|
||||
</p>
|
||||
|
||||
<div class="targetlang"><pre>example.ICONST=42
|
||||
example.SCONST="Hello World"
|
||||
example.SUNDAY=0
|
||||
<div class="targetlang"><pre>swigexample.ICONST=42
|
||||
swigexample.SCONST="Hello World"
|
||||
swigexample.SUNDAY=0
|
||||
.... </pre></div>
|
||||
|
||||
<H3><a name="Octave_nn12"></a>30.3.5 Pointers</H3>
|
||||
|
|
@ -350,7 +314,7 @@ example.SUNDAY=0
|
|||
C/C++ pointers are fully supported by SWIG. Furthermore, SWIG has no problem working with incomplete type information. Given a wrapping of the <file.h> interface:
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>%module example
|
||||
<div class="code"><pre>%module swigexample
|
||||
FILE *fopen(const char *filename, const char *mode);
|
||||
int fputs(const char *, FILE *);
|
||||
int fclose(FILE *);
|
||||
|
|
@ -361,18 +325,18 @@ When wrapped, you will be able to use the functions in a natural way from Octave
|
|||
</p>
|
||||
|
||||
<div class="targetlang"><pre>
|
||||
octave:1> example;
|
||||
octave:2> f=example.fopen("w","junk");
|
||||
octave:3> example.fputs("Hello world",f);
|
||||
octave:4> example.fclose(f);
|
||||
octave:1> swigexample;
|
||||
octave:2> f=swigexample.fopen("w","junk");
|
||||
octave:3> swigexample.fputs("Hello world",f);
|
||||
octave:4> swigexample.fclose(f);
|
||||
</pre></div>
|
||||
|
||||
<p>
|
||||
Simply printing the value of a wrapped C++ type will print it's typename. E.g.,
|
||||
</p>
|
||||
|
||||
<div class="targetlang"><pre>octave:1> example;
|
||||
octave:2> f=example.fopen("junk","w");
|
||||
<div class="targetlang"><pre>octave:1> swigexample;
|
||||
octave:2> f=swigexample.fopen("junk","w");
|
||||
octave:3> f
|
||||
f =
|
||||
|
||||
|
|
@ -384,8 +348,8 @@ f =
|
|||
As the user of the pointer, you are responsible for freeing it, or closing any resources associated with it (just as you would in a C program). This does not apply so strictly to classes and structs (see below).
|
||||
</p>
|
||||
|
||||
<div class="targetlang"><pre>octave:1> example;
|
||||
octave:2> f=example.fopen("not there","r");
|
||||
<div class="targetlang"><pre>octave:1> swigexample;
|
||||
octave:2> f=swigexample.fopen("not there","r");
|
||||
error: value on right hand side of assignment is undefined
|
||||
error: evaluating assignment expression near line 2, column 2 </pre></div>
|
||||
|
||||
|
|
@ -407,8 +371,8 @@ For each wrapped structure and class, a <tt>swig_ref</tt> will be exposed that h
|
|||
</p>
|
||||
|
||||
<div class="targetlang">
|
||||
<pre>octave:1> example;
|
||||
octave:2> p=example.Point();
|
||||
<pre>octave:1> swigexample;
|
||||
octave:2> p=swigexample.Point();
|
||||
octave:3> p.x=3;
|
||||
octave:4> p.y=5;
|
||||
octave:5> p.x, p.y
|
||||
|
|
@ -442,9 +406,9 @@ public:
|
|||
can be used from Octave like this
|
||||
</p>
|
||||
<div class="targetlang">
|
||||
<pre>octave:1> example;
|
||||
octave:2> p1=example.Point(3,5);
|
||||
octave:3> p2=example.Point(1,2);
|
||||
<pre>octave:1> swigexample;
|
||||
octave:2> p1=swigexample.Point(3,5);
|
||||
octave:3> p2=swigexample.Point(1,2);
|
||||
octave:4> p1.distance(p2)
|
||||
ans = 3.6056
|
||||
</pre></div>
|
||||
|
|
@ -685,7 +649,7 @@ C++ class and function templates are fully supported as in other modules, in tha
|
|||
For example, function templates can be instantiated as follows:
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>%module example
|
||||
<div class="code"><pre>%module swigexample
|
||||
%inline {
|
||||
template<class __scalar>
|
||||
__scalar mul(__scalar a,__scalar b) {
|
||||
|
|
@ -713,7 +677,7 @@ ans = 22 + 46i
|
|||
Similarly, class templates can be instantiated as in the following example,
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>%module example
|
||||
<div class="code"><pre>%module swigexample
|
||||
%include <std_complex.i>
|
||||
%include <std_string.i>
|
||||
%inline {
|
||||
|
|
|
|||
|
|
@ -170,8 +170,8 @@ $ perl -e 'use Config; print "$Config{archlib}\n";'
|
|||
|
||||
<p>
|
||||
The preferred approach to building an extension module is to compile it into
|
||||
a shared object file or DLL. To do this, you will need to compile your program
|
||||
using commands like this (shown for Linux):
|
||||
a shared object file or DLL. Assuming you have code you need to link to in a file called <tt>example.c</tt>,
|
||||
you will need to compile your program using commands like this (shown for Linux):
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
|
|
|
|||
|
|
@ -146,7 +146,7 @@ least work for Linux though):
|
|||
|
||||
<p>
|
||||
To test the extension from a PHP script, you need to load it first. You
|
||||
can load it for every script by adding this line the <tt>[PHP]</tt> section of
|
||||
can load it for every script by adding this line to the <tt>[PHP]</tt> section of
|
||||
<tt>php.ini</tt>:
|
||||
</p>
|
||||
|
||||
|
|
@ -156,7 +156,7 @@ can load it for every script by adding this line the <tt>[PHP]</tt> section of
|
|||
|
||||
<p>
|
||||
Alternatively, you can load it explicitly only for scripts which need it
|
||||
by adding this line:
|
||||
by adding this line to the start of each such PHP script::
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
|
|
@ -164,7 +164,7 @@ by adding this line:
|
|||
</pre></div>
|
||||
|
||||
<p>
|
||||
to the start of each PHP file. SWIG also generates a php module, which
|
||||
SWIG also generates a php module, which
|
||||
attempts to do the <tt>dl()</tt> call for you:
|
||||
</p>
|
||||
|
||||
|
|
@ -506,6 +506,12 @@ this, one needs to include <b>phppointers.i</b> which defines the
|
|||
named typemap REFERENCE.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
However, this relies on call-time pass-by-reference, which has been
|
||||
deprecated in PHP for some time, and was finally <b>removed in PHP 5.4</b>.
|
||||
So you should avoid creating new wrappers which rely on this approach.
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
%module example
|
||||
%include "phppointers.i"
|
||||
|
|
@ -705,7 +711,7 @@ would be accessed in PHP as,
|
|||
<div class="code"><pre>
|
||||
include("example.php");
|
||||
|
||||
echo "There has now been " . Ko::threats() . " threats\n";
|
||||
echo "There have now been " . Ko::threats() . " threats\n";
|
||||
|
||||
</pre></div>
|
||||
|
||||
|
|
@ -718,7 +724,7 @@ function, e.g.
|
|||
|
||||
Ko::threats(10);
|
||||
|
||||
echo "There has now been " . Ko::threats() . " threats\n";
|
||||
echo "There have now been " . Ko::threats() . " threats\n";
|
||||
|
||||
</pre></div>
|
||||
<H4><a name="Php_nn2_6_4"></a>32.2.6.4 Static Member Functions</H4>
|
||||
|
|
@ -895,9 +901,6 @@ globally, to specific classes, and to specific methods, like this:
|
|||
|
||||
// generate directors for all virtual methods in class Foo
|
||||
%feature("director") Foo;
|
||||
|
||||
// generate a director for just Foo::bar()
|
||||
%feature("director") Foo::bar;
|
||||
</pre>
|
||||
</div>
|
||||
|
||||
|
|
|
|||
|
|
@ -12,13 +12,23 @@
|
|||
<ul>
|
||||
<li><a href="#Preface_nn2">Introduction</a>
|
||||
<li><a href="#Preface_nn4">SWIG Versions</a>
|
||||
<li><a href="#Preface_license">SWIG License</a>
|
||||
<li><a href="#Preface_nn5">SWIG resources</a>
|
||||
<li><a href="#Preface_nn6">Prerequisites</a>
|
||||
<li><a href="#Preface_nn7">Organization of this manual</a>
|
||||
<li><a href="#Preface_nn8">How to avoid reading the manual</a>
|
||||
<li><a href="#Preface_nn9">Backwards compatibility</a>
|
||||
<li><a href="#Preface_release_notes">Release notes</a>
|
||||
<li><a href="#Preface_nn10">Credits</a>
|
||||
<li><a href="#Preface_nn11">Bug reports</a>
|
||||
<li><a href="#Preface_installation">Installation</a>
|
||||
<ul>
|
||||
<li><a href="#Preface_windows_installation">Windows installation</a>
|
||||
<li><a href="#Preface_unix_installation">Unix installation</a>
|
||||
<li><a href="#Preface_osx_installation">Macintosh OS X installation</a>
|
||||
<li><a href="#Preface_testing">Testing</a>
|
||||
<li><a href="#Preface_examples">Examples</a>
|
||||
</ul>
|
||||
</ul>
|
||||
</div>
|
||||
<!-- INDEX -->
|
||||
|
|
@ -57,13 +67,26 @@ In the late 1990's, the most stable version of SWIG was release
|
|||
over a period of 10 years starting from the year 2000. The final version in the 1.3.x
|
||||
series was 1.3.40, but in truth the 1.3.x series had been stable for many years.
|
||||
An official stable version was released along with the decision to make SWIG
|
||||
license changes and this gave rise to version 2.0.0 in 2010. The license was clarified
|
||||
license changes and this gave rise to version 2.0.0 in 2010.
|
||||
</p>
|
||||
|
||||
<H2><a name="Preface_license"></a>1.3 SWIG License</H2>
|
||||
|
||||
|
||||
<p>
|
||||
The LICENSE file shipped with SWIG in the top level directory contains the SWIG license.
|
||||
For further insight into the license including the license of SWIG's output code, please visit
|
||||
the SWIG legal page - <a href="http://www.swig.org/legal.html">http://www.swig.org/legal.html</a>.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
The license was clarified in version 2.0.0
|
||||
so that the code that SWIG generated could be distributed
|
||||
under license terms of the user's choice/requirements and at the same time the SWIG
|
||||
source was placed under the GNU General Public License version 3.
|
||||
</p>
|
||||
|
||||
<H2><a name="Preface_nn5"></a>1.3 SWIG resources</H2>
|
||||
<H2><a name="Preface_nn5"></a>1.4 SWIG resources</H2>
|
||||
|
||||
|
||||
<p>
|
||||
|
|
@ -93,16 +116,17 @@ SWIG along with information about beta releases and future work.
|
|||
</p>
|
||||
|
||||
<p>
|
||||
Subversion access to the latest version of SWIG is also available. More information
|
||||
Git and Subversion access to the latest version of SWIG is also available. More information
|
||||
about this can be obtained at:
|
||||
</p>
|
||||
|
||||
<div class="shell"><pre>
|
||||
<a href="http://www.swig.org/svn.html">http://www.swig.org/svn.html</a>
|
||||
<a href="http://www.swig.org/svn.html">SWIG Bleeding Edge</a>
|
||||
</pre></div>
|
||||
|
||||
|
||||
<H2><a name="Preface_nn6"></a>1.4 Prerequisites</H2>
|
||||
|
||||
<H2><a name="Preface_nn6"></a>1.5 Prerequisites</H2>
|
||||
|
||||
|
||||
<p>
|
||||
|
|
@ -127,7 +151,7 @@ However, this isn't meant to be a tutorial on C++ programming. For many
|
|||
of the gory details, you will almost certainly want to consult a good C++ reference. If you don't program
|
||||
in C++, you may just want to skip those parts of the manual.
|
||||
|
||||
<H2><a name="Preface_nn7"></a>1.5 Organization of this manual</H2>
|
||||
<H2><a name="Preface_nn7"></a>1.6 Organization of this manual</H2>
|
||||
|
||||
|
||||
<p>
|
||||
|
|
@ -139,7 +163,7 @@ can probably skip to that chapter and find almost everything you need
|
|||
to know.
|
||||
</p>
|
||||
|
||||
<H2><a name="Preface_nn8"></a>1.6 How to avoid reading the manual</H2>
|
||||
<H2><a name="Preface_nn8"></a>1.7 How to avoid reading the manual</H2>
|
||||
|
||||
|
||||
<p>
|
||||
|
|
@ -151,7 +175,7 @@ The SWIG distribution also comes with a large directory of
|
|||
examples that illustrate different topics.
|
||||
</p>
|
||||
|
||||
<H2><a name="Preface_nn9"></a>1.7 Backwards compatibility</H2>
|
||||
<H2><a name="Preface_nn9"></a>1.8 Backwards compatibility</H2>
|
||||
|
||||
|
||||
<p>
|
||||
|
|
@ -162,8 +186,8 @@ this isn't always possible as the
|
|||
primary goal over time is to make SWIG
|
||||
better---a process that would simply be impossible if the developers
|
||||
are constantly bogged down with backwards compatibility issues.
|
||||
Potential incompatibilities are clearly marked in the detailed release notes
|
||||
(CHANGES files).
|
||||
Potential incompatibilities are clearly marked in the detailed
|
||||
<a href="#Preface_release_notes">release notes</a>.
|
||||
</p>
|
||||
|
||||
|
||||
|
|
@ -187,7 +211,16 @@ Note: The version symbol is not defined in the generated SWIG
|
|||
wrapper file. The SWIG preprocessor has defined SWIG_VERSION since SWIG-1.3.11.
|
||||
</p>
|
||||
|
||||
<H2><a name="Preface_nn10"></a>1.8 Credits</H2>
|
||||
<H2><a name="Preface_release_notes"></a>1.9 Release notes</H2>
|
||||
|
||||
|
||||
<p>
|
||||
The CHANGES.current, CHANGES and RELEASENOTES files shipped with SWIG in the top level directory
|
||||
contain, respectively, detailed release notes for the current version,
|
||||
detailed release notes for previous releases and summary release notes from SWIG-1.3.22 onwards.
|
||||
</p>
|
||||
|
||||
<H2><a name="Preface_nn10"></a>1.10 Credits</H2>
|
||||
|
||||
|
||||
<p>
|
||||
|
|
@ -200,7 +233,7 @@ who have made contributions at all levels over time. Contributors
|
|||
are mentioned either in the COPYRIGHT file or CHANGES files shipped with SWIG or in submitted bugs.
|
||||
</p>
|
||||
|
||||
<H2><a name="Preface_nn11"></a>1.9 Bug reports</H2>
|
||||
<H2><a name="Preface_nn11"></a>1.11 Bug reports</H2>
|
||||
|
||||
|
||||
<p>
|
||||
|
|
@ -215,5 +248,204 @@ used, and any important pieces of the SWIG generated wrapper code. We
|
|||
can only fix bugs if we know about them.
|
||||
</p>
|
||||
|
||||
<H2><a name="Preface_installation"></a>1.12 Installation</H2>
|
||||
|
||||
|
||||
<H3><a name="Preface_windows_installation"></a>1.12.1 Windows installation</H3>
|
||||
|
||||
|
||||
<p>
|
||||
Please see the dedicated <a href="Windows.html">Windows chapter</a> for instructions on installing
|
||||
SWIG on Windows and running the examples. The Windows distribution is
|
||||
called swigwin and includes a prebuilt SWIG executable, swig.exe, included in
|
||||
the top level directory. Otherwise it is exactly the same as
|
||||
the main SWIG distribution. There is no need to download anything else.
|
||||
</p>
|
||||
|
||||
<H3><a name="Preface_unix_installation"></a>1.12.2 Unix installation</H3>
|
||||
|
||||
|
||||
<p>
|
||||
You must use <a href="http://www.gnu.org/software/make/">GNU make</a> to build and install SWIG.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
<a href="http://www.pcre.org/">PCRE</a>
|
||||
needs to be installed on your system to build SWIG, in particular
|
||||
pcre-config must be available. If you have PCRE headers and libraries but not
|
||||
pcre-config itself or, alternatively, wish to override the compiler or linker
|
||||
flags returned by pcre-config, you may set PCRE_LIBS and PCRE_CFLAGS variables
|
||||
to be used instead. And if you don't have PCRE at all, the configure script
|
||||
will provide instructions for obtaining it.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
To build and install SWIG, simply type the following:
|
||||
</p>
|
||||
|
||||
<div class="shell"><pre>
|
||||
$ ./configure
|
||||
$ make
|
||||
$ make install
|
||||
</pre></div>
|
||||
|
||||
<p>
|
||||
By default SWIG installs itself in /usr/local. If you need to install SWIG in
|
||||
a different location or in your home directory, use the <tt>--prefix</tt> option
|
||||
to <tt>./configure</tt>. For example:
|
||||
</p>
|
||||
|
||||
<div class="shell"><pre>
|
||||
$ ./configure --prefix=/home/yourname/projects
|
||||
$ make
|
||||
$ make install
|
||||
</pre></div>
|
||||
|
||||
<p>
|
||||
Note: the directory given to <tt>--prefix</tt> must be an absolute pathname. Do <b>not</b> use
|
||||
the ~ shell-escape to refer to your home directory. SWIG won't work properly
|
||||
if you do this.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
The INSTALL file shipped in the top level directory details more about using configure. Also try
|
||||
</p>
|
||||
|
||||
<div class="shell"><pre>
|
||||
$ ./configure --help.
|
||||
</pre></div>
|
||||
|
||||
<p>
|
||||
The configure script will attempt to locate various packages on your machine
|
||||
including Tcl, Perl5, Python and all the other target languages that SWIG
|
||||
supports. Don't panic if you get 'not found' messages -- SWIG does not need these
|
||||
packages to compile or run. The configure script is actually looking for
|
||||
these packages so that you can try out the SWIG examples contained
|
||||
in the 'Examples' directory without having to hack Makefiles.
|
||||
Note that the <tt>--without-xxx</tt> options, where xxx is a target language, have
|
||||
minimal effect. All they do is reduce the amount of testing done with
|
||||
'make check'. The SWIG executable and library files installed cannot currently
|
||||
be configured with a subset of target languages.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
SWIG used to include a set of runtime libraries for some languages for working
|
||||
with multiple modules. These are no longer built during the installation stage.
|
||||
However, users can build them just like any wrapper module as described in
|
||||
the <a href="Modules.html">Modules chapter</a>.
|
||||
The CHANGES file shipped with SWIG in the top level directory
|
||||
also lists some examples which build the runtime library.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Note:
|
||||
</p>
|
||||
|
||||
<ul>
|
||||
<li>
|
||||
If you checked the code out via Git, you will have to run <tt>./autogen.sh</tt>
|
||||
before <tt>./configure</tt>. In addition, a full build of SWIG requires
|
||||
a number of packages to be installed. Full instructions at
|
||||
<a href="http://www.swig.org/svn.html">SWIG bleeding edge</a>.
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
<H3><a name="Preface_osx_installation"></a>1.12.3 Macintosh OS X installation</H3>
|
||||
|
||||
|
||||
<p>
|
||||
SWIG is known to work on various flavors of OS X. Follow the Unix installation
|
||||
instructions above. However, as of this writing, there is still great deal of
|
||||
inconsistency with how shared libaries are handled by various scripting languages
|
||||
on OS X.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Users of OS X should be aware that Darwin handles shared libraries and linking in
|
||||
a radically different way than most Unix systems. In order to test SWIG and run
|
||||
the examples, SWIG configures itself to use flat namespaces and to allow undefined
|
||||
symbols (<tt>-flat_namespace -undefined suppress</tt>). This mostly closely follows the Unix
|
||||
model and makes it more likely that the SWIG examples will work with whatever
|
||||
installation of software you might have. However, this is generally not the recommended
|
||||
technique for building larger extension modules. Instead, you should utilize
|
||||
Darwin's two-level namespaces. Some details about this can be found here
|
||||
|
||||
<a href="http://developer.apple.com/documentation/ReleaseNotes/DeveloperTools/TwoLevelNamespaces.html">http://developer.apple.com/documentation/ReleaseNotes/DeveloperTools/TwoLevelNamespaces.html</a>.
|
||||
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Needless to say, you might have to experiment a bit to get things working at first.
|
||||
</p>
|
||||
|
||||
<H3><a name="Preface_testing"></a>1.12.4 Testing</H3>
|
||||
|
||||
|
||||
<p>
|
||||
If you want to test SWIG after building it, a check can be performed on Unix operating systems.
|
||||
Type the following:
|
||||
</p>
|
||||
|
||||
<div class="shell"><pre>
|
||||
$ make -k check
|
||||
</pre></div>
|
||||
|
||||
<p>
|
||||
This step can be performed either before or after installation.
|
||||
The check requires at least one of the target languages to be
|
||||
installed. If it fails, it may mean that you have an uninstalled
|
||||
language module or that the file 'Examples/Makefile' has been
|
||||
incorrectly configured. It may also fail due to compiler issues such
|
||||
as a broken C++ compiler. Even if the check fails, there is a
|
||||
pretty good chance SWIG still works correctly --- you will just have to
|
||||
mess around with one of the examples and some makefiles to get it to work.
|
||||
Some tests may also fail due to missing dependency packages, eg PCRE
|
||||
or Boost, but this will require careful analysis of the configure output
|
||||
done during configuration.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
The test suite executed by the check is designed to stress-test
|
||||
many parts of the implementation including obscure corner cases. If some
|
||||
of these tests fail or generate warning messages, there is no reason for
|
||||
alarm --- the test may be related to some new SWIG feature or a difficult bug
|
||||
that we're trying to resolve. Chances are that SWIG will work just fine
|
||||
for you. Note that if you have more than one CPU/core, then you can use
|
||||
parallel make to speed up the check as it does take quite some time to run,
|
||||
for example:
|
||||
</p>
|
||||
|
||||
<div class="shell"><pre>
|
||||
$ make -j2 -k check
|
||||
</pre></div>
|
||||
|
||||
<p>
|
||||
Also, SWIG's support for C++ is sufficiently advanced that certain
|
||||
tests may fail on older C++ compilers (for instance if your compiler
|
||||
does not support member templates). These errors are harmless if you
|
||||
don't intend to use these features in your own programs.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Note: The test-suite currently contains over 500 tests. If you
|
||||
have many different target languages installed and a slow machine, it
|
||||
might take more than an hour to run the test-suite.
|
||||
</p>
|
||||
|
||||
<H3><a name="Preface_examples"></a>1.12.5 Examples</H3>
|
||||
|
||||
|
||||
<p>
|
||||
The Examples directory contains a variety of examples of using SWIG
|
||||
and it has some browsable documentation. Simply point your browser to
|
||||
the file "Example/index.html".
|
||||
</p>
|
||||
|
||||
<p>
|
||||
The Examples directory also includes Visual C++ project 6 (.dsp) files for
|
||||
building some of the examples on Windows. Later versions of Visual Studio
|
||||
will convert these old style project files into a current solution file.
|
||||
</p>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
|
|
|
|||
|
|
@ -2345,7 +2345,7 @@ doesn't know how to add an instance of <tt>MyString</tt> to itself.
|
|||
</li>
|
||||
|
||||
<li><p>If you have multiple SWIG modules that share type information (<a href="Modules.html#Modules_nn2">more info</a>),
|
||||
the <tt>-builtin</tt> option requiress a bit of extra discipline to ensure that base classes are initialized before derived classes. Specifically:</p>
|
||||
the <tt>-builtin</tt> option requires a bit of extra discipline to ensure that base classes are initialized before derived classes. Specifically:</p>
|
||||
<ul>
|
||||
<li><p>There must be an unambiguous dependency graph for the modules.</p></li>
|
||||
<li><p>Module dependencies must be explicitly stated with <tt>%import</tt> statements in the SWIG interface file.</p>
|
||||
|
|
@ -2782,9 +2782,6 @@ globally, to specific classes, and to specific methods, like this:
|
|||
|
||||
// generate directors for all virtual methods in class Foo
|
||||
%feature("director") Foo;
|
||||
|
||||
// generate a director for just Foo::bar()
|
||||
%feature("director") Foo::bar;
|
||||
</pre>
|
||||
</div>
|
||||
|
||||
|
|
@ -3389,7 +3386,39 @@ public:
|
|||
</pre>
|
||||
</div>
|
||||
|
||||
<p>
|
||||
Note that when the underlying C++ method is overloaded, there is only one proxy Python method
|
||||
for multiple C++ methods. In this case, only one of parsed methods is examined
|
||||
for the feature. You are better off specifying the feature without the argument list to ensure it will get used,
|
||||
as it will then get attached to all the overloaded C++ methods. For example:
|
||||
</p>
|
||||
|
||||
<div class="code">
|
||||
<pre>
|
||||
%module example
|
||||
|
||||
// Add python code to bar()
|
||||
|
||||
%pythonprepend Foo::bar %{
|
||||
#do something before C++ call
|
||||
%}
|
||||
|
||||
%pythonappend Foo::bar %{
|
||||
#do something after C++ call
|
||||
%}
|
||||
|
||||
|
||||
class Foo {
|
||||
public:
|
||||
int bar(int x);
|
||||
int bar();
|
||||
}
|
||||
</pre>
|
||||
</div>
|
||||
|
||||
<p>
|
||||
The same applies for overloaded constructors.
|
||||
</p>
|
||||
|
||||
|
||||
<H3><a name="Python_nn43"></a>34.6.3 Class extension with %extend</H3>
|
||||
|
|
|
|||
|
|
@ -1,9 +1,9 @@
|
|||
This directory contains the HTML for the SWIG users manual.
|
||||
|
||||
All of this HTML is hand-written. However, section numbering, indices,
|
||||
and the table of contents is generated automatically by the 'maketoc.py'
|
||||
and the table of contents are generated automatically by the 'maketoc.py'
|
||||
script. The Makefile has further information on how the various alternative
|
||||
forms of the documentation is generated from the hand-written HTML.
|
||||
forms of the documentation are generated from the hand-written HTML.
|
||||
|
||||
There are 4 types of boxes that code or whatever can be inside:
|
||||
- <div class="shell">...</div>
|
||||
|
|
|
|||
|
|
@ -398,7 +398,8 @@ can add this: </p>
|
|||
<p> to the end of the <tt>extconf.rb</tt> file. If
|
||||
for some reason you don't want to use the standard approach, you'll
|
||||
need to determine the correct compiler and linker flags for your build
|
||||
platform. For example, a typical sequence of commands for the Linux
|
||||
platform. For example, assuming you have code you need to link to in a file
|
||||
called <tt>example.c</tt>, a typical sequence of commands for the Linux
|
||||
operating system would look something like this: </p>
|
||||
|
||||
|
||||
|
|
@ -3214,7 +3215,7 @@ directive which is unique to the Ruby module and was introduced in SWIG
|
|||
|
||||
|
||||
<div class="code">
|
||||
<pre>%bang sort!(arr);<br><br>int sort(int arr[]); </pre>
|
||||
<pre>%bang sort(int arr[]);<br><br>int sort(int arr[]); </pre>
|
||||
|
||||
|
||||
|
||||
|
|
@ -4925,7 +4926,7 @@ arguments. For example: </p>
|
|||
|
||||
|
||||
<div class="code">
|
||||
<pre>%typemap(in) (char *str, int len) {<br> $1 = STR2CSTR($input);<br> $2 = (int) RSTRING($input)->len;<br>};<br><br>int count(char c, char *str, int len);<br></pre>
|
||||
<pre>%typemap(in) (char *str, int len) {<br> $1 = StringValuePtr($input);<br> $2 = (int) RSTRING($input)->len;<br>};<br><br>int count(char c, char *str, int len);<br></pre>
|
||||
|
||||
|
||||
|
||||
|
|
@ -7134,7 +7135,7 @@ Ruby_Format_TypeError( "$1_name", "$1_type","$symname", $argnum, $input
|
|||
</tr>
|
||||
|
||||
<tr>
|
||||
<td style="font-family: monospace;">char * STR2CSTR(String)</td>
|
||||
<td style="font-family: monospace;">char * StringValuePtr(String)</td>
|
||||
<td style="font-family: monospace;">SWIG_AsCharPtrAndSize(VALUE, char*, size_t, int* alloc)</td>
|
||||
</tr>
|
||||
|
||||
|
|
@ -7517,7 +7518,7 @@ Array instance to be used as a <tt>char **</tt> object. </p>
|
|||
|
||||
|
||||
<div class="code">
|
||||
<pre>%module argv<br><br>// This tells SWIG to treat char ** as a special case<br>%typemap(in) char ** {<br> /* Get the length of the array */<br> int size = RARRAY($input)->len; <br> int i;<br> $1 = (char **) malloc((size+1)*sizeof(char *));<br> /* Get the first element in memory */<br> VALUE *ptr = RARRAY($input)->ptr; <br> for (i=0; i < size; i++, ptr++)<br> /* Convert Ruby Object String to char* */<br> $1[i]= STR2CSTR(*ptr); <br> $1[i]=NULL; /* End of list */<br>}<br><br>// This cleans up the char ** array created before <br>// the function call<br><br>%typemap(freearg) char ** {<br> free((char *) $1);<br>}<br><br>// Now a test function<br>%inline %{<br>int print_args(char **argv) {<br> int i = 0;<br> while (argv[i]) {<br> printf("argv[%d] = %s\n", i,argv[i]);<br> i++;<br> }<br> return i;<br>}<br>%}<br><br></pre>
|
||||
<pre>%module argv<br><br>// This tells SWIG to treat char ** as a special case<br>%typemap(in) char ** {<br> /* Get the length of the array */<br> int size = RARRAY($input)->len; <br> int i;<br> $1 = (char **) malloc((size+1)*sizeof(char *));<br> /* Get the first element in memory */<br> VALUE *ptr = RARRAY($input)->ptr; <br> for (i=0; i < size; i++, ptr++)<br> /* Convert Ruby Object String to char* */<br> $1[i]= StringValuePtr(*ptr); <br> $1[i]=NULL; /* End of list */<br>}<br><br>// This cleans up the char ** array created before <br>// the function call<br><br>%typemap(freearg) char ** {<br> free((char *) $1);<br>}<br><br>// Now a test function<br>%inline %{<br>int print_args(char **argv) {<br> int i = 0;<br> while (argv[i]) {<br> printf("argv[%d] = %s\n", i,argv[i]);<br> i++;<br> }<br> return i;<br>}<br>%}<br><br></pre>
|
||||
|
||||
|
||||
|
||||
|
|
@ -7795,7 +7796,7 @@ equivalents and store them in our local C arrays: </p>
|
|||
|
||||
|
||||
<div class="code">
|
||||
<pre>%typemap(in) (int nattributes, const char **names, const int *values)<br> (VALUE keys_arr, int i, VALUE key, VALUE val) {<br> Check_Type($input, T_HASH);<br> $1 = NUM2INT(rb_funcall($input, rb_intern("size"), 0, NULL));<br> $2 = NULL;<br> $3 = NULL;<br> if ($1 > 0) {<br> $2 = (char **) malloc($1*sizeof(char *));<br> $3 = (int *) malloc($1*sizeof(int));<br> keys_arr = rb_funcall($input, rb_intern("keys"), 0, NULL);<br> for (i = 0; i < $1; i++) {<br> key = rb_ary_entry(keys_arr, i);<br> val = rb_hash_aref($input, key);<br> Check_Type(key, T_STRING);<br> Check_Type(val, T_FIXNUM);<br> <b>$2[i] = STR2CSTR(key);<br> $3[i] = NUM2INT(val);</b><br>}<br>}<br>}<br></pre>
|
||||
<pre>%typemap(in) (int nattributes, const char **names, const int *values)<br> (VALUE keys_arr, int i, VALUE key, VALUE val) {<br> Check_Type($input, T_HASH);<br> $1 = NUM2INT(rb_funcall($input, rb_intern("size"), 0, NULL));<br> $2 = NULL;<br> $3 = NULL;<br> if ($1 > 0) {<br> $2 = (char **) malloc($1*sizeof(char *));<br> $3 = (int *) malloc($1*sizeof(int));<br> keys_arr = rb_funcall($input, rb_intern("keys"), 0, NULL);<br> for (i = 0; i < $1; i++) {<br> key = rb_ary_entry(keys_arr, i);<br> val = rb_hash_aref($input, key);<br> Check_Type(key, T_STRING);<br> Check_Type(val, T_FIXNUM);<br> <b>$2[i] = StringValuePtr(key);<br> $3[i] = NUM2INT(val);</b><br>}<br>}<br>}<br></pre>
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -2699,7 +2699,7 @@ the following declaration :</p>
|
|||
<div class="code"><pre>
|
||||
/* file : vector.h */
|
||||
...
|
||||
typedef struct {
|
||||
typedef struct Vector {
|
||||
double x,y,z;
|
||||
} Vector;
|
||||
|
||||
|
|
@ -2772,7 +2772,7 @@ of the Vector structure. For example:</p>
|
|||
#include "vector.h"
|
||||
%}
|
||||
|
||||
typedef struct {
|
||||
typedef struct Vector {
|
||||
double x,y,z;
|
||||
%extend {
|
||||
Vector(double x, double y, double z) { ... }
|
||||
|
|
@ -2783,7 +2783,7 @@ typedef struct {
|
|||
</pre></div>
|
||||
|
||||
<p>
|
||||
Finally, <tt>%extend</tt> can be used to access externally written
|
||||
Note that <tt>%extend</tt> can be used to access externally written
|
||||
functions provided they follow the naming convention used in this
|
||||
example :</p>
|
||||
|
||||
|
|
@ -2814,7 +2814,7 @@ double Vector_magnitude(Vector *v) {
|
|||
#include "vector.h"
|
||||
%}
|
||||
|
||||
typedef struct {
|
||||
typedef struct Vector {
|
||||
double x,y,z;
|
||||
%extend {
|
||||
Vector(int,int,int); // This calls new_Vector()
|
||||
|
|
@ -2826,6 +2826,37 @@ typedef struct {
|
|||
</pre>
|
||||
</div>
|
||||
|
||||
<p>
|
||||
The name used for %extend should be the name of the struct and not the name of any typedef to the struct.
|
||||
For example:
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
typedef struct Integer {
|
||||
int value;
|
||||
} Int;
|
||||
%extend Integer { ... } /* Correct name */
|
||||
%extend Int { ... } /* Incorrect name */
|
||||
|
||||
struct Float {
|
||||
float value;
|
||||
};
|
||||
typedef struct Float FloatValue;
|
||||
%extend Float { ... } /* Correct name */
|
||||
%extend FloatValue { ... } /* Incorrect name */
|
||||
</pre></div>
|
||||
|
||||
<p>
|
||||
There is one exception to this rule and that is when the struct is anonymously named such as:
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
typedef struct {
|
||||
double value;
|
||||
} Double;
|
||||
%extend Double { ... } /* Okay */
|
||||
</pre></div>
|
||||
|
||||
<p>
|
||||
A little known feature of the <tt>%extend</tt> directive is that
|
||||
it can also be used to add synthesized attributes or to modify the
|
||||
|
|
@ -2862,7 +2893,7 @@ For example, consider this interface:
|
|||
|
||||
<div class="code">
|
||||
<pre>
|
||||
typedef struct {
|
||||
typedef struct Person {
|
||||
char name[50];
|
||||
...
|
||||
} Person;
|
||||
|
|
@ -2876,7 +2907,7 @@ the interface as follows to ensure this occurs whenever a name is read or writte
|
|||
|
||||
<div class="code">
|
||||
<pre>
|
||||
typedef struct {
|
||||
typedef struct Person {
|
||||
%extend {
|
||||
char name[50];
|
||||
}
|
||||
|
|
|
|||
|
|
@ -2838,6 +2838,12 @@ struct Derived : Base {
|
|||
}
|
||||
</pre></div>
|
||||
|
||||
<p>
|
||||
The following special variables are expanded if used within a %extend block:
|
||||
$name, $symname, $overname, $decl, $fulldecl, $parentname and $parentsymname.
|
||||
The <a href="Customization.html#Customization_exception_special_variables">Special variables</a> section provides more information each of these special variables.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
The<tt> %extend</tt> directive follows all of the same conventions
|
||||
as its use with C structures. Please refer to the <a href="SWIG.html#SWIG_adding_member_functions">Adding member functions to C structures</a>
|
||||
|
|
@ -3121,8 +3127,8 @@ nothing is known about <tt>List<int></tt>, you will get a warning message
|
|||
|
||||
<div class="shell">
|
||||
<pre>
|
||||
example.h:42. Nothing known about class 'List<int >' (ignored).
|
||||
example.h:42. Maybe you forgot to instantiate 'List<int >' using %template.
|
||||
example.h:42: Warning 401. Nothing known about class 'List<int >'. Ignored.
|
||||
example.h:42: Warning 401. Maybe you forgot to instantiate 'List<int >' using %template.
|
||||
</pre>
|
||||
</div>
|
||||
|
||||
|
|
@ -3163,7 +3169,7 @@ Don't worry--if you get the order wrong, SWIG should generate a warning message.
|
|||
Occasionally, you may need to tell SWIG about base classes that are defined by templates,
|
||||
but which aren't supposed to be wrapped. Since SWIG is not able to automatically
|
||||
instantiate templates for this purpose, you must do it manually. To do this, simply
|
||||
use <tt>%template</tt> with no name. For example:
|
||||
use the empty template instantiation, that is, <tt>%template</tt> with no name. For example:
|
||||
</p>
|
||||
|
||||
<div class="code">
|
||||
|
|
|
|||
|
|
@ -6,7 +6,7 @@
|
|||
<body bgcolor="#ffffff">
|
||||
<H1><a name="Sections"></a>SWIG-2.0 Documentation</H1>
|
||||
|
||||
Last update : SWIG-2.0.6 (30 April 2012)
|
||||
Last update : SWIG-2.0.10 (in progress)
|
||||
|
||||
<H2>Sections</H2>
|
||||
|
||||
|
|
|
|||
|
|
@ -132,7 +132,8 @@ header file.
|
|||
|
||||
<p>
|
||||
The preferred approach to building an extension module is to compile it into
|
||||
a shared object file or DLL. To do this, you will need to compile your program
|
||||
a shared object file or DLL. Assuming you have code you need to link to in a file
|
||||
called <tt>example.c</tt>, you will need to compile your program
|
||||
using commands like this (shown for Linux):
|
||||
</p>
|
||||
|
||||
|
|
|
|||
|
|
@ -773,7 +773,7 @@ Here are some examples of valid typemap specifications:
|
|||
}
|
||||
|
||||
/* Typemap with modifiers */
|
||||
%typemap(in,doc="integer") int "$1 = gh_scm2int($input);";
|
||||
%typemap(in,doc="integer") int "$1 = scm_to_int($input);";
|
||||
|
||||
/* Typemap applied to patterns of multiple arguments */
|
||||
%typemap(in) (char *str, int len),
|
||||
|
|
|
|||
|
|
@ -398,7 +398,7 @@ int execlp(const char *path, const char *arg, ...);
|
|||
</div>
|
||||
|
||||
<p>
|
||||
Note that <tt>str3</tt> is the name of the last argument, as we have used <tt>%vargars</tt> with 3.
|
||||
Note that <tt>str3</tt> is the name of the last argument, as we have used <tt>%varargs</tt> with 3.
|
||||
Now <tt>execlp("a", "b", "c", "d", "e")</tt> will result in an error as one too many arguments has been passed,
|
||||
as now only 2 additional 'str' arguments can be passed with the 3rd one always using the specified default <tt>NULL</tt>.
|
||||
</p>
|
||||
|
|
@ -509,10 +509,10 @@ like this:
|
|||
|
||||
<div class="code">
|
||||
<pre>
|
||||
%typemap(in) (...)(char *args[10]) {
|
||||
%typemap(in) (...)(char *vargs[10]) {
|
||||
int i;
|
||||
int argc;
|
||||
for (i = 0; i < 10; i++) args[i] = 0;
|
||||
for (i = 0; i < 10; i++) vargs[i] = 0;
|
||||
argc = PyTuple_Size(varargs);
|
||||
if (argc > 10) {
|
||||
PyErr_SetString(PyExc_ValueError, "Too many arguments");
|
||||
|
|
@ -528,7 +528,7 @@ like this:
|
|||
return NULL;
|
||||
}
|
||||
pystr = PyUnicode_AsUTF8String(pyobj);
|
||||
str = PyBytes_AsString(pystr);
|
||||
str = strdup(PyBytes_AsString(pystr));
|
||||
Py_XDECREF(pystr);
|
||||
%#else
|
||||
if (!PyString_Check(pyobj)) {
|
||||
|
|
@ -537,22 +537,34 @@ like this:
|
|||
}
|
||||
str = PyString_AsString(pyobj);
|
||||
%#endif
|
||||
args[i] = str;
|
||||
vargs[i] = str;
|
||||
}
|
||||
$1 = (void *) args;
|
||||
$1 = (void *)vargs;
|
||||
}
|
||||
|
||||
%typemap(freearg) (...) {
|
||||
%#if PY_VERSION_HEX>=0x03000000
|
||||
int i;
|
||||
for (i = 0; i < 10; i++) {
|
||||
free(vargs$argnum[i]);
|
||||
}
|
||||
%#endif
|
||||
}
|
||||
</pre>
|
||||
</div>
|
||||
|
||||
<p>
|
||||
In this typemap, the special variable <tt>varargs</tt> is a tuple
|
||||
In the 'in' typemap, the special variable <tt>varargs</tt> is a tuple
|
||||
holding all of the extra arguments passed (this is specific to the
|
||||
Python module). The typemap then pulls this apart and sticks the
|
||||
values into the array of strings <tt>args</tt>. Then, the array is
|
||||
assigned to <tt>$1</tt> (recall that this is the <tt>void *</tt>
|
||||
variable corresponding to <tt>(...)</tt>). However, this assignment
|
||||
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. The 'freearg' typemap cleans up memory
|
||||
allocated in the 'in' typemap; this code is generated to be called
|
||||
after the <tt>execlp</tt> function is called. To patch everything
|
||||
up, you have to rewrite the
|
||||
underlying action code using the <tt>%feature</tt> directive like
|
||||
this:
|
||||
</p>
|
||||
|
|
@ -560,9 +572,9 @@ this:
|
|||
<div class="code">
|
||||
<pre>
|
||||
%feature("action") execlp {
|
||||
char *args = (char **) arg3;
|
||||
result = execlp(arg1, arg2, args[0], args[1], args[2], args[3], args[4],
|
||||
args[5],args[6],args[7],args[8],args[9], NULL);
|
||||
char **vargs = (char **) arg3;
|
||||
result = execlp(arg1, arg2, vargs[0], vargs[1], vargs[2], vargs[3], vargs[4],
|
||||
vargs[5], vargs[6], vargs[7], vargs[8], vargs[9], NULL);
|
||||
}
|
||||
|
||||
int execlp(const char *path, const char *arg, ...);
|
||||
|
|
@ -839,13 +851,13 @@ of type <tt>va_list</tt>. For example:
|
|||
|
||||
<div class="code">
|
||||
<pre>
|
||||
int vfprintf(FILE *f, const char *fmt, va_list ap);
|
||||
int vprintf(const char *fmt, va_list ap);
|
||||
</pre>
|
||||
</div>
|
||||
|
||||
<p>
|
||||
As far as we know, there is no obvious way to wrap these functions
|
||||
with SWIG. This is because there is no documented way to assemble the
|
||||
As far as we know, there is no obvious way to wrap these functions with
|
||||
SWIG. This is because there is no documented way to assemble the
|
||||
proper va_list structure (there are no C library functions to do it
|
||||
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
|
||||
|
|
@ -853,6 +865,36 @@ call-stack. It's not clear that exporting a <tt>va_list</tt> would
|
|||
have any use or that it would work at all.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
A workaround can be implemented by writing a simple varargs C wrapper and then using the techniques
|
||||
discussed earlier in this chapter for varargs. Below is a simple wrapper for <tt>vprintf</tt> renamed so that
|
||||
it can still be called as <tt>vprintf</tt> from your target language. The <tt>%varargs</tt>
|
||||
used in the example restricts the function to taking one string argument.
|
||||
</p>
|
||||
|
||||
<div class="code">
|
||||
<pre>
|
||||
%{
|
||||
int vprintf(const char *fmt, va_list ap);
|
||||
%}
|
||||
|
||||
%varargs(const char *) my_vprintf;
|
||||
%rename(vprintf) my_vprintf;
|
||||
|
||||
%inline %{
|
||||
int my_vprintf(const char *fmt, ...) {
|
||||
va_list ap;
|
||||
int result;
|
||||
|
||||
va_start(ap, fmt);
|
||||
result = vprintf(fmt, ap);
|
||||
va_end(ap);
|
||||
return result;
|
||||
}
|
||||
%}
|
||||
</pre>
|
||||
</div>
|
||||
|
||||
<H2><a name="Varargs_nn9"></a>13.8 C++ Issues</H2>
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -423,7 +423,8 @@ example.i(4) : Syntax error in input.
|
|||
<li>322. Redundant redeclaration of '<em>name</em>'.
|
||||
<li>323. Recursive scope inheritance of '<em>name</em>'.
|
||||
<li>324. Named nested template instantiations not supported. Processing as if no name was given to %template().
|
||||
<li>325. Nested class not currently supported (<em>name</em> ignored).
|
||||
<li>325. Nested <em>kind</em> not currently supported (<em>name</em> ignored).
|
||||
<li>326. Deprecated %extend name used - the <em>kind</em> name '<em>name</em>' should be used instead of the typedef name '<em>name</em>'.
|
||||
<li>350. operator new ignored.
|
||||
<li>351. operator delete ignored.
|
||||
<li>352. operator+ ignored.
|
||||
|
|
@ -526,6 +527,8 @@ example.i(4) : Syntax error in input.
|
|||
<li>519. %template() contains no name. Template method ignored: <em>declaration</em>
|
||||
<li>520. <em>Base/Derived</em> class '<em>classname1</em>' of '<em>classname2</em>' is not similarly marked as a smart pointer.
|
||||
<li>521. Illegal destructor name <em>name</em>. Ignored.
|
||||
<li>522. Use of an illegal constructor name '<em>name</em>' in %extend is deprecated, the constructor name should be '<em>name</em>'.
|
||||
<li>523. Use of an illegal destructor name '<em>name</em>' in %extend is deprecated, the destructor name should be '<em>name</em>'.
|
||||
</ul>
|
||||
|
||||
<H3><a name="Warnings_nn15"></a>14.9.6 Language module specific (700-899) </H3>
|
||||
|
|
@ -551,6 +554,8 @@ example.i(4) : Syntax error in input.
|
|||
<li>822. Covariant return types not supported in Java. Proxy method will return <em>basetype</em> (Java).
|
||||
<li>823. No javaconstruct typemap defined for <em>type</em> (Java).
|
||||
<li>824. Missing JNI descriptor in directorin typemap defined for <em>type</em> (Java).
|
||||
<li>825. "directorconnect" attribute missing in <em>type</em> "javaconstruct" typemap. (Java).
|
||||
<li>826. The nspace feature is used on '<em>type</em>' without -package. The generated code may not compile as Java does not support types declared in a named package accessing types declared in an unnamed package. (Java).
|
||||
</ul>
|
||||
|
||||
<ul>
|
||||
|
|
|
|||
|
|
@ -236,8 +236,8 @@ The short abbreviated instructions follow...
|
|||
</ul>
|
||||
|
||||
<p>
|
||||
The step by step instructions to download and install MinGW and MSYS, then download and build the latest version of SWIG from SVN follow...
|
||||
Note that the instructions for obtaining SWIG from SVN are also online at <a href="http://www.swig.org/svn.html">SWIG SVN</a>.
|
||||
The step by step instructions to download and install MinGW and MSYS, then download and build the latest version of SWIG from Github follow...
|
||||
Note that the instructions for obtaining SWIG from Github are also online at <a href="http://www.swig.org/svn.html">SWIG Bleeding Edge</a>.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
|
|
@ -300,15 +300,19 @@ tar -zxf bison-2.0-MSYS.tar.gz
|
|||
</li>
|
||||
|
||||
<li>
|
||||
To get the latest SWIG SVN (version from Subversion source control), type in the following:
|
||||
The very latest development version of SWIG is available from <a href="https://github.com/swig/swig">SWIG on Github</a>
|
||||
and can be downloaded as a zip file or if you have Git installed, via Git.
|
||||
Either download the latest <a href="https://github.com/swig/swig/archive/master.zip">Zip file</a> snapshot and unzip and rename the top level folder to /usr/src/swig.
|
||||
|
||||
Otherwise if using Git, type in the following:
|
||||
<div class="shell"><pre>
|
||||
mkdir /usr/src
|
||||
cd /usr/src
|
||||
svn co https://swig.svn.sourceforge.net/svnroot/swig/trunk swig
|
||||
git clone https://github.com/swig/swig.git
|
||||
</pre></div>
|
||||
|
||||
<b>Pitfall note:</b>
|
||||
If you want to check out SWIG to a different folder to the proposed
|
||||
If you want to place SWIG in a different folder to the proposed
|
||||
/usr/src/swig, do not use MSYS emulated windows drive letters, because
|
||||
the autotools will fail miserably on those.
|
||||
</li>
|
||||
|
|
|
|||
|
|
@ -1,25 +1,66 @@
|
|||
#
|
||||
# Patch managed by http://www.holgerschurig.de/patcher.html
|
||||
#
|
||||
# This patch is against htmldoc 1.8.24, and it hacks in support for
|
||||
# This patch is against htmldoc 1.8.27, and it hacks in support for
|
||||
# correctly indenting the <div class=""> sections in the SWIG manual.
|
||||
# This patch should only be used until the 1.9 branch of htmldoc
|
||||
# stabalizes, since the 1.9 branch includes true CSS1 support.
|
||||
# stabilizes, since the 1.9 branch includes true CSS1 support.
|
||||
#
|
||||
# This patch only affects the PDF generation, an unpatched htmldoc
|
||||
# creates the one-page html documentation just fine.
|
||||
#
|
||||
--- htmldoc-1.8.24/htmldoc/ps-pdf.cxx~margin-left
|
||||
+++ htmldoc-1.8.24/htmldoc/ps-pdf.cxx
|
||||
@@ -158,6 +158,7 @@
|
||||
diff -Naur htmldoc-1.8.27/htmldoc/htmldoc.cxx htmldoc-1.8.27-margin-left/htmldoc/htmldoc.cxx
|
||||
--- htmldoc-1.8.27/htmldoc/htmldoc.cxx 2006-03-30 14:01:20.000000000 +0100
|
||||
+++ htmldoc-1.8.27-margin-left/htmldoc/htmldoc.cxx 2013-05-11 10:11:47.428435647 +0100
|
||||
@@ -65,6 +65,8 @@
|
||||
const char *__XOS2RedirRoot(const char *);
|
||||
}
|
||||
#endif
|
||||
+
|
||||
+extern void parse_style(char *);
|
||||
|
||||
|
||||
/*
|
||||
@@ -1115,6 +1117,7 @@
|
||||
else if (compare_strings(argv[i], "--version", 6) == 0)
|
||||
{
|
||||
puts(SVERSION);
|
||||
+ puts("Patched with margin-left.patch");
|
||||
return (0);
|
||||
}
|
||||
else if (compare_strings(argv[i], "--webpage", 3) == 0)
|
||||
@@ -2403,6 +2406,10 @@
|
||||
}
|
||||
else if (strcmp(temp, "--cookies") == 0)
|
||||
file_cookies(temp2);
|
||||
+ else if (strcmp(temp, "--stylesheet") == 0)
|
||||
+ {
|
||||
+ parse_style(temp2);
|
||||
+ }
|
||||
}
|
||||
}
|
||||
|
||||
diff -Naur htmldoc-1.8.27/htmldoc/Makefile htmldoc-1.8.27-margin-left/htmldoc/Makefile
|
||||
--- htmldoc-1.8.27/htmldoc/Makefile 2005-10-28 21:32:59.000000000 +0100
|
||||
+++ htmldoc-1.8.27-margin-left/htmldoc/Makefile 2013-05-11 09:39:04.392367869 +0100
|
||||
@@ -36,7 +36,7 @@
|
||||
OBJS = gui.o file.o html.o htmldoc.o htmllib.o htmlsep.o \
|
||||
http.o http-addr.o http-addrlist.o http-support.o image.o \
|
||||
iso8859.o license.o md5.o progress.o ps-pdf.o rc4.o \
|
||||
- snprintf.o string.o toc.o util.o
|
||||
+ snprintf.o string.o toc.o util.o style.o
|
||||
|
||||
|
||||
#
|
||||
diff -Naur htmldoc-1.8.27/htmldoc/ps-pdf.cxx htmldoc-1.8.27-margin-left/htmldoc/ps-pdf.cxx
|
||||
--- htmldoc-1.8.27/htmldoc/ps-pdf.cxx 2006-08-01 17:58:50.000000000 +0100
|
||||
+++ htmldoc-1.8.27-margin-left/htmldoc/ps-pdf.cxx 2013-05-11 09:37:40.096364957 +0100
|
||||
@@ -160,6 +160,7 @@
|
||||
# undef page_t
|
||||
#endif // __hpux
|
||||
|
||||
+extern int lookup_div_class(uchar *);
|
||||
|
||||
/*
|
||||
* Constants...
|
||||
@@ -4188,9 +4189,24 @@
|
||||
* Output options...
|
||||
@@ -4230,9 +4231,24 @@
|
||||
para->child = para->last_child = NULL;
|
||||
}
|
||||
|
||||
|
|
@ -45,30 +86,9 @@
|
|||
if (para->child != NULL)
|
||||
{
|
||||
parse_paragraph(para, *left, *right, *bottom, *top, x, y, page, *needspace);
|
||||
--- htmldoc-1.8.24/htmldoc/htmldoc.cxx~margin-left
|
||||
+++ htmldoc-1.8.24/htmldoc/htmldoc.cxx
|
||||
@@ -62,6 +62,8 @@
|
||||
const char *__XOS2RedirRoot(const char *);
|
||||
}
|
||||
#endif
|
||||
+
|
||||
+extern void parse_style(char *);
|
||||
|
||||
|
||||
/*
|
||||
@@ -2140,6 +2142,10 @@
|
||||
}
|
||||
else if (strcmp(temp, "--cookies") == 0)
|
||||
file_cookies(temp2);
|
||||
+ else if (strcmp(temp, "--stylesheet") == 0)
|
||||
+ {
|
||||
+ parse_style(temp2);
|
||||
+ }
|
||||
}
|
||||
}
|
||||
|
||||
--- /dev/null
|
||||
+++ htmldoc-1.8.24/htmldoc/style.cxx
|
||||
diff -Naur htmldoc-1.8.27/htmldoc/style.cxx htmldoc-1.8.27-margin-left/htmldoc/style.cxx
|
||||
--- htmldoc-1.8.27/htmldoc/style.cxx 1970-01-01 01:00:00.000000000 +0100
|
||||
+++ htmldoc-1.8.27-margin-left/htmldoc/style.cxx 2013-05-11 09:37:40.096364957 +0100
|
||||
@@ -0,0 +1,185 @@
|
||||
+/* Extreamly simple parsing routines for CSS style sheets.
|
||||
+ * We only parse div.class { } sections, and only look
|
||||
|
|
@ -255,15 +275,3 @@
|
|||
+
|
||||
+ fclose(f);
|
||||
+}
|
||||
--- htmldoc-1.8.24/htmldoc/Makefile~margin-left
|
||||
+++ htmldoc-1.8.24/htmldoc/Makefile
|
||||
@@ -35,7 +35,7 @@
|
||||
|
||||
OBJS = gui.o file.o html.o htmldoc.o htmllib.o htmlsep.o http.o \
|
||||
http-addr.o http-support.o image.o iso8859.o license.o md5.o \
|
||||
- progress.o ps-pdf.o rc4.o snprintf.o string.o toc.o util.o
|
||||
+ progress.o ps-pdf.o rc4.o snprintf.o string.o toc.o util.o style.o
|
||||
|
||||
|
||||
#
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue