bg-debugCntr

#!/bin/bash


# (done) TODO: when bootstrapping on fresh VM, sourcing this is the fisrt step but between that and vinstalling bg-core/bg-dev, these functions
#       can not find the rest of the libs. Add logic to automatically vininstall bg-core and bg-dev based on the path being sourced
# TODO: when bootstrapping on fresh VM, check the <sanbbox>/.bglocal/hostManifest to see if the paths are valid and make a <sanbbox>/.bglocal/hostManifest.$$
#       with fixed up paths
# (done) TODO: when bootstrapping on fresh VM, check and install minum dependencies (binutils, ...)

# CRITICALTODO: see below
# SECURITY: consider how we can discourage use of bg-debugCntr on production servers -- provide an alternative that only controlls tracing -- put similar code here as in bg_core.sh to detect mode and hide/disable fetures based on that. Of course a user can do want they want with their environment but we can avoid facilitating a insecure practice
#           maybe this means that bg-debugCntr and Makefile both should only be in bg-scriptprojectdev -- maybe a stripped done bg-traceCntr should be in bg-lib
#           see also function bgListAllInstalledCodeFiles() -- whow it finds Makefile

# Command
# usage: bg-debugCntr [status]
# usage: bg-debugCntr trace [ on[:fileName] | off | status ]
#        bg-debugCntr trace bashCompOpts:(verbose | terse | cachingOff | cachingOn)
#        bg-debugCntr trace tests:(on | off)
#        bg-debugCntr trace errorStack [showSource|no-showSource|oneline|no-oneline|debugStack|no-debugStack|callerColumn|no-callerColumn]
# usage: bg-debugCntr vinstall [reinstall]
#        bg-debugCntr vinstall [-v] status
#        bg-debugCntr vinstall [-r] [\<sandboxPath>|\<projectPath>]
#        bg-debugCntr vinstall sourceCore
#        bg-debugCntr vinstall --remove [-r] all|\<sandboxPath>|\<projectPath>
#        bg-debugCntr vinstall devBash <pathToBash>
# usage: bg-debugCntr debugger [status]
#        bg-debugCntr debugger cntr-C:(on|off)
#        bg-debugCntr debugger stopOnAssert:(on|off)
#        bg-debugCntr debugger destination <dbgDriver>:<destination>
#        bgdb [--breakAt=stopOnLibInit|stopOnFirstScriptLine] <cmd> [<arg1>..<argN>]
# usage: bg-debugCntr utils name <termName>
#        bg-debugCntr utils termIdent
#        bg-debugCntr utils banner [status | on | off]
#        bg-debugCntr utils bashCmdHooks [status]
#        bg-debugCntr utils bashCmdHooks on | off
#        bg-debugCntr utils bashCmdHooks trace [status]
#        bg-debugCntr utils bashCmdHooks trace on | off
#        bg-debugCntr utils installDevCapsForUser
# usage: bg-debugCntr listCodeFiles
# usage: bg-debugCntr codeGrep
# usage: bg-debugCntr tags
# control debugging features of script commands.
# The bg-debugCntr command controls the development environment for script projects in a terminal. Typically to start devolomnet
# you open a terminal, cd to the project or sandbox project that conatins scripts that you want to develop and source this command
# into the terminal's bash process.
#    ~/github/bg-core$ . bg-debugCntr
#    BGTracing status     : disabled
#    VIinstall Status     : none
#    Banner Status        : on
#    Debugger Status      : off
#      BashCmdHooks Status: on
#    HostProductionMode   : development
#    Development Features: installed
#    ~/github/bg-core$
#
# You can then virtually install the project so that you can run its commands without building a package and installing it for real.
#    ~/github/bg-core$ bg-debugCntr vinstall .
#    virtually installed 565 assets from bg-core
#    ~/github/bg-core$
#
# Its handy to turn on tracing to another terminal. I divide the left side of my monitor between a terminal showing the trace output
# on the top half and one on the bottom half configured with bg-debugCntr
#    ~/github/bg-core$ bg-debugCntr trace on:
#    BGTracing status     : desination='/tmp/bgtrace.out' (bgTracingOn='on:')
#    ~/github/bg-core$
# Note the : at the end of on:. That tells the command that a file will follow which will be the destination of the trace output
# produced at this terminal but since its empty, its using the default at /tmp/bgtrace.out
#
# Then in another terminal window tail -f that file
#    ~/github/bg-core$ tail -f /tmp/bgtrace.out
#
# Sub Commands:
# The some sub commands have separate man pages. See the See Also section below.
#
# **listCodeFiles** : lists the assets from the current virtually installed projects.
#
# **codeGrep** : grep the set of virtually installed assets
#
# **tags** : show the code tags (e.g. TODO: ...) in the set of virtually installed assets
#
# See Also:
#    man(1) bg-debugCntr-debugger
#    man(1) bg-debugCntr-vinstall
#    man(1) bg-debugCntr-trace
#    man(1) bg-debugCntr-utils






# man(1.bashCmd) bg-debugCntr-utils
# usage: bg-debugCntr utils name <termName>
#        bg-debugCntr utils termIdent
#        bg-debugCntr utils banner [status | on | off]
#        bg-debugCntr utils bashCmdHooks [status]
#        bg-debugCntr utils bashCmdHooks on | off
#        bg-debugCntr utils bashCmdHooks trace [status]
#        bg-debugCntr utils bashCmdHooks trace on | off
#        bg-debugCntr utils installDevCapsForUser
# Miscellaneous sub commands in bg-debugCntr.
#
# name:
# Set the name that will be displayed in the title bar or tab for this terminal.
#
# termIdent:
# This will send commands to all of the tty on the host to set their terminal titles to show their process ID and tty.
# It also prints a ps command that show all of the bash processes currently running.
#
# The idea of this utility is that it allows you to find out which termianl window is running which bash process. For example if
# a terminal's bash process is locked and not responding to cntr-c, this will help you figure out which PID to kill.
#
# banner:
# When bg-debugCntr is installed in a terminal, each srcipt that uses oob_invokeOutOfBandSystem will write a banner line at its
# start summarizing its configuration to remind you that you that you are running cmds in a development mode. This sub command
# can be used to turn that off.
#
# bashCmdHooks:
# When bg-debugCntr is installed in a terminal, it uses a DEBUG trap and prompt commands to monitor commands entered on the cmdline.
# This can be used to disable or configure that feature.
#     * autoload imported script libraries when they are modified. (see bg-debugCntr vinstall sourceCore )
#     * When testing [[ =~ ]] regex, the BASH_REMATCH var is copied into rematch where is wont be clobbered
#
# installDevCapsForUser:
# In order to run vinstalled commands as root, the user working on the package must be given the sudo rights to run sudo with the -E
# option which preserves the unprivileged user's environment. This is needed so that the vinstalled PATH will be used for the root
# session so that it will find the vinstalled versions of commands.  This would be a security violation on a production server but
# on a developer's host where the developer already has super user privilege, it is OK.
#
# See Also:
#    man(1) bg-debugCntr
#
declare -x bgVinstallInhibitPostProcessing

# This script implements a pattern where it can be installed into the user's bash session by sourcing
# it directly into the interactive bash shell. Once installed, a function by the same name will be
# defined so that when this command's name is ran in the interactive prompt or in a script, the
# sourced function version will be executed instead of the disk file.

# bgDebugCntrRunMode is maintained to let global code in this file know the context that its being ran
# its undefined at the end of the script so that when sourced functions run normally it will not be
# defined. [ ! "${bgDebugCntrRunMode+exits}" ] && echo "sourced function running"
# This is implemented as a function because bash 5.x no longer sets FUNCNAME[0] to 'main' or 'source'
# in the global scope
declare bgDebugCntrRunMode=""
function _getGlobalBashScope()
{
	case "PRE.${FUNCNAME[@]: -1}" in
		PRE.main|PRE.)             bgDebugCntrRunMode="extScript" ;;
		PRE.source)                bgDebugCntrRunMode="sourcing" ;;
		PRE.debugCntr)             bgDebugCntrRunMode="reloading" ;;
		PRE.bg-debugCntr)          bgDebugCntrRunMode="reloading" ;;
		PRE.cmdlineHook_debugTrap) bgDebugCntrRunMode="reloading" ;;
		PRE.cmdlineHook_promtCmdHook) bgDebugCntrRunMode="reloading" ;;
		*)                bgDebugCntrRunMode="unknown:${FUNCNAME[@]: -1}"; echo "error: bg-debugCntr:_getGlobalBashScope() the reported top level bash FUNCNAME ($bgDebugCntrRunMode) is not recognized so we do not know the context that this script is running." >&2 ;;
	esac
}
_getGlobalBashScope


#################################################################################################################################
# Entry Point Functions
# These functions are meant to be invoked directly by the user. They typically exist as an external
# command script but when they are sourced, these functions override the invocation of those scripts.


# FUNCMAN_SKIP
# this sets the user's bgtrace environment variable that effects scripts run in the current bash session
# This function has the same name as the external script. After the user sources the script into their
# bash terminal environment, subsequent invocations will be handled by the script and not the external
# file unless the full path to the external file is specified
function bg-debugCntr()
{
	# disable the DEBUG trap handler while we are in this function
	builtin trap - DEBUG

	if [ "development" != "$([ ! -f /etc/bgHostProductionMode ] || awk '/^[[:space:]]*mode[[:space:]]*[:=][[:space:]]*development/ {print "development"; exit}' /etc/bgHostProductionMode)" ]; then
		cat - <<-EOS

			This host is not yet authorized to run bg-core development features.
			If you have admin privileges on this host you can authorize it by
			executing this cmd...
			    echo "mode=development" | sudo tee /etc/bgHostProductionMode >/dev/null

		EOS
		return 1
	fi


	local verboseFlag
	while [ $# -gt 0 ]; do case $1 in
		-v) verboseFlag="-v" ;;
		-hbOOBCompGen|-hb|-hbo) break ;;
		*)  break; esac; shift; # simplified version of bgOptionsEndLoop
	done

	local bgCoreAvail=""; (source /usr/lib/bg_core.sh 2>/dev/null) && bgCoreAvail="yes"

	local cmd="${1:-status}"; shift
	local cmd2="${1:-status}"
	case $cmd:$cmd2 in
		sourceCore:*|vinstall:sourceCore)
			source /usr/lib/bg_core.sh $2; importCntr reloadAll --init
			unset -f command_not_found_handle
			bg-debugCntr utils name "inside"
			;;
		trace:*)       _traceCntr  "$@" ;;
		vinstall:*)    _vinstall   "$@" ;;
		vuninstall:*)  _vuninstall "$@" ;;
		codeGrep:*)    _codeGrep   "$@" ;;
		tags:*)        _tagsGrep   "$@" ;;
		debugger:*)    _debugger   "$@" ;;
		listCodeFiles:*) (
			bgTracingBanner=""
			source /usr/lib/bg_core.sh --minimal
			bgListAllInstalledCodeFiles
		) ;;
		utils:banner) _bannerCntr "${@:2}" ;;
		utils:name)
			declare -g bgTermName="$2"
			declare -g bgTermTitle="$bgTermName($bgTermID)"
			PS1="${PS1#*\\a}"
			(source /usr/lib/bg_core.sh || exit 1; import bg_cui.sh; $L1;$L2; cuiSetTitle "$bgTermTitle" >/dev/tty)
			;;
		utils:termIdent)
			local -A pidsByTty
			local pid tty pids; while read -r pid tty; do
				pidsByTty[${tty:-notty}]+="${pidsByTty[${tty:-notty}]:+,}$pid"
				pids+=("$pid")
			done < <(ps  -C bash  -o pid=,tty=)
			for tty in "${!pidsByTty[@]}"; do
				[ -e "/dev/$tty" ] && echo -en "\e]0;Temp Ident: pid= ${pidsByTty[$tty]} tty= /dev/$tty\a" > /dev/$tty
			done

			echo "the titles of these bash terminal windows owned by you have temporarily been changed to identify their pid and tty"
			ps -f --forest --pid "${pids[@]}"
			;;
		utils:bashCmdHooks) _bashComandHooks "${@:2}" ;;
		utils:installDevCapsForUser) _installDevCapsForUser "${@:2}" ;;

		-hb:*|-hbOOBCompGen:*|-hbo:*)    _bg-debugCntrBC "$@" ;;
		-h:*) man bg-debugCntr ;;
		status:*)
			while [ $# -gt 0 ]; do case $1 in
				-v) verboseFlag="-v" ;;
				*)  break; esac; shift; # simplified version of bgOptionsEndLoop
			done
			[ ! "$bgHostProductionMode" ] && bgHostProductionMode="$(source /usr/lib/bg_core.sh --queryMode; echo $bgHostProductionMode)"
			if [ "$	bgHostProductionMode" == "production" ]; then
				cat <<-EOS
				 	This host is currently in production mode and therefore development features will not work with any installed
				 	scripts. If you have admin privilege on this host you can put it in development mode by creating the file
				 	/etc/bgHostProductionMode with the contents 'mode=development'
				EOS

			else
				_traceCntr  status $verboseFlag
				_vinstall   status $verboseFlag
				_bannerCntr status $verboseFlag
				_debugger   status $verboseFlag
				_bashComandHooks status $verboseFlag
				_installDevCapsForUser status $verboseFlag
				echo "HostProductionMode   : $bgHostProductionMode"

				# If we are running as the external script as opposed to the sourced function, dev features are not installed
				if [ "$bgDebugCntrRunMode" == ""extScript"" ]; then
					cat <<-EOS
					Development Features: off
					 	Development and Debugging features are not currently installed in this terminal but you can install them by
					 	sourceing this command instead of running it. This only has to be done once per terminal and then you can
					 	and should run this command without the 'source' prefix.
					 	Run the following command to install development and debugging features.

					 		   source $(basename $0)
					EOS
				elif [ "$bgCoreAvail" ]; then
					(
						source /usr/lib/bg_core.sh
						echo "Development Features: installed"
						echo "Manifest file        : $(manifestGetHostManifest)"
						echo "Plugin Manifest file : $(manifestGetHostPluginManifest)"
					)
				else
					echo "Development Features: installed"
					echo
					echo "bg-core is not installed on the host. You should either install it or use the 'vinstall' sub command to virtually install a source folder of the bg-core project"
				fi

				echo
			fi
			;;
		*) _assertError "unknown sub command '$cmd' '$cmd2'" ;;
	esac

	# if this feature is turned on, re-enable the DEBUG trap handler
	if [ "$bgBashCmdHookFeature" ]; then
		set +T
		builtin trap 'cmdlineHook_debugTrap' DEBUG
	fi
}
export -f bg-debugCntr

