DEBUG(nged)

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

COPYRIGHT

This software is Copyright (c) 1989-2021 by the United States Government as represented by U.S. Army Research Laboratory.

BUG REPORTS

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