Skip to content

Debug Tools

⬅ Parent

Debugging

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

Known tags are:

FunctionAttributeList: BUILD_DEBUG

buildDebugEnabled

Is build debugging enabled?

Usage

buildDebugEnabled [ moduleName ]

Is build debugging enabled?

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

Return codes

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

Environment

  • BUILD_DEBUG - CommaDelimitedList. Constant for turning debugging on during build to find errors in the build scripts. Enable debugging globally in the build scripts. Set to a comma (,) delimited list string to enable specific debugging, or true for ALL debugging, false (or blank) for NO debugging.
  • 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 build debugging if it is enabled.

Usage

buildDebugStart [ moduleName ]

Start build 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: buildDebugStart || :

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 - Success
  • 1 - Environment error
  • 2 - Argument error

Environment

  • BUILD_DEBUG - CommaDelimitedList. Constant for turning debugging on during build to find errors in the build scripts. Enable debugging globally in the build scripts. Set to a comma (,) delimited list string to enable specific debugging, or true for ALL debugging, false (or blank) for NO debugging.

Requires

buildDebugEnabled

buildDebugStop

Stop build debugging if it is enabled

Usage

buildDebugStop [ --help ]

Stop build debugging if it is enabled

Arguments

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

Return codes

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

Requires

buildDebugEnabled

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.

Arguments

  • none

Return codes

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

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

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

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

Return codes

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

Requires

declare diff grep throwArgument decorate usageArgumentString isCallable fileTemporaryName removeFields

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

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

Reads standard input

Any content

Writes to standard output

Same content

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.

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

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

Arguments

  • commandToDebug - Callable. Required. Command to debug.

Return codes

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

Usage

bashDebuggerDisable [ --help ]

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

Arguments

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

Return codes

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

Usage

bashDebuggerEnable [ --help ]

Enables the debugger immediately Saves file descriptors 0 1 and 2 as 20, 21 and 22 respectively

Arguments

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

Return codes

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

Debug

bashDebugInterruptFile

Adds a trap to capture the debugging stack on interrupt

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.

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

trap

bashRecursionDebug

Place this in code where you suspect an infinite loop

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.

Arguments

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

Return codes

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

Environment

  • __BUILD_RECURSION

Requires

printf unset export debuggingStack exit