complete -F _bgbc-complete-viaCmdDelegation bg-debugCntr
# This is the bash command line completion function for the bg-debugCntr entry point
function _bg-debugCntrBC()
(
	# note that this function uses () instead of {} so that we can source bg_core.sh without it
	# being permanent
	local bgTracingBanner=""
	source /usr/lib/bg_core.sh --minimal
	import bg_outOfBandScriptFeatures.sh ;$L1;$L2


	local words cword cur prev optWords posWords posCwords
	parseForBashCompletion --compat2 words cword cur prev optWords posWords posCwords "$@"

	local cmd1="${posWords[1]}"

	case $cmd1:$posCwords in
		*:1) echo "trace vinstall status codeGrep listCodeFiles tags debugger utils" ;;

		trace:*)
			local cmd2="${posWords[2]}"
			local colonCount="${cmd2//[^:]}"
			case ${cmd2%:*}:$posCwords:${#colonCount} in
				*:2:0) echo "status off on:%3A bashCompOpts:%3A errorStack openWin closeWin tests:%3A	" ;;
				on:2:1)
					echo "\$(cur:${cmd2#on:})"
					echo "1 2 tty stderr stdout file: winNew win"
					ls /tmp/bgtrace.win?.cntr 2>/dev/null | sed  's|/tmp/bgtrace[.]||; s|[.]cntr||'
					;;
				on:2:file:*)
					echo "\$(cur:${cmd2#on:file:})"
					echo "\$(_fileDir)"
					;;
				bashCompOpts:2:*)
					echo "\$(cur:${cmd2#bashCompOpts:})"
					echo "verbose terse cachingOff cachingOn"
					;;
				tests:2:*)
					echo "\$(cur:${cmd2#tests:})"
					echo "on off"
					;;
				errorStack:3:*) echo "showSource no-showSource oneline no-oneline debugStack no-debugStack callerColumn no-callerColumn" ;;
			esac
			;;

		utils:2)  echo "termIdent banner bashCmdHooks installDevCapsForUser name" ;;
		utils:*)
			utilCmd="${posWords[2]}"
			case $utilCmd:$((posCwords-2)) in
				name:1)   echo "<name>" ;;
				banner:1) echo "status on off" ;;
				bashCmdHooks:*)
					case ${posWords[3]}:${posWords[4]}:$((posCwords-2)) in
						*:*:1) echo "on off status trace" ;;

						trace:*:2) echo "on off status" ;;
						trace:on:*) echo "\$(usingListmode ,) b4Cmdline b4SimpleCmd afterSimpleCmd afterCmdline" ;;
					esac
					;;
			esac
			;;
		vinstall:2) echo "status --remove sourceCore devBash" ;;&
		vinstall:*)
			if [ "${posWords[2]}" == "--remove" ]; then
				[ ${posCwords:-0} -eq 3 ] && echo "status all"
				echo "<vInstalledProjects>"
				echo "$bgVinstalledPaths:" | tr ":" "\n" | sed -e 's|.*/|   |'
				return
			fi

			if [ "${posWords[2]}" == "devBash" ]; then
				echo "\$(doDirs) <pathToBashExec>"
				return
			fi

			if [ "$cur" ] && [[ ! "status" =~ ^$cur ]]; then
				 echo "\$(doDirs) reinstall"
			 else
			 	find -H * -name node_modules -prune -false -o -path "*.bg-sp/config" | sed 's|/.bg-sp/config||'
				 echo "<projectFolders> reinstall"
			fi
			;;
		vuninstall:2) echo "all status" ;;&
		vuninstall:*)
			echo "<vInstalledProjects>"
			echo "$bgVinstalledPaths:" | tr ":" "\n" | sed -e 's|.*/|   |'
			;;
		codeGrep:*)
			case $prev in
				-f) echo "<filterOnAssetTypes> $(bg-awkData -g manifest.assetType)"; return ;;
				-A) echo "<number_lines_after> 1 2 3"; return ;;
				-B) echo "<number_lines_before> 1 2 3"; return ;;
				-C) echo "<linesType> onlyComments codeOnly tagsOnly"; return ;;
				-O) echo "<output_mode> summary matchingFiles"; return ;;
				-T) echo "<TAG> CRITICALTODO TODO SECURITY DEPRECIATED UPDATE BGENV OBSOLETE NOTE AWKLIB DOMCONFIG"; return ;;
			esac
			[ $posCwords -eq 2 ] || [[ "$prev" =~ ^- ]] && echo "-C -A -B -O -T -t -l -i -f -F <regexSearchExpr>"
			;;
		tags:2)
			echo "<TAG> CRITICALTODO TODO SECURITY DEPRECIATED UPDATE BGENV OBSOLETE NOTE AWKLIB DOMCONFIG"
			;;

		debugger:2)
			if [[ ! "$cur" =~ : ]]; then
				echo "status destination cntr-C:%3A stopOnAssert:%3A"
			elif [[  "$cur" =~ ^cntr-C: ]]; then
				echo "\$(cur:${cur#cntr-C:}) on off"
			elif [[  "$cur" =~ ^stopOnAssert: ]]; then
				echo "\$(cur:${cur#stopOnAssert:}) on off"
			fi
			;;
		debugger:*)
			case ${posWords[2]}:$((posCwords-2)) in
				destination:1)
					if [[ ! "$cur" =~ : ]]; then
						echo "integrated:%3A remote:%3A atom:%3A <dbgDriver>"
					else
						dbgDriver="${cur%%:*}"
						cur="${cur#*:}"
						echo "\$(cur:$cur)"
						case $dbgDriver in
							integrated) echo "<ttyDev> self cuiWin /dev/pts/" ;;
							remote) echo "<remoteDbgInstancePipe> cuiWin >" ;;
							atom)
								echo "<atomInstanceRunningPlugin> "
								local codeEnvironment="${bgVinstalledSandbox##*/}"
								ls /tmp/bgAtomDebugger-$USER/${codeEnvironment}-toAtom 2>/dev/null | gawk -v USER="$USER" '{
									print gensub("^/tmp/bgAtomDebugger-"USER"/|-toAtom$","","g")
								}'
								;;
						esac
					fi
					;;
				on:1)  echo "<startingPoint> stopOnLibInit stopOnFirstScriptLine " ;;
			esac
			;;
	esac
	exit
)
export -f _bg-debugCntrBC




#################################################################################################################################
# Sub Command Functions
# these implement the various sub commands of bg-debugCntr


# man(1.bashCmd) bg-debugCntr-trace
# usage: bg-debugCntr trace [ on[:<filename>] | off | status ]
#        bg-debugCntr trace bashCompOpts:(verbose | terse | cachingOff | cachingOn)
#        bg-debugCntr trace tests:(on | off)
# this configures attributes of the bgtracing system for scripts ran in the same terminal.
# Sub Commands:
#    on[:[<filename>]]  : send tracing output produced in this terminal to the specified destination file
#       on         : send output to stderr
#       on:        : send output to /tmp/bgtrace.out (the default <filename> if none is given)
#       on:<filename> : <filename> can be and file that the user has permission to write to
#       on:win[:winID] : send output to a cuiWin. The default cuiWinID is 'out' which makes it shared with any other terminal
#          configured the same way. Use on:win:$$ to make a cuiWin termianl open that is unique and persistent to the specific
#          terminal
#       on:tty     : send output to /dev/tty
#       on:stderr  : send output to stderr
#    off   : disable bgtrace output from this terminal. bgtrace* statements in the scrip will be ignored.
#    status : print the current configuration
#    bashCompOpts  : configure how the _bgbc-complete-viaCmdDelegation produces bgtrace output. terse and cachingOn is the default.
#        When debugging the oob_printBashCompletion function in a script command, tracing is particularely convenient. The bgtrace
#        output from _bgbc-complete-viaCmdDelegation show how the output of oob_printBashCompletion is interpreted.
#    tests   : by default, when .ut scripts are ran, bgtracing is disabled because testcases often throw exceptions which cause
#        stack traces to be sent to the trace file. This can be used to override that so that you can see traces from .ut scripts.
# See Also:
#    man(7) bg_unitTest.sh
function _traceCntr()
{
	local quietFlag
	while [ $# -gt 0 ]; do case $1 in
		-q)   quietFlag="-q" ;;
		*)  break; esac; shift; # simplified version of bgOptionsEndLoop
	done

	local cmd="${1:-status}"; shift
	case $cmd in
		on*) assertBgDebugEnvironmentIsActive
			[ "$bgTracingOn" ] && _traceCntr -q off
			if [[ "$cmd" =~ ^on:win ]]; then
				_traceCntr openWin "${cmd#on:}"
			else
				# this condition is meant to be true when we are running in a headless VM. The assumption is that the bgVinstalledSandbox
				# is shared with the host OS so the developer can tail the bgtrace.out file from there
				if [ ! "$DISPLAY" ] && [ "$cmd" == "on:" ] && [ "$bgVinstalledSandbox" ]; then
					export bgTracingOn="on:$bgVinstalledSandbox/.bglocal/bgtrace.out.${HOSTNAME#bgcore-}"
				fi
				export bgTracingOn="$cmd"
			fi
			# 2022-08 bobg: commented out turning on extdebug. I think that was put in before sourcing bg_core turned it on
			# shopt -s extdebug
			[ ! "$quietFlag" ] && _traceCntr status
			;;
		off) assertBgDebugEnvironmentIsActive
			if [[ "$bgTracingOn" =~ ^on:win[0-9] ]]; then
				_traceCntr closeWin "${bgTracingOn#on:}"
			fi
			# 2022-08 bobg: commented out turning on extdebug. I think that was put in before sourcing bg_core turned it on
			#shopt -u extdebug
			export bgTracingOn=""
			unset bgTracingOn
			[ ! "$quietFlag" ] && _traceCntr status
			;;
		status)
			# if the user sets bgTracingOn directly to winNew, then we need to call this outside the ()
			[[ "$bgTracingOn" =~ ^(on:)?(winNew)$ ]] && _traceCntr openWin "${bgTracingOn#on:}"

			if [ "$bgCoreAvail" ]; then
				(
					bgTracingBanner=""
					source /usr/lib/bg_core.sh --minimal

					if ! bgtraceIsActive; then
						echo "BGTracing status     : disabled"
					elif touch $_bgtraceFile 2>/dev/null; then
						echo "BGTracing status     : desination='$_bgtraceFile'"
					else
						echo "BGTracing status     : desination='$_bgtraceFile' error: '$_bgtraceFile' is not writable"
					fi
					if [ "$bgErrorStack" ]; then
						echo "   stack trace options : '$bgErrorStack'"
					fi
				)
			else
				echo "BGTracing status     : ${bgTracingOn:-off}"

			fi
			;;
		bashCompOpts:*)
			declare -gA _bgbcData
			local option="${cmd#bashCompOpts:}"
			case $option in
				cachingOff) _bgbcData[noCache]="1" ;;
				cachingOn)  _bgbcData[noCache]="" ;;
				verbose)
					assertBgDebugEnvironmentIsActive
					_bgbcData[tracingDetail]="verbose"
					_bgbcData[noCache]="1"
					! type -t bgtraceVars &>/dev/null && echo -e \
						"\n\twarning: in order to see the full verbose output for completion, you need to 'source /usr/lib/bg_core.sh' in this terminal\n"
					;;
				terse)
					assertBgDebugEnvironmentIsActive
					_bgbcData[tracingDetail]=""
					_bgbcData[noCache]=""
					;;
				*) _assertError "unknown option '$option'"
			esac
			;;
		tests:*)
			local subCmd="${cmd#tests:}"
			case $subCmd in
				on)  declare -gx bgTracingTestRunner=on ;;
				off) declare -gx bgTracingTestRunner= ;;
			esac
			;;
		errorStack)
			local subCmd="$1"
			case $subCmd in
				showSource)     export bgErrorStack="${bgErrorStack/--source} --source" ;;
				no-showSource)  export bgErrorStack="${bgErrorStack/--source}" ;;

				oneline)        export bgErrorStack="${bgErrorStack/--oneline} --oneline" ;;
				no-oneline)     export bgErrorStack="${bgErrorStack/--oneline}" ;;

				debugStack)     export bgErrorStack="${bgErrorStack/--stackDebug} --stackDebug" ;;
				no-debugStack)  export bgErrorStack="${bgErrorStack/--stackDebug}" ;;

				callerColumn)    export bgErrorStack="${bgErrorStack/--no-callerColumn}" ;;
				no-callerColumn) export bgErrorStack="${bgErrorStack/--no-callerColumn} --no-callerColumn" ;;
			esac
			;;
		openWin)
			local win winTraceFile
			case ${1:-winNew} in
				win[0-9]) win="$1"  ;;
				win)      win="out" ;;
				winNew)
					local i; for ((i=0; i<10; i++)); do
						[ ! -e ${cuiWinCntrFilePrefix}$win.cntr ] && { win="win$i"; break; }
					done
					[ ! "$win" ] && _assertError "
						no available win communication pipes were found. looking for one of these that do not yet exist -- '/tmp/bgtrace.win{0..9}.cntr'
					"
					;;
				*) _assertError "invalid bgtrace window identifier. Expecting win[0-9]|winNew|win but got '$1'" ;;
			esac
			winTraceFile="/tmp/bgtrace.$win"
			touch "$winTraceFile" || _assertError "file '$winTraceFile' can not be used as a trace file because it is not writable"
			[ "$win" ] && [ "$winTraceFile" ] && (
				source /usr/lib/bg_core.sh
				import bg_cuiWin.sh ;$L1;$L2
				local tty; cuiWinCntr -R tty "$win" open || assertError -v win "failed to open cuiWin '$win'"
				cuiWinCntr "$win" tailFile "$winTraceFile" || assertError -v win -v winTraceFile "failed to tail '$winTraceFile' in cuiWin '$win'"
			) && declare -gx bgTracingOn="on:${win/%out/win}"
			;;
		closeWin)
			local win="$1"
			[ "$win" ] && (
				source /usr/lib/bg_core.sh
				import bg_cuiWin.sh ;$L1;$L2
				cuiWinCntr "$win" close || assertError -v win "failed to close cuiWin '$win'"
			)
			;;
		*) _assertError "unknown command '$cmd'"
	esac
}
export -f _traceCntr


