Merge branch 'master' into gsoc2009-matevz
parser.y still to be fixed up Conflicts: Doc/Devel/engineering.html Examples/Makefile.in Lib/allegrocl/allegrocl.swg Lib/csharp/csharp.swg Lib/csharp/enums.swg Lib/csharp/enumsimple.swg Lib/csharp/enumtypesafe.swg Lib/java/java.swg Lib/python/pydocs.swg Lib/r/rtype.swg Source/Include/swigwarn.h Source/Modules/octave.cxx Source/Modules/python.cxx Source/Modules/ruby.cxx Source/Swig/scanner.c Source/Swig/stype.c Source/Swig/swig.h configure.ac
This commit is contained in:
William S Fulton
commit
e805d5f925
1074 changed files with 54339 additions and 20134 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$ xxx.c";
|
||||
|
||||
#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>
|
||||
|
|
|
|||
|
|
@ -21,6 +21,7 @@ The following documentation describe the internal APIs used by SWIG. These may
|
|||
<li><a href="parm.html">Parameter and Parameter list handling functions</a>
|
||||
<li><a href="scanner.html">Generic C/C++ Scanner interface</a>
|
||||
<li><a href="wrapobj.html">Wrapper objects</a>.
|
||||
<li><a href="runtime.txt">SWIG Runtime</a>.
|
||||
</ul>
|
||||
|
||||
<hr>
|
||||
|
|
|
|||
|
|
@ -7,11 +7,6 @@
|
|||
<center>
|
||||
<h1>SWIG Internals Manual</h1>
|
||||
|
||||
<b>Thien-Thi Nguyen <br>
|
||||
|
||||
<p>
|
||||
David M. Beazley <br>
|
||||
|
||||
</b>
|
||||
</center>
|
||||
|
||||
|
|
@ -45,6 +40,10 @@ David M. Beazley <br>
|
|||
<li><a name="i5" href="#5">5. C/C++ Wrapper Support Functions</a>
|
||||
<li><a name="i6" href="#6">6. Symbol Naming Guidelines for Generated C/C++ Code</a>
|
||||
<li><a name="i7" href="#7">7. Debugging SWIG</a>
|
||||
<ul>
|
||||
<li><a name="i7.1" href="#7.1">7.1 Debugging DOH Types The Hard Way</a>
|
||||
<li><a name="i7.2" href="#7.2">7.2 Debugging DOH memory allocation problems</a>
|
||||
</ul>
|
||||
</ul>
|
||||
|
||||
<a name="1" href="#i1">
|
||||
|
|
@ -1015,15 +1014,139 @@ In the past SWIG has generated many symbols which flout the standard especially
|
|||
<a name="7" href="#i7">
|
||||
<h2>7. Debugging SWIG</h2>
|
||||
</a>
|
||||
Warning. Debugging SWIG is for the very patient.
|
||||
|
||||
<p>
|
||||
The DOH types used in the SWIG source code are all typedefined to void.
|
||||
Consequently, it is impossible for debuggers to automatically extract any information about DOH objects.
|
||||
The easiest approach to debugging and viewing the contents of DOH objects is to make a call into one of the family of SWIG print functions from the debugger.
|
||||
The "Debugging Functions" section in <a href="tree.html">SWIG Parse Tree Handling</a> lists them.
|
||||
It is sometimes easier to debug by placing a few calls to these functions in code of interest and recompile, especially if your debugger cannot easily make calls into functions within a debugged binary.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
The SWIG distribution comes with some additional support for the gdb debugger in the <tt>Tools/swig.gdb</tt> file.
|
||||
Follow the instructions in this file for 'installing'.
|
||||
This support file provides an easy way to call into some of the family of SWIG print functions via additional user-defined gdb commands.
|
||||
Some usage of the <tt>swigprint</tt> and <tt>locswigprint</tt> user-defined commands are demonstrated below.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
More often than not, a parse tree node needs to be examined.
|
||||
The session below displays the node <tt>n</tt> in one of the Java language module wrapper functions.
|
||||
The <tt>swigprint</tt> method is used to show the symbol name (<tt>symname</tt> - a DOH String type) and the node (<tt>n</tt> - a DOH Hash type).
|
||||
</p>
|
||||
<blockquote>
|
||||
<pre>
|
||||
Breakpoint 1, JAVA::functionWrapper (this=0x97ea5f0, n=0xb7d2afc8) at Modules/java.cxx:799
|
||||
799 String *symname = Getattr(n, "sym:name");
|
||||
(gdb) next
|
||||
800 SwigType *t = Getattr(n, "type");
|
||||
(gdb) swigprint symname
|
||||
Shape_x_set
|
||||
(gdb) swigprint n
|
||||
Hash(0xb7d2afc8) {
|
||||
'membervariableHandler:view' : variableHandler,
|
||||
'feature:except' : 0,
|
||||
'name' : x,
|
||||
'ismember' : 1,
|
||||
'sym:symtab' : Hash(0xb7d2aca8) {......},
|
||||
'nodeType' : cdecl,
|
||||
'nextSibling' : Hash(0xb7d2af98) {.............},
|
||||
'kind' : variable,
|
||||
'variableHandler:feature:immutable' : <Object 'VoidObj' at 0xb7cfa008>,
|
||||
'sym:name' : Shape_x_set,
|
||||
'view' : membervariableHandler,
|
||||
'membervariableHandler:sym:name' : x,
|
||||
'membervariableHandler:type' : double,
|
||||
'membervariableHandler:parms' : <Object 'VoidObj' at 0xb7cfa008>,
|
||||
'parentNode' : Hash(0xb7d2abc8) {..............................},
|
||||
'feature:java:enum' : typesafe,
|
||||
'access' : public,
|
||||
'parms' : Hash(0xb7cb9408) {......},
|
||||
'wrap:action' : if (arg1) (arg1)->x = arg2;,
|
||||
'type' : void,
|
||||
'memberset' : 1,
|
||||
'sym:overname' : __SWIG_0,
|
||||
'membervariableHandler:name' : x,
|
||||
}
|
||||
</pre>
|
||||
</blockquote>
|
||||
|
||||
<p>
|
||||
Note that all the attributes in the Hash are shown, including the 'sym:name' attribute which was assigned to the <tt>symname</tt> variable.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Hash types can be shown either expanded or collapsed.
|
||||
When a Hash is shown expanded, all the attributes are displayed along with their values, otherwise a '.' replaces each attribute when collapsed.
|
||||
Therefore a count of the dots provides the number of attributes within an unexpanded Hash.
|
||||
Below shows the 'parms' Hash being displayed with the default Hash expansion of 1, then with 2 provided as the second argument to <tt>swigprint</tt> to expand to two Hash levels in order to view the contents of the collapsed 'nextSibling' Hash.
|
||||
</p>
|
||||
|
||||
<blockquote>
|
||||
<pre>
|
||||
(gdb) swigprint 0xb7cb9408
|
||||
Hash(0xb7cb9408) {
|
||||
'name' : self,
|
||||
'type' : p.Shape,
|
||||
'self' : 1,
|
||||
'nextSibling' : Hash(0xb7cb9498) {...},
|
||||
'hidden' : 1,
|
||||
'nodeType' : parm,
|
||||
}
|
||||
(gdb) swigprint 0xb7cb9408 2
|
||||
Hash(0xb7cb9408) {
|
||||
'name' : self,
|
||||
'type' : p.Shape,
|
||||
'self' : 1,
|
||||
'nextSibling' : Hash(0xb7cb9498) {
|
||||
'name' : x,
|
||||
'type' : double,
|
||||
'nodeType' : parm,
|
||||
},
|
||||
'hidden' : 1,
|
||||
'nodeType' : parm,
|
||||
}
|
||||
</pre>
|
||||
</blockquote>
|
||||
|
||||
<p>
|
||||
The same Hash can also be displayed with file and line location information via the <tt>locswigprint</tt> command.
|
||||
</p>
|
||||
|
||||
<blockquote>
|
||||
<pre>
|
||||
(gdb) locswigprint 0xb7cb9408
|
||||
example.h:11: [Hash(0xb7cb9408) {
|
||||
Hash(0xb7cb9408) {
|
||||
'name' : self,
|
||||
'type' : p.Shape,
|
||||
'self' : 1,
|
||||
'nextSibling' : Hash(0xb7cb9498) {...},
|
||||
'hidden' : 1,
|
||||
'nodeType' : parm,
|
||||
}]
|
||||
</pre>
|
||||
</blockquote>
|
||||
|
||||
<p>
|
||||
<b>Tip</b>: Commands in gdb can be shortened with whatever makes them unique and can be command completed with the tab key.
|
||||
Thus <tt>swigprint</tt> can usually be shortened to <tt>sw</tt> and <tt>locswigprint</tt> to <tt>loc</tt>.
|
||||
The help for each command can also be obtained within the debugging session, for example, 'help swigprint'.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
The sub-section below gives pointers for debugging DOH objects using casts and provides an insight into why it can be hard to debug SWIG without the family of print functions.
|
||||
<p>
|
||||
|
||||
The DOH types are all typedefined to void.
|
||||
Consequently, it is impossible for debuggers to extract any information about DOH objects.
|
||||
Most debuggers will be able to display useful variable information when an object is cast to the appropriate type.
|
||||
Below are some tips for displaying some of the DOH objects.
|
||||
Be sure to compile with compiler optimisations turned off before attempting the casts shown in a debugger window else they are unlikely to work.
|
||||
Even displaying the underlying string in a String* doesn't work straight off in all debuggers due to the multiple definition of String as a struct and a void.
|
||||
<a name="7.1" href="#i7.1">
|
||||
<h3>7.1 Debugging DOH Types The Hard Way</h3>
|
||||
</a>
|
||||
The DOH types used in SWIG are all typedefined to void and hence the lack of type information for inspecting types within a debugger.
|
||||
Most debuggers will however be able to display useful variable information when an object is cast to the appropriate type.
|
||||
Getting at the underlying C string within DOH types is cumbersome, but possible with appropriate casts.
|
||||
The casts below can be used in a debugger windows, but be sure to compile with compiler optimisations turned off before attempting the casts else they are unlikely to work.
|
||||
Even displaying the underlying string in a String * doesn't work straight off in all debuggers due to the multiple definitions of String as a struct and a void.
|
||||
<p>
|
||||
|
||||
Below are a list of common SWIG types.
|
||||
|
|
@ -1033,34 +1156,56 @@ With each is the cast that can be used in the debugger to extract the underlying
|
|||
|
||||
<p>
|
||||
<li>String *s;</li>
|
||||
<br>
|
||||
(struct String *)((DohBase *)s)->data
|
||||
<tt>(struct String *)((DohBase *)s)->data</tt>
|
||||
<br>
|
||||
The underlying char * string can be displayed with
|
||||
<br>
|
||||
(*(struct String *)(((DohBase *)s)->data)).str
|
||||
<tt>(*(struct String *)(((DohBase *)s)->data)).str</tt>
|
||||
|
||||
<p>
|
||||
<li>SwigType *t;</li>
|
||||
<br>
|
||||
(struct String *)((DohBase *)t)->data
|
||||
<tt>(struct String *)((DohBase *)t)->data</tt>
|
||||
<br>
|
||||
The underlying char * string can be displayed with
|
||||
<br>
|
||||
(*(struct String *)(((DohBase *)t)->data)).str
|
||||
<tt>(*(struct String *)(((DohBase *)t)->data)).str</tt>
|
||||
|
||||
<p>
|
||||
<li>const_String_or_char_ptr sc;</li>
|
||||
Either <br>
|
||||
(*(struct String *)(((DohBase *)sc)->data)).str
|
||||
<tt>(*(struct String *)(((DohBase *)sc)->data)).str</tt>
|
||||
<br> or <br>
|
||||
(char *)sc
|
||||
<tt>(char *)sc</tt>
|
||||
<br> will work depending on whether the underlying type is really a String * or char *.
|
||||
|
||||
</ul>
|
||||
|
||||
<a name="7.2" href="#i7.2">
|
||||
<h3>7.2 Debugging DOH memory allocation problems</h3>
|
||||
</a>
|
||||
|
||||
<p>
|
||||
Please also read the Debugging Functions section in <a href="tree.html">SWIG Parse Tree Handling</a> for the <tt>Swig_print_node()</tt>, <tt>Swig_print_tree()</tt> and <tt>Swig_print_tags()</tt> functions for displaying node contents. It is often easier to place a few calls to these functions in code of interest and recompile than use the debugger.
|
||||
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>
|
||||
|
|
|
|||
|
|
@ -6,13 +6,6 @@
|
|||
<body>
|
||||
<center>
|
||||
<h1>SWIG Parse Tree Handling</h1>
|
||||
|
||||
<p>
|
||||
David M. Beazley <br>
|
||||
dave-swig@dabeaz.com<br>
|
||||
December, 2006<br>
|
||||
|
||||
</b>
|
||||
</center>
|
||||
|
||||
<h2>Introduction</h2>
|
||||
|
|
@ -210,7 +203,33 @@ This function restores a node to the state it was in prior to the last <tt>Swig_
|
|||
|
||||
<h2>Debugging Functions</h2>
|
||||
|
||||
The following functions are used to help debug SWIG parse trees.
|
||||
<p>
|
||||
The following functions can be used to help debug any SWIG DOH object.
|
||||
</p>
|
||||
|
||||
<b><tt>void Swig_print(DOH *object, int count = -1)</tt></b>
|
||||
|
||||
<blockquote>
|
||||
Prints to stdout a string representation of any DOH type.
|
||||
The number of nested Hash types to expand is set by count (default is 1 if count<0). See Swig_set_max_hash_expand() to change default.
|
||||
<pre>
|
||||
</pre>
|
||||
</blockquote>
|
||||
|
||||
<b><tt>void Swig_print_with_location(DOH *object, int count = -1)</tt></b>
|
||||
|
||||
<blockquote>
|
||||
Prints to stdout a string representation of any DOH type, within [] brackets
|
||||
for Hash and List types, prefixed by line and file information.
|
||||
The number of nested Hash types to expand is set by count (default is 1 if count<0). See Swig_set_max_hash_expand() to change default.
|
||||
<pre>
|
||||
</pre>
|
||||
</blockquote>
|
||||
|
||||
|
||||
<p>
|
||||
The following functions can be used to help debug SWIG parse trees.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
<b><tt>void Swig_print_tags(Node *node, String_or_char *prefix)</tt></b>
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue