1pkg_mkIndex(n) Tcl Built-In Commands pkg_mkIndex(n)
2______________________________________________________________________________
6
8 pkg_mkIndex - Build an index for automatic loading of packages
9
11 pkg_mkIndex ?options...? dir ?pattern pattern ...?
12______________________________________________________________________________
13
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:
19 [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.
28 [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].
33 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.
44 [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.
56 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.
69 [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.
80
82 The optional switches are:
83 -direct The generated index will implement direct loading of the
85 package upon package require. This is the default.
86 -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.
92 -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.
98 -verbose Generate output during the indexing process. Output is
100 via the tclLog procedure, which by default prints to
101 stderr.
102 -- End of the flags, in case dir begins with a dash.
104
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.
121
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.
137
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.
145
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.
151 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.
155 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.
163 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.
174 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.
182 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.
189
191 package(n)
192
194 auto-load, index, package, version
195Tcl 8.3 pkg_mkIndex(n)