bdl-lib.sh: add bash debug logger

Add bdl-lib.sh which provides functions to assit in debugging git shell scripts and tests. The primary public interace are two routines, bdl and bdl_nsl which print strings. The difference between the two is that bdl outputs location of the statement optionally followed by a string to print. For example:

  $ cat -n bdl-exmpl1.sh
       1  #!/usr/bin/env bash
       2  . bdl-lib.sh
       3  bdl "hi"
       4  
       5  # If no parameters just the location is printed
       6  bdl
  $ ./bdl-exmpl1.sh 
  bdl-exmpl1.sh:3: hi
  bdl-exmpl1.sh:6:

bdl_nsl means bdl with no source location being printed and at least one parameter is required. For example:

  $ cat -n bdl-exmpl2.sh 
       1  #!/usr/bin/env bash
       2  . bdl-lib.sh
       3  bdl_nsl "hi"
       4	
       5  # If no parameters nothing is printed
       6  bdl_nsl
  $ ./bdl-exmpl1.sh 
  hi

These routines can also take two parameters where the first parameter is the destination for the string. There are two types of destinations, either a single digit file descriptor 1..9 or a file name. For example:

  $ cat -n bdl-exmpl3.sh
       1  #!/usr/bin/env bash
       2  . bdl-lib.sh
       3  
       4  # Output to STDOUT
       5  bdl_nsl 1 "hi there"
       6  
       7  # Map 5 to STDOUT
       8  exec 5>&1
       9  bdl 5 "yo dude"
      10  
      11  # Output to a file
      12  bdl bdl_out.txt "good bye!"
      13  cat bdl_out.txt
      14  rm bdl_out.txt
  $ ./bdl-exmpl3.sh 
  hi there
  bdl-exmpl3.sh:9: yo dude
  bdl-exmpl3.sh:12: good bye!

If a destination is not provided as a parameter than there are two variables, bdl_dst and bdl_stdout, that can be used to provide a defaults. With bdl_dst taking presedence over bdl_stdout and a destination parameter taking presedence over the variables. For example:

  $ cat -n bdl-exmpl4.sh 
       1  #!/usr/bin/env bash
       2  . bdl-lib.sh
       3  
       4  # Set defaults with bdl_dst taking presedence
       5  bdl_dst=bdl_dst_out.txt
       6  bdl_stdout=5
       7  
       8  bdl_nsl "printed by bdl_nsl to bdl_dst_out.txt"
       9  bdl "printed by bdl to bdl_dst_out.txt"
      10  
      11  # But the parameter the ultimate presedence
      12  bdl bdl_out.txt "good bye to bdl_out.txt"
      13  
      14  cat bdl_dst_out.txt
      15  cat bdl_out.txt
      16  
      17  rm bdl_dst_out.txt
      18  rm bdl_out.txt
      19  
      20  # Now clear bdl_dst and bdl_stdout takes presedence
      21  # but parameters take presedence
      22  bdl_dst=
      23  exec 5>&1
      24  
      25  bdl_nsl "monkeys via 5"
      26  bdl 1 "horses via 1"
      27  bdl bdl_out.txt "orcas to bdl_out.txt"
      28  
      29  cat bdl_out.txt
      30  rm bdl_out.txt
  $ ./bdl-exmpl4.sh 
  printed by bdl_nsl to bdl_dst_out.txt
  bdl-exmpl4.sh:9: printed by bdl to bdl_dst_out.txt
  bdl-exmpl4.sh:26: orcas to bdl_out.txt
  bdl-exmpl4.sh:12: good bye to bdl_out.txt
  monkeys via 5
  bdl-exmpl4.sh:26: horses via 1
  bdl-exmpl4.sh:27: orcas to bdl_out.txt

TODO: More tests and documentation needed.

Wink Saville (1):
bdl-lib.sh: add bash debug logger

 bdl-exmpl.sh       |  46 ++++++++++++
 bdl-lib.sh         | 215 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 t/t0014-bdl-lib.sh | 115 ++++++++++++++++++++++++++++
 t/test-lib.sh      |   4 +
 4 files changed, 380 insertions(+)
 create mode 100755 bdl-exmpl.sh
 create mode 100644 bdl-lib.sh
 create mode 100755 t/t0014-bdl-lib.sh

