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

Expand the family of debug print functions for displaying DOH types. Provide gdb support for calling these. Document improved debugging experience.

Browse source 
git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk@12221 626c5289-ae23-0410-ae9c-e8d60b6d4f22
This commit is contained in:
William S Fulton 2010-09-15 20:17:11 +00:00
commit d1e6643161
13 changed files with 421 additions and 47 deletions
Download patch file Download diff file Expand all files Collapse all files

5
CHANGES.current
View file

@ -5,6 +5,11 @@ See the RELEASENOTES file for a summary of changes in each release.
Version 2.0.1 (in progress)
===========================
2010-09-15: wsfulton
A much improved debugging of SWIG source experience is now available and
documented in the "Debugging SWIG" section in the Doc/Devel/internals.html
file, including a swig.dbg support file for the gdb debugger.
2010-09-11: wsfulton
Fix incorrect line number reporting in errors/warnings when a macro
definition ends with '/' and it is not the end of a C comment.

164
Doc/Devel/internals.html
View file

@ -7,11 +7,6 @@
<center>
<h1>SWIG Internals Manual</h1>
<b>Thien-Thi Nguyen <br>
<p>
David M. Beazley <br>
</b>
</center>
@ -45,6 +40,9 @@ 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>
</ul>
</ul>
<a name="1" href="#i1">
@ -1015,15 +1013,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' : &lt;Object 'VoidObj' at 0xb7cfa008&gt;,
'sym:name' : Shape_x_set,
'view' : membervariableHandler,
'membervariableHandler:sym:name' : x,
'membervariableHandler:type' : double,
'membervariableHandler:parms' : &lt;Object 'VoidObj' at 0xb7cfa008&gt;,
'parentNode' : Hash(0xb7d2abc8) {..............................},
'feature:java:enum' : typesafe,
'access' : public,
'parms' : Hash(0xb7cb9408) {......},
'wrap:action' : if (arg1) (arg1)-&gt;x = arg2;,
'type' : void,
'memberset' : 1,
'sym:overname' : __SWIG_0,
'membervariableHandler:name' : x,
}
</pre>
</blockquote>
<p>
Note that all the attributes in the Hash are shown, including the 'sym:name' attribute which was assigned to the <tt>symname</tt> variable.
</p>
<p>
Hash types can be shown either expanded or collapsed.
When a Hash is shown expanded, all the attributes are displayed along with their values, otherwise a '.' replaces each attribute when collapsed.
Therefore a count of the dots provides the number of attributes within an unexpanded Hash.
Below shows the 'parms' Hash being displayed with the default Hash expansion of 1, then with 2 provided as the second argument to <tt>swigprint</tt> to expand to two Hash levels in order to view the contents of the collapsed 'nextSibling' Hash.
</p>
<blockquote>
<pre>
(gdb) swigprint 0xb7cb9408
Hash(0xb7cb9408) {
'name' : self,
'type' : p.Shape,
'self' : 1,
'nextSibling' : Hash(0xb7cb9498) {...},
'hidden' : 1,
'nodeType' : parm,
}
(gdb) swigprint 0xb7cb9408 2
Hash(0xb7cb9408) {
'name' : self,
'type' : p.Shape,
'self' : 1,
'nextSibling' : Hash(0xb7cb9498) {
'name' : x,
'type' : double,
'nodeType' : parm,
},
'hidden' : 1,
'nodeType' : parm,
}
</pre>
</blockquote>
<p>
The same Hash can also be displayed with file and line location information via the <tt>locswigprint</tt> command.
</p>
<blockquote>
<pre>
(gdb) locswigprint 0xb7cb9408
example.h:11: [Hash(0xb7cb9408) {
Hash(0xb7cb9408) {
'name' : self,
'type' : p.Shape,
'self' : 1,
'nextSibling' : Hash(0xb7cb9498) {...},
'hidden' : 1,
'nodeType' : parm,
}]
</pre>
</blockquote>
<p>
<b>Tip</b>: Commands in gdb can be shortened with whatever makes them unique and can be command completed with the tab key.
Thus <tt>swigprint</tt> can usually be shortened to <tt>sw</tt> and <tt>locswigprint</tt> to <tt>loc</tt>.
The help for each command can also be obtained within the debugging session, for example, 'help swigprint'.
</p>
<p>
The sub-section below gives pointers for debugging DOH objects using casts and provides an insight into why it can be hard to debug SWIG without the family of print functions.
<p>
The DOH types are all typedefined to void.
Consequently, it is impossible for debuggers to extract any information about DOH objects.
Most debuggers will be able to display useful variable information when an object is cast to the appropriate type.
Below are some tips for displaying some of the DOH objects.
Be sure to compile with compiler optimisations turned off before attempting the casts shown in a debugger window else they are unlikely to work.
Even displaying the underlying string in a String* doesn't work straight off in all debuggers due to the multiple definition of String as a struct and a void.
<a name="7.1" href="#i7.1">
<h3>7.1 Debugging DOH Types The Hard Way</h3>
</a>
The DOH types used in SWIG are all typedefined to void and hence the lack of type information for inspecting types within a debugger.
Most debuggers will however be able to display useful variable information when an object is cast to the appropriate type.
Getting at the underlying C string within DOH types is cumbersome, but possible with appropriate casts.
The casts below can be used in a debugger windows, but be sure to compile with compiler optimisations turned off before attempting the casts else they are unlikely to work.
Even displaying the underlying string in a String * doesn't work straight off in all debuggers due to the multiple definitions of String as a struct and a void.
<p>
Below are a list of common SWIG types.
@ -1033,36 +1155,30 @@ 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)-&gt;data
<tt>(struct String *)((DohBase *)s)-&gt;data</tt>
<br>
The underlying char * string can be displayed with
<br>
(*(struct String *)(((DohBase *)s)-&gt;data)).str
<tt>(*(struct String *)(((DohBase *)s)-&gt;data)).str</tt>
<p>
<li>SwigType *t;</li>
<br>
(struct String *)((DohBase *)t)-&gt;data
<tt>(struct String *)((DohBase *)t)-&gt;data</tt>
<br>
The underlying char * string can be displayed with
<br>
(*(struct String *)(((DohBase *)t)-&gt;data)).str
<tt>(*(struct String *)(((DohBase *)t)-&gt;data)).str</tt>
<p>
<li>const_String_or_char_ptr sc;</li>
Either <br>
(*(struct String *)(((DohBase *)sc)-&gt;data)).str
<tt>(*(struct String *)(((DohBase *)sc)-&gt;data)).str</tt>
<br> or <br>
(char *)sc
<tt>(char *)sc</tt>
<br> will work depending on whether the underlying type is really a String * or char *.
</ul>
<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.
</p>
<hr>
Copyright (C) 1999-2010 SWIG Development Team.

