Debugging
From DocR23
This article describes general ACIS application debugging techniques.
Contents |
ENTITY Class Debug Method
The ENTITY class (and each class derived from it) contains a method called debug_ent that is called to dump the instance's data for debugging. The method ENTITY::debug_ent is implemented as:
void ENTITY::debug_ent(FILE * fp) const { // Start with this entity's identifier debug_header( this, fp ); // Now the entity data. if (fp != NULL && debug_rollback.on()) { debug_title( "Rollback pointer", fp ); debug_pointer( data_container.rollback(), fp ); debug_newline( fp ); } debug_new_pointer( "Attribute list", attrib(), fp ); if (has_pattern_holder()) debug_int( "Pattern index", pattern_index(), fp ); else if (has_former_pattern_holder()) debug_int( "Old pattern idx", pattern_index(), fp ); // Put out anything from the unknown text. text_ptr->debug_ent( fp ); }
The functions most commonly used by the debug_ent methods to print out various types of data are listed below. The debug_ent methods are implemented using the entity derivation macros or attribute derivation macros when defining an ENTITY or ATTRIB. The implementation of debug_ent for classes derived from ENTITY first calls the debug_ent method for its parent class (the class from which it was derived) before printing the information specific to the derived class. Therefore, each class needs only to print the information that is specific to the class.
- debug_new_pointer
- Prints a pointer that has not been previously printed. By default, prints this as a relative address. The debug_absolute_addresses option can be used to specify the format of the pointer.
- debug_old_pointer
- Prints a pointer that has been previously printed. By default, prints this as a relative address. The debug_absolute_addresses option can be used to specify the format of the pointer.
- debug_sib_pointer
- Prints a pointer of a sibling. By default, prints this as a relative address. The debug_absolute_addresses option can be used to specify the format of the pointer.
- debug_int
- Prints an integer.
- debug_real
- Prints a real number with appropriate precision.
- debug_string
- Prints a string.
- debug_dist
- Prints a real representing a signed distance. It is considered to be zero if its magnitude is less than SPAresabs.
- debug_newline
- Prints a new line character.
- debug_norm
- Prints a real representing a normalized, dimensionless quantity. It is considered to be zero if its magnitude is less than SPAresnor.
An ENTITY, its sub-ENTITYs, and all ENTITYs pointed to by these ENTITYs can be debugged by calling void debug_entity(ENTITY const *this_entity, FILE *fp = debug_file_ptr). This function is frequently used to dump all of the ENTITYs in a BODY into a debug file, but it can be used with any type of ENTITY. The usage of debug_entity and the format of the output data for various types of ENTITYs is presented in Debug File.
debug_file_ptr
The global variable debug_file_ptr defines the output file used for debugging. This is the default output stream for debug_entity, all of the output statements supporting ACIS Debug Modules, and most other debugging-related functions. By default, debug_file_ptr is initialized to stdout.
Run-Time Debugging
Many software environments provide interactive run-time debuggers that allow you to perform tasks such as stop execution of the program, examine variables, and call functions. For example, in the LINUX environment, a common debugger is called gdb.
Several functions have been defined to aid debugging with such a debugger. These functions are not linked into the system by default, because they are not called by any ACIS functions. To access these functions, you must force the linkage of the file SPAkern/kernel_sg_husk_debug.m/src/sg_debug.cpp. Some of these functions are listed below.
- dbuvec
- Debug a SPAunit_vector
- dbvec
- Debug a SPAvector
- dbpos
- Debug a SPAposition
- dbtransf
- Debug a SPAtransf
- dbcurve
- Debug a curve
- dbpcurve
- Debug a pcurve
- dbsurface
- Debug a surface
- dbbs2_curve
- Debug a bs2_curve
- dbbs3_curve
- Debug a bs3_curve
- dbbs3_surface
- Debug a bs3_surface
- dbedge
- Print info about an EDGE
- dbcoedge
- Print info about a COEDGE
- dbbs2c
- Print info about a bs2_curve
- dbbs3c
- Print info about a bs3_curve
- bs2_curve_step_eval
- Evaluate a bs2_curve at increments
- bs3_curve_step_eval
- Evaluate a bs3_curve at increments
- dblaw
- Debug a law
- dbent
- Debug an ENTITY
- dbentall
- Debug this ENTITY and its siblings and children
- dbentallsz
- Get the size for this ENTITY and its siblings and children
- dbentkids
- Debug this ENTITY and its children
- dbsave
- Save an ENTITY to dbfile
- dblist
- Debug an ENTITY_LIST
- dblistent
- Debug an ENTITY_LIST
- dbdbg
- Turn on debugging module
- dbopti
- Set option to integer
- dboptd
- Set option to double
- dboptc
- Set option to string
- dbhelp
- Print out a list of run-time debug functions
Functions Used for Output Streams
The following output streams are used by these functions:
- dbfile
- Debug output stream stream
- dbout
- stdout output stream
- dberr
- stderr output stream
Scheme Debugging Extensions
Two Scheme extensions are provided to control ENTITY debugging.
- entity:debug
- Prints information about an ENTITY and (optionally) connected ENTITYs.
- debug:file
- Sets the debug output device.
Three Scheme extensions facilitate debugging using ACIS Debug Modules and the DEBUG_LEVEL macro. These include:
- debug:all-modules
- Sets the debug level for all modules.
- debug:list-modules
- Displays the current debug level for all modules.
- debug:module
- Sets the debugging level for a particular module.
Error and Warning Messages
It is valuable for applications to produce error or warning messages when something goes wrong during an operation. The following C++ functions can be called by applications to find and print ACIS error messages if an error occurs. These and other error handling functions are described in Error Handling.
- find_err_entry
- find_err_ident
- find_err_mess
- find_err_module
- print_warnerr_mess
- get_warnings
- init_warnings
