Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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 li-
       brary.  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  con-
	      tain  a  package provide command to declare the package and ver-
	      sion 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  dependen-
	      cies 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  normally  be  in-
	      stalled  under the first directory and machine-independent pack-
	      ages (e.g., those	that contain only Tcl scripts) should  be  in-
	      stalled under the	second directory.  The subdirectory should in-
	      clude 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  automati-
	      cally 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	subdirectory of	one of the di-
	      rectories	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 TCLLIB-
	      PATH 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 ver-
	      sions 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	      The generated index will implement direct	loading	of the
		      package upon package 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  immediately  upon
		      package require.	This is	not compatible with the	use of
		      auto_reset, and therefore	its use	is discouraged.

       -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  pat-
		      tern  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	procedure,  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.  How-
       ever, 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 be-
       cause 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 com-
       mands.  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  ver-
       sion;   in contrast, packages indexed with auto_mkindex can be used im-
       mediately 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 re-
       quire 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	avail-
       ability	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
       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 in-
       stead 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 con-
       tained 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 pack-
       ages.  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.

       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 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.

       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  pro-
       vide  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)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | PACKAGES AND THE AUTO-LOADER | HOW IT WORKS | DIRECT LOADING | COMPLEX CASES | SEE ALSO | KEYWORDS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=pkg_mkIndex.tcl85&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help