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