System.Data.SQLite


  #
  # NOTE: This procedure exports one or more commands from the specified
  #       namespace and imports them into the global namespace, optionally
  #       forgetting all previous imports from the specified namespace.
  #
  proc exportAndImportPackageCommands { namespace exports forget force } {
    #
    # NOTE: If the specified namespace is global, do nothing as this is a
    #       no-op.
    #
    if {[string length [string trimleft $namespace :]] == 0} then {return}

    #
    # NOTE: Forget any previous commands that were imported from
    #       this namespace into the global namespace?
    #
    if {$forget} then {
      namespace eval :: [list namespace forget [appendArgs $namespace ::*]]
    }

#
# NOTE: Use our own namespace here because even though we do not directly
#       support namespaces ourselves, we do not want to pollute the global
#       namespace if this script actually ends up being evaluated in Tcl.
#
namespace eval ::Eagle {
  #
  # NOTE: This procedure is used to log various stages of the C# compilation
  #       lifecycle.  Under normal circumstances, this procedure will not do
  #       anything.
  #
  proc csharpLog { string {object ""} } {
    #
    # NOTE: If the "enableCSharpLog" runtime option is enabled, this routine
    #       will emit log output somewhere; otherwise, it will do nothing.
    #
    if {[llength [info commands hasRuntimeOption]] > 0 && \
        [hasRuntimeOption enableCSharpLog]} then {
      #
      # NOTE: If the caller passed a valid opaque object handle, query its
      #       list of properties and emit them with the log output.
      #
      if {[llength [info commands object]] > 0 && \
          [isNonNullObjectHandle $object]} then {
        #
        # HACK: Attempt to dynamically query all public properties of the
        #       specified object -AND- add them to the log output.
        #
        set list null; set error null

        set code [object invoke -create -alias -flags +NonPublic \
            Eagle._Components.Private.MarshalOps ListProperties \
            "" $object null null true list error]

        #
        # HACK: Since -create was used above in the [object invoke] call,
        #       the "code" variable must be converted to a string before
        #       we can check it for success.
        #
        set code [getStringFromObjectHandle $code]

        if {$code eq "Ok"} then {
          #
          # HACK: In theory, at this point, the "list" variable must be
          #       a valid opaque object handle; however, to prevent any
          #       future issues with the ListProperties method check it
          #       just in case.
          #
          if {[isNonNullObjectHandle $list]} then {
            #
            # HACK: The [formatListAsDict] procedure will almost always
            #       be available at this point; however, we do not want
            #       to require it.
            #
            if {[llength [info commands formatListAsDict]] > 0} then {
              set suffix [formatListAsDict [$list ToString]]
            } else {
              set suffix [$list ToString]
            }
          } else {
            set suffix [appendArgs \
                "invalid property list for object \"" $object \"]
          }
        } else {
          set suffix [getStringFromObjectHandle $error]
        }

        set newString [appendArgs $string $suffix]
      } else {
        set newString $string
      }

      #
      # NOTE: If the "testCSharpLog" runtime option is enabled, emit the
      #       output to the test log.
      #
      if {[hasRuntimeOption testCSharpLog]} then {
        #
        # HACK: The [getTestChannelOrDefault] procedure will almost always
        #       be available at this point; however, we can work around the
        #       lack of it.
        #
        if {[llength [info commands getTestChannelOrDefault]] > 0} then {
          set channel [getTestChannelOrDefault]
        } else {
          if {[info exists ::test_channel]} then {
            set channel $::test_channel
          } else {
            set channel stdout
          }
        }

        #
        # HACK: The [tputs] procedure will almost always be available at
        #       this point; however, we can work around the lack of it.
        #
        set newString [appendArgs "---- " $newString \n]

        if {[llength [info commands tputs]] > 0} then {
          tputs $channel $newString
        } else {
          tqputs $channel $newString
        }
      } else {
        #
        # TODO: Is there a better place to send this log output when the
        #       test suite is not available?
        #
        tclLog $newString
      }
    }

    return ""
  }

  #
  # NOTE: This procedure is used to determine the fully qualified path to the
  #       .NET Core SDK.  An empty string will be returned to indicate an
  #       error.  This procedure should not raise script errors.
  #
  proc getDotNetCoreSdkPath {} {
    if {[catch {exec -- dotnet --info} info] == 0} then {
      csharpLog [appendArgs \
          "getDotNetCoreSdkPath ok:\n\t" \
          [string map [list \n \n\t] $info]]

      set info [string map [list \r\n \n] $info]

      if {[regexp -line -- \
          {^\s*Base Path:\s+([^\n]+)$} $info dummy path]} then {
        return [file normalize $path]
      }
    } else {
      csharpLog [appendArgs \
          "getDotNetCoreSdkPath error: " $info]
    }

    return ""
  }

  #
  # NOTE: This procedure is used to determine the fully qualified path to the
  #       directory containing the reference assemblies for the .NET Standard
  #       2.0.  An empty string will be returned to indicate an error.  This
  #       procedure should not raise script errors.
  #
  proc getDotNetStandardReferencePath {
          {packageVersion ""} {standardVersion ""} {useSdkVersion false} } {
    set path [getDotNetCoreSdkPath]

    if {[string length $path] > 0} then {
      if {[string length $standardVersion] == 0} then {
        if {!$useSdkVersion && \
            [info exists ::eagle_platform(runtimeVersion)]} then {
          set targetVersion $::eagle_platform(runtimeVersion)
        } else {
          set targetVersion [file tail $path]
        }

        if {[string match 3.* $targetVersion]} then {
          set standardVersion netstandard2.1
        } elseif {[string match 2.* $targetVersion]} then {
          set standardVersion netstandard2.0
        }
      }

      switch -exact -- $standardVersion {
        netstandard2.0 {
          set libraryDirectory [file normalize [file join [file dirname \
              $path] NuGetFallbackFolder netstandard.library]]

          set buildReferenceSubDirectory [file join build $standardVersion \
              ref]
        }
        netstandard2.1 {
          set libraryDirectory [file normalize [file join [file dirname \
              [file dirname $path]] packs NETStandard.Library.Ref]]

          set buildReferenceSubDirectory [file join ref $standardVersion]
        }
        default {
          #
          # TODO: Do something else here?  The version of the standard is
          #       not known.  Perhaps do some kind of search?
          #
          set libraryDirectory ""
          set buildReferenceSubDirectory ""
        }
      }

      if {[string length $libraryDirectory] > 0 && \
          [string length $buildReferenceSubDirectory] > 0} then {
        if {[string length $packageVersion] > 0} then {
          set assemblyDirectory [file normalize [file join \
              $libraryDirectory $packageVersion $buildReferenceSubDirectory]]

          if {[file exists $assemblyDirectory]} then {
            return $assemblyDirectory
          }
        } else {
          set globPathPattern [file join $libraryDirectory *]

          set maybeVersions [lsort -decreasing -command [list package vsort] \
              [lmap directory [glob -nocomplain -types {d} $globPathPattern] \
              { file tail $directory }]]

          foreach maybeVersion $maybeVersions {
            set assemblyDirectory [file normalize [file join \
                $libraryDirectory $maybeVersion $buildReferenceSubDirectory]]

            if {[file exists $assemblyDirectory]} then {
              return $assemblyDirectory
            }
          }
        }
      }
    }

    return ""
  }

  #
  # NOTE: This procedure is used to obtain a test program for use with the
  #       C# compiler.  Upon success, the return value will be a list with
  #       two elements.  The first element will be the name of the C# class
  #       to be compiled.  The second element will be the C# program text.
  #       Upon failure, the return value will be an empty list.
  #
  proc getCSharpTestProgram { {name ""} } {
    set prefix Test

    if {[llength [info commands object]] > 0} then {
      set id [object invoke Interpreter.GetActive NextId]

      set className [appendArgs \
          $prefix Namespace $id [object invoke Type Delimiter] \
          $prefix Class $id]
    } else {
      set id [string trimleft [expr {random()}] -]

      set className [appendArgs \
          $prefix Namespace $id . $prefix Class $id]
    }

    return [list $className [subst {
      using System;

      namespace ${prefix}Namespace${id}
      {
        public static class ${prefix}Class${id}

      return false
    }

    unset -nocomplain results local_errors

    if {[catch {
      compileCSharp [lindex $program 1] true false true results local_errors
    } code]} then {
      set errors [list [appendArgs \
          "caught error while compiling \"" $name "\" test program: " \
          $code]]

      return false
    }

    if {$code ne "Ok"} then {
      set errors [list [appendArgs \
          "errors from compilation of \"" $name "\" test program: " \
          [expr {[info exists local_errors] ? $local_errors : $code}]]]

      return false
    }

    if {[llength [info commands object]] == 0} then {
      set errors [list [appendArgs \
          "cannot execute \"" $name \
          "\" test program, missing \"object\" command"]]

      return false
    }

    if {[catch {
      object invoke [lindex $program 0] Main null
    } exitCode]} then {

      #       via the global array element "csharpOptions", if any.
      #
      foreach csharpOption $csharpOptions {
        if {[string length $result] > 0} then {
          append result " "
        }

        append result $prefix $csharpOption
      }
    }

    return $result
  }

  #

  #       platform normalized results.
  #
  proc runDotNetCSharpCommand { command } {
    #
    # NOTE: Evaluate the [exec] command constructed by our caller, in their
    #       context, and return the results, with line-endings normalized.
    #
    csharpLog [appendArgs "running C# command: " $command]
    return [string map [list \r\n \n] [uplevel 1 $command]]
  }

  #
  # NOTE: This procedure is used to extract the C# compiler error messages
  #       from its results.  An empty list will be returned if the errors
  #       cannot be determined for some reason.  This procedure should not

      # NOTE: Append to the list of errors.
      #
      lappend local_errors "cannot compile, missing \"object\" command"

      #
      # NOTE: Return the overall result to the caller.
      #
      return [list $code]
    }

    #
    # NOTE: Create the C# code provider object (i.e. the compiler).
    #
    set provider [object create -alias Microsoft.CSharp.CSharpCodeProvider]

    #
    # NOTE: Create the object that provides various parameters to the C#
    #       code provider (i.e. the compiler options).
    #
    set parameters [object create -alias \
        System.CodeDom.Compiler.CompilerParameters]

    #
    # NOTE: Do we not want to persist the generated assembly to disk?
    #       Either way, we must make sure the temporary file names used
    #       are determinstic (i.e. from our perspective, so that we can
    #       delete them later).
    #
    $parameters OutputAssembly [set outputFileName [appendArgs [set \
        tempName(1) [file tempname]] .dll]]

    if {$memory} then {
      $parameters GenerateInMemory true



    }

    #
    # NOTE: Use a try/finally block to cleanup temporary files.
    #
    try {
      #

        upvar 1 $resultsVarName results
      }

      #
      # NOTE: Attempt to compile the specified string as C# and capture the
      #       results into the variable provided by the caller.
      #
      csharpLog "compileViaCSharpCodeProvider parameters: " $parameters

      try {
        if {[info exists ::compileCSharp(preProcess)]} then {
          eval $::compileCSharp(preProcess); # pre-compilation HOOK
        }

        set results [$provider \
            -alias CompileAssemblyFromSource $parameters $string]
      } finally {
        if {[info exists ::compileCSharp(postProcess)]} then {
          eval $::compileCSharp(postProcess); # post-compilation HOOK
        }
      }

      #
      # NOTE: We no longer need the C# code provider object (i.e. the
      #       compiler); therefore, dispose it now.
      #
      unset provider; # dispose

      #
      unset errors; # dispose

      #
      # HACK: *BREAKING CHANGE* If there is an output file name, return it
      #       as well; otherwise, just return success.
      #
      if {!$memory && [string length $outputFileName] > 0} then {
        #
        # NOTE: Return a two element list: the first element is the overall
        #       result and the second element is the output file name.
        #
        return [list $code $outputFileName]
      } else {
        #
        # NOTE: Return the overall result to the caller.
        #
        return [list $code]
      }
    } finally {
      #
      # NOTE: Make sure the created temporary files are cleaned up unless we
      #       are forbidden from doing so.
      #
      if {![info exists ::no(deleteCompileCSharpFiles)]} then {
        #
        # NOTE: Make sure the dummy temporary files are cleaned up.
        #
        if {[array exists tempName]} then {
          foreach tempFileName [array values tempName] {
            if {[string length $tempFileName] > 0} then {
              if {$memory} then {
                #
                # NOTE: When operating in in-memory generation mode, delete
                #       all the temporary files associated with the original
                #       allocated temporary name.  This includes the ".dll",
                #       the ".pdb" (if any), and the empty "dummy" file that
                #       contains nothing.
                #
                foreach deleteFileName [glob -nocomplain \
                    [appendArgs [file normalize $tempFileName] *]] {
                  if {[file exists $deleteFileName]} then {
                    catch {file delete $deleteFileName}
                  }
                }
              } else {
                #
                # NOTE: Delete the empty "dummy" file that contains nothing.
                #       The actual compiled assembly has a ".dll" suffix and
                #       its symbols, if any, have a ".pdb" suffix.
                #
                catch {file delete $tempFileName}
              }
            }
          }
        }
      }
    }
  }

  #

      # NOTE: Append to the list of errors.
      #
      lappend local_errors "cannot compile, C# compiler was not found"

      #
      # NOTE: Return the overall result to the caller.
      #
      return [list $code]
    }

    #
    # NOTE: Insert the [exec] command before the command line arguments.
    #       The -success option is not used here because we want to handle
    #       errors (only) by processing the compiler output.
    #

      #
      # NOTE: Attempt to compile the temporary file as C# and capture the
      #       results into the variable provided by the caller.  Since the
      #       results are text, normalize line endings before extracting
      #       the compiler errors and/or warnings.
      #
      try {
        if {[info exists ::compileCSharp(preProcess)]} then {
          eval $::compileCSharp(preProcess); # pre-compilation HOOK
        }

        set local_results [runDotNetCSharpCommand $command]
      } finally {
        if {[info exists ::compileCSharp(postProcess)]} then {
          eval $::compileCSharp(postProcess); # post-compilation HOOK
        }
      }

      #
      # NOTE: Extract the compiler errors (which may be empty).
      #
      set errors [extractCSharpErrors $sourceFileName $local_results]

      #

        }
      } else {
        #
        # NOTE: If the generated assembly was supposed to be loaded into
        #       memory, try to do that now.
        #
        if {$memory} then {
          #
          # HACK: In order to load the newly compiled assembly into memory,
          #       the [object] command is required.  Generally, this is not
          #       an issue; however, if the [object] command is not present
          #       in the current interpreter (i.e. because it was explicitly
          #       removed, etc), we cannot succeed.
          #
          if {[llength [info commands object]] > 0} then {
            #
            # NOTE: At this point, the output file must exist.  If not,
            #       something is very wrong (i.e. C# compilation failed
            #       and we somehow did not detect it).
            #
            if {[string length $outputFileName] > 0 && \
                [file exists $outputFileName]} then {
              try {
                set stream [object create \
                    System.IO.FileStream $outputFileName Open Read None]

                object load -loadtype Stream $stream
              } finally {
                if {[info exists stream]} then {
                  unset -nocomplain stream
                }
              }

              #
              # NOTE: Compilation and loading of the assembly succeeded.
              #
              set code Ok
            } else {
              #
              # NOTE: Compilation of the assembly may not have succeeded
              #       because the output file is missing.
              #
              set code Error

              #
              # NOTE: Prepare to transfer error messages to the caller.
              #
              if {[string length $errorsVarName] > 0} then {
                upvar 1 $errorsVarName local_errors
              }

              #
              # NOTE: Inform caller why we could not load the compiled
              #       assembly into memory.
              #
              lappend local_errors [appendArgs \
                  "cannot load compiled assembly \"" $outputFileName \
                  "\" into memory, compiled assembly file is missing"]
            }
          } else {
            #
            # NOTE: Compilation of the assembly succeeded; however, it
            #       cannot be loaded, due to the [object] command being
            #       missing.
            #
            set code Error

            #
            # NOTE: Prepare to transfer error messages to the caller.
            #
            if {[string length $errorsVarName] > 0} then {
              upvar 1 $errorsVarName local_errors
            }

            #
            # NOTE: Inform caller why we could not load the compiled
            #       assembly into memory.
            #
            lappend local_errors [appendArgs \
                "cannot load compiled assembly \"" $outputFileName \
                "\" into memory, missing \"object\" command"]
          }
        } else {
          #
          # NOTE: Compilation of the assembly succeeded -AND- there is
          #       no need to load it into memory.
          #
          set code Ok
        }
      }
    } finally {
      #
      # NOTE: Make sure the created temporary files are cleaned up unless we
      #       are forbidden from doing so.
      #
      if {![info exists ::no(deleteCompileCSharpFiles)]} then {
        #
        # NOTE: Delete the temporary file name used to hold the source code.
        #
        if {[string length $sourceFileName] > 0 && \
            [file exists $sourceFileName]} then {
          catch {file delete $sourceFileName}
        }

        #
        # NOTE: Make sure the dummy temporary files are cleaned up.  This is
        #       done only if the caller requested in-memory generation.
        #
        if {[array exists tempName]} then {
          foreach tempFileName [array values tempName] {
            if {[string length $tempFileName] > 0} then {
              if {$memory} then {
                #
                # NOTE: When operating in in-memory generation mode, delete
                #       all the temporary files associated with the original
                #       allocated temporary name.  This includes the ".dll",
                #       the ".pdb" (if any), and the empty "dummy" file that
                #       contains nothing.
                #
                foreach deleteFileName [glob -nocomplain \
                    [appendArgs [file normalize $tempFileName] *]] {
                  if {[file exists $deleteFileName]} then {
                    catch {file delete $deleteFileName}
                  }
                }
              } else {
                #
                # NOTE: Delete the empty "dummy" file that contains nothing.
                #       The actual compiled assembly has a ".dll" suffix and
                #       its symbols, if any, have a ".pdb" suffix.
                #
                catch {file delete $tempFileName}
              }
            }
          }
        }
      }
    }

    #
    # HACK: *BREAKING CHANGE* If there is an output file name, return it
    #       as well; otherwise, just return success.
    #
    if {!$memory && [string length $outputFileName] > 0} then {
      #
      # NOTE: Return a two element list: the first element is the overall
      #       result and the second element is the output file name.
      #
      return [list $code $outputFileName]
    } else {
      #
      # NOTE: Return the overall result to the caller.
      #
      return [list $code]
    }
  }

  #
  # NOTE: This procedure is used to dynamically compile arbitrary C# code
  #       from within a script.  This procedure was originally designed to
  #       be used by the test suite; however, it can be quite useful in

    if {[isEagle] && [isMono]} then {
      #
      # HACK: Assume that Mono is somewhere along the PATH.
      #
      lappend command mono \
          [appendArgs \" [file nativename [info nameofexecutable]] \"]
    } else {
      #
      # NOTE: Assumes that the executable (e.g. "dotnet", "EagleShell",
      #       etc) is somewhere along the PATH -OR- the value returned
      #       from [info nameofexecutable] is fully qualified.
      #
      lappend command \
          [appendArgs \" [file nativename [info nameofexecutable]] \"]

      #
      # HACK: When running on .NET Core, we need to insert the "exec"
      #       command line argument followed by our assembly name.
      #
      if {[isEagle] && [isDotNetCore]} then {
        lappend command exec

      }
    }

    #
    # NOTE: Add command line arguments to the shell command, if any.
    #
    if {[llength $args] > 0} then {
      #
      # HACK: For reasons which are still unexplained, .NET Core seems
      #       to have trouble with preserving an argument value if it
      #       is an empty string (i.e. they are simply dropped).  Work
      #       around this.  Nothing fancy should be done here.  Simply
      #       using a single space instead seems to work around their
      #       problem (whatever it actually is).  Please refer to the
      #       following GitHub issue for more information:
      #
      #       https://github.com/dotnet/cli/issues/8892
      #
      if {[isEagle] && [isDotNetCore]} then {
        foreach arg $args {
          #
          # HACK: For now, only handle the cases where the argument is
          #       specified as something like {""}.
          #
          if {$arg eq "\"\""} then {
            lappend command "\" \""
          } else {
            lappend command $arg
          }
        }
      } else {
        eval lappend command $args
      }
    }

    #
    # NOTE: Finally, execute the resulting [exec] command in the context
    #       of the caller, returning its result.
    #
    return [uplevel 1 $command]

  }

  #
  # NOTE: This procedure returns non-zero if the specified value can be used
  #       as an opaque object handle.
  #
  proc isObjectHandle { value } {
    if {[catch {object exists $value} result] == 0 && $result} then {
      return true
    }

    set pattern [string map \
        [list \\ \\\\ * \\* - \\- ? \\? \[ \\\[ \] \\\]] $value]

    set objects [info objects $pattern]

    if {[llength $objects] == 1 && [lindex $objects 0] eq $value} then {
      return true
    }

    return false
  }

  #
  # NOTE: This procedure returns non-zero if the specified value can be used
  #       as an opaque object handle -AND- the value does not represent a null
  #       object value.
  #
  proc isNonNullObjectHandle { value } {
    if {![isObjectHandle $value]} then {
      return false
    }

    global null

    if {$value eq $null} then {
      return false
    }

    if {[catch {object isnull $value} result] == 0 && $result} then {
      return false
    }

    return true
  }

  #
  # NOTE: This procedure returns non-zero if the specified name represents
  #       a valid CLR type name.
  #
  proc isManagedType { name } {

  proc canGetManagedType { name {varName ""} } {
    if {[llength [info commands object]] > 0} then {
      if {![isObjectHandle $name]} then {
        set cultureInfo [object invoke Interpreter.GetActive CultureInfo]
        set type null

        set code [object invoke -create -alias -flags +NonPublic \
            Value GetAnyType "" $name null null None $cultureInfo type]

        if {[$code ToString] eq "Ok"} then {
          if {[string length $varName] > 0} then {
            upvar 1 $varName typeName
          }

          set typeName [$type AssemblyQualifiedName]

        set key null; object invoke Interpreter.GetActive \
            Host.ReadKey true key
      }

      eval lappend command #help $args; debug icommand $command
    }

    proc quit { args } {
      # <help>
      # Can be used to exit the interactive shell.  It does this by calling
      # the built-in [exit] command.  It is allowed to perform cleanup and
      # maintenance tasks.
      # </help>

      catch {
        host result Break [appendArgs \
            "WARNING: This command is not (simply) a synonym for the " \
            "built-in [exit] command, primarily because it is allowed " \
            "to perform additional cleanup and maintenance tasks."]
      }

      eval exit $args
    }

    proc #support {} {
      # <help>
      # Shows the requirements for obtaining commercial support and/or
      # redirects to the appropriate web site using the default browser.
      # </help>

#
# NOTE: Use our own namespace here because even though we do not directly
#       support namespaces ourselves, we do not want to pollute the global
#       namespace if this script actually ends up being evaluated in Tcl.
#
namespace eval ::Eagle {
  proc dumpState {} {
    set result [list]

    foreach varName [lsort [uplevel 1 [list info vars]]] {
      if {[uplevel 1 [list array exists $varName]]} then {
        lappend result $varName [list \
            array [uplevel 1 [list array get $varName]]]
      } else {
        lappend result $varName [list \
            scalar [uplevel 1 [list set $varName]]]
      }
    }

    return $result
  }

  proc trawputs { channel string } {
    #
    # NOTE: If an output channel was provided, use it; otherwise, ignore
    #       the message.
    #
    if {[string length $channel] > 0} then {
      #

    if {![info exists ::test_run_id]} then {
      set ::test_run_id [getNewTestRunId]
    }

    return [appendArgs \
        "**** START OF TEST LOG \"" $::test_run_id "\" ****\n"]
  }

  proc extractTestRunIdFromLogStartSentry { sentry } {
    set prefix {^\*\*\*\* START OF TEST LOG "}
    set suffix {" \*\*\*\*\n$}

    set pattern(1) [appendArgs $prefix {([0-9A-F]{56})} $suffix]; # Tcl

    if {[regexp -- $pattern(1) $sentry dummy result]} then {
      return $result
    }

    set pattern(2) [appendArgs $prefix {([0-9A-F]{64})} $suffix]; # Eagle

    if {[regexp -- $pattern(2) $sentry dummy result]} then {
      return $result
    }

    return <none>
  }

  proc doesTestLogHaveStartSentry {} {
    set fileName [getTestLog]

    if {[string length $fileName] > 0} then {
      if {[doesTestLogFileExist $fileName]} then {
        set sentry [string trim [getTestLogStartSentry]]

        if {[string length $sentry] > 0} then {
          set data [readFile $fileName]

          if {[string first $sentry $data] != -1} then {
            return true
          }
        }
      }
    }

    return false
  }

  proc didTestLogHaveStartSentry { sentry varName } {
    if {[info exists ::test_log_sentry]} then {
      if {$::test_log_sentry ne $sentry} then {
        upvar 1 $varName error

        set error [appendArgs \
            "---- test log start sentry mismatch error, was \"" \
            [extractTestRunIdFromLogStartSentry $::test_log_sentry] \
            "\", now \"" [extractTestRunIdFromLogStartSentry $sentry] \
            \"\n]
      }

      return true
    } else {
      return false
    }
  }

  proc setTestLogStartSentry { sentry varName } {
    upvar 1 $varName result

    if {[info exists ::test_log_sentry]} then {
      set result [appendArgs \
          "---- test log start sentry reinitialized to \"" \
          [extractTestRunIdFromLogStartSentry $sentry] \
          "\", was \"" [extractTestRunIdFromLogStartSentry \
          $::test_log_sentry] \"\n]
    } else {
      set result [appendArgs \
          "---- test log start sentry initialized to \"" \
          [extractTestRunIdFromLogStartSentry $sentry] \
          \"\n]
    }

    set ::test_log_sentry $sentry
  }

  proc tlog { string } {
    #
    # NOTE: If a test log file was configured, use it; otherwise, ignore the
    #       message.
    #
    set fileName [getTestLog]

          set newString $::test_log_queue($entry)

          if {[string length $newString] > 0} then {
            if {![doesTestLogFileExist $fileName]} then {
              set sentry [getTestLogStartSentry]

              if {[string length $sentry] > 0} then {
                #
                # BUGFIX: At this point, there should not be any record of a
                #         previously used test log sentry.  If there is, do
                #         not append a test log sentry again because the test
                #         log file may have been deleted and we need to make
                #         sure the test log is not considered as "complete".
                #
                if {[didTestLogHaveStartSentry $sentry sentryError]} then {
                  if {[info exists sentryError]} then {
                    appendSharedLogFile $fileName $sentryError
                  }
                } else {
                  setTestLogStartSentry $sentry sentryResult

                  appendSharedLogFile $fileName $sentry

                  if {[info exists sentryResult]} then {
                    appendSharedLogFile $fileName $sentryResult
                  }
                }
              }
            }

            appendSharedLogFile $fileName $newString
          }

          unset ::test_log_queue($entry)

      # NOTE: If an empty string is supplied by the caller, do nothing.
      #
      if {[string length $string] > 0} then {
        if {![doesTestLogFileExist $fileName]} then {
          set sentry [getTestLogStartSentry]

          if {[string length $sentry] > 0} then {
            #
            # BUGFIX: At this point, there should not be any record of a
            #         previously used test log sentry.  If there is, do
            #         not append a test log sentry again because the test
            #         log file may have been deleted and we need to make
            #         sure the test log is not considered as "complete".
            #
            if {[didTestLogHaveStartSentry $sentry sentryError]} then {
              if {[info exists sentryError]} then {
                appendSharedLogFile $fileName $sentryError
              }
            } else {
              setTestLogStartSentry $sentry sentryResult

              appendSharedLogFile $fileName $sentry

              if {[info exists sentryResult]} then {
                appendSharedLogFile $fileName $sentryResult
              }
            }
          }
        }

        appendSharedLogFile $fileName $string
      }
    }
  }

          set result [join [split $result] " && "]
        }
      }
    }

    return $result
  }

  proc isCorePublicKeyToken { publicKeyToken } {
    #
    # HACK: This list of "well-known" public key tokens is hard-coded.
    #
    set publicKeyTokens [list \
        29c6297630be05eb 1e22ec67879739a2 358030063a832bc3]

    if {[isEagle]} then {
      set expr {$publicKeyToken in $publicKeyTokens}

      if {[expr $expr]} then {
        return true
      }
    } else {
      if {[lsearch -exact $publicKeyTokens $publicKeyToken] != -1} then {
        return true
      }
    }

    return false
  }

  proc fixTimingConstraints { constraints } {
    #
    # HACK: In Eagle, when the right test constraint is present, *any* tests
    #       where PASSED / FAILED results can vary non-deterministically due
    #       to timing issues (e.g. performance) are forbidden from causing
    #       the overall test run to fail.
    #
    if {[isEagle]} then {
      if {[info exists ::no(failTimingTests)] || \
          [haveConstraint officialStableReleaseInProgress]} then {
        return [fixConstraints [concat $constraints [list fail.false]]]
      } else {
        return [fixConstraints $constraints]
      }
    } else {
      return [fixConstraints $constraints]
    }
  }

  proc testDebugBreak {} {
    if {[isEagle]} then {

    }

    return $error
  }

  proc calculateBogoCops { {milliseconds 2000} {legacy false} } {
    #
    # NOTE: Verify that the number of milliseconds requested is greater
    #       than zero.
    #
    if {$milliseconds <= 0} then {
      unset -nocomplain ::test_suite_running
      error "number of milliseconds must be greater than zero"
    }

    #
    # HACK: Different techniques are used to calculate the performance of
    #       the machine for Tcl and Eagle.
    #
    if {!$legacy && [isEagle]} then {
      #
      # BUGBUG: Tcl 8.4 does not like this expression (and Tcl tries to
      #         compile it even though it will only actually ever be


      #         evaluated in Eagle).
      #
      set expr {[catch {

        string first -timeout [time nop -1 ---]

      } timeout] in [list 0 2] && $timeout != -1}



      #


      # HACK: Attempt to determine if the "-timeout" option for [time] is



      #       available.  If so, use it.
      #


      if {[expr $expr]} then {

        set code [catch {
          #




          # NOTE: This is the most robust method, i.e. use the "-timeout"






          #       option to the [time] command.
          #







          set before [info cmdcount]
          catch {time {nop} -1 -timeout $milliseconds}; # internal loop.
          set after [info cmdcount]

          #
          # HACK: Mono has a bug that results in excessive trailing zeros
          #       here (Mono bug #655780).
          #
          if {[isMono]} then {
            expr {double(($after - $before) / ($milliseconds / 1000.0))}
          } else {
            expr {($after - $before) / ($milliseconds / 1000.0)}
          }
        } result]

        #
        # NOTE: If we failed above, return an obviously invalid result
        #       instead.
        #
        if {$code == 0} then {
          return $result
        } else {
          return 0
        }
      } else {
        #
        # HACK: This calculation method (i.e. using [after] to cancel the
        #       [time] command after the specified number of milliseconds)
        #       is no longer necessary as of Beta 45; however, it will be
        #       retained for backward compatibility with previous releases
        #       solely for the purpose of running comparative benchmarks.
        #
        # NOTE: Save the current readiness limit for later restoration
        #       and then set the current readiness limit to always check
        #       the interpreter readiness (default).  If this was not
        #       done, the [interp cancel] command in this procedure may
        #       have no effect, which could cause this procedure to run
        #       forever.
        #
        set readylimit [interp readylimit {}]
        interp readylimit {} 0

        try {
          #
          # NOTE: Save the current background error handler for later
          #       restoration and then reset the current background
          #       error handler to nothing.
          #
          set bgerror [interp bgerror {}]
          interp bgerror {} ""

          try {
            #
            # NOTE: Save the current [after] flags for later restoration
            #       and then reset them to process events immediately.
            #
            set flags [after flags]
            after flags =Immediate

            try {
              set code [catch {
                #
                # NOTE: First, make sure that the [after] event queue
                #       for the interpreter is totally empty.
                #
                catch {foreach id [after info] {after cancel $id}}

                #
                # NOTE: Schedule the event to cancel the script we are
                #       about to evaluate, capturing the name so we can
                #       cancel it later, if necessary.
                #
                set event [after $milliseconds [list interp cancel]]

                #
                # HACK: There is a potential "race condition" here.  If the
                #       specified number of milliseconds elapses before (or
                #       after) entering the [catch] script block (below)
                #       then the resulting script cancellation error will
                #       not be caught and we will be unable to return the
                #       correct result to the caller.
                #
                set before [info cmdcount]
                catch {time {nop} -1}; # uses the [time] internal busy loop.
                set after [info cmdcount]

                #
                # HACK: Mono has a bug that results in excessive trailing
                #       zeros here (Mono bug #655780).
                #
                if {[isMono]} then {
                  expr {double(($after - $before) / ($milliseconds / 1000.0))}
                } else {
                  expr {($after - $before) / ($milliseconds / 1000.0)}
                }
              } result]

              #
              # NOTE: If we failed due to the race condition explained
              #       above, return an obviously invalid result instead.
              #
              if {$code == 0} then {
                return $result
              } else {
                return 0
              }
            } finally {
              if {[info exists event]} then {
                catch {after cancel $event}
              }

              after flags [appendArgs = $flags]
            }
          } finally {
            interp bgerror {} $bgerror
          }
        } finally {
          interp readylimit {} $readylimit
        }
      }
    } else {
      #
      # NOTE: Record the initial Tcl command count.
      #
      set before [info cmdcount]

      # NOTE: Check each candidate Tcl shell and query its fully
      #       qualified path from it.  If it cannot be executed,
      #       we know that candidate Tcl shell is not available.
      #
      if {![info exists ::no(getTclExecutableForTclShell)]} then {
        foreach shell $shells {
          if {[catch {
            getTclExecutableForTclShell $shell [getTclShellVerbosity]
          } executable] == 0 && $executable ne "error" && \
              ![string match "error: *" $executable]} then {
            #
            # NOTE: It looks like this Tcl shell is available.
            #       Return the fully qualified path to it now.
            #
            return $executable
          }
        }
      }
    }

    #
    # NOTE: Return the fallback default.
    #
    return tclsh
  }

  proc getTemporaryPath { {usable true} } {
    #
    # NOTE: Build the list of "temporary directory" override
    #       environment variables to check.
    #
    set names [list]

    foreach name [list \
        EAGLE_TEST_TEMP EAGLE_TEMP XDG_RUNTIME_DIR TEMP TMP] {
      #
      # NOTE: Make sure we handle all the reasonable "cases" of
      #       the environment variable names.
      #
      lappend names [string toupper $name] [string tolower $name] \
          [string totitle $name]
    }

    #
    # NOTE: Check if we can use any of the environment variables.
    #
    foreach name $names {
      set value [getEnvironmentVariable $name]

      #
      # NOTE: First, make sure the environment variable was actually
      #       set to something.
      #
      if {[string length $value] > 0} then {
        #
        # NOTE: Next, when the "usable" argument is non-zero, attempt
        #       to make sure the returned temporary path is actually
        #       an existing directory, writable by us.
        #
        if {$usable} then {
          if {[file isdirectory $value] && [file writable $value]} then {
            return [file normalize $value]
          }
        } else {
          return [file normalize $value]
        }
      }
    }

    if {[isEagle] && [llength [info commands object]] > 0} then {
      #
      # NOTE: Eagle fallback, use whatever is reported by the
      #       underlying framework and/or operating system.

    } else {
      #
      # NOTE: Use the default test suite name for native Tcl.
      #
      return "Eagle Test Suite for Tcl"
    }
  }

  proc getTestSuiteFullName {} {
    if {[isEagle]} then {
      set fileName [probeForScriptFileName [list \
          [file join * prologue.eagle] [file join * epilogue.eagle] \
          [file join * Test1.0 *]]]
    } else {
      set fileName ""
    }

    if {[string length $fileName] == 0} then {
      if {[info exists ::test_suite_file]} then {
        set fileName $::test_suite_file
      }
    }

    if {[string length $fileName] == 0} then {
      set fileName [info script]
    }

    if {[string length $fileName] == 0} then {
      set fileName <none>
    }

    set suiteName [getTestSuite]

    if {[string length $suiteName] == 0} then {
      set suiteName <none>
    }

    return [appendArgs $fileName " (" $suiteName )]
  }

  proc getTestMachine {} {
    #
    # NOTE: Determine the effective test machine and return it.  If the
    #       test machine cannot be determined, return an empty string.
    #
    if {[info exists ::test_flags(-machine)] && \

    #
    # NOTE: Verify that the global test path variable is available.
    #
    if {![info exists ::test_path]} then {
      error "cannot run test prologue, \"::test_path\" must be set"
    }

    #
    # NOTE: Reset the primary test suite file name to our caller.
    #
    if {![info exists ::no(testSuiteFile)]} then {
      set ::test_suite_file [info script]
    }

    #
    # HACK: We do not want to force every third-party test suite
    #       to come up with a half-baked solution to finding its
    #       own files.
    #
    if {![info exists ::no(prologue.eagle)] && ![info exists ::path]} then {
      set ::path [file normalize [file dirname [info script]]]

  proc runTestEpilogue {} {
    #
    # NOTE: Verify that the global test path variable is available.
    #
    if {![info exists ::test_path]} then {
      error "cannot run test epilogue, \"::test_path\" must be set"
    }

    #
    # NOTE: Reset the primary test suite file name to our caller.
    #
    if {![info exists ::no(testSuiteFile)]} then {
      set ::test_suite_file [info script]
    }

    #
    # NOTE: Evaluate the standard test epilogue in the context of
    #       the caller.
    #
    uplevel 1 [list source [file join $::test_path epilogue.eagle]]

      #       test was skipped.  If the return code was 4 (i.e. continue),
      #       that indicates the test results should be highlighted in
      #       dark yellow -AND- that the test should still be considered
      #       successful because failures are being ignored for it.
      #
      set tresultCode $code

      if {$code == 3 || $code == 5} then {
        set code 0; set error false
      } elseif {$code == 4} then {
        set code 0
      }

      #
      # NOTE: If the return code from the test command indicates success

          tputs $::test_channel [appendArgs \
              "ERROR (runTest): " $result \n]
        }
      }

      unhookPuts
    }

    #
    # HACK: Return an empty string here just in case we are being called
    #       via the [testShim] procedure.  Doing this should prevent any
    #       superfluous output from being displayed via [host result] in
    #       the outermost call to this procedure.
    #
    return ""
  }

  proc testShim { args } {
    #
    # NOTE: Call the original (saved) [test] command, wrapping it in
    #       our standard [runTest] wrapper.
    #
    uplevel 1 [list runTest [concat ::savedTest $args]]; return ""
  }

  proc tsource { fileName {prologue true} {epilogue true} } {
    #
    # NOTE: Run the test prologue in the context of the caller (which
    #       must be global)?
    #

      if {![info exists ::no(uncountedProcesses)]} then {
        lappend array(uncounted,$index) processes
      }
    }
  }

  proc reportTestStatistics {
          channel fileName stop statsVarName filesVarName {quiet false} } {
    set statistics [list afters variables commands procedures namespaces \
        files temporaryFiles channels aliases interpreters environment \
        loaded]

    if {[isEagle]} then {
      #
      # TODO: For now, tracking "leaked" assemblies is meaningless because

    #
    # NOTE: Show what leaked, if anything.
    #
    set count 0; upvar 1 $statsVarName array

    foreach statistic $statistics {
      if {![info exists array($statistic,after)]} then {
        if {!$quiet} then {
          tputs $channel [appendArgs "==== \"" $fileName "\" MISSING " \
              $statistic " AFTER\n"]
        }

        continue
      }

      if {![info exists array($statistic,before)]} then {
        if {!$quiet} then {
          tputs $channel [appendArgs "==== \"" $fileName "\" MISSING " \
              $statistic " BEFORE\n"]
        }

        continue
      }

      if {$array($statistic,after) > $array($statistic,before)} then {
        lappend array(statistics,leaked) $statistic

        if {!$quiet} then {
          tputs $channel [appendArgs "==== \"" $fileName "\" LEAKED " \
              $statistic \n]
        }

        if {[info exists array($statistic,before,list)]} then {
          if {!$quiet} then {
            tputs $channel [appendArgs "---- " $statistic " BEFORE: " \
                [formatList $array($statistic,before,list)] \n]
          }
        }

        if {[info exists array($statistic,after,list)]} then {
          if {!$quiet} then {
            tputs $channel [appendArgs "---- " $statistic " AFTER: " \
                [formatList $array($statistic,after,list)] \n]
          }
        }

        if {[info exists array(uncounted,before)] && \
            [lsearch -exact $array(uncounted,before) $statistic] != -1} then {
          continue
        }

    if {$count > 0 && \
        [lsearch -exact $fileNames [file tail $fileName]] == -1} then {
      lappend fileNames [file tail $fileName]
    }

    #
    # NOTE: Disable test suite interaction in "quiet" mode.  Just return the
    #       leak count.
    #
    if {!$quiet} then {
      #
      # NOTE: If we are supposed to stop or break into the debugger whenever
      #       a leak is detected, do it now.
      #
      if {$count > 0} then {
        #
        # BUGFIX: Is we are already stopping (e.g. due to a test failure),
        #         do not try to stop again.
        #
        if {!$stop && [isStopOnLeak]} then {
          tresult Error "OVERALL RESULT: STOP-ON-LEAK\n"

          unset -nocomplain ::test_suite_running
          error ""; # no message
        } elseif {[isBreakOnLeak]} then {
          testDebugBreak
        }
      }
    }

    return [list leak $count]
  }

  proc formatList { list {default ""} {columns 1} } {
    if {[catch {
      set result ""
      set count 1

            Eagle._Components.Private.TestOps ShouldWriteTestData "" $code
      } writeTestData] == 0 && $writeTestData} then {
        return false
      }

      return true
    }

    proc probeForScriptFileName { {excludePatterns ""} {overridePatterns ""} } {
      if {[llength [info commands object]] > 0 && [catch {
        set locations [object invoke -alias -flags +NonPublic \
            Interpreter.GetActive ScriptLocations]

        set count [$locations Count]

        for {set index 0} {$index < $count} {incr index} {
          set location [$locations -alias Peek $index]

          if {[isNonNullObjectHandle $location]} then {
            set locationFileName [file normalize [$location FileName]]

            if {[string length $locationFileName] > 0} then {
              if {[llength $overridePatterns] > 0 && \
                  [lsearch -inverse -glob -- \
                      $overridePatterns $locationFileName] != -1} then {
                return $locationFileName
              }

              if {[llength $excludePatterns] == 0 || \
                  [lsearch -inverse -glob -- \
                      $excludePatterns $locationFileName] == -1} then {
                return $locationFileName
              }
            }
          }
        }

        return ""
      } result] in [list 0 2]} then {
        return $result
      }

      return ""
    }

    proc tresult { code result } {
      host result $code $result; tlog $result
    }

    proc getPassedPercentage {} {
      if {$::eagle_tests(Total) > 0} then {
        return [expr \
            {100.0 * (($::eagle_tests(Passed) + \
            $::eagle_tests(Skipped)) / \
            double($::eagle_tests(Total)))}]
      }

      return 0; # no tests were run, etc.
    }

    proc getSkippedPercentage {} {
      if {$::eagle_tests(Total) > 0} then {
        return [expr \
            {100.0 * ($::eagle_tests(Skipped) / \
            double($::eagle_tests(Total)))}]
      }

      return 0; # no tests were run, etc.
    }

    proc getDisabledPercentage {} {
      if {$::eagle_tests(Total) > 0} then {
        return [expr \
            {100.0 * ($::eagle_tests(Disabled) / \
            double($::eagle_tests(Total)))}]
      }

      return 0; # no tests were run, etc.
    }

    proc testObjectMembers { args } {
      if {[llength $args] == 0} then {
        error [appendArgs \
            "wrong # args: should be \"" \
            [lindex [info level [info level]] 0] \
            " ?options? object\""]
      }

      set command [list object members]
      eval lappend command $args

      return [lsort [uplevel 1 $command]]
    }

    proc createThread { script {parameterized false} {maxStackSize ""} } {
      if {[isDotNetCore]} then {
        #
        # HACK: This seems to make .NET Core happier for reasons
        #       that are not entirely clear.
        #
        set typeName "System.Threading.Thread, mscorlib"
      } else {
        set typeName System.Threading.Thread
      }

      if {$parameterized} then {
        if {[string length $maxStackSize] > 0} then {
          return [object create -alias -objectflags +NoReturnReference \
              -parametertypes [list System.Threading.ParameterizedThreadStart \
              System.Int32] $typeName $script $maxStackSize]
        } else {
          return [object create -alias -objectflags +NoReturnReference \
              -parametertypes [list System.Threading.ParameterizedThreadStart] \
              $typeName $script]
        }
      } else {
        if {[string length $maxStackSize] > 0} then {
          return [object create -alias -objectflags +NoReturnReference \
              -parametertypes [list System.Threading.ThreadStart \
              System.Int32] $typeName $script $maxStackSize]
        } else {
          return [object create -alias -objectflags +NoReturnReference \
              -parametertypes [list System.Threading.ThreadStart] \
              $typeName $script]
        }
      }
    }

    proc startThread { thread {parameterized false} {parameter null} } {
      if {$parameterized} then {
        $thread Start $parameter
      } else {
        $thread Start
      }
    }

    proc cleanupThread { thread {timeout 2000} } {
      #
      # HACK: When running on .NET Core, it seems that using the Interrupt
      #       method can result in a held lock being lost, even when using
      #       a lock statement, which should have try / finally semantics.
      #       Therefore, in that case, attempt to wait on the thread prior
      #       to attempting to use the Interrupt method.
      #
      if {[isDotNetCore]} then {
        if {[$thread IsAlive]} then {
          if {[catch {$thread Join $timeout} error]} then {
            tputs $::test_channel [appendArgs \
                "---- failed to pre-join test thread \"" $thread "\": " \
                $error \n]
          } elseif {$error} then {
            tputs $::test_channel [appendArgs \
                "---- pre-joined test thread \"" $thread \"\n]
          } else {
            tputs $::test_channel [appendArgs \
                "---- timeout pre-joining test thread \"" $thread " (" \
                $timeout " milliseconds)\"\n"]
          }
        }
      }

      if {[$thread IsAlive]} then {
        if {[catch {$thread Interrupt} error]} then {
          tputs $::test_channel [appendArgs \
              "---- failed to interrupt test thread \"" $thread "\": " \
              $error \n]
        } else {
          tputs $::test_channel [appendArgs "---- test thread \"" $thread \


    proc purgeAndCleanup { channel name } {
      catch {uplevel 1 [list debug purge]} result

      tputs $channel [appendArgs \
          "---- purge \"" $name "\" results: " $result \n]

      catch {uplevel 1 [list debug cleanup {
        Default -Miscellaneous
      }]} result

      tputs $channel [appendArgs \
          "---- cleanup \"" $name "\" results: " $result \n]

      catch {uplevel 1 [list object invoke -flags +NonPublic \
          Eagle._Components.Private.ProcessOps ClearOutputCache]} result

          "---- FactoryOps cleanup results: " $result \n]

      catch {uplevel 1 [list object invoke -flags +NonPublic \
          Eagle._Components.Private.ScriptOps ClearInterpreterCache]} result

      tputs $channel [appendArgs \
          "---- ScriptOps cleanup results: " $result \n]

      catch {uplevel 1 [list object invoke -flags +NonPublic \
          Eagle._Components.Private.SyntaxOps ClearCache]} result

      tputs $channel [appendArgs \
          "---- SyntaxOps cleanup results: " $result \n]
    }

    proc evalWithTimeout { script {milliseconds 2000} {resultVarName ""} } {
      #
      # NOTE: Verify that the number of milliseconds requested is greater than
      #       zero.
      #
      if {$milliseconds <= 0} then {
        error "number of milliseconds must be greater than zero"
      }

      #




















      # NOTE: Evaluate the specified script in the context of the caller,
      #       returning the result to the caller.
      #
      if {[string length $resultVarName] > 0} then {
        upvar 1 $resultVarName result
      }

      return [catch {
        #
        # NOTE: Evaluate the script in the context of the caller, forcing
        #       any [vwait] that may be in the contained script to stop


        #       when it hits a script cancellation -AND- reset the script



        #       cancellation flags upon completion (i.e. important due to


        #       the use of script cancellation to enforce the timeout).
        #


        uplevel 1 [list \
            debug secureeval -nocancel true -stoponerror true -timeout \
            $milliseconds {} $script]
      } result]













    }

    proc vwaitWithTimeout { varName {milliseconds 2000} } {
      #
      # NOTE: Verify that the number of milliseconds requested is positive
      #       or zero.
      #
      if {$milliseconds < 0} then {
        error "number of milliseconds cannot be negative"
      }









      if {[catch {
        #
        # NOTE: Refer to the specified variable in the context of our
        #       caller.
        #
        upvar 1 $varName variable

        #
        # NOTE: Wait for the variable to be changed -OR- for the wait
        #       to be canceled.
        #
        vwait -eventwaitflags {+NoBgError StopOnError} -force -timeout \
            $milliseconds -- variable
      } result] == 0} then {
        #
        # NOTE: The wait completed successfully, the variable may have
        #       been changed.
        #
        return $result
      } else {
        #
        # NOTE: The wait failed in some way, it may have been canceled
        #       and the variable may or may not have been changed.
        #
        return false





      }
    }

    proc tclLoadForTest { {varName ""} {findFlags ""} {loadFlags ""} } {
      if {[string length $varName] > 0} then {
        upvar 1 $varName loaded
      }

        tputs $::test_channel [appendArgs \
            "---- native Tcl " [expr {$force ? "forcibly " : ""}] \
            "unloaded, module \"" $module "\", interpreter \"" \
            $interp \"\n]
      }
    }

    proc generateUniqueId { {text ""} {length 16} } {
      #
      # HACK: This should generate a reasonably random unique identifier
      #       suitable for non-cryptographic use by the test suite.
      #
      if {[string length $text] > 0} then {
        return [string range \
            [string tolower [hash normal sha512 $text]] 0 $length]
      } else {
        return [string range \
            [string tolower [hash normal sha512 [appendArgs uniq \
            [info context] [info tid] [pid] [clock clicks] [clock \
            now]]]] 0 $length]
      }
    }

    proc testExecTclScript { script {shell ""} {verbose 0} } {
      try {
        #
        # NOTE: Get a temporary file name for the script we are going to
        #       use to query the machine type for the native Tcl shell.
        #
        set fileName [file tempname]

            #
            set shell $::test_tclsh
          } else {
            #
            # NOTE: We cannot execute the native Tcl shell because one
            #       has not been specified, nor configured.
            #
            set error "error: \"::test_tclsh\" variable is missing"

            if {$verbose > 0} then {
              tputs $::test_channel [appendArgs \
                  "---- native Tcl script error: " $error \n]
            }

            return [expr {$verbose > 3 ? $error : "error"}]
          }
        }

        #
        # NOTE: Generate a unique identifier to make it easier to locate
        #       this script and its results in the test log file.
        #
        if {$verbose > 1} then {
          set id [generateUniqueId $script]
        }

        #
        # NOTE: When in "ultra-verbose" mode, emit native Tcl script to
        #       the log file.
        #
        if {$verbose > 2} then {
          tputs $::test_channel [appendArgs \
              "---- native Tcl script (" $id ") text: " [string trim \
              $script] \n]
        }

        #
        # NOTE: Evaluate the script using the native Tcl shell, trim the
        #       excess whitespace from the output, and return it to the
        #       caller.
        #
        if {[catch {string trim \
            [testExec $shell [list -success Success] \
            [appendArgs \" $fileName \"]]} result] == 0} then {
          #
          # NOTE: When in "super-verbose" mode, emit native Tcl script
          #       results to the log file.
          #
          if {$verbose > 1} then {
            tputs $::test_channel [appendArgs \
                "---- native Tcl script (" $id ") result: " $result \n]
          }

          #
          # NOTE: Success, return the result to the caller.
          #
          return $result
        } else {
          #
          # NOTE: We could not execute the native Tcl shell (perhaps one
          #       is not available?).
          #
          set error [appendArgs "error: " $result]

          if {$verbose > 0} then {
            tputs $::test_channel [appendArgs \
                "---- native Tcl script error: " $error \n]
          }

          return [expr {$verbose > 3 ? $error : "error"}]
        }
      } finally {
        #
        # NOTE: Should we delete the temporary file we created, if any?
        #
        if {![info exists ::no(deleteTestExecTclFile)]} then {
          #

            #
            catch {file delete $fileName}
          }
        }
      }
    }

    proc getTclShellVerbosity {} {
      if {[info exists ::test_tclsh_verbose] && \
          [string is integer -strict $::test_tclsh_verbose]} then {
        return $::test_tclsh_verbose
      } else {
        return 0; # TODO: Good default?
      }
    }

    proc getTclVersionForTclShell { {shell ""} {verbose 0} } {
      return [testExecTclScript {
        puts -nonewline stdout [info tclversion]
      } $shell $verbose]
    }

    proc getCommandsForTclShell { {shell ""} {verbose 0} } {
      return [testExecTclScript {
        puts -nonewline stdout [info commands]
      } $shell $verbose]
    }

    proc getMachineForTclShell { {shell ""} {verbose 0} } {
      return [testExecTclScript {
        puts -nonewline stdout $tcl_platform(machine)
      } $shell $verbose]
    }

    proc getTclExecutableForTclShell { {shell ""} {verbose 0} } {
      return [testExecTclScript {
        puts -nonewline stdout [info nameofexecutable]
      } $shell $verbose]
    }

    proc getTkVersionForTclShell { {shell ""} {verbose 0} } {
      return [testExecTclScript {
        puts -nonewline stdout [package require Tk]; exit
      } $shell $verbose]
    }

    proc evalWithTclShell { script {raw false} {shell ""} {verbose 0} } {
      return [testExecTclScript [string map \
          [list %script% $script %raw% $raw] {
        if {%raw%} then {
          set code [catch {%script%} result]
          puts -nonewline stdout [list $code $result]
        } else {
          puts -nonewline stdout [eval {%script%}]

        #
        # NOTE: If necessary, automatically detect the machine for the Tcl
        #       shell that we plan on using.
        #
        if {[string length $machine] == 0 && \
            ![info exists ::no(getMachineForTclShell)]} then {
          set machine [getMachineForTclShell "" [getTclShellVerbosity]]
        }

        #
        # NOTE: Build the full path and file name of the Garuda DLL, using
        #       the Eagle base path.  Currently, this will only work
        #       correctly if the test suite is being run from inside the
        #       source tree.


    proc cleanupWinForms {} {
      #
      # TODO: These may need to be changed in later framework versions.
      #
      object unimport -importpattern System.Resources
      object unimport -importpattern System.Windows.Forms
      object unimport -importpattern System.Windows.Forms.Automation

      object unimport -importpattern \
          System.Windows.Forms.ComponentModel.Com2Interop

      object unimport -importpattern System.Windows.Forms.Design
      object unimport -importpattern System.Windows.Forms.Layout
      object unimport -importpattern System.Windows.Forms.PropertyGridInternal

    ############################# END Eagle ONLY ##############################
    ###########################################################################
  } else {
    ###########################################################################
    ############################# BEGIN Tcl ONLY ##############################
    ###########################################################################

    proc getPassedPercentage {} {
      if {$::tcltest::numTests(Total) > 0} then {
        return [expr \
            {100.0 * (($::tcltest::numTests(Passed) + \
            $::tcltest::numTests(Skipped)) / \
            double($::tcltest::numTests(Total)))}]
      }

      return 0; # no tests were run, etc.
    }

    proc getSkippedPercentage {} {
      if {$::tcltest::numTests(Total) > 0} then {
        return [expr \
            {100.0 * ($::tcltest::numTests(Skipped) / \
            double($::tcltest::numTests(Total)))}]
      }

      return 0; # no tests were run, etc.

    }

    #
    # NOTE: We need several of our test related commands in the global
    #       namespace as well.
    #
    exportAndImportPackageCommands [namespace current] [list \
        dumpState trawputs tputs ttclLog doesTestLogFileExist \
        getTestLogStartSentry extractTestRunIdFromLogStartSentry \
        doesTestLogHaveStartSentry didTestLogHaveStartSentry \
        setTestLogStartSentry tlog getSoftwareRegistryKey haveConstraint \
        addConstraint haveOrAddConstraint getConstraints getCachedConstraints \
        useCachedConstraints removeConstraint fixConstraints \
        fixTimingConstraints testDebugBreak testArrayGet testArrayGet2 \
        testResultGet testValueGet getFirstLineOfError calculateBogoCops \
        calculateRelativePerformance formatTimeStamp formatElapsedTime \
        sourceIfValid processTestArguments getTclShellFileName \
        getTemporaryPath getTemporaryFileName getFiles getTestFiles \
        getTestRunId getNewTestRunId getDefaultTestLogPath getTestLogPath \
        getTestLogId getDefaultTestLog getTestLog getLastTestLog \
        getTestSuite getTestSuiteFullName getTestMachine getTestPlatform \
        getTestConfiguration getTestNamePrefix getTestSuffix \
        getTestUncountedLeaks getRuntimeAssemblyName getTestAssemblyName \
        canTestExec testExec testClrExec execTestShell isRandomOrder \
        isBreakOnDemand isBreakOnLeak isStopOnFailure isStopOnLeak \
        isExitOnComplete returnInfoScript runTestPrologue runTestEpilogue \

        hookPuts unhookPuts runTest testShim tsource recordTestStatistics \
        reportTestStatistics formatList formatListAsDict pathToRegexp \
        assemblyNameToRegexp inverseLsearchGlob removePathFromFileNames \
        formatDecimal clearTestPercent reportTestPercent reportArrayGet \
        reportTestStatisticCounts runAllTests isTestSuiteRunning \
        getTestChannelOrDefault tryVerifyTestPath checkForAndSetTestPath \
        configureTcltest machineToPlatform architectureForPlatform \
        getPassedPercentage getSkippedPercentage] false false

    ###########################################################################
    ############################## END Tcl ONLY ###############################
    ###########################################################################
  }

  #
  # NOTE: Provide the Eagle "test" package to the interpreter.
  #
  package provide Eagle.Test \
    [expr {[isEagle] ? [info engine PatchLevel] : "1.0"}]
}


      #
      set arguments3 null; set error null

      #
      # NOTE: Attempt to merge the option and non-option arguments into a
      #       single list of arguments.
      #
      set code [object invoke -alias \
          Interpreter.GetActive MergeArguments $options $arguments1 \
          $arguments2 2 1 false false false arguments3 error]

      #
      # NOTE: Was the argument merging process successful?
      #
      if {$code eq "Ok"} then {
        #
        # NOTE: Jump up from our call frame (and optionally that of our

#
# NOTE: Use our own namespace here because even though we do not directly
#       support namespaces ourselves, we do not want to pollute the global
#       namespace if this script actually ends up being evaluated in Tcl.
#
namespace eval ::Eagle {
  #
  # NOTE: This procedure returns non-zero if the specified public key tokens
  #       match.  An empty string matches any public key token (including an
  #       empty string).
  #
  proc matchUpdatePublicKeyToken { publicKeyToken1 publicKeyToken2 } {
    if {[string length $publicKeyToken1] == 0} then {
      return true
    }

    if {[string length $publicKeyToken2] == 0} then {
      return true
    }

    return [expr {$publicKeyToken1 eq $publicKeyToken2}]
  }

  #
  # NOTE: This procedure returns non-zero if the specified product / update
  #       names match.  An empty string matches any name (including an empty
  #       string).
  #
  proc matchUpdateName { name1 name2 } {
    return [expr {[string length $name1] == 0 || $name1 eq $name2}]
  }

  #
  # NOTE: This procedure returns non-zero if the specified culture names
  #       match.  An empty string matches any culture name (including an
  #       empty string).
  #
  proc matchUpdateCulture { culture1 culture2 } {
    return [expr {[string length $culture1] == 0 || $culture1 eq $culture2}]
  }

  #
  # NOTE: This procedure returns non-zero if the specified public key token
  #       matches the one in use by the Eagle script engine.
  #
  proc matchEnginePublicKeyToken { publicKeyToken } {
    return [matchUpdatePublicKeyToken \
        $publicKeyToken [info engine PublicKeyToken]]
  }

  #
  # NOTE: This procedure returns non-zero if the specified product / update
  #       name matches the Eagle script engine.
  #
  proc matchEngineName { name } {

    return [matchUpdateName $name [info engine Name]]
  }

  #
  # NOTE: This procedure returns non-zero if the specified culture name
  #       matches the one in use by the Eagle script engine.
  #
  proc matchEngineCulture { culture } {

    return [matchUpdateCulture $culture [info engine Culture]]
  }

  #
  # NOTE: This procedure escapes the reserved characters in the specified
  #       update notes and returns the resulting string.
  #
  proc escapeUpdateNotes { notes } {

        [list &htab\; \t &vtab\; \v &lf\; \n &cr\; \r &amp\; &] $notes]
  }

  #
  # NOTE: This procedure returns the list of arguments to be passed to the
  #       [uri download] call that performs the auto-update check.
  #
  proc getFetchUpdateArgs { name type directory metadata extension varName } {
    #
    # NOTE: Use a variable in the context of the caller to communicate the
    #       exact error condition, if any.
    #
    upvar 1 $varName error

    #
    # NOTE: Initially, set the result to an empty list to indicate
    #       unrecognized input.
    #
    set result [list]

    #
    # NOTE: Make sure the base URI is valid.
    #
    set baseUri [getDictionaryValue $metadata uri]

    if {[uri isvalid $baseUri]} then {
      #
      # NOTE: Make sure the base (product) name looks valid.
      #
      if {[regexp -nocase -- {^[0-9A-Z_]+$} $name]} then {
        #
        # NOTE: Make sure the patch level looks valid.
        #
        set patchLevel [getDictionaryValue $metadata patchLevel]

        if {[regexp -- {^\d+\.\d+\.\d+\.\d+$} $patchLevel]} then {
          #
          # NOTE: Make sure the directory is either empty or an existing
          #       valid directory.
          #
          if {[string length $directory] == 0 || \
              [file isdirectory $directory]} then {
            #
            # NOTE: Make sure the extension is supported.
            #
            if {$extension eq ".exe" || \
                $extension eq ".rar" || $extension eq ".zip"} then {
              #
              # NOTE: Start with URI components common to all release
              #       types.
              #
              set components [list $baseUri releases $patchLevel]

              #
              # NOTE: Next, figure out what type of download is being
              #       requested.
              #
              switch -exact -nocase -- $type {
                source -
                setup -
                binary {
                  #
                  # NOTE: *LEGACY* These release types only support the ".exe"
                  #       and ".rar" file extensions.  Of these, the ".exe" is
                  #       always preferred (on Windows), primarily because it
                  #       can be securely signed (via Authenticode).
                  #
                  if {$extension eq ".exe" || $extension eq ".rar"} then {
                    #
                    # HACK: Setup files, which are currently only for Windows,
                    #       must always have an ".exe" file extension.
                    #
                    if {[string tolower $type] eq "setup"} then {
                      set extension .exe
                    }

                    #
                    # NOTE: Source code, setup, or binary download.  This may
                    #       be a RAR or an EXE file.  Append the appropriate
                    #       file name and then join all the URI components to
                    #       form the final URI.
                    #
                    set fileName [appendArgs \
                        $name [string totitle $type] $patchLevel $extension]

                    lappend components $fileName

                    set result [list \
                        [eval uri join $components] [file join $directory \
                        $fileName]]
                  } else {
                    set error [appendArgs \
                        "file extension is unsupported for release type \"" \
                        $type \"]
                  }
                }
                plugin {
                  #
                  # NOTE: Since this release type must work on all platforms,
                  #       use of the ".zip" file extension is a requirement.
                  #
                  if {$extension eq ".zip"} then {
                    set fileName [appendArgs \
                        $name [string totitle $type] $patchLevel $extension]

                    lappend components $fileName

                    set result [list \
                        [eval uri join $components] [file join $directory \
                        $fileName]]
                  } else {
                    set error [appendArgs \
                        "file extension is unsupported for release type \"" \
                        $type \"]
                  }
                }
                default {
                  set error "release type is unsupported"
                }
              }
            } else {
              set error "file extension is unsupported"
            }
          } else {
            set error "directory is invalid"
          }
        } else {
          set error "patch level is invalid"
        }
      } else {
        set error "base name is invalid"
      }
    } else {
      set error "base URI is invalid"
    }

    return $result
  }

  #
  # NOTE: This procedure fetches an update package with the specified patch
  #       level and package type and then saves it to the specified local
  #       directory.
  #
  proc fetchUpdate { name type targetDirectory metadata varName } {
    #
    # NOTE: Figure out the appropriate file extension to download for this
    #       release type and platform.
    #
    if {[string tolower $type] eq "plugin"} then {
      #
      # NOTE: Plugin updates are always packaged as ZIP archives on all
      #       supported platforms.  There is no portable way to securely
      #       sign these files.  In general, these should be checked via
      #       OpenPGP signatures before being used.
      #
      set extension .zip
    } elseif {[isWindows]} then {
      #
      # NOTE: Otherwise, on Windows, prefer self-extracting executables,
      #       because they can be secure signed and trivially verified.
      #
      set extension .exe
    } else {
      #
      # NOTE: Otherwise, fallback to using RAR archives, which should be
      #       cross-platform.  There is no portable way to securely sign
      #       these files.  In general, these should also be checked via
      #       OpenPGP signatures before being used.
      #
      set extension .rar
    }

    #
    # NOTE: Build the necessary arguments for the download, optionally
    #       capturing them into a variable provided by the caller.
    #
    if {[string length $varName] > 0} then {
      upvar 1 $varName args
    }

    set args [getFetchUpdateArgs \
        $name $type $targetDirectory $metadata $extension error]

    if {[llength $args] > 0} then {
      #
      # NOTE: Start trusting ONLY our self-signed SSL certificate.
      #
      set trusted true

          catch {uri softwareupdates false}
        }
      }

      #
      # NOTE: Return a result indicating what was done.
      #
      return [appendArgs \
          "downloaded URI " [lindex $args 0] " to directory \"" \
          $targetDirectory \"]
    } else {
      return [appendArgs "cannot fetch update: " $error]
    }
  }

  #
  # NOTE: This procedure runs the updater tool and then immediately exits the
  #       process.
  #
  proc runUpdateAndExit { {automatic false} } {
    global tcl_platform

    #
    # NOTE: Determine the fully qualified file name for the updater.  If
    #       it is not available, we cannot continue.

    if {[string length $pathAndQuery] > 0} then {
      lappend command -tagPathAndQuery $pathAndQuery
    }

    eval $command &; exit -force
  }

  #
  # NOTE: This procedure fetches an update file (based on a URI), saves it to
  #       a temporary directory, verifies its authenticity, extracts its files
  #       to another temporary directory, and then copies them to the target
  #       directory.
  #
  proc downloadAndExtractUpdate { name type targetDirectory metadata varName } {
    #
    # NOTE: Attempt to load Eagle test package as it is required for
    #       the [getTemporaryPath] procedure.
    #
    package require Eagle.Test

    #
    # NOTE: Figure out where, underneath the temporary directory, the
    #       update file should be downloaded and extracted to.
    #
    set temporaryDirectory [file join \
        [getTemporaryPath] [appendArgs ea-tu-pb- [pid] - [string trim \
        [clock seconds] -]]]

    try {
      #
      # NOTE: Create outer temporary directory used by this procedure.
      #       This makes it easy to cleanup later as it will contain
      #       all other temporary directories and files created within
      #       this procedure.
      #
      file mkdir $temporaryDirectory

      #
      # NOTE: Create the temporary directory only used for fetching the
      #       update (archive?) file.
      #
      set fetchDirectory [file join $temporaryDirectory fetch]
      file mkdir $fetchDirectory

      #
      # NOTE: Actually fetch (download) the update (archive?) file from
      #       the URI, saving it to the special temporary directory.
      #
      fetchUpdate $name $type $fetchDirectory $metadata fetchArgs

      #
      # NOTE: Grab the downloaded file name from the arguments returned
      #       by the fetch operation.
      #
      set archiveFileName [lindex $fetchArgs 1]

      #
      # NOTE: Match up the md5, sha1, and sha512 fields from the metadata
      #       and verify they match the fetched update (archive?) file.
      #
      if {[set md5 [string tolower [hash normal -filename md5 \
          $archiveFileName]]] ne [getDictionaryValue $metadata md5]} then {
        error [appendArgs \
            "cannot update: fetched update archive file \"" \
            $archiveFileName "\" has wrong MD5 hash, want \"" \
            [getDictionaryValue $metadata md5] "\", have \"" \
            $md5 \"]
      }

      if {[set sha1 [string tolower [hash normal -filename sha1 \
          $archiveFileName]]] ne [string tolower [getDictionaryValue \
          $metadata sha1]]} then {
        error [appendArgs \
            "cannot update: fetched update archive file \"" \
            $archiveFileName "\" has wrong SHA1 hash, want \"" \
            [getDictionaryValue $metadata sha1] "\", have \"" \
            $sha1 \"]
      }

      if {[set sha512 [string tolower [hash normal -filename sha512 \
          $archiveFileName]]] ne [string tolower [getDictionaryValue \
          $metadata sha512]]} then {
        error [appendArgs \
            "cannot update: fetched update archive file \"" \
            $archiveFileName "\" has wrong SHA512 hash, want \"" \
            [getDictionaryValue $metadata sha512] "\", have \"" \
            $sha512 \"]
      }

      #
      # NOTE: Create the temporary directory only used to contain the
      #       files extracted from the update (archive?) file.  These
      #       are the files that will be copied to the final target
      #       directory (after they have been fully verified).
      #
      set extractRootDirectory [file join $temporaryDirectory extract]
      file mkdir $extractRootDirectory

      #
      # NOTE: Attempt to load Eagle unzip package as it is required for
      #       the [extractZipArchive] procedure.
      #
      package require Eagle.Unzip

      #
      # NOTE: Extract the contents of the fetched update (archive?) file
      #       and then figure out the list of included content files.
      #
      set extractDirectory [extractZipArchive \
          $archiveFileName $extractRootDirectory true]

      catch {file delete $archiveFileName}; # NOTE: No longer needed.

      set extractFileNames [object invoke System.IO.Directory GetFiles \
          $extractDirectory * AllDirectories]

      #########################################################################
      #################### PHASE 1: VERIFY EXTRACTED FILES ####################
      #########################################################################

      foreach extractFileName $extractFileNames {
        #
        # NOTE: Based on the extension of the extracted file, attempt to
        #       verify its contents (e.g. check signatures, etc).
        #
        switch -exact -nocase -- [file extension $extractFileName] {
          .dll -
          .exe {
            #
            # NOTE: Verify the Authenticode signature for the native
            #       executable file is intact.  This always applies,
            #       even when the executable file contains a managed
            #       assembly (i.e. with its strong name signature).
            #
            if {[catch {library certificate $extractFileName}]} then {
              error [appendArgs \
                  "cannot update: extracted native executable \"" \
                  $extractFileName "\" was not properly signed"]
            }

            #
            # HACK: If this platform does not appear to have access to
            #       the necessary native CLR API used to verify strong
            #       name signatures, just skip it.
            #
            if {[info exists ::eagle_platform(strongName)] && \
                [string is true -strict [getDictionaryValue \
                $::eagle_platform(strongName) verified]]} then {
              #
              # NOTE: Does the extracted executable actually contain a
              #       managed assembly?
              #
              if {[catch {
                object invoke System.Reflection.AssemblyName \
                    GetAssemblyName $extractFileName
              }] == 0} then {
                #
                # NOTE: Forcibly verify the strong name signature for
                #       the managed assembly is intact.
                #
                if {[catch {
                  object invoke -flags +NonPublic \
                      Eagle._Components.Private.RuntimeOps \
                      IsStrongNameVerified $extractFileName true
                } verified] == 0 && $verified} then {
                  #
                  # NOTE: Everything is properly signed, do nothing.
                  #
                } else {
                  error [appendArgs \
                      "cannot update: extracted managed assembly \"" \
                      $extractFileName "\" was not properly signed"]
                }
              }
            }
          }
          .eagle -
          .harpy -
          .pdb -
          .xml {
            #
            # NOTE: *SECURITY* These file types are allowed -AND- do not
            #       (currently) require any further verification.
            #
          }
          .rar -
          .zip {
            #
            # NOTE: *SECURITY* These file types are forbidden (for now),
            #       due to the potential for abuse.
            #
            error [appendArgs \
                "cannot update: extracted file \"" $extractFileName \
                "\" has forbidden file extension"]
          }
          default {
            #
            # NOTE: *SECURITY* Other file types are forbidden (for now),
            #       due to the potential for abuse.
            #
            error [appendArgs \
                "cannot update: extracted file \"" $extractFileName \
                "\" has unrecognized file extension"]
          }
        }
      }

      #########################################################################
      ################## PHASE 2: VERIFY RELATIVE FILE NAMES ##################
      #########################################################################

      #
      # NOTE: If we get to this point, all extracted files are verified.
      #       The only remaining thing to do is to copy them to the final
      #       target directory specified by the caller.
      #
      set extractDirectoryLength1 [expr {
        [string length $extractDirectory]
      }]

      set extractDirectoryLength2 [expr {
        $extractDirectoryLength1 - 1
      }]

      foreach extractFileName $extractFileNames {
        #
        # NOTE: Sanity-check that the (prefix) portion of the extracted file
        #       name matches the originally specified extract directory name.
        #
        if {[string range $extractFileName 0 \
            $extractDirectoryLength2] ne $extractDirectory} then {
          error [appendArgs \
              "bad extracted file name \"" $extractFileName \
              "\", not relative to the extract directory"]
        }

        #
        # NOTE: Sanity-check the first character of the calculated relative
        #       file name is a legal directory separator.
        #
        set relativeFileName [string range \
            $extractFileName $extractDirectoryLength1 end]

        if {[string index $relativeFileName 0] ni [list / \\]} then {
          error [appendArgs \
              "bad relative file name \"" $relativeFileName \
              "\", malformed, missing leading directory separator"]
        }
      }

      #########################################################################
      ################### PHASE 3: COPY TO TARGET DIRECTORY ###################
      #########################################################################

      foreach extractFileName $extractFileNames {
        #
        # NOTE: Grab the relative file name from the extracted file name.
        #       This exact relative file name was already sanity-checked
        #       in the previous phase.
        #
        set relativeFileName [string range \
            $extractFileName $extractDirectoryLength1 end]

        #
        # NOTE: Figure out final target file name using the final target
        #       directory and the relative file name for this extracted
        #       file.
        #
        set targetFileName [appendArgs \
            $targetDirectory $relativeFileName]

        #
        # NOTE: Just in case the target sub-directory does not exist yet,
        #       create it now.  Then, copy the extracted file to its final
        #       target sub-directory.
        #
        file mkdir [file dirname $targetFileName]
        file copy $extractFileName $targetFileName
      }
    } finally {
      #
      # NOTE: Completely delete the outer temporary directory, which will
      #       cleanup the fetched update (archive?) file name and all the
      #       files subsequently extracted from the archive.
      #
      catch {file delete -recursive -- $temporaryDirectory}
    }
  }

  #
  # NOTE: This procedure returns the base URI that should be used to check
  #       for available updates.
  #
  proc getUpdateBaseUri { {refresh ""} } {
    #
    # NOTE: Does the caller want to force a choice between the current and
    #       default base URI?
    #
    if {[string length $refresh] > 0} then {
      #
      # NOTE: Return the specified base URI for updates.
      #
      return [info engine UpdateBaseUri $refresh]
    } else {
      #
      # NOTE: Check the current base URI for updates against the one baked
      #       into the assembly.  If they are different, then the base URI
      #       must have been overridden.  In that case, we must return the
      #       current base URI; otherwise, we must return an empty string.
      #
      set baseUri(0) [info engine UpdateBaseUri false]; # NOTE: Current.
      set baseUri(1) [info engine UpdateBaseUri true];  # NOTE: Default.

      if {[string length $baseUri(0)] > 0 && \
          [string length $baseUri(1)] > 0} then {
        #
        # NOTE: Ok, they are both valid.  Are they different?
        #
        if {$baseUri(0) ne $baseUri(1)} then {
          return $baseUri(0)
        }
      }

      return ""
    }
  }

  #
  # NOTE: This procedure returns the path and query portions of the URI that
  #       should be used to check for available updates.
  #
  proc getUpdatePathAndQuery { {refresh ""} } {
    #
    # NOTE: Does the caller want to force a choice between the current and
    #       default tag path and query?
    #
    if {[string length $refresh] > 0} then {
      #
      # NOTE: Return the specified tag path and query for updates.
      #
      return [info engine UpdatePathAndQuery $refresh]
    } else {
      #
      # NOTE: Check the current tag path and query for updates against the
      #       one baked into the assembly.  If they are different, then the
      #       tag path and query must have been overridden.  In that case,
      #       we must return the current tag path and query; otherwise, we
      #       must return an empty string.
      #
      set pathAndQuery(0) [info engine UpdatePathAndQuery \
          false]; # NOTE: Current.

      set pathAndQuery(1) [info engine UpdatePathAndQuery \
          true];  # NOTE: Default.

      if {[string length $pathAndQuery(0)] > 0 && \
          [string length $pathAndQuery(1)] > 0} then {
        #
        # NOTE: Ok, they are both valid.  Are they different?
        #
        if {$pathAndQuery(0) ne $pathAndQuery(1)} then {
          return $pathAndQuery(0)
        }
      }

      return ""
    }
  }

  #
  # NOTE: This procedure downloads the available update data and returns it
  #       verbatim.
  #
  proc getUpdateData { uri } {
    #
    # NOTE: Start trusting ONLY our own self-signed SSL certificate.
    #
    set trusted true


  #
  # NOTE: This procedure is used to check for new versions -OR- new update
  #       scripts for the runtime when a user executes the interactive
  #       "#check" command.  To disable this functionality, simply redefine
  #       this procedure to do nothing.
  #
  proc checkForEngine {
          {wantScripts false} {quiet false} {prompt false}
          {automatic false} } {
    return [checkForUpdate \
        "" "" "" "" "" "" "" $wantScripts $quiet $prompt $automatic]
  }

  #
  # NOTE: This procedure is used to check for new versions of a plugin just
  #       prior to it being loaded into an interpreter (when an appropriate
  #       flag is enabled).  To disable this functionality, simply redefine
  #       this procedure to do nothing.
  #
  proc checkForPlugin {
          {uri ""} {publicKeyToken ""} {name ""} {culture ""}
          {patchLevel ""} {timeStamp ""} {wantScripts false}
          {quiet false} {prompt false} {automatic false} } {
    return [checkForUpdate \
        plugin $uri $publicKeyToken $name $culture $patchLevel \
        $timeStamp $wantScripts $quiet $prompt $automatic]
  }

  #
  # NOTE: This procedure is used to check for new versions -OR- new update
  #       scripts for the runtime when a user executes the interactive
  #       "#check" command.  To disable this functionality, simply redefine
  #       this procedure to do nothing.
  #
  proc checkForUpdate {
          {type ""} {uri ""} {publicKeyToken ""} {name ""} {culture ""}
          {patchLevel ""} {timeStamp ""} {wantScripts false} {quiet false}
          {prompt false} {automatic false} } {
    #
    # NOTE: First of all, what type of update are we checking?  Possible
    #       values for this include "build", "plugin", "script", et al.
    #       These mirror the values of the UpdateType enumeration.
    #
    if {[string length $type] > 0} then {
      #
      # NOTE: Use the update type specified by the caller directly.  In
      #       the future, perhaps sanity check this?  Currently, its use
      #       is entirely cosmetic.
      #
      set updateType $type
    } else {
      #
      # NOTE: Default to the legacy update type of "build".  Currently,
      #       this is only used to construct messages to be displayed to
      #       the user.
      #
      set updateType build; # LEGACY
    }

    #
    # NOTE: Did the caller directly specify a URI to use?
    #
    if {[string length $uri] > 0} then {
      #
      # NOTE: If the caller specified a URI, it must be fully qualified.
      #       It will be used verbatim.
      #
      set updateBaseUri $uri

      #
      # NOTE: Assume that the URI refers to the latest available version
      #       of the specified product.
      #
      set updateUriType latest; # TODO: Good default?

      #
      # NOTE: If the caller specified a URI, it must be fully qualified.
      #       It will be used verbatim.
      #
      set updateUri $updateBaseUri
    } else {
      #
      # NOTE: Grab the (current) base URI for updates.
      #
      set updateBaseUri [getUpdateBaseUri false]

      #
      # NOTE: Grab the (current) update path and query string used for
      #       updates.
      #
      set updatePathAndQuery [getUpdatePathAndQuery false]

      #
      # TODO: Exract the URI type (e.g. "stable" or "latest") from the
      #       update path and query.  This code may need to be modified
      #       in the future.
      #
      set updateUriType [lindex [split $updatePathAndQuery .] 0]

      #
      # NOTE: Combine them to form the complete update URI.
      #
      set updateUri [appendArgs $updateBaseUri $updatePathAndQuery]
    }

    #
    # NOTE: Did the caller directly specify a public key token to use?
    #
    if {[string length $publicKeyToken] > 0} then {
      #
      # NOTE: Use the public key token specified by the caller to match
      #       against.
      #
      set updatePublicKeyToken $publicKeyToken
    } else {
      #
      # NOTE: Use the public key token of the script engine to match
      #       against.
      #
      set updatePublicKeyToken [info engine PublicKeyToken]
    }

    #

    # NOTE: Did the caller directly specify a (product) name to use?  In
    #       almost all cases, this will be the base name of the manifest
    #       assembly associated with the product.
    #
    if {[string length $name] > 0} then {
      #
      # NOTE: Use the (product) name specified by the caller to match
      #       against.
      #
      set updateName $name
    } else {

      #
      # NOTE: Use assembly name of the script engine to match against.
      #
      set updateName Eagle; # LEGACY
    }

    #
    # NOTE: Did the caller directly specify a culture name to use?  In
    #       almost all cases, this will be the invariant culture.
    #

    if {[string length $culture] > 0} then {
      #
      # NOTE: Use the culture name specified by the caller to match
      #       against.
      #
      set updateCulture $culture
    } else {
      #
      # NOTE: Use culture name of the script engine to match against.
      #
      set updateCulture [info engine Culture]
    }

    #
    # NOTE: Did the caller directly specify a patch level to use?
    #
    if {[string length $patchLevel] > 0} then {
      #
      # NOTE: Use the patch level specified by the caller to compare
      #       against versions available on the server.
      #
      set updatePatchLevel $patchLevel
    } else {
      #
      # NOTE: Use patch level of the script engine to compare against
      #       versions available on the server.
      #
      set updatePatchLevel [info engine PatchLevel]
    }

    #
    # NOTE: Did the caller directly specify a timestamp to use?  As of
    #       this writing (2019-05-10) this is only used to construct an
    #       information message to the user.
    #
    if {[string length $timeStamp] > 0} then {
      #
      # NOTE: Use the timestamp specified by the caller.
      #
      set updateTimeStamp $timeStamp
    } else {
      #
      # NOTE: Use timestamp of the script engine.
      #
      set updateTimeStamp [info engine TimeStamp]
    }

    if {[string length $updateTimeStamp] == 0} then {
      #
      # NOTE: This will end up displaying as the Unix epoch, which would
      #       be January 1st, 1970 at midnight (UTC).
      #
      set updateTimeStamp 0; #never?
    }

    #
    # NOTE: What should the DateTime format be for display?  This should
    #       be some variation on ISO-8601.
    #
    set dateTimeFormat yyyy-MM-ddTHH:mm:ss

    #
    # NOTE: Does it look like the number of seconds since the epoch -OR-
    #       some kind of date/time string?
    #
    if {[string is integer -strict $updateTimeStamp]} then {
      set updateDateTime [clock format \
          $updateTimeStamp -format $dateTimeFormat]
    } else {
      set updateDateTime [clock format \
          [clock scan $updateTimeStamp] -format $dateTimeFormat]
    }

    #
    # NOTE: Fetch the master update data from the distribution site and
    #       normalize to Unix-style line-endings.
    #
    set updateData [string map [list \r\n \n] [getUpdateData $updateUri]]

    #
    # NOTE: Split the data into lines.  Given the previous command, this
    #       will always use Unix-style line-endings.
    #
    set lines [split $updateData \n]

    #
    # NOTE: Keep track of how many update scripts are processed -AND- their
    #       associated (final) dispositions.
    #
    array set scriptCounts {
      invalid              0 fail                 0 bad                  0
      ok                   0 error                0
    }

    #
    # NOTE: Check each update line to find the build information...  Lines
    #       that do not conform to the correct format should be skipped.
    #
    foreach line $lines {
      #
      # NOTE: Remove surrounding spaces (but not tabs), skip blank lines
      #       and comment lines.
      #
      set line [string trim $line " "]
      if {[string length $line] == 0} then {continue}

      set char [string index $line 0]
      if {$char eq "#" || $char eq ";"} then {continue}

      #
      # NOTE: Split the tab-delimited line into its fields.  The format of
      #       all lines in the data must be as follows, all on the same
      #       line:
      #
      #       <startLine> protocolId <tab> publicKeyToken <tab> name <tab>
      #       culture <tab> patchLevel <tab> timeStamp <tab> baseUri <tab>
      #       md5Hash <tab> sha1Hash <tab> sha512Hash <tab> notes <newLine>
      #
      set fields [split $line \t]
      if {[llength $fields] < 11} then {continue}

      #
      # NOTE: Grab the protocol Id field.
      #
      set product(protocolId) [lindex $fields 0]

      #
      # NOTE: Grab the public key token field.




      #
      set product(publicKeyToken) [lindex $fields 1]

      #
      # NOTE: Grab the (product) name field.
      #
      set product(name) [lindex $fields 2]

      #
      # NOTE: Grab the culture field.
      #
      set product(culture) [lindex $fields 3]

      #
      # NOTE: Figure out which protocol is in use for this line.  The value
      #       "1" means this line specifies a build of the script engine.
      #       The value "2" means this line specifies an update script (via
      #       a URI) to evaluate.  The value "3" means this line specifies
      #       a build of the GUI updater tool (not handled by this script).
      #       The value "4" means this line specifies a build of a (binary)
      #       plugin.  All other values are currently reserved and ignored.
      #
      set checkBuild [expr {
        !$wantScripts && $product(protocolId) eq "1"
      }]

      set checkScript [expr {
        $wantScripts && $product(protocolId) eq "2"
      }]

      set checkSelf [expr {
        !$wantScripts && $product(protocolId) eq "3"
      }]

      set checkPlugin [expr {
        !$wantScripts && $product(protocolId) eq "4"
      }]

      #
      # NOTE: We only want to find the first line that matches our target.
      #       The public key token is being used here to make sure we get
      #       the same build "flavor" of the script engine -OR- the binary
      #       plugin vendor / identity.  These lines are organized so that
      #       the "latest stable version" should be on the first line (for
      #       a given public key token) and may be followed by development
      #       / experimental versions, etc.  Prior to checking patch level
      #
      #
      if {($checkBuild || $checkScript || $checkPlugin) && \
          [matchUpdatePublicKeyToken \
              $product(publicKeyToken) $updatePublicKeyToken] && \
          [matchUpdateName $product(name) $updateName] && \
          [matchUpdateCulture $product(culture) $updateCulture]} then {
        #
        # NOTE: Grab the patch level field.
        #
        set product(patchLevel) [lindex $fields 4]

        if {[string length $product(patchLevel)] == 0} then {
          set product(patchLevel) 0.0.0.0; # no patch level?
        }

        #
        # NOTE: Grab the time-stamp field.
        #
        set product(timeStamp) [lindex $fields 5]

        if {[string length $product(timeStamp)] == 0} then {
          set product(timeStamp) 0; #never?
        }

        #
        # NOTE: What should the DateTime format be for display?  This
        #       should be some variation on ISO-8601.
        #
        set dateTimeFormat yyyy-MM-ddTHH:mm:ss

        #
        # NOTE: Does it look like the number of seconds since the epoch
        #       or some kind of date/time string?
        #
        if {[string is integer -strict $product(timeStamp)]} then {
          set product(dateTime) [clock format \
              $product(timeStamp) -format $dateTimeFormat]
        } else {
          set product(dateTime) [clock format \
              [clock scan $product(timeStamp)] -format $dateTimeFormat]


























        }

        #
        # NOTE: For build lines, compare the patch level from the line
        #       to the one we are currently using using a simple patch
        #       level comparison.
        #
        if {$checkBuild || $checkPlugin} then {
          #
          # NOTE: Compare patch level from this line against the one
          #       associated with the target product.
          #
          set compare [package \
              vcompare $product(patchLevel) $updatePatchLevel]
        } else {
          #
          # NOTE: This is not a build line, no match.
          #
          set compare -1; # force less than as fake result
        }

        #
        # NOTE: For script lines, use regular expression matching.
        #
        if {$checkScript} then {
          #
          # NOTE: Use [catch] here to prevent raising a script error due
          #       to a malformed patch level regular expression.
          #
          if {[catch {
            regexp -nocase -- $product(patchLevel) $updatePatchLevel
          } match]} then {
            #
            # NOTE: The patch level from the script line was most likely
            #       not a valid regular expression.
            #
            set match false
          }
        } else {
          #
          # NOTE: This is not a script line, so no match.
          #
          set match false
        }

        #
        # NOTE: Are we interested in further processing this line?
        #
        if {(($checkBuild || $checkPlugin) && $compare > 0) ||
            ($checkScript && $match)} then {
          #
          # NOTE: Grab the base URI field (i.e. may be a mirror site).
          #       Then, if set, use it as the base URI for the build
          #       and/or script.  Fallback to using the default base
          #       URI for builds (or scripts) when the base URI field
          #       is not present.
          #
          set product(baseUri) [lindex $fields 6]

          if {$checkBuild || $checkPlugin} then {
            if {[string length $product(baseUri)] > 0} then {
              set buildUri $product(baseUri)
            } else {
              set buildUri [getDownloadBaseUri]; # primary site.
            }
          }

          if {$checkScript} then {
            if {[string length $product(baseUri)] > 0} then {
              set scriptUri $product(baseUri)
            } else {
              set scriptUri [getScriptBaseUri]; # primary site.
            }
          }

          #
          # NOTE: Grab the md5, sha1, and sha512 fields.  These will only
          #       be used (and validated) if a script update is processed
          #       (below).  However, they will always be included in the
          #       result if the build is a later version.
          #
          set product(md5) [lindex $fields 7]
          set product(sha1) [lindex $fields 8]
          set product(sha512) [lindex $fields 9]

          #
          # NOTE: Grab the notes field (which may be empty) and unescape
          #       any reserved characters within it.  The notes may end
          #       up being included in the result returned to the caller
          #       and in that case they will be [list] escaped instead.
          #
          set product(notes) [lindex $fields 10]

          if {[string length $product(notes)] > 0} then {
            set product(notes) [unescapeUpdateNotes $product(notes)]
          }

          #
          # NOTE: The update patch level from the line is greater, we
          #       are out-of-date.  Return the result of our checking
          #       now.
          #
          if {$checkBuild || $checkPlugin} then {
            #
            # NOTE: Are we supposed to prompt the interactive user, if
            #       any, to upgrade now?
            #
            set text [appendArgs \
                $updateUriType " " $updateType " " \
                $product(patchLevel) ", dated " $product(dateTime) \
                ", is newer than the running " $updateType " " \
                $updatePatchLevel ", dated " $updateDateTime \
                ", based on the data from " $updateBaseUri]

            if {$prompt && [isInteractive]} then {
              #
              # NOTE: Is the [object] command available?  If not, this
              #       cannot be done.
              #
              if {[llength [info commands object]] > 0} then {
                set messageCaption [appendArgs \
                    [info engine Name] " (" [lindex [info level 0] 0] \
                    " script)"]

                set messageText [appendArgs \
                    "The " $text \n\n "Run the updater tool now?"]

                if {$automatic} then {
                  append messageText \n\n \
                      "WARNING: The updater tool process will be " \
                      "run in automatic mode and there will be no " \
                      "further prompts."
                }

                if {[object invoke -flags +NonPublic \
                    Eagle._Components.Private.WindowOps YesOrNo \
                    $messageText $messageCaption false]} then {
                  #
                  # NOTE: Ok, run the updater tool now and then exit.
                  #
                  runUpdateAndExit $automatic
                }
              }
            }

            #
            # NOTE: If we get to this point, the user has opted to not run
            #       the updater tool -OR- it cannot be run for some reason.
            #
            return [list \
                $text [list uri $buildUri patchLevel $product(patchLevel) \
                notes $product(notes) md5 $product(md5) sha1 $product(sha1) \
                sha512 $product(sha512)]]
          }

          #
          # NOTE: The script patch level from this line matches the current
          #       engine patch level exactly.  Therefore, the script should
          #       be evaluated if it can be authenticated.
          #
          if {$checkScript} then {
            #
            # NOTE: First, set the default channel for update script status
            #       messages.  If the test channel has been set (i.e. by the
            #       test suite), it will be used instead.

            #
            if {![info exists channel]} then {
              set channel [expr {
                [info exists ::test_channel] ? $::test_channel : "stdout"
              }]
            }

            #
            # NOTE: Next, verify the script has a valid base URI.  For update
            #       scripts, this must be the location where the update script
            #       data can be downloaded.
            #
            if {[string length $scriptUri] == 0} then {
              if {!$quiet} then {
                tqputs $channel [appendArgs \
                    "---- invalid baseUri value for update script " \
                    "line: " $line \"\n]
              }

              incr scriptCounts(invalid); continue
            }

            #
            # NOTE: Next, grab md5 field and see if it looks valid.  Below,
            #       the value of this field will be compared to that of the
            #       actual MD5 hash of the downloaded script data.

            #


            if {[string length $product(md5)] == 0} then {
              if {!$quiet} then {
                tqputs $channel [appendArgs \
                    "---- invalid md5 value for update script " \
                    "line: " $line \"\n]
              }

              incr scriptCounts(invalid); continue
            }

            #
            # NOTE: Next, grab sha1 field and see if it looks valid.  Below,
            #       the value of this field will be compared to that of the
            #       actual SHA1 hash of the downloaded script data.

            #


            if {[string length $product(sha1)] == 0} then {
              if {!$quiet} then {
                tqputs $channel [appendArgs \
                    "---- invalid sha1 value for update script " \
                    "line: " $line \"\n]
              }

              incr scriptCounts(invalid); continue
            }

            #
            # NOTE: Next, grab sha512 field and see if it looks valid.  Below,
            #       the value of this field will be compared to that of the

            #       actual SHA512 hash of the downloaded script data.
            #


            if {[string length $product(sha512)] == 0} then {
              if {!$quiet} then {
                tqputs $channel [appendArgs \
                    "---- invalid sha512 value for update script " \
                    "line: " $line \"\n]
              }

              incr scriptCounts(invalid); continue
            }

            #
            # NOTE: Next, show the extra information associated with this
            #       update script, if any.
            #
            if {!$quiet} then {
              tqputs $channel [appendArgs \
                  "---- fetching update script from \"" $scriptUri \
                  "\" (" $product(dateTime) ") with notes:\n"]

              set trimNotes [string trim $product(notes)]

              tqputs $channel [appendArgs \
                  [expr {[string length $trimNotes] > 0 ? $trimNotes : \
                  "<none>"}] "\n---- end of update script notes\n"]
            }

            #
            # NOTE: Next, attempt to fetch the update script data.
            #
            set code [catch {getUpdateScriptData $scriptUri} result]

            if {$code == 0} then {
              #
              # NOTE: Success, set the script data from the result.
              #
              set scriptData $result
            } else {
              #
              # NOTE: Failure, report the error message to the log.
              #
              if {!$quiet} then {
                tqputs $channel [appendArgs \
                    "---- failed to fetch update script: " $result \n]
              }

              incr scriptCounts(fail); continue
            }

            #
            # NOTE: Next, verify that the md5, sha1, and sha512 hashes of
            #       the raw script data match what was specified in the
            #       md5, sha1, and sha512 fields.
            #
            set md5 [hash normal md5 $scriptData]

            if {![string equal -nocase $product(md5) $md5]} then {
              if {!$quiet} then {
                tqputs $channel [appendArgs \
                    "---- wrong md5 value \"" $md5 \
                    "\" for update script line: " $line \"\n]
              }

              incr scriptCounts(bad); continue
            }

            set sha1 [hash normal sha1 $scriptData]

            if {![string equal -nocase $product(sha1) $sha1]} then {
              if {!$quiet} then {
                tqputs $channel [appendArgs \
                    "---- wrong sha1 value \"" $sha1 \
                    "\" for update script line: " $line \"\n]
              }

              incr scriptCounts(bad); continue
            }

            set sha512 [hash normal sha512 $scriptData]

            if {![string equal -nocase $product(sha512) $sha512]} then {
              if {!$quiet} then {
                tqputs $channel [appendArgs \
                    "---- wrong sha512 value \"" $sha512 \
                    "\" for update script line: " $line \"\n]
              }

              incr scriptCounts(bad); continue
            }

            #
            # NOTE: Everything looks good.  Therefore, evaluate the update
            #       script and print the result.
            #
            if {!$quiet} then {
              tqputs $channel [appendArgs \
                  "---- evaluating update script from \"" $scriptUri \
                  \"...\n]
            }

            #
            # NOTE: Reset the variables that will be used to contain the
            #       result of the update script.
            #
            set code 0; set result ""

            #
            # NOTE: Must manually override the file name to be returned by
            #       [info script] to refer back to the original script base
            #       URI.
            #
            set pushed false

            if {[llength [info commands object]] > 0} then {
              object invoke -flags +NonPublic Interpreter.GetActive \
                  PushScriptLocation $scriptUri true pushed
            }



            try {
              #
              # NOTE: Evaluate the update script in the context of the
              #       caller.
              #
              set code [catch {uplevel 1 $scriptData} result]
            } finally {
              #
              # NOTE: Reset manual override of the script file name to be
              #       returned by [info script].
              #

              object invoke -flags +NonPublic Interpreter.GetActive \
                  PopScriptLocation true pushed
            }

            #

            # NOTE: Keep track of number of update scripts that generate
            #       Ok and Error return codes.
            #
            if {$code == 0} then {
              incr scriptCounts(ok)
            } else {
              incr scriptCounts(error)
            }

            if {!$quiet} then {
              host result $code $result
              tqputs $channel "\n---- end of update script results\n"
            }
          }
        } elseif {($checkBuild || $checkPlugin) && $compare < 0} then {
          #
          # NOTE: The patch level from the line is less, we are more
          #       up-to-date than the latest version?
          #
          return [list [appendArgs \
              "running " $updateType " " $updatePatchLevel ", dated " \
              $updateDateTime ", is newer than the " $updateUriType " " \
              $updateType " " $product(patchLevel) ", dated " \
              $product(dateTime) ", based on the data " "from " \
              $updateBaseUri]]
        } elseif {$checkBuild || $checkPlugin} then {
          #
          # NOTE: The patch levels are equal, we are up-to-date.
          #
          return [list [appendArgs \
              "running " $updateType " " $updatePatchLevel ", dated " \
              $updateDateTime ", is the " $updateUriType " " $updateType \
              ", based on the data from " $updateBaseUri]]
        }
      }
    }


    #

    # NOTE: Figure out what the final result should be.  If we get to this
    #       point when checking for a new build, something must have gone
    #       awry.  Otherwise, report the number of update scripts that were
    #       successfully processed.
    #
    if {$wantScripts} then {
      set scriptCounts(total) [expr [join [array values scriptCounts] +]]

      if {$scriptCounts(total) > 0} then {
        return [list [appendArgs \
            "processed " $scriptCounts(total) " update scripts: " [array \
            get scriptCounts]]]
      } else {
        return [list "no update scripts were processed"]
      }
    } else {
      return [list [appendArgs \
          "could not determine if running " $updateType " is the latest " \
          $updateType]]
    }
  }

  #
  # NOTE: Provide the Eagle "update" package to the interpreter.
  #
  package provide Eagle.Update \
    [expr {[isEagle] ? [info engine PatchLevel] : "1.0"}]
}


      # NOTE: Check if the HTTPS security protocols need to be adjusted for
      #       use with the test suite and/or build tools.
      #
      checkForSecurityProtocols stdout \
          [checkForVendorQuiet checkForSecurityProtocols]
    }



































    #
    # HACK: Prevent the Eagle core test suite infrastructure from checking
    #       test constraints that are time-consuming and/or most likely to
    #       be superfluous to third-party test suites (i.e. those that are
    #       not testing the Eagle core library itself).
    #
    set no(core) 1

#
#           runTestEpilogue
#
if {![info exists test_all_path]} then {
  set test_all_path \
      [file normalize [file dirname [info script]]]
}

if {![info exists test_suite_file]} then {
  set test_suite_file [file normalize [info script]]
}

source [file join $test_all_path prologue.eagle]

if {![info exists test_path]} then {
  #
  # NOTE: Build a reusable expression that can be used to verify the
  #       candidate paths.  This is done to avoid duplication of this

#
# NOTE: Use our own namespace here because even though we do not directly
#       support namespaces ourselves, we do not want to pollute the global
#       namespace if this script actually ends up being evaluated in Tcl.
#
namespace eval ::Eagle {
  proc getKnownBuildTypes {} {
    if {[info exists ::test_well_known(buildTypes)]} then {
      return $::test_well_known(buildTypes)
    }

    return [list \
        NetFx20 NetFx35 NetFx40 NetFx45 NetFx451 \
        NetFx452 NetFx46 NetFx461 NetFx462 NetFx47 \
        NetFx471 NetFx472 NetFx48 NetStandard20 Bare \
        LeanAndMean Database MonoOnUnix Development]
  }

  proc getKnownCompileOptions {} {
    if {[info exists ::test_well_known(compileOptions)]} then {
      return $::test_well_known(compileOptions)
    }

    return [list \
        APPDOMAINS APPROVED_VERBS ARGUMENT_CACHE ARM ARM64 ASSEMBLY_DATETIME \
        ASSEMBLY_RELEASE ASSEMBLY_STRONG_NAME_TAG ASSEMBLY_TAG ASSEMBLY_TEXT \
        ASSEMBLY_URI BREAK_ON_EXITING BREAKPOINTS CACHE_ARGUMENT_TOSTRING \
        CACHE_ARGUMENTLIST_TOSTRING CACHE_DICTIONARY CACHE_RESULT_TOSTRING \
        CACHE_STATISTICS CACHE_STRINGLIST_TOSTRING CALLBACK_QUEUE CAS_POLICY \
        CERTIFICATE_PLUGIN CERTIFICATE_POLICY CERTIFICATE_RENEWAL \
        CODE_ANALYSIS COM_TYPE_CACHE CONFIGURATION CONSOLE DAEMON DATA \
        DEAD_CODE DEBUG DEBUGGER DEBUGGER_ARGUMENTS DEBUGGER_ENGINE \
        DEBUGGER_EXECUTE DEBUGGER_EXPRESSION DEBUGGER_VARIABLE DEBUG_TRACE \
        DEBUG_WRITE DEMO_EDITION DRAWING DYNAMIC EAGLE EMBEDDED_LIBRARY \
        EMBED_CERTIFICATES EMIT ENTERPRISE_LOCKDOWN EXECUTE_CACHE \
        EXPRESSION_FLAGS FAST_ERRORCODE FAST_ERRORINFO FOR_TEST_USE_ONLY \
        FORCE_TRACE HAVE_SIZEOF HISTORY IA64 INTERACTIVE_COMMANDS \
        INTERNALS_VISIBLE_TO ISOLATED_INTERPRETERS ISOLATED_PLUGINS LIBRARY \
        LICENSING LICENSE_MANAGER LIMITED_EDITION LIST_CACHE MONO MONO_BUILD \
        MONO_HACKS MONO_LEGACY NATIVE NATIVE_PACKAGE NATIVE_THREAD_ID \
        NATIVE_UTILITY NATIVE_UTILITY_BSTR NETWORK NET_20 NET_20_FAST_ENUM \
        NET_20_ONLY NET_20_SP1 NET_20_SP2 NET_30 NET_35 NET_40 NET_45 NET_451 \
        NET_452 NET_46 NET_461 NET_462 NET_47 NET_471 NET_472 NET_48 \
        NET_CORE_20 NET_STANDARD_20 NON_WORKING_CODE NOTIFY NOTIFY_ACTIVE \
        NOTIFY_ARGUMENTS NOTIFY_EXCEPTION NOTIFY_EXECUTE NOTIFY_EXPRESSION \
        NOTIFY_GLOBAL NOTIFY_OBJECT OBSOLETE OBFUSCATION OFFICIAL PARSE_CACHE \
        PATCHLEVEL PLUGIN_COMMANDS POLICY_TRACE PREVIOUS_RESULT RANDOMIZE_ID \
        REMOTING RESULT_LIMITS SAMPLE SCRIPT_ARGUMENTS SECURITY SERIALIZATION \
        SHARED_ID_POOL SHELL SOURCE_ID SOURCE_TIMESTAMP STATIC TCL TCL_KITS \
        TCL_THREADED TCL_THREADS TCL_UNICODE TCL_WRAPPER TEST TEST_PLUGIN \
        THREADING THROW_ON_DISPOSED TRACE TYPE_CACHE UNIX UNSAFE \
        USE_APPDOMAIN_FOR_ID USE_NAMESPACES VERBOSE WEB WINDOWS WINFORMS \
        WIX_30 WIX_35 WIX_36 WIX_37 WIX_38 WIX_39 WIX_310 WIX_311 X64 X86 XML]
  }

  proc getKnownWindowsVersions { {force false} } {
    if {[info exists ::test_well_known(windowsVersions)]} then {
      return $::test_well_known(windowsVersions)
    }

    if {$force || ![info exists ::no(windowsVersions)]} then {
      return [list [list 3 1] [list 3 5] [list 3 51] [list 4 0] [list 5 0] \
          [list 5 1] [list 5 2] [list 6 0] [list 6 1] [list 6 2] [list 6 3] \
          [list 10 0]]
    } else {
      return [list]
    }
  }

  proc getKnownMonoVersions { {force false} } {
    #
    # NOTE: This job of this procedure is to return the list of "known"
    #       versions of Mono supported by the test suite infrastructure.
    #
    # NOTE: Other than version 2.11 (which was officially announced and
    #       released), all of these releases are listed on the official
    #       release history pages:
    #
    #       https://en.wikipedia.org/wiki/Mono_%28software%29
    #       https://www.mono-project.com/docs/about-mono/releases/
    #       https://www.mono-project.com/docs/about-mono/versioning/
    #
    # TODO: This list should be manually updated when a new version of
    #       the Mono runtime is released -OR- when one is skipped (e.g.
    #       5.6 and 5.22).
    #
    if {[info exists ::test_well_known(monoVersions)]} then {
      return $::test_well_known(monoVersions)
    }

    if {$force || ![info exists ::no(monoVersions)]} then {
      return [list \
          [list 2 0] [list 2 2] [list 2 4] [list 2 6] [list 2 8] [list 2 10] \
          [list 2 11] [list 3 0] [list 3 1] [list 3 2] [list 3 4] [list 3 6] \
          [list 3 8] [list 3 10] [list 3 12] [list 4 0] [list 4 2] [list 4 4] \
          [list 4 6] [list 4 8] [list 5 0] [list 5 2] [list 5 4] [list 5 8] \
          [list 5 10] [list 5 12] [list 5 14] [list 5 16] [list 5 18] \
          [list 5 20] [list 6 0] [list 6 4] [list 6 6]]
    } else {
      return [list]
    }
  }

  proc addKnownMonoConstraints { generic } {
    #

      set constraints [list monoToDo monoBug monoCrash]

      foreach constraint $constraints {
        addConstraint $constraint
      }
    }
  }

  proc getKnownDotNetCoreVersions { {force false} } {
    #
    # NOTE: This job of this procedure is to return the list of "known"
    #       versions of .NET Core supported by the test suite infrastructure.
    #
    #       https://en.wikipedia.org/wiki/.NET_Core
    #       https://github.com/dotnet/core/releases
    #
    # TODO: This list should be manually updated when a new version of
    #       the .NET Core runtime is released.
    #
    if {[info exists ::test_well_known(dotNetCoreVersions)]} then {
      return $::test_well_known(dotNetCoreVersions)
    }

    if {$force || ![info exists ::no(dotNetCoreVersions)]} then {
      return [list [list 2 0] [list 2 1] [list 2 2] [list 3 0]]
    } else {
      return [list]
    }
  }

  proc addKnownDotNetCoreConstraints { generic } {
    #
    # NOTE: Does the caller want to add the version-specific constraints
    #       or the generic ones?
    #
    if {!$generic} then {
      #
      # NOTE: Add the necessary constraints for each version of .NET Core
      #       that we know about.
      #
      foreach dotNetCoreVersion [getKnownDotNetCoreVersions] {
        set constraintVersion [join $dotNetCoreVersion ""]

        addConstraint [appendArgs dotNetCoreToDo $constraintVersion]
        addConstraint [appendArgs dotNetCoreToDo $constraintVersion Only]
        addConstraint [appendArgs dotNetCoreBug $constraintVersion]
        addConstraint [appendArgs dotNetCoreBug $constraintVersion Only]
        addConstraint [appendArgs dotNetCoreCrash $constraintVersion]
        addConstraint [appendArgs dotNetCoreCrash $constraintVersion Only]
      }
    } else {
      #
      # NOTE: Also add just the generic .NET Core constraints that do not
      #       have a trailing version.
      #
      set constraints [list dotNetCoreToDo dotNetCoreBug dotNetCoreCrash]

      foreach constraint $constraints {
        addConstraint $constraint
      }
    }
  }

  proc getKnownTclVersions { {force false} } {
    #
    # NOTE: This job of this procedure is to return the list of "known"
    #       versions of Tcl/Tk supported by the test suite infrastructure.
    #
    if {[info exists ::test_well_known(tclVersions)]} then {
      return $::test_well_known(tclVersions)
    }

    if {$force || ![info exists ::no(tclVersions)]} then {
      return [list [list 8 4] [list 8 5] [list 8 6] [list 8 7]]
    } else {
      return [list]
    }
  }


    if {[info exists ::no(fossil)]} then {
      return false
    }

    if {[info exists ::no(canExecFossil)]} then {
      return false
    }

    return true
  }

  #
  # NOTE: This procedure should return non-zero if the "fsutil" tool may be
  #       executed by the test suite infrastructure outside the context of
  #       any specific tests.  The specific tests themselves must make use
  #       of their own constraints to prevent its execution.
  #
  proc canExecFsUtil {} {
    if {[info exists ::no(exec)]} then {
      return false
    }

    if {[info exists ::no(fsutil)]} then {
      return false
    }

    if {[info exists ::no(canExecFsUtil)]} then {
      return false
    }

    return true
  }

  #
  # NOTE: This procedure should return non-zero if the "vswhere" tool may be
  #       executed by the test suite infrastructure outside the context of

    if {![isEagle]} then {
      #
      # BUGFIX: We do not normally want to skip any Mono bugs in native Tcl.
      #
      if {![info exists ::no(runtimeVersion)]} then {
        addKnownMonoConstraints true; # running in native Tcl.
        addKnownMonoConstraints false; # running in native Tcl.
        addKnownDotNetCoreConstraints true; # running in native Tcl.
        addKnownDotNetCoreConstraints false; # running in native Tcl.
      }
    }
  }

  proc checkForWindowsVersion { channel } {
    tputs $channel "---- checking for Windows version... "

                  ", resetting...\n"]

              set osVersion $comSpecVersion
            }
          }
        }

        #
        # NOTE: Check all the well-known versions of Windows -AND- add
        #       appropriate test constraints.
        #
        foreach windowsVersion [getKnownWindowsVersions] {
          set dotWindowsVersion [getDottedVersion $windowsVersion]

          if {$osVersion >= $dotWindowsVersion} then {
            #
            # NOTE: Start out with the OS name, removing all spaces and
            #       then append the well-known OS version number as well
            #       as the suffix "_OrHigher" to indicate a inexact match.
            #
            set version [appendArgs \
                [string map [list " " ""] $::tcl_platform(os)] _ \
                $dotWindowsVersion _ OrHigher]

            addConstraint [appendArgs osVersion. $version]
          }
        }

        #
        # NOTE: Start out with the OS name, removing all spaces and then
        #       append the reported (or detected) OS version number.
        #
        set version [appendArgs \
            [string map [list " " ""] $::tcl_platform(os)] _ \
            $osVersion]

        if {[string length $extra] > 0} then {
          tputs $channel $extra
        }

        #
        # NOTE: We are done here, return now.
        #
        return
      }
    }

    tputs $channel no\n
  }

  proc checkForGetInstalledUpdates { channel {populate true} {timeout 60000} } {
    tputs $channel "---- checking for installed updates support... "

    if {[info exists ::tcl_platform(osExtra)]} then {
      #
      # HACK: When running in Eagle, wait for the "setup" event in
      #       the active interpreter.  This event will be signaled
      #       (only) after the "tcl_platform(osExtra)" element has
      #       been fully populated by its dedicated thread.
      #
      if {[isEagle]} then {
        if {[catch {
          object invoke -flags +NonPublic \
              Eagle._Components.Private.PlatformOps \
              ShouldPopulateOperatingSystemExtra "" \
              false true false true
        } should] == 0 && $should} then {
          if {[catch {
            if {$populate} then {
              object invoke -flags +NonPublic \
                  Eagle._Components.Private.PlatformOps \
                  PopulateOperatingSystemExtra "" \
                  false true
            }

            object invoke -flags +NonPublic \
                Interpreter.GetActive WaitSetupEvent \
                $timeout
          } code] || $code ne "Ok"} then {
            tputs $channel timeout\n

            return
          }
        } else {
          tputs $channel disabled\n

          return
        }
      }

      #
      # HACK: Assume the GetInstalledUpdates method works if the
      #       associated "tcl_platform" element is populated with
      #       the update names.  Technically, this check does not
      #       rely on anything specific to Windows; however, the
      #       underlying functionality is currently only present
      #       on Windows.
      #
      if {[llength [getDictionaryValue \
          $::tcl_platform(osExtra) UpdateNames]] > 0} then {
        addConstraint getInstalledUpdates

        tputs $channel yes\n

        return
      }
    }

    tputs $channel no\n
  }


    #       any instances of Visual Studio.
    #
    if {[canExecVsWhere]} then {
      #
      # NOTE: The versions of Visual Studio that we support detection
      #       of using the "vswhere" tool.
      #
      set versions [list [list 15.0 2017] [list 16.0 2019]]

      #
      # NOTE: Check each version and keep track of the ones we find.
      #
      foreach version $versions {
        #
        # NOTE: Attempt to fetch Visual Studio install directories

    if {![info exists ::no(stackIntensive)]} then {
      if {[isEagle]} then {
        #
        # NOTE: Attempt to query for native stack checking in Eagle.
        #
        if {[catch {
          object invoke -flags +NonPublic \
              Eagle._Components.Private.NativeStack IsAvailable
        } isAvailable] == 0 && \
            [string is true -strict $isAvailable]} then {
          #
          # NOTE: Yes, it appears that it is available.
          #
          addConstraint stackIntensive

          tputs $channel yes\n
        } else {

      } elseif {[isTestMono]} then {
        #
        # NOTE: Yes, it appears that we are running inside Mono.
        #
        addConstraint mono; # running on Mono.
        addConstraint monoOrDotNetCore

        #
        # NOTE: We do not want to skip .NET Core bugs on Mono.
        #
        addKnownDotNetCoreConstraints true; # running on Mono.

        tputs $channel [appendArgs [expr {[info exists \
            ::eagle_platform(runtime)] ? \
            $::eagle_platform(runtime) : "Mono"}] \n]
      } else {
        #
        # NOTE: It appears that we are running on the full .NET.
        #
        addConstraint dotNet; # running on .NET.
        addConstraint dotNetOrDotNetCore

        #
        # NOTE: We do not want to skip Mono -OR- .NET Core bugs on .NET.
        #
        addKnownMonoConstraints true; # running on .NET.
        addKnownDotNetCoreConstraints true; # running on .NET.

        tputs $channel [appendArgs [expr {[info exists \
            ::eagle_platform(runtime)] ? \
            $::eagle_platform(runtime) : "Microsoft.NET"}] \n]
      }
    }


            # NOTE: We are running on the .NET Core.  Keep track of the
            #       specific version for usage in test constraints.
            #
            addConstraint [appendArgs dotNetCore $version]
            addConstraint [appendArgs dotNetCore $version OrHigher]
          }

          #
          # NOTE: Attempt to parse the version into its major and minor
          #       components.
          #
          if {[string length $dotVersion] > 0 && [regexp -- {^(\d+)\.(\d+)$} \
              $dotVersion dummy majorVersion minorVersion]} then {
            #
            # NOTE: This is the list of .NET Core versions to add test
            #       constraints for.
            #
            set dotNetCoreVersions [list]

            #
            # NOTE: Check each .NET Core version "known" to the test
            #       suite.
            #
            foreach dotNetCoreVersion [getKnownDotNetCoreVersions] {
              #
              # NOTE: Check for any .NET Core major version X or higher.
              #
              if {$majorVersion >= [lindex $dotNetCoreVersion 0]} then {
                #
                # NOTE: Check for any .NET Core major/minor version
                #       higher than X.Y.
                #
                if {$majorVersion > [lindex $dotNetCoreVersion 0] || \
                    $minorVersion > [lindex $dotNetCoreVersion 1]} then {
                  #
                  # NOTE: Add this "known" version of .NET Core.
                  #
                  lappend dotNetCoreVersions $dotNetCoreVersion
                }
              }
            }

            #
            # NOTE: Add the necessary constraints for each version of .NET
            #       Core we should NOT skip bugs for.
            #
            foreach dotNetCoreVersion $dotNetCoreVersions {
              set constraintVersion [join $dotNetCoreVersion ""]

              addConstraint [appendArgs \
                  dotNetCore $constraintVersion OrHigher]

              addConstraint [appendArgs \
                  dotNetCoreToDo $constraintVersion]

              addConstraint [appendArgs \
                  dotNetCoreBug $constraintVersion]

              addConstraint [appendArgs \
                  dotNetCoreCrash $constraintVersion]
            }

            #
            # NOTE: Check all known versions of .NET Core for an exact match
            #       with the currently running one.
            #
            foreach dotNetCoreVersion [getKnownDotNetCoreVersions] {
              #
              # NOTE: Check if .NET Core major/minor version is exactly the
              #       one we are currently processing.
              #
              set constraintVersion [join $dotNetCoreVersion ""]

              if {[lindex $dotNetCoreVersion 0] == $majorVersion && \
                  [lindex $dotNetCoreVersion 1] == $minorVersion} then {
                #
                # NOTE: Add test constraints that only apply to this exact
                #       version of .NET Core.
                #
                addConstraint [appendArgs \
                    dotNetCore $constraintVersion Only]
              } else {
                #
                # NOTE: Add test constraints that apply to all versions of
                #       .NET Core except this exact version.
                #
                addConstraint [appendArgs \
                    dotNetCoreToDo $constraintVersion Only]

                addConstraint [appendArgs \
                    dotNetCoreBug $constraintVersion Only]

                addConstraint [appendArgs \
                    dotNetCoreCrash $constraintVersion Only]
              }
            }
          }

          #
          # NOTE: We do not want to skip any Mono bugs on .NET Core.  Add
          #       the necessary constraints for each version of Mono we
          #       know about.
          #
          addKnownMonoConstraints false; # running on .NET.
        } elseif {[isTestMono]} then {

                #
                addConstraint [appendArgs monoToDo $constraintVersion Only]
                addConstraint [appendArgs monoBug $constraintVersion Only]
                addConstraint [appendArgs monoCrash $constraintVersion Only]
              }
            }
          }

          #
          # NOTE: We do not want to skip any .NET Core bugs on Mono.  Add
          #       the necessary constraints for each version of Mono we
          #       know about.
          #
          addKnownDotNetCoreConstraints false; # running on Mono.
        } else {
          #
          # NOTE: If the runtime version was found, add a test constraint
          #       for it now.
          #
          if {[string length $version] > 0} then {
            #
            # NOTE: We are running on the .NET Framework.  Keep track of the
            #       specific version for usage in test constraints.
            #
            addConstraint [appendArgs dotNet $version]
            addConstraint [appendArgs dotNet $version OrHigher]
          }

          #
          # NOTE: We do not want to skip any Mono bugs on .NET.  Add the
          #       necessary constraints for each version of Mono we know
          #       about.
          #
          addKnownMonoConstraints false; # running on .NET.
          addKnownDotNetCoreConstraints false; # running on .NET.
        }

        tputs $channel [appendArgs \
            $::eagle_platform(runtimeVersion) " (" $dotVersion ")\n"]
      } else {
        tputs $channel no\n
      }

        #
        if {[string length $machine] == 0} then {
          set machine unknown
        }
      }

      #
      # NOTE: First, figure out what the file name for the Garuda DLL is,
      #       if anything.
      #
      set fileName [getGarudaDll $machine]

      if {[string length $fileName] > 0} then {
        #
        # NOTE: Next, check if the Garuda DLL is the same platform (i.e.
        #       machine type) as the native Tcl shell.
        #
        checkForFile $channel $fileName

        #
        # NOTE: Next, check if the Garuda DLL appears to be compatible
        #       with this platform.
        #
        tputs $channel [appendArgs \
            "---- checking if file \"" $fileName \
            "\" matches architecture for current process... "]

        if {[catch {
          library matcharchitecture $fileName; # maybe missing command?
        } match] == 0 && $match} then {
          addConstraint garudaLibrary

          tputs $channel yes\n
        } else {
          tputs $channel no\n
        }
      }
    }

    proc checkForCulture { channel } {
      tputs $channel "---- checking for culture... "

      #
      # NOTE: Grab the current culture.

      } members] == 0 && [llength $members] > 0} then {
        #
        # NOTE: Yes, it appears that it is available.
        #
        if {[string length $constraint] > 0} then {
          addConstraint [appendArgs member_ $constraint]
        } else {
          addConstraint [appendArgs $object . [string trim $member *?]]
        }

        tputs $channel yes\n
      } else {
        tputs $channel no\n
      }
    }

    proc checkForExcelUsable { channel {milliseconds 5000} } {
      tputs $channel "---- checking for usable instance of Excel... "

      #
      # NOTE: As of this writing, this check is only supported on Windows.
      #
      if {[isWindows]} then {
        #

                # NOTE: Give the newly created (isolated) interpreter a means
                #       to set variables in the parent (this) interpreter.
                #
                interp alias $interp pset {} set; # parent set

                #
                # NOTE: Give the newly created (isolated) interpreter a base
                #       name for a temporary file and our milliseconds value.
                #
                interp set $interp milliseconds $milliseconds
                interp set $interp tempName(1) $tempName(1)

                #
                # NOTE: Evaluate all the Excel interop assembly related code
                #       in the other AppDomain.
                #
                interp eval $interp {

                  # NOTE: Next, attempt to make sure that the Excel instance
                  #       is not visible and will not display alerts/prompts.
                  #       If this fails, Excel is not considered usable.
                  #
                  $application Visible false
                  $application DisplayAlerts false

                  #
                  # NOTE: Wait for a bit to make sure that the Excel process
                  #       is actually running (?).
                  #
                  after $milliseconds

                  #
                  # NOTE: Next, create a value of an enumerated type exposed
                  #       by the Excel automation object model so that we can
                  #       add a new workbook.  Generally, this does not fail.
                  #       If this fails, Excel is not considered usable.
                  #
                  set enumValue [object invoke -create \

                tputs $channel yes\n
              } else {
                #
                # NOTE: This is the list of error message patterns that may
                #       indicate a trial version of Excel is being used.
                #
                set patterns [list \
                    "* 0x80010001*" "* 0x800AC472*" "* 0x800A03EC*" \
                    "* application has expired.*"]

                #
                # NOTE: Check each error message pattern.  Upon finding any
                #       match, mark Excel as unusable due to being a trial
                #       edition and then stop.
                #

      # HACK: If this returns "error" that normally indicates an error was
      #       caught during [exec] (i.e. the native Tcl shell could not be
      #       executed).
      #
      set prefix "---- checking for Tcl shell version... "

      if {[canExecTclShell] && \
          ![info exists ::no(getTclVersionForTclShell)] && [catch {
        getTclVersionForTclShell "" [getTclShellVerbosity]
      } version] == 0 && $version ne "error" && \
          ![string match "error: *" $version]} then {
        #
        # NOTE: Yes, a native Tcl shell appears to be available.
        #
        addConstraint tclShell

        #
        # NOTE: Now, add the version specific test constraint.

      #       procedure, we only care if it returns "error" because that
      #       would indicate an error was caught during [exec] (i.e. the
      #       native Tcl shell could not be executed).
      #
      set prefix "---- checking for Tk package version... "

      if {[canExecTclShell] && \
          ![info exists ::no(getTkVersionForTclShell)] && [catch {
        getTkVersionForTclShell "" [getTclShellVerbosity]
      } version] == 0 && $version ne "error" && \
          ![string match "error: *" $version]} then {
        #
        # NOTE: Yes, a native Tk package appears to be available.
        #
        addConstraint tkPackage

        tputs $channel [appendArgs $prefix "yes (" $version ")\n"]
      } else {

      #
      if {[isWindows] && [info exists ::tcl_platform(osVersion)] && \
          $::tcl_platform(osVersion) >= 10.0 && \
          [haveTclPlatformOsExtraUpdateName "April 2018 Update"]} then {
        #
        # NOTE: We are running on Windows 10, return the special value.
        #
        return 461808; # BUGBUG: April 2018 Update only?
      }

      #
      # NOTE: We are not running on Windows 10, return the normal value.
      #
      return 461814
    }

    proc getFrameworkSetup48Value {} {
      #
      # NOTE: Check if we are running on Windows 10 or later.
      #
      # BUGBUG: Is greater-than-or-equal-to matching correct here?
      #
      if {[isWindows] && [info exists ::tcl_platform(osVersion)] && \
          $::tcl_platform(osVersion) >= 10.0 && \
          [haveTclPlatformOsExtraUpdateName "May 2019 Update"]} then {
        #
        # NOTE: We are running on Windows 10, return the special value.
        #
        return 528040; # BUGBUG: May 2019 Update only?
      }

      #
      # NOTE: We are not running on Windows 10, return the normal value.
      #
      return 528049
    }

    proc checkForNetFx4x { channel } {
      tputs $channel "---- checking for .NET Framework 4.x... "

      #
      # NOTE: Platform must be Windows for this constraint to even be
      #       checked (i.e. we require the registry).

          #       is installed.  However, if the "release" value is also
          #       greater than or equal to 379893, then the .NET Framework
          #       4.5.2 is installed, which is an in-place upgrade to 4.5.1
          #       (and 4.5).  If the "release" value is also greater than or
          #       equal to 393297 (393295 on Windows 10), then the .NET
          #       Framework 4.6 is installed, which is an in-place upgrade
          #       to 4.5.x.  Similar handling is necessary for the .NET
          #       Framework 4.6.1, 4.6.2, 4.7, 4.7.1, 4.7.2, and 4.8.  For
          #       more information, see:
          #
          #       https://msdn.microsoft.com/en-us/library/hh925568.aspx
          #
          if {$release >= [getFrameworkSetup48Value]} then {
            addConstraint dotNet451OrHigher
            addConstraint dotNet452OrHigher
            addConstraint dotNet46OrHigher
            addConstraint dotNet461OrHigher
            addConstraint dotNet462OrHigher
            addConstraint dotNet47OrHigher
            addConstraint dotNet471OrHigher
            addConstraint dotNet472OrHigher
            addConstraint dotNet48
            addConstraint dotNet48OrHigher

            set version 4.8
          } elseif {$release >= [getFrameworkSetup472Value]} then {
            addConstraint dotNet451OrHigher
            addConstraint dotNet452OrHigher
            addConstraint dotNet46OrHigher
            addConstraint dotNet461OrHigher
            addConstraint dotNet462OrHigher
            addConstraint dotNet47OrHigher
            addConstraint dotNet471OrHigher

        #       Visual Studio is currently always a 32-bit application.
        #
        set key [appendArgs HKEY_LOCAL_MACHINE\\ \
            [getSoftwareRegistryKey true] {\Microsoft\VisualStudio}]

        #
        # NOTE: The versions of Visual Studio that we support detection
        #       of using the registry.  This no longer works as of the
        #       release of Visual Studio 2017.  For Visual Studio 2017
        #       and beyond, the [checkForVisualStudioViaVsWhere] method
        #       must be used instead.
        #
        set versions [list [list 8.0 2005] [list 9.0 2008] \
            [list 10.0 2010] [list 11.0 2012] [list 12.0 2013] \
            [list 14.0 2015]]

        #
        # NOTE: Check each version and keep track of the ones we find.

    ###########################################################################

    #
    # NOTE: We need several of our test constraint related commands in the
    #       global namespace.
    #
    exportAndImportPackageCommands [namespace current] [list \
        getKnownBuildTypes getKnownCompileOptions getKnownWindowsVersions \
        getKnownMonoVersions addKnownMonoConstraints \
        getKnownDotNetCoreVersions addKnownDotNetCoreConstraints \
        getDotNetCoreLibPathDirectoryNameOnly lpermute alwaysFullInterpReady \
        canExecComSpec canExecWhoAmI canExecTclShell canExecFossil \
        canExecVsWhere isTestMono isTestDotNetCore isTestAdministrator canPing \
        cleanConstraintName cleanPackageName haveTclPlatformOsExtraUpdateName \
        checkForTestSuiteFiles checkForPlatform checkForWindowsVersion \
        checkForGetInstalledUpdates checkForOperatingSystemUpdate \
        checkForScriptLibrary checkForVariable checkForTclOptions \
        checkForWindowsCommandProcessor checkForPackage checkForFossil \
        checkForVisualStudioViaVsWhere checkForEagle checkForSymbols \
        checkForLogFile checkForGaruda checkForShell \
        checkForOfficialStableReleaseInProgress checkForDebug checkForTk \
        checkForVersion checkForCommand checkForSubCommand checkForEFormat \
        checkForNamespaces checkForTestExec checkForTestMachine \
        checkForTestPlatform checkForTestConfiguration checkForTestNamePrefix \
        checkForTestSuffix checkForFile checkForPathFile checkForNativeCode \
        checkForTip127 checkForTip194 checkForTip207 checkForTip241 \
        checkForTip285 checkForTip405 checkForTip421 checkForTip426 \

      error "cannot run epilogue, current frame not for this script"
    }
  }

  #
  # NOTE: Make sure all the variables used by this epilogue are unset.
  #
  unset -nocomplain memory stack name count passedOrSkipped \
      passedSkippedOrDisabled percent exitCode

  #
  # NOTE: Show when the tests actually ended (now).
  #
  tputs $test_channel [appendArgs "---- tests ended at " \
      [formatTimeStamp [set test_timestamp(endSeconds) \
      [clock seconds]]] \n]

    if {$eagle_tests(Skipped) > 0} then {
      tresult Break [appendArgs "SKIPPED: " $eagle_tests(Skipped) \n]

      if {[llength $eagle_tests(SkippedNames)] > 0} then {
        tresult Break [appendArgs "SKIPPED: " $eagle_tests(SkippedNames) \n]
      }
    }

    if {$eagle_tests(Disabled) > 0} then {
      tresult WhatIf [appendArgs "DISABLED: " $eagle_tests(Disabled) \n]
    }

    if {$eagle_tests(Total) > 0} then {
      tresult Return [appendArgs "TOTAL: " $eagle_tests(Total) \n]

      if {$eagle_tests(Skipped) > 0} then {
        set percent [getSkippedPercentage]

        tresult Break [appendArgs \
            "SKIP PERCENTAGE: " [formatDecimal $percent] %\n]
      }

      if {$eagle_tests(Disabled) > 0} then {
        set percent [getDisabledPercentage]

        tresult WhatIf [appendArgs \
            "DISABLED PERCENTAGE: " [formatDecimal $percent] %\n]
      }

      set percent [getPassedPercentage]

      tresult Return [appendArgs \
          "PASS PERCENTAGE: " [formatDecimal $percent] %\n]
    } else {
      #
      # NOTE: No tests.
      #

    #
    if {![info exists test_threshold] || $test_threshold == 100} then {
      #
      # NOTE: The test pass threshold is set to the default value (100%).
      #       Check to make sure that all tests pass and then set the
      #       exit code to success; otherwise, we set it to failure.
      #
      set passedSkippedOrDisabled [expr {$eagle_tests(Passed) + \
          $eagle_tests(Skipped) + $eagle_tests(Disabled)}]

      if {![info exists test_suite_errors] && \
          ([info exists no(failLogStartSentry)] || $haveStartSentry) && \
          $passedSkippedOrDisabled == $eagle_tests(Total)} then {
        set exitCode Success

        tresult Ok [appendArgs \
            "OVERALL RESULT: " [getTestSuiteFullName] \n]

        if {$eagle_tests(Total) > 0} then {
          tresult Ok "OVERALL RESULT: SUCCESS\n"
        } else {
          tresult Ok "OVERALL RESULT: NONE\n"
        }
      } else {
        set exitCode Failure

        tresult Error [appendArgs \
            "OVERALL RESULT: " [getTestSuiteFullName] \n]

        if {[info exists test_suite_errors]} then {
          tresult Error [appendArgs "OVERALL ERRORS: " \
              [expr {[llength $test_suite_errors] > 0 ? \
              $test_suite_errors : "<empty>"}] \n]
        }

        tresult Error "OVERALL RESULT: FAILURE\n"
      }

      unset passedSkippedOrDisabled
    } else {
      #
      # NOTE: They specified a non-default test pass threshold.  Check to
      #       make sure that we meet or exceed the requirement and then
      #       set the exit code to success; otherwise, set it to failure.
      #
      if {![info exists test_suite_errors] && \
          ([info exists no(failLogStartSentry)] || $haveStartSentry) && \
          $percent >= $test_threshold} then {
        set exitCode Success

        tresult Ok [appendArgs \
            "OVERALL RESULT: " [getTestSuiteFullName] \n]

        if {$eagle_tests(Total) > 0} then {
          tresult Ok [appendArgs \
              "OVERALL RESULT: SUCCESS (" \
              $percent "% >= " $test_threshold %)\n]
        } else {
          tresult Ok [appendArgs \
              "OVERALL RESULT: NONE (" \
              $percent "% >= " $test_threshold %)\n]
        }
      } else {
        set exitCode Failure

        tresult Error [appendArgs \
            "OVERALL RESULT: " [getTestSuiteFullName] \n]

        if {[info exists test_suite_errors]} then {
          tresult Error [appendArgs "OVERALL ERRORS: " \
              [expr {[llength $test_suite_errors] > 0 ? \
              $test_suite_errors : "<empty>"}] \n]
        }

        tresult Error [appendArgs \

    }

    if {$::tcltest::numTests(Total) > 0} then {
      tputs $test_channel [appendArgs \
          "TOTAL: " $::tcltest::numTests(Total) \n]

      if {$::tcltest::numTests(Skipped) > 0} then {
        set percent [getSkippedPercentage]

        tputs $test_channel [appendArgs \
            "SKIP PERCENTAGE: " [formatDecimal $percent] %\n]
      }

      set percent [getPassedPercentage]

      tputs $test_channel [appendArgs \
          "PASS PERCENTAGE: " [formatDecimal $percent] %\n]
    } else {
      #
      # NOTE: No tests.
      #

          $::tcltest::numTests(Skipped)}]

      if {![info exists test_suite_errors] && \
          ([info exists no(failLogStartSentry)] || $haveStartSentry) && \
          $passedOrSkipped == $::tcltest::numTests(Total)} then {
        set exitCode 0; # Success.

        tputs $test_channel [appendArgs \
            "OVERALL RESULT: " [getTestSuiteFullName] \n]

        if {$::tcltest::numTests(Total) > 0} then {
          tputs $test_channel "OVERALL RESULT: SUCCESS\n"
        } else {
          tputs $test_channel "OVERALL RESULT: NONE\n"
        }
      } else {
        set exitCode 1; # Failure.

        tputs $test_channel [appendArgs \
            "OVERALL RESULT: " [getTestSuiteFullName] \n]

        if {[info exists test_suite_errors]} then {
          tputs $test_channel [appendArgs "OVERALL ERRORS: " \
              [expr {[llength $test_suite_errors] > 0 ? \
              $test_suite_errors : "<empty>"}] \n]
        }

        tputs $test_channel "OVERALL RESULT: FAILURE\n"

      #       set the exit code to success; otherwise, set it to failure.
      #
      if {![info exists test_suite_errors] && \
          ([info exists no(failLogStartSentry)] || $haveStartSentry) && \
          $percent >= $test_threshold} then {
        set exitCode 0; # Success.

        tputs $test_channel [appendArgs \
            "OVERALL RESULT: " [getTestSuiteFullName] \n]

        if {$::tcltest::numTests(Total) > 0} then {
          tputs $test_channel [appendArgs \
              "OVERALL RESULT: SUCCESS (" $percent "% >= " $test_threshold %)\n]
        } else {
          tputs $test_channel [appendArgs \
              "OVERALL RESULT: NONE (" $percent "% >= " $test_threshold %)\n]
        }
      } else {
        set exitCode 1; # Failure.

        tputs $test_channel [appendArgs \
            "OVERALL RESULT: " [getTestSuiteFullName] \n]

        if {[info exists test_suite_errors]} then {
          tputs $test_channel [appendArgs "OVERALL ERRORS: " \
              [expr {[llength $test_suite_errors] > 0 ? \
              $test_suite_errors : "<empty>"}] \n]
        }

        tputs $test_channel [appendArgs \

  #
  # NOTE: Set the location of the test suite package, if necessary.
  #
  if {![info exists test_all_path]} then {
    set test_all_path [file normalize [file dirname [info script]]]
  }

  #
  # NOTE: Set the location of the primary test suite file, if necessary.
  #
  if {![info exists test_suite_file]} then {
    set test_suite_file [file normalize [info script]]
  }

  #
  # NOTE: Set the location of the test suite, if necessary.
  #
  if {![info exists test_path]} then {
    #
    # NOTE: Build a reusable expression that can be used to verify the
    #       candidate paths.  This is done to avoid duplication of this

  #############################################################################

  #
  # NOTE: Has native Tcl shell detection and use been disabled?
  #
  if {![info exists no(tclsh)]} then {
    #
    # NOTE: By default, disable verbose output when using the native
    #       Tcl shell within the test suite.
    #
    if {![info exists test_tclsh_verbose]} then {
      set test_tclsh_verbose 0
    }

    #
    # NOTE: Set the Tcl shell executable to use for those specialized
    #       tests that may require it, if necessary.
    #
    if {![info exists test_tclsh]} then {
      #
      # NOTE: When running in Eagle, more complex logic is required to

  tputs $test_channel [appendArgs "---- temporary files stored in: \"" \
      [getTemporaryPath] \"\n]

  tputs $test_channel [appendArgs "---- native Tcl shell: " \
      [expr {[info exists test_tclsh] && [string length $test_tclsh] > 0 ? \
          [appendArgs \" $test_tclsh \"] : "<none>"}] \n]

  tputs $test_channel [appendArgs \
      "---- verbosity level for native Tcl shell: " [expr {[info exists \
          test_tclsh_verbose] && [string length $test_tclsh_verbose] > 0 ? \
          $test_tclsh_verbose : "<none>"}] \n]

  tputs $test_channel [appendArgs "---- disabled options: " \
      [formatList [lsort [array names no]] <none>] \n]

  #
  # NOTE: Is the use of Fossil by the test suite allowed?
  #
  if {[canExecFossil]} then {

        if {![info exists no(compileDebuggerArguments)]} then {
          #
          # NOTE: For tests "object-5.1.*".
          #
          checkForCompileOption $test_channel DEBUGGER_ARGUMENTS
        }

        #
        # NOTE: Has script arguments stack support been enabled (at
        #       compile-time)?
        #
        if {![info exists no(compileScriptArguments)]} then {
          #
          # NOTE: For test "debug-2.86".
          #
          checkForCompileOption $test_channel SCRIPT_ARGUMENTS
        }

        #
        # NOTE: Has script breakpoint support been enabled (at compile-time)?
        #
        if {![info exists no(compileBreakpoints)]} then {
          #
          # NOTE: For test "proc-2.1".
          #

      }
    }

    #
    # NOTE: Has custom test method support been disabled?
    #
    if {![info exists no(core)] && ![info exists no(test)]} then {
      #
      # NOTE: Has UnknownCallback testing support been disabled?
      #
      if {![info exists no(testUnknownCallback)]} then {
        #
        # NOTE: For tests "unknown-*".
        #
        checkForObjectMember $test_channel Eagle._Tests.Default \
            *TestSetUnknownSpyCallback*

        checkForObjectMember $test_channel Eagle._Tests.Default \
            *TestSetUnknownScriptObjectCallback*

        checkForObjectMember $test_channel Eagle._Tests.Default \
            *TestSetUnknownScriptCommandCallback*

        checkForObjectMember $test_channel Eagle._Tests.Default \
            *TestSetUnknownObjectInvokeCallback*
      }

      #
      # NOTE: Has PackageCallback testing support been disabled?
      #
      if {![info exists no(testPackageCallback)]} then {
        #
        # NOTE: For test "package-2.1".
        #

        checkForObjectMember $test_channel Eagle._Tests.Default \
            *TestExecuteCallback1*

        checkForObjectMember $test_channel Eagle._Tests.Default \
            *TestExecuteCallback2*
      }

      #
      # NOTE: Has SleepWaitCallback testing support been disabled?
      #
      if {![info exists no(testSleepWaitCallback)]} then {
        #
        # NOTE: For test "vwait-1.31".
        #
        checkForObjectMember $test_channel Eagle._Tests.Default \
            *TestGetSleepWaitCallback*

        checkForObjectMember $test_channel Eagle._Tests.Default \
            *TestSetSleepWaitCallback*
      }

      #
      # NOTE: Has WriteHeader testing support been disabled?
      #
      if {![info exists no(testWriteHeader)]} then {
        #
        # NOTE: For test "host-1.5".

        checkForObjectMember $test_channel Eagle._Tests.Default \
            *TestSetVariableSystemArray*

        checkForObjectMember $test_channel Eagle._Tests.Default \
            *TestUnsetVariableSystemArray*
      }

      #
      # NOTE: Has reparse point testing support been disabled?
      #
      if {![info exists no(reparsePoints)]} then {
        #
        # NOTE: For tests "fileIO-14.*".
        #
        checkForObjectMember $test_channel Eagle._Tests.Default \
            *TestProcessReparseData*
      }

      #
      # NOTE: Has field testing support been disabled?
      #
      if {![info exists no(testFields)]} then {
        #
        # NOTE: For tests "basic-1.39", "basic-1.40", "basic-1.41",

  if {![info exists no(platform)]} then {
    checkForPlatform $test_channel
  }

  if {![info exists no(windowsVersion)]} then {
    checkForWindowsVersion $test_channel
  }

  if {![info exists no(getInstalledUpdates)]} then {
    checkForGetInstalledUpdates $test_channel
  }

  if {![info exists no(operatingSystemUpdates)]} then {
    if {[isEagle] && [info exists tcl_platform(osExtra)]} then {
      vwaitWithTimeout tcl_platform(osExtra) $test_timeout
    }

    checkForOperatingSystemUpdate $test_channel KB936929
    checkForOperatingSystemUpdate $test_channel KB976932
    checkForOperatingSystemUpdate $test_channel "November Update"
    checkForOperatingSystemUpdate $test_channel "Anniversary Update"
    checkForOperatingSystemUpdate $test_channel "Creators Update"
    checkForOperatingSystemUpdate $test_channel "Fall Creators Update"
    checkForOperatingSystemUpdate $test_channel "April 2018 Update"
    checkForOperatingSystemUpdate $test_channel "October 2018 Update"
    checkForOperatingSystemUpdate $test_channel "May 2019 Update"
  }

  if {![info exists no(scriptLibrary)]} then {
    checkForScriptLibrary $test_channel
  }

  if {![info exists no(tclOptions)]} then {

  if {![info exists no(lremoveCommand)]} then {
    checkForCommand $test_channel lremove
  }

  if {![info exists no(nopCommand)]} then {
    checkForCommand $test_channel nop
  }

  if {![info exists no(nprocCommand)]} then {
    checkForCommand $test_channel nproc
  }

  if {![info exists no(objectCommand)]} then {
    checkForCommand $test_channel object
  }

  if {![info exists no(parseCommand)]} then {
    checkForCommand $test_channel parse

    #
    checkForInteractiveCommand $test_channel done

    #
    # NOTE: For test "object-15.9".
    #
    checkForInteractiveCommand $test_channel args

    #
    # NOTE: For test "debug-10.1".
    #
    checkForInteractiveCommand $test_channel exit
    checkForInteractiveCommand $test_channel pause
    checkForInteractiveCommand $test_channel unpause
  }

  if {![info exists no(userInteraction)]} then {
    checkForUserInteraction $test_channel
  }

  #

  #
  tputs $test_channel [appendArgs "---- active constraints: " \
      [formatList [lsort [getConstraints]] <none>] \n]

  tputs $test_channel [appendArgs "---- cached constraints: " \
      [formatList [lsort [getCachedConstraints]] <none>] \n]

  #
  # NOTE: Show the lists of "well known" metadata.
  #
  tputs $test_channel [appendArgs "---- well known metadata: " \
      [formatListAsDict [array get test_well_known] <none>] \n]

  #
  # NOTE: Show the starting command count (for both Tcl and Eagle).
  #
  tputs $test_channel [appendArgs "---- starting command count: " \
      [info cmdcount] \n]

  if {[isEagle]} then {