## Tcl9.0.3/Tk9.0.3 Documentation > Tcl Commands > pkgMkIndex

### Tcl/Tk Applications | Tcl Commands | Tk Commands | [incr Tcl] Package Commands | SQLite3 Package Commands | TDBC Package Commands | tdbc::mysql Package Commands | tdbc::odbc Package Commands | tdbc::postgres Package Commands | tdbc::sqlite3 Package Commands | Thread Package Commands | Tcl C API | Tk C API | [incr Tcl] Package C API | TDBC Package C API

  NAME
    pkg_mkIndex — 梱包を自動組込みする為の索引を作り上げる Build an index for automatic loading of packages
  構文 SYNOPSIS
  説明 DESCRIPTION
  指示項目 OPTIONS
    -direct
    -lazy
    -load pkgPat
    -verbose
    --
  梱包と自動組込み PACKAGES AND THE AUTO-LOADER
  如何に動作するか HOW IT WORKS
  直接組込み DIRECT LOADING
  COMPLEX CASES
  SEE ALSO
  KEYWORDS

### NAME

pkg_mkIndex — 梱包を自動組込みする為の索引を作り上げる Build an index for automatic loading of packages

### 構文 SYNOPSIS

pkg_mkIndex ?options...? dir ?pattern pattern ...?

### 説明 DESCRIPTION

Pkg_mkIndex は､ Tcl 標準外部函数の一部であって､有益な手続函数である｡これは､package require 命令が実行される時､梱包を自動的に組込まれることを許容する索引ファイルを生成する為に使用される｡ pkg_mkIndex を使うには､次の段階を踏む: Pkg_mkIndex is a utility procedure that is part of the standard Tcl library. It is used to create index files that allow packages to be loaded automatically when package require commands are executed. To use pkg_mkIndex, follow these steps:

1. 梱包の作成｡各梱包は､一つ或はそれ以上のTcl 記述譜か二進数ファイルにより構成され得る｡二進数ファイルは､引数一個の load 命令による組込みに適してなければならない; 譬えば､もし､ファイルが test.so であると､命令 load test.so によって､このファイルを組込むことが可能でなければならない｡それぞれの記述譜ファイルは､梱包と版番号を宣言する為の package provide 命令を含んでいなければならず､又､各二進数ファイルは､ Tcl_PkgProvide の呼出しを含んでいなければならない｡ Create the package(s). Each package may consist of one or more Tcl script files or binary files. Binary files must be suitable for loading with the load command with a single argument; for example, if the file is test.so it must be possible to load this file with the command load test.so. Each script file must contain a package provide command to declare the package and version number, and each binary file must contain a call to Tcl_PkgProvide.

2. pkg_mkIndex を起動して索引を作成する｡ dir 引数はディレクトリーの名前を与え､それぞれの pattern 引数は展開形式の( glob-style )模様であって､それが dir の中の､記述譜や二進数ファイルを選択する｡省略時設定の模様は *.tcl と *.[info sharedlibextension] である｡ Create the index by invoking pkg_mkIndex. The dir argument gives the name of a directory and each pattern argument is a glob-style pattern that selects script or binary files in dir. The default pattern is *.tcl and *.[info sharedlibextension].

   pkg_mkIndex は､ pattern 引数によって与えられる全てのファイルに関する梱包の情報によって dir 中にフィル pkgIndex.tcl を作成する｡それは､子供の解釈実行機能の中に各ファイルを組込み､どの梱包と新しい命令が現れるかを調べる(これが､package provide 命令又は Tcl_PkgProvide を上述の様にファイル中で呼出させるのが不可欠の理由である)事を行う｡もし､梱包を記述譜と二進ファイルに分割させるか､ファイル間に依存関係があるなら､ -load 指示項目を使わねばならないか､ファイルを処理している pkg_mkIndex の順番を調整しなければならないかもしれない｡下の COMPLEX CASES を参照されたい｡ Pkg_mkIndex will create a file pkgIndex.tcl in dir with package information about all the files given by the pattern arguments. It does this by loading each file into a child interpreter and seeing what packages and new commands appear (this is why it is essential to have package provide commands or Tcl_PkgProvide calls in the files, as described above). If you have a package split among scripts and binary files, or if you have dependencies among files, you may have to use the -load option or adjust the order in which pkg_mkIndex processes the files. See COMPLEX CASES below.

