pkg_mkIndex(n)
_________________________________________________________________
NAME
pkg_mkIndex - Build an index for automatic loading of
packages
SYNOPSIS
pkg_mkIndex dir pattern ?pattern pattern ...?
_________________________________________________________________
DESCRIPTION
Pkg_mkIndex 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 pack-
age 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 pat-
tern 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 pro-
vide 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 con- |
tain 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 |
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 pack- |
age is in the auto_path global variable or an imme- |
diate subdirectory of one of the directories in |
auto_path. Auto_path contains a list of directo- |
ries 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
explicitly in your application, or you can add the
directory to your TCLLIBPATH environment variable:
if this environment variable is present, Tcl ini-
tializes 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 version 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 interpreter,
based on the first call to package require. Dif-
ferent 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 package mechanism provides ver-
sion control: several versions of a package can be made
available in the index files, with different applications
using different versions based on package require com-
mands. In contrast, auto_mkindex does not understand ver-
sions so it can only handle a single version of each pack-
age. 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 avail-
able package; these commands invoke package provide com-
mands 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 package
require you won't see the package's commands in the inter-
preter, but you will be able to invoke the commands and
they will be auto-loaded.
KEYWORDS
auto-load, index, package, version