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
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
with package information about all the files given by the pattern
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).
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 (for example, those that
contain binary shared libraries) should normally be installed
under the first directory and machine-independent packages (for example,
those that contain only Tcl scripts) should be installed under the
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 containing
the package is in the auto_path global variable
or an immediate subdirectory 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
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 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 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.
Different versions of a package may be loaded in different
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
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 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 initialization to a script that
evaluates all of the pkgIndex.tcl files in the
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 is not
actually loaded until the first time one of its commands
Thus, after invoking package require you will not see
the package's commands in the interpreter, but you will be able
to invoke the commands and they will be auto-loaded.
25 April 2004
© 2004 The SCO Group, Inc. All rights reserved.
UnixWare 7 Release 7.1.4 - 25 April 2004