bashdb(1)

📦 version 5.2, in nixos 26.05, nixpkgs unstable

💅 bashdb(1) — like, the bash debugger script, bestie

okay so quick vibe check: this is the manual page for bashdb, one of the GNU Tools crew. she's a debugger for bash scripts and she ate. let's get into it 🫶

✨ NAME ✨

bashdb — the bash debugger script. that's her. that's the whole name. iconic 💖

🌸 SYNOPSIS 🌸

bashdb [options] script-name [--] [script options]

bashdb [options] -c execution-string

bash --debugger [bash-options...] script-name [[--] script options]

three ways to summon her, pick your fighter 🎀

🦋 DESCRIPTION 🦋

bashdb is a bash script that arranges for another bash script to get debugged, which is honestly such a flex. the debugger's command interface is similar to gdb(1) — so if you already know gdb, you're gonna feel right at home, no cap.

the way this script pulls it off is by including (or more accurately, "source"-ing) some debug-support code, and then sourcing the script or command string you handed over. lowkey clever.

⚠️ okay so here's the one catch, bestie — when you source a debugged script, the program name stored in $0 will be bashdb instead of the name of the script being debugged 😭. and your debugged script shows up in a call stack not as the top item, but as the item below bashdb. if that's a problem for you (fair), use the last form shown above: bash --debugger script-name [script-options].

if you went the bashdb script route and you need to pass options through to the script being debugged, just drop a -- after the script name. that tells bashdb to stop trying to process any further options — like, "we're done here, take the rest, thanks" 💅

also!! there's a whole reference manual at <http://bashdb.sourceforge.net/bashdb.html> that explains how to call the debugger from inside your own program, or how to arrange for the debugger to get called when your program gets sent a signal. go read it, it's giving essential lore 📖

🎀 OPTIONS 🎀

  • -h | --help — prints a usage message on standard error and dips out with a return code of 100. very "here's the info, bye" energy.
  • -A | --annotation level — sets the debugger to output extra stack and status info, which lets front-ends like emacs keep track of what's going on without polling. this is needed in for regression testing, fr fr. using this option is equivalent to typing this inside the debugger:
set annotation LEVEL
  • -B | --basename — wherever a filename shows up in debugger output, you get just the basename only. also needed in for regression testing. using this option is equivalent to typing this inside the debugger:
set basename on
  • -n | --nx — normally the debugger reads debugger commands in ~/.bashdbrc (if that file exists) before accepting user interaction. .bashdbrc is analogous to Perl's .perldb or GNU gdb's .gdbinit — the whole point being that you might wanna create a debugger profile like this and fill it with various user-specific customizations, slay. with the -n option, that initialization file will not be read. super useful in regression testing, or when you're tracking down a problem with your own .bashdbrc profile 🔍
  • -c command-string — instead of naming a script file, you can hand over an execution string that's to be debugged. that's what this option is for, bestie. if you invoke the debugger via bash --debugger, the filename that appears in a source listing or in a call stack trace will be the artificial name *BOGUS*. yes, really. she said "fake name, don't perceive me" 💀
  • -q | --quiet — do not print the introductory version and copyright info. again, useful in regression testing, where we do not want a changeable copyright date getting mixed up in the regression-test matching. no changeable dates on the runway, periodt.
  • -x debugger-cmdfile — runs the debugger commands in debugger-cmdfile before accepting user input. these commands are read however after any .bashdbinit commands. again, useful for running regression-testing debug scripts. order matters, iykyk 🌈
  • -L | --library debugger-library — the debugger needs to source or include a bunch of functions, and those live in a library. if you don't pass this option, the default location of the library is relative to the installed bashdb script: "../lib/bashdb". she knows where her stuff lives 💜
  • -T | --tempdir temporary-file-directory — the debugger needs some temporary filesystem storage to save persistent info across a subshell return, or in order to evaluate an expression. the default directory is "/tmp", but you can use this option to set the directory where debugger temporary files get created. spring cleaning, but for paths 🧹
  • -t | --tty tty-name — debugger output usually goes to a terminal rather than STDOUT, because the debugged program might be using STDOUT. figuring out the tty or pseudo-tty is normally done automatically. but if you want to control where the debugger output goes, use this option. if you want output to go to STDOUT, use &1. note: the & may have to be escaped or quoted to avoid shell interpretation with forking. don't say we didn't warn you ⭐
  • -V | --version — shows the version number and the no-warranty notice, then exits with return code 1. yep, 1. she's quirky like that.
  • -X | --trace — similar to "set -x" line tracing, except that by default the location of each line, the bash level, and the subshell level all get printed. you might be able to get something roughly similar if you set PS4 like this:
export PS4='(${BASH_SOURCE}:${LINENO}): ${FUNCNAME[0]}\n'

in contrast however to "set -x" tracing, the indentation of the original program is also preserved in the source output. and if you interrupt the program with a break (a "SIGINT" signal), you'll go into the debugger — assuming your program doesn't trap "SIGINT", that is. main character energy, honestly 👑

💀 BUGS 💀

the bashdb script and the --debugger option assume you've got a version of bash with debugging support. meaning: you can't debug bash scripts using the standard-issue version 2.05b bash or earlier versions. and in versions after 3.0, debugging should have been enabled when bash was built (i think this is usually the case though). if you try to run the bashdb script on such a shell, you may get this message:

Sorry, you need to use a debugger-enabled version of bash.

oof. 😭

debugging startup time can be slow, especially on large bash scripts. scripts created by GNU autoconf are at thousands of lines — and it's not uncommon for them to be tens of thousands of lines. like, hello??

there is a provision to address this problem by including a fast file-to-array read routine (readarray), but the bashdb package has to be compiled in a special way, which needs access to the bash source code and objects. so, y'know. tradeoffs.

another reason for the debugger slowness: the debugger has to intercept every single line and check whether some action is to be taken for it — and this is all in bash code. a better and faster architecture would be for the debugger to register a list of conditions or stopping places inside the bash code itself, and have it arrange to call the debugger only when a condition requiring the debugger arises. the checks would be faster since that'd be done in C code, and access to internal structures would make it more efficient. someone get this girl a rewrite 🙈

🔥 SEE ALSO 🔥

go click them, they're literally right there 🦋

👑 AUTHOR 👑

the current version is maintained (or not) by Rocky Bernstein. (or not. she said what she said 💅)

Copyright (C) 2003, 2006-2007, 2016 Rocky Bernstein
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

okay that's the whole page, bestie. stay debuggin', stay slaying 🍓💖

version 5.2-1.2.0 ✨ dated 1980-01-01 ✨ brought to you by the GNU Tools girlies 🎀🫶

📦 where this page comes from