3. tcl_pkgPath 変数によって与えられたディレクトリーの一つの仔ディレクトリーとして梱包を実装する｡もし､$tcl_pkgPath が複数のディレクトリーを含んでいると､機械-依存の梱包が通常(譬えば二進数の共有外部函数群を含んでいる様な)第１のディレクトリーの下に実装され､次いで､機械-不依存の梱包(譬えば､ Tcl 記述譜のみを含むような)が第二のディレクトリーの下に､実装される｡仔ディレクトリーは梱包の記述譜 及び/又は 二進数のファイルを pkgIndex.tcl ファイルの如く含んでいる｡梱包が $tcl_pkgPath のディレクトリーの仔ディレクトリーとして実装されている限り package require 命令の間に自動的に発見されるようになる｡ Install the package as a subdirectory of one of the directories given by the tcl_pkgPath variable. If $tcl_pkgPath contains more than one directory, machine-dependent packages (e.g., those that contain binary shared libraries) should normally be installed under the first directory and machine-independent packages (e.g., those that contain only Tcl scripts) should be installed under the second directory. The subdirectory should include the package's script and/or binary files as well as the pkgIndex.tcl file. As long as the package is installed as a subdirectory of a directory in $tcl_pkgPath it will automatically be found during package require commands.

   もし､梱包をそれ以外のどこかに実装すると､梱包を含むディレクトリーは auto_path 大域変数又は､ auto_path 中の一つのディレクトリーの直属の仔ディレクトリーに確実にある様にしなければならない｡ auto_path は､auto-loader とpackage loader の両方に捜索されたディレクトリーのリストを含み; 省略時設定では $tcl_pkgPath. を含んでいる｡package loader は auto_path 中のディレクトリーの全ての仔ディレクトリーを検査する｡応用譜の中で､auto_path に明示的にディレクトリーを追加でき､又､TCLLIBPATH 環境変数にディレクトリーを追加できる: もし､この環境変数が存在するならば､Tcl はそれによって､応用譜が実行準備をしている間に､ auto_path を初期化できる｡ If you install the package anywhere else, then you must ensure that the directory containing the package is in the auto_path global variable or an immediate subdirectory of one of the directories in auto_path. Auto_path contains a list of directories that are searched by both the auto-loader and the package loader; by default it includes $tcl_pkgPath. The package loader also checks all of the subdirectories of the directories in auto_path. You can add a directory to auto_path explicitly in your application, or you can add the directory to your TCLLIBPATH environment variable: if this environment variable is present, Tcl initializes auto_path from it during application startup.

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 の初めての呼出しに基いて､ただ一つだけが､与えられた解釈実行機能内に実際に組込まれる｡異なる解釈実行機能内には異なる版の梱包が組込まれても好い｡ Once the above steps have been taken, all you need to do to use a package is to invoke package require. For example, if versions 2.1, 2.3, and 3.1 of package Test have been indexed by pkg_mkIndex, the command package require Test will make version 3.1 available and the command package require -exact Test 2.1 will make version 2.1 available. There may be many versions of a package in the various index files in auto_path, but only one will actually be loaded in a given interpreter, based on the first call to package require. Different versions of a package may be loaded in different interpreters.

### 指示項目 OPTIONS

使用できる指示項目は: The optional switches are:

-direct
  生成された索引が package require 上の梱包の直接組込みを実現することになる｡この設定が省略時設定である｡ vThe generated index will implement direct loading of the package upon package require. This is the default.

-lazy
  生成された索引は､package require 上に直接組込む代わりに､梱包に供給された命令の一つが使用される迄､組込みを遅らせるよう制御される｡これは auto_reset とは両立しない､従って使用は思い留まるべき｡ The generated index will manage to delay loading the package until the use of one of the commands provided by the package, instead of loading it immediately upon package require. This is not compatible with the use of auto_reset, and therefore its use is discouraged.

-load pkgPat
  指定先を定める手順課程は､現在の解釈実行機能に実在し､且つ､ pkgPat に合致するどの梱包でも､索引の生成に使用される子供の解釈実行機能に予備-組込みする｡模様の合致は string match の規則を使用するが､大文字小文字の区別はしない｡下の COMPLEX CASES を参照のこと｡ The index process will preload any packages that exist in the current interpreter and match pkgPat into the child interpreter used to generate the index. The pattern match uses string match rules, but without making case distinctions. See COMPLEX CASES below.

-verbose
  指定先を定める課程を出力に生成する｡出力は､省略時設定での標準不具合印刷出力と同じく tclLog 手続函数を経由する｡ Generate output during the indexing process. Output is via the tclLog procedure, which by default prints to stderr.

--
  dir がダッシュ記号(-)で始まる場合の､旗印の終り｡ End of the flags, in case dir begins with a dash.

