diff options
| -rw-r--r-- | doc/pkgMkIndex.n | 73 |
1 files changed, 66 insertions, 7 deletions
diff --git a/doc/pkgMkIndex.n b/doc/pkgMkIndex.n index 7c02741..5ac1a9d 100644 --- a/doc/pkgMkIndex.n +++ b/doc/pkgMkIndex.n @@ -4,7 +4,7 @@ '\" 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.2 1998/09/14 18:39:54 stanton Exp $ +'\" RCS: @(#) $Id: pkgMkIndex.n,v 1.3 1998/10/17 00:16:38 escoffon Exp $ '\" .so man.macros .TH pkg_mkIndex n 7.6 Tcl "Tcl Built-In Commands" @@ -14,7 +14,9 @@ pkg_mkIndex \- Build an index for automatic loading of packages .SH SYNOPSIS .nf -\fBpkg_mkIndex \fIdir\fR \fIpattern \fR?\fIpattern pattern ...\fR? +.VS 8.0.3 +\fBpkg_mkIndex ?\fI-direct\fR? ?\fI-verbose\fR? ?\fI-nopkgrequire\fR? \fIdir\fR ?\fIpattern pattern ...\fR? +.VE .fi .BE @@ -39,6 +41,12 @@ Create the index by invoking \fBpkg_mkIndex\fR. The \fIdir\fR argument gives the name of a directory and each \fIpattern\fR argument is a \fBglob\fR-style pattern that selects script or binary files in \fIdir\fR. +.VS 8.0.3 +The default pattern is \fB*.tcl\fR and \fB*.[info sharedlibextension]\fR. +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 \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. @@ -46,7 +54,6 @@ 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). -.VS "" br .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 @@ -63,14 +70,13 @@ directory in \fB$tcl_pkgPath\fR it will automatically be found during .RS .LP If you install the package anywhere else, then you must ensure that -the directory contaiingn the package is in the \fBauto_path\fR global variable +the directory containing the package is in the \fBauto_path\fR global variable or an immediate subdirectory of one of the directories in \fBauto_path\fR. \fBAuto_path\fR contains a list of directories that are searched by both the auto-loader and the package loader; by default it includes \fB$tcl_pkgPath\fR. The package loader also checks all of the subdirectories of the directories in \fBauto_path\fR. -.VE You can add a directory to \fBauto_path\fR explicitly in your application, or you can add the directory to your \fBTCLLIBPATH\fR environment variable: if this environment variable is present, @@ -124,12 +130,65 @@ commands for each version of each available package; these commands invoke \fBpackage provide\fR commands to announce the availability of the package, and they setup auto-loader information to load the files of the package. -A given file of a given version of a given package isn't +.VS 8.0.3 +Unless the \fI-direct\fR flag was provided when the \fBpkgIndex.tcl\fR +was generated, +.VE +a given file of a given version of a given package isn't actually loaded until the first time one of its commands is invoked. -Thus, after invoking \fBpackage require\fR you won't see +Thus, after invoking \fBpackage require\fR you +.VS 8.0.3 +may +.VE +not see the package's commands in the interpreter, but you will be able to invoke the commands and they will be auto-loaded. +.VS 8.0.3 +.SH "DIRECT LOADING" +.PP +Some packages, for instance packages which use namespaces and export +commands or those which require special initialization, might select +that their package files be loaded immediately upon \fBpackage require\fR +instead of delaying the actual loading to the first use of one of the +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" +.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 + .SH KEYWORDS auto-load, index, package, version |