# usage: _traceCntr [ on[:fileName] | off | status ]
# this sets the user's bgtrace environment variable that effects scripts run in the current bash session
function _bannerCntr()
{
	local cmd="${1:-status}"
	case $cmd in
		on) assertBgDebugEnvironmentIsActive
			export bgTracingBanner="on"
			_bannerCntr status
			;;
		off)assertBgDebugEnvironmentIsActive
			export bgTracingBanner=""
			unset bgTracingBanner
			_bannerCntr status
			;;
		status)
			if [ "$bgTracingBanner" ]; then
				echo "Banner Status        : on"
			else
				echo "Banner Status        : off"
			fi
			;;
		*) _assertError "unknown banner command cmd='$cmd'"
	esac
}
export -f _bannerCntr


# usage: _vinstallStatus
function _vinstallStatus()
{
	local verboseFlag
	while [ $# -gt 0 ]; do case $1 in
		-v) verboseFlag="-v" ;;
		*)  break; esac; shift; # simplified version of bgOptionsEndLoop
	done
	if [ "$bgVinstalledPaths" ]; then
		echo "VIinstall Status     : ${bgVinstalledSandbox:-one or more projects are vinstalled. use -v to enumerate them}"
		if [ "$verboseFlag" ]; then
			echo "   affected environment vars: PATH, MANPATH, AWKPATH, bgLibPath and bgDataPath"
			echo "   vinstalled projects: "
			echo "$bgVinstalledPaths:" | tr ":" "\n" | sed -e 's/./      &/; /^[[:space:]]*$/d'
		fi

	else
		echo "VIinstall Status     : none"
	fi
}
export -f _vinstallStatus

# usage: _vinstallMakePathList -R <foldersVar> -S <sandboxFolderVar> [-r] [<path> [..<pathN>]]
# This processes the path arguments for the _vinstall and _vuninstall functions to create the expanded project folder list and
# the sandbox path if one is specified
# Params:
#    <pathN> : 0 or more paths of sandbox or package projects that will be acted on
# Options:
#    -R <foldersVar> : an array var to return the expanded project folder list
#    -S <sandboxFolderVar> : a variable that will return the sandbox root folder if one is specified.
#    -r : if a folder is neither a sandbox nor package project, this will determine if the path will be descended to find child
#         project folders
#    -e : (expand). expand each project folder and sandbox folder into its full, absolute path. vinstall wants this but vuninstall does not.
function _vinstallMakePathList()
{
	local recurse verboseFlag path foldersVar sandboxFolderVar expandFlag
	while [ $# -gt 0 ]; do case $1 in
		-v)   verboseFlag="-v" ;;
		-r)   recurse="-r" ;;
		-e)   expandFlag="-e" ;;
		-R)   foldersVar="$2"; shift ;;
		-S)   sandboxFolderVar="$2"; shift ;;
		*)  break;
	esac; shift; done

	# expand the list of folders to be installed taking into account the types of folders they are
	# -r only effects folders that do not have a .bg-sp/config file
	while [ $# -gt 0 ]; do
		path="$1"; shift
		[ -d "$path" ] || _assertError "error: '$path' is not a folder path" || continue
		[ "$expandFlag" ] &&  path=$(cd  ${path:-.}; pwd)

		# get pathType for this folder using -r option to determine unknown types
		pathType="$(gawk -F= '$1=="projectType" {print $2}' $path/.bg-sp/config 2>/dev/null)"
		[ ! "$pathType" ] && [ -f "$path/.bg-sp/config" ] && pathType="package" # if .bg-sp/config exists the default projectType is 'package'

		case ${pathType:-notOurs} in
			sandbox)
				[ "${!sandboxFolderVar}" ] && _assertError "Only one sandbox folder can be vinstalled in any given terminal window."
				[ "$sandboxFolderVar" ] && printf -v "$sandboxFolderVar" "%s" "$path"
				local folderValue; for folderValue in $(ls -d  ${path%/}/*/.bg-sp/ 2>/dev/null); do
					folderValue="${folderValue%/.bg-sp*}"
					local folderType="$(gawk -F= '$1=="projectType" {print $2}' $folderValue/.bg-sp/config 2>/dev/null)"
					[ "$folderType" == "package" ] && [ "$foldersVar" ] && eval $foldersVar'+=("$folderValue")'
				done
				;;
			package)
				[ "$foldersVar" ] && eval $foldersVar'+=("$path")'
				;;
			notOurs)
				# find all subfolders that have a .bg-sp/config and if the projectType is 'package', add it. Do not consider below node_modules
				if [ "$recurse" ]; then
					local folderValue; for folderValue in $(find -L "${path}"  -name node_modules -prune -false -o  -path "*/.bg-sp/config"); do
						folderValue="${folderValue%/.bg-sp*}"
						local folderType="$(gawk -F= '$1=="projectType" {print $2}' $folderValue/.bg-sp/config 2>/dev/null)"
						[ "$folderType" == "package" ] && [ "$foldersVar" ] && eval $foldersVar'+=("$folderValue")'
					done
				fi
				;;
		esac
	done
}
export -f _vinstallMakePathList

