DEBUG.SH(8)

okay bestie, welcome to DEBUG.SH(8) (aka debug.sh) from the System Manager's Manual ✨ this is the page where shell debugging gets its main character energy 💅

🎀 NAME 🎀

debug.sh — selectively debug scripts 🦋

✨ SYNOPSIS ✨

$_DEBUG_SH . debug.sh

DebugOn [-eo] tag ...
DebugOff [-eo] [rc=rc] tag ...
Debugging
DebugAdd tag
DebugEcho [message]
DebugLog [message]
DebugShell tag ...
DebugTrace message
Debug tag ...

💅 DESCRIPTION 💅

okay so debug.sh provides the following functions to facilitate flexible run-time tracing of complicated shell scripts — literally the whole toolbox, no cap 🧰✨

• DebugOn [-eo] tag ... — turns tracing on if any tag is found in DEBUG_SH (a comma separated list of tags). It turns tracing off if !tag is found in DEBUG_SH. It sets DEBUG_ON to the tag that caused tracing to be enabled, or DEBUG_OFF if we matched !tag. If -e option is present, returns 1 if no tag matched. If -o option is present, tracing is turned off unless there was a matched tag, useful for functions too noisy to trace.
• DebugOff [-eo] [rc=rc] tag ... — turns tracing on if any tag matches DEBUG_OFF or off if any tag matches DEBUG_ON. This allows nested functions to not interfere with each other. The flags -e and -o are ignored, they just allow for symmetry with calls to DebugOn(). The optional rc value will be returned rather than the default of 0. Thus if DebugOff() is the last operation in a function, rc will be the return code of the function.
• Debugging — returns true if tracing is enabled. It is useful for bounding complex debug actions, rather than using lots of $DEBUG_DO lines.
• DebugAdd tag — Add tag to DEBUG_SH to influence later output, possibly in a child process.
• DebugEcho [message] — is just shorthand for:

$DEBUG_DO echo "$@"

• DebugLog [message] — If debugging is enabled, output message prefixed with a timestamp.
• DebugShell tag ... — runs an interactive shell if any tag is found in DEBUG_INTERACTIVE, and there is a tty available. The shell used is defined by DEBUG_SHELL or SHELL and defaults to /bin/sh.
• DebugTrace message — Debug output can be very noisy, and it can be tricky to align with the script. This function outputs a very noticeable banner indicating the value of DEBUG_ON, and message is passed to DebugLog(), finally the banner is repeated.
• Debug tag ... — For backwards compatibility, calls DebugOn() and if that does not turn tracing on, it calls DebugOff() to turn it off.

The variables DEBUG_SKIP and DEBUG_DO are set so as to enable/disable code that should be skipped/run when debugging is turned on. DEBUGGING is the same as DEBUG_SKIP for backwards compatibility and is only set by Debug().

The use of $_DEBUG_SH is to prevent multiple inclusion, though it does no harm in this case.

💀 BUGS 💀

Does not work with some versions of ksh(1). If a function turns tracing on, ksh turns it off when the function returns - useless. 😭

PD ksh works ok ;-) 💀

👑 AUTHOR 👑

debug.sh was written by Simon J Gerraty <sjg@crufty.net>.

---

xoxo, from Debian, dated October 22, 2024 — yep, that's the source/version + date on this DEBUG.SH(8) footer, bestie 🫶