tcl7.6 User Commands - pkgMkIndex






NAME

     pkg_mkIndex - Build an index for automatic loading of  pack-
     ages


SYNOPSIS

     pkg_mkIndex dir pattern ?pattern pattern ...?





DESCRIPTION

     Pkg_mkIndex is a utility procedure that is part of the stan-
     dard  Tcl  library.   It  is used to create index files that
     allow packages  to  be  loaded  automatically  when  package
     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 pattern 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 provide 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 contain  |
          binary shared libraries) should normally  be  installed  |
          under the first directory and machine-independent pack-  |
          ages (e.g., those that contain only Tcl scripts) should  |
          be installed under the second directory.  The subdirec-  |
          tory 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 subdirec-  |
          tory of one of the directories in auto_path.  Auto_path  |
          contains a list of directories  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 expli-
          citly in your application, or you can add the directory
          to  your  TCLLIBPATH  environment  variable:   if  this
          environment   variable   is  present,  Tcl  initializes
          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 ver-
          sion 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  inter-
          preter,  based  on  the  first call to package require.
          Different 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 pack-
     age 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
     package  require  commands.   In contrast, auto_mkindex does
     not understand versions so it can only handle a single  ver-
     sion  of  each  package.  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 available
     package;   these commands invoke package provide commands 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 actu-
     ally  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 interpreter, but you will be
     able to invoke the commands and they will be auto-loaded.



KEYWORDS

     auto-load, index, package, version