### Build and install bashdb from source

Source: https://github.com/trepan-debuggers/bashdb/blob/bash-5.2/docs/install.md

These commands guide the user through installing bashdb from its source code. It involves cloning the repository, running a configuration script, compiling the code, running tests, and finally installing the debugger. Dependencies like autoconf and automake might be required for the `./autogen.sh` step.

```bash
git clone git://github.com/rocky/bashdb.git
cd bashdb
./autogen.sh  # Add configure options. See ./configure --help
make && make test
sudo make install
```

--------------------------------

### Clone and Build bashdb from Source

Source: https://github.com/trepan-debuggers/bashdb/blob/bash-5.2/README-git.md

This sequence of commands clones the repository, generates the configuration script using autotools, compiles the source code, and runs the test suite. It requires autoconf, automake, autoheader, and texinfo to be installed on the system.

```bash
git clone https://github.com/Trepan-Debuggers/bashdb
cd bashdb
bash ./autogen.sh
bash ./configure
make
make check
sudo make install
```

--------------------------------

### Example BashDB Backtrace Output

Source: https://github.com/trepan-debuggers/bashdb/blob/bash-5.2/htdocs/bashdbOutline.html

An example session showing the output of the 'where' command in bashdb. It illustrates how the debugger lists frame numbers, function names, source files, and line numbers.

```text
bashdb<1> where
->0 in file `./parm.sh' at line 14
#1 fn3() called from file `./parm.sh' at line 14
#2 fn2("testing 1", "2 3") called from file `parm.sh' at line 5
#3 fn1("0") called from file `parm.sh' at line 9
#4 fn1("1") called from file `parm.sh' at line 9
#5 fn1("2") called from file `parm.sh' at line 9
#6 fn1("3") called from file `parm.sh' at line 9
#7 fn1("4") called from file `parm.sh' at line 9
#8 fn1("5") called from file `parm.sh' at line 21
#9 source("parm.sh") called from file `bashdb' at line 143
#10 main("-n", "-L", "..", "parm.sh") called from file `bashdb' at line 0
```

--------------------------------

### Example Script Using Bashdb Trace

Source: https://github.com/trepan-debuggers/bashdb/blob/bash-5.2/htdocs/bashdbOutline.html

A complete example of a BASH script (`debugit.sh`) that incorporates the `bashdb-trace` for debugging. It includes sourcing the debugger and a simple loop to print the date. The example also shows the output when running the script with the debugger.

```bash
# This is my extra debug hook
  source _/usr/share/bashdb/bashdb-trace_ # adjust location

  echo $$ 
  while : ; do
        date=$(date)
        echo "$date"
        sleep 2
  done 

# Example execution output:
# $ bash ./debugit.sh
# Bourne-Again Shell Debugger, release bash-3.1-0.08
# Copyright 2002, 2003, 2004, 2006 Rocky Bernstein
# This is free software, covered by the GNU General Public License, and you are
# welcome to change it and/or distribute copies of it under certain conditions.
# 
# 9435
```

--------------------------------

### Start BASH Debugger via Command Line

Source: https://github.com/trepan-debuggers/bashdb/blob/bash-5.2/htdocs/bashdbOutline.html

Demonstrates the standard methods for launching the BASH debugger using the --debugger flag with either a script file or a command string.

```bash
bash --debugger script-name script-arguments...
bash --debugger -c "command-string"
```

--------------------------------

### Step Into Command Usage Examples

Source: https://github.com/trepan-debuggers/bashdb/blob/bash-5.2/docs/commands/running/step.md

Demonstrates various ways to invoke the step command, including basic single stepping and using arithmetic expressions to define the step count.

```bash
step        # step 1
step 1      # same as above
step 5/5+0  # same as above
```

--------------------------------

### Print String Example in BashDB

Source: https://github.com/trepan-debuggers/bashdb/blob/bash-5.2/htdocs/bashdbOutline.html

This example shows how to use the `print` command in BashDB to display a string, including the value of a variable prefixed with a dollar sign. It also illustrates the need for escaping special characters like `*` or `$` if they are intended as literal characters.

```bash
bashdb<0> print the value of x is $x

