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


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
