pkg_mkIndex man page on BSDOS

Man page or keyword search:  
man Server   6284 pages
apropos Keyword Search (all sections)
Output format
BSDOS logo
[printable version]



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

_________________________________________________________________

NAME
       pkg_mkIndex  -  Build  an  index	 for automatic loading of
       packages

SYNOPSIS
       pkg_mkIndex dir pattern ?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  pack-
       age  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.  Pkg_mkIndex
	      will create a file pkgIndex.tcl in dir with package
	      information about all the files given by	the  pat-
	      tern  arguments.	It does this by loading each file
	      and seeing what packages and  new	 commands  appear
	      (this  is	 why it is essential to have package pro-
	      vide commands or Tcl_PkgProvide calls in the files,
	      as described above).

       [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 con- |
	      tain 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 |

Tcl			       7.6				1

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

	      package require commands.				  |

	      If  you install the package anywhere else, then you |
	      must ensure that the directory contaiingn the pack- |
	      age is in the auto_path global variable or an imme- |
	      diate subdirectory of one	 of  the  directories  in |
	      auto_path.   Auto_path  contains a list of directo- |
	      ries 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 ini-
	      tializes	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 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.  Dif-
	      ferent versions of a package may be loaded in  dif-
	      ferent interpreters.

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 generally better
       to  index  a  package   with   pkg_mkIndex   rather   than
       auto_mkindex  because  the package mechanism provides ver-
       sion control:  several versions of a package can	 be  made
       available  in the index files, with different applications
       using different versions based  on  package  require  com-
       mands.  In contrast, auto_mkindex does not understand ver-
       sions so it can only handle a single version of each pack-
       age.   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.

Tcl			       7.6				2

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

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 initializa-
       tion  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 avail-
       able package;  these commands invoke package provide  com-
       mands  to  announce  the	 availability of the package, and
       they setup auto-loader information to load  the	files  of
       the  package.   A given file of a given version of a given
       package isn't actually loaded until the first time one  of
       its  commands  is  invoked.   Thus, after invoking package
       require you won't see the package's commands in the inter-
       preter,	but  you  will be able to invoke the commands and
       they will be auto-loaded.

KEYWORDS
       auto-load, index, package, version

Tcl			       7.6				3

[top]
                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server BSDOS

List of man pages available for BSDOS

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net