NAME
       pkg_mkIndex  -  Build  an  index  for automatic loading of
       packages

SYNOPSIS
       pkg_mkIndex ?-direct? ?-load pkgPat? ?-verbose? dir ?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.  The default
              pattern is *.tcl and *.[info sharedlibextension].

              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 into a slave interpreter 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).  If you have a package split among  scripts
              and binary files, or if you have dependencies among
              files, you may have to  use  the  -load  option  or
              adjust the order in which pkg_mkIndex processes the
              files.  See COMPLEX CASES below.


       [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  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 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.


OPTIONS
       The optional switches are:

       -direct        The generated index will manage to load the
                      package immediately  upon  package  require
                      instead  of  delaying  loading until actual
                      use of one of the commands.

       -load pkgPat   The index process will pre-load  any  pack-
                      ages  that exist in the current interpreter
                      and match pkgPat into the slave interpreter
                      used  to  generate  the index.  The pattern
                      match uses string match rules.  See COMPLEX
                      CASES below.

       -verbose       Generate  output  during  the indexing pro-
                      cess.  Output is via the tclLog  procedure,
                      which by default prints to stderr.

       --             End of the flags, in case dir begins with a
                      dash.


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 about  package  from  this
              interpreter, including information provided by both
              package ifneeded and package provide.

       package ifneeded package version ?script?
              This command typically appears only in system  con-
              figuration  scripts to set up the package database.
              It indicates that a particular version of a partic-
              ular  package  is available if needed, and that the
              package can be added to the interpreter by  execut-
              ing  script.  The script is saved in a database for
              use by subsequent package require commands;   typi-
              cally, script sets up auto-loading for the commands
              in  the  package  (or  calls  load  and/or   source
              directly), then invokes package provide to indicate
              that the package is present.  There may be informa-
              tion in the database for several different versions
              of a single package.  If the database already  con-
              tains  information for package and version, the new
              script replaces the existing one.   If  the  script
              argument is omitted, the current script for version
              version of package package is returned, or an empty
              string  if  no  package  ifneeded  command has been
              invoked for this package and version.

       package names
              Returns a list of the names of all packages in  the
              interpreter  for  which a version has been provided
              (via  package  provide)  or  for  which  a  package
              ifneeded  script  is  available.  The order of ele-
              ments in the list is arbitrary.

       package present ?-exact? package ?version?
              This  command  is  equivalent  to  package  require
              except that it does not try and load the package if
              it is not already loaded.

       package provide package ?version?
              This command is invoked to  indicate  that  version
              version  of  package  package is now present in the
              interpreter.  It is typically invoked once as  part
              of  an  ifneeded  script,  and again by the package
              itself when it is finally loaded.  An error  occurs
              if a different version of package has been provided
              by a previous package provide command.  If the ver-
              sion  argument is omitted, then the command returns
              the version number that is currently  provided,  or
              an  empty  string if no package provide command has
              been invoked for package in this interpreter.

       package require ?-exact? package ?version?
              This command is typically invoked by Tcl code  that
              wishes  to use a particular version of a particular
              package.  The arguments indicate which  package  is
              wanted,  and  the  command  ensures that a suitable
              version of the package is loaded  into  the  inter-
              preter.   If  the  command succeeds, it returns the
              version number that is loaded;  otherwise it gener-
              ates  an  error.  If both the -exact switch and the
              version argument are specified then only the  given
              version  is  acceptable.   If -exact is omitted but
              version is specified, then versions later than ver-
              sion  are  also acceptable as long as they have the
              same major version  number  as  version.   If  both
              -exact  and  version  are  omitted then any version
              whatsoever is acceptable.  If a version of  package
              has  already been provided (by invoking the package
              provide command), then its version number must sat-
              isfy  the  criteria given by -exact and version and
              the command returns  immediately.   Otherwise,  the
              command  searches  the database of information pro-
              vided by previous package ifneeded commands to  see
              if  an  acceptable version of the package is avail-
              able.  If so, the script for the highest acceptable
              version  number  is invoked; it must do whatever is
              necessary to load the  package,  including  calling
              package  provide  for  the package.  If the package
              ifneeded database does not  contain  an  acceptable
              version  of  the package and a