Tcl Built-In Commands pkgmkIndex(1T)
NAME
pkgmkIndex - Build an index for automatic loading of pack-
ages
SYNOPSIS
pkgmkIndex ?-direct? ?-lazy? ?-load pkgPat? ?-verbose? dir ?pattern pattern ...?
DESCRIPTION
PkgmkIndex is a utility procedure that is part of the stan-
dard Tcl library. It is used to create index files that
allow packages to be loaded automatically when package
require commands are executed. To use pkgmkIndex, follow
these steps:
[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 load command with
a single argument; for example, if the file is test.so
it must be possible to load this file with the command
load test.so. Each script file must contain a package
provide command to declare the package and version
number, and each binary file must contain a call to
TclPkgProvide.
[2] Create the index by invoking pkgmkIndex. The dir
argument gives the name of a directory and each pattern
argument is a glob-style pattern that selects script or
binary files in dir. The default pattern is *.tcl and
*.[info sharedlibextension].
PkgmkIndex will create a file pkgIndex.tcl in dir with
package information about all the files given by the
pattern arguments. It does this by loading each file
into a slave interpreter and seeing what packages and
new commands appear (this is why it is essential to
have package provide commands or TclPkgProvide calls
in the files, as described above). If you have a pack-
age split among scripts and binary files, or if you
have dependencies among files, you may have to use the
-load option or adjust the order in which pkgmkIndex
processes the files. See COMPLEX CASES below.
[3] Install the package as a subdirectory of one of the
directories given by the tclpkgPath variable. If
$tclpkgPath 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
Tcl Last change: 8.3 1
Tcl Built-In Commands pkgmkIndex(1T)
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 pkgIndex.tcl file. As long
as the package is installed as a subdirectory of a
directory in $tclpkgPath it will automatically be
found during package require commands.
If you install the package anywhere else, then you must
ensure that the directory containing the package is in
the autopath global variable or an immediate subdirec-
tory of one of the directories in autopath. Autopath
contains a list of directories that are searched by
both the auto-loader and the package loader; by default
it includes $tclpkgPath. The package loader also
checks all of the subdirectories of the directories in
autopath. You can add a directory to autopath expli-
citly in your application, or you can add the directory
to your TCLIBPATH environment variable: if this
environment variable is present, Tcl initializes
autopath from it during application startup.
[4] Once the above steps have been taken, all you need to
do to use a package is to invoke package require. For
example, if versions 2.1, 2.3, and 3.1 of package Test
have been indexed by pkgmkIndex, the command package
require Test will make version 3.1 available and the
command package require -exact Test 2.1 will make ver-
sion 2.1 available. There may be many versions of a
package in the various index files in autopath, but
only one will actually be loaded in a given inter-
preter, based on the first call to package require.
Different versions of a package may be loaded in dif-
ferent interpreters.
OPTIONS
The optional switches are:
-direct The generated index will implement direct
loading of the package upon package require.
This is the default.
-lazy The generated index will manage to delay
loading the package until the use of one of
the commands provided by the package, instead
of loading it immediately upon package
require.
-load pkgPat The index process will pre-load any packages
that exist in the current interpreter and
match pkgPat into the slave interpreter used
to generate the index. The pattern match
Tcl Last change: 8.3 2
Tcl Built-In Commands pkgmkIndex(1T)
uses string match rules, but without making
case distinctions. See COMPLEX CASES below.
-verbose Generate output during the indexing process.
Output is via the tclLog procedure, which by
default prints to stderr.
-- End of the flags, in case dir begins with a
dash.
PACKAGES AND THE AUTO-LOADER
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 pkgmkIndex rather than automkindex because the pack-
age 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
package require commands. In contrast, automkindex does
not understand versions so it can only handle a single ver-
sion of each package. It is probably not a good idea to
index a given package with both pkgmkIndex and
automkindex. If you use pkgmkIndex to index a package,
its commands cannot be invoked until package require has
been used to select a version; in contrast, packages
indexed with automkindex can be used immediately since
there is no version control.
HOW IT WORKS
PkgmkIndex depends on the package unknown command, the
package ifneeded command, and the auto-loader. The first
time a package require command is invoked, the package
unknown script is invoked. This is set by Tcl initializa-
tion to a script that evaluates all of the pkgIndex.tcl
files in the autopath. The pkgIndex.tcl files contain
package ifneeded commands for each version of each available
package; these commands invoke package provide commands to
announce the availability of the package, and they setup
auto-loader information to load the files of the package.
If the -lazy flag was provided when the pkgIndex.tcl was
generated, a given file of a given version of a given pack-
age isn't actually loaded until the first time one of its
commands is invoked. Thus, after invoking package require
you may not see the package's commands in the interpreter,
but you will be able to invoke the commands and they will be
auto-loaded.
Tcl Last change: 8.3 3
Tcl Built-In Commands pkgmkIndex(1T)
DIRECT LOADING
Some packages, for instance packages which use namespaces
and export commands or those which require special initiali-
zation, might select that their package files be loaded
immediately upon package require instead of delaying the
actual loading to the first use of one of the package's com-
mand. This is the default mode when generating the package
index. It can be overridden by specifying the -lazy argu-
ment.
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 pkgmkIndex. These
issues are described in detail below.
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.
In general, it is OK for scripts to have dependencies on
other packages. If scripts contain package require com-
mands, these are stubbed out in the interpreter used to pro-
cess the scripts, so these do not cause problems. If
scripts call into other packages in global code, these calls
are handled by a stub unknown command. However, if scripts
make variable references to other package's variables in
global code, these will cause errors. That is also bad cod-
ing style.
If binary files have dependencies on other packages, things
can become tricky because it is not possible to stub out C-
level APIs such as TclPkgRequire API when loading a binary
file. For example, suppose the BLT package requires Tk, and
expresses this with a call to TclPkgRequire in its BltInit
routine. To support this, you must run pkgmkIndex in an
interpreter that has Tk loaded. You can achieve this with
the -load pkgPat option. If you specify this option,
pkgmkIndex will load any packages listed by info loaded and
that match pkgPat into the interpreter used to process
files. In most cases this will satisfy the TclPkgRequire
calls made by binary files.
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 avail-
able when the second file is processed. You may also need
to load the first package into the temporary interpreter
Tcl Last change: 8.3 4
Tcl Built-In Commands pkgmkIndex(1T)
used to create the index by using the -load flag; it won't
hurt to specify package patterns that are not yet loaded.
If you have a package that is split across scripts and a
binary file, then you should avoid the -load flag. The prob-
lem is that if you load a package before computing the index
it masks any other files that provide part of the same pack-
age. If you must use -load, then you must specify the
scripts first; otherwise the package loaded from the binary
file may mask the package defined by the scripts.
SEE ALSO
package(1T)
KEYWORDS
auto-load, index, package, version
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Availability SUNWTcl
Interface Stability Uncommitted
NOTES
Source for Tcl is available on http:/opensolaris.org.
Tcl Last change: 8.3 5
|
