116 lines
5.1 KiB
Plaintext
116 lines
5.1 KiB
Plaintext
'\"
|
|
'\" 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.2 96/02/15 20:03:23
|
|
'\"
|
|
.so man.macros
|
|
.TH pkg_mkIndex n 7.5 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 \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).
|
|
.IP [3]
|
|
Make sure that the directory is in the \fBauto_path\fR global variable.
|
|
\fBAuto_path\fR contains a list of directories that are searched
|
|
by both the auto-loader and the package loader.
|
|
If you want access to files described by a \fBpkgIndex.tcl\fR file
|
|
in a directory, that directory must be present in \fBauto_path\fR.
|
|
You can add the 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.
|
|
.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 vesion 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
|