# man(1.bashCmd) bg-debugCntr-vinstall
# usage: bg-debugCntr vinstall [reinstall]
#        bg-debugCntr vinstall [-v] status
#        bg-debugCntr vinstall [-r] [<sandboxPath>|<projectPath>]
#        bg-debugCntr vinstall sourceCore
#        bg-debugCntr vinstall --remove [-r] all|<sandboxPath>|<projectPath>
#        bg-debugCntr vinstall devBash <pathToBash>
# virtually install a project folder or set of project folders from a sandbox project.
# Virtual installation adjusts the PATH and other environment of the terminal (bash process) where its ran so that the assets
# contained in the project(s) are active when executed from that terminal. It does not affect other terminals.
#
# The main feature of vinstall is that commands located in the project root or its "./bin" folders can be launched from any CWD/PWD
# folder the terminal is currently in and any libraries that the command uses will be loaded from vinstalled projects before
# any actually installed libraries of the same name. The import syntax provided by bg_core.sh works with vinstalled folders.
# bash completion works for vinstalled commands including newly added commands to the project.
#
# Other asset types contained in projects managed by bg-dev cooperate with vinstall to make them work similar to being installed
# whereever possible.  If you have custom install hooks in a project those can not be tested by vinstalling the project.
#
# In general a project only needs to be vinstalled once at the start of working on a project in a terminal but you can re-vinstall
# projects as needed. Each time vinstall is ran, funcman will update all the generated manpages from the sources in the project.
# There may be other features that get updated when vinstall is ran.
#
# Hooks:
# If your project has special assets that are not yet covered by vinstall, you can add hooks in your project that get invoked in
# the terminal's process space when vinstall or vuninstall is called on your project. The hooks can modify environment variables
# or take other actions. The hook scripts are placed in the ./.bg-sp/ folder as .bg-sp/onVInstall and .bg-sp/onVUninstall
#
# sourceCore:
# This sub command is a convenient shortcut for typing `source /usr/lib/bg_core.sh` in your terminal. Source the core libraries
# makes the terminal work like the inside of a script that sources bg_core.sh. You have access to all the core bash functions.
# While developing scripts, its convenient to copy and paste command into the terminal to test them as you write the script.
#
# devBash:
# This sub command allows you to specify an alternate bash executable to use instead of the system installed bash. This could be
# to test a different bash version or it could be a bash built for debugging.
#
# Options:
#   --quick  : skip the maintentance of the manifest and plugin registries
#   -v       : be more verbose
#   --remove): uninstall the projects listed on the command line
# See Also:
#    man(1) bg-dev
#    man(1) bg-debugCntr
function _vinstall()
{
	local recurse verboseFlag quickFlag
	while [ $# -gt 0 ]; do case $1 in
		-v)   verboseFlag="-v" ;;
		-r)   recurse="-r" ;;
		--quick) quickFlag="--quick" ;;
		--remove)
			shift
			_vuninstall "$@"
			return
			;;
		*)  break;
	esac; shift; done

	if [ "$1" == "status" ]; then
		shift
		_vinstallStatus $verboseFlag "$@"
		return
	elif [ "$1" == "devBash" ]; then
		local devPath
		if [ -f "$2" ]; then
			devPath="${2%/*}"
		elif [ -f "${2}/bash" ]; then
			devPath="${2}"
		fi
		echo "executing the bash found at devPath='$devPath'"
		if [ ! "$devPath" ]; then
			_assertError "the path to the alternate bash executable file is a required argument"
		fi
		devPath="$(cd  ${devPath:-.}; pwd)"
		[[ ! ":${PATH}:" =~ :$devPath: ]] && export PATH="$devPath:$PATH"
		export bgBashPath="${devPath}/bash"
		echo "bgBashPath='$bgBashPath'"
		bash
		return 0
	fi

	assertBgDebugEnvironmentIsActive

	local gdeps folders folder addedFlag sandboxFromFolderList

	# default is to reinstall the projects that are already vinstalled
	# this block populates folders.
	if [ $# -eq 0 ] || [ "${1:-reinstall}" == "reinstall" ]; then
		if [ ! "$bgVinstalledPaths" ]; then
			echo "there are no vinstalled projects in this terminal"
			return
		fi
		echo "re-installing all projects registered in \$bgVinstalledPaths"
		IFS=":" read -a folders <<<$bgVinstalledPaths

		[ "$bgVinstalledSandbox" ] && ( (
			cd "$bgVinstalledSandbox"
			[ -x makeCtags.sh ] && ./makeCtags.sh &>/dev/null
		)  & )
		shift
	fi

	# expand the cmdline parameters into the list of <folders> to operate on
	# if folders is already populated, this will only add to them
	_vinstallMakePathList -e -R folders -S sandboxFromFolderList $recurse "$@"

	# if the user is vinstalling a sandbox folder, we record it in the ENV separately and it activates some special features
	# the sandbox's project folders are already in $folders
	if [ "$sandboxFromFolderList" ]; then
		declare -gx bgVinstalledSandbox="$sandboxFromFolderList"
	fi

	### choose a host manifest file for use in this vinstalled session
	if [ "$bgVinstalledSandbox" ]; then
		export bgVinstalledManifest="$bgVinstalledSandbox/.bglocal/hostmanifest"
		export bgVinstalledPluginManifest="$bgVinstalledSandbox/.bglocal/hostPluginManifest"
	elif [ ${#folders[@]} -gt 0 ] || [ "$bgVinstalledPaths" ]; then
		export bgVinstalledManifest="$(mktemp --tmpdir bgVinstalledManifest.$$.XXXXXXX)"
		export bgVinstalledPluginManifest="$(mktemp --tmpdir bgVinstalledPluginManifest.$$.XXXXXXX)"
	else
		unset bgVinstalledManifest
		unset bgVinstalledPluginManifest
	fi

	# make sure that it exists
	if [ "$bgVinstalledManifest" ] && [ ! -s "$bgVinstalledManifest" ]; then
		if [ -f "/var/lib/bg-core/manifest" ]; then
			cp "/var/lib/bg-core/manifest" "$bgVinstalledManifest"
		else
			touch "$bgVinstalledManifest"
		fi
	fi

	### when a sandbox includes build dep projects like bg-core and bg-dev, we have a chicken and egg problem.
	# the following blocks attempts to avieviate that by pre installing parts of them

	# separate the build dep projects from other projects being installed
	local foldersBldDeps foldersOthers
	for folder in "${folders[@]}"; do
		# build deps are bg-core,bg-dev and any package that contains a PackageAsset plugin
		if [[ "$folder" =~ (bg-core|bg-dev)(.git)?$ ]] || [ "$(find -L "$folder" \( -type d  -name ".?*" \) -prune  -o -type f -name "*..PackageAsset" -printf "%P\n" 2>/dev/null)" ]; then
			foldersBldDeps+=("$folder")
		else
			foldersOthers+=("$folder")
		fi
	done
	# make sure that the build dep projects are first
	folders=( "${foldersBldDeps[@]}" "${foldersOthers[@]}" )

	# pre-install the build dep packages
	for folder in "${foldersBldDeps[@]}"; do
		echo "pre-installing build dependency package: ${folder##*/}"
		_vinstallOneProject --preInst $quickFlag "$folder"
	done

	if ! which bg-dev &>/dev/null; then
		echo "error: can not complete the virtual installation because the bg-dev command is not available. You must either install the bg-dev package or include it in the packages being vinstalled"
		return
	fi

	# build the host manifest up to this point so that all the PackageAsset plugins will be known during the rest of the vinstalls
	if [ ! "$quickFlag" ] && [ "$bgVinstalledManifest" ]; then
		(
			echo "updating host manifest with newly installed build deb assets"
			source /usr/lib/bg_core.sh
			import PackageAsset.PluginType ;$L1;$L2
			static::PackageAsset::updateVInstalledHostmanifest
		)
	fi

	### do the vinstall on each folder in the list,
	for folder in "${foldersBldDeps[@]}" "${foldersOthers[@]}"; do
		_vinstallOneProject $quickFlag "$folder"
	done

	### now that the project manifest files are updated, update the vinstalled host manifest
	if [ ! "$quickFlag" ] && [ "$bgVinstalledManifest" ]; then
		(
			source /usr/lib/bg_core.sh
			import PackageAsset.PluginType ;$L1;$L2
			static::PackageAsset::updateVInstalledHostmanifest
		)
	fi

	# build the host plugin manifest in the background. as of 2022-02 no instalation task needs the plugin attributes. the manifest already lists all the plugins
	if [ ! "$quickFlag" ] && [ "$bgVinstalledPluginManifest" ]; then
		((
			source /usr/lib/bg_core.sh
			import bg_plugins.sh  ;$L1;$L2
			# $Plugin::buildAwkDataTable ... failed when processing PluginType:Collect (Collect[0] was overwritten with 'Class')
			# bg_plugins.sh: line 386: _bgclassCall Plugin Class 0 |: expression recursion level exceeded (error token is "Plugin Class 0 |")
			static::Plugin::buildAwkDataTable | fsPipeToFile "$bgVinstalledPluginManifest"
		)&)
	fi

	[ ! "$quickFlag" ] && for folder in "${folders[@]}"; do
		local fullpath=$(cd  ${folder:-.}; pwd)
		local projName="${fullpath##*/}"

		# update the funcman man pages in the background
		which bg-dev &>/dev/null && [ ! "$bgVinstallInhibitPostProcessing" ] && (
			(export bgTracingBanner=""; cd "$fullpath"; bg-dev funcman update >/dev/null) &
		)
	done

	# report if there are any uninstalled dependencies
	[ "$addedFlag" ] && __bgCheckForMissingDeps "$gdeps"
}
export -f _vinstall

function _vinstallOneProject()
{
	local preInstallFlag quickFlag
	while [ $# -gt 0 ]; do case $1 in
		--preInst) preInstallFlag="--preInst" ;;
		--quick)   quickFlag="--quick" ;;
		*)  break;
	esac; shift; done
	local folder="$1"
	local fullpath=$(cd  ${folder:-.}; pwd)
	local projName="${fullpath##*/}"

	# the package name is typically the foldername but it could be different. Look in .bg-sp/config and then the deb control file
	local pkgName="$(gawk -F= '$1==packageName {print $2}' "$fullpath/.bg-sp/config" 2>/dev/null)"
	[ ! "$pkgName" ] && pkgName="$(gawk -F: '$1=="Package" {print $2}' $fullpath/pkgControl/debControl 2>/dev/null )"
	[ ! "$pkgName" ] && pkgName="${fullpath##*/}"
	pkgName=$(echo $pkgName) # remove leading and trailing spaces

	# keep track of reloading or new install state. addedFlag is the running state to see if any have been added even if some are reloaded
	local status="updated"
	if [[ ! ":${bgInstalledPkgNames}:" =~ :$pkgName: ]]; then
		status="added"
		addedFlag="1"
	fi

	# make sure this project appears in each of these paths but dont add it twice.
	[[ ! ":${PATH}:"                =~ :$fullpath:      ]] && export PATH="$fullpath:$PATH"
	[[ ! ":${BASH_LOADABLES_PATH}:" =~ :$fullpath:      ]] && export BASH_LOADABLES_PATH="$fullpath:$BASH_LOADABLES_PATH"
	[[ ! ":${BASH_LOADABLES_PATH}:" =~ :$fullpath/bin:  ]] && export BASH_LOADABLES_PATH="$fullpath/bin:$BASH_LOADABLES_PATH"
	[[ ! ":${MANPATH}:"             =~ :$fullpath:      ]] && export MANPATH="$fullpath:$MANPATH"
	[[ ! ":${MANPATH}:" =~ :$fullpath/.bglocal/funcman: ]] && export MANPATH="$fullpath/.bglocal/funcman:$MANPATH"
	[[ ! ":${AWKPATH}:"             =~ :$fullpath:      ]] && export AWKPATH="$fullpath:${AWKPATH:-$(gawk 'BEGIN {print ENVIRON["AWKPATH"]}')}"
	[[ ! ":${AWKPATH}:"             =~ :$fullpath/lib:  ]] && export AWKPATH="$fullpath/lib:${AWKPATH:-$(gawk 'BEGIN {print ENVIRON["AWKPATH"]}')}"
	#(done in node-cli) [[ ! ":${NODE_PATH}:"   =~ :$fullpath/node_modules: ]] && export NODE_PATH="$fullpath/node_modules:$NODE_PATH"
	[[ ! ":${NODE_PATH}:" =~ :$fullpath/global_node_modules: ]] && export NODE_PATH="$fullpath/global_node_modules:$NODE_PATH"
	[[ ! ":${bgLibPath}:"           =~ :$fullpath:      ]] && export bgLibPath="$fullpath:$bgLibPath"
	[[ ! ":${bgDataPath}:"          =~ :$fullpath:      ]] && export bgDataPath="$fullpath:$bgDataPath"
	[[ ! ":${bgVinstalledPaths}:"   =~ :$fullpath:      ]] && export bgVinstalledPaths="$fullpath:$bgVinstalledPaths"
	[ ! "$preInstallFlag" ] && [[ ! ":${bgInstalledPkgNames}:" =~ :$pkgName:       ]] && export bgInstalledPkgNames="$pkgName:$bgInstalledPkgNames"

	# invoke the project's vinstall hook if it exists
	# at the time of adding [ ! "$quickFlag" ], the only onVInstall scripts were light but we pass the flag to the scripts so that
	# each script can respect the flag if something heavy is added
	local savedPWD=$PWD; cd $fullpath
	if [ -f "$fullpath/.bg-sp/onVInstall" ]; then
		source "$fullpath/.bg-sp/onVInstall" $quickFlag || echo "$pkgName:.bg-sp/onVInstall exitted with a non-zero exit code"
	fi
	cd $savedPWD

	# make sure that the manifest file is up to date
	if which bg-dev &>/dev/null; then
		if [ ! "$quickFlag" ]; then
			(export bgTracingBanner=""; cd $fullpath; bg-dev assets update -q)
			# now catch up the packages that were vinstalled before bg-dev was available
			if [ "$pkgName" == "bg-dev" ] && [ ${#_bgTmpPkgListNotUpdated[@]} -gt 0 ]; then
				local _tmpPath; for _tmpPath in "${_bgTmpPkgListNotUpdated[@]}"; do
					(export bgTracingBanner=""; cd $_tmpPath; bg-dev assets update -q)
				done
				unset _bgTmpPkgListNotUpdated
			fi
		fi
	else
		export _bgTmpPkgListNotUpdated
		_bgTmpPkgListNotUpdated+=("$fullpath")
	fi

	# loop over the project's assets
	local -A assetCounts=()
	local assetCount=0
	local assetType file; while read -r assetType file; do
		((assetCounts[${assetType:-"<empty>"}]++))
		((assetCount++))
		case $assetType in
			cmd)                  complete -r $file &>/dev/null ;; # now the ondemand mechanism will set it the next time its used
			globalBashCompletion) [ -f "$fullpath/$file" ] && source "$fullpath/$file" ;;
		esac
	done < <(gawk '{print $2 " " $4}' "$fullpath/.bglocal/manifest" 2>/dev/null)

	# record the dependencies so that we can suggest installing missing dependencies
	local deps="$(gawk '$1~"^Depends:" {FS=",";sub("^Depends:","",$0); for (i=2; i<NR; i++) {s=$i; sub("\\(.*$","",s); print s}}' $fullpath/pkgControl/debControl 2>/dev/null)"
	gdeps="$gdeps${gdeps:+ }$deps"

	[ ! "$preInstallFlag" ] && case $status in
		added)   printf "${quickFlag:+"(quick mode) "}virtually installed %3s assets from %s\n" "$assetCount" "$projName" ;;
		updated) printf "${quickFlag:+"(quick mode) "}updated %3s virtually installed assets from %s\n" "$assetCount" "$projName" ;;
	esac
}
export -f _vinstallOneProject


# usage: _vuninstall [-r] <path>
# undo the _vinstall effect when you are done
function _vuninstall()
{
	local recurse verboseFlag folders sandboxFromFolderList
	while [ $# -gt 0 ]; do case $1 in
		-v)   verboseFlag="-v" ;;
		-r)   recurse="-r" ;;
		*)  break;
	esac; shift; done

	if [ "$1" == "status" ]; then
		_vinstallStatus "$@"
		return
	fi

	assertBgDebugEnvironmentIsActive

	# implement no <path> or the keyword "all" by re-calling ourseves to vuninstall each of the currently installed projects.
	if [ "${1:-all}" == "all" ]; then
		echo "uninstalling all projects registered in \$bgVinstalledPaths"
		local installedProjectPaths; IFS=":" read -a installedProjectPaths <<<$bgVinstalledPaths
		_vuninstall "${installedProjectPaths[@]:-status}"
		unset bgVinstalledSandbox
		return
	fi

	_vinstallMakePathList -R folders -S sandboxFromFolderList $recurse "$@"

	if [ "$sandboxFromFolderList" ]; then
		[ "$sandboxFromFolderList" == "$bgVinstalledSandbox" ] || _assertError "The sandbox you specified to vuninstall is not currently installed. \n\tcurrently installed sandbox='$bgVinstalledSandbox' \n\tcthe sandbox specified='$sandboxFromFolderList'"
		unset bgVinstalledSandbox
	fi


	local projFolder
	for projFolder in "${folders[@]}"; do

		# when we uninstall, the user can specify the project name instead of a path to the folder
		local paths; IFS=":" read -a paths <<<$bgVinstalledPaths
		local path; for path in "${paths[@]}"; do
			if [[ "${path%/}" =~ /${projFolder%/}$ ]]; then
				projFolder="$path"
				break
			fi
		done

		# invoke the project's onVUninstall hook if it exists
		local savedPWD=$PWD; cd $fullpath
		if [ -f "$fullpath/.bg-sp/onVUninstall" ]; then
			source "$fullpath/.bg-sp/onVUninstall" || echo "$pkgName:.bg-sp/onVUninstall exitted with a non-zero exit code"
		fi
		cd $savedPWD

		# this function is needed to handle the trick case that the path we are removing is a subset of another path
		function __subtractPathElement()
		{
			local s=":${1}:"
			s="${s//:$2:/:}"
			s="${s//::/:}"
			s="${s#:}"
			s="${s%:}"
			echo "$s"
		}

		local pkgName="$(gawk '/^Package:/ {s=$0; sub("^Package:[ \t]*","",s); print s}' $projFolder/pkgControl/debControl 2>/dev/null )"
		[ ! "$pkgName" ] && pkgName="${projFolder##*/}"

		export PATH="$(__subtractPathElement "$PATH" "$projFolder")"
		export MANPATH="$(__subtractPathElement "$MANPATH" "$projFolder")"
		export MANPATH="$(__subtractPathElement "$MANPATH" "$projFolder/.bglocal/funcman")"
		export AWKPATH="$(__subtractPathElement "$AWKPATH" "$projFolder")"
		export AWKPATH="$(__subtractPathElement "$AWKPATH" "$projFolder/lib")"
		export bgLibPath="$(__subtractPathElement "$bgLibPath" "$projFolder")"
		export bgDataPath="$(__subtractPathElement "$bgDataPath" "$projFolder")"
		export bgVinstalledPaths="$(__subtractPathElement "$bgVinstalledPaths" "$projFolder")"

		if [[ ":${bgInstalledPkgNames}:" =~ :$pkgName: ]]; then
			echo "removed '$projFolder' from PATH, MANPATH, AWKPATH, bgLibPath and bgDataPath"
			export bgInstalledPkgNames="$(__subtractPathElement "$bgInstalledPkgNames" "$pkgName")"
		else
			echo "skipped '$projFolder' was already removed"
		fi
	done
}
export -f _vuninstall





# usage: _tagsGrep <tag> [<regex>]
# grep the installed script code from any installed or vinstalled package project
function _tagsGrep()
(
	bgTracingBanner=""
	source /usr/lib/bg_core.sh --minimal
	local tmp
	local -a opts=()
	while [ $# -gt 0 ]; do case $1 in
		-A*|-B*|-O*) bgOptionGetOpt opt: opts "$@" && shift ;;
		-*) bgOptionGetOpt opt opts "$@" && shift ;;
		*)  bgOptionsEndLoop "$@" && break; set -- "${bgOptionsExpandedOpts[@]}"; esac; shift;
	done
	[ $# -gt 0 ] || _assertError "tag name is a required parameter" || return 2
	_codeGrep "${opts[@]}" -T "$@"
)
export -f _tagsGrep


