DEBUG

## Name

debug — Allows the user to set or check the flags used by BRL-CAD libraries to enable low level debugging outputs.

## Synopsis

`debug` [-h] [-l [`lib`]] [-C [`lib`]] [-V [`val`]] [lib [`flag`]]

## DESCRIPTION

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.

## FLAG REPORTING AND MANIPULATION

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.

## EXAMPLES

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

Example 7. Clear all active debug flags for all libraries

`mged>` `debug -C`

## AUTHOR

BRL-CAD Team

## BUG REPORTS

Reports of bugs or problems should be submitted via electronic mail to `<devs@brlcad.org>`