Overhaul of pkg_mkIndex

1 files changed, 63 insertions, 35 deletions

diff --git a/doc/pkgMkIndex.n b/doc/pkgMkIndex.n
index 5ac1a9d..e4bcf78 100644
--- a/doc/pkgMkIndex.n
+++ b/doc/pkgMkIndex.n
@@ -4,10 +4,10 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: pkgMkIndex.n,v 1.3 1998/10/17 00:16:38 escoffon Exp $
+'\" RCS: @(#) $Id: pkgMkIndex.n,v 1.4 1998/10/30 23:02:02 welch Exp $
 '\" 
 .so man.macros
-.TH pkg_mkIndex n 7.6 Tcl "Tcl Built-In Commands"
+.TH pkg_mkIndex n 8.0 Tcl "Tcl Built-In Commands"
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -15,7 +15,7 @@ pkg_mkIndex \- Build an index for automatic loading of packages
 .SH SYNOPSIS
 .nf
 .VS 8.0.3
-\fBpkg_mkIndex ?\fI-direct\fR? ?\fI-verbose\fR? ?\fI-nopkgrequire\fR? \fIdir\fR ?\fIpattern pattern ...\fR?
+\fBpkg_mkIndex ?\fI-direct\fR? ?\fI-verbose\fR? \fIdir\fR ?\fIpattern pattern ...\fR?
 .VE
 .fi
 .BE
@@ -47,6 +47,8 @@ If the optional \fI-direct\fR argument is given, the generated index
 will manage to load the package immediately upon \fBpackage require\fR
 instead of delaying loading until actual use of one of the commands.
 .VE
+.RS
+.LP
 \fBPkg_mkIndex\fR will create a file \fBpkgIndex.tcl\fR in \fIdir\fR
 with package information about all the files given by the \fIpattern\fR
 arguments.
@@ -54,6 +56,11 @@ It does this by loading each file and seeing what packages
 and new commands appear (this is why it is essential to have
 \fBpackage provide\fR commands or \fBTcl_PkgProvide\fR calls
 in the files, as described above).
+If you have a package split among scripts and binary files, 
+or if you have dependencies among files,
+you may have to adjust the order in which \fBpkg_mkIndex\fR processes
+the files.  See COMPLEX CASES below.
+.RE
 .IP [3]
 Install the package as a subdirectory of one of the directories given by
 the \fBtcl_pkgPath\fR variable.  If \fB$tcl_pkgPath\fR contains more
@@ -156,39 +163,60 @@ package's command. This mode is enabled when generating the package
 index by specifying the \fI-direct\fR argument.
 .VE
 
-.VS 8.0.3
-.SH "INDEXING OF DEPENDENT PACKAGES"
+.SH "COMPLEX CASES"
+Most complex cases of dependencies among scripts
+and binary files, and packages being split among scripts and
+binary files are handled OK.  However, you may have to adjust
+the order in which files are processed by \fBpkg_mkIndex\fR.
+The only case that is not supported is a package that is
+provided by more than one binary file.
+These issues are described in detail below.
 .PP
-Earlier versions of \fBpkg_mkIndex\fR were unable to handle some packages
-that did a \fIpackage require\fR for a second package also to be indexed,
-and then proceeded to execute
-code from that package (for example in a \fInamespace eval\fR construct).
-This happended because the autoloading mechanism did not have access to
-the index file being built, thus causing \fIpackage require\fR to fail.
-\fBPkg_mkIndex\fR circumvented this problem by redefining
-\fIpackage require\fR to be a null operation, which in turn then caused the
-indexing to fail when procedures from the second package were being called
-in the first.
-.LP
-\fBPkg_mkIndex\fR now implements \fIpackage require\fR. Additionally, it
-does the indexing in multiple passes, until either
-all files have been indexed, or until the current pass could index no more
-files. For each pass, files that were indexed are added to a partial
-\fBpkgIndex.tcl\fR, which is reloaded at the start of each pass. In the case
-described above, for example, \fBpkg_mkIndex\fR will do two passes. During the
-first pass, the first package will not index, but the second will. Then,
-during the second pass, the first package will be able to
-\fIpackage require\fR the second, and therefore will also be indexed.
-If the \fI-verbose\fR optional argument is givem, \fBpkg_mkIndex\fR will
-display its progress.
-.LP
-Under some conditions, \fBpkg_mkIndex\fR may not be able to index any file
-during a pass; for example, if package \fIa\fR requires package \fIb\fR,
-and package \fIb\fR requires package \fIa\fR, neither one can be indexed.
-In these situations, you can give the \fI-nopkgrequire\fR optional argument;
-this will cause \fBpkg_mkIndex\fR to revert to the old behaviour, where
-\fIpackage require\fR is a null operation.
-.VE
+If each script or file contains one package, and packages
+are only contained in one file, then things are easy.
+You simply specify all files to be indexed in any order
+with some glob patterns.
+.PP
+In general, it is OK for scripts to have dependencies on other
+packages.
+If scripts contain \fBpackage require\fP commands, these are
+stubbed out in the interpreter used to process the scripts,
+so these do not cause problems.
+If scripts call into other packages in global code,
+these calls are handled by a stub \fBunknown\fP command.
+However, if scripts make variable references to other package's
+variables in global code, these will cause errors.  That is
+also bad coding style.
+.PP
+If binary files have dependencies on other packages, things
+can become tricky because it is not possible to stub out
+the C-level \fBTcl_PkgRequire\fP API.
+For example, suppose the BLT package requires Tk, and expresses
+this with a call to \fBTcl_PkgRequire\fP in its \fBBlt_Init\fP routine.
+To support this, you must run \fBpkg_mkIndex\fR in a shell that
+has Tk loaded.  \fBpkg_mkIndex\fR will load any packages listed by
+\fBinfo loaded\fP into the interpreter used to process files.
+In most cases this will satisfy the \fBTcl_PkgRequire\fP calls
+made by binary files.
+.PP
+If you are indexing two binary files and one depends on the other,
+you should specify the one that has dependencies last.
+This way the one without dependencies will get loaded and indexed,
+and then the package it provides
+will be available when the second file is processed.
+.PP
+You cannot have the same package provided by two different binary
+files.  Well, you can, but they cannot be indexed by \fBpkg_mkIndex\fR
+and it seems like a poor design choice anyway.  The problem is that
+once the package is provided by the first binary file, then that
+masks the provide made by the other binary file.  If you
+absolutely must do this, you'll have to run \fBpkg_mkIndex\fR on
+each different file, save the resulting pkgIndex.tcl files,
+and merge the results.
+.PP
+If you have a package that is split across scripts and a binary file,
+then you must specify the scripts first; otherwise the package loaded from
+the binary file may mask the package defined by the scripts.
 
 .SH KEYWORDS
 auto-load, index, package, version