NAME

       pkg_mkIndex - 为包的自动装载建造一个索引

总览 SYNOPSIS

       pkg_mkIndex ?-direct?  ?-lazy?  ?-load pkgPat? ?-verbose? dir ?pattern pattern ...?                       2
_________________________________________________________________

描述 DESCRIPTION

       Pkg_mkIndex 是标准Tcl 库中的一个实用过程。它被用于建立索引文件，在执行 package require 的时候用它来允许自
       动装载包。使用 pkg_mkIndex要依从下面这些步骤:

       [1]    建立包。 每个包可以由一个或多个 Tcl   脚本文件或二进制文件组成。二进制文件必须适合使用有一个单一参
              数的  load  命令装载；例如，如果文件是  test.so   它必须可能用命令  load test.so  命令来装载这个文
              件。每个脚本文件必须包含一个 package provide  命令来声明包和版本号，而每个二进制文件必须包含一个对
              Tcl_PkgProvide的调用。

       [2]    通过调用 pkg_mkIndex 建立索引。 用 dir 参数给出一个目录的名字并且每个pattern  参数都是在 dir  中选
              择脚本或二进制文件的一个通配符式样的模式。 缺省的模式是 *.tcl 和 *.[info sharedlibextension]。     2
              Pkg_mkIndex 将在 dir   中建立一个文件 pkgIndex.tcl，其中有关于用 pattern  参数给出的所有文件的包信
              息。它通过把每个文件装载到一个从解释器中并查看出现了那些包和新命令来完成这项工作(这就是上面描述的
              在这些文件中必须有  package provide  命令或 Tcl_PkgProvide 调用的原因)。如果你有一个分开成多个脚本
              和二进制文件的包，或有文件间的依赖，你可能必须使用 -load 选项或调整  pkg_mkIndex  处理这些文件的次
              序。参见下面的 COMPLEX CASES 复杂情况。

       [3]    把包安装为由  tcl_pkgPath   变量给出的某个目录的子目录。如果 $tcl_pkgPath 包含多于一个的目录，依赖
              于机器的包(例如，包含二进制共享库的包)通常应该被安装在第一个目录下面而不依赖于机器的包(例如，只包
              含       Tcl        脚本的包)应该被安装在第二个目录下面。子目录应该包含包的脚本和/或二进制文件还有
              pkgIndex.tcl   文件。包被安装为在  $tcl_pkgPath   中的一个目录的一个子目录之后，在 package require
              命令期间可自动找到它。
              如果你把包安装在其他地方，则你必须确保包含包的目录在 auto_path 全局变量中或在 auto_path   中的一个
              目录的最直接(immediate)子目录中。Auto_path包含由自动装载器和包装载器查找的目录的一个列表；缺省的它
              包括   $tcl_pkgPath。包装载器也检查在  auto_path  中的目录的所有子目录。你可以在你的应用中显式的向
              auto_path增加一个目录，或向你的 TCLLIBPATH  环境变量添加这个目录:   如果这个环境变量存在，在应用启
              动期间Tcl 用它来初始化 auto_path。

       [4]    一旦进行了上述步骤，要使用一个包你需要做的就是调用  package  require。例如，如果包  Test    的版本
              2.1、2.3、和  3.1  已经用  pkg_mkIndex  建立了索引，package  require  Test 将可获得版本 3.1 而命令
              package require -exact Test 2.1将可获得版本 2.1。在 auto_path 中的不同的索引文件中可能有一个包的多
              个版本，实际上只有一个将被装载到给定的解释器中，具体决定于首先调用了哪个 package require。一个包的
              不同版本可以装载到不同的解释器中。

选项 OPTIONS

       选项开关有:

       -direct        The generated index will implement direct loading of the  package  upon  package  require.
                      This is the default.

       -lazy          生成的索引将设法延迟装载包，一直等到使用了由这个包提供命令之一，而不是在  package  require
                      时立即装载。

       -load pkgPat   索引处理将预装载在当前解释器中现存的所有包和匹配 pkgPat   的包装载到到用于生成索引的从解释
                      器中。模式匹配使用与字符串匹配相同的规则。参见下面的COMPLEX CASES复杂情况。

       -verbose       在索引处理期间生成输出。输出通过 tclLog    过程，这个过程缺省输出到 stderr。

       --             标志的终止，用于 dir  以连字号开始的情况。

