Debug your shell scripts with bashdb

The Bash Debugger Project (bashdb) lets you set breakpoints, inspect variables, perform a backtrace, and step through a bash script line by line. In other words, it provides the features you expect in a C/C++ debugger to anyone programming a bash script.

To see if your standard bash executable has bashdb support, execute the command shown below; if you are not taken to a bashdb prompt then you’ll have to install bashdb yourself.

$ bash --debugger -c "set|grep -i dbg"
...
bashdb

The Ubuntu Intrepid repository contains a package for bashdb, but there is no special bashdb package in the openSUSE 11 or Fedora 9 repositories. I built from source using version 4.0-0.1 of bashdb on a 64-bit Fedora 9 machine, using the normal ./configure; make; sudo make install commands.

You can start the Bash Debugger using the bash --debugger foo.sh syntax or the bashdb foo.sh command. The former method is recommended except in cases where I/O redirection might cause issues, and it’s what I used. You can also use bashdb through ddd or from an Emacs buffer.

The syntax for many of the commands in bashdb mimics that of gdb, the GNU debugger. You can step into functions, use next to execute the next line without stepping into any functions, generate a backtrace with bt, exit bashdb with quit or Ctrl-D, and examine a variable with print $foo. Aside from the prefixing of the variable with $ at the end of the last sentence, there are some other minor differences that you’ll notice. For instance, pressing Enter on a blank line in bashdb executes the previous step or next command instead of whatever the previous command was.

The print command forces you to prefix shell variables with the dollar sign ($foo). A slightly shorter way of inspecting variables and functions is to use the x foo command, which uses declare to print variables and functions.

Both bashdb and your script run inside the same bash shell. Because bash lacks some namespace properties, bashdb will include some functions and symbols into the global namespace which your script can get at. bashdb prefixes its symbols with _Dbg_, so you should avoid that prefix in your scripts to avoid potential clashes. bashdb also uses some environment variables; it uses the DBG_ prefix for its own, and relies on some standard bash ones that begin with BASH_.

To illustrate the use of bashdb, I’ll work on the small bash script below, which expects a numeric argument n and calculates the nth Fibonacci number.

#!/bin/bash

version="0.01";

fibonacci() {
    n=${1:?If you want the nth fibonacci number, you must supply n as the first parameter.}
    if [ $n -le 1 ]; then 
	echo $n
    else
	l=`fibonacci $((n-1))`
	r=`fibonacci $((n-2))`
	echo $((l + r))
    fi
}

for i in `seq 1 10`
do
  result=$(fibonacci $i)
  echo "i=$i result=$result"
done

The below session shows bashdb in action, stepping over and then into the fibonacci function and inspecting variables. I’ve made my input text bold for ease of reading. An initial backtrace (bt) shows that the script begins at line 3, which is where the version variable is written. The next and list commands then progress to the next line of the script a few times and show the context of the current execution line. After one of the next commands I press Enter to execute next again. I invoke the examine command through the single letter shortcut x. Notice that the variables are printed out using declare as opposed to their display on the next line using print. Finally I set a breakpoint at the start of the fibonacci function and continue the execution of the shell script. The fibonacci function is called and I move to the next line a few times and inspect a variable.

$ bash --debugger ./fibonacci.sh
...
(/home/ben/testing/bashdb/fibonacci.sh:3):
3:	version="0.01";
bashdbbt
->0 in file `./fibonacci.sh' at line 3
##1 main() called from file `./fibonacci.sh' at line 0
bashdbnext
(/home/ben/testing/bashdb/fibonacci.sh:16):
16:	for i in `seq 1 10`
bashdblist
 16:==>for i in `seq 1 10`
 17:   do
 18:   result=$(fibonacci $i)
 19:   echo "i=$i result=$result"
 20:   done
bashdbnext
(/home/ben/testing/bashdb/fibonacci.sh:18):
18:	result=$(fibonacci $i)
bashdb 
(/home/ben/testing/bashdb/fibonacci.sh:19):
19:	echo "i=$i result=$result"
bashdbx i result
declare -- i="1"
declare -- result=""

bashdbprint $i $result
1
bashdbbreak fibonacci
Breakpoint 1 set in file /home/ben/testing/bashdb/fibonacci.sh, line 5.
bashdbcontinue
Breakpoint 1 hit (1 times).
(/home/ben/testing/bashdb/fibonacci.sh:5):
5:	fibonacci() {
bashdbnext
(/home/ben/testing/bashdb/fibonacci.sh:6):
6:	n=${1:?If you want the nth fibonacci number, you must supply n as the first parameter.}
bashdbnext
(/home/ben/testing/bashdb/fibonacci.sh:7):
7:	if [ $n -le 1 ]; then
bashdbx n
declare -- n="2"
bashdbquit

Notice that the number in the bashdb prompt toward the end of the above example is enclosed in parentheses. Each set of parentheses indicates that you have entered a subshell. In this example this is due to being inside a shell function.

In the below example I use a watchpoint to see if and where the result variable changes. Notice the initial next command. I found that if I didn’t issue that next then my watch would fail to work. As you can see, after I issue c to continue execution, execution is stopped whenever the result variable is about to change, and the new and old value are displayed.

(/home/ben/testing/bashdb/fibonacci.sh:3):
3:	version="0.01";
bashdb<0> next
(/home/ben/testing/bashdb/fibonacci.sh:16):
16:	for i in `seq 1 10`
bashdb<1> watch result
 0: ($result)==0 arith: 0
bashdb<2> c
Watchpoint 0: $result changed:
  old value: ''
  new value: '1'
(/home/ben/testing/bashdb/fibonacci.sh:19):
19:	echo "i=$i result=$result"
bashdb<3> c
i=1 result=1
i=2 result=1
Watchpoint 0: $result changed:
  old value: '1'
  new value: '2'
(/home/ben/testing/bashdb/fibonacci.sh:19):
19:	echo "i=$i result=$result"

To get around the strange initial next requirement I used the watche command in the below session, which lets you stop whenever an expression becomes true. In this case I’m not overly interested in the first few Fibonacci numbers so I set a watch to have execution stop when the result is greater than 4. You can also use a watche command without a condition; for example, watche result would stop execution whenever the result variable changed.

$ bash --debugger ./fibonacci.sh
(/home/ben/testing/bashdb/fibonacci.sh:3):
3:	version="0.01";
bashdb<0> watche result > 4
 0: (result > 4)==0 arith: 1
bashdb<1> continue
i=1 result=1
i=2 result=1
i=3 result=2
i=4 result=3
Watchpoint 0: result > 4 changed:
  old value: '0'
  new value: '1'
(/home/ben/testing/bashdb/fibonacci.sh:19):
19:	echo "i=$i result=$result"

When a shell script goes wrong, many folks use the time-tested method of incrementally adding in echo or printf statements to look for invalid values or code paths that are never reached. With bashdb, you can save yourself time by just adding a few watches on variables or setting a few breakpoints.