#
  # NOTE: This procedure returns the root directory where any packages that
  #       are downloaded should be saved to permanent storage for subsequent
  #       use.  There are no arguments.
  #
  proc getPersistentRootDirectory {} {
    global env
    #
    # NOTE: Return a directory parallel to the one containing the library
    #       directory.

    #
    # NOTE: Allow the persistent root directory to be overridden via the
    #       environment.  Typically, this customization will only be needed
    #       if multiple instances of Tcl need to share packages.
    #
    if {[info exists env(PKGD_ROOT)]} then {
      return $env(PKGD_ROOT)
    }

    #
    # NOTE: Fallback to returning a directory parallel to the one containing
    #       the library directory.
    #
    return [file join [file dirname [info library]] pkgd]
  }

  #
  # NOTE: This procedure, which is only used with native Tcl, generates a
  #       package index file (i.e. "pkgIndex.tcl") suitable for use with
  # NOTE: This procedure checks the configured persistent root directory for
  #       downloaded packages.  If any checks fail, a script error is raised.
  #       native Tcl 8.4 (or higher).  It will recursively [source] other
  #       native Tcl package index files that are within the configured
  #       persistent root directory, thereby causing all packages located
  #       within it to become available.  Since Eagle (by default) already
  #       performs a recursive search for its package index files, this
  #       procedure is not necessary for Eagle packages.
  #       There are no arguments.  The return value is undefined.
  #
  proc maybeCreateMasterTclPackageIndex {} {
  proc verifyPersistentRootDirectory {} {
    variable persistentRootDirectory

    if {![info exists persistentRootDirectory]} then {
      error "persistent root directory not set"
    }

    if {[string length $persistentRootDirectory] == 0} then {
      error "persistent root directory is invalid"
    }

    #
    # NOTE: Either the persistent root directory must already exist -OR- we
    #       must be able to create it.
    #
    if {![file isdirectory $persistentRootDirectory]} then {
    if {![file isdirectory $persistentRootDirectory] && \
        [catch {file mkdir $persistentRootDirectory}]} then {
      error "persistent root directory does not exist"
    }

    set fileName [file join $persistentRootDirectory pkgIndex.tcl]
  }

  #
  # NOTE: This procedure returns the name of the package index file for the
  #       language specified by the language argument.  An empty string will
  #       be returned if the language is unsupported or unrecognized.
  #
  proc getPackageIndexFileName { language } {
    if {[string length $language] == 0 || $language eq "eagle"} then {
      return pkgIndex.eagle
    } elseif {$language eq "tcl"} then {
      return pkgIndex.tcl
    } else {
      return ""
    }
  }

  #
  # NOTE: This procedure returns non-zero if the specified file appears
  #       to contain a master package index for native Tcl.  The fileName
  #       argument is the name of the file to check.
  #
  proc isMasterTclPackageIndex { fileName } {
    #
    # NOTE: Read all data from the specified file.  This should always be
    #       a relatively small file with a constant size.
    #
    set data [readFile $fileName]

    #
    # NOTE: Check the data read from the file for the magic string that
    #       we use to indicate a "master package index" file.
    #
    if {[string first <MASTER_PACKAGE_INDEX> $data] == -1} then {
      return false
    }

    #
    # TODO: Make this procedure smarter?
    #
    return true
  }

  #
  # NOTE: This procedure, which is only used for native Tcl, generates a
  #       package index file (i.e. "pkgIndex.tcl") suitable for use with
  #       native Tcl 8.4 (or higher).  It will recursively [source] other
  #       native Tcl package index files that are within the configured
  #       persistent root directory, thereby causing all packages located
  #       within it to become available.  Since Eagle (by default) already
  #       performs a recursive search for its package index files, this
  #       procedure is not necessary for Eagle packages.  This procedure
  #       will return non-zero if productive work was done.
  #
  proc maybeModifyMasterTclPackageIndex {} {
    variable persistentRootDirectory

    verifyPersistentRootDirectory
    set persistentDirectory $persistentRootDirectory

    set fileName [file join $persistentDirectory pkgIndex.tcl]

    if {[file exists $fileName]} then {
    if {[file exists $fileName] && ![isMasterPackageIndex $fileName]} then {
      return false
    }

    writeFile $fileName [string trim [string map [list \r\n \n] {
###############################################################################
#
# pkgIndex.tcl --

  }

  eval lappend pkgd(dirs) \
      [glob -nocomplain -types {d} [file join $pkgd(dir) *]]
}

set dir $pkgd(savedDir); unset -nocomplain pkgd
## <MASTER_PACKAGE_INDEX> ##
    }]]

    return true
  }

  #
  # NOTE: This procedure returns non-zero if the specified file seems to be
  #       an OpenPGP signature file.  The fileName argument is the name of
  #       the file to check, which may or may not exist.  The nameOnly
  #       argument should be non-zero to ignore the contents of the file.
  #
  proc isPgpSignatureFileName { fileName nameOnly } {
  proc isOpenPgpSignatureFileName { fileName nameOnly } {
    if {[string length $fileName] == 0} then {
      return false
    }

    set extension [file extension $fileName]

    if {$extension eq ".asc"} then {
      if {!$nameOnly && [file exists $fileName]} then {
        return [::PackageRepository::isPgpSignature [readFile $fileName]]
        return [::PackageRepository::isOpenPgpSignature \
            [readFile $fileName]]
      } else {
        return true
      }
    } else {
      return false
    }
  }

      return false
    }

    set extension [file extension $fileName]

    if {$extension eq ".harpy"} then {
      if {!$nameOnly && [file exists $fileName]} then {
        return [::PackageRepository::isHarpyCertificate [readFile $fileName]]
        return [::PackageRepository::isHarpyCertificate \
            [readFile $fileName]]
      } else {
        return true
      }
    } else {
      return false
    }
  }

  #
  # NOTE: This procedure returns the auto-path for the language specified by
  #       the language argument.  An empty list is returned if the auto-path
  #       does not exist in the target language.  This procedure may raise
  #       script errors.
  #
  proc getAutoPath { language } {
    if {[string length $language] == 0 || $language eq "eagle"} then {
      if {[isEagle]} then {
        if {![info exists ::auto_path]} then {
          return [list]
        }

        return $::auto_path
      } else {
        ::PackageRepository::eagleMustBeReady

        eagle {
          if {![info exists ::auto_path]} then {
            return [list]
          }

          return $::auto_path
        }
      }
    } elseif {$language eq "tcl"} then {
      if {[isEagle]} then {
        tcl eval [tcl master] {
          if {![info exists ::auto_path]} then {
            return [list]
          }

          return $::auto_path
        }
      } else {
        if {![info exists ::auto_path]} then {
          return [list]
        }

        return $::auto_path
      }
    } else {
      error "unsupported language, no idea how to query auto-path"
    }
  }

  #
  # NOTE: This procedure adds a directory to the auto-path of the specified
  #       language (i.e. native Tcl or Eagle).  The directory will not be
  #       added if it is already present.  The language argument must be the
  #       literal string "eagle" or the literal string "tcl".  The directory
  #       argument is the fully qualified path for the directory to add to

          lappend ::auto_path $directory
        }
      }
    } else {
      error "unsupported language, no idea how to modify auto-path"
    }
  }

  #
  # NOTE: This procedure adds a directory to the auto-path of the specified
  #       language (i.e. native Tcl or Eagle).  The directory will not be
  #       added if it is already present.  The language argument must be the
  #       literal string "eagle" or the literal string "tcl".  The directory
  #       argument is the fully qualified path for the directory to add to
  #       the auto-path.  The directory will not be added if it falls under
  #       a directory already in the auto-path.
  #
  proc maybeAddToAutoPath { language directory } {
    #
    # NOTE: Verify that the directory to be added is valid and exists.  If
    #       not, do nothing.
    #
    if {[string length $directory] == 0 || \
        ![file isdirectory $directory]} then {
      return false
    }

    #
    # NOTE: Normalize the specified directory.  This is necessary so that
    #       we can compare apples-to-apples within the auto-path.
    #
    set directory [file normalize $directory]
    set directoryLength [string length $directory]

    #
    # NOTE: Query the auto-path for the target language.
    #
    set autoPath [getAutoPath $language]

    #
    # NOTE: Check each directory in the auto-path to see if the specified
    #       directory is already underneath it.
    #
    foreach autoDirectory $autoPath {
      #
      # NOTE: Normalize the auto-path directory.  This is necessary so
      #       that we can compare apples-to-apples with the specified
      #       directory.
      #
      set autoDirectory [file normalize $autoDirectory]
      set autoDirectoryLength [string length $autoDirectory]

      #
      # NOTE: Prefix match is impossible if the length of the specified
      #       directory is less than the length of this directory in the
      #       auto-path.
      #
      if {$directoryLength < $autoDirectoryLength} then {
        continue
      }

      #
      # NOTE: If the initial portion of the specified directory is the
      #       same as this directory in the auto-path, it must reside
      #       underneath it.  In that case, there is no need to modify
      #       the auto-path, bail out now.
      #
      set last [expr {$autoDirectoryLength - 1}]

      if {[string range $directory 0 $last] eq $autoDirectory} then {
        return false
      }
    }

    #
    # NOTE: At this point, it is pretty safe to assume that the specified
    #       directory is not in the auto-path, nor underneath a directory
    #       within the auto-path.
    #
    addToAutoPath $language $directory

    return true
  }

  #
  # NOTE: This procedure verifies the combination of language and version
  #       specified by the caller.  The language argument must be one of the
  #       literal strings "eagle", "tcl", or "client".  The version argument
  #       must be one of the literal strings "8.4", "8.5", or "8.6" when the
  #       language is "tcl" -OR- the literal string "1.0" when the language

  #       directory on the package file server and may be an empty string.  The
  #       usePgp argument should be non-zero when an OpenPGP signature file
  #       needs to be downloaded and verified for the downloaded file.
  #
  # <public>
  proc checkForHigherVersion { language version packageName usePgp } {
    variable clientDirectory
    variable persistentRootDirectory
    variable temporaryRootDirectory

    verifyLanguageAndVersion $language $version isClient

    set temporaryDirectory [file join \
        $temporaryRootDirectory [appendArgs \
        pkgd_ver_ [::PackageRepository::getUniqueSuffix]]]

    if {$isClient} then {
      set persistentDirectory $clientDirectory
    } else {
      verifyPersistentRootDirectory
      set persistentDirectory $persistentRootDirectory
    }

    set fileName [file join $packageName VERSION]
    set downloadFileName [file join $temporaryDirectory $fileName]

    file mkdir [file dirname $downloadFileName]

    #
    writeFile $localFileName [getPackageFile $uri]

    #
    # NOTE: Is use of OpenPGP for signature verification enabled?  Also,
    #       did we just download an OpenPGP signature file?
    #
    if {$usePgp && [isPgpSignatureFileName $localFileName true]} then {
    if {$usePgp && [isOpenPgpSignatureFileName $localFileName true]} then {
      #
      # NOTE: Attempt to verify the OpenPGP signature.  If this fails,
      #       an error is raised.
      #
      if {![::PackageRepository::verifyPgpSignature $localFileName]} then {
      if {![::PackageRepository::verifyOpenPgpSignature $localFileName]} then {
        error [appendArgs \
            "bad PGP signature \"" $localFileName \"]
            "bad OpenPGP signature \"" $localFileName \"]
      }
    }
  }

  #
  # NOTE: This procedure attempts to download a list of files, optionally
  #       persistening them for subsequent uses by the target language.

    set temporaryDirectory [file join \
        $temporaryRootDirectory [appendArgs \
        pkgd_lib_ [::PackageRepository::getUniqueSuffix]]]

    if {$isClient} then {
      set persistentDirectory $clientDirectory
    } else {
      verifyPersistentRootDirectory
      set persistentDirectory $persistentRootDirectory
    }

    set downloadedFileNames [list]

    foreach fileName $fileNames {
      if {[string length $fileName] == 0 || \

      file mkdir [file dirname $downloadFileName]
      downloadOneFile $language $version $fileName $downloadFileName $usePgp

      lappend downloadedFileNames [list \
          $fileNameOnly $directory(temporary) $directory(persistent)]

      if {$usePgp && ![isPgpSignatureFileName $downloadFileName true]} then {
      if {$usePgp && ![isOpenPgpSignatureFileName $downloadFileName true]} then {
        downloadOneFile $language $version [appendArgs $fileName .asc] \
            [appendArgs $downloadFileName .asc] $usePgp

        lappend downloadedFileNames [list \
            [appendArgs $fileNameOnly .asc] $directory(temporary) \
            $directory(persistent)]
      }

      if {$persistent || $viaInstall} then {
        set fileNameOnly [lindex $downloadedFileName 0]
        set directory(persistent) [lindex $downloadedFileName 2]

        file mkdir $directory(persistent)
        set command [list file copy]

        #
        # NOTE: When updating the package repository client files, always
        #       use the -force option to overwrite existing files.
        #
        if {$isClient} then {
          lappend command -force
        }

        lappend command --
        lappend command [file join $directory(temporary) $fileNameOnly]
        lappend command [file join $directory(persistent) $fileNameOnly]

        eval $command

        lappend downloadDirectories $directory(persistent)
      } else {
        lappend downloadDirectories $directory(temporary)
      }
    }

    #
    # NOTE: Does the package need to be persisted locally?  This can be set
    #       via the direct caller or via the installer tool.
    #
    set addPersistentDirectoryToAutoPath false

    if {$persistent || $viaInstall} then {
      #
      # NOTE: In Eagle, a slightly different command is required to delete
      #       an entire directory tree.
      #
      if {[isEagle]} then {
        file delete -recursive -- $temporaryDirectory
      } else {
        file delete -force -- $temporaryDirectory
      }

      #
      # NOTE: When dealing with packages for native Tcl, modify the master
      #       package index.
      #
      if {$language eq "tcl"} then {
        set addPersistentDirectoryToAutoPath [maybeModifyMasterTclPackageIndex]
      }
    }

    #
    # NOTE: Sort the list of directories that downloaded files were written
    #       to, removing any duplicates in the process.
    #
    set downloadDirectories [lsort -unique $downloadDirectories]

    if {$useAutoPath} then {
      #
      # NOTE: The auto-path, for whatever language this package belongs to,
      #       needs to be modified.
      #
      if {$addPersistentDirectoryToAutoPath} then {
        #
        # NOTE: The downloaded package was persisted -AND- will be handled
        #       by the master package index; therefore, just make sure the
        #       package persistence root directory is in the auto-path and
        #       then return only that directory in the result.
        #
        maybeAddToAutoPath $language $persistentDirectory
        set downloadDirectories [list $persistentDirectory]
      } else {
        #
        # NOTE: Check each unique download directory for a package index
        #       file.  If a directory has a package index for the target
        #       language, add to the auto-path for the target language.
        #
        set packageIndexFileName [getPackageIndexFileName $language]

        if {[string length $packageIndexFileName] > 0} then {
      foreach downloadDirectory $downloadDirectories {
        addToAutoPath $language $downloadDirectory
      }
    }

          foreach downloadDirectory $downloadDirectories {
            if {[file exists [file join \
                $downloadDirectory $packageIndexFileName]]} then {
              addToAutoPath $language $downloadDirectory
            }
          }
        }
    if {$persistent || $viaInstall} then {
      if {[isEagle]} then {
        file delete -recursive -- $temporaryDirectory
      } else {
        file delete -force -- $temporaryDirectory
        maybeCreateMasterTclPackageIndex
      }
    }

    #
    # NOTE: Always return the list of directories that were actually added
    #       to the auto-path, if any.
    #
    return $downloadDirectories
  }

  #
  # NOTE: This package requires that support for namespaces, which is an
  #       optional feature of Eagle, must be enabled.
  #

  ::PackageRepository::maybeReadSettingsFile [info script]

  #
  # NOTE: Setup the variables, within this namespace, used by this script.
  #
  setupDownloadVars [info script]

  #
  # NOTE: If necessary, add the package persistence root directory to the
  #       auto-path for the current language.  This will only be done if
  #       it falls outside of the existing auto-path.
  #
  variable persistentRootDirectory

  maybeAddToAutoPath [expr {[isEagle] ? "eagle" : "tcl"}] \
      $persistentRootDirectory

  #
  # NOTE: Provide the package to the interpreter.
  #
  package provide Eagle.Package.Downloader \
    [expr {[isEagle] ? [info engine PatchLevel] : "1.0"}]
}