From d1e66431613ad092aa91770f52a2a2e5dede5a23 Mon Sep 17 00:00:00 2001 From: William S Fulton Date: Wed, 15 Sep 2010 20:17:11 +0000 Subject: [PATCH] Expand the family of debug print functions for displaying DOH types. Provide gdb support for calling these. Document improved debugging experience. git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk@12221 626c5289-ae23-0410-ae9c-e8d60b6d4f22 --- CHANGES.current | 5 ++ Doc/Devel/internals.html | 164 +++++++++++++++++++++++++++++++++------ Doc/Devel/tree.html | 35 +++++++-- Source/DOH/doh.h | 4 + Source/DOH/hash.c | 53 ++++++++++--- Source/DOH/list.c | 2 +- Source/Modules/lang.cxx | 2 +- Source/Modules/swigmod.h | 9 ++- Source/Modules/utils.cxx | 113 +++++++++++++++++++++++++++ Source/Swig/error.c | 35 +++++++++ Source/Swig/misc.c | 1 - Source/Swig/swig.h | 4 +- Tools/swig.gdb | 41 ++++++++++ 13 files changed, 421 insertions(+), 47 deletions(-) create mode 100644 Tools/swig.gdb diff --git a/CHANGES.current b/CHANGES.current index 64770055f..ff5b40fb6 100644 --- a/CHANGES.current +++ b/CHANGES.current @@ -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. diff --git a/Doc/Devel/internals.html b/Doc/Devel/internals.html index 6ac3947f7..d24869d10 100644 --- a/Doc/Devel/internals.html +++ b/Doc/Devel/internals.html @@ -7,11 +7,6 @@

SWIG Internals Manual

-Thien-Thi Nguyen
- -

-David M. Beazley
-

@@ -45,6 +40,9 @@ David M. Beazley
  • 5. C/C++ Wrapper Support Functions
  • 6. Symbol Naming Guidelines for Generated C/C++ Code
  • 7. Debugging SWIG + @@ -1015,15 +1013,139 @@ In the past SWIG has generated many symbols which flout the standard especially

    7. Debugging SWIG

     -Warning. Debugging SWIG is for the very patient. + +

    +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 SWIG Parse Tree Handling 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. +

    + +

    +The SWIG distribution comes with some additional support for the gdb debugger in the Tools/swig.gdb 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 swigprint and locswigprint user-defined commands are demonstrated below. +

    + +

    +More often than not, a parse tree node needs to be examined. +The session below displays the node n in one of the Java language module wrapper functions. +The swigprint method is used to show the symbol name (symname - a DOH String type) and the node (n - a DOH Hash type). +

    +
    +
    +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, 
+}
+
    +
    + +

    +Note that all the attributes in the Hash are shown, including the 'sym:name' attribute which was assigned to the symname variable. +

    + +

    +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 swigprint to expand to two Hash levels in order to view the contents of the collapsed 'nextSibling' Hash. +

    + +
    +
    +(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, 
+}
+
    +
    + +

    +The same Hash can also be displayed with file and line location information via the locswigprint command. +

    + +
    +
    +(gdb) locswigprint 0xb7cb9408
