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?

Return Code: 1 - Debugging is not enabled (for any module) Return Code: 0 - Debugging is enabled

Arguments

  • moduleName - Optional. String. 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

  • 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.
  • 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 - Optional. String. 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

Stop build debugging if it is enabled

Arguments

  • none

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 ...

Run command and detect any global or local leaks

Arguments

  • none

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 [ --help ] [ --ignore grepPattern ] [ --path path ] [ path ... ] callable

Run a command and ensure files are not modified

Arguments

  • --path path - Optional. Directory. One or more directories to watch. If no directories are supplied uses current working directory.

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 ]

Check output for content and trigger environment error if found Usage outputTrigger [ --help ] [ --verbose ] [ --name name ]

Arguments

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

Examples

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

Return codes

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

Simple debugger

bashDebug

Simple debugger to walk through a program

Usage

bashDebug commandToDebug ...

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

Arguments

  • commandToDebug - Callable. Required. Command to debug.

Return codes

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

bashDebuggerDisable

Disables the debugger immediately

Usage

bashDebuggerDisable

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

Arguments

  • none

Return codes

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

bashDebuggerEnable

Enables the debugger immediately

Usage

bashDebuggerEnable

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

Arguments

  • none

Return codes

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