NAME

       pkg_mkIndex - 為包的自動裝載建造一個索引

總覽 SYNOPSIS

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

描述 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]。
              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  命令來宣佈這個包的可獲得性，並且它
       們設定自動裝載器的資訊來裝載這些包的檔案。  如果在生成pkgIndex.tcl  時提供了 -lazy  標誌， │
       在第一次呼叫它的命令之前不實際上裝載一個給定包的給定版本的一個給定檔案。所以在呼叫了
       package  require之後，你可能在這個直譯器中不能看到這個包的命令，但你可以呼叫它的命令而它們
       將被自動裝載。

直接裝載 DIRECT LOADING                                                                           │
       一些包，例如使用了名字空間和匯出命令或要求特殊初始化的包，可以選擇在 package require  的時 │
       候立即裝載它們的包檔案而不是延遲實際的裝載到第一次使用這個包中的命令的時候。在生成包索引時 │
       這是預設的模式。可以指定 -lazy 引數來屏棄(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