Skip to content

Debug Tools

Debugging

The global BUILD_DEBUG can be set to a comma-delimited list of values to enable debugging for areas of Zesk Build.

You can use # BUILD_DEBUG: tokenName - descriptions as an function comment to document meanings of debug tokens honored by your function.

buildDebugEnabled

Is build debugging enabled?

Usage

buildDebugEnabled [ moduleName ]

Is build debugging enabled?

Location: bin/build/tools/debug.sh

Arguments

  • moduleName - String. Optional. If BUILD_DEBUG contains any token passed, debugging is enabled.

Examples

BUILD_DEBUG=false # All debugging disabled
BUILD_DEBUG= # All debugging disabled
unset BUILD_DEBUG # All debugging is disabled
BUILD_DEBUG=true # All debugging is enabled
BUILD_DEBUG=handler,bashPrompt # Debug `handler` and `bashPrompt` calls
if buildDebugEnabled bashPrompt; then
    # ... prompt debugging code
fi

Return codes

  • 1 - Debugging is not enabled (for any module)
  • 0 - Debugging is enabled

Environment

  • BUILD_DEBUG Debugging Flag – CommaDelimitedList. Constant for turning debugging on during build to find errors - Set to non-blank to enable debugging, blank to disable. BUILD_DEBUG may be a comma-separated list of modules to target debugging.

buildDebugStart

Start bash debugging

Usage

buildDebugStart [ moduleName ]

Start bash debugging if it is enabled. This does set -x which traces and outputs every shell command. Use it to debug when you can not figure out what is happening internally.

BUILD_DEBUG can be a list of strings like environment,assert for example.

Example: Example: buildDebugStart || :

Location: bin/build/tools/debug.sh

Arguments

  • moduleName - String. Optional. Only start debugging if debugging is enabled for ANY of the passed in modules.

Examples

# ... complex code here
buildDebugStop || :. -

Return codes

  • 0 - bash debugging was started
  • 1 - bash debugging was not started because token did not match.

Environment

Requires

buildDebugStop

Stop bash debugging

Usage

buildDebugStop [ --help ]

Stop bash debugging if it is enabled.

Location: bin/build/tools/debug.sh

Arguments

  • --help - Flag. Optional. Display this help.

Return codes

  • 0 - bash debugging was stopped
  • 1 - bash debugging was not stopped because token did not match.

Requires

See Also

Bash Debug

isBashDebug

Returns whether the shell has the debugging flag set

Usage

isBashDebug

Returns whether the shell has the debugging flag set

Useful if you need to temporarily enable or disable it.

Location: bin/build/tools/debug.sh

Arguments

  • none

Return codes

  • 0 - bash debugging (set -x) is enabled
  • 1 - bash debugging (set -x) is not enabled

isErrorExit

Returns whether the shell has the error exit flag set

Usage

isErrorExit

Returns whether the shell has the error exit flag set

Useful if you need to temporarily enable or disable it.

October 2024 - Does appear to be inherited by subshells

set -e
printf "$(isErrorExit; printf %d $?)"

Outputs 1 always

Location: bin/build/tools/debug.sh

Arguments

  • none

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Requires

  • -

Debugging tools

plumber

Run command and detect any global or local leaks

Usage

plumber [ command ... ] [ --temporary tempPath ] [ --leak envName ... ] [ --verbose ] [ --help ]

Run command and detect any global or local leaks

Location: bin/build/tools/debug.sh

Arguments

  • command ... - Callable. Command to run
  • --temporary tempPath - Directory. Optional. Use this for the temporary path.
  • --leak envName ... - EnvironmentVariable. Variable name which is OK to leak.
  • --verbose - Flag. Optional. Be verbose.
  • --help - Flag. Optional. Display this help.

Debugging settings

Append to the value of BUILD_DEBUG (a comma-delimited (,) list) and add these tokens to enable debugging:

  • plumber-verbose - The plumber outputs the exact variable captures before and after
  • plumber-verbose - The plumber outputs the exact variable captures before and after

Return codes

  • 0 - No leaks detected in the command
  • 108 - A leak was detected in the command
  • 1 - Argument error, plumber was called incorrectly.

Requires

housekeeper

Run a command and ensure files are not modified

Usage

housekeeper [ --ignore grepPattern ] [ --temporary temporaryPath ] [ --cache cacheDirectory ] [ --overhead ] [ --path path ] [ path ] [ callable ] [ --help ] [ --handler handler ]

Run a command and ensure files are not modified

Location: bin/build/tools/debug.sh

