pkg_mkIndex - Build an index for automatic loading of packages
pkg_mkIndex dir pattern ?pattern pattern ...?
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 package require commands are executed.
To use pkg_mkIndex, follow these steps:
-
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.
-
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).
-
Make sure that the directory is in the auto_path global variable.
Auto_path 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 pkgIndex.tcl file
in a directory, that directory must be present in auto_path.
You can add the 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 initializes auto_path from it during application startup.
-
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 vesion 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.
Different versions of a package may be loaded in different
interpreters.
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
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 version 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.
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 initialization 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
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 interpreter, but you will be able
to invoke the commands and they will be auto-loaded.
auto-load, index, package, version
Copyright © 1996 Sun Microsystems, Inc.
Copyright © 1995, 1996 Roger E. Critchlow Jr.