246 lines
12 KiB
HTML
246 lines
12 KiB
HTML
<HTML><HEAD><TITLE>Tcl Built-In Commands - pkg_mkIndex manual page</TITLE></HEAD><BODY>
|
|
<DL>
|
|
<DD><A HREF="pkgMkIndex.htm#M2" NAME="L821">NAME</A>
|
|
<DL><DD>pkg_mkIndex - Build an index for automatic loading of packages</DL>
|
|
<DD><A HREF="pkgMkIndex.htm#M3" NAME="L822">SYNOPSIS</A>
|
|
<DL>
|
|
<DD><B>pkg_mkIndex ?</B><I>-direct</I>? ?<I>-lazy</I>? ?<I>-load pkgPat</I>? ?<I>-verbose</I>? <I>dir</I> ?<I>pattern pattern ...</I>?
|
|
</DL>
|
|
<DD><A HREF="pkgMkIndex.htm#M4" NAME="L823">DESCRIPTION</A>
|
|
<DL>
|
|
</DL>
|
|
<DD><A HREF="pkgMkIndex.htm#M5" NAME="L824">OPTIONS</A>
|
|
<DL>
|
|
<DD><A HREF="pkgMkIndex.htm#M6" NAME="L825"><B>-direct</B></A>
|
|
<DD><A HREF="pkgMkIndex.htm#M7" NAME="L826"><B>-lazy</B></A>
|
|
<DD><A HREF="pkgMkIndex.htm#M8" NAME="L827"><B>-load </B><I>pkgPat</I></A>
|
|
<DD><A HREF="pkgMkIndex.htm#M9" NAME="L828"><B>-verbose</B></A>
|
|
<DD><A HREF="pkgMkIndex.htm#M10" NAME="L829"><B>--</B></A>
|
|
</DL>
|
|
<DD><A HREF="pkgMkIndex.htm#M11" NAME="L830">PACKAGES AND THE AUTO-LOADER</A>
|
|
<DD><A HREF="pkgMkIndex.htm#M12" NAME="L831">HOW IT WORKS</A>
|
|
<DD><A HREF="pkgMkIndex.htm#M13" NAME="L832">DIRECT LOADING</A>
|
|
<DD><A HREF="pkgMkIndex.htm#M14" NAME="L833">COMPLEX CASES</A>
|
|
<DD><A HREF="pkgMkIndex.htm#M15" NAME="L834">SEE ALSO</A>
|
|
<DD><A HREF="pkgMkIndex.htm#M16" NAME="L835">KEYWORDS</A>
|
|
</DL><HR>
|
|
<H3><A NAME="M2">NAME</A></H3>
|
|
pkg_mkIndex - Build an index for automatic loading of packages
|
|
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
|
<B>pkg_mkIndex ?</B><I>-direct</I>? ?<I>-lazy</I>? ?<I>-load pkgPat</I>? ?<I>-verbose</I>? <I>dir</I> ?<I>pattern pattern ...</I>?<BR>
|
|
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
|
<B>Pkg_mkIndex</B> 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 <B>package require</B> commands are executed.
|
|
To use <B>pkg_mkIndex</B>, follow these steps:
|
|
<P>
|
|
<DL>
|
|
<P><DT>[1]<DD>
|
|
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 <B><A HREF="../TkCmd/load.htm">load</A></B> command
|
|
with a single argument; for example, if the file is <B>test.so</B> it must
|
|
be possible to load this file with the command <B>load test.so</B>.
|
|
Each script file must contain a <B>package provide</B> command to declare
|
|
the package and version number, and each binary file must contain
|
|
a call to <B><A HREF="../TkLib/PkgRequire.htm">Tcl_PkgProvide</A></B>.
|
|
<P><DT>[2]<DD>
|
|
Create the index by invoking <B>pkg_mkIndex</B>.
|
|
The <I>dir</I> argument gives the name of a directory and each
|
|
<I>pattern</I> argument is a <B><A HREF="../TkCmd/glob.htm">glob</A></B>-style pattern that selects
|
|
script or binary files in <I>dir</I>.
|
|
The default pattern is <B>*.tcl</B> and <B>*.[info sharedlibextension]</B>.
|
|
<BR>
|
|
<B>Pkg_mkIndex</B> will create a file <B>pkgIndex.tcl</B> in <I>dir</I>
|
|
with package information about all the files given by the <I>pattern</I>
|
|
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
|
|
<B>package provide</B> commands or <B><A HREF="../TkLib/PkgRequire.htm">Tcl_PkgProvide</A></B> calls
|
|
in the files, as described above).
|
|
If you have a package split among scripts and binary files,
|
|
or if you have dependencies among files,
|
|
you may have to use the <B>-load</B> option
|
|
or adjust the order in which <B>pkg_mkIndex</B> processes
|
|
the files. See COMPLEX CASES below.
|
|
|
|
<P><DT>[3]<DD>
|
|
Install the package as a subdirectory of one of the directories given by
|
|
the <B>tcl_pkgPath</B> variable. If <B>$tcl_pkgPath</B> 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 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 <B>pkgIndex.tcl</B>
|
|
file. As long as the package is installed as a subdirectory of a
|
|
directory in <B>$tcl_pkgPath</B> it will automatically be found during
|
|
<B>package require</B> commands.
|
|
<BR>
|
|
If you install the package anywhere else, then you must ensure that
|
|
the directory containing the package is in the <B>auto_path</B> global variable
|
|
or an immediate subdirectory of one of the directories in <B>auto_path</B>.
|
|
<B>Auto_path</B> contains a list of directories that are searched
|
|
by both the auto-loader and the package loader; by default it
|
|
includes <B>$tcl_pkgPath</B>.
|
|
The package loader also checks all of the subdirectories of the
|
|
directories in <B>auto_path</B>.
|
|
You can add a directory to <B>auto_path</B> explicitly in your
|
|
application, or you can add the directory to your <B>TCLLIBPATH</B>
|
|
environment variable: if this environment variable is present,
|
|
Tcl initializes <B>auto_path</B> from it during application startup.
|
|
<P><DT>[4]<DD>
|
|
Once the above steps have been taken, all you need to do to use a
|
|
package is to invoke <B>package require</B>.
|
|
For example, if versions 2.1, 2.3, and 3.1 of package <B>Test</B>
|
|
have been indexed by <B>pkg_mkIndex</B>, the command
|
|
<B>package require Test</B> will make version 3.1 available
|
|
and the command <B>package require -exact Test 2.1</B> will
|
|
make version 2.1 available.
|
|
There may be many versions of a package in the various index files
|
|
in <B>auto_path</B>, but only one will actually be loaded in a given
|
|
interpreter, based on the first call to <B>package require</B>.
|
|
Different versions of a package may be loaded in different
|
|
interpreters.
|
|
|
|
<P></DL>
|
|
<H3><A NAME="M5">OPTIONS</A></H3>
|
|
The optional switches are:
|
|
<P>
|
|
<DL>
|
|
<P><DT><A NAME="M6"><B>-direct</B></A><DD>
|
|
The generated index will implement direct loading of the package
|
|
upon <B>package require</B>. This is the default.
|
|
<P><DT><A NAME="M7"><B>-lazy</B></A><DD>
|
|
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 <B>package require</B>.
|
|
<P><DT><A NAME="M8"><B>-load </B><I>pkgPat</I></A><DD>
|
|
The index process will pre-load any packages that exist in the
|
|
current interpreter and match <I>pkgPat</I> into the slave interpreter used to
|
|
generate the index. The pattern match uses string match rules.
|
|
See COMPLEX CASES below.
|
|
<P><DT><A NAME="M9"><B>-verbose</B></A><DD>
|
|
Generate output during the indexing process. Output is via
|
|
the <B>tclLog</B> procedure, which by default prints to stderr.
|
|
<P><DT><A NAME="M10"><B>--</B></A><DD>
|
|
End of the flags, in case <I>dir</I> begins with a dash.
|
|
|
|
<P></DL>
|
|
<H3><A NAME="M11">PACKAGES AND THE AUTO-LOADER</A></H3>
|
|
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 <B>pkg_mkIndex</B>
|
|
rather than <B><A HREF="../TkCmd/library.htm">auto_mkindex</A></B> 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 <B>package require</B> commands.
|
|
In contrast, <B><A HREF="../TkCmd/library.htm">auto_mkindex</A></B> 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
|
|
<B>pkg_mkIndex</B> and <B><A HREF="../TkCmd/library.htm">auto_mkindex</A></B>.
|
|
If you use <B>pkg_mkIndex</B> to index a package, its commands cannot
|
|
be invoked until <B>package require</B> has been used to select a
|
|
version; in contrast, packages indexed with <B><A HREF="../TkCmd/library.htm">auto_mkindex</A></B>
|
|
can be used immediately since there is no version control.
|
|
|
|
<H3><A NAME="M12">HOW IT WORKS</A></H3>
|
|
<B>Pkg_mkIndex</B> depends on the <B>package unknown</B> command,
|
|
the <B>package ifneeded</B> command, and the auto-loader.
|
|
The first time a <B>package require</B> command is invoked,
|
|
the <B>package unknown</B> script is invoked.
|
|
This is set by Tcl initialization to a script that
|
|
evaluates all of the <B>pkgIndex.tcl</B> files in the
|
|
<B>auto_path</B>.
|
|
The <B>pkgIndex.tcl</B> files contain <B>package ifneeded</B>
|
|
commands for each version of each available package; these commands
|
|
invoke <B>package provide</B> commands to announce the
|
|
availability of the package, and they setup auto-loader
|
|
information to load the files of the package.
|
|
If the <I>-lazy</I> flag was provided when the <B>pkgIndex.tcl</B>
|
|
was generated,
|
|
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 <B>package require</B> 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.
|
|
|
|
<H3><A NAME="M13">DIRECT LOADING</A></H3>
|
|
Some packages, for instance packages which use namespaces and export
|
|
commands or those which require special initialization, might select
|
|
that their package files be loaded immediately upon <B>package require</B>
|
|
instead of delaying the actual loading to the first use of one of the
|
|
package's command. This is the default mode when generating the package
|
|
index. It can be overridden by specifying the <I>-lazy</I> argument.
|
|
|
|
<H3><A NAME="M14">COMPLEX CASES</A></H3>
|
|
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 <B>pkg_mkIndex</B>.
|
|
These issues are described in detail below.
|
|
<P>
|
|
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.
|
|
<P>
|
|
In general, it is OK for scripts to have dependencies on other
|
|
packages.
|
|
If scripts contain <B>package require</B> commands, these are
|
|
stubbed out in the interpreter used to process the scripts,
|
|
so these do not cause problems.
|
|
If scripts call into other packages in global code,
|
|
these calls are handled by a stub <B><A HREF="../TkCmd/unknown.htm">unknown</A></B> command.
|
|
However, if scripts make variable references to other package's
|
|
variables in global code, these will cause errors. That is
|
|
also bad coding style.
|
|
<P>
|
|
If binary files have dependencies on other packages, things
|
|
can become tricky because it is not possible to stub out
|
|
C-level API's such as <B><A HREF="../TkLib/PkgRequire.htm">Tcl_PkgRequire</A></B> API
|
|
when loading a binary file.
|
|
For example, suppose the BLT package requires Tk, and expresses
|
|
this with a call to <B><A HREF="../TkLib/PkgRequire.htm">Tcl_PkgRequire</A></B> in its <B>Blt_Init</B> routine.
|
|
To support this, you must run <B>pkg_mkIndex</B> in an interpreter that
|
|
has Tk loaded. You can achieve this with the
|
|
<B>-load </B><I>pkgPat</I> option. If you specify this option,
|
|
<B>pkg_mkIndex</B> will load any packages listed by
|
|
<B><A HREF="../TkCmd/info.htm">info loaded</A></B> and that match <I>pkgPat</I>
|
|
into the interpreter used to process files.
|
|
In most cases this will satisfy the <B><A HREF="../TkLib/PkgRequire.htm">Tcl_PkgRequire</A></B> calls
|
|
made by binary files.
|
|
<P>
|
|
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 available when the second file is processed.
|
|
You may also need to load the first package into the
|
|
temporary interpreter used to create the index by using
|
|
the <B>-load</B> flag;
|
|
it won't hurt to specify package patterns that are not yet loaded.
|
|
<P>
|
|
If you have a package that is split across scripts and a binary file,
|
|
then you should avoid the <B>-load</B> flag. The problem is that
|
|
if you load a package before computing the index it masks any
|
|
other files that provide part of the same package.
|
|
If you must use <B>-load</B>,
|
|
then you must specify the scripts first; otherwise the package loaded from
|
|
the binary file may mask the package defined by the scripts.
|
|
|
|
<H3><A NAME="M15">SEE ALSO</A></H3>
|
|
<B><A HREF="../TkCmd/package.htm">package</A></B>
|
|
<H3><A NAME="M16">KEYWORDS</A></H3>
|
|
<A href="../Keywords/A.htm#auto-load">auto-load</A>, <A href="../Keywords/I.htm#index">index</A>, <A href="../Keywords/P.htm#package">package</A>, <A href="../Keywords/V.htm#version">version</A>
|
|
<HR><PRE>
|
|
<A HREF="../copyright.htm">Copyright</A> © 1996 Sun Microsystems, Inc.
|
|
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
|
</BODY></HTML>
|