35
Doc/Devel/tree.html
View file

@ -6,13 +6,6 @@
<body>
<center>
<h1>SWIG Parse Tree Handling</h1>
<p>
David M. Beazley <br>
dave-swig@dabeaz.com<br>
December, 2006<br>
</b>
</center>
<h2>Introduction</h2>
@ -210,7 +203,33 @@ This function restores a node to the state it was in prior to the last <tt>Swig_
<h2>Debugging Functions</h2>
The following functions are used to help debug SWIG parse trees.
<p>
The following functions can be used to help debug any SWIG DOH object.
</p>
<b><tt>void Swig_print(DOH *object, int count = -1)</tt></b>
<blockquote>
Prints to stdout a string representation of any DOH type.
The number of nested Hash types to expand is set by count (default is 1 if count&lt;0). See Swig_set_max_hash_expand() to change default.
<pre>
</pre>
</blockquote>
<b><tt>void Swig_print_with_location(DOH *object, int count = -1)</tt></b>
<blockquote>
Prints to stdout a string representation of any DOH type, within [] brackets
for Hash and List types, prefixed by line and file information.
The number of nested Hash types to expand is set by count (default is 1 if count&lt;0). See Swig_set_max_hash_expand() to change default.
<pre>
</pre>
</blockquote>
<p>
The following functions can be used to help debug SWIG parse trees.
</p>
<p>
<b><tt>void Swig_print_tags(Node *node, String_or_char *prefix)</tt></b>

