'\" t
.\"     Title: DEBUG
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL-NS Stylesheets v1.76.1 <http://docbook.sf.net/>
.\"      Date: 04/13/2022
.\"    Manual: BRL-CAD User Commands
.\"    Source: BRL-CAD
.\"  Language: English
.\"
.TH "DEBUG" "nged" "04/13/2022" "BRL\-CAD" "BRL\-CAD User Commands"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
debug \- Allows the user to set or check the flags used by BRL\-CAD libraries to enable low level debugging outputs\&.
.SH "SYNOPSIS"
.HP \w'\fBdebug\fR\ 'u
\fBdebug\fR [\-h] [\-l\ [\fIlib\fR]] [\-C\ [\fIlib\fR]] [\-V\ [\fIval\fR]] [lib\ [\fIflag\fR]]
.SH "DESCRIPTION"
.PP
Supports listing, setting and checking the debug flags defined by
\fIBRL\-CAD\fR
libraries\&. The outputs controlled by this command are extremely low level, most likely cryptic to those not familiar with the internal of BRL\-CAD\*(Aqs 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,
\fInot\fR
intended for general user consumption and should be avoided unless you know
\fIexactly\fR
what you are doing\&.
.PP
The
\fB\-h\fR
help option will print out a list of libraries supported by the debug command\&.
.PP
The
\fB\-l\fR
option will print out a list of debugging flags supported by the debug command\&. With no argument to
\fB\-l\fR
all flags for all libraries are listed \- supplying a library name (per output from the
\fB\-h\fR
option) to
\fB\-l\fR
will list only the flags specific to that library\&.
.PP
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
\fInever\fR
be relied upon for any user\-facing functionality\&.
.SH "FLAG REPORTING AND MANIPULATION"
.PP
With no arguments, the
\fBdebug\fR
command displays all currently set debug flags for all libraries\&. If no debug flags are set (the default) the return will be empty\&.
.PP
If a library name is added as an argument, (for example, "debug bu") the
\fBdebug\fR
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\&.
.PP
To toggle a particular flag, the user supplies the library name and the flag to the
\fBdebug\fR
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
\fBdebug\fR
command modes allow the user to determine the current state of a flag\&.
.PP
If a user wishes to simply clear all active flags, they can use the
\fB\-C\fR
option to
\fBdebug\fR
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\&.
.PP
Although it shouldn\*(Aqt normally be necessary, the
\fB\-V\fR
option provides a way to report and manipulate the low level hexadecimal numerical values controlling the flag behaviors\&. Without additional arguments,
\fB\-V\fR
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\&.
.SH "EXAMPLES"
.PP
\fBExample\ \&1.\ \&Display help and available libraries\fR
.PP

mged>\fBdebug \-h\fR
.sp
.if n \{\
.RS 4
.\}
.nf
debug [\-h] [\-l [lib]] [\-C [lib]] [\-V [lib] [val]] [lib [flag]]

Available libs:
        BU
        NMG
        OPTICAL
        RT
    
.fi
.if n \{\
.RE
.\}
.sp

.PP
\fBExample\ \&2.\ \&List available flags for \fILIBBU\fR\fR
.PP

mged>\fBdebug \-l BU\fR
.sp
.if n \{\
.RS 4
.\}
.nf
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 
    
.fi
.if n \{\
.RE
.\}
.sp

.PP
\fBExample\ \&3.\ \&Set \fILIBBU\fR flags for bu_avs and path debugging\fR
.PP

mged>\fBdebug BU AVS\fR
.sp
.if n \{\
.RS 4
.\}
.nf
           AVS (0x00000400): bu_avs_() loggin
    
.fi
.if n \{\
.RE
.\}
.PP

mged>\fBdebug BU PATHS\fR
.sp
.if n \{\
.RS 4
.\}
.nf
           AVS (0x00000400): bu_avs_() logging 
         PATHS (0x00001000): File and path debug logging 
    
.fi
.if n \{\
.RE
.\}
.sp

.PP
\fBExample\ \&4.\ \&Set \fILIBRT\fR flag for rt_shootray processing\fR
.PP

mged>\fBdebug RT SHOOT\fR
.sp
.if n \{\
.RS 4
.\}
.nf
         SHOOT (0x00000004): 3 Info about rt_shootray() processing
    
.fi
.if n \{\
.RE
.\}
.sp

.PP
\fBExample\ \&5.\ \&List LIBBU's active debugging flags and all active debugging flags\fR
.PP

mged>\fBdebug BU\fR
.sp
.if n \{\
.RS 4
.\}
.nf
           AVS (0x00000400): bu_avs_() logging 
         PATHS (0x00001000): File and path debug logging
    
.fi
.if n \{\
.RE
.\}
.PP

mged>\fBdebug\fR
.sp
.if n \{\
.RS 4
.\}
.nf
BU flags:
           AVS (0x00000400): bu_avs_() logging 
         PATHS (0x00001000): File and path debug logging 

RT flags:
         SHOOT (0x00000004): 3 Info about rt_shootray() processing 
    
.fi
.if n \{\
.RE
.\}
.sp

.PP
\fBExample\ \&6.\ \&Clear LIBRT debug flags\fR
.PP

mged>\fBdebug \-C RT\fR
.sp
.if n \{\
.RS 4
.\}
.nf
    
.fi
.if n \{\
.RE
.\}
.sp

mged>\fBdebug\fR
.sp
.if n \{\
.RS 4
.\}
.nf
BU flags:
           AVS (0x00000400): bu_avs_() logging 
         PATHS (0x00001000): File and path debug logging 

    
.fi
.if n \{\
.RE
.\}
.sp

.PP
\fBExample\ \&7.\ \&Clear all active debug flags for all libraries\fR
.PP

mged>\fBdebug \-C\fR
.SH "AUTHOR"
.PP
BRL\-CAD Team
.SH "BUG REPORTS"
.PP
Reports of bugs or problems should be submitted via electronic mail to
devs@brlcad\&.org