### 梱包と自動組込み PACKAGES AND THE AUTO-LOADER

梱包管理機能は幾らか自動-組込みと重複していて､両方とも､要求があり次第組込むべきファイルを手配する｡しかし､梱包管理は高水準の仕組みで､最後の組込み処理の段階で自動-組込を使用している｡一般には､auto_mkindex よりも pkg_mkIndex により梱包を索引する方が好ましい､理由は梱包管理機能の仕組みは版番号管理を提供しているから: package require 命令に基いて､異なる版を使う異なる応用譜により索引ファイル中ある､梱包の幾つもの版が利用できるようになる｡それに対して､auto_mkindex は､版番号を理解できず､為に､各梱包ごとに１つの版しか処理できない｡ pkg_mkIndex と auto_mkindex の両方を使って､与えられた梱包に索引をつけるのは､多分余りよい着想ではない｡梱包の索引付けに pkg_mkIndex を使うと､その命令は､版を選択する為に package require が使われるまで､起動されなくなる; それに対し auto_mkindex を使った梱包の索引付けは､版制御がないのですぐさま使用できる｡ The package management facilities overlap somewhat with the auto-loader, in that both arrange for files to be loaded on-demand. However, package management is a higher-level mechanism that uses the auto-loader for the last step in the loading process. It is generally better to index a package with pkg_mkIndex rather than auto_mkindex because the package mechanism provides version control: several versions of a package can be made available in the index files, with different applications using different versions based on package require commands. In contrast, auto_mkindex does not understand versions so it can only handle a single version of each package. It is probably not a good idea to index a given package with both pkg_mkIndex and auto_mkindex. If you use pkg_mkIndex to index a package, its commands cannot be invoked until package require has been used to select a version; in contrast, packages indexed with auto_mkindex can be used immediately since there is no version control.

### 如何に動作するか HOW IT WORKS

pkg_mkIndex 命令は package unknown 命令と､package ifneeded 命令と､自動-組込み譜に依存する｡初めて package require が起動される時､package unknown 記述譜が起動される｡これは Tcl の初期化により､auto_path の中の pkgIndex.tcl ファイルの全てを評価する記述譜､に設定される｡この pkgIndex.tcl ファイルは､それぞれの利用できる梱包のそれぞれの版についてpackage ifneeded 命令を含んでいる; これらの命令は梱包の利用可能性を告げるために､ package provide 命令を起動し､梱包のファイルを組込むための自動-組込み用情報を組上げる｡もし､ -lazy 旗標が与えられると､pkgIndex.tcl が生成された時に､与えられた梱包の与えられた版の与えられたファイルは､その命令の一つが起動される迄､実際は組込まれない｡そこで､ package require の起動の後､解釈実行機能の中に梱包の命令は見当たらないかもしれないが､その命令は起動できるし､自動-組込みするようになる｡ Pkg_mkIndex depends on the package unknown command, the package ifneeded command, and the auto-loader. The first time a package require command is invoked, the package unknown script is invoked. This is set by Tcl initialization to a script that evaluates all of the pkgIndex.tcl files in the auto_path. The pkgIndex.tcl files contain package ifneeded commands for each version of each available package; these commands invoke package provide commands to announce the availability of the package, and they setup auto-loader information to load the files of the package. If the -lazy flag was provided when the pkgIndex.tcl was generated, a given file of a given version of a given package is not actually loaded until the first time one of its commands is invoked. Thus, after invoking package require you may not see the package's commands in the interpreter, but you will be able to invoke the commands and they will be auto-loaded.

### 直接組込み DIRECT LOADING

ある梱包､譬えば名前空間と export 命令を使う梱包や､特別な初期化が要求されるような梱包は､梱包の命令のどれか一つの最初の使用の為の､実際の組込みを遅らせる代わりに､package require によりすぐさま組込まれるべきその梱包ファイルを選定するかもしれない｡これは､その梱包索引を生成する時の省略時設定である｡ -lazy 引数を指定することで上書き可能である｡ Some packages, for instance packages which use namespaces and export commands or those which require special initialization, might select that their package files be loaded immediately upon package require instead of delaying the actual loading to the first use of one of the package's command. This is the default mode when generating the package index. It can be overridden by specifying the -lazy argument.

### COMPLEX CASES

多くの､記述譜と二進数ファイルの間の依存関係が複雑であるが､梱包が記述譜と二進数ファイルに分割されている場合は､良好に処理される｡しかし､ pkg_mkIndex によってどのファイルを処理するかの順番を調整する必要があるかもしれない｡この問題は下に詳細が記述されている｡ Most complex cases of dependencies among scripts and binary files, and packages being split among scripts and binary files are handled OK. However, you may have to adjust the order in which files are processed by pkg_mkIndex. These issues are described in detail below.