Arguments

  • --ignore grepPattern - String. Directory. One or more directories to watch. If no directories are supplied uses current working directory.
  • --temporary temporaryPath - Directory. Optional. Use this as a temporary directory instead of the default.
  • --cache cacheDirectory - Directory. Optional. Directory used to cache information between calls; if supplied for similar calls saves time in subsequent calls.
  • --overhead - Flag. Optional. Report on timing used by this function.
  • --path path - Directory. Optional. One or more directories to watch. If no directories are supplied uses current working directory.
  • path - Directory. Optional. One or more directories to watch. If no directories are supplied uses current working directory.
  • callable - Callable. Optional. Program to run and watch directory before and after.
  • --help - Flag. Optional. Display this help.
  • --handler handler - Function. Optional. Use this error handler instead of the default error handler.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

outputTrigger

Check output for content and trigger environment error if found

Usage

outputTrigger [ --help ] [ --verbose ] [ --name name ] [ message ... ]

Check output for content and trigger environment error if found

Location: bin/build/tools/debug.sh

Arguments

  • --help - Help
  • --verbose - Flag. Optional. Verbose messages when no errors exist.
  • --name name - String. Optional. Name for verbose mode.
  • message ... - Optional. Optional. Message for verbose mode.

Reads standard input

Any content

Writes to standard output

Same content

Examples

source "$include" > >(outputTrigger source "$include") || return $?

Return codes

  • 0 - If no content is read from stdin
  • 1 - If any content is read from stdin (and output to stdout)
  • 2 - Argument error

Simple debugger

bashDebug

Bash debugger

Usage

    bashDebug [ --help ] command ...

bashDebug: Simple debugger to walk through a program.

Debugger accepts the following keystrokes:

Flow control

  • . or or Return - Repeat last flow command

  • j - Skip next command (jump over)

  • s or n - Step to next command (step)
  • i or d - Step into next command (follow)
  • q - Quit debugger (and continue execution)
  • ! - Enter a command to execute
Watching
  • w - Enter a watch expression
  • u - Remove a watch expression
Utilities

k - Display call stack * - Add an interrupt handler to capture the stack upon interrupt (SIGINT, or Ctrl-C from a console) h or ? - This help

Location: bin/build/tools/debugger.sh

Arguments

  • commandToDebug ... - Callable. Required. Command to debug.
  • --help - Flag. Optional. Display this help.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

bashDebuggerDisable

Disable the debugger

Usage

bashDebuggerDisable [ --help ]

Disables the debugger immediately. Restores file descriptors 0 1 and 2 from 20, 21 and 22 respectively

Location: bin/build/tools/debugger.sh

Arguments

  • --help - Flag. Optional. Display this help.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

See Also

bashDebuggerEnable

Enable the debugger

Usage

bashDebuggerEnable [ --help ]

Enables the debugger immediately.

Saves file descriptors 0 1 and 2 as 20, 21 and 22 respectively

Location: bin/build/tools/debugger.sh

Arguments

  • --help - Flag. Optional. Display this help.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

See Also

Debugging Internal Tools

bashDebugInterruptFile

Output debugging stack on program termination

Usage

bashDebugInterruptFile [ --help ] [ --handler handler ] [ --error ] [ --clear ] [ --interrupt ] [ --already-error ]

Adds a trap to capture the debugging stack on interrupt. Use this in a bash script which runs forever or runs in an infinite loop to determine where the problem or loop exists. The file is named ./.interrupt.log and is appended each time the program is terminated or exits improperly.

Location: bin/build/tools/debug.sh

Arguments

  • --help - Flag. Optional. Display this help.
  • --handler handler - Function. Optional. Use this error handler instead of the default error handler.
  • --error - Flag. Add ERR trap.
  • --clear - Flag. Remove all traps.
  • --interrupt - Flag. Add INT trap.
  • --already-error - Flag. If the signals are already installed, then throw an error. Otherwise exits 0.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Requires

bashRecursionDebug

Recursion detection

Usage

bashRecursionDebug [ --end ]

Place this in code where you suspect an infinite loop occurs. It will fail upon a second call; to reset call with --end When called twice, fails on the second invocation and dumps a call stack to stderr.

Location: bin/build/tools/debug.sh

Arguments

  • --end - Flag. Optional. Stop testing for recursion.

Return codes

  • 91 - Recursion failure. Exits, actually after sleeping for 99 seconds.

Environment

  • __BUILD_RECURSION

Requires

🛠️ Tools · ⬅ Top