4
Source/DOH/doh.h
View file

@ -267,6 +267,8 @@ extern int DohIsSequence(const DOH *obj);
extern int DohIsString(const DOH *obj);
extern int DohIsFile(const DOH *obj);
extern void DohSetMaxHashExpand(int count);
extern int DohGetMaxHashExpand(void);
extern void DohSetmark(DOH *obj, int x);
extern int DohGetmark(DOH *obj);
@ -424,6 +426,8 @@ extern void DohMemoryDebug(void);
#define SplitLines DohSplitLines
#define Setmark DohSetmark
#define Getmark DohGetmark
#define SetMaxHashExpand DohSetMaxHashExpand
#define GetMaxHashExpand DohGetMaxHashExpand
#define None DohNone
#define Call DohCall
#define First DohFirst

53
Source/DOH/hash.c
View file

@ -42,6 +42,7 @@ typedef struct KeyValue {
} KeyValue;
static KeyValue *root = 0;
static int max_expand = 1;
/* Find or create a key in the interned key table */
static DOH *find_key(DOH *doh_c) {
@ -378,6 +379,26 @@ static DOH *Hash_keys(DOH *so) {
return keys;
}
/* -----------------------------------------------------------------------------
* DohSetMaxHashExpand()
*
* Controls how many Hash objects are displayed in full in Hash_str
* ----------------------------------------------------------------------------- */
void DohSetMaxHashExpand(int count) {
max_expand = count;
}
/* -----------------------------------------------------------------------------
* DohGetMaxHashExpand()
*
* Returns how many Hash objects are displayed in full in Hash_str
* ----------------------------------------------------------------------------- */
int DohGetMaxHashExpand(void) {
return max_expand;
}
/* -----------------------------------------------------------------------------
* Hash_str()
*
@ -388,7 +409,8 @@ static DOH *Hash_str(DOH *ho) {
int i, j;
HashNode *n;
DOH *s;
static int indent = 4;
static int expanded = 0;
static const char *tab = " ";
Hash *h = (Hash *) ObjData(ho);
s = NewStringEmpty();
@ -396,22 +418,35 @@ static DOH *Hash_str(DOH *ho) {
Printf(s, "Hash(0x%x)", ho);
return s;
}
if (expanded >= max_expand) {
/* replace each hash attribute with a '.' */
Printf(s, "Hash(0x%x) {", ho);
for (i = 0; i < h->hashsize; i++) {
n = h->hashtable[i];
while (n) {
Putc('.', s);
n = n->next;
}
}
Putc('}', s);
return s;
}
ObjSetMark(ho, 1);
Printf(s, "Hash {\n");
Printf(s, "Hash(0x%x) {\n", ho);
for (i = 0; i < h->hashsize; i++) {
n = h->hashtable[i];
while (n) {
for (j = 0; j < indent; j++)
Putc(' ', s);
indent += 4;
for (j = 0; j < expanded + 1; j++)
Printf(s, tab);
expanded += 1;
Printf(s, "'%s' : %s, \n", n->key, n->object);
indent -= 4;
expanded -= 1;
n = n->next;
}
}
for (j = 0; j < (indent - 4); j++)
Putc(' ', s);
Printf(s, "}\n");
for (j = 0; j < expanded; j++)
Printf(s, tab);
Printf(s, "}");
ObjSetMark(ho, 0);
return s;
}

2
Source/DOH/list.c
View file

@ -252,7 +252,7 @@ static DOH *List_str(DOH *lo) {
if ((i + 1) < l->nitems)
Printf(s, ", ");
}
Printf(s, " ]\n");
Printf(s, " ]");
ObjSetMark(lo, 0);
return s;
}

2
Source/Modules/lang.cxx
View file

@ -52,7 +52,7 @@ extern "C" {
return all_protected_mode;
}
void Language_replace_special_variables(String *method, String *tm, Parm *parm) {
Language::instance()->replaceSpecialVariables(method, tm, parm);
Language::instance()->replaceSpecialVariables(method, tm, parm);
}
}

9
Source/Modules/swigmod.h
View file