# usage: _codeGrep
# grep the installed script code from any installed or vinstalled package project
function _codeGrep()
(
	bgTracingBanner=""
	source /usr/lib/bg_core.sh --minimal

	local outMode="summary"
	local tagsExpression=""
	local commentMode=""
	local passThruOpts=()
	local preColorize="on"
	local preLineFormat="on"
	local suppressPrefix=""
	local truncateFlag=""

	# Handle the command line options as defined by the "getopts" unix/linux standard.
	# Specify the supported options in the optSpecs. 'x:' requires and argument.
	optSpecs="tT:C:A:B:O:livhf:"
	while getopts "$optSpecs" flag; do case $flag in
		T) tagsExpression="#[A-Z0-9:[:space:]]*${OPTARG}[A-Z0-9:[:space:]]*:" ;;
		t) truncateFlag="-t" ;;
		-) break ;;
		f) fileFilters=${OPTARG} ;;
		C) commentMode=${OPTARG}
			[ "$commentMode" == "codeOnly" ] && fileFilters+=" -manpage -template -data -doc "
			;;
		O) outMode=${OPTARG} ;;
		l) outMode="matchingFiles" ;;
		h) suppressPrefix="-h"  ;;
		v) passThruOpts+=("-${flag}${OPTARG}")  ;;
		A) passThruOpts+=("-${flag}${OPTARG}")  ;;
		B) passThruOpts+=("-${flag}${OPTARG}")  ;;
		i) passThruOpts+=("-${flag}${OPTARG}")  ;;
		?) passThruOpts+=(-$flag)  ;;
	esac; done; shift $((OPTIND-1)); unset OPTIND

	local manFile="$bgVinstalledManifest"
	if [ ! "$manFile" ] || [ ! -f "$manFile" ]; then
		echo "error: bgVinstalledManifest is not set. can not codeGrep without vinstalled projects" >&2
	fi
	local codeFiles="$(gawk -v fileFilters="$fileFilters" \
		-i bg_core.awk '
		BEGIN {
			typeRegexIncludeList=".*"
			typeRegexExcludeList=""
			typeRegex="^.*$"
			if (fileFilters) {
				typeRegexIncludeList=""
				typeRegexExcludeList=""
				split(fileFilters, filters)
				for (i in filters) {
					if (filters[i]~/^[-]/)
						typeRegexExcludeList=typeRegexExcludeList ((typeRegexExcludeList)?"|":"") ".*" gensub(/^[-]/,"","g",filters[i]) ".*"
					else
						typeRegexIncludeList=typeRegexIncludeList ((typeRegexIncludeList)?"|":"") ".*" gensub(/^[-]/,"","g",filters[i]) ".*"
				}
				if (!typeRegexIncludeList)
					typeRegexIncludeList=".*"
			}
		}
		$2 ~ "^("typeRegexIncludeList")$"  && $2 !~ "^("typeRegexExcludeList")$" {print $4}
	' "$manFile")"
	codeFiles="$(fsExpandFiles -F -f $codeFiles)"
	codeFiles="${codeFiles[*]}"

	case $outMode in
		# the awk script branches on outMode to implement this option
		summary)       : ;;
		matchingFiles) preColorize="skip" ;;
		*)             assertError "unknown output format specified in '-O $outMode' option" ;;
	esac

	[[ "${commentMode:-empty}" =~ ^(onlyComments|codeOnly|tagsOnly|empty)$ ]] || assertError "unknown comment mode '$commentMode'. Expected one of onlyComments|codeOnly|tagsOnly"

	[ "$commentMode" == "tagsOnly" ] && tagsExpression="#[[:space:]]*[A-Z][A-Z0-9]*:"
	local tagsExpressionSep=""; [ "$tagsExpression" ] && [ "$1" ] && tagsExpressionSep=".*"

	local windowWidth=$(( [ -t 1 ] || [ -t 2 ] ) && tput cols || echo 1000)

	# TODO: make an awk library string that both _codeGrep and funcman can use to keep track of file sections and linetypes
	# TODO: I started adding file, and section level classification but then realized that codeGrep only sees the reduced output of grep so it can not do that. Move this algorithm to funcman or a new tool in the funcman space of full source scanning ctags, etc...
	grep "${passThruOpts[@]}" --color=never -n -- "${tagsExpression}${tagsExpressionSep}$1" $codeFiles \
		| $(cmdSw $preLineFormat) awk -v regex="${tagsExpression}${tagsExpressionSep}$1" -v commentMode="$commentMode" -v suppressPrefix="$suppressPrefix" -v windowWidth="$windowWidth" -v truncateFlag="$truncateFlag" '
			function bgtrace(s) {
				print s >> "/tmp/bgtrace.out"
			}
			BEGIN {
				csiHiRed=sprintf("'"$csiHiRed"'")
				csiFontReset=sprintf("'"$csiFontReset"'")
				csiWhite=sprintf("'"$csiWhite"'")
			}


			BEGINFILE {
				# we currently pipe grep into this function so awk is reading stdin and not files so BEGINFILE is not useful
			}
			FNR==1 {
				if (fileType ~ /lib|command/ && $1 ~ /^#!/) {
					sub(".*/","", $0)
					fileType=fileType":"$0
				}
			}
			{
				# parse the grep output format. Context lines vs matching lines and file/lineNo prefix vs content
				# Output:
				#      lineType=context|data
				#      filePart=<filename>
				#      lineNo=<lineNumber>
				filePart=$0; sub("[-:][0-9]*[-:].*$","", filePart);
				contentPart=substr($0,length(filePart)+1)
				lineType=(substr(contentPart,1,1)=="-")?"context":"data"
				lineNo=contentPart; sub("^[-:]","", lineNo); sub("[-:].*$","", lineNo);
				colNo=(match(contentPart, regex)?RSTART:1);
				sub("^[-:][0-9]*[-:]","", contentPart);


				srcFile=filePart; sub("^.*/|[(].*$","",srcFile)
				if (srcFile != srcFileLast) {
					# stateful sections are reset each time we enter a new file
					sectionType="global"
					switch (srcFile) {
					 	case /^.._.*[.]sh$/:          fileType="lib"; break;
						case /^.*[.]creqConfig$/:     fileType="plugin:creqConfig"; break;
						case /^.*[.]creqProfile$/:    fileType="plugin:creqConfig"; break;
						case /^.*[.]standards$/:      fileType="plugin:standards"; break;
						case /^.*[.]collect$/:        fileType="plugin:collect"; break;

						case /^.*[.]bgGitFeature$/:   fileType="plugin:bgGitFeature"; break;
						case /^.*[.]domWiki$/:        fileType="plugin:domWiki"; break;
						case /^.*[.]pluginType$/:     fileType="plugin:pluginType"; break;
						case /^.*[.]rbacPermission$/: fileType="plugin:rbacPermission"; break;
						case /^[^.]*$/:               fileType="command"; break;
				 	}

					srcFileLast=srcFile
				}
#
#
# 				# maintain a running section type so that we know what kind of content we are in.
# 				# this is a state machine. The rest state is "global". From there, various patterns can change the state to something else
# 				# and from those places, a pattern specific to it can return it to the "global state"
# 				# the state is reset to "global each time a new file is started"
# 				switch (sectionType) {
# 					case "global":
# 						switch (contentPart) {
# 							case /^[[:space:]]*function[[:space:]]/:                          sectionType="function"      ; break
# 							case /^[[:space:]]*#[[:space:]]usage:[[:space:]]/:                sectionType="manPage"       ; break
# 							case /^[[:space:]]*#[[:space:]]?(funcman)?[[:space:]]?MAN[(]/:    sectionType="manPage"       ; break
# 							case /^[[:space:]]*#[[:space:]]*AWKLIB([[:space:]]|:)/:           sectionType="awkCode:lib"   ; break
# 							case /^[[:space:]]*[^#[:space:]].*(awk|bgawk|awkDataRunBuilder).*['\''][[:space:]]*$/: sectionType="awkCode:script"; break
# 							case /^[[:space:]]*[^#[:space:]].*(awk|bgawk|awkDataRunBuilder).*\\$/: sectionType="awkStartContinue"; break
# 						}
# 					case "function": if (contentPart ~ /^}/)  sectionType="global"; break
# 					case "manPage":  if (contentPart !~ /^[[:space:]]*#/)  sectionType="global"; break
# 					case "awkStartContinue":
# 						switch (contentPart) {
# 							case /\\$/:                 sectionType="awkStartContinue"; break
# 							case /['\''][[:space:]]*$/: sectionType="awkCode:script"  ; break
# 							default:                    sectionType="global"          ; break
# 						}
# 						break;
# 					case /^awkCode/:  if (contentPart !~ /^[[:space:]]*#/)  sectionType="global"; break
# 				}


				# classify the line type
				if (lineType~"data" && contentPart~"^[[:space:]]*#")
					lineType=lineType"-comment"
				if (lineType~"data" && contentPart~"^[[:space:]]*[^#[:space:]]")
					lineType=lineType"-code"
				if (lineType~"context" && !lineNo)
					lineType=lineType"-separator"
				if (lineType~"comment" && contentPart~"#[[:space:]]*[A-Z][A-Z0-9]*[[:space:]]*:")
					lineType=lineType"-tag"

				# canonize the TAG format
				if (lineType ~ "tag") {
					if (match(contentPart, "#[[:space:]]*([A-Z][A-Z0-9]*)[[:space:]]*:", matches)) {
						tag=matches[1]
						sub("#[[:space:]]*"tag"[[:space:]]*:","# "csiHiRed""tag""csiFontReset" :", contentPart)
					}
				}

				#printf("%-13s %-7s %-13s %-13s %s\n", srcFile, fileType, sectionType, lineType, contentPart) >>"/tmp/codeGrepTest.data"

				# if this line does not match the requested content type, mark it for skipping
				if (commentMode) switch (commentMode":"lineType) {
					case "onlyComments:data-comment": break
					case "codeOnly:data-code":        break
					case "tagsOnly:data-comment-tag": break
					case ":.*":                       break
					default: skips[NR]=1
				}

				# reduce the filename
				# TODO: use the .bg-sp folder to identify the containing project
				fullFiles[NR]=filePart
				folderCount=0
				filename=filePart; sub("^.*[/]","", filename); filePart=substr(filePart, 1, length(filePart)-length(filename)-1)
				for (i=0; i<folderCount; i++) {
					folder=filePart; sub("^.*[/]","", folder); filePart=substr(filePart, 1, length(filePart)-length(folder)-1)
					filename=folder"/"filename
				}
				if (lineType~"context") gsub("."," ", filename)

				colNoOpt=(true)?":"colNo:""

				pad=(int(lineNo)<10?"   ":((int(lineNo)<100)?"  ":((int(lineNo)<1000)?" ":"")))
				fileWithLineNo=filename"("lineNo""colNoOpt"):"pad
				if (lineType~"separator") fileWithLineNo=""

				# record this line record. We buffer them to do some post processing in the end
				files[NR]=filename
				lineNos[NR]=lineNo
				colNos[NR]=colNo
				filesWithLineNo[NR]=fileWithLineNo
				content[NR]=contentPart
				lineTypes[NR]=lineType

				if (!skips[NR])
					matchingFiles[filename]++

				fileSumLen+=length(fileWithLineNo)
				fileLens[NR]=length(fileWithLineNo)
			}
			END {
				if ("'"$outMode"'"=="matchingFiles") {
					for (file in matchingFiles)
						printf("%3s : %s\n", matchingFiles[file], file)

				} else {

					fileAvgLen=fileSumLen/((NR>0)?NR:1)
					asort(fileLens)
					iggy=0
					iggy=int(NR*0.1)
					fileMaxLen=fileLens[NR-iggy]

					lineSetCount=0
					lastLineNo=999
					lineSetState=1
					for (i=1; i<=NR; i++) {
						if (lastLineNo+1 != lineNos[i] || lineTypes[i]~"separator") {
							if (!lineSetState && lineSetCount>1) {
								for (n=0; n<lineSetCount; n++)
									skips[lineSet[n]]=1
							}
							delete lineSet
							lineSetState=0
							lineSetCount=0
						}
						lastLineNo=lineNos[i]
						lineSet[lineSetCount++]=i
						if (!skips[i] && lineTypes[i]~"data")
							lineSetState=1
					}

					lastIsASeparator=0
					for (i=1; i<=NR; i++) {
						if (lastIsASeparator && lineTypes[i]~"separator")
							skips[i]=1
						if (!skips[i])
							lastIsASeparator=(lineTypes[i]~"separator")
					}

					debug=0
					for (i=1; i<=NR; i++) {
						if (debug || !skips[i]) {
							data=content[i]
							if (debug) data=skips[i]"| "lineTypes[i]
							gsub("^[[:space:]]*", "", data)
							prefix=filesWithLineNo[i]; if (suppressPrefix) {prefix=""; fileMaxLen=0}
							outline=sprintf(csiWhite"%*s"csiFontReset" %s", fileMaxLen,prefix, data)
							if (truncateFlag && length(outline)>windowWidth) {
								realLength=0
								realOut=""
								colorRegex=csiHiRed"|"csiFontReset"|"csiWhite
								gsub("[[]","\\[",colorRegex)
								match(outline, colorRegex)
								while (realLength<windowWidth) {
									# when the colors are turned off b/c output is not going to a terminal,
									# the colorRegex matches the empty string and RSTART will 1 and RLENGTH will be 0
									if (RSTART>0 && RLENGTH>0 && realLength+RSTART <= windowWidth) {
										realLength+=(RSTART-1)
										realOut=realOut""substr(outline,1,RSTART+RLENGTH-1)
										outline=substr(outline,RSTART+RLENGTH)
									} else {
										realOut=realOut""substr(outline,1,windowWidth-realLength-1)
										realLength=windowWidth
										outline=""
									}
									match(outline, colorRegex)
								}
								outline=realOut"+"
							}
							printf("%s"csiFontReset"\n", outline)
						}
					}
				}
			}' \
		| $(cmdSw $preColorize) grep  --color=always -E -- "${1}|$"
)
export -f _codeGrep



