Unix/Linux Go Back    


OpenDarwin 7.2.1 - man page for pkg_mkindex (opendarwin section n)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


pkg_mkIndex(n)			      Tcl Built-In Commands			   pkg_mkIndex(n)

_________________________________________________________________________________________________

NAME
       pkg_mkIndex - Build an index for automatic loading of packages

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

DESCRIPTION
       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]    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]    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 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 slave 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]    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 nor-
	      mally 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.
	      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  subdi-
	      rectory  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 subdi-
	      rectories 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]    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 ver-
	      sion 3.1 available and the command package require -exact Test 2.1 will  make  ver-
	      sion  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	      The generated index will implement direct loading of the package upon pack-
		      age require.  This is the default.

       -lazy	      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 imme-
		      diately upon package require.

       -load pkgPat   The  index  process  will  pre-load  any packages that exist in the current
		      interpreter and match pkgPat into the slave interpreter  used  to  generate
		      the  index.   The pattern match uses string match rules, but without making
		      case distinctions.  See COMPLEX CASES below.

       -verbose       Generate output during the indexing process.  Output is via the tclLog pro-
		      cedure, which by default prints to stderr.

       --	      End of the flags, in case dir begins with a dash.

PACKAGES AND THE AUTO-LOADER
       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 gen-
       erally 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 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  pro-
       vide  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 isn't actu-
       ally 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											  |
       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
       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.

       In  general, it is OK for scripts to have dependencies on other packages.  If scripts con-
       tain 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.

       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.

       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 pro-
       cessed.	You may also need to load the first package into the temporary	interpreter  used
       to  create  the	index  by using the -load flag; it won't hurt to specify package patterns
       that are not yet loaded.

       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(n)

KEYWORDS
       auto-load, index, package, version

Tcl					       8.3				   pkg_mkIndex(n)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 09:49 PM.