diff options
author | rjohnson <rjohnson@noemail.net> | 1998-03-26 14:45:59 (GMT) |
---|---|---|
committer | rjohnson <rjohnson@noemail.net> | 1998-03-26 14:45:59 (GMT) |
commit | 26a76b6c669bbb7629454ffa56a7f3f501a86dae (patch) | |
tree | 6e8c9473978f6dab66c601e911721a7bd9d70b1b /doc/pkgMkIndex.n | |
parent | f91eedbd6219cd3648cf1085083990df5c0e77dd (diff) | |
download | tcl-26a76b6c669bbb7629454ffa56a7f3f501a86dae.zip tcl-26a76b6c669bbb7629454ffa56a7f3f501a86dae.tar.gz tcl-26a76b6c669bbb7629454ffa56a7f3f501a86dae.tar.bz2 |
Initial revision
FossilOrigin-Name: cacdd0f329872d67973970d74c6978730bc24baa
Diffstat (limited to 'doc/pkgMkIndex.n')
-rw-r--r-- | doc/pkgMkIndex.n | 135 |
1 files changed, 135 insertions, 0 deletions
diff --git a/doc/pkgMkIndex.n b/doc/pkgMkIndex.n new file mode 100644 index 0000000..702c657 --- /dev/null +++ b/doc/pkgMkIndex.n @@ -0,0 +1,135 @@ +'\" +'\" Copyright (c) 1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) pkgMkIndex.n 1.8 97/10/31 12:51:13 +'\" +.so man.macros +.TH pkg_mkIndex n 7.6 Tcl "Tcl Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +pkg_mkIndex \- Build an index for automatic loading of packages +.SH SYNOPSIS +.nf +\fBpkg_mkIndex \fIdir\fR \fIpattern \fR?\fIpattern pattern ...\fR? +.fi +.BE + +.SH DESCRIPTION +.PP +\fBPkg_mkIndex\fR is a utility procedure that is part of the standard +Tcl library. +It is used to create index files that allow packages to be loaded +automatically when \fBpackage require\fR commands are executed. +To use \fBpkg_mkIndex\fR, follow these steps: +.IP [1] +Create the package(s). +Each package may consist of one or more Tcl script files or binary files. +Binary files must be suitable for loading with the \fBload\fR command +with a single argument; for example, if the file is \fBtest.so\fR it must +be possible to load this file with the command \fBload test.so\fR. +Each script file must contain a \fBpackage provide\fR command to declare +the package and version number, and each binary file must contain +a call to \fBTcl_PkgProvide\fR. +.IP [2] +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. +\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. +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 +than one directory, machine-dependent packages (e.g., those that +contain binary shared libraries) should normally be installed +under the first directory and machine-independent packages (e.g., +those that contain only Tcl scripts) should be installed under the +second directory. +The subdirectory should include +the package's script and/or binary files as well as the \fBpkgIndex.tcl\fR +file. As long as the package is installed as a subdirectory of a +directory in \fB$tcl_pkgPath\fR it will automatically be found during +\fBpackage require\fR commands. +.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 +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, +Tcl initializes \fBauto_path\fR from it during application startup. +.RE +.IP [4] +Once the above steps have been taken, all you need to do to use a +package is to invoke \fBpackage require\fR. +For example, if versions 2.1, 2.3, and 3.1 of package \fBTest\fR +have been indexed by \fBpkg_mkIndex\fR, the command +\fBpackage require Test\fR will make version 3.1 available +and the command \fBpackage require \-exact Test 2.1\fR will +make version 2.1 available. +There may be many versions of a package in the various index files +in \fBauto_path\fR, but only one will actually be loaded in a given +interpreter, based on the first call to \fBpackage require\fR. +Different versions of a package may be loaded in different +interpreters. + +.SH "PACKAGES AND THE AUTO-LOADER" +.PP +The package management facilities overlap somewhat with the auto-loader, +in that both arrange for files to be loaded on-demand. +However, package management is a higher-level mechanism that uses +the auto-loader for the last step in the loading process. +It is generally better to index a package with \fBpkg_mkIndex\fR +rather than \fBauto_mkindex\fR because the package mechanism provides +version control: several versions of a package can be made available +in the index files, with different applications using different +versions based on \fBpackage require\fR commands. +In contrast, \fBauto_mkindex\fR does not understand versions so +it can only handle a single version of each package. +It is probably not a good idea to index a given package with both +\fBpkg_mkIndex\fR and \fBauto_mkindex\fR. +If you use \fBpkg_mkIndex\fR to index a package, its commands cannot +be invoked until \fBpackage require\fR has been used to select a +version; in contrast, packages indexed with \fBauto_mkindex\fR +can be used immediately since there is no version control. + +.SH "HOW IT WORKS" +.PP +\fBPkg_mkIndex\fR depends on the \fBpackage unknown\fR command, +the \fBpackage ifneeded\fR command, and the auto-loader. +The first time a \fBpackage require\fR command is invoked, +the \fBpackage unknown\fR script is invoked. +This is set by Tcl initialization to a script that +evaluates all of the \fBpkgIndex.tcl\fR files in the +\fBauto_path\fR. +The \fBpkgIndex.tcl\fR files contain \fBpackage ifneeded\fR +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 +actually loaded until the first time one of its commands +is invoked. +Thus, after invoking \fBpackage require\fR you won't see +the package's commands in the interpreter, but you will be able +to invoke the commands and they will be auto-loaded. + +.SH KEYWORDS +auto-load, index, package, version |