First draft of tcl/pkgs/README bundling instructions.

1 files changed, 57 insertions, 1 deletions

diff --git a/pkgs/README b/pkgs/README
index e2b33f5..01c6f43 100644
--- a/pkgs/README
+++ b/pkgs/README
@@ -1 +1,57 @@
-Add notes here about bundling packages with Tcl.
+
+The 'pkgs' subdirectory of the Tcl source code distribution is meant to be
+a place where the source code distribution of Tcl packages may be placed so
+that they are built, installed, and tested along with Tcl.  As originally
+distributed, Tcl re-distributes a number of packages in this location.  The
+build systems for Tcl are written so that additional packages may be added,
+or the original packages removed in any number and still have all packages
+present get built, installed, and tested along with Tcl.
+
+In order for a package to work properly under the pkgs subdirectory, it
+needs to conform to the following conventions.
+
+  All files of the package need to be contained in (subdirs of ...) a
+  single subdirectory of the "pkgs" directrory.
+
+  In that subdirectory of "pkgs" there must be an executable file named
+  "configure".  When the program "configure" is run, it should generate
+  a file "Makefile" in the current working directory.  The "configure"
+  program should be able to accept as command line arguments all the
+  arguments that can be passed to the master unix/configure program.  It
+  should also accept the --with-tcl= and --with-tclinclude= options in
+  the conventional way.
+
+  The generated "Makefile" must be one suitable for controlling the operations
+  of a `make` program.  The following targets must be defined:
+
+    <default>:	Perform a build of the runtime components of the
+		package from sources.
+
+    install:	Copy the runtime components of the package into their
+		installed location.  Must respect the DESTDIR variable
+		for determining the installation location.
+
+    test:	Run the test suite of the package.  Must respect the
+		TCLSH_PROG, TESTFLAGS variables.
+
+    clean:	Delete all files generated by the default build target.
+
+    distclean:	Delete all generated files. 
+
+    dist:	Produce a copy of the package's source code distribution.
+		Must respect the DIST_ROOT variable determing where to
+		write the generated directory.
+
+Packages that are written to make use of the Tcl Extension Architecture (TEA)
+and that make use of the tclconfig collection of support files, should 
+conform to these conventions without further efforts.
+
+These conventions are subject to revision and refinement over time to
+better support the needs of the build system.  Efforts will be made to
+keep the TEA support scripts consistent with the demands of this system.
+
+In addition, it is requested that packages also support building with
+Microsoft Visual Studio tools.  This means the file win/makefile.vc
+should be included, suitable for use by the nmake program, defining the
+targets <default>, install, test, and clean.
+