summaryrefslogtreecommitdiffstats
path: root/doc/pkgMkIndex.n
diff options
context:
space:
mode:
Diffstat (limited to 'doc/pkgMkIndex.n')
-rw-r--r--doc/pkgMkIndex.n98
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