@ -380,9 +380,15 @@ void Wrapper_fast_dispatch_mode_set(int);
void Wrapper_cast_dispatch_mode_set(int);
void Wrapper_naturalvar_mode_set(int);
void clean_overloaded(Node *n);
extern "C" {
const char *Swig_to_string(DOH *object, int count = -1);
const char *Swig_to_string_with_location(DOH *object, int count = -1);
void Swig_print(DOH *object, int count = -1);
void Swig_print_with_location(DOH *object, int count = -1);
}
/* Contracts */
void Swig_contracts(Node *n);
@ -395,5 +401,4 @@ void Swig_browser(Node *n, int);
void Swig_default_allocators(Node *n);
void Swig_process_types(Node *n);
#endif

113
Source/Modules/utils.cxx
View file

@ -100,3 +100,116 @@ void clean_overloaded(Node *n) {
Delattr(n, "sym:overloaded");
}
}
/* -----------------------------------------------------------------------------
* Swig_set_max_hash_expand()
*
* Controls how many Hash objects are displayed when displaying nested Hash objects.
* Makes DohSetMaxHashExpand an externally callable function (for debugger).
* ----------------------------------------------------------------------------- */
void Swig_set_max_hash_expand(int count) {
SetMaxHashExpand(count);
}
extern "C" {
/* -----------------------------------------------------------------------------
* Swig_get_max_hash_expand()
*
* Returns how many Hash objects are displayed when displaying nested Hash objects.
* Makes DohGetMaxHashExpand an externally callable function (for debugger).
* ----------------------------------------------------------------------------- */
int Swig_get_max_hash_expand() {
return GetMaxHashExpand();
}
/* -----------------------------------------------------------------------------
* Swig_to_doh_string()
*
* DOH version of Swig_to_string()
* ----------------------------------------------------------------------------- */
static String *Swig_to_doh_string(DOH *object, int count) {
int old_count = Swig_get_max_hash_expand();
if (count >= 0)
Swig_set_max_hash_expand(count);
String *debug_string = object ? NewStringf("%s", object) : NewString("NULL");
Swig_set_max_hash_expand(old_count);
return debug_string;
}
/* -----------------------------------------------------------------------------
* Swig_to_doh_string_with_location()
*
* DOH version of Swig_to_string_with_location()
* ----------------------------------------------------------------------------- */
static String *Swig_to_doh_string_with_location(DOH *object, int count) {
int old_count = Swig_get_max_hash_expand();
if (count >= 0)
Swig_set_max_hash_expand(count);
String *debug_string = Swig_stringify_with_location(object);
Swig_set_max_hash_expand(old_count);
return debug_string;
}
/* -----------------------------------------------------------------------------
* Swig_to_string()
*
* Swig debug - return C string representation of any DOH type.
* Nested Hash types expand count is value of Swig_get_max_hash_expand when count<0
* Note: leaks memory.
* ----------------------------------------------------------------------------- */
const char *Swig_to_string(DOH *object, int count) {
return Char(Swig_to_doh_string(object, count));
}
/* -----------------------------------------------------------------------------
* Swig_to_string_with_location()
*
* Swig debug - return C string representation of any DOH type, within [] brackets
* for Hash and List types, prefixed by line and file information.
* Nested Hash types expand count is value of Swig_get_max_hash_expand when count<0
* Note: leaks memory.
* ----------------------------------------------------------------------------- */
const char *Swig_to_string_with_location(DOH *object, int count) {
return Char(Swig_to_doh_string_with_location(object, count));
}
/* -----------------------------------------------------------------------------
* Swig_print()
*
* Swig debug - display string representation of any DOH type.
* Nested Hash types expand count is value of Swig_get_max_hash_expand when count<0
* ----------------------------------------------------------------------------- */
void Swig_print(DOH *object, int count) {
String *output = Swig_to_doh_string(object, count);
Printf(stdout, "%s\n", output);
Delete(output);
}
/* -----------------------------------------------------------------------------
* Swig_to_string_with_location()
*
* Swig debug - display string representation of any DOH type, within [] brackets
* for Hash and List types, prefixed by line and file information.
* Nested Hash types expand count is value of Swig_get_max_hash_expand when count<0
* ----------------------------------------------------------------------------- */
void Swig_print_with_location(DOH *object, int count) {
String *output = Swig_to_doh_string_with_location(object, count);
Printf(stdout, "%s\n", output);
Delete(output);
}
} // extern "C"