もし､それぞれの記述譜やファイルが一つの梱包を含んでいて､梱包はその中に１つだけファイルを含んでいると､ことは簡単である｡全てのファイルをどのような順序でも､何かの展開模様を付けて索引付けを指定すればよい｡ If each script or file contains one package, and packages are only contained in one file, then things are easy. You simply specify all files to be indexed in any order with some glob patterns.

一般に､記述譜が他の梱包に依存関係を有してもよい｡もし､記述譜が package require 命令を含んでいると､それらは､その記述譜を処理する為に使われた解釈実行機能内で揉消され､問題を起さなくなる｡もし､記述譜が大域命令譜の中の他の梱包の中に呼ばれたら､これらの呼出しは名目的な unknown 命令によって扱われる｡しかし､もし記述譜が､他の梱包の大域命令譜の変数への種々の参照を作ると､それは不具合を引起すことになる｡これも悪い作譜の流儀である｡ In general, it is OK for scripts to have dependencies on other packages. If scripts contain package require commands, these are stubbed out in the interpreter used to process the scripts, so these do not cause problems. If scripts call into other packages in global code, these calls are handled by a stub unknown command. However, if scripts make variable references to other package's variables in global code, these will cause errors. That is also bad coding style.

もし二進数ファイルが他の梱包に依存関係を有していると､ことは扱い難い､理由は､二進数ファイルを組込む時､ Tcl_PkgRequire API の様な C-level APIs は揉消すことができないから｡譬えば､ BLT 梱包が Tk を要求し､それを､その初期化の Blt_Init 譜の中で､ Tcl_PkgRequire の呼出しによって表現すると仮定する｡ これを実現する為には､Tk を組込んだ解釈実行機能の中で pkg_mkIndex を走らせる必要がある｡これは､ -load pkgPat 指示項目を使用すると遂行可能である｡この指示項目を指定すると､pkg_mkIndex は､ info loaded に列挙され且つ､ pkgPat に合致する如何なるファイルも､ファイルを処理する為に使用する解釈実行機能内に組込むようになる｡殆どの場合､これは､二進数ファイルによってなされた Tcl_PkgRequire 呼出しを満足する｡ If binary files have dependencies on other packages, things can become tricky because it is not possible to stub out C-level APIs such as Tcl_PkgRequire API when loading a binary file. For example, suppose the BLT package requires Tk, and expresses this with a call to Tcl_PkgRequire in its Blt_Init routine. To support this, you must run pkg_mkIndex in an interpreter that has Tk loaded. You can achieve this with the -load pkgPat option. If you specify this option, pkg_mkIndex will load any packages listed by info loaded and that match pkgPat into the interpreter used to process files. In most cases this will satisfy the Tcl_PkgRequire calls made by binary files.

もし二つの二進数ファイルを索引付けし､片方が他方に依存しているなら､最終的な依存関係を指定した方がよい｡この方法では､依存関係のないファイルが組込まれ､索引付けされ､次に､第２のファイルが処理される時に､それが与える梱包が利用可能になる｡また､第１の梱包を､ -load 旗標を使って索引を作成するために使用した臨時の解釈実行機能の中に組込む必要があるかもしれない; それは､未だ組込んでいない梱包の模様を指定することを妨げない｡ If you are indexing two binary files and one depends on the other, you should specify the one that has dependencies last. This way the one without dependencies will get loaded and indexed, and then the package it provides will be available when the second file is processed. You may also need to load the first package into the temporary interpreter used to create the index by using the -load flag; it will not hurt to specify package patterns that are not yet loaded.

もし､記述譜と二進数ファイルを横断して分割した梱包があるなら､ -load 旗標は避けたほうがよい｡問題は､索引を計算する前に梱包を組込むと､それが同じ梱包の部分を提供する如何なる他のファイルも隠すことである｡もし､ -load の使用が必須の場合は､記述譜を初めに指定しなければならない; さもなくば､二進数ファイルから組込んだ梱包が､記述譜によって定義された梱包を隠すかもしれない｡ If you have a package that is split across scripts and a binary file, then you should avoid the -load flag. The problem is that if you load a package before computing the index it masks any other files that provide part of the same package. If you must use -load, then you must specify the scripts first; otherwise the package loaded from the binary file may mask the package defined by the scripts.

### SEE ALSO

package

### KEYWORDS

auto-load, index, package, version
Copyright © 1996 Sun Microsystems, Inc.