1pkg_mkIndex(n)               Tcl Built-In Commands              pkg_mkIndex(n)


8       pkg_mkIndex - Build an index for automatic loading of packages


11       pkg_mkIndex ?options...? dir ?pattern pattern ...?


15       Pkg_mkIndex  is  a  utility  procedure that is part of the standard Tcl
16       library.  It is used to create index files that allow  packages  to  be
17       loaded  automatically  when  package require commands are executed.  To
18       use pkg_mkIndex, follow these steps:
20       [1]    Create the package(s).  Each package may consist of one or  more
21              Tcl script files or binary files.  Binary files must be suitable
22              for loading with the load command with a single  argument;   for
23              example, if the file is test.so it must be possible to load this
24              file with the command load test.so.  Each script file must  con‐
25              tain  a  package provide command to declare the package and ver‐
26              sion number, and  each  binary  file  must  contain  a  call  to
27              Tcl_PkgProvide.
29       [2]    Create  the  index  by  invoking  pkg_mkIndex.  The dir argument
30              gives the name of a directory and each  pattern  argument  is  a
31              glob-style  pattern  that selects script or binary files in dir.
32              The default pattern is *.tcl and *.[info sharedlibextension].
34              Pkg_mkIndex will create a file pkgIndex.tcl in dir with  package
35              information  about all the files given by the pattern arguments.
36              It does this by loading each file into a slave  interpreter  and
37              seeing  what packages and new commands appear (this is why it is
38              essential to have package  provide  commands  or  Tcl_PkgProvide
39              calls  in the files, as described above).  If you have a package
40              split among scripts and binary files, or if you  have  dependen‐
41              cies among files, you may have to use the -load option or adjust
42              the order in which pkg_mkIndex processes the files.  See COMPLEX
43              CASES below.
45       [3]    Install  the package as a subdirectory of one of the directories
46              given by the tcl_pkgPath  variable.   If  $tcl_pkgPath  contains
47              more than one directory, machine-dependent packages (e.g., those
48              that  contain  binary  shared  libraries)  should  normally   be
49              installed  under  the  first  directory  and machine-independent
50              packages (e.g., those that contain only Tcl scripts)  should  be
51              installed  under  the second directory.  The subdirectory should
52              include the package's script and/or binary files as well as  the
53              pkgIndex.tcl  file.   As  long  as the package is installed as a
54              subdirectory of a directory in $tcl_pkgPath  it  will  automati‐
55              cally be found during package require commands.
57              If  you  install the package anywhere else, then you must ensure
58              that the directory containing the package is  in  the  auto_path
59              global  variable  or  an  immediate  subdirectory  of one of the
60              directories in auto_path.  Auto_path contains a list of directo‐
61              ries  that  are searched by both the auto-loader and the package
62              loader; by default it includes $tcl_pkgPath.  The package loader
63              also  checks  all  of  the  subdirectories of the directories in
64              auto_path.  You can add a directory to auto_path  explicitly  in
65              your  application,  or you can add the directory to your TCLLIB‐
66              PATH environment variable:   if  this  environment  variable  is
67              present,  Tcl  initializes  auto_path from it during application
68              startup.
70       [4]    Once the above steps have been taken, all you need to do to  use
71              a  package  is  to invoke package require.  For example, if ver‐
72              sions 2.1, 2.3, and 3.1 of package Test  have  been  indexed  by
73              pkg_mkIndex,  the command package require Test will make version
74              3.1 available and the command package require  -exact  Test  2.1
75              will  make version 2.1 available.  There may be many versions of
76              a package in the various index files in auto_path, but only  one
77              will  actually  be  loaded  in a given interpreter, based on the
78              first call to package require.  Different versions of a  package
79              may be loaded in different interpreters.


82       The optional switches are:
84       -direct        The generated index will implement direct loading of the
85                      package upon package require.  This is the default.
87       -lazy          The generated index will manage  to  delay  loading  the
88                      package until the use of one of the commands provided by
89                      the package, instead  of  loading  it  immediately  upon
90                      package require.  This is not compatible with the use of
91                      auto_reset, and therefore its use is discouraged.
93       -load pkgPat   The index process will pre-load any packages that  exist
94                      in  the  current  interpreter  and match pkgPat into the
95                      slave interpreter used to generate the index.  The  pat‐
96                      tern  match  uses string match rules, but without making
97                      case distinctions.  See COMPLEX CASES below.
99       -verbose       Generate output during the indexing process.  Output  is
100                      via  the  tclLog  procedure,  which by default prints to
101                      stderr.
103       --             End of the flags, in case dir begins with a dash.


