Files in the top-level directory of check-in ee99c0e5ae21dd45

This will build a Tclkit named "tclkit-<version>".

---------------
Using This Tool
---------------
Usage:
	kitcreator [{<version> | cvs_<cvsTag> | clean | distclean}]
	           [<configure_options...>]

	Where:
		version            is a Tcl version number (e.g., 8.4.19)
		cvsTag             is a CVS release tag (e.g., HEAD)
		configure_options  are options to pass to subordinate configure
		                   scripts (e.g., --enable-64bit)

	Default is to create a Tclkit from Tcl version 8.4.19

Examples:
	1. Create a Tclkit:
		a. $ ./kitcreator

	2. Create a Tclkit for Tcl 8.5.8:
		a. $ ./kitcreator 8.5.8

	3. Create a Tclkit for Tcl from CVS HEAD:
		a. $ ./kitcreator cvs_HEAD

	4. Compile a 64-bit Tclkit:
		a. $ ./kitcreator --enable-64bit

	5. Cross-compile a Tclkit:
		a. Bootstrap (optional, you can use an existing Tclkit):
			i.   $ ./kitcreator
			ii.  $ mv tclkit-8.4.19 tclkit-local
			iii. $ TCLKIT="`pwd`/tclkit-local"
			iv.  $ export TCLKIT
		b. Cross-compile:
			i.   $ CC=mipsel-linux-uclibc-gcc
			ii.  $ AR=mipsel-linux-uclibc-ar
			iii. $ RANLIB=mipsel-linux-uclibc-ranlib
			iv.  $ export CC AR RANLIB
		v.   $ ./kitcreator --host=mipsel-linux-uclibc

	6. Compile a 64-bit Tclkit 8.5.8 using SunStudio 12.1 on Solaris/x86:
		a. $ CC='/opt/sunstudio12.1/bin/cc -m64'
		b. $ CXX='/opt/sunstudio12.1/bin/CC -m64'
		c. $ PATCH='gpatch'
		c. $ export CC CXX PATCH
		d. $ ./kitcreator 8.5.8 --enable-64bit

	7. To clean up post-build:
		a. $ ./kitcreator clean

Environment variables:
	1. MAKE
		Specifies the tool you wish to be called to build targets
		from a Makefile.  This script is generally more well tested
		with GNU Make.

	2. PATCH
		Specifies the tool you wish to be called to apply unified
		diff patches.  This script is generally more well tested with
		GNU Patch. 

	3. TCLKIT
		Specify the path to a Tclkit that is runnable on the current
		system.  The default is "tclkit".  A working tclkit is required
		for cross-compiling Tclkits.



-------------------
Method of Operation
-------------------
Summary:
	1. "kitcreator" calls */build.sh
	2. */build.sh downloads and compiles appropriate software
	3. */build.sh installs software into "inst" (run-time + compile-time)
	4. */build.sh installs run-time software into "out", this will be
	   included in the Tclkit as if it were the root directory of the
	   Tclkit (combined with other "out" directories)
	5. kitsh/build.sh compiles a "main" function and links all the built
	   libraries together into an executable
	6. kitsh/build.sh combines all the "out" directories into one
	7. kitsh/build.sh creates a Metakit database from the combined
	   directories and appends that to the compiled executable using:
		a. A Tclkit found in the environment variable "TCLKIT" (tclkit
		   if unset) if it is functional; or
		b. The built kit itself (does not work for cross-compiling)

Details:
	The general mechanism that enables a Tclkit to operate is a small Tcl
initialization routine linked statically to the core libraries needed to
operate a Tcl interpreter, the Tcl VFS Layer, and a database-backed (Metakit)
Virtual File System that is appended to the end of the executable.

This project brings together all of the required pieces, plus some additional
pieces that were found in the original Tclkit:
	1. Tk (dynamically linked)
	2. Itcl (dynamically linked)

These source code for these pieces are downloaded, compiled, and linked, and
the database containing the appropriate filesystem data is created.  What sets
this project apart from other similar projects is that:
	1. It attempts to be modular;
	2. It supports cross-compiling;
	3. It downloads the source from their original repositories;
	4. It allows you to specify an arbitrary version of Tcl (including
	   CVS); and
	5. It uses GNU Autoconf scripts for compiling the part of the Tclkit
	   that brings the whole thing together (the Kitsh)

To accomplish these goals the following mechanisms are in place:
	1. The top-level "kitcreator" script; and
	2. Per-project subdirectories, each containing a "build.sh" script

The top-level "kitcreator" script is very simple.  Its only job is to
interpret command line arguments, and call the per-project "build.sh" scripts.
For the "tcl" project it also finds the appropriate "tclConfig.sh" (and stores
this path in TCLCONFIGDIR) to enable subsequent build scripts to find the
appropriate Tcl to link against.

The per-project "build.sh" scripts are entirely autonomous.  They are
responsible for downloading the source code for the appropriate version that
will compile and link against the current version of Tcl (user requested
version can be found in "TCLVERS", while the actual version must be requested
from the "tclConfig.sh" script), compiling it, installing a functional copy
into the per-project "inst" directory, and installing anything that needs to
be in the Tclkit's VFS root into the per-project "out" directory.

The exception to this is the "kitsh" project.  It is the glue that binds all
the individual projects together into a single executable.  Its build script
does not create an "inst" or an "out" directory because it is not a library.
Instead, it collects all the other project's "out" directories into a single
directory (starpack.vfs), as well a static file (boot.tcl).  It then compiles
the source code, and then installs the Metakit database containing the VFS
onto the resulting executable.

To create the Metakit database, one of two Tclkits is used (tried in this
order):
	1. The Tclkit specified by the TCLKIT environment variable (or
	   "tclkit" if that variable is not set) if it is functional; or
	2. The built Tclkit itself

The second method will not work if the built Tclkit is not executable on the
current platform (i.e., in the case of cross-compilation) and so it may be
necessary to bootstrap a runnable Tclkit first.