debug — Allows the user to set or check the flags used by BRL-CAD libraries to enable low level debugging outputs.
Supports listing, setting and checking the debug flags defined by BRL-CAD libraries. The outputs controlled by this command are extremely low level, most likely cryptic to those not familiar with the internal of BRL-CAD's implementation, and may cause any variety of odd or unexpected behaviors. Generally speaking, they are present to avoid having to recompile the code to obtain more verbose information printing during a debugging setssion, and are intended only for that use case. In short, they are development only, not intended for general user consumption and should be avoided unless you know exactly what you are doing.
The -h help option will print out a list of libraries supported by the
debug command.
The -l option will print out a list of debugging flags supported by the
debug command. With no argument to -l all flags for all libraries are
listed - supplying a library name (per output from the -h option) to -l
will list only the flags specific to that library.
Note that this list and the flags defined within specific libraries may change at any time - debugging flags are not considered public API and should never be relied upon for any user-facing functionality.
With no arguments, the debug command displays all currently set debug flags for all libraries. If no debug flags are set (the default) the return will be empty.
If a library name is added as an argument, (for example, "debug bu") the debug command displays only the currently set debug flags for that specific library. Again if no debug flags are set (the default) the return will be empty.
To toggle a particular flag, the user supplies the library name and the flag to the debug command - for example, "debug bu AVS" will toggle the state of the attribute-value debugging flag in libbu. If the flag was previously set this command will unset it, and if unset will set it. The previously discussed debug command modes allow the user to determine the current state of a flag.
If a user wishes to simply clear all active flags, they can use the -C option to
debug to accomplishe this. If an optional library name is supplied only the
flags speific to that library will be cleared - otherwise, all flags will be cleared globally for
all libraries.
Although it shouldn't normally be necessary, the -V option provides a way to report
and manipulate the low level hexadecimal numerical values controlling the flag behaviors. Without
additional arguments, -V will report the hex values for all libraries. With a library
name supplied, it will report the value for that library. If a library name and a string defining a
positive hexidecimal number are supplied, the debugging flag will be directly assigned that numerical
value.
Example 1. Display help and available libraries
mged>debug -h
debug [-h] [-l [lib]] [-C [lib]] [-V [lib] [val]] [lib [flag]]
Available libs:
BU
NMG
OPTICAL
RT
Example 2. List available flags for LIBBU
mged>debug -l BU
BU flags:
COREDUMP (0x00000001): bu_bomb() should dump core on exit
PARALLEL (0x00000010): Parallel debug logging
BACKTRACE (0x00000040): Log backtrace details during abnormal exit
ATTACH (0x00000080): Waits for a debugger to attach during a crash
MATH (0x00000100): Fundamental math routines (plane.c, mat.c)
PTBL (0x00000200): bu_ptbl_() logging
AVS (0x00000400): bu_avs_() logging
MAPPED_FILE (0x00000800): bu_mapped_file logging
PATHS (0x00001000): File and path debug logging
TABDATA (0x00010000): LIBBN: tabdata
Example 3. Set LIBBU flags for bu_avs and path debugging
mged>debug BU AVS
AVS (0x00000400): bu_avs_() loggin
mged>debug BU PATHS
AVS (0x00000400): bu_avs_() logging
PATHS (0x00001000): File and path debug logging
Example 4. Set LIBRT flag for rt_shootray processing
mged>debug RT SHOOT
SHOOT (0x00000004): 3 Info about rt_shootray() processing
Example 5. List LIBBU's active debugging flags and all active debugging flags
mged>debug BU
AVS (0x00000400): bu_avs_() logging
PATHS (0x00001000): File and path debug logging
mged>debug
BU flags:
AVS (0x00000400): bu_avs_() logging
PATHS (0x00001000): File and path debug logging
RT flags:
SHOOT (0x00000004): 3 Info about rt_shootray() processing
Example 6. Clear LIBRT debug flags
mged>debug -C RT
mged>debug
BU flags:
AVS (0x00000400): bu_avs_() logging
PATHS (0x00001000): File and path debug logging
Reports of bugs or problems should be submitted via electronic
mail to <devs@brlcad.org>