# man(1.bashCmd) bg-debugCntr-debugger
# usage: bg-debugCntr debugger [status]
#        bg-debugCntr debugger cntr-C:(on|off)
#        bg-debugCntr debugger stopOnAssert:(on|off)
#        bg-debugCntr debugger destination <dbgDriver>:<destination>
# usage: bgdb [--breakAt=stopOnLibInit|stopOnFirstScriptLine] <cmd> [<arg1>..<argN>]
# configure interactive debugging for bash scripts
#
# Launching the Debugger:
# There are several ways to invoke a script in the interactive debugger. Its possible to invoke the debugger outside of the
# bg-debugCntr environment but typically bg-debugCntr is used.
#   1) bgdb <cmdline>
#      see man(1) bgdb
#      bgdb is a sourced function that is a part of bg-debugCntr. This is the only way to invoke the debugger on scripts thta do
#      not source bg_core.sh
#   2) bg-debugCntr debugger cntr-c:on
#      pressing cntr-c while the script is running will invoke the debugger. This is useful it the script takes a long time to run
#      and you want to see where its hanging and if its in an infinite loop. If the script is blocked on an external cmd, it might
#      not respond.
#   3) bg-debugCntr debugger stopOnAssert:on
#      if the script calls an assert* function that is not caught by a Tyy:/Catch: block it will invoke the debugger at that point.
#
# Debugger Destinations:
# The destination determines the debugger driver that is loaded to handle the interactive debugger and driver specific parameters
# that determine where the driver displays the UI. At the time of this writing, there are two drivers, integrated and remote.
#
# **integrated**:  The integrated driver implements a whole debugger UI in bash that runs inside the target script's process.
# It can use any tty you specify to display the UI and read user input. The default is 'win' which uses the cuiWin
# library to open a new terminal window to get a tty
# The integrated driver can be passed a <terminalID> which supports these values
#    <terminalID> : tty|bgtrace|win|win<n>|/dev/pts/<n>  Typically you just use the default, 'win' which will use a cuiWin with the
#           name $$.debug . Because this name contains the bash PID ($$), the effect is that a debugger terminal window will be
#           openned that is specific to that terminal. Each script you debug in that terminal will re-use that same debugger instance
#           and will create it if needed.
#
# **remote**: The remote driver communicates to a separate dugger UI process over a pipe or socket. By default it will launch the
# the bash debugger from the integrated driver in a sepate cuiWin. This driver can also be used to connect to IDE
# plugins.
# The remote driver can be passed a <connectionID> which supports these values
#    win : will create a cuiWin with the name $$.debug so that is is unique and persistent to the terminal being used.
#    <socket> : WIP....
#
# Params:
#    <dbgDriver>
#    <destination>
#    <terminalID> : which tty the debugger cui should be done on
#           win : in a separate cuiWin (terminal emulator window) with the ID '$termID.debugger'
#           win[0-9] : in a separate cuiWin (terminal emulator window) with the ID 'win[0-9]'
#           tty : the script's terminal. The debugger UI will be intermixed with the script UI
#           bgtrace : in the bgtrace tty destination
#    <firstBreakpoint> : the breakpoint that will be set to determine where the bebugger will be first activated
#           stopOnLibInit : stops script execution on as soon as enough libraries have been sourced to run the debugger
#                This allows stepping through most of the library initiallization
#           stopOnFirstScriptLine : stops the script on the first line of the main script. This skips the initialization
#                of any libraries that the script imports before its first line.
function _debugger()
{
	local cmd="$1"; shift
	[ "${cmd:-status}" != "status" ] && assertBgDebugEnvironmentIsActive
	case ${cmd:-status} in
		-h) man bg-debugCntr-debugger ;;
		cntr-C:on)    unset bgDebuggerInhibitCntrC ;;
		cntr-C:off)   export bgDebuggerInhibitCntrC="1" ;;

		stopOnAssert:on)    export bgDebuggerStopOnAssert="1" ;;
		stopOnAssert:off)   unset bgDebuggerStopOnAssert ;;

		destination)  export bgDebuggerDestination="$1" ;;
		status)
			echo "Debugger Status      : ${bgDebuggerDestination:-<defaultDestination>}"
			echo "  debug on cntr-c    : $([ ! "$bgDebuggerInhibitCntrC" ] && echo on || echo off)"
			echo "  debug on assert    : $([ "$bgDebuggerStopOnAssert" ] && echo on || echo off)"
			;;
	esac
}
export -f _debugger

# set cntr-c  to debug off by default
export bgDebuggerInhibitCntrC="1"


# man(1.bashCmd) bgdb
# usage: bgdb [--breakAt=<firstBreakpoint>|stopOnLibInit|stopOnFirstScriptLine] <cmd> [<arg1>..<argN>]
# invoke a bash script in an interactive debugger.
# bgdb is implemented as a sourced function by bg-debugCntr so you need to source bg-debugCntr in your terminal before using the
# interactive debugger.
#
# Typically this is used for scripts that source /usr/lib/bg_core.sh but there is experimental support for debugging any bash script.
#
# There are other ways to invoke the debugger. See bg-debugCntr-debugger
#
# Options:
#    --breakAt=<firstBreakpoint>  : instruct the debugger where to initially stop the script. If the script does not
#                                   source bg_core.sh, this option is ignored
#       stopOnFirstScriptLine : (default) start on the first code line of the script.
#       stopOnLibInit         : stop as soon as possible so that the bg_core.sh startup code can be stepped through
#
# Params:
#    <cmdline>  : the command line to debug
# See Also:
#    man(1) bg-debugCntr-debugger
function bgdb() (
#_bgtrace "starting bgdb args[*]='$*'"
	bgDebugCntrRunMode="extScript" # so that _assertError will work right since we are in a sub shell
	local firstBreakpoint
	while [ $# -gt 0 ]; do case $1 in
		--breakAt*) bgOptionGetOpt val: firstBreakpoint "$@" && shift ;;
		*)  break; esac; shift; # simplified version of bgOptionsEndLoop
	done
	local cmdScript cmdPath env=() args=()
	local param; for param in "$@"; do
		if [ "$cmdScript" ]; then
			args+=("$param")
		elif [[ "$param" =~ = ]]; then
			env+=("$param")
		else
			cmdScript="$param"
			cmdPath="$(which "$cmdScript")"
		fi
	done

	if [ ! -x "$cmdPath" ] || [[ ! "$(file "$cmdPath")" =~ "Bourne-Again" ]]; then
		_assertError "'$cmdScript' is not a bash script. This debugger only works on bash scripts"
	fi

	if grep -q '^\s*source \s*/usr/lib/bg_core.sh' "$cmdPath"; then
		# this line sets an environment var at the start of executing "$@"
		bgDebuggerOn=on:${firstBreakpoint:-stopOnFirstScriptLine} "$@"
	else
		local script="$cmdPath "
		local arg; for arg in "${args[@]}"; do
			script="'$arg' "
		done
		"${env[@]}" bash -c '
			source /usr/lib/bg_core.sh
			import bg_debugger.sh ;$L1;$L2
			bgtrace "starting a foriegn script in the debugger"
			debuggerOn  stepToLevel 1
			source '"$script"'
		'
	fi
)

# usage: _bashComandHooks on|off|status
# This manages a DEBUG trap and PROMPT_COMMAND to call onBeforeBashCmd and onAfterBashCmd hook functions
# Note that onBeforeBashCmd is executed in the shell's environment but onAfterBashCmd is executed
# in a subshell because bash does not allow it to run in its environment.
function _bashComandHooks()
{
	local verboseFlag
	while [ $# -gt 0 ]; do case $1 in
		-v) verboseFlag="-v" ;;
		*)  break; esac; shift; # simplified version of bgOptionsEndLoop
	done
	local cmd="$1"; shift
	[ "${cmd:-status}" != "status" ] && assertBgDebugEnvironmentIsActive
	local marker=$'#onBeforeBashCmd; '
	case ${cmd:-status} in
		on)	export bgBashCmdHookFeature=on
			local script; read -r -d "" script <<-EOS
				cmdlineHook_promtCmdHook
			EOS

			# if our script is not present the first will be false and the second will set \1 to the whole string.
			# TODO: BASH5.1: now PROMPT_COMMAND can be an array to hold multiple separate commands
			[[ "$PROMPT_COMMAND" =~ ^(.*)(${marker}.*${marker})(.*)$ ]] || [[ "$PROMPT_COMMAND" =~ ^(.*)(.*)(.*)$ ]]
			PROMPT_COMMAND="${BASH_REMATCH[1]}${BASH_REMATCH[1]:+$'\n'}${marker}"$'\n'"${script}"$'\n'"${marker}${BASH_REMATCH[3]:+$'\n'}${BASH_REMATCH[3]}"
			;;
		off)unset bgBashCmdHookFeature
			[[ "$PROMPT_COMMAND" =~ ^(.*)(${marker}.*${marker})(.*)$ ]] && PROMPT_COMMAND="${BASH_REMATCH[1]}${BASH_REMATCH[3]}"
			PROMPT_COMMAND="${PROMPT_COMMAND//$'\n'$'\n'/$'\n'}"
			[[ "$PROMPT_COMMAND" =~ ^$'\n'*$ ]] && PROMPT_COMMAND=""
			PROMPT_COMMAND='builtin trap - DEBUG; PROMPT_COMMAND=""'
			;;
		trace)
			subCmd="$1"; shift
			case $subCmd in
				on*)    cmdlineHook_traceingOn="b4Cmdline,b4SimpleCmd,afterSimpleCmd,afterCmdline,dbgtrap,prompthook" ;;
				off)    cmdlineHook_traceingOn="" ;;
				status) echo "cmdlin hook tracing is set to : cmdlineHook_traceingOn='${cmdlineHook_traceingOn:-off}'" ;;
			esac
			;;
		status)
			[ "$1" == "-v" ] && verboseFlag="-v"
			echo "BashCmdHooks Status: ${bgBashCmdHookFeature:-off}"
			if [ "$bgBashCmdHookFeature" ]; then
				[[ "$PROMPT_COMMAND" =~ ^(.*)(${marker}.*${marker})?(.*)$ ]] || echo "   warning: PROMPT_COMMAND does not have the onBeforeBashCmd hook installed"
			else
				[[ "$PROMPT_COMMAND" =~ ^(.*)(${marker}.*${marker})(.*)$ ]] && echo "   warning: PROMPT_COMMAND has the onBeforeBashCmd hook installed"
			fi
			if [ "$verboseFlag" ]; then
				echo "  PROMPT_COMMAND=${PROMPT_COMMAND//$'\n'/$'\n'                 }"
			fi
			;;
	esac
}
export -f _bashComandHooks


function _installDevCapsForUser()
{
	local verboseFlag
	while [ $# -gt 0 ]; do case $1 in
		-v) verboseFlag="-v" ;;
		*)  break; esac; shift; # simplified version of bgOptionsEndLoop
	done
	local cmd="$1"; shift
	[ "${cmd:-status}" != "status" ] && assertBgDebugEnvironmentIsActive
	local marker=$'#onBeforeBashCmd; '
	case ${cmd:-status} in
		on)
			echo "setting /proc/sys/kernel/yama/ptrace_scope to 0 which allows attaching gdb to a running bash process for debugging"
			echo 0 > /proc/sys/kernel/yama/ptrace_scope
			echo
			echo "work in progress: invokeOutOfBandSystem now sets PATH=\$PATH which seems to alieviate the need to change the sudoers config. If we need to change sudoers in a fresh install in order to run vinstalled scripts with sudo, this would be the place to do it."
			;;
		off)
			;;
		status)

			;;
	esac
}
export -f _installDevCapsForUser