35
Source/Swig/error.c
View file

@ -284,6 +284,41 @@ static String *format_filename(const_String_or_char_ptr filename) {
return formatted_filename;
}
/* -----------------------------------------------------------------------------
* Swig_stringify_with_location()
*
* Return a string representation of any DOH object with line and file location
* information in the appropriate error message format. The string representation
* is enclosed within [] brackets after the line and file information.
* ----------------------------------------------------------------------------- */
String *Swig_stringify_with_location(DOH *object) {
String *str = NewStringEmpty();
if (!init_fmt)
Swig_error_msg_format(DEFAULT_ERROR_MSG_FORMAT);
if (object) {
int line = Getline(object);
String *formatted_filename = format_filename(Getfile(object));
if (line > 0) {
Printf(str, diag_line_fmt, formatted_filename, line);
} else {
Printf(str, diag_eof_fmt, formatted_filename);
}
if (Len(object) == 0) {
Printf(str, "[EMPTY]");
} else {
Printf(str, "[%s]", object);
}
Delete(formatted_filename);
} else {
Printf(str, "[NULL]");
}
return str;
}
/* -----------------------------------------------------------------------------
* Swig_diagnostic()
*

1
Source/Swig/misc.c
View file

@ -527,7 +527,6 @@ String *Swig_string_schemify(String *s) {
return ns;
}
/* -----------------------------------------------------------------------------
* Swig_string_typecode()
*

4
Source/Swig/swig.h
View file

@ -319,7 +319,6 @@ extern int ParmList_is_compactdefargs(ParmList *p);
extern String *Swig_string_lower(String *s);
extern String *Swig_string_upper(String *s);
extern String *Swig_string_title(String *s);
extern void Swig_init(void);
extern int Swig_value_wrapper_mode(int mode);
@ -334,6 +333,7 @@ extern int ParmList_is_compactdefargs(ParmList *p);
extern int Swig_warn_count(void);
extern void Swig_error_msg_format(ErrorMessageFormat format);
extern void Swig_diagnostic(const_String_or_char_ptr filename, int line, const char *fmt, ...);
extern String *Swig_stringify_with_location(DOH *object);
/* --- C Wrappers --- */
extern String *Swig_cparm_name(Parm *p, int i);
@ -408,6 +408,8 @@ extern int ParmList_is_compactdefargs(ParmList *p);
extern void Wrapper_director_protected_mode_set(int);
extern void Wrapper_all_protected_mode_set(int);
extern void Language_replace_special_variables(String *method, String *tm, Parm *parm);
extern void Swig_print(DOH *object, int count);
extern void Swig_print_with_location(DOH *object, int count);
/* -- template init -- */

41
Tools/swig.gdb Normal file
View file

@ -0,0 +1,41 @@
# User-defined commands for easier debugging of SWIG in gdb
#
# This file can be "included" into your main .gdbinit file using:
# source swig.gdb
# or otherwise paste the contents into .gdbinit
#
# Note all user defined commands can be seen using:
# (gdb) show user
# The documentation for each command can be easily viewed, for example:
# (gdb) help swigprint
define swigprint
if ($argc == 2)
set $expand_count = $arg1
else
set $expand_count = -1
end
call Swig_print($arg0, $expand_count)
end
document swigprint
Displays any SWIG DOH object
Usage: swigprint swigobject [hashexpandcount]
swigobject - The object to display.
hashexpandcount - Number of nested Hash types to expand (default is 1). See Swig_set_max_hash_expand() to change default.
end
define locswigprint
if ($argc == 2)
set $expand_count = $arg1
else
set $expand_count = -1
end
call Swig_print_with_location($arg0, $expand_count)
end
document locswigprint
Displays any SWIG DOH object prefixed with file and line location
Usage: locswigprint swigobject [hashexpandcount]
swigobject - The object to display.
hashexpandcount - Number of nested Hash types to expand (default is 1). See Swig_set_max_hash_expand() to change default.
end