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