# usage: cmdlineHook_debugTrap <whereCalledFrom>
# this is the system trap function for onBeforeBashCmd. We separate this and the logical onBeforeBashCmd so
# that this can maintain the system part of the mechanism and the onBeforeBashCmd can contain only the
# logical actions we want to add to the bash cmd hook.
# In particular, we synthesize a call to onBeforeBashCmd when the user enters an empty line which contains no
# bash simple commands and therefore does not cause the DEBUG trap to execute
# It calls the logical onBeforeBashCmd* callback(s) which is where you put features
function cmdlineHook_debugTrap()
{
	# the first thing we do must be to save the last exit code
	local last_exitCode="$?"
	local IFS=$' \t\n'

	# in bash 5.1 and onward, its important to turn off the debug trap because if this function calls a subshell, it would re-enter
	# the debug trap
	builtin trap - DEBUG

	# keep track of the value that this function will return at the end
	local dbgResult=0

	# uncomment out this tracing if debugging the bg-debugCntr sourced code
	[[ "$cmdlineHook_traceingOn" == *dbgtrap* ]] &&  _bgtrace "### >DEBUG TRAP '$*'  BASH_COMMAND='$BASH_COMMAND'"

	# this trap is meant to only operate on the simple commands typed on the shell prompt. When simple commands are sourced functions
	# like bash completion functions, we do not want to incur the overhead for each line of those functions so we return if the
	# function nesting level is >1. We cant turn off the trap or else we wont have an oportunity to turn it back on before the command
	# is executed. Use-case: cd <tab><tab>
	(( ${#FUNCNAME[@]} > 1 )) && {
		[[ "$cmdlineHook_traceingOn" == *dbgtrap* ]] &&  _bgtrace "### <DEBUG TRAP dont want this one because its too deep {#FUNCNAME[@]}='${#FUNCNAME[@]}'"
		return 0
	}

	# now that we know we are being triggered for real, record the saved code in the global bgBASH_COMMAND_exitCode
	bgBASH_COMMAND_exitCode="$last_exitCode"

	# detect and suppress traps that we dont want to process.
	#    1) when regular code turns off the debug trap with 'builtin trap - DEBUG', we dont want to process that simple cmd
	#    2) when functions sourced in the shell get called, we this trap is not meant to track them
	if [[ "$BASH_COMMAND" == builtin*trap*-*DEBUG ]] \
	   || [ "$BASH_COMMAND" == "cmdlineHook_promtCmdHook" ] \
	   || (( ${#FUNCNAME[@]} > 1 )) ; then
		# put code here that ends a run of DEBUG trapping
		[[ "$cmdlineHook_traceingOn" == *dbgtrap* ]] &&  _bgtrace "### <DEBUG TRAP dont want this one '$BASH_COMMAND' {#FUNCNAME[@]}='${#FUNCNAME[@]}>1'"
		return 0
	fi

	# the first DEBUG trap invocation after the user hits enter, will get the full cmdline from the
	# bash history mechanism and fire the preCmdline event before moving on to the simple cmd about
	# to run.
	if ((bgBASH_COMMAND_INDEX==0)); then
		local cmdID; read -r cmdID bgBASH_COMMAND_LINE < <(history 1)
		# for the pre and pos cmdline hooks, bgBASH_COMMAND is the entire cmd line typed by the user
		bgBASH_COMMAND="$bgBASH_COMMAND_LINE"
		_fireCallbackList cmdlineHook_preCmdlineCallbackList DEBUG

	# synthesize a postSimpleCmd event for the last simple cmd that executed before. This does not run
	# the first time b/c we get called before each simple cmd so the first time there was no previous
	# cmd. This event will also get fired from the PROMPT_COMMAND hook so that it picks up the
	# last simple cmd ran
	else
		# bgBASH_COMMAND is still set from the last debug trap so it is the simple cmd that just finished
		_fireCallbackList cmdlineHook_postSimpleCmdCallbackList DEBUG
	fi

	# now fire the preSimpleCmd event for the new $BASH_COMMAND which is about to run
	bgBASH_COMMAND="$BASH_COMMAND"
	_fireCallbackList cmdlineHook_preSimpleCmdCallbackList DEBUG

	# count how many simple commands are executed as a result of this cmdline
	((bgBASH_COMMAND_INDEX++))

	# TODO: BASH5.1: BASH_REMATCH is no longer read only. this may allow improving this feature
	if [[ "$BASH_COMMAND" == *BASH_REMATCH* ]]; then
		[[ "$cmdlineHook_traceingOn" == *dbgtrap* ]] &&  _bgtrace "    DEBUG HOOK replacing 'BASH_REMATCH' with 'rematch'"
		# we cant change the cmd that bash is about to run but we can eval the cmd here and then exitcode=1 to tell bash to skip
		# the original cmd
		eval ${BASH_COMMAND//BASH_REMATCH/rematch}
		dbgResult=1
	fi

	# assume the simple cmd will be a sourcedFunction. If not, the cmd will set up its environment and override this if its a bg_core
	# style script or it wont matter if its not
	declare -g bgLibExecMode="sourcedFunction"
	declare -g bgLibExecCmd=($bgBASH_COMMAND)
	declare -g bgLibExecSrc=($bgBASH_COMMAND_LINE)
	declare -g scriptFolder="$PWD"

	# re-enable the trap since the user might have typed a compound command and DEBUG trap is called
	# before each simple command
	if [ "$bgBashCmdHookFeature" ]; then
		set +T
		builtin trap 'cmdlineHook_debugTrap' DEBUG
	fi

	# when $dbgResult is non-zero, it means that we dont want to execute the next command. We need extdebug on for that to work
	# but we do not want the DEBUG trap to be inherited so turn it off b/c extdebug turns it on)
	if [ ${dbgResult:-0} -gt 0 ]; then
		shopt -sq extdebug
		set +T
	fi
	[[ "$cmdlineHook_traceingOn" == *dbgtrap* ]] && _bgtrace "### <DEBUG HOOK returning '$dbgResult'"
	return $dbgResult
}
export -f cmdlineHook_debugTrap


# usage: cmdlineHook_promtCmdHook
# This is the system callback executed by PROMPT_COMMAND after each command has finished running,
# right before bash displays the prompt
# It fires off any registered logical onAfterBashCmd* callback(s) which is where you put features
function cmdlineHook_promtCmdHook()
{
	# TODO: 2022-08 bobg: switched these two lines: why was IFS line before $? line?
	bgBASH_COMMAND_exitCode="$?"
	local IFS=$' \t\n'
	# disable the DEBUG trap handler while we are in this function
	builtin trap - DEBUG

	[[ "$cmdlineHook_traceingOn" == *prompthook* ]] && _bgtrace "### PROMPT HOOK bgBASH_COMMAND='$bgBASH_COMMAND'"

	# synthesize a preCmdline event for <enter> on an empty line. Technically there was no bash simple
	# command so the debug trap did not get called. It normally detects and fires the preCmdline event
	# but if it never ran for this command, we can do it at the top of the PROMPT_COMMAND hook
	if [  ${bgBASH_COMMAND_INDEX:-1} -eq 0 ]; then
		bgBASH_COMMAND=""
		_fireCallbackList cmdlineHook_preCmdlineCallbackList PROMPT_COMMAND

	# if at least one simple cmd ran, we need to do the post simple cmd event
	else
		# bgBASH_COMMAND is still set from the last debug trap so it is the simple cmd that just finished
		_fireCallbackList cmdlineHook_postSimpleCmdCallbackList DEBUG
	fi

	# now fire the post cmdline event which is the last one
	# for the pre and post cmdline events, the bgBASH_COMMAND is the entire bgBASH_COMMAND_LINE
	bgBASH_COMMAND="$bgBASH_COMMAND_LINE"
	_fireCallbackList cmdlineHook_postCmdlineCallbackList PROMPT_COMMAND

	# reset our bgBASH_COMMAND_* vars before the next cmd starts
	bgBASH_COMMAND_LINE=""
	bgBASH_COMMAND_INDEX=0

	# do this before turning the debug trap back on
	[[ "$cmdlineHook_traceingOn" == *prompthook* ]] && _bgtrace "### PROMPT HOOK returning\n\n"

	# if this feature is still turned on,
	# enable the DEBUG trap handler so that the next time the user enters enter, it will run before
	# the next simple cmd.
	if [ "$bgBashCmdHookFeature" ]; then
		set +T
		builtin trap 'cmdlineHook_debugTrap' DEBUG
	fi
}
export -f cmdlineHook_promtCmdHook










# usage: onBeforeCmdline
# This callback is called after the user presses enter and before any simple cmd is ran.
# bgBASH_COMMAND is set to the entire cmdline that the user entered
function onBeforeCmdline()
{
	# its convenient to write a blank line to bgtrace before each compound command
	_bgtrace
	[[ "$cmdlineHook_traceingOn" == *b4Cmdline* ]] && _bgtrace " b4Cmdline        : '$bgBASH_COMMAND_LINE'"

	# vinstall feature: ensure that /usr/lib/bg_core.sh exists (if we have at least one vinstalled project. in a fresh VM we source and then install)
	if [ ! -f "/usr/lib/bg_core.sh" ] && [ "$bgVinstalledPaths" ]; then
		local bootStrapLibPath="$(gawk '$1=="bg-core" && $2=="lib.script.bash" && $3=="bg_core" {print $4} '  ${bgVinstalledManifest:-/dev/null})"
		if [ ! "$bootStrapLibPath" ] || [ ! -f "$bootStrapLibPath" ]; then
			local paths; IFS=":" read -a paths <<<$bgVinstalledPaths
			local path; for path in "${paths[@]}"; do
				if [ -f "$path/bg_core.sh" ]; then
					bootStrapLibPath="$path/bg_core.sh"
					break
				fi
			done
		fi

		if [ ! "$bootStrapLibPath" ]; then
			echo "bg_core.sh needs to be installed in /usr/lib/ but the vinstalled manifest does not have an entry for the bg_core library so it can not be installed by bg-debugCntr. Try to copy that library into place manually" >&2
		elif [ ! -f "$bootStrapLibPath" ]; then
			echo "bg_core.sh needs to be installed in /usr/lib/ but the bg_core library does not exist in the vinstalled path specified in the vinstalled manifest so it can not be installed by bg-debugCntr. Try to copy that library into place manually"
		else
			sudo -p "reinstalling bg_core.sh boot strap lib [sudo] " cp "$bootStrapLibPath" /usr/lib/bg_core.sh
		fi
	fi

	# vinstall feature: ensure that host is still configured for development mode
	if [ "development" != "$([ ! -f /etc/bgHostProductionMode ] || awk '/^[[:space:]]*mode[[:space:]]*[:=][[:space:]]*development/ {print "development"; exit}' /etc/bgHostProductionMode)" ]; then
		echo "This host is no longer configured to allow development mode. Will attempt to change config to delelopment mode." >&2
		echo "mode=development" | sudo -p "modify /etc/bgHostProductionMode [sudo] " tee /etc/bgHostProductionMode >/dev/null
	fi

	# bgtrace win: feature
	# check to see if the user set bgTracingOn directly to 'newWin' and replace it with the next win?
	# use [[ ]] inside () so it does not overwrite the user's BASH_REMATCH
	( [[ "$bgTracingOn" =~ ^(on:)?(winNew)$ ]] ) && {
		_traceCntr openWin "${bgTracingOn#on:}"
		[[ "$bgTracingOn" =~ ^(on:)?(winNew)$ ]] && {
			echo "failed to create a new bgtrace window. turning off"
			declare -gx bgTracingOn=""
		}
	}


	# bgtrace win: feature
	# check to see if a bgtrace viewer that we are using has closed
	# use [[ ]] inside () so it does not overwrite the user's BASH_REMATCH
	if ( [[ "$bgTracingOn" =~ (^|:)win[0-9]?$ ]] ); then
		local winName="${bgTracingOn#on:}"; [ "$winName" == "win" ] && winName="out"
		[ ! -e "/tmp/bgtrace.${winName}.cntr" ] && _traceCntr openWin "${bgTracingOn#on:}"
	fi

	# reload ourself if changes have been saved
	if [ "$_bg_debugCntr_selfPath" ] && [ "$_bg_debugCntr_selfTimestamp" != "$(stat -c"%Y" $_bg_debugCntr_selfPath)" ]; then
		echo "reloading bg-debugCntr because its source files has been changed"
		source "$_bg_debugCntr_selfPath" noop
	fi

	# import library refresh feature
	# if bg_core.sh is sourced into the environment, check to see if any of the libraries are newer
	[ "$(type -t importCntr)" ] && importCntr reloadAll -v

	return 0
}
export -f onBeforeCmdline
cmdlineHook_preCmdlineCallbackList+="    onBeforeCmdline "

[ "$$BASH_SOURCE" ] && {
	_bg_debugCntr_selfTimestamp=$(stat -c"%Y" $BASH_SOURCE)
	_bg_debugCntr_selfPath="$BASH_SOURCE"; [[ "$BASH_SOURCE" != /* ]] && _bg_debugCntr_selfPath="${PWD}/$BASH_SOURCE"
}

# usage: onBeforeSimpleCmd
# This callback is executed right before each individual simple command that make up the entered cmd line
# If the user entered a compound command this will be invokes multiple times for the one entered cmd line
# bgBASH_COMMAND is set to simple cmd that is about to run.
# Example:
#    $ echo "hello"; echo "world"<enter>
#      1) onBeforeSimpleCmd     # bgBASH_COMMAND == 'echo "hello"'
#      2) echo "hello"
#      3) onBeforeSimpleCmd     # bgBASH_COMMAND == 'echo "world"'
#      4) echo "world"
#      5) onAfterBashCmd      # bgBASH_COMMAND == 'echo "hello"; echo "world"'
# Use "$bgBASH_COMMAND" instead of $BASH_COMMAND since $BASH_COMMAND will behave differently based on whether this
# is called from the trap or the PROMPT_COMMAND
function onBeforeSimpleCmd()
{
	[[ "$cmdlineHook_traceingOn" == *b4SimpleCmd* ]] && _bgtrace "    b4SimpleCmd   :    '$bgBASH_COMMAND'"

	return 0
}
export -f onBeforeSimpleCmd
cmdlineHook_preSimpleCmdCallbackList+="  onBeforeSimpleCmd "


# usage: onAfterSimpleCmd
# This callback is executed after each simple command that make up the entered cmd line is finished running
# If the user entered a compound command this will be invokes multiple times for the one entered cmd line
# bgBASH_COMMAND is set to simple cmd that just finished running.
function onAfterSimpleCmd()
{
	[[ "$cmdlineHook_traceingOn" =~ *afterSimpleCmd* ]] && _bgtrace "    afterSimpleCmd:    '$bgBASH_COMMAND' exit='$bgBASH_COMMAND_exitCode'"

	# for interactive use, save BASH_REMATCH into rematch
	# TODO: BASH5.1: changed BASH_REMATCH so we might be able to improve this
	( [[ "$bgBASH_COMMAND" =~ ^'[[' ]] ) && declare -ga rematch=("${BASH_REMATCH[@]}")
	return 0
}
export -f onAfterSimpleCmd
cmdlineHook_postSimpleCmdCallbackList+=" onAfterSimpleCmd "


# usage: onAfterCmdline
# This callback is executed after all the simple commands that make up the entered cmd line are
# finished, right before bash displays the prompt for the next cmd line
# bgBASH_COMMAND is set to the entire cmdline that the user entered
function onAfterCmdline()
{
	[[ "$cmdlineHook_traceingOn" == *afterCmdline* ]] && _bgtrace " afterCmdline     : '$bgBASH_COMMAND'"

	while [ -s /tmp/bg-debugCntr-$bgTermID.msgs ]; do
		local _bgdcCmd="$(source /usr/lib/bg_core.sh; import bg_ipc.sh ;$L1;$L2; msgGet /tmp/bg-debugCntr-$bgTermID.msgs)"
		case $_bgdcCmd in
			bgdbRerun)
				echo "rerunning in debugger"
				eval $bgBASH_COMMAND
			;;
			*) break ;;
		esac
	done

	(source /usr/lib/bg_core.sh || exit 1; import bg_cui.sh; $L1;$L2; cuiSetTitle "$bgTermTitle" >/dev/tty)
	return 0
}
export -f onAfterCmdline
cmdlineHook_postCmdlineCallbackList+="   onAfterCmdline "


export cmdlineHook_preCmdlineCallbackList
export cmdlineHook_preSimpleCmdCallbackList
export cmdlineHook_postSimpleCmdCallbackList
export cmdlineHook_postCmdlineCallbackList




#################################################################################################################################
# Helper Library functions

# usage: _fireCallbackList <callbackListVar> [<p1> .. <pN>]
# executes each function name in the list. Only the first occurrence of each name is executed. On return
# the <callbackListVar> will be normallized to remove dupes and any function name that returned non zero
# will be removed from the list so that it won't run next time.
# Params:
#    <callbackListVar> : is a whitespace separated list of function names that should be invoked.
#            order is significant. dupes only called the first time.
function _fireCallbackList()
{
	local callbackListVar="$1"

	# do the firing
	local -A callbackDedupe
	local callback normalizedList
	for callback in ${!callbackListVar}; do
		((callbackDedupe[$callback]++ > 0)) && continue
		$callback "$@" && normalizedList+="$callback " || echo "'$callback' hook will not be called again because it exitted non zero" >&2
	done
	printf -v "$callbackListVar"  "%s" "$normalizedList"
}
export -f _fireCallbackList

# usage: assertBgDebugEnvironmentIsActive
# Some features of this script can be executed as an external script and some require the script to
# be sourced into the user's interactive base environment.  Any feature that requires that calls this
# to assert that its true or show the user a message explaining what they must do to use the feature.
function assertBgDebugEnvironmentIsActive()
{
	if [ "$bgDebugCntrRunMode" == ""extScript"" ]; then
		cat <<-EOS

		    You are invoking a development time debugging feature of $(basename $0). You must enable a terminal
		    to use these features by sourcing $(basename $0) into its interactive bash environment.
		    These features may be prohibitted in production environments.
		    Run the following command and then rerun this command.

		        source $(basename $0)

		EOS
		exit
	fi
}
export -f assertBgDebugEnvironmentIsActive

# usage: _assertError
# This is a simple version of assertError since the full version is not available.
# its critical that it only calls exit when its running in an external command so that it does not
# close the user's terminal window
function _assertError()
{
	echo "error: $@" >&2
	if [ "$bgDebugCntrRunMode" == "extScript" ]; then
		exit 2
	else
		# issue a cntr-c so that bash will not execute the remainder of any functions on the stack and
		# return to the prompt
		kill -SIGINT $$
		echo "system error: should not have gotten here. 'kill -SIGINT $$' did not work to end the function"
	fi
}
export -f _assertError


# usage: _bgtrace
# This is a simple version of bgtrace since the full version is not usually available in this library.
# note: that it does not set the global _bgtraceFile. it reclaculates it each time
function _bgtrace()
{
	# note: that _bgtraceFile is local
	local _bgtraceFile=""
	if [ "$bgTracingOn" ] && { [ ! "$_bgtraceFile" ] || [ "$_bgtraceFile" == "/dev/null" ]; } ; then
		if ([[ "$bgTracingOn" =~ (^|:)win[0-9]$ ]]); then
			local win=${bgTracingOn#*:}
			_bgtraceFile="/tmp/bgtrace.$win"
		elif ([[ "$bgTracingOn" =~ (on:)?win$ ]]); then
			_bgtraceFile="/tmp/bgtrace.out"
		elif ([[ "$bgTracingOn" =~ :std(out|err) ]]); then
			_bgtraceFile=/dev/${bgTracingOn#*:}
		elif ([[ "$bgTracingOn" =~ : ]]); then
			_bgtraceFile=${bgTracingOn#*:}
			_bgtraceFile=${_bgtraceFile:-/tmp/bgtrace.out}
		elif [ -w /tmp/bgtrace.out ]; then
			_bgtraceFile="/tmp/bgtrace.out"
		elif [ -w /tmp/bgtrace.out.$USER.$$ ]; then
			_bgtraceFile="/tmp/bgtrace.out.$USER.$$"
		fi

		[ "$1" != "--getDestination" ] && {
			echo -e "$@" >>$_bgtraceFile
			#echo -e "     |$@"
		}
	elif [ ! "$bgTracingOn" ] && [ "$_bgtraceFile" != "/dev/null" ]; then
		_bgtraceFile="/dev/null"
	fi

	[ "$1" == "--getDestination" ] && echo "${_bgtraceFile:-/dev/null}"
}
export -f _bgtrace


# usage: __bgCheckForMissingDeps <dependencies>
# used by vinstall to warn the user if there should be dependencies installed for the packages being
# virtually installed
function __bgCheckForMissingDeps()
{
	(
		bgTracingBanner=""
		source /usr/lib/bg_core.sh --minimal

		local deps="$(echo "$*" | sed -e 's/[ \t\n][ \t\n]*/\n/g' | sort | uniq)"
		local depsNeedingInstall=""
		local depsWithProblems=""
		local dep
		for dep in $deps; do
			local status=""
			if ! _bg_debug_isDependencyInstalled "$dep"; then
				depsNeedingInstall="$depsNeedingInstall${depsNeedingInstall:+ }$dep"
			fi
			shift
		done
		if [ "$depsNeedingInstall" ]; then
			cat <<-EOS
				warning: some packages are required by some vinstalled commands but are not installed.
				         Depending on why you are vinstalling these packages, you may or may not need to
				         install some or all of these packages.
				missing packages:
				         '$depsNeedingInstall'
			EOS
		fi
	)
}
export -f __bgCheckForMissingDeps

function _bg_debug_isDependencyInstalled()
{
	local dep="$1"
	# check if its virtually installed
	[[ :"$bgInstalledPkgNames": == :$dep: ]] && return 0

	local pkgMngr=""
	[ ! "$pkgMngr" ] && [ -f "/etc/centos-release" ] && pkgMngr="yum"
	[ ! "$pkgMngr" ] && [ -f "/etc/redhat-release" ] && pkgMngr="yum"
	[ ! "$pkgMngr" ] && [ -f "/etc/lsb-release" ]    && pkgMngr="apt"
	[ ! "$pkgMngr" ] && type -t apt-get &>/dev/null  && pkgMngr="apt"
	[ ! "$pkgMngr" ] && type -t yum &>/dev/null      && pkgMngr="apt"

	case $pkgMngr in
		apt) [[ "$(dpkg-query  -f '${db:Status-Status}\n' --show  "$dep"  2>/dev/null)" == "installed" ]] ;;
		yum) yum list installed "$dep" &>/dev/null ;;
		*) return 1
	esac
}


function _bg_debug_installDependency()
{
	local outFile=$(mktemp)
	local pkgMngr=""
	[ ! "$pkgMngr" ] && [ -f "/etc/centos-release" ] && pkgMngr="yum"
	[ ! "$pkgMngr" ] && [ -f "/etc/redhat-release" ] && pkgMngr="yum"
	[ ! "$pkgMngr" ] && [ -f "/etc/lsb-release" ]    && pkgMngr="apt"
	[ ! "$pkgMngr" ] && type -t apt-get &>/dev/null  && pkgMngr="apt"
	[ ! "$pkgMngr" ] && type -t yum &>/dev/null      && pkgMngr="apt"

	if [ ! "$pkgMngr" ]; then
		cat <<-EOS
			The bg-debugCntr script knows how to install packages using 'apt' or 'yum'
			but neither appear to be available in this environment.
			You can manually install the following dependency(ies) and then re-run this command.
			EOS
		local pkgName cmdName
		local -A cmdsByPkg=()
		for cmdName in "${!_bgRequiredDeps[@]}"; do
			cmdsByPkg["${_bgRequiredDeps[$cmdName]}"]+="$cmdName "
		done
		while [ $# -gt 0 ]; do
			pkgName="$1"; shift
			if [ ${#cmdsByPkg[@]} -gt 0 ]; then
				printf "   %-16s: needed for cmds '%s'\n" "$pkgName" "${cmdsByPkg[$pkgName]:-<unknown>}"
			else
				printf "   %-16s\n" "$pkgName"
			fi
		done
		return 1
	fi

	echo "installing required dependencies '$@'"
	local savedJCMode="${-//[^m]}"
	set +m
	(case $pkgMngr in
		apt) sudo apt-get install -y "$@" &>"$outFile"  ;;
		yum) sudo yum install -y  -q "$@" &>"$outFile"  ;;
	esac)&
	local pkgInstallPID=$!
	local spinner=('\' '|' '/' '-') count=0
	while kill -0 $pkgInstallPID 2>/dev/null; do
		((count++))
		printf "\033[?25l\033[500D${spinner[count %4]} installing... \033[?25h"
		sleep 0.2
	done
	printf "\033[500D\033[K\n"
	# wait should not block now and it will reurn the exit code of the pkgInstallPID
	if ! wait "$pkgInstallPID"; then
		cat "$outFile"
		printf "\npackage installation ended in error\n" >&2
	fi
	rm -f "$outFile"
	[ "$savedJCMode" ] && set -m
}



#################################################################################################################################
# Script Global Code
# Above this point this script should be only function definitions. Below is global code that will be executed
# when the external script is ran or sourced.

_bg_debugCntr_productionMode="$([ ! -f /etc/bgHostProductionMode ] || awk '/^[[:space:]]*mode[[:space:]]*[:=][[:space:]]*development/ {print "development"; exit}' /etc/bgHostProductionMode)"


# This is the init code for when the script is sourcing into the environment or being reloaded
if [ "$bgDebugCntrRunMode" != "extScript" ] && [ "$_bg_debugCntr_productionMode" == "development" ]; then
	while [ $# -gt 0 ]; do case $1 in
		--quick) _bgQuickFlag="--quick" ;;
		*)  break;
	esac; shift; done

	declare -gA _bgRequiredDeps=(
		[strings]="binutils"
		[gawk]="gawk"
		[git]="git"
	)
	declare -g _bgMissingDeps=()
	for _bgCmdName in "${!_bgRequiredDeps[@]}"; do
		! which $_bgCmdName &>/dev/null && _bgMissingDeps+=("${_bgRequiredDeps[$_bgCmdName]}")
	done
	[ ${#_bgMissingDeps[@]} -gt 0 ] && _bg_debug_installDependency "${_bgMissingDeps[@]}"

	# this is used in the cuiWinID of debug windows. The idea is that you can use it like $$ in scripts
	# to make sure a name is unque to a proc but it is stable for any proc ran in a particular term window.
	declare -gx bgTermID=$$

	# domData / awkData / plugins integration.
	# TODO: 2022-08 bobg: i dont think that this ever is true b/c this block is when we are being sourced so there will never be
	#       any vinstalled projects yet.
	if [ "$bgVinstalledSandbox" ] && [ -d "$bgVinstalledSandbox/.bglocal" ]; then
		declare -gx vinstallMeScopeFolder="$bgVinstalledSandbox/.bglocal/vinstall"
		mkdir -p "$vinstallMeScopeFolder"
	fi

	# banner is on by default
	export bgTracingBanner="on"

	# if this is a fresh OS and we are sourcing bg-debugCntr, attempt to vinstall bg_core and bg_dev
	if [ ! "$_bg_debugCntr_doneInit" ] && { [ ! -f "/usr/lib/bg_core.sh" ] || ! (source "/usr/lib/bg_core.sh" 2>/dev/null); }; then
		_bg_debugCntr_doneInit="1"
		declare bgDevPath="${BASH_SOURCE%/*}"
		[[ "$bgDevPath" != /* ]] && bgDevPath="$PWD/$bgDevPath"
		if [[ ! "$bgDevPath" =~ /bg-dev$ ]]; then
			echo "bg-core is not installed and bg-debugCntr is not being sourced from a bg-dev/ folder so I am not assuming that its parent is a sandbox containing bg-dev and bg-core. " >&2
		else
			declare bgCorePath="${bgDevPath/bg-dev/bg-core}"
			if [ ! -f "$bgCorePath/bg_core.sh" ]; then
				echo "bg-core is not installed and the path to a bg-core project could not be gleaned from the path where bg-debugCntr is being sourced from." >&2
			elif [ "$(type -t "$(basename $BASH_SOURCE)")" != "function" ]; then
				echo "error sourcing bg-debugCntr. bg-debugCntr is not a function now" >&2
			else
				sandboxPath="${bgCorePath%/*}"
				[ ! -d "$sandboxPath/.bglocal" ] && mkdir "$sandboxPath/.bglocal"
				_traceCntr "on:${sandboxPath}/.bglocal/bgtrace.out.${HOSTNAME#bgcore-}"
				_bgtrace "installing sandbox at '${bgCorePath%/*}'"
				bg-debugCntr vinstall $_bgQuickFlag "${bgCorePath%/*}"
				unset sandboxPath
			fi
			unset bgCorePath
		fi
		unset bgDevPath
	fi

	unset _bgQuickFlag

	# install the pre and post interactive command hooks by default.
	# See 'bg-debugCntr debugger bashCmdHooks on|off|status'
	_bashComandHooks on
fi


# We get to this point whenever the external script file is executed or sourced. In either case, the function
# by the same name should exist at this point so we can pass off the work to it.
# (either in the interactive bash environment or in the external cmd's execution child environment)
# The only caveat is that if there was a script error and the function did not get defined for any reason,
# we don't want to invoke that name because it would infinitely invoke the same external command and come back here.
if [ "$(type -t "$(basename $BASH_SOURCE)")" == "function" ]; then
	[ "$1" != "noop" ] && [ "$*" ] && $(basename $BASH_SOURCE) "$@"
else
	_assertError "function '$(basename $BASH_SOURCE)' not defined"
fi



# bgDebugCntrRunMode will only be defined while this global script code is running. When sourced functions
# run normally it will not be defined
unset bgDebugCntrRunMode