+example.h:11: [Hash(0xb7cb9408) {
+Hash(0xb7cb9408) {
+  'name' : self, 
+  'type' : p.Shape, 
+  'self' : 1, 
+  'nextSibling' : Hash(0xb7cb9498) {...}, 
+  'hidden' : 1, 
+  'nodeType' : parm, 
+}]
+
    +
    + +

    +Tip: Commands in gdb can be shortened with whatever makes them unique and can be command completed with the tab key. +Thus swigprint can usually be shortened to sw and locswigprint to loc. +The help for each command can also be obtained within the debugging session, for example, 'help swigprint'. +

    + +

    +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.

    -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. + +

    7.1 Debugging DOH Types The Hard Way

    + +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.

    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

  • String *s;
    • -
    -(struct String *)((DohBase *)s)->data +(struct String *)((DohBase *)s)->data
    The underlying char * string can be displayed with
    -(*(struct String *)(((DohBase *)s)->data)).str +(*(struct String *)(((DohBase *)s)->data)).str

  • SwigType *t;
    • -
    -(struct String *)((DohBase *)t)->data +(struct String *)((DohBase *)t)->data
    The underlying char * string can be displayed with
    -(*(struct String *)(((DohBase *)t)->data)).str +(*(struct String *)(((DohBase *)t)->data)).str

  • const_String_or_char_ptr sc;
    • Either
    -(*(struct String *)(((DohBase *)sc)->data)).str +(*(struct String *)(((DohBase *)sc)->data)).str
    or
    -(char *)sc +(char *)sc
    will work depending on whether the underlying type is really a String * or char *. -

    -Please also read the Debugging Functions section in SWIG Parse Tree Handling for the Swig_print_node(), Swig_print_tree() and Swig_print_tags() 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. -

    -
    Copyright (C) 1999-2010 SWIG Development Team. diff --git a/Doc/Devel/tree.html b/Doc/Devel/tree.html index 43ad191f6..db3c6fee4 100644 --- a/Doc/Devel/tree.html +++ b/Doc/Devel/tree.html @@ -6,13 +6,6 @@

    SWIG Parse Tree Handling

    - -

    -David M. Beazley
    -dave-swig@dabeaz.com
    -December, 2006
    - -

    Introduction

    @@ -210,7 +203,33 @@ This function restores a node to the state it was in prior to the last Swig_

    Debugging Functions

    -The following functions are used to help debug SWIG parse trees. +

    +The following functions can be used to help debug any SWIG DOH object. +

    + +void Swig_print(DOH *object, int count = -1) + +
    +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. +
    +
    +
    + +void Swig_print_with_location(DOH *object, int count = -1) + +
    +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. +
    +
    +
    + + +

    +The following functions can be used to help debug SWIG parse trees. +

    void Swig_print_tags(Node *node, String_or_char *prefix) diff --git a/Source/DOH/doh.h b/Source/DOH/doh.h index e46d103de..6fa352547 100644 --- a/Source/DOH/doh.h +++ b/Source/DOH/doh.h @@ -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 diff --git a/Source/DOH/hash.c b/Source/DOH/hash.c index 87f8e3c40..48afd2e54 100644 --- a/Source/DOH/hash.c +++ b/Source/DOH/hash.c @@ -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; } diff --git a/Source/DOH/list.c b/Source/DOH/list.c index a08cadb5a..d5b532409 100644 --- a/Source/DOH/list.c +++ b/Source/DOH/list.c @@ -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; } diff --git a/Source/Modules/lang.cxx b/Source/Modules/lang.cxx index e28fcbb89..6ec0463fa 100644 --- a/Source/Modules/lang.cxx +++ b/Source/Modules/lang.cxx @@ -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); } } diff --git a/Source/Modules/swigmod.h b/Source/Modules/swigmod.h index b0b488d6f..d3074105f 100644 --- a/Source/Modules/swigmod.h +++ b/Source/Modules/swigmod.h @@ -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 diff --git a/Source/Modules/utils.cxx b/Source/Modules/utils.cxx index 3fe7a2709..13a504bcf 100644 --- a/Source/Modules/utils.cxx +++ b/Source/Modules/utils.cxx @@ -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" + diff --git a/Source/Swig/error.c b/Source/Swig/error.c index fa82ad8d9..5dfcf605b 100644 --- a/Source/Swig/error.c +++ b/Source/Swig/error.c @@ -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() * diff --git a/Source/Swig/misc.c b/Source/Swig/misc.c index 2105f0c51..a57c7cf33 100644 --- a/Source/Swig/misc.c +++ b/Source/Swig/misc.c @@ -527,7 +527,6 @@ String *Swig_string_schemify(String *s) { return ns; } - /* ----------------------------------------------------------------------------- * Swig_string_typecode() * diff --git a/Source/Swig/swig.h b/Source/Swig/swig.h index f90a5ffb1..021c5611f 100644 --- a/Source/Swig/swig.h +++ b/Source/Swig/swig.h @@ -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 -- */ diff --git a/Tools/swig.gdb b/Tools/swig.gdb new file mode 100644 index 000000000..195032955 --- /dev/null +++ b/Tools/swig.gdb @@ -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