```

--------------------------------

### bashdb Frame Command Examples

Source: https://github.com/trepan-debuggers/bashdb/blob/bash-5.2/docs/commands/stack/frame.md

Demonstrates various ways to use the 'frame' command in bashdb to navigate the call stack. Includes setting the current frame, moving to specific frame numbers, and examples of valid and invalid expression syntax.

```bash
frame     # Set current frame at the current stopping point
frame 0   # Same as above
frame 5-5 # Same as above. Note: no spaces allowed in expression 5-5
frame 1   # Move to frame 1. Same as: frame 0; up
```

--------------------------------

### Uninstall bashdb

Source: https://github.com/trepan-debuggers/bashdb/blob/bash-5.2/docs/install.md

This command uninstalls bashdb if it was installed using the `sudo make install` command from the source code.

```bash
sudo make uninstall
```

--------------------------------

### Configure Integration Test Files

Source: https://github.com/trepan-debuggers/bashdb/blob/bash-5.2/test/integration/README.md

Shows how to register an integration test file in configure.ac to enable template substitution and ensure the resulting script is executable.

```autoconf
AC_CONFIG_FILES([test/integration/test-delete],
                [chmod +x test/integration/test-delete])
```

--------------------------------

### Run bashdb debugger on a script

Source: https://github.com/trepan-debuggers/bashdb/blob/bash-5.2/docs/install.md

This command demonstrates how to invoke the bashdb debugger on a specific bash script. Replace `/etc/profile` with the path to the bash script you wish to debug.

```bash
./bashdb -L /etc/profile
```

--------------------------------

### Define Integration Test Template

Source: https://github.com/trepan-debuggers/bashdb/blob/bash-5.2/test/integration/README.md

Examples of .in template files for bashdb integration tests. These scripts use @-delimited variables for path substitution and source common library routines to execute debugger tests.

```bash
#!@SH_PROG@ -f
# -*- shell-script -*-
t=${0##*/}; TEST_NAME=${t:5}

[ -z "$builddir" ] && builddir=$PWD
. ${builddir}/check-common.sh
. run_test_check stepping
```

```bash
#!@SH_PROG@
# -*- shell-script -*-
TEST_NAME='file with spaces'

[ -z "$builddir" ] && builddir=$PWD
. ${builddir}/check-common.sh

if [[ -f "$top_srcdir/test/example/file with spaces.sh" ]] ; then
   run_test_check
else
   echo "Skipping test due to autoconf problems"
   exit 77
fi
```

--------------------------------

### Install bashdb using Homebrew on macOS

Source: https://github.com/trepan-debuggers/bashdb/blob/bash-5.2/docs/install.md

This command installs bashdb using the Homebrew package manager on macOS systems. Ensure Homebrew is installed and up-to-date before running this command.

```bash
brew install bashdb
```

--------------------------------

### Invoke Bashdb Debugger

Source: https://context7.com/trepan-debuggers/bashdb/llms.txt

Demonstrates the three primary methods for starting a debugging session: direct execution, using the bash flag, or embedding debugger calls within a script.

```bash
# Method 1: Direct invocation with bashdb
bashdb /etc/profile

# Method 2: Using bash with debugger flag
bash --debugger -- myscript.sh arg1 arg2

# Method 3: Embedded in your script for targeted debugging
#!/bin/bash
# my-script.sh

# Normal script execution with no debugger overhead
do_something

# Load debugger support at a specific point
source /usr/share/bashdb/bashdb-trace -L /usr/share/bashdb

# Invoke debugger - stops at next line
_Dbg_debugger; :
critical_function_to_debug
```

--------------------------------

### Integrate bashdb trace into a script

Source: https://github.com/trepan-debuggers/bashdb/blob/bash-5.2/docs/install.md

This snippet shows how to integrate bashdb's debugging capabilities directly into a bash script by sourcing the `dbg-trace.sh` script and then calling the `_Dbg_debugger` function. The `source` command should be executed once before `_Dbg_debugger` is called.

```bash
source path-to-bashdb/bashdb/dbg-trace.sh
# work, work, work.

_Dbg_debugger
# start debugging here
```

--------------------------------

### Invoke BashDB via command line

Source: https://github.com/trepan-debuggers/bashdb/blob/bash-5.2/README.md

Methods to start the debugger from the terminal. The first method uses the bash executable directly, while the second uses the bashdb wrapper.

```bash
bash --debugger -- bash-script-name script-arg1 script-arg2...
bashdb [bashdb-opts] -- bash-script-name script-arg1 script-arg2...
```

--------------------------------

### Start BASH Debugger Session

Source: https://github.com/trepan-debuggers/bashdb/blob/bash-5.2/htdocs/bashdbOutline.html

Initiates an interactive debugging session for a BASH script using the 'bashdb' command. The '-L .' option is used to specify the debugger's library path, typically when running from source.

```bash
bashdb -L .  /tmp/fact.sh
```

--------------------------------

### Filter and Validate Test Output

Source: https://github.com/trepan-debuggers/bashdb/blob/bash-5.2/test/integration/README.md

Demonstrates how to normalize debugger output using sed and grep before comparing it against expected results. Includes logic to handle differences between bash versions.

```bash
cat ${TEST_FILE} | @SED@ -e "s:1 = .*/dbg-test2.sh:1 = ./example/dbg-test2.sh:" \
| @SED@ -e 's:record the command history is .*:record the command history is: ' \
| @SED@ -e 's:step-:step+:' \
| @GREP@ -v '^set dollar0' > ${TEST_FILTERED_FILE}

if (( BASH_VERSINFO[0] == 5 )) ; then
    RIGHT_FILE="${top_srcdir}/test/data/${TEST_NAME}-output-50.right"
elif (( (BASH_VERSINFO[0] == 4 && BASH_VERSINFO[1] >= 1) )) ; then
    RIGHT_FILE="${top_srcdir}/test/data/${TEST_NAME}-output-41.right"
fi

check_output $TEST_FILTERED_FILE $RIGHT_FILE
```

--------------------------------

### Configure Editor for BashDB

Source: https://github.com/trepan-debuggers/bashdb/blob/bash-5.2/htdocs/bashdbOutline.html

This demonstrates how to configure the `EDITOR` environment variable to specify which editor BashDB should use for the `edit` command. The examples show settings for `sh` and `csh` shells.

```bash
# sh shell
EDITOR=/usr/bin/vi
export EDITOR

# csh shell
setenv EDITOR /usr/bin/vi
```

--------------------------------

### Set Temporary Breakpoints in BashDB

Source: https://github.com/trepan-debuggers/bashdb/blob/bash-5.2/docs/commands/breakpoints/tbreak.md

Demonstrates various ways to invoke the tbreak command to set temporary breakpoints. These examples show usage with current location, specific line numbers, and file-prefixed paths.

```bash
tbreak
tbreak 10
tbreak /etc/profile:10
tbreak myfile:45
```

--------------------------------

### Configure bashdb startup with .bashdbrc

Source: https://github.com/trepan-debuggers/bashdb/blob/bash-5.2/docs/entry-exit.md

Demonstrates creating a per-project .bashdbrc file to load external script functions and set conditional breakpoints automatically upon debugger startup.

```console
load ./libs/functions.sh
break ./main.sh:13 $cmd == "start"
break ./libs/functions.sh:332
```

--------------------------------

### Step Into Execution

Source: https://context7.com/trepan-debuggers/bashdb/llms.txt

Demonstrates the step command, which executes a single statement and enters function calls or sourced files.

```bash
bashdb<0> step        # Step one statement
bashdb<1> step 1      # Same as above
bashdb<2> step 5      # Step 5 statements
bashdb<3> step+       # Step, ensuring different line
bashdb<4> step-       # Step, may stop at same line
```

--------------------------------

### Deploy Documentation to SourceForge

Source: https://github.com/trepan-debuggers/bashdb/blob/bash-5.2/doc/how-to-make-a-release.md

Generates HTML documentation and deploys it to the SourceForge web server via SCP. Requires appropriate SSH access to the project hosting environment.

```bash
$ cd doc
$ rm *.html
$ make
$ scp *.html rockyb,bashdb@web.sourceforge.net:htdocs
```

--------------------------------

### Prepare Repository for Release

Source: https://github.com/trepan-debuggers/bashdb/blob/bash-5.2/doc/how-to-make-a-release.md

Commands to synchronize the local repository and generate the project ChangeLog file. This is the initial step in the release preparation workflow.

```bash
$ git pull
$ make ChangeLog
```

--------------------------------

### Copy BashDB Manual to Web Server (Bash)

Source: https://github.com/trepan-debuggers/bashdb/wiki/Releasing

This set of commands navigates to the `doc` directory, rebuilds the HTML documentation, and then securely copies the generated HTML files to the SourceForge web server. This makes the latest manual version accessible online.

```bash
$ cd doc
$ rm *.html
$ make
$ scp *.html rockyb,bashdb@web.sourceforge.net:htdocs
$ # scp -i ~/.ssh/id_rsa_sourceforge *.html rockyb,bashdb@web.sourceforge.net:/home/groups/b/ba/bashdb/htdocs/
```

--------------------------------

### Test Package from GitHub Clone (Bash)

Source: https://github.com/trepan-debuggers/bashdb/wiki/Releasing

This snippet demonstrates how to clone the BashDB repository from GitHub into a temporary directory, build it, and run checks. This is a crucial step to ensure the package is buildable and testable from a fresh clone.

```bash
$ [[ ! -d /tmp/gittest ]] && mkdir /tmp/gittest; pushd /tmp/gittest
$ git clone git+https://github.com/Trepan-Debuggers/bashdb.git
$ ./autogen && make && make check
```

--------------------------------

### List Specific Line in BASH Debugger

Source: https://github.com/trepan-debuggers/bashdb/blob/bash-5.2/htdocs/bashdbOutline.html

Displays source code starting from a specified line number in the BASH debugger. This allows targeted viewing of specific parts of the script.

```bash
list 1
```

--------------------------------

### Run Bash Script with Debugger Tracing

Source: https://github.com/trepan-debuggers/bashdb/blob/bash-5.2/htdocs/bashdbOutline.html

Demonstrates how to invoke the bashdb debugger with the -X flag to enable full script tracing without manual breakpoints.

```bash
/usr/local/bin/bashdb -X /tmp/fact.sh
```

--------------------------------

### Invoke bashdb from the command line

Source: https://github.com/trepan-debuggers/bashdb/blob/bash-5.2/docs/entry-exit.md

Shows the standard method for launching a bash script under the control of the bashdb debugger.

```console
bashdb /etc/profile
```

--------------------------------

### Call bashdb programmatically from a script

Source: https://github.com/trepan-debuggers/bashdb/blob/bash-5.2/docs/entry-exit.md

Explains how to trigger the debugger at a specific point in a script by sourcing the trace file and calling the _Dbg_debugger function, avoiding overhead until needed.

```bash
if [[ $i == "/etc/profile.d/bash_completion.sh" ]]; then
  # Load in debugger
  . /usr/share/bashdb/bashdb-trace -q
  # Call debugger
  _Dbg_debugger
fi
```

--------------------------------

### Define Debugger Command Aliases

Source: https://github.com/trepan-debuggers/bashdb/blob/bash-5.2/docs/commands/support/alias.md

The alias command maps a custom name to a standard debugger command. This is useful for creating shortcuts or resolving ambiguity between commands that share the same starting characters.

```default
alias cat list   # "cat myprog.sh" is the same as "list myprog.sh"
alias s   step   # "s" is now an alias for "step".
```

--------------------------------

### List Variables with Pattern Matching

Source: https://github.com/trepan-debuggers/bashdb/blob/bash-5.2/htdocs/bashdbOutline.html

The 'V' command allows users to list variables and their values, optionally filtering by a specific pattern.

```bash
V dq*
V FUNCNAME
```

--------------------------------

### Conditional statement behavior with skip

Source: https://github.com/trepan-debuggers/bashdb/blob/bash-5.2/docs/commands/running/skip.md

An example demonstrating how skipping an 'if' statement affects the execution flow of a grep command. Because the exit status $? is not changed, the debugger may enter the body of the conditional block even if the command was skipped.

```bash
if grep foo bar.txt ; then
   echo not skipped
fi
```

--------------------------------

### Loading Bashdb Trace for Program-Controlled Debugging

Source: https://github.com/trepan-debuggers/bashdb/blob/bash-5.2/htdocs/bashdbOutline.html

Shows how to modify a BASH script to load the `bashdb-trace` file, enabling program-controlled debugging. This method adds no overhead until the debugger is invoked. The `source` command is used to load the debugger code.

```bash
source /usr/local/share/bashdb/bashdb-trace
# or
source _/usr/share/bashdb/bashdb-trace_ # adjust location
```

--------------------------------

### Print and Examine Variables in BashDB

Source: https://github.com/trepan-debuggers/bashdb/blob/bash-5.2/htdocs/bashdbOutline.html

The 'p' command prints expressions, while the 'x' command provides a versatile way to inspect variables, arrays, functions, or evaluate arithmetic expressions using BASH's internal mechanisms.

```bash
p The home directory for root is ~root
p '*** You may have won $$$ ***'
examine x y
examine x+y
x fn1
x FUNCNAME
```

--------------------------------

### Loading Bashdb Debugger within a Script

Source: https://github.com/trepan-debuggers/bashdb/blob/bash-5.2/doc/README.md

Shows how to load and activate the bashdb debugger from within a Bash script itself. This method involves sourcing a bashdb trace script and then calling a debugger function. It offers an advantage of having no overhead until the debugger is explicitly invoked.

```bash
# Load debugger support
BASHDB_INSTALL=/usr/share/bashdb # ADJUST THIS!
source ${BASHDB_INSTALL}/bashdb-trace -L $BASHDB_INSTALL
# work, work, work or not...
_Dbg_debugger; :   # Calls the debugger at the line below
```

--------------------------------

### Search Source Files in BashDB

Source: https://github.com/trepan-debuggers/bashdb/blob/bash-5.2/htdocs/bashdbOutline.html

The `search` (or `forward`) and `reverse` commands allow searching within the current source file using Bash extended pattern-matching expressions. `search` moves forward from the current line, while `reverse` moves backward. They list the first matching line found.

```bash
forward bash-pattern
search bash-pattern
reverse bash-pattern
```

--------------------------------

### Set Breakpoints in BashDB

Source: https://github.com/trepan-debuggers/bashdb/blob/bash-5.2/htdocs/bashdbOutline.html

Demonstrates how to set breakpoints at specific functions, line numbers, or files. It also shows how to apply conditional logic to breakpoints using the 'if' keyword.

```bash
# Set breakpoint at function entry
break fn1

# Set breakpoint at specific line
break 28

# Set breakpoint in specific file
break parm.sh:29

# Set conditional breakpoint
break 28 if x==5
```

--------------------------------

### Control Line Tracing Programmatically

Source: https://github.com/trepan-debuggers/bashdb/blob/bash-5.2/htdocs/bashdbOutline.html

Demonstrates how to enable and disable line tracing within a script using _Dbg_linetrace_on and _Dbg_linetrace_off, and how to manage debugger exit behavior.

```bash
source _path-to-program_/bashdb-trace
_Dbg_linetrace_on
for i in `seq 10` ; do
  echo $i
done
_Dbg_linetrace_off
_Dbg_QUIT_ON_QUIT=1
```

--------------------------------

### Display Call Stack

Source: https://context7.com/trepan-debuggers/bashdb/llms.txt

Shows how to use the backtrace command to view the current call stack and navigate through execution frames.

```bash
bashdb<0> backtrace         # Show full call stack
->0 in file `/home/user/script.sh' at line 45
##1 function1() called from file `/home/user/script.sh' at line 32
##2 main() called from file `/home/user/script.sh' at line 10

bashdb<1> backtrace 2       # Show only top 2 entries
bashdb<2> backtrace -1      # Show all except bottom entry
```

--------------------------------

### Configure Bash PS4 for Detailed Tracing

Source: https://github.com/trepan-debuggers/bashdb/blob/bash-5.2/htdocs/bashdbOutline.html

Sets the PS4 environment variable to display the current file source, line number, function name, shell level, and subshell depth during execution. This configuration should be placed in shell startup files like .bashrc or .profile.

```bash
PS4='(${BASH_SOURCE}:${LINENO}): ${FUNCNAME[0]} - [${SHLVL},${BASH_SUBSHELL}, $?]
'
```

--------------------------------

### Source Debugger Configuration Files

Source: https://context7.com/trepan-debuggers/bashdb/llms.txt

The source command executes a sequence of debugger commands from a specified file. This is commonly used to load preset breakpoints and environment configurations.

```bash
bashdb<0> source debug-config.txt
bashdb<1> source -v debug-config.txt
bashdb<2> source -Y debug-config.txt
bashdb<3> source -c debug-config.txt
```

--------------------------------

### Commit Version Changes and Build (Bash)

Source: https://github.com/trepan-debuggers/bashdb/wiki/Releasing

After updating version variables, commit the changes and then run `autogen.sh`, `make`, and `make check` to build the project and run tests. This ensures the new version is correctly reflected and the build is stable.

```bash
$ git commit . -m"Get ready for release $BASHDB_VERSION"
$ ./autogen.sh && make && make check
```

--------------------------------

### Set Breakpoints

Source: https://context7.com/trepan-debuggers/bashdb/llms.txt

Shows how to set breakpoints at specific lines, files, or functions within the Bashdb environment.

```bash
bashdb<0> break              # Break at current line
bashdb<1> break 10           # Break at line 10 of current file
bashdb<2> break /etc/profile:45   # Break at line 45 of /etc/profile
bashdb<3> break myfunc       # Break at function myfunc
```

--------------------------------

### Step Over Execution

Source: https://context7.com/trepan-debuggers/bashdb/llms.txt

Shows the next command, which executes function calls at full speed and stops at the next line in the current scope.

```bash
bashdb<0> next        # Step over function call
bashdb<1> next 3      # Execute next 3 statements at current level
bashdb<2> next+       # Step over, must stop at different line
bashdb<3> next-       # Step over, can stop at same line
```

--------------------------------

### List Source Code

Source: https://context7.com/trepan-debuggers/bashdb/llms.txt

The list command displays source code snippets based on line numbers or file paths. It supports relative navigation and specific range selection.

```bash
bashdb<0> list              # List lines around current position
bashdb<1> list 5            # List starting from line 5
bashdb<2> list /etc/profile:20   # List from line 20 of /etc/profile
bashdb<3> list /etc/profile 10 20   # List lines 10-20 of /etc/profile
bashdb<4> list .            # List around current stopped line
bashdb<5> list -            # List lines before previously shown
```