 |
Open CASCADE Technology
7.8.0
|
|
|
Open CASCADE Technology
7.8.0
|
|
This manual describes facilities included in OCCT to support debugging, and provides some hints for more efficient debug.
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.
To enable this macro on Windows when building with Visual Studio projects, edit file custom.bat and add the line:
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.
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().
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.
Note that this feature does not applicable for UWP build.
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.
Note that all these functions accept pointer to variable as void* 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.
Open CASCADE Test Harness or 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.
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).
Evaluates a DRAW command or script. A command is passed as a string parameter.
Sets the specified shape as a value of DRAW interpreter variable with the given name.
Makes a compound from the specified list of shapes and sets it as a value of DRAW interpreter variable with the given name.
Sets the specified geometric object as a value of DRAW interpreter variable with the given name.
All these functions are defined in TKDraw toolkit and return a string indicating the result of execution.
The following functions are provided by TKBRep toolkit and can be used from debugger prompt:
Saves the specified shape to a file with the given name.
Dumps shape or its location to cout.
The following function is provided by TKMesh toolkit:
Stores mesh produced in parametric space to BREP file.
The following functions are provided by TKTopTest toolkit:
Sets the edges or triangles from mesh data structure of type Handle(BRepMesh_FaceAttribute) as DRAW interpreter variables, assigning a unique name in the form "<theNameStr>_<index>" to each object.
The following additional function is provided by TKGeomBase toolkit:
Dump geometric object to cout.
Many OCCT classes may dump the current state into the stream. This stream contains the information about the class field into the field value/s. It is possible to prepare recursive dump using corresponded macro for class fields. The depth of this recursion is defined by parameter of the dump. The object defines What parameters should be presented in the Dump. The usual way is to dump all object fields.
Steps to prepare dump of the object into json:
The following macro are defined to cover the object parameters into json format:
| Name | Result in json |
|---|---|
| OCCT_DUMP_FIELD_VALUE_NUMERICAL | "field": value |
| OCCT_DUMP_FIELD_VALUE_STRING | "field": "value" |
| OCCT_DUMP_FIELD_VALUE_POINTER | "field": "pointer address" |
| OCCT_DUMP_FIELD_VALUES_DUMPED | "field": { result of field->DumpJson(...) } |
| OCCT_DUMP_FIELD_VALUES_NUMERICAL | "field": [value_1, ..., value_n] |
| OCCT_DUMP_FIELD_VALUES_STRING | "field": ["value_1", ..., "value_n"] |
| OCCT_DUMP_BASE_CLASS | "kind": { result of kind::DumpJson(...) } |
In DRAW, key '-dumpJson' is used to dump an object. It is implemented in 'vaspect' and 'boundingbox' commands.
Json output for Bnd_OBB (using command 'bounding v -obb -dumpJson'):
Visual Studio debugger provides the Command Window (can be activated from menu View / Other Windows / Command Window), which can be used to evaluate variables and expressions interactively in a debug session (see https://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.
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.
For example, assume that you are debugging a function, where local variable TopoDS_Edge anEdge1 is of interest. 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:
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):
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!):
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.
Visual Studio provides a way to customize display of variables of different types in debugger windows (Watch, Autos, Locals, etc.).
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.
In Visual Studio 2012 and later, visualizers can be put in a separate file in subdirectory Visualizers. See file occt.natvis for example.
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 OSD package can be used: low-level C functions and macros defined in 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 a performance counter to a function of interest allows to get statistics on the number of calls and the total execution time of the function.
Note that this instrumentation is intended to be removed when the 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 print all performance statistics.
Note that performance counters are not thread-safe.
GCC and Clang compilers provide options for instrumenting the code with the tools intended for detection of run-time errors, called sanitizers. This section provides some hints for using sanitizers for detecting possible errors in OCCT code.
Example of configuration steps for Ubuntu:
Build as usual (make)
Be prepared that it works much slower than normal build and consumes more disk space.
Before running executable, make sure that "llvm-symbolizer" is in PATH; this is necessary to get human-readable stack traces. The tool must have exactly that name.
If it is installed in common folder (/usr/bin or similar) with different name, one option is to create a symlink, for instance:
sudo ln -s /usr/bin/llvm-symbolizer-6.0 /usr/bin/llvm-symbolizer
Alternatively, add directory where actual llvm-symbolizer is located (such as /usr/lib/llvm-6.0/bin) to the PATH variable.
export ASAN_OPTIONS=detect_leaks=0
export CSF_CPULIMIT_FACTOR=20
export UBSAN_OPTIONS=print_stacktrace=1
./draw.sh relwithdeb
Note that when running tests under sanitizers, behavior may be different. Known problems (as of CLang 6.0) are:
Though CLang toolset is available in Visual Studio 2015 and newer, sanitizer do not seem to be available out of the box (last tested with VS 2019 16.2.3).
1.8.18