NAME
       pkg_mkIndex  -  Build  an  index  for automatic loading of
       packages

SYNOPSIS
       pkg_mkIndex ?-direct?  ?-lazy?  ?-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 pack-
              age is in the auto_path global variable or an imme-
              diate 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 implement direct
                      loading  of  the   package   upon   package
                      require.  This is the default.

       -lazy          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
                      package require.

       -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, but without
                      making  case  distinctions.   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 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.  If the -lazy  flag  was  provided  when  the
       pkgIndex.tcl  was  generated, a given file of a given ver-
       sion of a given package isn't actually  loaded  until  the
       first  time  one  of its commands is invoked.  Thus, after
       invoking package require 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.


DIRECT LOADING
       Some packages, for instance packages which use  namespaces
       and  export  commands  or those which require special ini-
       tialization, might select  that  their  package  files  be
       loaded  immediately upon package require instead of delay-
       ing the actual loading to the first  use  of  one  of  the
       package's  command. This is the default mode when generat-
       ing the package index.  It can be overridden by specifying
       the -lazy argument.


COMPLEX CASES
       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
       pkg_mkIndex.   These issues are described in detail below.

       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.

       In  general,  it is OK for scripts to have dependencies on
       other packages.  If scripts contain package  require  com-
       mands,  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 unknown command.  However,  if
       scripts  make variable references to other package's vari-
       ables in global code, these will cause  errors.   That  is
       also bad coding style.

       If  binary  files  have  dependencies  on  other packages,
       things can become tricky because it  is  not  possible  to
       stub  out  C-level  APIs  such  as Tcl_PkgRequire API when
       loading a binary file.  For example, suppose the BLT pack-
       age  requires  Tk,  and  expresses  this  with  a  call to
       Tcl_PkgRequire in its Blt_Init routine.  To support  this,
       you  must  run  pkg_mkIndex  in an interpreter that has Tk
       loaded.  You  can  achieve  this  with  the  -load  pkgPat
       option.  If you specify this option, pkg_mkIndex will load
       any packages listed by info loaded and that  match  pkgPat
       into the interpreter used to process files.  In most cases
       this will satisfy the Tcl_PkgRequire calls made by  binary
       files.

       If  you  are  indexing two binary files and one depends on
       the other, you should specify the one that  has  dependen-
       cies 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 -load
       flag; it won't hurt to specify package patterns  that  are
       not yet loaded.

       If  you  have a package that is split across scripts and a
       binary file, then you should avoid  the  -load  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 -load, then you must spec-
       ify the scripts first; otherwise the package  loaded  from
       the  binary  file  may  mask  the  package  defined by the
       scripts.


SEE ALSO
       package(n)


KEYWORDS