106       The package management  facilities  overlap  somewhat  with  the  auto-
107       loader,  in  that  both arrange for files to be loaded on-demand.  How‐
108       ever, package management is a  higher-level  mechanism  that  uses  the
109       auto-loader  for the last step in the loading process.  It is generally
110       better to index a package with  pkg_mkIndex  rather  than  auto_mkindex
111       because  the  package mechanism provides version control:  several ver‐
112       sions of a package can be made available in the index files, with  dif‐
113       ferent  applications  using different versions based on package require
114       commands.  In contrast, auto_mkindex does not understand versions so it
115       can only handle a single version of each package.  It is probably not a
116       good  idea  to  index  a  given  package  with  both  pkg_mkIndex   and
117       auto_mkindex.   If you use pkg_mkIndex to index a package, its commands
118       cannot be invoked until package require has been used to select a  ver‐
119       sion;   in  contrast,  packages  indexed  with auto_mkindex can be used
120       immediately since there is no version control.


123       Pkg_mkIndex  depends  on  the  package  unknown  command,  the  package
124       ifneeded  command,  and  the  auto-loader.   The  first  time a package
125       require command is invoked, the  package  unknown  script  is  invoked.
126       This is set by Tcl initialization to a script that evaluates all of the
127       pkgIndex.tcl files in the auto_path.  The  pkgIndex.tcl  files  contain
128       package  ifneeded  commands for each version of each available package;
129       these commands invoke package provide commands to announce  the  avail‐
130       ability  of the package, and they setup auto-loader information to load
131       the files of the package.  If the -lazy  flag  was  provided  when  the
132       pkgIndex.tcl  was generated, a given file of a given version of a given
133       package is not actually loaded until the first time one of its commands
134       is  invoked.   Thus, after invoking package require you may not see the
135       package's commands in the interpreter, but you will be able  to  invoke
136       the commands and they will be auto-loaded.


139       Some  packages,  for  instance packages which use namespaces and export
140       commands or those which require special  initialization,  might  select
141       that  their  package  files  be loaded immediately upon package require
142       instead of delaying the actual loading to the first use of one  of  the
143       package's command. This is the default mode when generating the package
144       index.  It can be overridden by specifying the -lazy argument.


147       Most complex cases of dependencies among scripts and binary files,  and
148       packages  being  split  among  scripts and binary files are handled OK.
149       However, you may have to adjust the order in which files are  processed
150       by pkg_mkIndex.  These issues are described in detail below.
152       If each script or file contains one package, and packages are only con‐
153       tained in one file, then things are easy.  You simply specify all files
154       to be indexed in any order with some glob patterns.
156       In  general,  it  is OK for scripts to have dependencies on other pack‐
157       ages.  If scripts contain package require commands, these  are  stubbed
158       out  in  the  interpreter  used to process the scripts, so these do not
159       cause problems.  If scripts call into other packages  in  global  code,
160       these calls are handled by a stub unknown command.  However, if scripts
161       make variable references to other package's variables in  global  code,
162       these will cause errors.  That is also bad coding style.
164       If  binary files have dependencies on other packages, things can become
165       tricky because it is not possible to stub  out  C-level  APIs  such  as
166       Tcl_PkgRequire  API  when  loading a binary file.  For example, suppose
167       the BLT package  requires  Tk,  and  expresses  this  with  a  call  to
168       Tcl_PkgRequire  in its Blt_Init routine.  To support this, you must run
169       pkg_mkIndex in an interpreter that has Tk loaded.  You can achieve this
170       with  the -load pkgPat option.  If you specify this option, pkg_mkIndex
171       will load any packages listed by info loaded and that match pkgPat into
172       the interpreter used to process files.  In most cases this will satisfy
173       the Tcl_PkgRequire calls made by binary files.
175       If you are indexing two binary files and one depends on the other,  you
176       should  specify  the  one that has dependencies last.  This way the one
177       without dependencies will get loaded and indexed, and then the  package
178       it  provides  will be available when the second file is processed.  You
179       may also need to load the first package into the temporary  interpreter
180       used  to  create the index by using the -load flag; it will not hurt to
181       specify package patterns that are not yet loaded.
183       If you have a package that is split across scripts and a  binary  file,
184       then you should avoid the -load flag. The problem is that if you load a
185       package before computing the index it masks any other files  that  pro‐
186       vide  part  of  the same package.  If you must use -load, then you must
187       specify the scripts first; otherwise the package loaded from the binary
188       file may mask the package defined by the scripts.


191       package(n)


194       auto-load, index, package, version
198Tcl                                   8.3                       pkg_mkIndex(n)