Ubuntu Manpage: pkg_mkIndex - 爲包的自動裝載建造一個索引

name
總覽 synopsis
描述 description
選項 options
包和自動裝載器 packages and the auto-loader
它是如何工作的 how it works
複雜情況 complex cases
參見 see also
關鍵字 keywords
[中文版維護人]
[中文版最新更新]
《中國 linux 論壇 man 手冊頁翻譯計劃》:
跋

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