2 pkg_mkIndex - Build an index for automatic loading of packages
5 pkg_mkIndex ?-direct? ?-lazy? ?-load pkgPat? ?-verbose? dir ?pattern pattern ...?
9 Pkg_mkIndex is a utility procedure that is part of the standard Tcl
10 library. It is used to create index files that allow packages to be
11 loaded automatically when package require commands are executed. To
12 use pkg_mkIndex, follow these steps:
14 [1] Create the package(s). Each package may consist of one or more
15 Tcl script files or binary files. Binary files must be suitable
16 for loading with the load command with a single argument; for
17 example, if the file is test.so it must be possible to load this
18 file with the command load test.so. Each script file must con-
19 tain a package provide command to declare the package and ver-
20 sion number, and each binary file must contain a call to
23 [2] Create the index by invoking pkg_mkIndex. The dir argument
24 gives the name of a directory and each pattern argument is a
25 glob-style pattern that selects script or binary files in dir.
26 The default pattern is *.tcl and *.[info sharedlibextension].
27 Pkg_mkIndex will create a file pkgIndex.tcl in dir with package
28 information about all the files given by the pattern arguments.
29 It does this by loading each file into a slave interpreter and
30 seeing what packages and new commands appear (this is why it is
31 essential to have package provide commands or Tcl_PkgProvide
32 calls in the files, as described above). If you have a package
33 split among scripts and binary files, or if you have dependen-
34 cies among files, you may have to use the -load option or adjust
35 the order in which pkg_mkIndex processes the files. See COMPLEX
39 [3] Install the package as a subdirectory of one of the directories
40 given by the tcl_pkgPath variable. If $tcl_pkgPath contains
41 more than one directory, machine-dependent packages (e.g., those
42 that contain binary shared libraries) should normally be
43 installed under the first directory and machine-independent
44 packages (e.g., those that contain only Tcl scripts) should be
45 installed under the second directory. The subdirectory should
46 include the package's script and/or binary files as well as the
47 pkgIndex.tcl file. As long as the package is installed as a
48 subdirectory of a directory in $tcl_pkgPath it will automati-
49 cally be found during package require commands.
50 If you install the package anywhere else, then you must ensure
51 that the directory containing the package is in the auto_path
52 global variable or an immediate subdirectory of one of the
53 directories in auto_path. Auto_path contains a list of directo-
54 ries that are searched by both the auto-loader and the package
55 loader; by default it includes $tcl_pkgPath. The package loader
56 also checks all of the subdirectories of the directories in
57 auto_path. You can add a directory to auto_path explicitly in
58 your application, or you can add the directory to your TCLLIB-
59 PATH environment variable: if this environment variable is
60 present, Tcl initializes auto_path from it during application
63 [4] Once the above steps have been taken, all you need to do to use
64 a package is to invoke package require. For example, if ver-
65 sions 2.1, 2.3, and 3.1 of package Test have been indexed by
66 pkg_mkIndex, the command package require Test will make version
67 3.1 available and the command package require -exact Test 2.1
68 will make version 2.1 available. There may be many versions of
69 a package in the various index files in auto_path, but only one
70 will actually be loaded in a given interpreter, based on the
71 first call to package require. Different versions of a package
72 may be loaded in different interpreters.
76 The optional switches are:
78 -direct The generated index will implement direct loading of the
79 package upon package require. This is the default.
81 -lazy The generated index will manage to delay loading the
82 package until the use of one of the commands provided by
83 the package, instead of loading it immediately upon
86 -load pkgPat The index process will pre-load any packages that exist
87 in the current interpreter and match pkgPat into the
88 slave interpreter used to generate the index. The pat-
89 tern match uses string match rules, but without making
90 case distinctions. See COMPLEX CASES below.
92 -verbose Generate output during the indexing process. Output is
93 via the tclLog procedure, which by default prints to
96 -- End of the flags, in case dir begins with a dash.
99 PACKAGES AND THE AUTO-LOADER
100 The package management facilities overlap somewhat with the auto-
101 loader, in that both arrange for files to be loaded on-demand. How-
102 ever, package management is a higher-level mechanism that uses the
103 auto-loader for the last step in the loading process. It is generally
104 better to index a package with pkg_mkIndex rather than auto_mkindex
105 because the package mechanism provides version control: several ver-
106 sions of a package can be made available in the index files, with dif-
107 ferent applications using different versions based on package require
108 commands. In contrast, auto_mkindex does not understand versions so it
109 can only handle a single version of each package. It is probably not a
110 good idea to index a given package with both pkg_mkIndex and
111 auto_mkindex. If you use pkg_mkIndex to index a package, its commands
112 cannot be invoked until package require has been used to select a ver-
113 sion; in contrast, packages indexed with auto_mkindex can be used
114 immediately since there is no version control.
118 Pkg_mkIndex depends on the package unknown command, the package
119 ifneeded command, and the auto-loader. The first time a package
120 require command is invoked, the package unknown script is invoked.
121 This is set by Tcl initialization to a script that evaluates all of the
122 pkgIndex.tcl files in the auto_path. The pkgIndex.tcl files contain
123 package ifneeded commands for each version of each available package;
124 these commands invoke package provide commands to announce the avail-
125 ability of the package, and they setup auto-loader information to load
126 the files of the package. If the -lazy flag was provided when the
127 pkgIndex.tcl was generated, a given file of a given version of a given
128 package isn't actually loaded until the first time one of its commands
129 is invoked. Thus, after invoking package require you may not see the
130 package's commands in the interpreter, but you will be able to invoke
131 the commands and they will be auto-loaded.
135 Some packages, for instance packages which use namespaces and export
136 commands or those which require special initialization, might select
137 that their package files be loaded immediately upon package require
138 instead of delaying the actual loading to the first use of one of the
139 package's command. This is the default mode when generating the package
140 index. It can be overridden by specifying the -lazy argument.
144 Most complex cases of dependencies among scripts and binary files, and
145 packages being split among scripts and binary files are handled OK.
146 However, you may have to adjust the order in which files are processed
147 by pkg_mkIndex. These issues are described in detail below.
149 If each script or file contains one package, and packages are only con-
150 tained in one file, then things are easy. You simply specify all files
151 to be indexed in any order with some glob patterns.
153 In general, it is OK for scripts to have dependencies on other pack-
154 ages. If scripts contain package require commands, these are stubbed
155 out in the interpreter used to process the scripts, so these do not
156 cause problems. If scripts call into other packages in global code,
157 these calls are handled by a stub unknown command. However, if scripts
158 make variable references to other package's variables in global code,
159 these will cause errors. That is also bad coding style.
161 If binary files have dependencies on other packages, things can become
162 tricky because it is not possible to stub out C-level APIs such as
163 Tcl_PkgRequire API when loading a binary file. For example, suppose
164 the BLT package requires Tk, and expresses this with a call to
165 Tcl_PkgRequire in its Blt_Init routine. To support this, you must run
166 pkg_mkIndex in an interpreter that has Tk loaded. You can achieve this
167 with the -load pkgPat option. If you specify this option, pkg_mkIndex
168 will load any packages listed by info loaded and that match pkgPat into
169 the interpreter used to process files. In most cases this will satisfy
170 the Tcl_PkgRequire calls made by binary files.
172 If you are indexing two binary files and one depends on the other, you
173 should specify the one that has dependencies last. This way the one
174 without dependencies will get loaded and indexed, and then the package
175 it provides will be available when the second file is processed. You
176 may also need to load the first package into the temporary interpreter
177 used to create the index by using the -load flag; it won't hurt to
178 specify package patterns that are not yet loaded.
180 If you have a package that is split across scripts and a binary file,
181 then you should avoid the -load flag. The problem is that if you load a
182 package before computing the index it masks any other files that pro-
183 vide part of the same package. If you must use -load, then you must
184 specify the scripts first; otherwise the package loaded from the binary
185 file may mask the package defined by the scripts.
projects / tas-yagle.git / blob