Files in the top-level directory of check-in 5f6fa113cf737221

I. CLIENT
=========
This is a very basic implementation of a Teapot client.  It will fetch all
requested packages and their dependencies from a remote TEAPOT server.

1. Installing
-------------
The supplied Makefile only installs the client library.  A sample client that
makes use of this library is included.  The sample library is called
"teapot-client.tcl".

	a. To install with all the default options and auto configuration,
	   execute:
		# make install
	b. If you wish to install the package into a particular directory,
	   execute:
		# make install TCLDIR=your_particular_directory
	   (note that it will create a "teapotclient0.1" directory and
	    but no "lib" or similar directory)
	c. If you wish to install into an alternate root directory (i.e., for
	   packaging), execute:
		# make install DESTDIR=your_new_rootdir
	   This will search for a "tclConfig.sh" in the destination directory.
	d. If you wish to install into an alternate prefix (default is
	   "/usr/local"), execute:
		# make install PREFIX=your_new_prefix
	   (note that this only affects the search path and where the
	   "teapot-client" script is installed, not where the package goes
	   directly)

Note that the install directory is not encoded in the script in any way so it
can be safely moved after installation.

2. Using
--------

a. teapotclient:

	i. get_extensions
		SYNOPSIS
		package require teapotclient

		::teapotclient::get_extensions <teapot_server> \
		  ?<os_glob_pattern>? ?<cpu_glob_pattern>?

		DESCRIPTION
		get_extensions gets the extensions that are available from a
		TEAPOT server, for a particular operating system and CPU
		tuple (which can be glob patterns).

		The default OS and CPU patterns are both "*" which will match
		all operating system and cpus.

		RETURN VALUE
		The returned value is a list in the format of:
		{Extension_1} {ExtensionInfo_1} {Extension_2} {ExtensionInfo_2} ...

		Where ExtensionInfo_N is a list in the format of:
		ExtensionVersion ExtensionPlatformInfo

	ii. download_extensions
		SYNOPSIS
		package require teapotclient

		::teapotclient::download_extensions <rootdir> \
		  <list_of_teapot_servers> <list_of_extensions> \
		  <os_glob_pattern> <cpu_glob_pattern> \
		  ?<list_of_extensions_to_exclude>?

		DESCRIPTION
		download_extensions will download the list of extensions for a
		given operating system and CPU tuple, and download their
		dependencies recursively.  It will place each downloaded
		extensions in its own subdirectory beneath the specified
		"rootdir".

		The latest version available for the given OS and CPU tuple of
		each extension will be downloaded.

		You may optionally specify a list of extensions that you do not
		wish to be downloaded.

		RETURN VALUE
		The return value is a list of extensions actually downloaded.
		This may contain items that were not requested (if they were
		needed to satisfy a dependency), and may not contain all items
		that were requested (if they were unavailable).

		The list is in the format:
		{Extension_1} {ExtensionInfo_1} {Extension_2} {ExtensionInfo_2} ...

		Where ExtensionInfo_N is a list in the format of:
		ExtensionVersion ExtensionPlatformInfo ExtensionServer

	iii. setcachedir
		SYNOPSIS
		package require teapotclient

		::teapotclient::setcachedir <directory>

		DESCRIPTION
		The download_extensions and get_extensions commands use a
		local disk cache to improve performance.  The default
		cache directory is a directory in the user's home directory, or
		a temporary directory if a home directory is not found.

		setcachedir specifies an alternate location to store the cache.

		setcachedir should be called before any other commands if it is
		intended to be used.
	

		RETURN VALUE
		Unspecified.

	iv. Example 1:
		package require teapotclient

		puts "The following extensions are available:"
		foreach {extension extensioninfo} [::teapotclient::get_extensions \
		                                   [list teapot.activestate.com] \
		                                   {*} {*}] {
			puts "  $extension [join $extensioninfo {, }]"
		}

	 v. Example 2:
		package require teapotclient

		set os $tcl_platform(os)
		if {$tcl_platform(platform) == "windows"} {
			set os $tcl_platform(platform)
		}

		puts "Downloading md5 and sha1 packages for the current system"
		::teapotclient::download_extensions "." \
		  [list teapot.activestate.com] [list md5 sha1] $os \
		  $tcl_platform(machine)

		
b. teapot-client / teapot-client.tcl:
	i. teapot-client get <dir> <os> <cpu> <packages...>
		Downloads all the requested extensions/packages for the OS+CPU
		pair into the "lib" directory of the directory specified.

		Specifying a package name that begins with a "!" (bang) will
		indicate that the specified package does NOT need to be
		fetched, even if it is depended on by some other package.

	ii. teapot-client list ?<os>? ?<cpu>?
		Lists all available extensions and their most recent versions,
		optionally restricted to an OS+CPU pair.

II. SERVER
==========
This is not yet implemented.