dox/dev_guides/debug/debug.md

   1 Debugging tools and hints {#dev_guides__debug}
   2 =========================
   3
   4 @tableofcontents
   5
   6 @section occt_debug_intro Introduction
   7
   8 This manual describes facilities included in OCCT to support debugging, and provides some hints for more efficient debug.
   9
  10 @section occt_debug_bop Self-diagnostics in Boolean operations algorithm
  11
  12 In real-world applications modeling operations are often performed in a long sequence, while the user sees only the final result of the whole sequence. If the final result is wrong, the first debug step is to identify the offending operation to be debugged further. Boolean operation algorithm in OCCT provides a self-diagnostic feature which can help to do that step.
  13
  14 This feature can be activated by defining environment variable *CSF_DEBUG_BOP*, which should specify an existing writeable directory.
  15
  16 The diagnostic code checks validity of the input arguments and the result of each Boolean operation. When an invalid situation is detected, the report consisting of argument shapes and a DRAW script to reproduce the problematic operation is saved to the directory pointed by *CSF_DEBUG_BOP*.
  17
  18 @section occt_debug_exceptions Calling JIT debugger on exception
  19
  20 On Windows platform when using Visual Studio compiler there is a possibility to start the debugger automatically if an exception is caught in a program running OCCT. For this, set environment variable *CSF_DEBUG* to any value. Note that this feature works only if you enable OCCT exception handler in your application by calling *OSD::SetSignal()*.
  21
  22 @section occt_debug_call Functions for calling from debugger
  23
  24 Modern interactive debuggers provide the possibility to execute application code at a program break point. This feature can be used to analyse the temporary objects available only in the context of the debugged code. OCCT provides several global functions that can be used in this way.
  25
  26 Note that all these functions accept pointer to variable as <i>void*</i> to allow calling the function even when debugger does not recognize type equivalence or can not perform necessary type cast automatically. It is responsibility of the developer to provide the correct pointer. In general these functions are not guaranteed to work, thus use them with caution and at your own risk.
  27
  28 @subsection occt_debug_call_draw Interacting with DRAW
  29
  30 Open CASCADE Test Harness or @ref user_guides__test_harness "DRAW" provides an extensive set of tools for inspection and analysis of OCCT shapes and geometric objects and is mostly used as environment for prototyping and debugging OCCT-based algorithms.
  31
  32 In some cases the objects to be inspected are available in DRAW as results of DRAW commands. In other cases, however, it is necessary to inspect intermediate objects created by the debugged algorithm. To support this, DRAW provides a set of commands allowing the developer to store intermediate objects directly from the debugger stopped at some point during the program execution (usually at a breakpoint).
  33
  34 ~~~~~
  35 const char* Draw_Eval (const char *theCommandStr)
  36 ~~~~~
  37
  38 Evaluates a DRAW command or script.
  39 A command is passed as a string parameter.
  40
  41 ~~~~~
  42 const char* DBRep_Set (const char* theNameStr, void* theShapePtr)
  43 ~~~~~
  44
  45 Sets the specified shape as a value of DRAW interpreter variable with the given name.
  46 - *theNameStr* – the DRAW interpreter variable name to set.
  47 - *theShapePtr* – a pointer to *TopoDS_Shape* variable.
  48
  49 ~~~~~
  50 const char* DrawTrSurf_Set (const char* theNameStr, void* theHandlePtr)
  51 const char* DrawTrSurf_SetPnt (const char* theNameStr, void* thePntPtr)
  52 const char* DrawTrSurf_SetPnt2d (const char* theNameStr, void* thePnt2dPtr)
  53 ~~~~~
  54
  55 Sets the specified geometric object as a value of DRAW interpreter variable with the given name.
  56 - *theNameStr* – the DRAW interpreter variable name to set.
  57 - *theHandlePtr* – a pointer to the geometric variable (Handle to *Geom_Geometry* or *Geom2d_Curve* or descendant) to be set.
  58 - *thePntPtr* – a pointer to the variable of type *gp_Pnt* to be set.
  59 - *thePnt2dPtr* – a pointer to the variable of type *gp_Pnt2d* to be set.
  60
  61 All these functions are defined in *TKDraw* toolkit and return a string indicating the result of execution.
  62
  63 @subsection occt_debug_call_brep Saving and dumping shapes and geometric objects
  64
  65 The following functions are provided by *TKBRep* toolkit and can be used from debugger prompt:
  66
  67 ~~~~~
  68 const char* BRepTools_Write (const char* theFileNameStr, void* theShapePtr)
  69 ~~~~~
  70
  71 Saves the specified shape to a file with the given name.
  72 - *theFileNameStr* – the DRAW interpreter variable name to set.
  73 - *theShapePtr* – a pointer to *TopoDS_Shape* variable.
  74
  75 ~~~~~
  76 const char* BRepTools_Dump (void* theShapePtr)
  77 const char* BRepTools_DumpLoc (void* theShapePtr)
  78 ~~~~~
  79
  80 Dumps shape or its location to cout.
  81 - *theShapePtr* – a pointer to *TopoDS_Shape* variable.
  82
  83 The following additional function is provided by *TKGeomBase* toolkit:
  84
  85 ~~~~~
  86 const char* GeomTools_Dump (void* theHandlePtr)
  87 ~~~~~
  88
  89 Dump geometric object to cout.
  90 - *theHandlePtr* – a pointer to the geometric variable (<i>Handle</i> to *Geom_Geometry* or *Geom2d_Curve* or descendant) to be set.
  91
  92 @section occt_debug_vstudio Using Visual Studio debugger
  93
  94 @subsection occt_debug_vstudio_command Command window
  95
  96 Visual Studio debugger provides the Command Window (can be activated from menu <b>View / Other Windows / Command Window</b>), which can be used to evaluate variables and expressions interactively in a debug session (see http://msdn.microsoft.com/en-us/library/c785s0kz.aspx). Note that the Immediate Window can also be used but it has some limitations, e.g. does not support aliases.
  97
  98 When the execution is interrupted by a breakpoint, you can use this window to call the above described functions in context of the currently debugged function. Note that in most cases you will need to specify explicitly context of the function by indicating the name of the DLL where it is defined.
  99
 100 For example, assume that you are debugging a function, where local variable *TopoDS_Edge* *anEdge1* is of interest.
 101 The following set of commands in the Command window will save this edge to file *edge1.brep*, then put it to DRAW variable *e1* and show it maximized in the axonometric DRAW view:
 102
 103 ~~~~~
 104 >? ({,,TKBRep.dll}BRepTools_Write)("d:/edge1.brep",(void*)&anEdge1)
 105 0x04a2f234 "d:/edge1.brep"
 106 >? ({,,TKDraw.dll}DBRep_Set)("e1",(void*)&anEdge1)
 107 0x0369eba8 "e1"
 108 >? ({,,TKDraw.dll}Draw_Eval)("donly e1; axo; fit")
 109 0x029a48f0 ""
 110 ~~~~~
 111
 112 For convenience it is possible to define aliases to commands in this window, for instance (here ">" is prompt provided by the command window; in the Immediate window this symbol should be entered manually):
 113
 114 ~~~~~
 115 >alias deval      ? ({,,TKDraw}Draw_Eval)
 116 >alias dsetshape  ? ({,,TKDraw}DBRep_Set)
 117 >alias dsetgeom   ? ({,,TKDraw}DrawTrSurf_SetPnt)
 118 >alias dsetpnt2d  ? ({,,TKDraw}DrawTrSurf_SetPnt2d)
 119 >alias saveshape  ? ({,,TKBRep}BRepTools_Write)
 120 >alias dumpshape  ? ({,,TKBRep}BRepTools_Dump)
 121 >alias dumploc    ? ({,,TKBRep}BRepTools_DumpLoc)
 122 >alias dumpgeom   ? ({,,TKGeomBase}GeomTools_Dump)
 123 ~~~~~
 124
 125 Note that aliases are stored in the Visual Studio user's preferences and it is sufficient to define them once on a workstation. With these aliases, the above example can be reproduced easier (note the space symbol after alias name!):
 126
 127 ~~~~~
 128 >saveshape ("d:/edge1.brep",(void*)&anEdge1)
 129 0x04a2f234 "d:/edge1.brep"
 130 >dsetshape ("e1",(void*)&anEdge1)
 131 0x0369eba8 "e1"
 132 >deval ("donly e1; axo; fit")
 133 0x029a48f0 ""
 134 ~~~~~
 135
 136 Note that there is no guarantee that the call will succeed and will not affect the program execution, thus use this feature at your own risk. In particular, the commands interacting with window system (such as *axo*, *vinit*, etc.) are known to cause application crash when the program is built in 64-bit mode. To avoid this, it is recommended to prepare all necessary view windows in advance, and arrange these windows to avoid overlapping with the Visual Studio window, to ensure that they are visible during debug.
 137
 138 @subsection occt_debug_vstudio_watch Customized display of variables content
 139
 140 Visual Studio provides a way to customize display of variables of different types in debugger windows (Watch, Autos, Locals, etc.).
 141
 142 In Visual Studio 2005-2010 the rules for this display are defined in file *autoexp.dat* located in  subfolder *Common7\\Packages\\Debugger* of the Visual Studio installation folder (hint: the path to that folder is given in the corresponding environment variable, e.g. *VS100COMNTOOLS* for vc10). This file contains two sections: *AutoExpand* and *Visualizer*. The following rules can be added to these sections to provide more convenient display of some OCCT data types.
 143
 144 ### \[AutoExpand\] section
 145
 146 ~~~~~
 147 ; Open CASCADE classes
 148 Standard_Transient=<,t> count=<count,d>
 149 Handle_Standard_Transient=<entity,x> count=<entity->count,d> <,t>
 150 TCollection_AsciiString=<mylength,d> <mystring,s>
 151 TCollection_HAsciiString=<myString.mylength,d> <myString.mystring,s>
 152 TCollection_ExtendedString=<mylength,d> <mystring,su>
 153 TCollection_HExtendedString=<myString.mylength,d> <myString.mystring,su>
 154 TCollection_BaseSequence=size=<Size,d> curr=<CurrentIndex,d>
 155 TCollection_BasicMap=size=<mySize,d>
 156 NCollection_BaseSequence=size=<mySize,d> curr=<myCurrentIndex,d>
 157 NCollection_BaseList=length=<myLength,d>
 158 NCollection_BaseMap=size=<mySize,d> buckets=<myNbBuckets>
 159 NCollection_BaseVector=length=<myLength,d>
 160 TDF_Label=<myLabelNode,x> tag=<myLabelNode->myTag>
 161 TDF_LabelNode=tag=<myTag,d>
 162 TDocStd_Document=format=<myStorageFormat.mystring,su> count=<count,d> <,t>
 163 TopoDS_Shape=<myTShape.entity,x> <myOrient>
 164 gp_XYZ=<x,g>, <y,g>, <z,g>
 165 gp_Pnt=<coord.x,g>, <coord.y,g>, <coord.z,g>
 166 gp_Vec=<coord.x,g>, <coord.y,g>, <coord.z,g>
 167 gp_Dir=<coord.x,g>, <coord.y,g>, <coord.z,g>
 168 gp_XY=<x,g>, <y,g>
 169 gp_Pnt2d=<coord.x,g>, <coord.y,g>
 170 gp_Dir2d=<coord.x,g>, <coord.y,g>
 171 gp_Vec2d=<coord.x,g>, <coord.y,g>
 172 gp_Mat2d={<matrix[0][0],g>,<matrix[0][1],g>}, {<matrix[1][0],g>,<matrix[1][1],g>}
 173 gp_Ax1=loc={<loc.coord.x,g>, <loc.coord.y,g>, <loc.coord.z,g>} vdir={<vdir.coord.x,g>, <vdir.coord.y,g>, <vdir.coord.z,g>}
 174 ~~~~~
 175
 176 ### \[Visualizer\] section
 177
 178 ~~~~~
 179 ; Open CASCADE classes
 180
 181 NCollection_Handle<*> {
 182   preview ( *((($T0::Ptr*)$e.entity)->myPtr) )
 183   children ( (($T0::Ptr*)$e.entity)->myPtr )
 184 }
 185
 186 NCollection_List<*> {
 187   preview ( #( "NCollection_List [", $e.myLength, "]" ) )
 188   children ( #list( head: $c.myFirst, next: myNext ) : #(*($T1*)(&$e+1)) )
 189 }
 190
 191 NCollection_Array1<*> {
 192   preview ( #( "NCollection_Array1 [", $e.myLowerBound, "..", $e.myUpperBound, "]" ) )
 193   children ( #array( expr: $c.myData[$i], size: 1+$c.myUpperBound ) )
 194 }
 195
 196 math_Vector {
 197   preview ( #( "math_Vector [", $e.LowerIndex, "..", $e.UpperIndex, "]" ) )
 198   children ( #array ( expr: ((double*)($c.Array.Addr))[$i], size: 1+$c.UpperIndex ) )
 199 }
 200
 201 TColStd_Array1OfReal {
 202   preview ( #( "Array1OfReal [", $e.myLowerBound, "..", $e.myUpperBound, "]" ) )
 203   children ( #array ( expr: ((double*)($c.myStart))[$i], size: 1+$c.myUpperBound ) )
 204 }
 205
 206 Handle_TColStd_HArray1OfReal {
 207   preview ( #( "HArray1OfReal [",
 208                ((TColStd_HArray1OfReal*)$e.entity)->myArray.myLowerBound, "..",
 209                ((TColStd_HArray1OfReal*)$e.entity)->myArray.myUpperBound, "] ",
 210                [$e.entity,x], " count=", $e.entity->count ) )
 211   children ( #array ( expr: ((double*)(((TColStd_HArray1OfReal*)$e.entity)->myArray.myStart))[$i],
 212                       size: 1+((TColStd_HArray1OfReal*)$e.entity)->myArray.myUpperBound ) )
 213 }
 214
 215 TColStd_Array1OfInteger {
 216   preview ( #( "Array1OfInteger [", $e.myLowerBound, "..", $e.myUpperBound, "]" ) )
 217   children ( #array ( expr: ((int*)($c.myStart))[$i], size: 1+$c.myUpperBound ) )
 218 }
 219
 220 Handle_TColStd_HArray1OfInteger {
 221   preview ( #( "HArray1OfInteger [",
 222                ((TColStd_HArray1OfInteger*)$e.entity)->myArray.myLowerBound, "..",
 223                ((TColStd_HArray1OfInteger*)$e.entity)->myArray.myUpperBound, "] ",
 224                [$e.entity,x], " count=", $e.entity->count ) )
 225   children ( #array ( expr: ((int*)(((TColStd_HArray1OfInteger*)$e.entity)->myArray.myStart))[$i],
 226                       size: 1+((TColStd_HArray1OfInteger*)$e.entity)->myArray.myUpperBound ) )
 227 }
 228
 229 Handle_TCollection_HExtendedString {
 230   preview ( #( "HExtendedString ", [$e.entity,x], " count=", $e.entity->count,
 231                " ", ((TCollection_HExtendedString*)$e.entity)->myString ) )
 232   children ( #([actual members]: [$e,!] ) )
 233 }
 234
 235 Handle_TCollection_HAsciiString {
 236   preview ( #( "HAsciiString ", [$e.entity,x], " count=", $e.entity->count,
 237                " ", ((TCollection_HAsciiString*)$e.entity)->myString ) )
 238   children ( #([actual members]: [$e,!],
 239              #array( expr: ((TCollection_HAsciiString*)$e.entity)->myString.mystring[$i],
 240                      size: ((TCollection_HAsciiString*)$e.entity)->myString.mylength) ) )
 241 }
 242 ~~~~~
 243
 244 In Visual Studio 2012 and later, visualizers can be put in a separate file in subdirectory *Visualizers*. See file *occt.natvis* for example.