'\"
'\" Copyright (c) 1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: pkgMkIndex.n,v 1.2 2003/11/24 05:09:59 bbbush Exp $
'\" 
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
'\"	or "in/out" to describe whether procedure reads or modifies arg,
'\"	and indent is equivalent to second arg of .IP (shouldn't ever be
'\"	needed;  use .AS below instead)
'\"
'\" .AS ?type? ?name?
'\"	Give maximum sizes of arguments for setting tab stops.  Type and
'\"	name are examples of largest possible arguments that will be passed
'\"	to .AP later.  If args are omitted, default tab stops are used.
'\"
'\" .BS
'\"	Start box enclosure.  From here until next .BE, everything will be
'\"	enclosed in one large box.
'\"
'\" .BE
'\"	End of box enclosure.
'\"
'\" .CS
'\"	Begin code excerpt.
'\"
'\" .CE
'\"	End code excerpt.
'\"
'\" .VS ?version? ?br?
'\"	Begin vertical sidebar, for use in marking newly-changed parts
'\"	of man pages.  The first argument is ignored and used for recording
'\"	the version when the .VS was added, so that the sidebars can be
'\"	found and removed when they reach a certain age.  If another argument
'\"	is present, then a line break is forced before starting the sidebar.
'\"
'\" .VE
'\"	End of vertical sidebar.
'\"
'\" .DS
'\"	Begin an indented unfilled display.
'\"
'\" .DE
'\"	End of indented unfilled display.
'\"
'\" .SO
'\"	Start of list of standard options for a Tk widget.  The
'\"	options follow on successive lines, in four columns separated
'\"	by tabs.
'\"
'\" .SE
'\"	End of list of standard options for a Tk widget.
'\"
'\" .OP cmdName dbName dbClass
'\"	Start of description of a specific option.  cmdName gives the
'\"	option's name as specified in the class command, dbName gives
'\"	the option's name in the option database, and dbClass gives
'\"	the option's class in the option database.
'\"
'\" .UL arg1 arg2
'\"	Print arg1 underlined, then print arg2 normally.
'\"
'\" RCS: @(#) $Id: pkgMkIndex.n,v 1.2 2003/11/24 05:09:59 bbbush Exp $
'\"
'\"	# Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
.if t .wh -1.3i ^B
.nr ^l \n(.l
.ad b
'\"	# Start an argument description
.de AP
.ie !"\\$4"" .TP \\$4
.el \{\
.   ie !"\\$2"" .TP \\n()Cu
.   el          .TP 15
.\}
.ta \\n()Au \\n()Bu
.ie !"\\$3"" \{\
\&\\$1	\\fI\\$2\\fP	(\\$3)
.\".b
.\}
.el \{\
.br
.ie !"\\$2"" \{\
\&\\$1	\\fI\\$2\\fP
.\}
.el \{\
\&\\fI\\$1\\fP
.\}
.\}
..
'\"	# define tabbing values for .AP
.de AS
.nr )A 10n
.if !"\\$1"" .nr )A \\w'\\$1'u+3n
.nr )B \\n()Au+15n
.\"
.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
.nr )C \\n()Bu+\\w'(in/out)'u+2n
..
.AS Tcl_Interp Tcl_CreateInterp in/out
'\"	# BS - start boxed text
'\"	# ^y = starting y location
'\"	# ^b = 1
.de BS
.br
.mk ^y
.nr ^b 1u
.if n .nf
.if n .ti 0
.if n \l'\\n(.lu\(ul'
.if n .fi
..
'\"	# BE - end boxed text (draw box now)
.de BE
.nf
.ti 0
.mk ^t
.ie n \l'\\n(^lu\(ul'
.el \{\
.\"	Draw four-sided box normally, but don't draw top of
.\"	box if the box started on an earlier page.
.ie !\\n(^b-1 \{\
\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.el \}\
\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.\}
.fi
.br
.nr ^b 0
..
'\"	# VS - start vertical sidebar
'\"	# ^Y = starting y location
'\"	# ^v = 1 (for troff;  for nroff this doesn't matter)
.de VS
.if !"\\$2"" .br
.mk ^Y
.ie n 'mc \s12\(br\s0
.el .nr ^v 1u
..
'\"	# VE - end of vertical sidebar
.de VE
.ie n 'mc
.el \{\
.ev 2
.nf
.ti 0
.mk ^t
\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
.sp -1
.fi
.ev
.\}
.nr ^v 0
..
'\"	# Special macro to handle page bottom:  finish off current
'\"	# box/sidebar if in box/sidebar mode, then invoked standard
'\"	# page bottom macro.
.de ^B
.ev 2
'ti 0
'nf
.mk ^t
.if \\n(^b \{\
.\"	Draw three-sided box if this is the box's first page,
.\"	draw two sides but no top otherwise.
.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
.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
.\}
.if \\n(^v \{\
.nr ^x \\n(^tu+1v-\\n(^Yu
\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
.\}
.bp
'fi
.ev
.if \\n(^b \{\
.mk ^y
.nr ^b 2
.\}
.if \\n(^v \{\
.mk ^Y
.\}
..
'\"	# DS - begin display
.de DS
.RS
.nf
.sp
..
'\"	# DE - end display
.de DE
.fi
.RE
.sp
..
'\"	# SO - start of list of standard options
.de SO
.SH "STANDARD OPTIONS"
.LP
.nf
.ta 5.5c 11c
.ft B
..
'\"	# SE - end of list of standard options
.de SE
.fi
.ft R
.LP
See the \\fBoptions\\fR manual entry for details on the standard options.
..
'\"	# OP - start of full description for a single option
.de OP
.LP
.nf
.ta 4c
Command-Line Name:	\\fB\\$1\\fR
Database Name:	\\fB\\$2\\fR
Database Class:	\\fB\\$3\\fR
.fi
.IP
..
'\"	# CS - begin code excerpt
.de CS
.RS
.nf
.ta .25i .5i .75i 1i
..
'\"	# CE - end code excerpt
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH pkg_mkIndex 3tcl 8.3 Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
pkg_mkIndex \- 為包的自動裝載建造一個索引
.SH "總覽 SYNOPSIS"
.nf
.VS 8.3.0
\fBpkg_mkIndex ?\fI\-direct\fR?  ?\fI\-lazy\fR?  ?\fI\-load pkgPat\fR? ?\fI\-verbose\fR? \fIdir\fR ?\fIpattern pattern ...\fR?
.VE
.fi
.BE

.SH "描述 DESCRIPTION"
.PP
\fBPkg_mkIndex\fR 是標準Tcl 庫中的一個實用過程。它被用於建立索引檔案，在執行 \fBpackage require\fR 的時候用它來允許自動裝載包。使用 \fBpkg_mkIndex\fR要依從下面這些步驟:         
.IP [1]
建立包。
每個包可以由一個或多個 Tcl   指令碼檔案或二進位制檔案組成。二進位制檔案必須適合使用有一個單一引數的 \fBload\fR 命令裝載；例如，如果檔案是 \fBtest.so\fR  它必須可能用命令 \fBload test.so  \fR命令來裝載這個檔案。每個指令碼檔案必須包含一個 \fBpackage provide\fR  命令來宣告包和版本號，而每個二進位制檔案必須包含一個對 \fBTcl_PkgProvide\fR的呼叫。            
.IP [2]
透過呼叫 \fBpkg_mkIndex \fR建立索引。
用 \fIdir\fR              
引數給出一個目錄的名字並且每個\fIpattern\fR  引數都是在 \fIdir\fR\fI \fR中選擇指令碼或二進位制檔案的一個萬用字元式樣的模式。
.VS 8.0.3
預設的模式是 \fB*.tcl\fR 和 \fB*.[info sharedlibextension]\fR。
.VE
.br
\fBPkg_mkIndex\fR 將在 \fIdir\fR   中建立一個檔案 \fBpkgIndex.tcl\fR，其中有關於用 \fIpattern\fR  引數給出的所有檔案的包資訊。它透過把每個檔案裝載到一個從直譯器中並查看出現了那些包和新命令來完成這項工作(這就是上面描述的在這些檔案中必須有 \fBpackage provide\fR  命令或 \fBTcl_PkgProvide\fR 呼叫的原因)。如果你有一個分開成多個指令碼和二進位制檔案的包，或有檔案間的依賴，你可能必須使用 \fB-load\fR 選項或調整 \fBpkg_mkIndex\fR 處理這些檔案的次序。參見下面的 COMPLEX CASES 複雜情況。        

.IP [3]
把包安裝為由 \fBtcl_pkgPath\fR   變數給出的某個目錄的子目錄。如果 \fB$tcl_pkgPath\fR 包含多於一個的目錄，依賴於機器的包(例如，包含二進位制共享庫的包)通常應該被安裝在第一個目錄下面而不依賴於機器的包(例如，只包含 Tcl  指令碼的包)應該被安裝在第二個目錄下面。子目錄應該包含包的指令碼和/或二進位制檔案還有 \fBpkgIndex.tcl\fR  檔案。包被安裝為在 \fB$tcl_pkgPath\fR   中的一個目錄的一個子目錄之後，在 \fBpackage require\fR  命令期間可自動找到它。
.br
如果你把包安裝在其他地方，則你必須確保包含包的目錄在 \fBauto_path\fR 全域性變數中或在 \fBauto_path\fR  中的一個目錄的最直接(immediate)子目錄中。\fBAuto_path\fR包含由自動裝載器和包裝載器查詢的目錄的一個列表；預設的它包括 \fB$tcl_pkgPath\fR。包裝載器也檢查在 \fBauto_path\fR 中的目錄的所有子目錄。你可以在你的應用中顯式的向 \fBauto_path\fR增加一個目錄，或向你的 \fBTCLLIBPATH\fR  環境變數新增這個目錄:   如果這個環境變數存在，在應用啟動期間Tcl 用它來初始化 \fBauto_path\fR。            
.IP [4]
一旦進行了上述步驟，要使用一個包你需要做的就是呼叫 \fBpackage require\fR。例如，如果包 \fBTest\fR  的版本 2.1、2.3、和 3.1 已經用 \fBpkg_mkIndex \fR建立了索引，\fBpackage require Test\fR 將可獲得版本 3.1 而命令 \fBpackage require -exact Test 2.1\fR將可獲得版本 2.1。在 \fBauto_path\fR 中的不同的索引檔案中可能有一個包的多個版本，實際上只有一個將被裝載到給定的直譯器中，具體決定於首先呼叫了哪個 \fBpackage require\fR。一個包的不同版本可以裝載到不同的直譯器中。

.SH "選項 OPTIONS"
選項開關有:    
.TP 15
\fB\-direct\fR
The generated index will implement direct loading of the package
upon \fBpackage require\fR.  This is the default.
.TP 15
\fB\-lazy\fR
生成的索引將設法延遲裝載包，一直等到使用了由這個包提供命令之一，而不是在 \fBpackage require \fR時立即裝載。
.TP 15
\fB\-load \fIpkgPat\fR
索引處理將預裝載在當前直譯器中現存的所有包和匹配 \fIpkgPat\fR  的包裝載到到用於生成索引的從直譯器中。模式匹配使用與字串匹配相同的規則。參見下面的COMPLEX CASES複雜情況。  
.TP 15
\fB\-verbose\fR
在索引處理期間生成輸出。輸出透過 \fBtclLog\fR    過程，這個過程預設輸出到 stderr。 
.TP 15
\fB\-\-\fR
標誌的終止，用於 \fIdir\fR  以連字號開始的情況。 

.SH "包和自動裝載器 PACKAGES AND THE AUTO-LOADER"
.PP
包管理設施與自動裝載器在一些方面有所重疊，二者都安排檔案在需要時(on-demand)裝載。但是，包管理是一個高層機制，它在裝載過程的最後一步使用自動裝載器。一般的，使用\fBpkg_mkIndex\fR  給一個包加索引而不使用 \fBauto_mkindex\fR ，因為包機制提供了版本控制: 在索引檔案中可獲得一個包的多個版本，急於 \fBpackage require\fR  命令不同的應用可使用不同的版本。相反的，\fBauto_mkindex\fR  不理解版本，所以它只能處理每個包的一個單一版本。對一個給定的包使用   \fBpkg_mkIndex\fR 和 \fBauto_mkindex\fR 兩者來建立索引可能不是個好主意。如果你使用 \fBpkg_mkIndex\fR 來為一個包建立索引，它的命令不能被呼叫，一直等到使用 \fBpackage require\fR 選擇了一個版本；相反的，用 \fBauto_mkindex\fR  建立索引的包由於沒有版本而可以立即使用。           

.SH "它是如何工作的 HOW IT WORKS"
.PP
\fBPkg_mkIndex\fR 依賴於 \fBpackage unknown\fR  命令、\fBpackage ifneeded\fR 命令、和自動裝載器。在第一次呼叫一個 \fBpackage require\fR命令時，呼叫 \fBpackage unknown\fR   指令碼。Tcl   初始化把它設定成求值在\fBauto_path \fR中的所有 \fBpkgIndex.tcl\fR  檔案的一個指令碼。\fBpkgIndex.tcl\fR 檔案包含給每個可獲得的包的 \fBpackage ifneeded\fR 命令；這些命令呼叫 \fBpackage provide\fR 命令來宣佈這個包的可獲得性，並且它們設定自動裝載器的資訊來裝載這些包的檔案。
.VS 8.3
如果在生成\fBpkgIndex.tcl\fR 時提供了 \fI-lazy\fR  標誌，
.VE
在第一次呼叫它的命令之前不實際上裝載一個給定包的給定版本的一個給定檔案。所以在呼叫了 \fBpackage require\fR之後，你可能在這個直譯器中不能看到這個包的命令，但你可以呼叫它的命令而它們將被自動裝載。  

.VS 8.3
.SH "直接裝載 DIRECT LOADING"
.PP
一些包，例如使用了名字空間和匯出命令或要求特殊初始化的包，可以選擇在 \fBpackage require\fR 的時候立即裝載它們的包檔案而不是延遲實際的裝載到第一次使用這個包中的命令的時候。在生成包索引時這是預設的模式。可以指定 \fI-lazy\fR 引數來屏棄(override)它。
.VE

.SH "複雜情況 COMPLEX CASES"
指令碼和二進位制檔案之間存在依賴，和包被分開成指令碼和二進位制檔案的可被正確處理。但是，你可能必須調整\fBpkg_mkIndex\fR  處理這些檔案的次序。下面詳細描述這些要點。
.PP
如果每個指令碼或檔案包含一個包，並且包只包含在一個檔案中，則事情就很容易。你可以簡單的用一些萬用字元模式指定以任意次序為所有檔案建立索引。
.PP
一般的，指令碼依賴於其他包是沒有問題的。如果指令碼包含 \fBpackage require\fR 命令，在用於處理這個指令碼的直譯器中把他們連根拔除(stubbed out)，所以不會導致問題。如果指令碼呼叫了其他包的在全域性程式碼中的過程，這些呼叫由一個存根(stub) \fBunknown\fR    命令處理。但是，如果指令碼引用了其他包的在全域性程式碼中的變數   ，這將導致錯誤。這也是糟糕的編碼風格。
.PP
如果二進位制檔案依賴於其他的包，事情就變的棘手了，因為在裝載一個二進位制檔案時不可能連根拔除C-層次 API 如 \fBTcl_PkgRequire\fR API。例如，假設 BLT 包要求 Tk，並在它的 \fBBlt_Init \fR例程中用對 \fBTcl_PkgRequire\fR 的一個呼叫表達了這種需求。要支援它，你必須在一個已經裝載了Tk 的直譯器中執行 \fBpkg_mkIndex\fR。你用 \fB-load \fR\fIpkgPat\fR選項來完成這個任務。如果你指定了這個選項，\fBpkg_mkIndex\fR將裝載在 \fBinfo loaded\fR 中列出的所有的包和那些匹配 \fIpkgPat\fR 的包到用於處理檔案的直譯器中。在多數情況下這將可以滿足二進位制檔案中的 \fBTcl_PkgRequire\fR 呼叫。
.PP
如果你為兩個二進位制檔案建立索引，其中的一個依賴於另一個，你應該最後指定有依賴的那個包。這樣沒有依賴的那個包將被裝載和建立索引，那麼在處理第二個檔案的時候這個檔案所提供的包就是可獲得的了。你還必須使用 \fB-load\fR 標誌把第一個包裝載到用於建立索引的一個臨時直譯器中；這將無損於指定仍未裝載的包模式。
.PP
如果你有一個分開成一些指令碼和一個二進位制檔案的包，則你必須避免 \fB-load\fR    標誌。問題在於如果你在計算索引之前裝載了一個包，它將遮蔽提供同一個包的其他部分的所有其他檔案。如果你必須使用 \fB-load\fR，則你必須首先指定指令碼；否則從二進位制檔案裝載的包可能會遮蔽用指令碼定義的包。    

.SH "參見 SEE ALSO"
package(n)

.SH "關鍵字 KEYWORDS"
auto-load, index, package, version

.SH "[中文版維護人]"
.B 寒蟬退士
.SH "[中文版最新更新]"
.B 2001/09/01 
.SH "《中國 Linux 論壇 man 手冊頁翻譯計劃》:"
.BI http://cmpp.linuxforum.net
.SH "跋"
.br
本頁面中文版由中文 man 手冊頁計劃提供。
.br
中文 man 手冊頁計劃：\fBhttps://github.com/man-pages-zh/manpages-zh\fR