包和自动装载器 PACKAGES AND THE AUTO-LOADER

       包管理设施与自动装载器在一些方面有所重叠，二者都安排文件在需要时(on-demand)装载。但是，包管理是一个高层机
       制，它在装载过程的最后一步使用自动装载器。一般的，使用pkg_mkIndex    给一个包加索引而不使用  auto_mkindex
       ，因为包机制提供了版本控制: 在索引文件中可获得一个包的多个版本，急于 package require   命令不同的应用可使
       用不同的版本。相反的，auto_mkindex     不理解版本，所以它只能处理每个包的一个单一版本。对一个给定的包使用
       pkg_mkIndex 和 auto_mkindex 两者来建立索引可能不是个好主意。如果你使用 pkg_mkIndex 来为一个包建立索引，它
       的命令不能被调用，一直等到使用 package require 选择了一个版本；相反的，用 auto_mkindex   建立索引的包由于
       没有版本而可以立即使用。

它是如何工作的 HOW IT WORKS

       Pkg_mkIndex  依赖于  package unknown  命令、package ifneeded 命令、和自动装载器。在第一次调用一个 package
       require命令时，调用 package unknown   脚本。Tcl   初始化把它设置成求值在auto_path  中的所有  pkgIndex.tcl
       文件的一个脚本。pkgIndex.tcl   文件包含给每个可获得的包的  package  ifneeded  命令；这些命令调用  package
       provide       命令来宣布这个包的可获得性，并且它们设置自动装载器的信息来装载这些包的文件。       如果在生 2
       成pkgIndex.tcl  时提供了 -lazy  标志， 在第一次调用它的命令之前不实际上装载一个给定包的给定版本的一个给定
       文件。所以在调用了 package  require之后，你可能在这个解释器中不能看到这个包的命令，但你可以调用它的命令而
       它们将被自动装载。

直接装载 DIRECT LOADING                                                                                          2
       一些包，例如使用了名字空间和导出命令或要求特殊初始化的包，可以选择在 package require 的时候立即装载它们的 2
       包文件而不是延迟实际的装载到第一次使用这个包中的命令的时候。在生成包索引时这是缺省的模式。可以指定  -lazy 2
       参数来屏弃(override)它。

复杂情况 COMPLEX CASES

       脚本和二进制文件之间存在依赖，和包被分开成脚本和二进制文件的可被正确处理。但是，你可能必须调整pkg_mkIndex
       处理这些文件的次序。下面详细描述这些要点。

       如果每个脚本或文件包含一个包，并且包只包含在一个文件中，则事情就很容易。你可以简单的用一些通配符模式指定
       以任意次序为所有文件建立索引。

       一般的，脚本依赖于其他包是没有问题的。如果脚本包含 package require 命令，在用于处理这个脚本的解释器中把他
       们连根拔除(stubbed     out)，所以不会导致问题。如果脚本调用了其他包的在全局代码中的过程，这些调用由一个存
       根(stub) unknown    命令处理。但是，如果脚本引用了其他包的在全局代码中的变量   ，这将导致错误。这也是糟糕
       的编码风格。

       如果二进制文件依赖于其他的包，事情就变的棘手了，因为在装载一个二进制文件时不可能连根拔除C-层次   API   如
       Tcl_PkgRequire API。例如，假设 BLT 包要求 Tk，并在它的 Blt_Init 例程中用对 Tcl_PkgRequire  的一个调用表达
       了这种需求。要支持它，你必须在一个已经装载了Tk  的解释器中运行 pkg_mkIndex。你用 -load pkgPat选项来完成这
       个任务。如果你指定了这个选项，pkg_mkIndex将装载在 info loaded 中列出的所有的包和那些匹配 pkgPat  的包到用
       于处理文件的解释器中。在多数情况下这将可以满足二进制文件中的 Tcl_PkgRequire 调用。

       如果你为两个二进制文件建立索引，其中的一个依赖于另一个，你应该最后指定有依赖的那个包。这样没有依赖的那个
       包将被装载和建立索引，那么在处理第二个文件的时候这个文件所提供的包就是可获得的了。你还必须使用 -load 标志
       把第一个包装载到用于建立索引的一个临时解释器中；这将无损于指定仍未装载的包模式。

       如果你有一个分开成一些脚本和一个二进制文件的包，则你必须避免  -load    标志。问题在于如果你在计算索引之前
       装载了一个包，它将屏蔽提供同一个包的其他部分的所有其他文件。如果你必须使用      -load，则你必须首先指定脚
       本；否则从二进制文件装载的包可能会屏蔽用脚本定义的包。

参见 SEE ALSO

       package(n)

关键字 KEYWORDS

       auto-load, index, package, version

[中文版维护人]

       寒蝉退士

[中文版最新更新]

       2001/09/01

《中国 Linux 论坛 man 手册页翻译计划》:

       http://cmpp.linuxforum.net

跋

       本页面中文版由中文 man 手册页计划提供。
       中文 man 手册页计划：https://github.com/man-pages-zh/manpages-zh

Tcl                                                    8.3                                     pkg_mkIndex(3tcl)