2.16.3

Add bdl-lib to assist the programmer in debugging scripts and tests.

---
 bdl-exmpl.sh       |  46 ++++++++++++
 bdl-lib.sh         | 215 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 t/t0014-bdl-lib.sh | 115 ++++++++++++++++++++++++++++
 t/test-lib.sh      |   4 +
 4 files changed, 380 insertions(+)
 create mode 100755 bdl-exmpl.sh
 create mode 100644 bdl-lib.sh
 create mode 100755 t/t0014-bdl-lib.sh

new file mode 100755
index 000000000..a47d82bca
@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+# Examples using bdl-lib.sh
+
+# Source bdl-lib.sh
+. bdl-lib.sh
+
+# These both output to the default bdl_stdout=1
+bdl
+bdl "hi"
+bdl 1 "hi"
+
+# Output to a file as parameter
+echo -n >bdl_out.txt
+bdl bdl_out.txt "hi to bdl_out.txt"
+cat bdl_out.txt
+
+# Output to a file via bdl_dst
+echo -n >bdl_out.txt
+bdl_dst=bdl_out.txt
+bdl "hi to bdl_out.txt"
+cat bdl_out.txt
+bdl_dst=
+
+# Output to FD 5 connected to 1 via bdl_stdout
+bdl_stdout=5
+exec 5>&1
+bdl
+bdl "hi"
+bdl 5 "hi"
+exec 1>&5
+bdl_stdout=1
+
+# No printing to stdout
+echo -n >bdl_out.txt
+bdl_stdout=1
+bdl_dst=
+bdl 0 "not printed"
+bdl_stdout=0
+bdl
+bdl bdl_out.txt "printed to bdl_out.txt"
+bdl "not printed"
+bdl_stdout=1
+cat bdl_out.txt
+
+# This prints a "0" since there is only one parameter
+bdl 0

index 7740d511d..85142e462 100644
@@ -680,11 +680,15 @@ test_run_ () {
 		trace=$trace_tmp
 	fi
 
+	test "$BDL_LOADED" = "t" && bdl_push 4 "$@"
+
 	setup_malloc_check
 	test_eval_ "$1"
 	eval_ret=$?
 	teardown_malloc_check
 
+	test "$BDL_LOADED" = "t" && bdl_pop
+
 	if test -z "$immediate" || test $eval_ret = 0 ||
 	   test -n "$expecting_failure" && test "$test_cleanup" != ":"
 	then

2.16.3

Hi Wink,

Interesting idea. It is Bash-only, though... (and it is not a secret that I want to discourage using Unix shell scripts in Git's production code, they are a decent way to prototype things, but they fall short of being robust and portable in practice, and don't get me started on speed issues).

So rather than spending time on making it easier to debug shell scripts, I would love to see us going into the direction of a consistent C source code. I still believe that we can get there, and that the benefits are worth the (huge) effort.

Ciao,
Johannes

I totally agree the code base should use primarily one language!

But that's not the case now and "bdl" gave me insight into the workings of rebase--interactive and I found little guidance on how to debug or learn the code base. So I thought I'd see if there was interest in what I'd done.

If I were to make it non-bash specific would there be any interest?

-- Wink

Hi Wink,

Great!

And realistically, requiring Bash is not all that much of a problem when targeting developers.

After thinking about this more, I am a lot less opposed to including this in Git's source code. However, as it is not necessary for Git's functionality, it should probably go into contrib/, and I would much rather have a more descriptive name such as contrib/bash-debugging-library/...

Ciao,
Johannes

I'll move it, thanks for the feed back and considering it for inclusion.

-- Wink

Hi Wink,

Note: I have nothing to do with including it. That is the sole discretion of Junio (who is offline for a week or two, if I understood correctly).

Ciao,
Johannes

txs, I understand.