tcl7.6 User Commands - pkgMkIndex
NAME
pkg_mkIndex - Build an index for automatic loading of pack-
ages
SYNOPSIS
pkg_mkIndex dir pattern ?pattern pattern ...?
DESCRIPTION
Pkg_mkIndex 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 pkg_mkIndex, 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
Tcl_PkgProvide.
[2] Create the index by invoking pkg_mkIndex. 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. Pkg_mkIndex 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 and seeing what packages and new
commands appear (this is why it is essential to have
package provide commands or Tcl_PkgProvide calls in the
files, as described above).
[3] |
| |
Install the package as a subdirectory of one of the |
directories given by the tcl_pkgPath variable. If |
$tcl_pkgPath 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 pack- |
ages (e.g., those that contain only Tcl scripts) should |
be installed under the second directory. The subdirec- |
tory 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 $tcl_pkgPath it will automatically be found during |
package require commands. |
If you install the package anywhere else, then you must |
ensure that the directory contaiingn the package is in |
the auto_path global variable or an immediate subdirec- |
tory of one of the directories in auto_path. Auto_path |
contains a list of directories that are searched by |
both the auto-loader and the package loader; by default |
it includes $tcl_pkgPath. The package loader also |
checks all of the subdirectories of the directories in |
auto_path. You can add a directory to auto_path expli-
citly in your application, or you can add the directory
to your TCLLIBPATH environment variable: if this
environment variable is present, Tcl initializes
auto_path 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 pkg_mkIndex, 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 auto_path, 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.
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 pkg_mkIndex rather than auto_mkindex 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, auto_mkindex 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 pkg_mkIndex and
auto_mkindex. If you use pkg_mkIndex to index a package,
its commands cannot be invoked until package require has
been used to select a version; in contrast, packages
indexed with auto_mkindex can be used immediately since
there is no version control.
HOW IT WORKS
Pkg_mkIndex 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 auto_path. 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. A
given file of a given version of a given package isn't actu-
ally loaded until the first time one of its commands is
invoked. Thus, after invoking package require 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.
KEYWORDS
auto-load, index, package, version