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 ?-direct? ?-lazy? ?-load pkgPat? ?-verbose? dir ?pattern pattern ...?│
12_________________________________________________________________
13
16 Pkg_mkIndex is a utility procedure that is part of the standard Tcl
17 library. It is used to create index files that allow packages to be
18 loaded automatically when package require commands are executed. To
19 use pkg_mkIndex, follow these steps:
20 [1] Create the package(s). Each package may consist of one or more
22 Tcl script files or binary files. Binary files must be suitable
23 for loading with the load command with a single argument; for
24 example, if the file is test.so it must be possible to load this
25 file with the command load test.so. Each script file must con‐
26 tain a package provide command to declare the package and ver‐
27 sion number, and each binary file must contain a call to
28 Tcl_PkgProvide.
29 [2] Create the index by invoking pkg_mkIndex. The dir argument
31 gives the name of a directory and each pattern argument is a
32 glob-style pattern that selects script or binary files in dir. │
33 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.
44 [3] Install the package as a subdirectory of one of the directories
47 given by the tcl_pkgPath variable. If $tcl_pkgPath contains
48 more than one directory, machine-dependent packages (e.g., those
49 that contain binary shared libraries) should normally be
50 installed under the first directory and machine-independent
51 packages (e.g., those that contain only Tcl scripts) should be
52 installed under the second directory. The subdirectory should
53 include the package's script and/or binary files as well as the
54 pkgIndex.tcl file. As long as the package is installed as a
55 subdirectory of a directory in $tcl_pkgPath it will automati‐
56 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.
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
83 The optional switches are:
84 -direct The generated index will implement direct loading of the
86 package upon package require. This is the default.
87 -lazy The generated index will manage to delay loading the
89 package until the use of one of the commands provided by
90 the package, instead of loading it immediately upon
91 package require.
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
107 The package management facilities overlap somewhat with the auto-
108 loader, in that both arrange for files to be loaded on-demand. How‐
109 ever, package management is a higher-level mechanism that uses the
110 auto-loader for the last step in the loading process. It is generally
111 better to index a package with pkg_mkIndex rather than auto_mkindex
112 because the package mechanism provides version control: several ver‐
113 sions of a package can be made available in the index files, with dif‐
114 ferent applications using different versions based on package require
115 commands. In contrast, auto_mkindex does not understand versions so it
116 can only handle a single version of each package. It is probably not a
117 good idea to index a given package with both pkg_mkIndex and
118 auto_mkindex. If you use pkg_mkIndex to index a package, its commands
119 cannot be invoked until package require has been used to select a ver‐
120 sion; in contrast, packages indexed with auto_mkindex can be used
121 immediately since there is no version control.
122
125 Pkg_mkIndex depends on the package unknown command, the package
126 ifneeded command, and the auto-loader. The first time a package
127 require command is invoked, the package unknown script is invoked.
128 This is set by Tcl initialization to a script that evaluates all of the
129 pkgIndex.tcl files in the auto_path. The pkgIndex.tcl files contain
130 package ifneeded commands for each version of each available package;
131 these commands invoke package provide commands to announce the avail‐
132 ability of the package, and they setup auto-loader information to load
133 the files of the package. If the -lazy flag was provided when the │
134 pkgIndex.tcl was generated, a given file of a given version of a given
135 package isn't actually loaded until the first time one of its commands
136 is invoked. Thus, after invoking package require you may not see the
137 package's commands in the interpreter, but you will be able to invoke
138 the commands and they will be auto-loaded.
139
142 Some packages, for instance packages which use namespaces and export │
143 commands or those which require special initialization, might select │
144 that their package files be loaded immediately upon package require │
145 instead of delaying the actual loading to the first use of one of the │
146 package's command. This is the default mode when generating the package │
147 index. It can be overridden by specifying the -lazy argument.
148
151 Most complex cases of dependencies among scripts and binary files, and
152 packages being split among scripts and binary files are handled OK.
153 However, you may have to adjust the order in which files are processed
154 by pkg_mkIndex. These issues are described in detail below.
155 If each script or file contains one package, and packages are only con‐
157 tained in one file, then things are easy. You simply specify all files
158 to be indexed in any order with some glob patterns.
159 In general, it is OK for scripts to have dependencies on other pack‐
161 ages. If scripts contain package require commands, these are stubbed
162 out in the interpreter used to process the scripts, so these do not
163 cause problems. If scripts call into other packages in global code,
164 these calls are handled by a stub unknown command. However, if scripts
165 make variable references to other package's variables in global code,
166 these will cause errors. That is also bad coding style.
167 If binary files have dependencies on other packages, things can become
169 tricky because it is not possible to stub out C-level APIs such as
170 Tcl_PkgRequire API when loading a binary file. For example, suppose
171 the BLT package requires Tk, and expresses this with a call to
172 Tcl_PkgRequire in its Blt_Init routine. To support this, you must run
173 pkg_mkIndex in an interpreter that has Tk loaded. You can achieve this
174 with the -load pkgPat option. If you specify this option, pkg_mkIndex
175 will load any packages listed by info loaded and that match pkgPat into
176 the interpreter used to process files. In most cases this will satisfy
177 the Tcl_PkgRequire calls made by binary files.
178 If you are indexing two binary files and one depends on the other, you
180 should specify the one that has dependencies last. This way the one
181 without dependencies will get loaded and indexed, and then the package
182 it provides will be available when the second file is processed. You
183 may also need to load the first package into the temporary interpreter
184 used to create the index by using the -load flag; it won't hurt to
185 specify package patterns that are not yet loaded.
186 If you have a package that is split across scripts and a binary file,
188 then you should avoid the -load flag. The problem is that if you load a
189 package before computing the index it masks any other files that pro‐
190 vide part of the same package. If you must use -load, then you must
191 specify the scripts first; otherwise the package loaded from the binary
192 file may mask the package defined by the scripts.
193
196 package(n)
197
200 auto-load, index, package, version
201Tcl 8.3 pkg_mkIndex(n)