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