This manual describes facilities included in OCCT to support debugging, and provides some hints for more efficient debug.
-@section occt_debug_bop Self-diagnostics in Boolean operations algorithm
+@section occt_debug_macro Compiler macro to enable extended debug messages
-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.
+Many OCCT algorithms can produce extended debug messages, usually printed to cout.
+These include messages on internal errors and special cases encountered, timing etc.
+In OCCT versions prior to 6.8.0 most of these messages were activated by compiler macro *DEB*, enabled by default in debug builds.
+Since version 6.8.0 this is disabled by default but can be enabled by defining compiler macro *OCCT_DEBUG*.
-This feature can be activated by defining environment variable *CSF_DEBUG_BOP*, which should specify an existing writeable directory.
+To enable this macro on Windows when building with Visual Studio projects, edit file custom.bat and add the line:
-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*.
+ set CSF_DEFINES=OCCT_DEBUG
+
+Some algorithms use specific macros for yet more verbose messages, usually started with OCCT_DEBUG_.
+These messages can be enabled in the same way, by defining corresponding macro.
+
+Note that some header files are modified when *OCCT_DEBUG* is enabled, hence binaries built with it enabled are not compatible with client code built without this option; this is not intended for production use.
@section occt_debug_exceptions Calling JIT debugger on exception
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()*.
+@section occt_debug_bop Self-diagnostics in Boolean operations algorithm
+
+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.
+
+This feature can be activated by defining environment variable *CSF_DEBUG_BOP*, which should specify an existing writeable directory.
+
+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*.
+
@section occt_debug_call Functions for calling from debugger
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.
Dumps shape or its location to cout.
- *theShapePtr* - a pointer to *TopoDS_Shape* variable.
+The following function is provided by *TKMesh* toolkit:
+
+~~~~~
+const char* BRepMesh_Dump (void* theMeshHandlePtr, const char* theFileNameStr)
+~~~~~
+
+Stores mesh produced in parametric space to BREP file.
+- *theMeshHandlePtr* - a pointer to *Handle(BRepMesh_DataStructureOfDelaun)* variable.
+- *theFileNameStr* - name of file the mesh sould be stored to.
+
The following additional function is provided by *TKGeomBase* toolkit:
~~~~~
~~~~~
>alias deval ? ({,,TKDraw}Draw_Eval)
>alias dsetshape ? ({,,TKDraw}DBRep_Set)
->alias dsetgeom ? ({,,TKDraw}DrawTrSurf_SetPnt)
+>alias dsetgeom ? ({,,TKDraw}DrawTrSurf_Set)
+>alias dsetpnt ? ({,,TKDraw}DrawTrSurf_SetPnt)
>alias dsetpnt2d ? ({,,TKDraw}DrawTrSurf_SetPnt2d)
>alias saveshape ? ({,,TKBRep}BRepTools_Write)
>alias dumpshape ? ({,,TKBRep}BRepTools_Dump)
>alias dumploc ? ({,,TKBRep}BRepTools_DumpLoc)
+>alias dumpmesh ? ({,,TKMesh}BRepMesh_Dump)
>alias dumpgeom ? ({,,TKGeomBase}GeomTools_Dump)
~~~~~
}
~~~~~
-In Visual Studio 2012 and later, visualizers can be put in a separate file in subdirectory *Visualizers*. See file *occt.natvis* for example.
\ No newline at end of file
+In Visual Studio 2012 and later, visualizers can be put in a separate file in subdirectory *Visualizers*. See file *occt.natvis* for example.
+
+@section occt_debug_perf Performance measurement tools
+
+It is recommended to use specialized performance analysis tools to profile OCCT and application code.
+However, when such tools are not available or cannot be used for some reason, tools provided by OCD package can be used: see low-level C functions and macros defined OSD_PerfMeter.h, and OSD_PerfMeter class.
+
+This tool maintains an array of 100 global performance counters that can be started and stopped independently.
+Adding performance counter to a function of interest allows to get statistics on number of calls and total execution time of the function.
+In C++ code, this can be achieved by creating local variable OSD_PerfMeter in each block of code to be measured.
+In C or Fortran code, use functions perf_start_meter and perf_stop_meter to start and stop the counter.
+Note that this instrumentation is intended to be removed when profiling is completed.
+Macros provided in OSD_PerfMeter.h can be used to keep instrumentation code permanently, but enable it only when macro PERF_ENABLE_METERS is defined.
+Each counter has its name shown when the collected statistics are printed.
+
+In DRAW, use command dperf to prints all performance statistics.
+
+Note that performance counters are not thread-safe.
projects / occt.git / blobdiff