| 1 | '\" |
| 2 | '\" Copyright (c) 1996 Sun Microsystems, Inc. |
| 3 | '\" |
| 4 | '\" See the file "license.terms" for information on usage and redistribution |
| 5 | '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. |
| 6 | '\" |
| 7 | '\" RCS: @(#) $Id: pkgMkIndex.n,v 1.14 2003/02/25 23:58:09 dgp Exp $ |
| 8 | '\" |
| 9 | '\" The definitions below are for supplemental macros used in Tcl/Tk |
| 10 | '\" manual entries. |
| 11 | '\" |
| 12 | '\" .AP type name in/out ?indent? |
| 13 | '\" Start paragraph describing an argument to a library procedure. |
| 14 | '\" type is type of argument (int, etc.), in/out is either "in", "out", |
| 15 | '\" or "in/out" to describe whether procedure reads or modifies arg, |
| 16 | '\" and indent is equivalent to second arg of .IP (shouldn't ever be |
| 17 | '\" needed; use .AS below instead) |
| 18 | '\" |
| 19 | '\" .AS ?type? ?name? |
| 20 | '\" Give maximum sizes of arguments for setting tab stops. Type and |
| 21 | '\" name are examples of largest possible arguments that will be passed |
| 22 | '\" to .AP later. If args are omitted, default tab stops are used. |
| 23 | '\" |
| 24 | '\" .BS |
| 25 | '\" Start box enclosure. From here until next .BE, everything will be |
| 26 | '\" enclosed in one large box. |
| 27 | '\" |
| 28 | '\" .BE |
| 29 | '\" End of box enclosure. |
| 30 | '\" |
| 31 | '\" .CS |
| 32 | '\" Begin code excerpt. |
| 33 | '\" |
| 34 | '\" .CE |
| 35 | '\" End code excerpt. |
| 36 | '\" |
| 37 | '\" .VS ?version? ?br? |
| 38 | '\" Begin vertical sidebar, for use in marking newly-changed parts |
| 39 | '\" of man pages. The first argument is ignored and used for recording |
| 40 | '\" the version when the .VS was added, so that the sidebars can be |
| 41 | '\" found and removed when they reach a certain age. If another argument |
| 42 | '\" is present, then a line break is forced before starting the sidebar. |
| 43 | '\" |
| 44 | '\" .VE |
| 45 | '\" End of vertical sidebar. |
| 46 | '\" |
| 47 | '\" .DS |
| 48 | '\" Begin an indented unfilled display. |
| 49 | '\" |
| 50 | '\" .DE |
| 51 | '\" End of indented unfilled display. |
| 52 | '\" |
| 53 | '\" .SO |
| 54 | '\" Start of list of standard options for a Tk widget. The |
| 55 | '\" options follow on successive lines, in four columns separated |
| 56 | '\" by tabs. |
| 57 | '\" |
| 58 | '\" .SE |
| 59 | '\" End of list of standard options for a Tk widget. |
| 60 | '\" |
| 61 | '\" .OP cmdName dbName dbClass |
| 62 | '\" Start of description of a specific option. cmdName gives the |
| 63 | '\" option's name as specified in the class command, dbName gives |
| 64 | '\" the option's name in the option database, and dbClass gives |
| 65 | '\" the option's class in the option database. |
| 66 | '\" |
| 67 | '\" .UL arg1 arg2 |
| 68 | '\" Print arg1 underlined, then print arg2 normally. |
| 69 | '\" |
| 70 | '\" RCS: @(#) $Id: man.macros,v 1.4 2000/08/25 06:18:32 ericm Exp $ |
| 71 | '\" |
| 72 | '\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. |
| 73 | .if t .wh -1.3i ^B |
| 74 | .nr ^l \n(.l |
| 75 | .ad b |
| 76 | '\" # Start an argument description |
| 77 | .de AP |
| 78 | .ie !"\\$4"" .TP \\$4 |
| 79 | .el \{\ |
| 80 | . ie !"\\$2"" .TP \\n()Cu |
| 81 | . el .TP 15 |
| 82 | .\} |
| 83 | .ta \\n()Au \\n()Bu |
| 84 | .ie !"\\$3"" \{\ |
| 85 | \&\\$1 \\fI\\$2\\fP (\\$3) |
| 86 | .\".b |
| 87 | .\} |
| 88 | .el \{\ |
| 89 | .br |
| 90 | .ie !"\\$2"" \{\ |
| 91 | \&\\$1 \\fI\\$2\\fP |
| 92 | .\} |
| 93 | .el \{\ |
| 94 | \&\\fI\\$1\\fP |
| 95 | .\} |
| 96 | .\} |
| 97 | .. |
| 98 | '\" # define tabbing values for .AP |
| 99 | .de AS |
| 100 | .nr )A 10n |
| 101 | .if !"\\$1"" .nr )A \\w'\\$1'u+3n |
| 102 | .nr )B \\n()Au+15n |
| 103 | .\" |
| 104 | .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n |
| 105 | .nr )C \\n()Bu+\\w'(in/out)'u+2n |
| 106 | .. |
| 107 | .AS Tcl_Interp Tcl_CreateInterp in/out |
| 108 | '\" # BS - start boxed text |
| 109 | '\" # ^y = starting y location |
| 110 | '\" # ^b = 1 |
| 111 | .de BS |
| 112 | .br |
| 113 | .mk ^y |
| 114 | .nr ^b 1u |
| 115 | .if n .nf |
| 116 | .if n .ti 0 |
| 117 | .if n \l'\\n(.lu\(ul' |
| 118 | .if n .fi |
| 119 | .. |
| 120 | '\" # BE - end boxed text (draw box now) |
| 121 | .de BE |
| 122 | .nf |
| 123 | .ti 0 |
| 124 | .mk ^t |
| 125 | .ie n \l'\\n(^lu\(ul' |
| 126 | .el \{\ |
| 127 | .\" Draw four-sided box normally, but don't draw top of |
| 128 | .\" box if the box started on an earlier page. |
| 129 | .ie !\\n(^b-1 \{\ |
| 130 | \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' |
| 131 | .\} |
| 132 | .el \}\ |
| 133 | \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' |
| 134 | .\} |
| 135 | .\} |
| 136 | .fi |
| 137 | .br |
| 138 | .nr ^b 0 |
| 139 | .. |
| 140 | '\" # VS - start vertical sidebar |
| 141 | '\" # ^Y = starting y location |
| 142 | '\" # ^v = 1 (for troff; for nroff this doesn't matter) |
| 143 | .de VS |
| 144 | .if !"\\$2"" .br |
| 145 | .mk ^Y |
| 146 | .ie n 'mc \s12\(br\s0 |
| 147 | .el .nr ^v 1u |
| 148 | .. |
| 149 | '\" # VE - end of vertical sidebar |
| 150 | .de VE |
| 151 | .ie n 'mc |
| 152 | .el \{\ |
| 153 | .ev 2 |
| 154 | .nf |
| 155 | .ti 0 |
| 156 | .mk ^t |
| 157 | \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' |
| 158 | .sp -1 |
| 159 | .fi |
| 160 | .ev |
| 161 | .\} |
| 162 | .nr ^v 0 |
| 163 | .. |
| 164 | '\" # Special macro to handle page bottom: finish off current |
| 165 | '\" # box/sidebar if in box/sidebar mode, then invoked standard |
| 166 | '\" # page bottom macro. |
| 167 | .de ^B |
| 168 | .ev 2 |
| 169 | 'ti 0 |
| 170 | 'nf |
| 171 | .mk ^t |
| 172 | .if \\n(^b \{\ |
| 173 | .\" Draw three-sided box if this is the box's first page, |
| 174 | .\" draw two sides but no top otherwise. |
| 175 | .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c |
| 176 | .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c |
| 177 | .\} |
| 178 | .if \\n(^v \{\ |
| 179 | .nr ^x \\n(^tu+1v-\\n(^Yu |
| 180 | \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c |
| 181 | .\} |
| 182 | .bp |
| 183 | 'fi |
| 184 | .ev |
| 185 | .if \\n(^b \{\ |
| 186 | .mk ^y |
| 187 | .nr ^b 2 |
| 188 | .\} |
| 189 | .if \\n(^v \{\ |
| 190 | .mk ^Y |
| 191 | .\} |
| 192 | .. |
| 193 | '\" # DS - begin display |
| 194 | .de DS |
| 195 | .RS |
| 196 | .nf |
| 197 | .sp |
| 198 | .. |
| 199 | '\" # DE - end display |
| 200 | .de DE |
| 201 | .fi |
| 202 | .RE |
| 203 | .sp |
| 204 | .. |
| 205 | '\" # SO - start of list of standard options |
| 206 | .de SO |
| 207 | .SH "STANDARD OPTIONS" |
| 208 | .LP |
| 209 | .nf |
| 210 | .ta 5.5c 11c |
| 211 | .ft B |
| 212 | .. |
| 213 | '\" # SE - end of list of standard options |
| 214 | .de SE |
| 215 | .fi |
| 216 | .ft R |
| 217 | .LP |
| 218 | See the \\fBoptions\\fR manual entry for details on the standard options. |
| 219 | .. |
| 220 | '\" # OP - start of full description for a single option |
| 221 | .de OP |
| 222 | .LP |
| 223 | .nf |
| 224 | .ta 4c |
| 225 | Command-Line Name: \\fB\\$1\\fR |
| 226 | Database Name: \\fB\\$2\\fR |
| 227 | Database Class: \\fB\\$3\\fR |
| 228 | .fi |
| 229 | .IP |
| 230 | .. |
| 231 | '\" # CS - begin code excerpt |
| 232 | .de CS |
| 233 | .RS |
| 234 | .nf |
| 235 | .ta .25i .5i .75i 1i |
| 236 | .. |
| 237 | '\" # CE - end code excerpt |
| 238 | .de CE |
| 239 | .fi |
| 240 | .RE |
| 241 | .. |
| 242 | .de UL |
| 243 | \\$1\l'|0\(ul'\\$2 |
| 244 | .. |
| 245 | .TH pkg_mkIndex n 8.3 Tcl "Tcl Built-In Commands" |
| 246 | .BS |
| 247 | '\" Note: do not modify the .SH NAME line immediately below! |
| 248 | .SH NAME |
| 249 | pkg_mkIndex \- Build an index for automatic loading of packages |
| 250 | .SH SYNOPSIS |
| 251 | .nf |
| 252 | .VS 8.3.0 |
| 253 | \fBpkg_mkIndex ?\fI\-direct\fR? ?\fI\-lazy\fR? ?\fI\-load pkgPat\fR? ?\fI\-verbose\fR? \fIdir\fR ?\fIpattern pattern ...\fR? |
| 254 | .VE |
| 255 | .fi |
| 256 | .BE |
| 257 | |
| 258 | .SH DESCRIPTION |
| 259 | .PP |
| 260 | \fBPkg_mkIndex\fR is a utility procedure that is part of the standard |
| 261 | Tcl library. |
| 262 | It is used to create index files that allow packages to be loaded |
| 263 | automatically when \fBpackage require\fR commands are executed. |
| 264 | To use \fBpkg_mkIndex\fR, follow these steps: |
| 265 | .IP [1] |
| 266 | Create the package(s). |
| 267 | Each package may consist of one or more Tcl script files or binary files. |
| 268 | Binary files must be suitable for loading with the \fBload\fR command |
| 269 | with a single argument; for example, if the file is \fBtest.so\fR it must |
| 270 | be possible to load this file with the command \fBload test.so\fR. |
| 271 | Each script file must contain a \fBpackage provide\fR command to declare |
| 272 | the package and version number, and each binary file must contain |
| 273 | a call to \fBTcl_PkgProvide\fR. |
| 274 | .IP [2] |
| 275 | Create the index by invoking \fBpkg_mkIndex\fR. |
| 276 | The \fIdir\fR argument gives the name of a directory and each |
| 277 | \fIpattern\fR argument is a \fBglob\fR-style pattern that selects |
| 278 | script or binary files in \fIdir\fR. |
| 279 | .VS 8.0.3 |
| 280 | The default pattern is \fB*.tcl\fR and \fB*.[info sharedlibextension]\fR. |
| 281 | .VE |
| 282 | .br |
| 283 | \fBPkg_mkIndex\fR will create a file \fBpkgIndex.tcl\fR in \fIdir\fR |
| 284 | with package information about all the files given by the \fIpattern\fR |
| 285 | arguments. |
| 286 | It does this by loading each file into a slave |
| 287 | interpreter and seeing what packages |
| 288 | and new commands appear (this is why it is essential to have |
| 289 | \fBpackage provide\fR commands or \fBTcl_PkgProvide\fR calls |
| 290 | in the files, as described above). |
| 291 | If you have a package split among scripts and binary files, |
| 292 | or if you have dependencies among files, |
| 293 | you may have to use the \fB\-load\fP option |
| 294 | or adjust the order in which \fBpkg_mkIndex\fR processes |
| 295 | the files. See COMPLEX CASES below. |
| 296 | |
| 297 | .IP [3] |
| 298 | Install the package as a subdirectory of one of the directories given by |
| 299 | the \fBtcl_pkgPath\fR variable. If \fB$tcl_pkgPath\fR contains more |
| 300 | than one directory, machine-dependent packages (e.g., those that |
| 301 | contain binary shared libraries) should normally be installed |
| 302 | under the first directory and machine-independent packages (e.g., |
| 303 | those that contain only Tcl scripts) should be installed under the |
| 304 | second directory. |
| 305 | The subdirectory should include |
| 306 | the package's script and/or binary files as well as the \fBpkgIndex.tcl\fR |
| 307 | file. As long as the package is installed as a subdirectory of a |
| 308 | directory in \fB$tcl_pkgPath\fR it will automatically be found during |
| 309 | \fBpackage require\fR commands. |
| 310 | .br |
| 311 | If you install the package anywhere else, then you must ensure that |
| 312 | the directory containing the package is in the \fBauto_path\fR global variable |
| 313 | or an immediate subdirectory of one of the directories in \fBauto_path\fR. |
| 314 | \fBAuto_path\fR contains a list of directories that are searched |
| 315 | by both the auto-loader and the package loader; by default it |
| 316 | includes \fB$tcl_pkgPath\fR. |
| 317 | The package loader also checks all of the subdirectories of the |
| 318 | directories in \fBauto_path\fR. |
| 319 | You can add a directory to \fBauto_path\fR explicitly in your |
| 320 | application, or you can add the directory to your \fBTCLLIBPATH\fR |
| 321 | environment variable: if this environment variable is present, |
| 322 | Tcl initializes \fBauto_path\fR from it during application startup. |
| 323 | .IP [4] |
| 324 | Once the above steps have been taken, all you need to do to use a |
| 325 | package is to invoke \fBpackage require\fR. |
| 326 | For example, if versions 2.1, 2.3, and 3.1 of package \fBTest\fR |
| 327 | have been indexed by \fBpkg_mkIndex\fR, the command |
| 328 | \fBpackage require Test\fR will make version 3.1 available |
| 329 | and the command \fBpackage require \-exact Test 2.1\fR will |
| 330 | make version 2.1 available. |
| 331 | There may be many versions of a package in the various index files |
| 332 | in \fBauto_path\fR, but only one will actually be loaded in a given |
| 333 | interpreter, based on the first call to \fBpackage require\fR. |
| 334 | Different versions of a package may be loaded in different |
| 335 | interpreters. |
| 336 | |
| 337 | .SH OPTIONS |
| 338 | The optional switches are: |
| 339 | .TP 15 |
| 340 | \fB\-direct\fR |
| 341 | The generated index will implement direct loading of the package |
| 342 | upon \fBpackage require\fR. This is the default. |
| 343 | .TP 15 |
| 344 | \fB\-lazy\fR |
| 345 | The generated index will manage to delay loading the package until the |
| 346 | use of one of the commands provided by the package, instead of loading |
| 347 | it immediately upon \fBpackage require\fR. |
| 348 | .TP 15 |
| 349 | \fB\-load \fIpkgPat\fR |
| 350 | The index process will pre-load any packages that exist in the |
| 351 | current interpreter and match \fIpkgPat\fP into the slave interpreter used to |
| 352 | generate the index. The pattern match uses string match rules, but without |
| 353 | making case distinctions. |
| 354 | See COMPLEX CASES below. |
| 355 | .TP 15 |
| 356 | \fB\-verbose\fR |
| 357 | Generate output during the indexing process. Output is via |
| 358 | the \fBtclLog\fP procedure, which by default prints to stderr. |
| 359 | .TP 15 |
| 360 | \fB\-\-\fR |
| 361 | End of the flags, in case \fIdir\fP begins with a dash. |
| 362 | |
| 363 | .SH "PACKAGES AND THE AUTO-LOADER" |
| 364 | .PP |
| 365 | The package management facilities overlap somewhat with the auto-loader, |
| 366 | in that both arrange for files to be loaded on-demand. |
| 367 | However, package management is a higher-level mechanism that uses |
| 368 | the auto-loader for the last step in the loading process. |
| 369 | It is generally better to index a package with \fBpkg_mkIndex\fR |
| 370 | rather than \fBauto_mkindex\fR because the package mechanism provides |
| 371 | version control: several versions of a package can be made available |
| 372 | in the index files, with different applications using different |
| 373 | versions based on \fBpackage require\fR commands. |
| 374 | In contrast, \fBauto_mkindex\fR does not understand versions so |
| 375 | it can only handle a single version of each package. |
| 376 | It is probably not a good idea to index a given package with both |
| 377 | \fBpkg_mkIndex\fR and \fBauto_mkindex\fR. |
| 378 | If you use \fBpkg_mkIndex\fR to index a package, its commands cannot |
| 379 | be invoked until \fBpackage require\fR has been used to select a |
| 380 | version; in contrast, packages indexed with \fBauto_mkindex\fR |
| 381 | can be used immediately since there is no version control. |
| 382 | |
| 383 | .SH "HOW IT WORKS" |
| 384 | .PP |
| 385 | \fBPkg_mkIndex\fR depends on the \fBpackage unknown\fR command, |
| 386 | the \fBpackage ifneeded\fR command, and the auto-loader. |
| 387 | The first time a \fBpackage require\fR command is invoked, |
| 388 | the \fBpackage unknown\fR script is invoked. |
| 389 | This is set by Tcl initialization to a script that |
| 390 | evaluates all of the \fBpkgIndex.tcl\fR files in the |
| 391 | \fBauto_path\fR. |
| 392 | The \fBpkgIndex.tcl\fR files contain \fBpackage ifneeded\fR |
| 393 | commands for each version of each available package; these commands |
| 394 | invoke \fBpackage provide\fR commands to announce the |
| 395 | availability of the package, and they setup auto-loader |
| 396 | information to load the files of the package. |
| 397 | .VS 8.3 |
| 398 | If the \fI\-lazy\fR flag was provided when the \fBpkgIndex.tcl\fR |
| 399 | was generated, |
| 400 | .VE |
| 401 | a given file of a given version of a given package isn't |
| 402 | actually loaded until the first time one of its commands |
| 403 | is invoked. |
| 404 | Thus, after invoking \fBpackage require\fR you may |
| 405 | not see the package's commands in the interpreter, but you will be able |
| 406 | to invoke the commands and they will be auto-loaded. |
| 407 | |
| 408 | .VS 8.3 |
| 409 | .SH "DIRECT LOADING" |
| 410 | .PP |
| 411 | Some packages, for instance packages which use namespaces and export |
| 412 | commands or those which require special initialization, might select |
| 413 | that their package files be loaded immediately upon \fBpackage require\fR |
| 414 | instead of delaying the actual loading to the first use of one of the |
| 415 | package's command. This is the default mode when generating the package |
| 416 | index. It can be overridden by specifying the \fI\-lazy\fR argument. |
| 417 | .VE |
| 418 | |
| 419 | .SH "COMPLEX CASES" |
| 420 | Most complex cases of dependencies among scripts |
| 421 | and binary files, and packages being split among scripts and |
| 422 | binary files are handled OK. However, you may have to adjust |
| 423 | the order in which files are processed by \fBpkg_mkIndex\fR. |
| 424 | These issues are described in detail below. |
| 425 | .PP |
| 426 | If each script or file contains one package, and packages |
| 427 | are only contained in one file, then things are easy. |
| 428 | You simply specify all files to be indexed in any order |
| 429 | with some glob patterns. |
| 430 | .PP |
| 431 | In general, it is OK for scripts to have dependencies on other |
| 432 | packages. |
| 433 | If scripts contain \fBpackage require\fP commands, these are |
| 434 | stubbed out in the interpreter used to process the scripts, |
| 435 | so these do not cause problems. |
| 436 | If scripts call into other packages in global code, |
| 437 | these calls are handled by a stub \fBunknown\fP command. |
| 438 | However, if scripts make variable references to other package's |
| 439 | variables in global code, these will cause errors. That is |
| 440 | also bad coding style. |
| 441 | .PP |
| 442 | If binary files have dependencies on other packages, things |
| 443 | can become tricky because it is not possible to stub out |
| 444 | C-level APIs such as \fBTcl_PkgRequire\fP API |
| 445 | when loading a binary file. |
| 446 | For example, suppose the BLT package requires Tk, and expresses |
| 447 | this with a call to \fBTcl_PkgRequire\fP in its \fBBlt_Init\fP routine. |
| 448 | To support this, you must run \fBpkg_mkIndex\fR in an interpreter that |
| 449 | has Tk loaded. You can achieve this with the |
| 450 | \fB\-load \fIpkgPat\fR option. If you specify this option, |
| 451 | \fBpkg_mkIndex\fR will load any packages listed by |
| 452 | \fBinfo loaded\fP and that match \fIpkgPat\fP |
| 453 | into the interpreter used to process files. |
| 454 | In most cases this will satisfy the \fBTcl_PkgRequire\fP calls |
| 455 | made by binary files. |
| 456 | .PP |
| 457 | If you are indexing two binary files and one depends on the other, |
| 458 | you should specify the one that has dependencies last. |
| 459 | This way the one without dependencies will get loaded and indexed, |
| 460 | and then the package it provides |
| 461 | will be available when the second file is processed. |
| 462 | You may also need to load the first package into the |
| 463 | temporary interpreter used to create the index by using |
| 464 | the \fB\-load\fP flag; |
| 465 | it won't hurt to specify package patterns that are not yet loaded. |
| 466 | .PP |
| 467 | If you have a package that is split across scripts and a binary file, |
| 468 | then you should avoid the \fB\-load\fP flag. The problem is that |
| 469 | if you load a package before computing the index it masks any |
| 470 | other files that provide part of the same package. |
| 471 | If you must use \fB\-load\fP, |
| 472 | then you must specify the scripts first; otherwise the package loaded from |
| 473 | the binary file may mask the package defined by the scripts. |
| 474 | |
| 475 | .SH "SEE ALSO" |
| 476 | package(n) |
| 477 | |
| 478 | .SH KEYWORDS |
| 479 | auto-load, index, package, version |